### Install @astx/runtime Source: https://github.com/garmingo/astx/blob/master/packages/runtime/README.md Install the package using npm. ```bash npm install @astx/runtime ``` -------------------------------- ### Monorepo Setup Commands Source: https://github.com/garmingo/astx/blob/master/README.md Manage the ASTX monorepo using pnpm workspaces and Turborepo. These commands cover installing dependencies, building all packages, and type-checking. ```bash # Install dependencies pnpm install # Build all packages pnpm -r build # Type-check all packages pnpm -r check-types ``` -------------------------------- ### Install @astx/compiler Source: https://github.com/garmingo/astx/blob/master/packages/compiler/README.md Install the compiler package using npm. ```bash npm install @astx/compiler ``` -------------------------------- ### Install ASTX Packages Source: https://github.com/garmingo/astx/blob/master/README.md Install the compiler, runtime, and CLI packages using npm. The compiler is for build processes, the runtime for applications, and the CLI for command-line operations. ```bash # Compiler (e.g. in a build script) npm install @astx/compiler # Runtime (e.g. in your app) npm install @astx/runtime # CLI (global) npm install -g @astx/cli ``` -------------------------------- ### Install @astx/cli Globally Source: https://github.com/garmingo/astx/blob/master/apps/cli/README.md Install the ASTX CLI globally using npm for command-line access. ```bash npm install -g @astx/cli ``` -------------------------------- ### Display ASTX CLI and Compiler Versions Source: https://github.com/garmingo/astx/blob/master/apps/cli/README.md Print the installed versions of the ASTX CLI and compiler. ```bash astx version ``` -------------------------------- ### Print ASTX versions Source: https://context7.com/garmingo/astx/llms.txt Displays the installed versions of the ASTX CLI, compiler, and runtime. ```bash astx version # CLI: 3.1.0 # Compiler: 3.1.0 # Runtime: 3.1.0 ``` -------------------------------- ### astx version Source: https://context7.com/garmingo/astx/llms.txt Prints the installed versions of the ASTX CLI, compiler, and runtime. ```APIDOC ## astx version ### Description Prints installed versions of CLI, compiler, and runtime. ### Method `version` ### Request Example ```bash astx version ``` ### Response #### Success Response - Prints the version information for different ASTX components. #### Response Example ``` CLI: 3.1.0 Compiler: 3.1.0 Runtime: 3.1.0 ``` ``` -------------------------------- ### Run ASTX File Source: https://github.com/garmingo/astx/blob/master/README.md Execute a compiled ASTX file using the ASTX runtime library. This example loads a program from a file and runs it in 'vm' mode. ```typescript import { loadFromFile, run } from "@astx/runtime"; const program = await loadFromFile("greet.astx"); run(program, { mode: "vm" }); ``` -------------------------------- ### Browser Support with Custom Codec Source: https://github.com/garmingo/astx/blob/master/packages/runtime/README.md In a browser environment, you must supply a custom AstxCodec for decompression, as the default uses Node.js built-ins. This example uses the 'fzstd' library. ```ts import { decompress } from "fzstd"; // pure-JS Zstd decompressor import { loadFromBuffer, run } from "@astx/runtime"; const bytes = new Uint8Array(await (await fetch("/app.astx")).arrayBuffer()); const program = await loadFromBuffer(bytes, { codec: { compress: async () => { throw new Error("not needed"); }, decompress: async (data) => decompress(data), }, }); run(program); ``` -------------------------------- ### Compile JavaScript to ASTX Source: https://github.com/garmingo/astx/blob/master/README.md Use the ASTX compiler to transform JavaScript code into the ASTX binary format. This example demonstrates compiling a simple greet function and saving it to a file. ```typescript import { compile, saveToFile } from "@astx/compiler"; const program = compile(` function greet(name) { console.log("Hello, " + name); } greet("world"); `); await saveToFile(program, "greet.astx"); ``` -------------------------------- ### Browser: Compile and Serialize with Custom Codec Source: https://github.com/garmingo/astx/blob/master/packages/compiler/README.md In a browser environment, supply a custom AstxCodec for serialization when using toBuffer. This example uses WASM-backed zstd compression from @mongodb-js/zstd. ```typescript import { compress, decompress } from "@mongodb-js/zstd"; // WASM-backed import { compile, toBuffer } from "@astx/compiler"; const program = compile(source); const bytes = await toBuffer(program, { codec: { compress, decompress }, }); ``` -------------------------------- ### Define Custom AstxCodec Source: https://context7.com/garmingo/astx/llms.txt Example of defining a custom codec for ASTX, demonstrating how to integrate external compression libraries like Zstd. This is useful for custom compression strategies or environments like browsers. ```typescript import type { AstxCodec, AstxCodecOptions, CompiledProgram } from "@astx/compiler"; // or equivalently: // import type { AstxCodec, AstxCodecOptions, CompiledProgram } from "@astx/runtime"; // Custom codec example (WASM Zstd for browsers or dictionary support) import { compress, decompress } from "@mongodb-js/zstd"; const myCodec: AstxCodec = { compress: async (data: Uint8Array, opts?: AstxCodecOptions) => compress(data, opts?.level ?? 22, opts?.dict), decompress: async (data: Uint8Array, opts?: AstxCodecOptions) => decompress(data, opts?.dict), }; // CompiledProgram shape (in-memory representation) const prog: CompiledProgram = { expressionDict: ["Program", "FunctionDeclaration", ...], // AST node type names valueDict: ["Hello", 42, true], // deduplicated literals bytecode: [[0, 1, 2], [5, 0], ...], // encoded AST node arrays sourceMap: [[1, 0], [2, 4], null, ...], // optional [line, col] per slot }; ``` -------------------------------- ### Disable Individual Transformers Source: https://context7.com/garmingo/astx/llms.txt Import the compile function and pass an array of transformer keys to disable specific optimizations. This example shows how to skip loop fusion and keep map chains and assigned arrow functions. ```typescript import { compile } from "@astx/compiler"; // Disable individual transformers by key const program = compile(source, [ "FusionLoop", // Skip loop fusion "UnchainMapToLoop", // Keep .map() chains "AssignedArrowToFunction", // Keep arrow functions assigned to variables ]); ``` -------------------------------- ### Execute ASTX Binary File Source: https://github.com/garmingo/astx/blob/master/apps/cli/README.md Run an ASTX binary file. The program executes in 'vm' mode, with '__dirname' and '__filename' injected based on the file's location. ```bash astx run dist/index.astx ``` -------------------------------- ### Run Benchmarks Source: https://github.com/garmingo/astx/blob/master/packages/compiler/README.md Execute the provided benchmark script using pnpm to measure the performance of the compile() and toBuffer() functions. ```bash pnpm bench ``` -------------------------------- ### loadFromFile Source: https://context7.com/garmingo/astx/llms.txt Loads an ASTX binary from a file on disk using Node.js's `node:fs/promises` and then delegates to `loadFromBuffer`. This function is only available in Node.js environments and will throw an error if called in a browser. ```APIDOC ## loadFromFile(filename, opts?) ### Description Reads an ASTX binary file from disk using `node:fs/promises` and then uses `loadFromBuffer` to decode it. This function is exclusive to Node.js environments and will throw an error if executed in a browser. ### Parameters #### Path Parameters - **filename** (string) - Required - The path to the ASTX binary file. - **opts** (object) - Optional - Options for loading and decoding. - **codec** (AstxCodec) - Optional - A custom codec for compression and decompression. Must implement `compress` and `decompress` methods. - **dict** (Uint8Array) - Optional - A dictionary to be used with the custom codec for decompression. ``` -------------------------------- ### astx run Source: https://context7.com/garmingo/astx/llms.txt Executes a compiled ASTX binary file. ```APIDOC ## astx run ### Description Executes an ASTX binary file. ### Method `run` ### Parameters #### Path Parameters - **file** (string) - Required - The path to the ASTX binary file. ### Request Example ```bash astx run dist/index.astx ``` ### Response #### Success Response - Executes the ASTX binary and outputs its result. #### Response Example ``` # Running... # Hello, world! ``` ``` -------------------------------- ### Execute an ASTX binary Source: https://context7.com/garmingo/astx/llms.txt Executes a compiled ASTX binary file. ```bash astx run dist/index.astx # Running... # Hello, world! ``` -------------------------------- ### run Source: https://github.com/garmingo/astx/blob/master/packages/runtime/README.md Executes a previously decoded CompiledProgram. Supports different execution modes and variable injection. ```APIDOC ## `run(program, opts?)` ### Description Executes a decoded `CompiledProgram`. ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **program** (CompiledProgram) - Required - The decoded ASTX program to execute. - **opts** (RunOptions) - Optional - Options for execution. - **mode** (string) - Optional - Execution mode: `'vm'` (Node.js vm module) or `'eval'` (direct eval). - **inject** (object) - Optional - Variables to inject into the program's scope. - **__dirname** (string) - Example: `"/app"` - **__filename** (string) - Example: `"/app/index.astx"` ### Request Example ```ts run(program, { mode: "vm", // 'vm' (Node.js vm module) | 'eval' (direct eval) inject: { // variables injected into the program's scope __dirname: "/app", __filename: "/app/index.astx", }, }); ``` ### Response No specific return value documented for successful execution. ``` -------------------------------- ### toBuffer(program, opts?) Source: https://github.com/garmingo/astx/blob/master/packages/compiler/README.md Serializes a CompiledProgram to the compressed ASTX binary format. Supports custom compression codecs and levels. ```APIDOC ## toBuffer(program, opts?): Promise ### Description Serialises a `CompiledProgram` to the compressed ASTX binary format. ### Parameters #### Path Parameters - **program** (CompiledProgram) - Required - The compiled program to serialize. - **opts** (ToBufferOptions) - Optional - Options to control the serialization process. ### ToBufferOptions | Option | Type | Default | Description | |---|---|---|---| | `codec` | `AstxCodec` | Node.js built-in zstd | Custom compress/decompress implementation | | `level` | `number` | `22` | Zstd compression level (1–22) | | `dict` | `Uint8Array` | — | Pre-trained Zstd dictionary (requires custom codec) | ### Request Example ```ts import { compile, toBuffer } from "@astx/compiler"; const program = compile(source); const bytes = await toBuffer(program); ``` ### Response #### Success Response (Uint8Array) - **bytes** (Uint8Array) - The serialized binary data. ### Response Example ```ts // Example of a Uint8Array representing binary data new Uint8Array([1, 2, 3, 4, 5]) ``` ``` -------------------------------- ### Load ASTX Program from File (Node.js) Source: https://context7.com/garmingo/astx/llms.txt Reads an ASTX binary file from disk using `node:fs/promises` and delegates to `loadFromBuffer`. Throws an error in browser environments. Supports loading programs compiled with custom Zstd dictionaries. ```typescript import { loadFromFile, run } from "@astx/runtime"; // Basic load and execute const program = await loadFromFile("dist/app.astx"); run(program, { mode: "vm" }); // Load compiled with a Zstd dictionary import { decompress } from "@mongodb-js/zstd"; import { readFileSync } from "node:fs"; const dict = new Uint8Array(readFileSync("astx.dict")); const dictProgram = await loadFromFile("dist/app-dict.astx", { codec: { compress: async () => { throw new Error("not used"); }, decompress: (d, o) => decompress(d, o?.dict), }, dict, }); run(dictProgram, { mode: "vm" }); ``` -------------------------------- ### Save ASTX Program to File (Node.js) Source: https://context7.com/garmingo/astx/llms.txt Convenience wrapper for `toBuffer()` that writes an ASTX binary to disk using `node:fs/promises.writeFile`. Throws an error in browser environments. Ensure the full filename, including the extension, is provided. ```typescript import { compile, saveToFile } from "@astx/compiler"; const program = compile(` export function greet(name) { console.log("Hello, " + name + "!"); } greet("world"); `); // Write to disk await saveToFile(program, "greet.astx"); // Extension is NOT auto-appended here — provide the full filename await saveToFile(program, "dist/bundle.astx", { level: 10 }); // Error handling try { await saveToFile(program, "/read-only/output.astx"); } catch (err) { console.error("Write failed:", (err as Error).message); } ``` -------------------------------- ### Compile JavaScript to ASTX Binary Source: https://github.com/garmingo/astx/blob/master/apps/cli/README.md Compile a JavaScript file to an ASTX binary format. The .astx extension is appended automatically if omitted from the output path. ```bash astx compile src/index.js dist/index.astx ``` -------------------------------- ### ASTX CLI Compile and Run Source: https://github.com/garmingo/astx/blob/master/README.md Utilize the ASTX command-line interface to compile JavaScript files to ASTX format and to run ASTX files directly. ```bash astx compile src/index.js dist/index.astx astx run dist/index.astx ``` -------------------------------- ### saveToFile Source: https://context7.com/garmingo/astx/llms.txt Writes a CompiledProgram to disk as an ASTX binary. This is a convenience wrapper around `toBuffer()` that uses `node:fs/promises.writeFile`. It is only available in Node.js environments and will throw an error if called in a browser. ```APIDOC ## saveToFile(program, filename, opts?) ### Description Writes an ASTX binary to disk. This function is a convenience wrapper around `toBuffer()` that utilizes `node:fs/promises.writeFile`. It is exclusively available in Node.js environments and will raise an error if invoked in a browser. ### Parameters #### Path Parameters - **program** (CompiledProgram) - Required - The compiled ASTX program to save. - **filename** (string) - Required - The full path and filename to save the ASTX binary to. The extension is not auto-appended. - **opts** (object) - Optional - Options for saving, such as compression level. - **level** (number) - Optional - Compression level for the ASTX binary. ``` -------------------------------- ### Load ASTX from File (Node.js) Source: https://github.com/garmingo/astx/blob/master/packages/runtime/README.md Reads an .astx file from disk and decodes it. This function is only available in Node.js environments. ```ts import { loadFromFile, run } from "@astx/runtime"; const program = await loadFromFile("app.astx"); run(program, { mode: "vm" }); ``` -------------------------------- ### toBuffer(program, opts?) Source: https://context7.com/garmingo/astx/llms.txt Serializes a CompiledProgram object into the ASTX binary format (Zstd-compressed MessagePack). Supports custom codecs for different environments. ```APIDOC ## toBuffer(program, opts?) ### Description Encodes the compiled program to a `Uint8Array` using the ASTX wire format v0x02: a 4-byte magic header, a 1-byte format version, then a Zstd-compressed MessagePack payload of `[valueDict, bytecode, sourceMap | null]`. The default codec uses Node.js built-in `node:zlib` zstd (Node ≥ 21.7). Supply a custom `AstxCodec` for browser environments or to use Zstd dictionaries. ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Parameters - **program** (object) - Required - The `CompiledProgram` object to serialize. - **opts** (object) - Optional - Options for serialization. - **codec** (object) - Optional - A custom codec object with `compress` and `decompress` methods. - **compress** (function) - Function to compress data. - **decompress** (function) - Function to decompress data. - **level** (number) - Optional - The Zstd compression level. - **dict** (Uint8Array) - Optional - A Zstd dictionary for compression. ### Request Example ```javascript import { compile, toBuffer } from "@astx/compiler"; import { compress, decompress } from "@mongodb-js/zstd"; // WASM-backed, for browsers const program = compile(` const items = [1, 2, 3]; items.forEach(x => console.log(x)); `); // Node.js (default codec, max compression) const bytes = await toBuffer(program); // Custom compression level const fast = await toBuffer(program, { level: 3 }); // Browser / WASM codec const browserBytes = await toBuffer(program, { codec: { compress, decompress }, level: 22, }); // With a pre-trained Zstd dictionary (requires custom codec) import { readFileSync } from "node:fs"; const dict = new Uint8Array(readFileSync("astx.dict")); const dictBytes = await toBuffer(program, { codec: { compress: (d, o) => compress(d, o?.level, o?.dict), decompress: (d, o) => decompress(d, o?.dict), }, dict, }); ``` ### Response #### Success Response (200) - **bytes** (Uint8Array) - The serialized ASTX binary data. #### Response Example ```javascript // Example output is a Uint8Array, actual content is binary data. console.log(bytes.byteLength); ``` ``` -------------------------------- ### Watch and Recompile Files with ASTX CLI Source: https://github.com/garmingo/astx/blob/master/apps/cli/README.md Enable watch mode to automatically recompile the input file on every save. Compile errors during watch mode are displayed without stopping the watcher. ```bash astx compile --watch src/index.js dist/index.astx ``` -------------------------------- ### Load ASTX Program from Buffer (Node.js & Browser) Source: https://context7.com/garmingo/astx/llms.txt Decodes an ASTX binary from a `Uint8Array`. Validates the header, decompresses the payload, and MessagePack-decodes it. Works in Node.js with the default codec and in browsers with a custom `AstxCodec`. Throws on invalid magic number or unsupported version. ```typescript import { loadFromBuffer, run } from "@astx/runtime"; import { decompress } from "fzstd"; // pure-JS, browser-compatible // --- Node.js: load from a fetch response --- const response = await fetch("https://cdn.example.com/app.astx"); const bytes = new Uint8Array(await response.arrayBuffer()); try { const program = await loadFromBuffer(bytes); run(program, { mode: "eval" }); } catch (err) { // "Invalid file format: bad magic number" // "Unsupported version: 1 | Current version: 2" console.error("Load failed:", err); } // --- Browser with custom codec --- const browserProgram = await loadFromBuffer(bytes, { codec: { compress: async () => { throw new Error("not needed"); }, decompress: async (data) => decompress(data), }, }); run(browserProgram); ``` -------------------------------- ### loadFromFile Source: https://github.com/garmingo/astx/blob/master/packages/runtime/README.md Reads an .astx file from disk and decodes it. This function is only available in Node.js environments. ```APIDOC ## `loadFromFile(filename, opts?)` ### Description Reads an `.astx` file from disk and decodes it. **Node.js only.** ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **filename** (string) - Required - The path to the `.astx` file. - **opts** (LoadFileOptions) - Optional - Options for loading the file (similar to `loadFromBuffer` options like `codec`, `dict`). ### Request Example ```ts import { loadFromFile, run } from "@astx/runtime"; const program = await loadFromFile("app.astx"); run(program, { mode: "vm" }); ``` ### Response #### Success Response (200) - **program** (CompiledProgram) - The decoded ASTX program. #### Response Example (CompiledProgram object structure not detailed in source) ``` -------------------------------- ### Compile JS file to .astx Source: https://context7.com/garmingo/astx/llms.txt Compiles a JavaScript file to the ASTX binary format. The extension is appended automatically if omitted. Supports watch mode for automatic recompilation on file changes. ```bash # One-shot compile astx compile src/index.js dist/index.astx # Extension is appended automatically if omitted astx compile src/index.js dist/index # → dist/index.astx # Watch mode: recompiles on every save, prints timestamped output astx compile --watch src/index.js dist/index.astx # Watching src/index.js for changes… (Ctrl+C to stop) # [14:02:33] Compiled src/index.js → dist/index.astx in 11.4ms # [14:02:45] Compiled src/index.js → dist/index.astx in 10.9ms ``` -------------------------------- ### AstxCodec Interface Source: https://github.com/garmingo/astx/blob/master/packages/shared/README.md Interface for pluggable compression/decompression. Implement this to use ASTX in a browser or with a Zstd dictionary. ```APIDOC ## AstxCodec Interface for pluggable compression/decompression. Implement this to use ASTX in a browser or with a Zstd dictionary. ### Methods - `compress(data: Uint8Array, opts?: AstxCodecOptions): Uint8Array | Promise`: Compresses the given data. - `decompress(data: Uint8Array, opts?: AstxCodecOptions): Uint8Array | Promise`: Decompresses the given data. ``` -------------------------------- ### saveToFile(program, filename, opts?) Source: https://github.com/garmingo/astx/blob/master/packages/compiler/README.md A convenience wrapper that serializes a CompiledProgram and writes the binary data to a specified file. This function is Node.js specific. ```APIDOC ## saveToFile(program, filename, opts?): Promise ### Description Convenience wrapper: serialises and writes the binary to disk. **Node.js only.** ### Parameters #### Path Parameters - **program** (CompiledProgram) - Required - The compiled program to save. - **filename** (string) - Required - The name of the file to save the binary to. - **opts** (object) - Optional - Additional options (currently not detailed in source). ### Request Example ```ts import { compile, saveToFile } from "@astx/compiler"; const program = compile(source); await saveToFile(program, "output.astx"); ``` ### Response #### Success Response (void) - This function does not return a value upon successful completion. ### Response Example ``` // No response body for success ``` ``` -------------------------------- ### Save Compiled Program to File Source: https://github.com/garmingo/astx/blob/master/packages/compiler/README.md Convenience wrapper to serialize and write the compiled binary program to disk. This function is Node.js specific. ```typescript import { compile, saveToFile } from "@astx/compiler"; const program = compile(source); await saveToFile(program, "output.astx"); ``` -------------------------------- ### AstxCodecOptions Interface Source: https://github.com/garmingo/astx/blob/master/packages/shared/README.md Options for AstxCodec compression and decompression. ```APIDOC ## AstxCodecOptions Options for AstxCodec compression and decompression. ### Properties - `level?` (number): Zstd compression level 1–22. - `dict?` (Uint8Array): Pre-trained Zstd dictionary. ``` -------------------------------- ### AstxCodec Interface Source: https://github.com/garmingo/astx/blob/master/packages/shared/README.md Interface for pluggable compression/decompression. Implement this to use ASTX in a browser or with a Zstd dictionary. ```typescript export interface AstxCodec { compress(data: Uint8Array, opts?: AstxCodecOptions): Uint8Array | Promise; decompress(data: Uint8Array, opts?: AstxCodecOptions): Uint8Array | Promise; } ``` -------------------------------- ### Wire Format Header Constants Source: https://github.com/garmingo/astx/blob/master/packages/shared/README.md Defines the MAGIC_HEADER and FORMAT_VERSION for the ASTX wire format. ```plaintext Offset Length Field ────────────────────────────────── 0 4 MAGIC_HEADER (0xa5 0x7b 0x1c 0x00) 4 1 FORMAT_VERSION (0x02) 5 … Zstd-compressed MessagePack payload ``` -------------------------------- ### Wire Format (v0x02) Source: https://github.com/garmingo/astx/blob/master/packages/shared/README.md Specification for the ASTX wire format. ```APIDOC ## Wire Format (v0x02) ### Structure | Offset | Length | Field | |--------|--------|----------------| | 0 | 4 | MAGIC_HEADER | | 4 | 1 | FORMAT_VERSION | | 5 | … | Payload | - `MAGIC_HEADER`: `0xa5 0x7b 0x1c 0x00` - `FORMAT_VERSION`: `0x02` ### Payload The decompressed payload is a Zstd-compressed MessagePack array with the following structure: ``` [valueDict, bytecode, sourceMap | null] ``` - `valueDict`: Deduplicated literal values. - `bytecode`: Encoded AST nodes. - `sourceMap`: Optional array of [line, col] tuples. Note: `expressionDict` is not stored on disk and is reconstructed from `PREDEFINED_TYPES`. ``` -------------------------------- ### Decompile ASTX Binary to JavaScript Source: https://github.com/garmingo/astx/blob/master/apps/cli/README.md Decompile an ASTX binary file back into JavaScript source code. This output is intended for debugging and is not optimized or human-readable. ```bash astx gen dist/index.astx dist/index.debug.js ``` -------------------------------- ### createSourceMapConsumer Source: https://context7.com/garmingo/astx/llms.txt Creates a SourceMapConsumer from a compiled program to inspect source locations. Returns null if no source map is present. ```APIDOC ## createSourceMapConsumer(program) ### Description Creates a `SourceMapConsumer` from a program compiled with `{ sourceMap: true }`. Returns `null` if no source map is present. Useful for mapping runtime errors or coverage data back to original source lines. ### Parameters #### Path Parameters - **program** (CompiledProgram) - Required - The compiled program object. ### Request Example ```ts import { compile, toBuffer } from "@astx/compiler"; import { loadFromBuffer, createSourceMapConsumer } from "@astx/runtime"; const source = ` function add(a, b) { return a + b; } console.log(add(1, 2)); `; const program = compile(source, [], { sourceMap: true }); const bytes = await toBuffer(program); const loaded = await loadFromBuffer(bytes); const consumer = createSourceMapConsumer(loaded); if (consumer) { // Look up a specific bytecode slot console.log(consumer.lookup(0)); // e.g. { line: 2, column: 0 } console.log(consumer.lookup(5)); // { line: 3, column: 2 } or null for synthetic node // All recorded positions (for coverage tooling) const all = consumer.allPositions(); // [{ bytecodeIndex: 0, line: 2, column: 0 }, ...] // Find bytecode slots for a given original line (e.g. for error mapping) const slots = consumer.findSlotsByLine(3); console.log(slots); // [4, 5] } ``` ### Response #### Success Response - **SourceMapConsumer** - An object with methods to inspect source map data, or null if no source map is present. #### Response Example ```json { "lookup": "(bytecodeIndex: number) => { line: number, column: number } | null", "allPositions": "() => Array<{ bytecodeIndex: number, line: number, column: number }>", "findSlotsByLine": "(line: number) => number[]" } ``` ``` -------------------------------- ### astx compile Source: https://context7.com/garmingo/astx/llms.txt Compiles a JavaScript file into an ASTX binary format. Supports watch mode for continuous compilation. ```APIDOC ## astx compile [--watch] ### Description Compiles a JS file to `.astx`. The extension is appended automatically if omitted. Supports watch mode for recompiling on file save. ### Method `compile` ### Parameters #### Path Parameters - **input** (string) - Required - The input JavaScript file path. - **output** (string) - Required - The output ASTX file path. #### Query Parameters - **--watch** (boolean) - Optional - Enables watch mode for continuous compilation. ### Request Example ```bash # One-shot compile astx compile src/index.js dist/index.astx # Extension is appended automatically if omitted astx compile src/index.js dist/index # → dist/index.astx # Watch mode: recompiles on every save, prints timestamped output astx compile --watch src/index.js dist/index.astx ``` ### Response #### Success Response - Compiles the input file to the specified output file. #### Response Example ``` # Watching src/index.js for changes… (Ctrl+C to stop) # [14:02:33] Compiled src/index.js → dist/index.astx in 11.4ms # [14:02:45] Compiled src/index.js → dist/index.astx in 10.9ms ``` ``` -------------------------------- ### Serialize Compiled Program to Buffer Source: https://github.com/garmingo/astx/blob/master/packages/compiler/README.md Serializes a CompiledProgram to the compressed ASTX binary format. Imports compile and toBuffer from the @astx/compiler package. The toBuffer function returns a Promise resolving to a Uint8Array. ```typescript import { compile, toBuffer } from "@astx/compiler"; const program = compile(source); const bytes = await toBuffer(program); ``` -------------------------------- ### Redirect Compilation Logs to Custom Logger Source: https://github.com/garmingo/astx/blob/master/packages/compiler/README.md Redirect compilation logs to a custom logger by providing a logger object with log and warn methods. This is useful for integrating with existing logging systems like pino or winston. ```typescript // Redirect to a custom logger (e.g. pino, winston, a test spy) const program = compile(source, [], { verbose: true, logger: { log: (...args) => myLogger.debug(args.join(" ")), warn: (...args) => myLogger.warn(args.join(" ")), }, }); ``` -------------------------------- ### run Source: https://context7.com/garmingo/astx/llms.txt Executes a decoded CompiledProgram. This function can regenerate JavaScript source from the decoded AST and execute it in one of three modes: 'eval' (indirect eval in global scope, default), 'scoped' (Function constructor with injected variables), or 'vm' (Node.js vm module sandbox, recommended for server-side). The 'inject' map merges extra variables into the execution scope. ```APIDOC ## run(program, opts?) ### Description Executes a decoded `CompiledProgram`. This function regenerates JavaScript source from the decoded AST and executes it in one of three modes: `"eval"` (indirect `eval` in global scope - default, suitable for FiveM/game-engine environments), `"scoped"` (Function constructor with injected variables), or `"vm"` (Node.js `vm` module sandbox - recommended for server-side use). The `inject` map allows merging extra variables into the execution scope; `__dirname` / `__filename` are particularly important in `vm` mode for resolving relative `require` paths. ### Parameters #### Path Parameters - **program** (CompiledProgram) - Required - The decoded ASTX program to execute. - **opts** (object) - Optional - Options for execution. - **mode** (string) - Optional - Execution mode: `"eval"`, `"scoped"`, or `"vm"`. Defaults to `"eval"`. - **inject** (object) - Optional - A map of variables to inject into the execution scope. - **skipDefaultInjects** (boolean) - Optional - If true, skips default injections like `require`, `process`, and `console`. ``` -------------------------------- ### AstxCodecOptions Interface Source: https://github.com/garmingo/astx/blob/master/packages/shared/README.md Options for AstxCodec, including compression level and Zstd dictionary. ```typescript export interface AstxCodecOptions { level?: number; // Zstd compression level 1–22 dict?: Uint8Array; // Pre-trained Zstd dictionary } ``` -------------------------------- ### loadFromBuffer Source: https://context7.com/garmingo/astx/llms.txt Decodes an ASTX binary from a Uint8Array. This function validates the magic header and format version, decompresses the payload using Zstd, and then MessagePack-decodes it into a CompiledProgram. It works in Node.js with the default codec and in browsers when a custom AstxCodec is provided. Errors are thrown for invalid magic numbers or unsupported format versions. ```APIDOC ## loadFromBuffer(buffer, opts?) ### Description Decodes an ASTX binary from a `Uint8Array`. This function performs validation of the magic header and format version, decompresses the payload using Zstd, and then MessagePack-decodes it into a `CompiledProgram`. It is compatible with Node.js using the default codec and with browsers when a custom `AstxCodec` is supplied. Throws an error if the magic number is invalid or the format version is unsupported. ### Parameters #### Path Parameters - **buffer** (Uint8Array) - Required - The buffer containing the ASTX binary data. - **opts** (object) - Optional - Options for decoding. - **codec** (AstxCodec) - Optional - A custom codec for compression and decompression. Must implement `compress` and `decompress` methods. ``` -------------------------------- ### Load ASTX from Buffer Source: https://github.com/garmingo/astx/blob/master/packages/runtime/README.md Decodes an ASTX binary from a Uint8Array or Buffer. Ensure the response is correctly converted to bytes. ```ts import { loadFromBuffer, run } from "@astx/runtime"; const response = await fetch("/app.astx"); const bytes = new Uint8Array(await response.arrayBuffer()); const program = await loadFromBuffer(bytes); run(program); ``` -------------------------------- ### Create SourceMapConsumer from Compiled Program Source: https://context7.com/garmingo/astx/llms.txt Creates a SourceMapConsumer from a program compiled with `{ sourceMap: true }`. Returns `null` if no source map is present. Useful for mapping runtime errors or coverage data back to original source lines. ```typescript import { compile, toBuffer } from "@astx/compiler"; import { loadFromBuffer, createSourceMapConsumer } from "@astx/runtime"; const source = ` function add(a, b) { return a + b; } console.log(add(1, 2)); `; const program = compile(source, [], { sourceMap: true }); const bytes = await toBuffer(program); const loaded = await loadFromBuffer(bytes); const consumer = createSourceMapConsumer(loaded); if (consumer) { // Look up a specific bytecode slot console.log(consumer.lookup(0)); // e.g. { line: 2, column: 0 } console.log(consumer.lookup(5)); // { line: 3, column: 2 } or null for synthetic node // All recorded positions (for coverage tooling) const all = consumer.allPositions(); // [{ bytecodeIndex: 0, line: 2, column: 0 }, ...] // Find bytecode slots for a given original line (e.g. for error mapping) const slots = consumer.findSlotsByLine(3); console.log(slots); // [4, 5] } ``` -------------------------------- ### loadFromBuffer Source: https://github.com/garmingo/astx/blob/master/packages/runtime/README.md Decodes an ASTX binary from a Uint8Array or Buffer. Supports custom decompression implementations via options. ```APIDOC ## `loadFromBuffer(buffer, opts?)` ### Description Decodes an ASTX binary from a `Uint8Array` or `Buffer`. ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **buffer** (Uint8Array | Buffer) - Required - The binary data of the ASTX file. - **opts** (LoadBufferOptions) - Optional - Options for decoding. - **codec** (AstxCodec) - Optional - Custom decompression implementation. - **dict** (Uint8Array) - Optional - Zstd dictionary for decompression. ### Request Example ```ts import { loadFromBuffer, run } from "@astx/runtime"; const response = await fetch("/app.astx"); const bytes = new Uint8Array(await response.arrayBuffer()); const program = await loadFromBuffer(bytes); run(program); ``` ### Response #### Success Response (200) - **program** (CompiledProgram) - The decoded ASTX program. #### Response Example (CompiledProgram object structure not detailed in source) ``` -------------------------------- ### Execute Compiled ASTX Program Source: https://github.com/garmingo/astx/blob/master/packages/runtime/README.md Executes a decoded CompiledProgram. Options include 'vm' or 'eval' mode and injecting variables into the program's scope. ```ts run(program, { mode: "vm", // 'vm' (Node.js vm module) | 'eval' (direct eval) inject: { // variables injected into the program's scope __dirname: "/app", __filename: "/app/index.astx", }, }); ``` -------------------------------- ### compile(code, skipTransformers?, opts?) Source: https://github.com/garmingo/astx/blob/master/packages/compiler/README.md Parses and optimizes JavaScript source code, returning a CompiledProgram. It can optionally skip specified transformers and accept compilation options. ```APIDOC ## compile(code, skipTransformers?, opts?) ### Description Parses and optimises JavaScript source code, returns a `CompiledProgram`. ### Parameters #### Path Parameters - **code** (string) - Required - The JavaScript source code to compile. - **skipTransformers** (array of string) - Optional - An array of transformer names to disable for this compilation. - **opts** (CompileOptions) - Optional - Options to control the compilation process. ### CompileOptions | Option | Type | Default | Description | |---|---|---|---| | `sourceMap` | `boolean` | `false` | Attach `[line, col]` info to every bytecode slot | | `verbose` | `boolean` | `false` | Print transformer activity to the logger | | `logger` | `CompileLogger` | `console` | Custom logger – implement `{ log, warn }` to redirect output | ### Request Example ```ts import { compile } from "@astx/compiler"; const program = compile(` const result = 2 ** 10; console.log(result); `); ``` ### Response #### Success Response (CompiledProgram) - **program** (CompiledProgram) - The compiled program object. ### Response Example ```ts // Example of a CompiledProgram object (structure not fully defined in source) { // ... program details ... } ``` ``` -------------------------------- ### Compile JavaScript to ASTX CompiledProgram Source: https://context7.com/garmingo/astx/llms.txt Parses JavaScript source, runs an optimization pipeline, and returns an in-memory CompiledProgram. Use `skipTransformers` to exclude specific optimizations or presets like 'keep-functional'. Custom loggers can be provided. ```typescript import { compile } from "@astx/compiler"; // --- Basic compilation --- const program = compile(` const TAX = 0.2; function total(price) { return price + price * TAX; } console.log(total(100)); `); // InlineConstantVariables replaces TAX → 0.2, ConstantFolding folds 0.2*100 → 20, etc. console.log(program.bytecode.length); // number of deduplicated bytecode slots console.log(program.valueDict); // e.g. [0.2] // --- Skip specific transformers --- const noFusion = compile(source, ["FusionLoop", "PowToMultiply"]); // --- Keep-functional preset (skip all loop-rewriting transforms) --- const functional = compile(source, "keep-functional"); // --- Skip every transformer --- const raw = compile(source, "all"); // --- With source map + custom logger --- import pino from "pino"; const logger = pino(); const withMap = compile(source, [], { sourceMap: true, verbose: true, logger: { log: (...args) => logger.debug(args.join(" ")), warn: (...args) => logger.warn(args.join(" ")), }, }); console.log(withMap.sourceMap?.[0]); // e.g. [1, 0] ``` -------------------------------- ### Enable Built-in Console Logging Source: https://github.com/garmingo/astx/blob/master/packages/compiler/README.md Enable built-in console output for transformer activity during compilation by setting the verbose option to true. ```typescript // Enable built-in console output const program = compile(source, [], { verbose: true }); ``` -------------------------------- ### Use 'keep-functional' Preset Source: https://context7.com/garmingo/astx/llms.txt Import the compile function and use the 'keep-functional' preset to skip all loop-rewriting transforms. This preset retains several other optimizations. ```typescript // "keep-functional" preset — skips all loop-rewriting transforms // Retains: tree-shaking, inline-constant-variables, constant-folding, // dead-code-elimination, logical-simplification, pow-to-multiply, // redundant-return-elimination, consecutive-var-merging, restore-exported-names const safe = compile(source, "keep-functional"); ``` -------------------------------- ### CompiledProgram Interface Source: https://github.com/garmingo/astx/blob/master/packages/shared/README.md In-memory representation of a compiled ASTX program. ```APIDOC ## CompiledProgram In-memory representation of a compiled ASTX program. ### Properties - `expressionDict` (string[]): AST node type names. - `valueDict` (any[]): Deduplicated literal values. - `bytecode` (any[]): Encoded AST nodes. - `sourceMap?` (([number, number] | null)[] | null): Optional [line, col] per slot. ``` -------------------------------- ### Use 'keep-functional' Preset Source: https://github.com/garmingo/astx/blob/master/packages/compiler/README.md The 'keep-functional' preset includes only lightweight, syntactic passes and skips loop-rewriting transformers. Use this preset when a more minimal set of optimizations is desired. ```typescript const program = compile(source, "keep-functional"); ``` -------------------------------- ### Serialise CompiledProgram to ASTX Binary Format Source: https://context7.com/garmingo/astx/llms.txt Encodes a CompiledProgram into a `Uint8Array` using the ASTX v0x02 format. Supports custom codecs for browser environments or specific compression needs, including Zstd dictionaries. ```typescript import { compile, toBuffer } from "@astx/compiler"; import { compress, decompress } from "@mongodb-js/zstd"; // WASM-backed, for browsers const program = compile(` const items = [1, 2, 3]; items.forEach(x => console.log(x)); `); // --- Node.js (default codec, max compression) --- const bytes = await toBuffer(program); console.log(bytes.byteLength); // typically much smaller than JSON.stringify(program) // --- Custom compression level --- const fast = await toBuffer(program, { level: 3 }); // --- Browser / WASM codec --- const browserBytes = await toBuffer(program, { codec: { compress, decompress }, level: 22, }); // --- With a pre-trained Zstd dictionary (requires custom codec) --- import { readFileSync } from "node:fs"; const dict = new Uint8Array(readFileSync("astx.dict")); const dictBytes = await toBuffer(program, { codec: { compress: (d, o) => compress(d, o?.level, o?.dict), decompress: (d, o) => decompress(d, o?.dict), }, dict, }); ``` -------------------------------- ### Generate JavaScript Code from ASTX Source: https://github.com/garmingo/astx/blob/master/packages/runtime/README.md Converts a decoded CompiledProgram back to JavaScript source code. The output is not minified and is primarily for debugging purposes. ```ts import { loadFromFile, generateJSCode } from "@astx/runtime"; const program = await loadFromFile("app.astx"); console.log(generateJSCode(program)); ``` -------------------------------- ### Execute Compiled ASTX Program Source: https://context7.com/garmingo/astx/llms.txt Executes a decoded `CompiledProgram` in one of three modes: 'eval' (global scope, default), 'scoped' (Function constructor), or 'vm' (Node.js vm module sandbox, recommended for server-side). The `inject` map merges variables into the scope; `__dirname` and `__filename` are important in 'vm' mode. ```typescript import { loadFromFile, run } from "@astx/runtime"; import path from "node:path"; const program = await loadFromFile("dist/worker.astx"); // --- vm mode (Node.js sandbox, recommended) --- run(program, { mode: "vm", inject: { __dirname: path.resolve("dist"), __filename: path.resolve("dist/worker.astx"), MY_CONFIG: { apiKey: "secret", timeout: 5000 }, }, }); // --- scoped mode (Function constructor) --- run(program, { mode: "scoped", inject: { ENV: "production" }, }); // --- eval mode (global scope, no require check) --- run(program, { mode: "eval", skipDefaultInjects: true, // skip require/process/console defaults inject: { customGlobal: 42 }, }); // --- vm mode returns a Promise --- const result = await (run(program, { mode: "vm" }) as Promise); console.log("Exit value:", result); ``` -------------------------------- ### astx gen Source: https://context7.com/garmingo/astx/llms.txt Decompiles an ASTX binary file back into JavaScript code (primarily for debugging). ```APIDOC ## astx gen ### Description Decompiles an ASTX binary to JS (debug only). ### Method `gen` ### Parameters #### Path Parameters - **input** (string) - Required - The path to the input ASTX binary file. - **output** (string) - Required - The path for the output JavaScript file. ### Request Example ```bash astx gen dist/index.astx dist/index.debug.js ``` ### Response #### Success Response - Decompiles the ASTX binary and saves the JavaScript code to the specified output file. #### Response Example ``` # Loading .astx file... # Generating JS Code... # Saving to file... ``` ``` -------------------------------- ### generateJSCode Source: https://context7.com/garmingo/astx/llms.txt Decompiles a CompiledProgram back into JavaScript source code. This function decodes the bytecode back to a Babel AST and then uses `@babel/generator` to regenerate the JavaScript source. The output is not minified and uses short, generated identifiers for variables, making it suitable for debugging purposes only. ```APIDOC ## generateJSCode(program) ### Description Decompiles a `CompiledProgram` back into JavaScript source code. This function decodes the bytecode into a Babel AST and then uses `@babel/generator` to regenerate the JavaScript source. The output is not minified and uses short, generated identifiers for variable names (e.g., `a`, `b`, `c`), making it intended for debugging purposes only. ### Parameters #### Path Parameters - **program** (CompiledProgram) - Required - The compiled ASTX program to decompile. ``` -------------------------------- ### CompiledProgram Interface Source: https://github.com/garmingo/astx/blob/master/packages/shared/README.md In-memory representation of a compiled ASTX program. Includes dictionaries for expressions and values, bytecode, and an optional source map. ```typescript export interface CompiledProgram { expressionDict: string[]; // AST node type names valueDict: any[]; // Deduplicated literal values bytecode: any[]; // Encoded AST nodes sourceMap?: ([number, number] | null)[] | null; // Optional [line, col] per slot } ```