weft
ir 2.6.0 · warp 1.8.0
generatedwalked out of the package's public entry

@weftjs/compiler

TSX to sealed templates, on Oxc, with effect inference and type-driven escape elision. Also the virtual file set the playground on this site compiles through.

27exports
27with a doc comment on the declaration

Read out of packages/compiler/src/index.ts, the package’s public entry, so this page is the surface itself rather than a description of it.

cannotBeMarkup function

export function cannotBeMarkup(kind: ValueKind): boolean { … }

Values of these kinds cannot contain markup, so escaping them is a no-op.

Specified inspec/compiler/supported-subset.md

packages/compiler/src/kinds.ts

compileFile function

export async function compileFile(path: string, options?: CompileOptions): Promise<CompiledModule> { … }

One module from a path, or from the supplied reader when the file set is virtual.

Raised in this fileE_COMPONENT_CYCLE·E_FRAGMENT_ARGUMENT·E_NESTED_HOLE_MISSING·E_NO_SOURCE·E_PARSE·E_PRIVATE_COMPONENT_NESTED

Specified inspec/compiler/supported-subset.md

packages/compiler/src/compile.ts

compileFiles function

export async function compileFiles(
  files: string[],
  options?: Omit<CompileOptions, 'types' | 'external' | 'composedElsewhere' | 'read' | 'cssScope'> & {
    types?: boolean
    /** The scope attribute for a file, when a scoped stylesheet sits beside it. A function so the caller keys it by whatever it has. */
    cssScopes?: (file: string) => string | undefined
    /**
     * A file set that exists only in memory, keyed by the same paths passed in `files`. Also turns
     * off the type checker, which needs a real directory — a virtually compiled fragment escapes
     * every value rather than eliding by type, stated by `virtual: true` on the result.
     */
    sources?: ReadonlyMap<string, string>
  },
): Promise<{ modules: CompiledModule[]; diagnostics: string[]; virtual: boolean }> { … }

Compiles with type information over the whole file set at once — the only entry point that can compose across modules, since composition needs an order and an order needs the file set.

Raised in this fileE_COMPONENT_CYCLE·E_FRAGMENT_ARGUMENT·E_NESTED_HOLE_MISSING·E_NO_SOURCE·E_PARSE·E_PRIVATE_COMPONENT_NESTED

Specified inspec/compiler/supported-subset.md

packages/compiler/src/compile.ts

compileSource function

export async function compileSource(
  source: string,
  file: string,
  options?: CompileOptions,
): Promise<CompiledModule> { … }

One module from its text. The entry point a test uses; a build uses compileFiles.

Raised in this fileE_COMPONENT_CYCLE·E_FRAGMENT_ARGUMENT·E_NESTED_HOLE_MISSING·E_NO_SOURCE·E_PARSE·E_PRIVATE_COMPONENT_NESTED

packages/compiler/src/compile.ts

intentId function

export function intentId(module: string, exportName: string): string { … }

Opaque, derived from the module and export it came from. See spec/kernel/intents.md.

Specified inspec/kernel/authority.md·spec/kernel/intents.md

packages/compiler/src/intents.ts

loaderReads function

export function loaderReads(file: string, source: string): string[] { … }

The reads a route's declaration file performs, for the keys of the slots it declares. Must never return an empty set on a parse failure — that would read as "this loader reads nothing" and put the wrong key back — so it throws and the caller decides.

Raised in this fileE_COMPONENT_CYCLE·E_FRAGMENT_ARGUMENT·E_NESTED_HOLE_MISSING·E_NO_SOURCE·E_PARSE·E_PRIVATE_COMPONENT_NESTED

packages/compiler/src/compile.ts

locate function

export function locate(file: string, source: string, offset = 0): Loc { … }

A byte offset as a line and column.

packages/compiler/src/errors.ts

lower function

export function lower(input: LowerInput): Lowered { … }

JSX to segments and holes. Every expression it cannot lower is refused by name.

