Purpose

Use this skill when working with Biome's type inference system and module graph. Covers type references, resolution phases, and the architecture designed for IDE performance.

Prerequisites

Read

crates/biome_js_type_info/CONTRIBUTING.md

for architecture details

Understand Biome's focus on IDE support and instant updates

Familiarity with TypeScript type system concepts

Key Concepts

Module Graph Constraint

Critical rule

No module may copy or clone data from another module, not even behind

Arc

.

Why

Any module can be updated at any time (IDE file changes). Copying data would create stale references that are hard to invalidate.

Solution

Use

TypeReference

instead of direct type references.

Type Data Structure

Types are stored in

TypeData

enum with many variants:

// Simplified — see crates/biome_js_type_info/src/type_data.rs for the full enum

enum

TypeData

{

Unknown

,

// Inference not implemented

Global

,

// Global type reference

BigInt

,

Boolean

,

Null

,

Number

,

// Primitive types

String

,

Symbol

,

Undefined

,

Function

(

Box

<

Function

>

)

,

// Function with parameters

Object

(

Box

<

Object

>

)

,

// Object with properties

Class

(

Box

<

Class

>

)

,

// Class definition

Interface

(

Box

<

Interface

>

)

,

// Interface definition

Union

(

Box

<

Union

>

)

,

// Union type (A | B)

Intersection

(

Box

<

Intersection

>

)

,

// Intersection type (A & B)

Tuple

(

Box

<

Tuple

>

)

,

// Tuple type

Literal

(

Box

<

Literal

>

)

,

// Literal type ("foo", 42)

Reference

(

TypeReference

)

,

// Reference to another type

TypeofExpression

(

Box

<

TypeofExpression

>

)

,

// typeof an expression

// ... plus Conditional, Generic, TypeOperator, InstanceOf,

// keyword variants (AnyKeyword, NeverKeyword, VoidKeyword, etc.)

}

Type References

Instead of direct type references, use

TypeReference

:

enum

TypeReference

{

Qualifier

(

Box

<

TypeReferenceQualifier

>

)

,

// Name-based reference

Resolved

(

ResolvedTypeId

)

,

// Resolved to type ID

Import

(

Box

<

TypeImportQualifier

>

)

,

// Import reference

}

Note:

There is no

Unknown

variant. Unknown types are represented as

TypeReference::Resolved(GLOBAL_UNKNOWN_ID)

. Use

TypeReference::unknown()

to create one.

Type Resolution Phases

1. Local Inference

What

Derives types from expressions without surrounding context.

Example

For

a + b

, creates:

TypeData

::

TypeofExpression

(

TypeofExpression

::

Addition

{

left

:

TypeReference

::

from

(

TypeReferenceQualifier

::

from_name

(

"a"

)

)

,

right

:

TypeReference

::

from

(

TypeReferenceQualifier

::

from_name

(

"b"

)

)

}

)

Where

Implemented in

local_inference.rs

Output

Types with unresolved

TypeReference::Qualifier

references

2. Module-Level ("Thin") Inference

What

Resolves references within a single module's scope.

Process

:

Takes results from local inference

Looks up qualifiers in local scopes

Converts to

TypeReference::Resolved

if found locally

Converts to

TypeReference::Import

if from import statement

Falls back to globals (like

Array

,

Promise

)

Uses

TypeReference::Unknown

if nothing found

Where

Implemented in

js_module_info/collector.rs

Output

Types with resolved local references, import markers, or unknown

3. Full Inference

What

Resolves import references across module boundaries.

Process

:

Has access to entire module graph

Resolves

TypeReference::Import

by following imports

Converts to

TypeReference::Resolved

after following imports

Where

Implemented in

js_module_info/module_resolver.rs

Limitation

Results cannot be cached (would become stale on file changes)

Working with Type Resolvers

Available Resolvers

// 1. For tests

HardcodedSymbolResolver

// 2. For globals (Array, Promise, etc.)

GlobalsResolver

// 3. For thin inference (single module)

JsModuleInfoCollector

// 4. For full inference (across modules)

ModuleResolver

Using a Resolver

use

biome_js_type_info

::

{

TypeResolver

,

ResolvedTypeData

}

;

fn

analyze_type

(

resolver

:

&

impl

TypeResolver

,

type_ref

:

TypeReference

)

{

// Resolve the reference

let

resolved_data

:

ResolvedTypeData

=

resolver

.

resolve_type

(

type_ref

)

;

// Get raw data for pattern matching

match

resolved_data

.

as_raw_data

(

)

{

TypeData

::

String

=>

{

/ handle string /

}

,

TypeData

::

Number

=>

{

/ handle number /

}

,

TypeData

::

Function

(

func

)

=>

{

/ handle function /

}

,

_

=>

{

/ handle others /

}

}

// Resolve nested references

if

let

TypeData

::

Reference

(

inner_ref

)

=

resolved_data

.

as_raw_data

(

)

{

let

inner_data

=

resolver

.

resolve_type

(

*

inner_ref

)

;

// Process inner type

}

}

