@felixdrp/gcf-wasm 0.1.0 → 0.2.0

package/README.md

@@ -92,6 +92,41 @@ text as rows arrive, and crossing into wasm for every row would cost more
 than it saves. They follow the same quoting and number rules as the module,
 and the tests check that the two agree.
 
+## Compatibility and limits
+
+* **Spec 3.6.0 output.** The encoder factors constant columns
+  (`## users [3]{id,name=Ada}`), as SPEC v3.6.0 §7.4.7 requires, byte for
+  byte like Blackwell's gcf-typescript 2.7.0. Decoders written for older
+  versions of the spec cannot read it: `@blackwell-systems/gcf` 2.6.1, the
+  latest on npm at the time of writing, predates spec 3.6.0 and fails with
+  `invalid field name: name=Ada`. Check the version of the decoder at the
+  other end.
+* **JS values are normalised like `JSON.stringify`.** `encode(value)`
+  serialises with `JSON.stringify` semantics, the host-value normalisation
+  that SPEC §2.3.2 allows: `undefined` and functions are omitted, `NaN` and
+  `±Infinity` become null, array holes become null, `toJSON` is honoured
+  (so a `Date` becomes its ISO string), and a `Map` or `Set` becomes `{}`.
+  Normalise such values yourself if they matter. For exact key order
+  (numeric-looking keys), encode JSON text with `encodeJson`.
+* **Memory: streaming decode, released above 64 MiB.** Decoding writes a
+  document while it parses it, so it never holds the whole document as a
+  tree: it peaks at about 1.2–1.6 times its input plus its output (for
+  typical tables, about 3.5 times the GCF input; `decodeLazy` about 4.5
+  times). Encoding peaks at about 4.5 times the JSON input. Each codec has
+  one WebAssembly memory that grows to the largest payload it has handled,
+  and WebAssembly memory cannot shrink. By default, a call that leaves more
+  than 64 MiB reserved is followed by a fresh instance, switched in as soon
+  as the call returns, and the old memory is garbage collected. Decoding up
+  to about 15 MB of GCF, or encoding up to about 15 MB of JSON, stays below
+  the limit. Above it, the next large call is up to about 25% slower while
+  the memory is requested again; if you handle such payloads continuously,
+  raise the limit with `init(undefined, { maxRetainedMemory: 512 << 20 })`
+  (bytes) or pass `Infinity` to keep the memory. `codec.memoryBytes`
+  reports the current size and `await codec.recycle()` releases it on
+  demand. The limit bounds what stays reserved between calls, not the peak
+  during a call.
+* **Streaming encoders run in JavaScript** (see above).
+
 ## CLI
 
 ```sh

package/dist/cli.js

@@ -16,6 +16,7 @@ class GcfError extends Error {
     this.line = line;
   }
 }
+var DEFAULT_MAX_RETAINED_MEMORY = 64 * 1024 * 1024;
 var utf8 = new TextEncoder;
 var fromUtf8 = new TextDecoder;
 function isPlainGraph(text) {
@@ -153,13 +154,35 @@ function parseLargeInts(text, mode) {
 }
 
 class GcfCodec {
-  exports;
-  constructor(exports) {
-    this.exports = exports;
-  }
-  static async instantiate(wasm) {
-    const instance = wasm instanceof WebAssembly.Module ? await WebAssembly.instantiate(wasm, {}) : (await WebAssembly.instantiate(wasm, {})).instance;
-    return new GcfCodec(instance.exports);
+  x;
+  module;
+  maxRetained;
+  pending;
+  constructor(module, exports, opts) {
+    this.module = module;
+    this.x = exports;
+    const max = opts.maxRetainedMemory ?? DEFAULT_MAX_RETAINED_MEMORY;
+    if (!(max > 0))
+      throw new RangeError(`maxRetainedMemory must be a positive number of bytes or Infinity, got ${max}`);
+    this.maxRetained = max;
+  }
+  static async instantiate(wasm, opts = {}) {
+    const module = wasm instanceof WebAssembly.Module ? wasm : await WebAssembly.compile(wasm);
+    const instance = await WebAssembly.instantiate(module, {});
+    return new GcfCodec(module, instance.exports, opts);
+  }
+  get exports() {
+    return this.x;
+  }
+  get memoryBytes() {
+    return this.x.memory.buffer.byteLength;
+  }
+  recycle() {
+    this.pending ??= WebAssembly.instantiate(this.module, {}).then((instance) => {
+      this.x = instance.exports;
+      this.pending = undefined;
+    });
+    return this.pending;
   }
   load(input) {
     const x = this.exports;
@@ -172,7 +195,12 @@ class GcfCodec {
     const ptr = x.gcf_input_alloc(cap);
     return utf8.encodeInto(input, new Uint8Array(x.memory.buffer, ptr, cap)).written;
   }
+  releaseIfLarge() {
+    if (!this.pending && this.x.memory.buffer.byteLength > this.maxRetained)
+      this.recycle();
+  }
   output(status) {
+    this.releaseIfLarge();
     const x = this.exports;
     const text = (p, n) => fromUtf8.decode(new Uint8Array(x.memory.buffer, p, n));
     if (status !== 0) {
@@ -181,6 +209,7 @@ class GcfCodec {
     return text(x.gcf_output_ptr(), x.gcf_output_len());
   }
   outputBytes(status, view) {
+    this.releaseIfLarge();
     if (status !== 0)
       this.output(status);
     const x = this.exports;
@@ -682,6 +711,7 @@ function main(argv, gcf) {
   }
 }
 // src/index.ts
+var bundled;
 var shared;
 async function wasmBytes(source) {
   if (source instanceof URL || typeof source === "string") {
@@ -697,15 +727,18 @@ async function wasmBytes(source) {
     throw new Error(`failed to load gcf.wasm: HTTP ${res.status}`);
   return res.arrayBuffer();
 }
-function init(source) {
+function init(source, options) {
   if (source === undefined) {
-    shared ??= wasmBytes(new URL("./gcf.wasm", import.meta.url)).then((b) => GcfCodec.instantiate(b));
+    bundled ??= wasmBytes(new URL("./gcf.wasm", import.meta.url)).then((b) => WebAssembly.compile(b));
+    if (options !== undefined)
+      return bundled.then((m) => GcfCodec.instantiate(m, options));
+    shared ??= bundled.then((m) => GcfCodec.instantiate(m));
     return shared;
   }
   if (source instanceof WebAssembly.Module || source instanceof ArrayBuffer || ArrayBuffer.isView(source)) {
-    return GcfCodec.instantiate(source);
+    return GcfCodec.instantiate(source, options);
   }
-  return wasmBytes(source).then((b) => GcfCodec.instantiate(b));
+  return wasmBytes(source).then((b) => GcfCodec.instantiate(b, options));
 }
 
 // src/cli-npm.ts

package/dist/host.d.ts

@@ -28,6 +28,28 @@ export interface BytesOptions {
      */
     view?: boolean;
 }
+/** Default `maxRetainedMemory`: 64 MiB. */
+export declare const DEFAULT_MAX_RETAINED_MEMORY: number;
+export interface CodecOptions {
+    /**
+     * Bytes of WebAssembly memory a codec may keep reserved between calls.
+     * A codec's memory grows to the largest payload it has handled and
+     * WebAssembly memory cannot shrink, so when a call leaves more than this,
+     * the codec prepares a fresh instance in the background and switches to
+     * it as soon as the call has returned (asynchronously, never during a
+     * call); the old memory is then garbage collected. Calls can still use
+     * more while they run: this bounds what stays reserved afterwards, not
+     * the peak.
+     *
+     * Default: 64 MiB (`DEFAULT_MAX_RETAINED_MEMORY`), which decoding up to
+     * about 15 MB of GCF, or encoding up to about 15 MB of JSON, does not
+     * reach. Above it, the first large call on the fresh instance is up to
+     * about 25% slower while the memory is requested again, so if you handle
+     * such payloads continuously, raise the limit or pass `Infinity` to keep
+     * the memory.
+     */
+    maxRetainedMemory?: number;
+}
 export interface GraphSymbol {
     qualifiedName: string;
     kind: string;
@@ -135,11 +157,31 @@ type Columns = {
     references?: number[];
 };
 export declare class GcfCodec {
-    readonly exports: Exports;
+    private x;
+    private readonly module;
+    private readonly maxRetained;
+    /** A fresh instance being prepared; it replaces the current one when ready. */
+    private pending;
     private constructor();
-    static instantiate(wasm: BufferSource | WebAssembly.Module): Promise<GcfCodec>;
+    static instantiate(wasm: BufferSource | WebAssembly.Module, opts?: CodecOptions): Promise<GcfCodec>;
+    /** The current instance's exports (the raw ABI, docs/WASM_ABI.md). */
+    get exports(): Exports;
+    /** Bytes of WebAssembly memory the codec currently holds. */
+    get memoryBytes(): number;
+    /**
+     * Replace the instance with a fresh one, releasing the memory it holds
+     * (see `maxRetainedMemory`, which does this automatically). Results of
+     * earlier calls stay valid, including `view: true` byte views.
+     */
+    recycle(): Promise<void>;
     /** Copy the input into the engine's arena and return its byte length. */
     private load;
+    /**
+     * Every call ends by reading its result through output() or outputBytes().
+     * When the call left more memory than `maxRetainedMemory`, a fresh
+     * instance is prepared; it takes over once the call has returned.
+     */
+    private releaseIfLarge;
     private output;
     /** Raw output bytes: an owned copy, or a view valid until the next call. */
     private outputBytes;

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 export * from "./host.js";
-import { GcfCodec } from "./host.js";
+import { type CodecOptions, GcfCodec } from "./host.js";
 export type WasmSource = BufferSource | WebAssembly.Module | URL | string | Response | Promise<Response>;
 /**
  * Create a codec. Without arguments, returns a shared instance backed by the
- * `gcf.wasm` shipped with this package (loaded once). Each codec owns its
- * own WebAssembly memory; create more than one only for parallel use.
+ * `gcf.wasm` shipped with this package (loaded and compiled once). With
+ * `options` (e.g. `init(undefined, { maxRetainedMemory: 512 << 20 })`), returns
+ * a new codec from the same compiled module. Each codec owns its own
+ * WebAssembly memory; create more than one only for parallel use or
+ * different options.
  */
-export declare function init(source?: WasmSource): Promise<GcfCodec>;
+export declare function init(source?: WasmSource, options?: CodecOptions): Promise<GcfCodec>;

package/dist/index.js

@@ -12,6 +12,7 @@ class GcfError extends Error {
   }
 }
 var GcfDecodeError = GcfError;
+var DEFAULT_MAX_RETAINED_MEMORY = 64 * 1024 * 1024;
 var utf8 = new TextEncoder;
 var fromUtf8 = new TextDecoder;
 function isPlainGraph(text) {
@@ -149,13 +150,35 @@ function parseLargeInts(text, mode) {
 }
 
 class GcfCodec {
-  exports;
-  constructor(exports) {
-    this.exports = exports;
-  }
-  static async instantiate(wasm) {
-    const instance = wasm instanceof WebAssembly.Module ? await WebAssembly.instantiate(wasm, {}) : (await WebAssembly.instantiate(wasm, {})).instance;
-    return new GcfCodec(instance.exports);
+  x;
+  module;
+  maxRetained;
+  pending;
+  constructor(module, exports, opts) {
+    this.module = module;
+    this.x = exports;
+    const max = opts.maxRetainedMemory ?? DEFAULT_MAX_RETAINED_MEMORY;
+    if (!(max > 0))
+      throw new RangeError(`maxRetainedMemory must be a positive number of bytes or Infinity, got ${max}`);
+    this.maxRetained = max;
+  }
+  static async instantiate(wasm, opts = {}) {
+    const module = wasm instanceof WebAssembly.Module ? wasm : await WebAssembly.compile(wasm);
+    const instance = await WebAssembly.instantiate(module, {});
+    return new GcfCodec(module, instance.exports, opts);
+  }
+  get exports() {
+    return this.x;
+  }
+  get memoryBytes() {
+    return this.x.memory.buffer.byteLength;
+  }
+  recycle() {
+    this.pending ??= WebAssembly.instantiate(this.module, {}).then((instance) => {
+      this.x = instance.exports;
+      this.pending = undefined;
+    });
+    return this.pending;
   }
   load(input) {
     const x = this.exports;
@@ -168,7 +191,12 @@ class GcfCodec {
     const ptr = x.gcf_input_alloc(cap);
     return utf8.encodeInto(input, new Uint8Array(x.memory.buffer, ptr, cap)).written;
   }
+  releaseIfLarge() {
+    if (!this.pending && this.x.memory.buffer.byteLength > this.maxRetained)
+      this.recycle();
+  }
   output(status) {
+    this.releaseIfLarge();
     const x = this.exports;
     const text = (p, n) => fromUtf8.decode(new Uint8Array(x.memory.buffer, p, n));
     if (status !== 0) {
@@ -177,6 +205,7 @@ class GcfCodec {
     return text(x.gcf_output_ptr(), x.gcf_output_len());
   }
   outputBytes(status, view) {
+    this.releaseIfLarge();
     if (status !== 0)
       this.output(status);
     const x = this.exports;
@@ -960,6 +989,7 @@ class GenericStreamEncoder {
   }
 }
 // src/index.ts
+var bundled;
 var shared;
 async function wasmBytes(source) {
   if (source instanceof URL || typeof source === "string") {
@@ -975,17 +1005,21 @@ async function wasmBytes(source) {
     throw new Error(`failed to load gcf.wasm: HTTP ${res.status}`);
   return res.arrayBuffer();
 }
-function init(source) {
+function init(source, options) {
   if (source === undefined) {
-    shared ??= wasmBytes(new URL("./gcf.wasm", import.meta.url)).then((b) => GcfCodec.instantiate(b));
+    bundled ??= wasmBytes(new URL("./gcf.wasm", import.meta.url)).then((b) => WebAssembly.compile(b));
+    if (options !== undefined)
+      return bundled.then((m) => GcfCodec.instantiate(m, options));
+    shared ??= bundled.then((m) => GcfCodec.instantiate(m));
     return shared;
   }
   if (source instanceof WebAssembly.Module || source instanceof ArrayBuffer || ArrayBuffer.isView(source)) {
-    return GcfCodec.instantiate(source);
+    return GcfCodec.instantiate(source, options);
   }
-  return wasmBytes(source).then((b) => GcfCodec.instantiate(b));
+  return wasmBytes(source).then((b) => GcfCodec.instantiate(b, options));
 }
 export {
+  DEFAULT_MAX_RETAINED_MEMORY,
   DEFAULT_REANCHOR_N,
   GcfCodec,
   GcfDecodeError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@felixdrp/gcf-wasm",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Fast, strict codec for the Graph Compact Format (GCF v3.6.0): an 88 KB WebAssembly SIMD engine written by hand in WAT, with a zero-dependency JS API for Node, Bun, Deno, browsers and edge runtimes.",
   "keywords": ["gcf", "graph-compact-format", "llm", "tokens", "token-efficient", "serialization", "json-alternative", "mcp", "webassembly", "wasm", "simd", "wat"],
   "license": "Apache-2.0",