Raised in this fileE_ATTRIBUTE_UNSUPPORTED·E_BRANCH_MIXES_SHAPE_AND_VALUE·E_BRANCH_NOT_SOLE_CHILD·E_BRANCH_ON_SIGNAL·E_CHILDREN_AS_PROP·E_CHILDREN_NOT_A_VALUE·E_CHILDREN_NOT_SOLE_CHILD·E_COMPONENT_CHILDREN_UNDECLARED·E_COMPONENT_NOT_SINGLE_ROOT·E_COMPONENT_PROP_MISSING·E_COMPONENT_PROP_UNKNOWN·E_COMPONENT_UNRESOLVED·E_COMPUTED_MEMBER·E_CTX_IN_MARKUP·E_EXPRESSION_UNSUPPORTED·E_HANDLER_NOT_AN_INTENT·E_HANDLER_NOT_IMPORTED·E_LIST_NOT_SOLE_CHILD·E_MAP_PARAM·E_NESTED_FRAGMENT·E_NO_RETURN·E_OPERATOR_UNSUPPORTED·E_OUT_OF_ROW_SCOPE·E_RAW_EMPTY·E_ROOT_NOT_JSX·E_ROW_NOT_SINGLE_ROOT·E_SIGNAL_IN_LIST·E_SIGNAL_NOT_READ·E_SPREAD_UNSUPPORTED·E_UNKNOWN_BINDING·E_VOID_CHILDREN

packages/compiler/src/lower.ts

returnedJsx function

export function returnedJsx(block: Node, input: LowerInput): Node { … }

The JSX a fragment body returns, past the statements that set up its signals.

Raised in this fileE_ATTRIBUTE_UNSUPPORTED·E_BRANCH_MIXES_SHAPE_AND_VALUE·E_BRANCH_NOT_SOLE_CHILD·E_BRANCH_ON_SIGNAL·E_CHILDREN_AS_PROP·E_CHILDREN_NOT_A_VALUE·E_CHILDREN_NOT_SOLE_CHILD·E_COMPONENT_CHILDREN_UNDECLARED·E_COMPONENT_NOT_SINGLE_ROOT·E_COMPONENT_PROP_MISSING·E_COMPONENT_PROP_UNKNOWN·E_COMPONENT_UNRESOLVED·E_COMPUTED_MEMBER·E_CTX_IN_MARKUP·E_EXPRESSION_UNSUPPORTED·E_HANDLER_NOT_AN_INTENT·E_HANDLER_NOT_IMPORTED·E_LIST_NOT_SOLE_CHILD·E_MAP_PARAM·E_NESTED_FRAGMENT·E_NO_RETURN·E_OPERATOR_UNSUPPORTED·E_OUT_OF_ROW_SCOPE·E_RAW_EMPTY·E_ROOT_NOT_JSX·E_ROW_NOT_SINGLE_ROOT·E_SIGNAL_IN_LIST·E_SIGNAL_NOT_READ·E_SPREAD_UNSUPPORTED·E_UNKNOWN_BINDING·E_VOID_CHILDREN

packages/compiler/src/lower.ts

stripComments function

export function stripComments(file: string, source: string): StripCommentsResult { … }

A module with its prose removed, and the number of bytes that was. See spec/kernel/static.md.

Specified inspec/kernel/static.md

packages/compiler/src/comments.ts

CompileError class

export class CompileError extends Error {
  code: string
  loc: Loc

  constructor(code: string, message: string, loc: Loc) {
    super(`${code} at ${loc.file}:${loc.line}:${loc.column} — ${message}`)
    this.name = 'CompileError'
    this.code = code
    this.loc = loc
  }
}

A compile error names a location and a code, so a miscompile is never silent.

Specified inspec/compiler/supported-subset.md

packages/compiler/src/errors.ts

CompiledFragment interface

export interface CompiledFragment {
  /** The root template, plus every nested row template it needs, sealed. */
  entry: TemplateIR
  templates: TemplateIR[]
  exportName: string
}

One compiled fragment: its sealed entry, the templates inside it, and which export it was.

Raised in this fileE_COMPONENT_CYCLE·E_FRAGMENT_ARGUMENT·E_NESTED_HOLE_MISSING·E_NO_SOURCE·E_PARSE·E_PRIVATE_COMPONENT_NESTED

packages/compiler/src/compile.ts

CompiledModule interface

export interface CompiledModule {
  file: string
  fragments: CompiledFragment[]
}

One module's fragments. A module may export several; a page is one of them.

Raised in this fileE_COMPONENT_CYCLE·E_FRAGMENT_ARGUMENT·E_NESTED_HOLE_MISSING·E_NO_SOURCE·E_PARSE·E_PRIVATE_COMPONENT_NESTED