Type Flattening

What

Converts complex type expressions to concrete types.

Example

After resolving

a + b

:

If both are

TypeData::Number

→ Flatten to

TypeData::Number

Otherwise → Usually flatten to

TypeData::String

Where

Implemented in

flattening.rs

Common Workflows

Implement Type-Aware Lint Rule

use

biome_analyze

::

Semantic

;

use

biome_js_type_info

::

{

TypeResolver

,

TypeData

}

;

impl

Rule

for

MyTypeRule

{

type

Query

=

Semantic

<

JsCallExpression

>

;

fn

run

(

ctx

:

&

RuleContext

<

Self

>

)

->

Self

::

Signals

{

let

node

=

ctx

.

query

(

)

;

let

model

=

ctx

.

model

(

)

;

// Get type resolver from model

let

resolver

=

model

.

type_resolver

(

)

;

// Get type of expression

let

expr_type

=

node

.

callee

(

)

.

ok

(

)

?

.

infer_type

(

resolver

)

;

// Check the type

match

expr_type

.

as_raw_data

(

)

{

TypeData

::

Function

(

_

)

=>

{

/ valid /

}

,

TypeData

::

Unknown

=>

{

/ might be valid, can't tell /

}

,

_

=>

{

return

Some

(

(

)

)

;

/ not callable /

}

}

None

}

}

Navigate Type References

fn

is_string_type

(

resolver

:

&

impl

TypeResolver

,

type_ref

:

TypeReference

)

->

bool

{

let

resolved

=

resolver

.

resolve_type

(

type_ref

)

;

// Follow references

let

data

=

match

resolved

.

as_raw_data

(

)

{

TypeData

::

Reference

(

ref_to

)

=>

resolver

.

resolve_type

(

*

ref_to

)

,

_other

=>

resolved

,

}

;

// Check the resolved type

matches!

(

data

.

as_raw_data

(

)

,

TypeData

::

String

)

}

Work with Function Types

fn

analyze_function

(

resolver

:

&

impl

TypeResolver

,

type_ref

:

TypeReference

)

{

let

resolved

=

resolver

.

resolve_type

(

type_ref

)

;

if

let

TypeData

::

Function

(

func_type

)

=

resolved

.

as_raw_data

(

)

{

// Access parameters

for

param

in

func_type

.

parameters

(

)

{

let

param_type

=

resolver

.

resolve_type

(

param

.

type_ref

(

)

)

;

// Analyze parameter type

}

// Access return type

let

return_type

=

resolver

.

resolve_type

(

func_type

.

return_type

(

)

)

;

}

}

Architecture Principles

Why Type References?

Advantages

:

No stale data

Module updates don't leave old types in memory

Better performance

Types stored in vectors (data locality)

Easier debugging

Can inspect all types in vector

Simpler algorithms

Process vectors instead of traversing graphs

Trade-off

Must explicitly resolve references (not automatic like

Arc

)

ResolvedTypeId Structure

struct

ResolvedTypeId

(

ResolverId

,

TypeId

)

TypeId

(u32): Index into a type vector

ResolverId

(u32): Identifies which vector to use

Total: 64 bits (compact representation)

ResolvedTypeData

Always work with

ResolvedTypeData

from resolver, not raw

&TypeData

:

// Good - tracks resolver context

let

resolved_data

:

ResolvedTypeData

=

resolver

.

resolve_type

(

type_ref

)

;

// Be careful - loses resolver context

let

raw_data

:

&

TypeData

=

resolved_data

.

as_raw_data

(

)

;

// Can't resolve nested TypeReferences without ResolverId!

Tips

Unknown types

:

TypeData::Unknown

means inference not implemented, treat as "could be anything"

Follow references

Always follow

TypeData::Reference

to get actual type

Resolver context

Keep

ResolvedTypeData

when possible, don't extract raw

TypeData

early

Performance

Type vectors are fast - iterate directly instead of recursive traversal

IDE focus

All design decisions prioritize instant IDE updates over CLI performance

No caching

Full inference results can't be cached (would become stale)

Globals

Currently hardcoded, eventually should use TypeScript's .d.ts files Common Patterns // Pattern 1: Resolve and flatten let type_ref = expr . infer_type ( resolver ) ; let flattened = type_ref . flatten ( resolver ) ; // Pattern 2: Check if type matches fn is_string_type ( resolver : & impl TypeResolver , type_ref : TypeReference ) -> bool { let resolved = resolver . resolve_type ( type_ref ) ; matches! ( resolved . as_raw_data ( ) , TypeData :: String ) } // Pattern 3: Handle unknown gracefully match resolved . as_raw_data ( ) { TypeData :: Unknown | TypeData :: UnknownKeyword => { // Can't verify, assume valid return None ; } TypeData :: String => { / handle / } _ => { / handle / } } References Architecture guide: crates/biome_js_type_info/CONTRIBUTING.md Module graph: crates/biome_module_graph/ Type resolver trait: crates/biome_js_type_info/src/resolver.rs Flattening: crates/biome_js_type_info/src/flattening.rs