DriftJS Compiler API
The driftjs-compiler package parses, transforms, and generates register VM bytecode from .drift source strings.
Primary Function
Compile Function
Compiles a .drift Single File Component source string into a CompiledModule.
import { compile, type CompiledModule } from 'driftjs-compiler';
const sfcSource = `
<script>
let count = 0;
</script>
<button onclick={() => count++}>Count: {count}</button>
`;
const compiled: CompiledModule = compile(sfcSource, false);
console.log(compiled.bytecode); // Uint32Array [...]
console.log(compiled.constants); // Array of constant pool entries
Parameters
source:string— Raw.driftSFC template string.debug:boolean(optional, default:false) — When true, emits AST diagnostics and instruction disassembly to console.
Returns
CompiledModule: The executable module containing bytecode and constant pool entries.
Core Classes
Drift Lexer Class
Stateful scanner converting raw template text into a stream of Token records.
import { DriftLexer, type Token } from 'driftjs-compiler';
const lexer = new DriftLexer(source);
let token: Token = lexer.nextToken();
while (token.type !== 'EOF') {
console.log(token.type, token.value, token.loc);
token = lexer.nextToken();
}
Drift Parser Class
Recursive descent parser producing a typed AST (ProgramNode).
import { DriftLexer, DriftParser, type ProgramNode } from 'driftjs-compiler';
const lexer = new DriftLexer(source);
const parser = new DriftParser(lexer);
const ast: ProgramNode = parser.parse();
Drift Transformer Class
Enriches the raw AST by parsing JavaScript expressions with Acorn, extracting <script> code, and pruning whitespace text nodes.
import { DriftTransformer } from 'driftjs-compiler';
const transformer = new DriftTransformer(ast);
const enrichedAst = transformer.transform();
Drift Generator Class
Walks enriched AST nodes, allocates 256 registers, and generates the final CompiledModule.
import { DriftGenerator } from 'driftjs-compiler';
const generator = new DriftGenerator(enrichedAst);
const module = generator.generate();
Interfaces and Types
Compiled Module Interface
export interface CompiledModule {
readonly bytecode: Uint32Array | readonly number[];
readonly constants: readonly any[];
readonly reactiveBindings?: readonly ReactiveBinding[];
readonly declaredVars?: readonly string[];
readonly derived?: readonly DerivedBinding[];
readonly effects?: readonly EffectBinding[];
readonly imports?: readonly ImportSpec[];
readonly scope?: Record<string, any>;
}
Reactive Binding Interface
export type ReactiveBindingKind = 'variable' | 'property' | 'derived' | 'custom';
export interface ReactiveBinding {
readonly name: string;
readonly type: ReactiveBindingKind;
readonly positions: readonly number[]; // Bytecode PC indices
}