packages/compiler/src/compile.ts

CompileOptions interface

export interface CompileOptions {
  /** Template ids are stated relative to this directory, so a version does not depend on checkout location. */
  root?: string
  /** Type information for escape elision. Without it the compiler escapes by default. */
  types?: TypeOracle
  /** Fragments this module imports and renders, already compiled. Supplied by the build. */
  external?: (module: string, exported: string) => ExternalFragment | undefined
  /** Export names in this module that some other module renders, so a composed fragment wires its props. */
  composedElsewhere?: ReadonlySet<string>
  /** Where this file's text comes from. Defaults to reading the path. */
  read?: SourceReader
  /** The scope attribute to stamp on every element this module's fragments declare. Absent means unscoped. */
  cssScope?: string
}

What one module's compilation needs beyond its source: a root, types, and its dependencies.

Raised in this fileE_COMPONENT_CYCLE·E_FRAGMENT_ARGUMENT·E_NESTED_HOLE_MISSING·E_NO_SOURCE·E_PARSE·E_PRIVATE_COMPONENT_NESTED

packages/compiler/src/compile.ts

ComponentRef interface

export interface ComponentRef {
  id: string
  props: Set<string>
  lower?(): Lowered
  /** Set when the fragment was compiled by another module and is already sealed. */
  sealed?: SealedFragment
}

A fragment another fragment can render. props is checked against a use site rather than discovered at render.

Raised in this fileE_ATTRIBUTE_UNSUPPORTED·E_BRANCH_MIXES_SHAPE_AND_VALUE·E_BRANCH_NOT_SOLE_CHILD·E_BRANCH_ON_SIGNAL·E_CHILDREN_AS_PROP·E_CHILDREN_NOT_A_VALUE·E_CHILDREN_NOT_SOLE_CHILD·E_COMPONENT_CHILDREN_UNDECLARED·E_COMPONENT_NOT_SINGLE_ROOT·E_COMPONENT_PROP_MISSING·E_COMPONENT_PROP_UNKNOWN·E_COMPONENT_UNRESOLVED·E_COMPUTED_MEMBER·E_CTX_IN_MARKUP·E_EXPRESSION_UNSUPPORTED·E_HANDLER_NOT_AN_INTENT·E_HANDLER_NOT_IMPORTED·E_LIST_NOT_SOLE_CHILD·E_MAP_PARAM·E_NESTED_FRAGMENT·E_NO_RETURN·E_OPERATOR_UNSUPPORTED·E_OUT_OF_ROW_SCOPE·E_RAW_EMPTY·E_ROOT_NOT_JSX·E_ROW_NOT_SINGLE_ROOT·E_SIGNAL_IN_LIST·E_SIGNAL_NOT_READ·E_SPREAD_UNSUPPORTED·E_UNKNOWN_BINDING·E_VOID_CHILDREN

packages/compiler/src/lower.ts

ExternalFragment interface

export interface ExternalFragment {
  id: string
  props: Set<string>
  entry: TemplateIR
  templates: TemplateIR[]
  effects: EffectSet
}

A fragment another module exported, resolved for the module that renders it.

Raised in this fileE_COMPONENT_CYCLE·E_FRAGMENT_ARGUMENT·E_NESTED_HOLE_MISSING·E_NO_SOURCE·E_PARSE·E_PRIVATE_COMPONENT_NESTED

packages/compiler/src/compile.ts

ImportRef interface

export interface ImportRef {
  /** The specifier exactly as written, which is what resolving a sibling module needs. */
  module: string
  exported: string
  /** The module id: project-relative and slash-separated, the same form a template id uses. See `spec/kernel/intents.md`. */
  id: string
}

Where a tag came from: the module specifier and the export, exactly as written.

