BytecodeBuilder

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:98

Direct-to-bytecode compiler for the Pratt parser.

Accumulates opcodes, numeric constants, and string references during parsing, then produces a BytecodeProgram for VM execution. Supports:

• Standard build via build
• Zero-copy build into pre-allocated buffers via buildInto
• In-place reset for reuse without reallocation

Constructors

Constructor

new BytecodeBuilder(): BytecodeBuilder;

Returns

BytecodeBuilder

Accessors

currentLength

Get Signature

get currentLength(): number;

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:184

Number of opcodes/operands emitted so far, used to compute jump targets before patchJump.

Returns

number

Methods

build()

build(): BytecodeProgram;

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:243

Build the accumulated opcodes/numbers/strings into a BytecodeProgram. Creates new TypedArrays, the builder can be reused after this call.

Returns

BytecodeProgram

---

buildInto()

buildInto(buf?): BytecodeProgram;

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:271

Build directly into a pre-allocated buffer for zero-copy VM consumption.

When buf is provided and large enough, writes into it and returns subarray views (not copies), the returned TypedArrays share the buffer’s underlying ArrayBuffer. The caller MUST NOT mutate the buffer until the returned BytecodeProgram is no longer needed.

If the caller intends to cache the result, they must copy the TypedArrays (e.g. new Uint8Array(program.opcodes)) before reusing the buffer pool.

When buf is omitted or too small, allocates fresh TypedArrays.

Parameters

Parameter	Type
buf?	{ numbers: Float64Array; opcodes: Uint8Array; }
buf.numbers?	Float64Array
buf.opcodes?	Uint8Array

Returns

BytecodeProgram

---

emitAnonymousBody()

emitAnonymousBody(params, program): number;

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:221

Register a compiled map/reduce anonymous transform body, returning its index into this program’s anonymousBodies side-table, the caller emits that index as MAP_INVOKE/REDUCE_INVOKE’s operand via emitIndex. Same MAX_CONSTANT_POOL_INDEX bound as emitUserFunctionBody.

Parameters

Parameter	Type
params	string[]
program	BytecodeProgram

Returns

number

Throws

If more than 256 anonymous bodies are registered on one program.

---

emitByte()

emitByte(b): void;

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:179

Emit a raw byte (0-255), used for fixed small operands like argument counts.

Parameters

Parameter	Type
b	number

Returns

void

---

emitIndex()

emitIndex(idx): void;

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:174

Emit a raw numeric operand (0-255) following an opcode, e.g. a plugin-function index for CALL_PLUGIN, or an argument count. Unlike emitOpcode, this does not go through the OpCode enum, so package authors use this (not an unsafe cast to OpCode) to push operands their own opcode handler expects to read positionally.

Parameters

Parameter	Type
idx	number

Returns

void

---

emitNumber()

emitNumber(n): void;

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:128

Emit a numeric literal: appends n to the program’s constant pool and writes its index into the opcode stream (read back by the VM as e.g. PUSH_NUMBER <idx>).

Numeric constants are NOT deduplicated (unlike emitString) every call appends a new entry, so an expression with more than MAX_CONSTANT_POOL_INDEX+1 distinct numeric-literal occurrences throws rather than silently wrapping the index (see MAX_CONSTANT_POOL_INDEX’s doc for what that would otherwise do).

Parameters

Parameter	Type
n	number

Returns

void

Throws

If the constant pool would exceed 256 entries.

---

emitOpcode()

emitOpcode(op): void;

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:108

Emit an OpCode instruction.

Parameters

Parameter	Type
op	OpCode

Returns

void

---

emitString()

emitString(s): void;

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:150

Emit a string literal: interns s into the program’s string pool (deduplicated via stringIndex) and writes its index into the opcode stream. Subject to the same constant-pool bound as emitNumber, but since strings ARE deduplicated, only distinct string values count against the limit.

Parameters

Parameter	Type
s	string

Returns

void

Throws

If the string pool would exceed 256 distinct entries.

---

emitUserFunctionBody()

emitUserFunctionBody(
   name,
   params,
   program): number;

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:199

Register a compiled user-defined-function body, returning its index into this program’s userFunctionBodies side-table, the caller emits that index as DEFINE_USER_FUNCTION’s operand via emitIndex. Subject to the same MAX_CONSTANT_POOL_INDEX bound as emitNumber/emitString (the index itself is a single opcode-stream byte), in practice a single line defines at most a handful of functions, so this limit is never realistically reached.

Parameters

Parameter	Type
name	string
params	string[]
program	BytecodeProgram

Returns

number

Throws

If more than 256 function bodies are registered on one program.

---

patchJump()

patchJump(position, target): void;

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:235

Overwrite a previously-emitted placeholder operand at position with the real jump target, once known.

Parameters

Parameter	Type
position	number
target	number

Returns

void

---

reset()

reset(): void;

Defined in: packages/engine/src/parser/BytecodeBuilder.ts:301

Returns

void