BytecodeBuilder

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

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(pluginFunctionIndex?): BytecodeBuilder;

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

The per-engine plugin function name -> registry index map, wired in by the engine so emitPluginCall can resolve a name at emit time. The same object reference is shared with every builder in an engine (the pool and each ad-hoc nested-body builder), and the engine populates it as packages register, so a parselet never sees the numeric index.

Parameters

Parameter	Type
pluginFunctionIndex?	ReadonlyMap<string, number>

Returns

BytecodeBuilder

Accessors

currentLength

Get Signature

get currentLength(): number;

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

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

Returns

number

---

pluginIndexMap

Get Signature

get pluginIndexMap(): ReadonlyMap<string, number> | undefined;

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

The name->index map, so a nested-body builder inherits the same resolution.

Returns

ReadonlyMap<string, number> | undefined

---

readsDocument

Get Signature

get readsDocument(): boolean;

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

Whether a call emitted into this builder since its last reset reads other lines of the document (PluginCallOptions.readsDocument), so a held expression can say why it is refused.

Returns

boolean

Methods

build()

build(): BytecodeProgram;

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

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:467

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:409

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:367

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:362

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:311

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

Deduplicated so that the 256-entry pool counts distinct values rather than occurrences: a long line of repeated literals used to exhaust it long before it held 256 different numbers. Negative zero keeps its own slot, because 1 / -0 is not 1 / 0; NaN shares one, since every NaN reads the same.

Parameters

Parameter	Type
n	number

Returns

void

Throws

If the pool would exceed 256 distinct entries.

---

emitOpcode()

emitOpcode(op): void;

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

Emit an OpCode instruction.

Parameters

Parameter	Type
op	OpCode

Returns

void

---

emitPluginCall()

emitPluginCall(
   name,
   argCount,
   options?
): void;

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

Emit a plugin-function call by NAME. The engine assigns each registered pluginFunctions entry an index at registration; this resolves the name to that index and emits CALL_PLUGIN + index + argCount. Package authors emit through this rather than a hand-allocated index.

A call marks the program as one that may wait for data (BytecodeProgram.hasAsync), since a handler is allowed to return a promise, and every held expression (the expression of solve, a function body, a map transform) refuses such a program. A handler that never returns a promise, one that only builds a value from its arguments (the constants package attaching gravity’s unit), passes { synchronous: true }, and the call leaves that mark alone.

Parameters

Parameter	Type	Description
name	string	The plugin function’s registered name.
argCount	number	How many values the call takes from the stack.
options?	PluginCallOptions	synchronous: the handler always answers at once.

Returns

void

---

emitString()

emitString(s): void;

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

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:387

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:423

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:497

Returns

void