Raised in this fileE_ATTRIBUTE_UNSUPPORTED·E_BRANCH_MIXES_SHAPE_AND_VALUE·E_BRANCH_NOT_SOLE_CHILD·E_BRANCH_ON_SIGNAL·E_CHILDREN_AS_PROP·E_CHILDREN_NOT_A_VALUE·E_CHILDREN_NOT_SOLE_CHILD·E_COMPONENT_CHILDREN_UNDECLARED·E_COMPONENT_NOT_SINGLE_ROOT·E_COMPONENT_PROP_MISSING·E_COMPONENT_PROP_UNKNOWN·E_COMPONENT_UNRESOLVED·E_COMPUTED_MEMBER·E_CTX_IN_MARKUP·E_EXPRESSION_UNSUPPORTED·E_HANDLER_NOT_AN_INTENT·E_HANDLER_NOT_IMPORTED·E_LIST_NOT_SOLE_CHILD·E_MAP_PARAM·E_NESTED_FRAGMENT·E_NO_RETURN·E_OPERATOR_UNSUPPORTED·E_OUT_OF_ROW_SCOPE·E_RAW_EMPTY·E_ROOT_NOT_JSX·E_ROW_NOT_SINGLE_ROOT·E_SIGNAL_IN_LIST·E_SIGNAL_NOT_READ·E_SPREAD_UNSUPPORTED·E_UNKNOWN_BINDING·E_VOID_CHILDREN

packages/compiler/src/lower.ts

Loc interface

export interface Loc {
  file: string
  line: number
  column: number
}

A position in a source file, so a refusal can name the line rather than the offset.

packages/compiler/src/errors.ts

Lowered interface

export interface Lowered {
  id: string
  parts: string[]
  holes: Hole[]
  wiring: WiringEntry[]
  signals: SignalDecl[]
  derived: DerivedDecl[]
  nested: NestedRequest[]
  markers: number
  /** Ids of the fragments this one renders, including instances inside a row or children markup. See `spec/compiler/effects.md`. */
  components: string[]
  /** Set when this template's markup interpolated its list item directly. Read by the list hole that owns the row. */
  rowValue?: string
  /** Whether the template is exactly one element and nothing else. See `spec/compiler/supported-subset.md`: `E_COMPONENT_NOT_SINGLE_ROOT`. */
  singleRoot: boolean
}

The result: segments, holes, wiring, and the nested templates a list or instance needs.

Raised in this fileE_ATTRIBUTE_UNSUPPORTED·E_BRANCH_MIXES_SHAPE_AND_VALUE·E_BRANCH_NOT_SOLE_CHILD·E_BRANCH_ON_SIGNAL·E_CHILDREN_AS_PROP·E_CHILDREN_NOT_A_VALUE·E_CHILDREN_NOT_SOLE_CHILD·E_COMPONENT_CHILDREN_UNDECLARED·E_COMPONENT_NOT_SINGLE_ROOT·E_COMPONENT_PROP_MISSING·E_COMPONENT_PROP_UNKNOWN·E_COMPONENT_UNRESOLVED·E_COMPUTED_MEMBER·E_CTX_IN_MARKUP·E_EXPRESSION_UNSUPPORTED·E_HANDLER_NOT_AN_INTENT·E_HANDLER_NOT_IMPORTED·E_LIST_NOT_SOLE_CHILD·E_MAP_PARAM·E_NESTED_FRAGMENT·E_NO_RETURN·E_OPERATOR_UNSUPPORTED·E_OUT_OF_ROW_SCOPE·E_RAW_EMPTY·E_ROOT_NOT_JSX·E_ROW_NOT_SINGLE_ROOT·E_SIGNAL_IN_LIST·E_SIGNAL_NOT_READ·E_SPREAD_UNSUPPORTED·E_UNKNOWN_BINDING·E_VOID_CHILDREN

packages/compiler/src/lower.ts

LowerInput interface

export interface LowerInput {
  id: string
  root: Node
  scope: Scope
  file: string
  source: string
  /** When present, escaping is decided by the value's type rather than by its syntax. */
  types?: TypeOracle
  /** The scope this fragment's stylesheet was rewritten under, when it brought a scoped one. See `spec/compiler/scoped-styles.md`. */
  cssScope?: string
  /** A derived table to append to rather than start — children markup shares its caller's binding namespace. */
  derived?: DerivedDecl[]
}

What lowering needs: the JSX, the scope around it, and the type oracle if there is one.

