@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.
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
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
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
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
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
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
locate
function
export function locate(file: string, source: string, offset = 0): Loc { … }A byte offset as a line and column.
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
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
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
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
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
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
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
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
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
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
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.
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
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
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
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
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
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.
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
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
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