Raised in this fileE_ATTRIBUTE_UNSUPPORTED·E_BRANCH_MIXES_SHAPE_AND_VALUE·E_BRANCH_NOT_SOLE_CHILD·E_BRANCH_ON_SIGNAL·E_CHILDREN_AS_PROP·E_CHILDREN_NOT_A_VALUE·E_CHILDREN_NOT_SOLE_CHILD·E_COMPONENT_CHILDREN_UNDECLARED·E_COMPONENT_NOT_SINGLE_ROOT·E_COMPONENT_PROP_MISSING·E_COMPONENT_PROP_UNKNOWN·E_COMPONENT_UNRESOLVED·E_COMPUTED_MEMBER·E_CTX_IN_MARKUP·E_EXPRESSION_UNSUPPORTED·E_HANDLER_NOT_AN_INTENT·E_HANDLER_NOT_IMPORTED·E_LIST_NOT_SOLE_CHILD·E_MAP_PARAM·E_NESTED_FRAGMENT·E_NO_RETURN·E_OPERATOR_UNSUPPORTED·E_OUT_OF_ROW_SCOPE·E_RAW_EMPTY·E_ROOT_NOT_JSX·E_ROW_NOT_SINGLE_ROOT·E_SIGNAL_IN_LIST·E_SIGNAL_NOT_READ·E_SPREAD_UNSUPPORTED·E_UNKNOWN_BINDING·E_VOID_CHILDREN

packages/compiler/src/lower.ts

NestedRequest interface

export interface NestedRequest {
  holeIndex: number
  id: string
  /** Whose markup this is. Decides whether isolation reaches inside it or stops at the boundary. See `spec/compiler/effects.md`. */
  kind: 'row' | 'component' | 'children' | 'variant'
  lowered?: Lowered
  sealed?: SealedFragment
}

A template the parent renders — lowered here if it's from this module, already sealed if from another.

Raised in this fileE_ATTRIBUTE_UNSUPPORTED·E_BRANCH_MIXES_SHAPE_AND_VALUE·E_BRANCH_NOT_SOLE_CHILD·E_BRANCH_ON_SIGNAL·E_CHILDREN_AS_PROP·E_CHILDREN_NOT_A_VALUE·E_CHILDREN_NOT_SOLE_CHILD·E_COMPONENT_CHILDREN_UNDECLARED·E_COMPONENT_NOT_SINGLE_ROOT·E_COMPONENT_PROP_MISSING·E_COMPONENT_PROP_UNKNOWN·E_COMPONENT_UNRESOLVED·E_COMPUTED_MEMBER·E_CTX_IN_MARKUP·E_EXPRESSION_UNSUPPORTED·E_HANDLER_NOT_AN_INTENT·E_HANDLER_NOT_IMPORTED·E_LIST_NOT_SOLE_CHILD·E_MAP_PARAM·E_NESTED_FRAGMENT·E_NO_RETURN·E_OPERATOR_UNSUPPORTED·E_OUT_OF_ROW_SCOPE·E_RAW_EMPTY·E_ROOT_NOT_JSX·E_ROW_NOT_SINGLE_ROOT·E_SIGNAL_IN_LIST·E_SIGNAL_NOT_READ·E_SPREAD_UNSUPPORTED·E_UNKNOWN_BINDING·E_VOID_CHILDREN

packages/compiler/src/lower.ts

Scope interface

export interface Scope {
  props: Set<string>
  propsIdent?: string
  signals: Map<string, SignalDecl>
  imports: Map<string, ImportRef>
  /** Values computed in the fragment body, including everything read through the context. */
  locals: Set<string>
  /** The context parameter, whose calls are the fragment's reads. */
  ctxParam?: string
  /** Set inside a list row: the map callback's parameter name. */
  itemParam?: string
  /** Set inside a list row that named a second parameter: the row's position. See `spec/compiler/supported-subset.md`. */
  indexParam?: string
  /** Fragments this one may render, by the name it refers to them as. */
  components?: Map<string, ComponentRef>
  /** Set when some fragment in this module renders this one, so its props are wired. See `spec/compiler/supported-subset.md`. */
  wireProps?: boolean
}

What names are in scope while lowering, so a prop and a signal can be told apart.

Raised in this fileE_ATTRIBUTE_UNSUPPORTED·E_BRANCH_MIXES_SHAPE_AND_VALUE·E_BRANCH_NOT_SOLE_CHILD·E_BRANCH_ON_SIGNAL·E_CHILDREN_AS_PROP·E_CHILDREN_NOT_A_VALUE·E_CHILDREN_NOT_SOLE_CHILD·E_COMPONENT_CHILDREN_UNDECLARED·E_COMPONENT_NOT_SINGLE_ROOT·E_COMPONENT_PROP_MISSING·E_COMPONENT_PROP_UNKNOWN·E_COMPONENT_UNRESOLVED·E_COMPUTED_MEMBER·E_CTX_IN_MARKUP·E_EXPRESSION_UNSUPPORTED·E_HANDLER_NOT_AN_INTENT·E_HANDLER_NOT_IMPORTED·E_LIST_NOT_SOLE_CHILD·E_MAP_PARAM·E_NESTED_FRAGMENT·E_NO_RETURN·E_OPERATOR_UNSUPPORTED·E_OUT_OF_ROW_SCOPE·E_RAW_EMPTY·E_ROOT_NOT_JSX·E_ROW_NOT_SINGLE_ROOT·E_SIGNAL_IN_LIST·E_SIGNAL_NOT_READ·E_SPREAD_UNSUPPORTED·E_UNKNOWN_BINDING·E_VOID_CHILDREN

packages/compiler/src/lower.ts

SealedFragment interface

export interface SealedFragment {
  entry: TemplateIR
  templates: TemplateIR[]
}

A fragment another module already compiled: its entry, and everything it needs.

Raised in this fileE_ATTRIBUTE_UNSUPPORTED·E_BRANCH_MIXES_SHAPE_AND_VALUE·E_BRANCH_NOT_SOLE_CHILD·E_BRANCH_ON_SIGNAL·E_CHILDREN_AS_PROP·E_CHILDREN_NOT_A_VALUE·E_CHILDREN_NOT_SOLE_CHILD·E_COMPONENT_CHILDREN_UNDECLARED·E_COMPONENT_NOT_SINGLE_ROOT·E_COMPONENT_PROP_MISSING·E_COMPONENT_PROP_UNKNOWN·E_COMPONENT_UNRESOLVED·E_COMPUTED_MEMBER·E_CTX_IN_MARKUP·E_EXPRESSION_UNSUPPORTED·E_HANDLER_NOT_AN_INTENT·E_HANDLER_NOT_IMPORTED·E_LIST_NOT_SOLE_CHILD·E_MAP_PARAM·E_NESTED_FRAGMENT·E_NO_RETURN·E_OPERATOR_UNSUPPORTED·E_OUT_OF_ROW_SCOPE·E_RAW_EMPTY·E_ROOT_NOT_JSX·E_ROW_NOT_SINGLE_ROOT·E_SIGNAL_IN_LIST·E_SIGNAL_NOT_READ·E_SPREAD_UNSUPPORTED·E_UNKNOWN_BINDING·E_VOID_CHILDREN

packages/compiler/src/lower.ts

StripCommentsResult interface

export interface StripCommentsResult {
  code: string
  /** How many bytes of prose came out, for a caller that wants to report the saving. */
  removed: number
}

A module's prose, removed for the browser that will never read it. See spec/kernel/static.md.

packages/compiler/src/comments.ts

TypeOracle interface

export interface TypeOracle {
  /** The kind of the expression occupying exactly this span, if it can be determined. */
  kindAt(file: string, start: number, end: number): ValueKind
  /** Type errors in the compiled files. Reported, never fatal: a template still lowers. */
  diagnostics(): string[]
  /** Shuts down the checker. It runs as a separate process, so this is not optional. */
  dispose(): void
}

The type checker, asked one question: what kind of value occupies this span.

Specified inspec/compiler/supported-subset.md

packages/compiler/src/kinds.ts

SourceReader type

export type SourceReader = (file: string) => string | Promise<string>

Where a file's text comes from. One option rather than two entry points, for a file set that exists only in memory.

Raised in this fileE_COMPONENT_CYCLE·E_FRAGMENT_ARGUMENT·E_NESTED_HOLE_MISSING·E_NO_SOURCE·E_PARSE·E_PRIVATE_COMPONENT_NESTED

packages/compiler/src/compile.ts

ValueKind type

export type ValueKind = 'number' | 'boolean' | 'string' | 'other'

What the checker said a hole holds. number and boolean are what make escaping a no-op.

Specified inspec/compiler/supported-subset.md

packages/compiler/src/kinds.ts