@temporal-cortex/toon 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# @temporal-cortex/toon
+
+WASM-powered TOON (Token-Oriented Object Notation) encoder/decoder for Node.js.
+
+This package wraps the Rust `temporal-cortex-toon` library via WebAssembly, providing near-native performance for TOON encoding and decoding in JavaScript/TypeScript environments.
+
+## Installation
+
+```bash
+npm install @temporal-cortex/toon
+# or
+pnpm add @temporal-cortex/toon
+```
+
+## Usage
+
+```typescript
+import { encode, decode } from "@temporal-cortex/toon";
+
+// JSON string → TOON string
+const toon = encode('{"name":"Alice","scores":[95,87,92]}');
+console.log(toon);
+// name: Alice
+// scores[3]: 95,87,92
+
+// TOON string → JSON string (perfect roundtrip)
+const json = decode(toon);
+console.log(json);
+// {"name":"Alice","scores":[95,87,92]}
+```
+
+## API
+
+### `encode(json: string): string`
+
+Converts a valid JSON string into TOON format. Throws if the input is not valid JSON.
+
+### `decode(toon: string): string`
+
+Converts a TOON string back into compact JSON. Throws if the input is not valid TOON.
+
+## Build from Source
+
+This package requires the WASM artifacts to be built from the Rust crate first:
+
+```bash
+# From the monorepo root:
+
+# 1. Build the WASM binary
+cargo build -p temporal-cortex-toon-wasm --target wasm32-unknown-unknown --release
+
+# 2. Generate Node.js bindings
+wasm-bindgen --target nodejs \
+  --out-dir packages/temporal-cortex-toon-js/wasm/ \
+  target/wasm32-unknown-unknown/release/toon_wasm.wasm
+
+# 3. Rename for ESM/CJS compatibility
+mv packages/temporal-cortex-toon-js/wasm/toon_wasm.js packages/temporal-cortex-toon-js/wasm/toon_wasm.cjs
+
+# 4. Build TypeScript
+pnpm --filter @temporal-cortex/toon build
+
+# 5. Run tests
+pnpm --filter @temporal-cortex/toon test
+```
+
+## Architecture
+
+```
+src/index.ts          ← Public API (encode/decode), loads WASM via createRequire
+wasm/toon_wasm.cjs    ← wasm-bindgen generated CommonJS bindings
+wasm/toon_wasm.wasm   ← Compiled WASM binary from temporal-cortex-toon (Rust)
+wasm/toon_wasm.d.ts   ← TypeScript type declarations for WASM exports
+```
+
+The package uses `createRequire(import.meta.url)` to load the CommonJS WASM bindings from an ESM context. This bridges the module system mismatch since `wasm-bindgen --target nodejs` generates CommonJS but the package uses `"type": "module"`.
+
+## Testing
+
+26 tests covering encode, decode, and roundtrip operations:
+
+```bash
+pnpm --filter @temporal-cortex/toon test
+```
+
+## License
+
+MIT OR Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Encode a JSON string into TOON format.
+ * @param json - A valid JSON string
+ * @returns The TOON-encoded string
+ */
+export declare function encode(json: string): string;
+/**
+ * Decode a TOON string back into JSON format.
+ * @param toon - A valid TOON string
+ * @returns The JSON string
+ */
+export declare function decode(toon: string): string;

package/dist/index.js

@@ -0,0 +1,28 @@
+// @temporal-cortex/toon — WASM-powered TOON encoder/decoder for Node.js
+//
+// This module loads the WASM binary compiled from the temporal-cortex-toon-wasm Rust crate.
+// The WASM bindings are generated by wasm-bindgen as CommonJS (.cjs), but this
+// package uses ESM ("type": "module" in package.json). We bridge the two module
+// systems using Node's createRequire().
+//
+// Build chain: temporal-cortex-toon (Rust) → temporal-cortex-toon-wasm (wasm-bindgen) → temporal-cortex-toon-js (this wrapper)
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+// Load the WASM-generated Node.js bindings (.cjs for CommonJS/ESM compat)
+const wasm = require("../wasm/toon_wasm.cjs");
+/**
+ * Encode a JSON string into TOON format.
+ * @param json - A valid JSON string
+ * @returns The TOON-encoded string
+ */
+export function encode(json) {
+    return wasm.encode(json);
+}
+/**
+ * Decode a TOON string back into JSON format.
+ * @param toon - A valid TOON string
+ * @returns The JSON string
+ */
+export function decode(toon) {
+    return wasm.decode(toon);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@temporal-cortex/toon",
+  "version": "0.1.0",
+  "description": "TOON (Token-Oriented Object Notation) encoder/decoder — compact JSON for LLMs",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "wasm"
+  ],
+  "keywords": [
+    "toon",
+    "json",
+    "llm",
+    "compression",
+    "wasm"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "author": "Billy Lui",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/billylui/temporal-cortex-core.git",
+    "directory": "packages/temporal-cortex-toon-js"
+  },
+  "homepage": "https://github.com/billylui/temporal-cortex-core",
+  "bugs": {
+    "url": "https://github.com/billylui/temporal-cortex-core/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5",
+    "vitest": "^3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/wasm/toon_wasm.cjs

@@ -0,0 +1,198 @@
+/* @ts-self-types="./toon_wasm.d.ts" */
+
+/**
+ * Decode a TOON string back into compact JSON format.
+ *
+ * Returns the JSON string, or throws a JS error if the input is not valid TOON.
+ * @param {string} toon
+ * @returns {string}
+ */
+function decode(toon) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(toon, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.decode(retptr, ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr2 = r0;
+        var len2 = r1;
+        if (r3) {
+            ptr2 = 0; len2 = 0;
+            throw takeObject(r2);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred3_0, deferred3_1, 1);
+    }
+}
+exports.decode = decode;
+
+/**
+ * Encode a JSON string into TOON v3.0 format.
+ *
+ * Returns the TOON string, or throws a JS error if the input is not valid JSON.
+ * @param {string} json
+ * @returns {string}
+ */
+function encode(json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.encode(retptr, ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr2 = r0;
+        var len2 = r1;
+        if (r3) {
+            ptr2 = 0; len2 = 0;
+            throw takeObject(r2);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred3_0, deferred3_1, 1);
+    }
+}
+exports.encode = encode;
+
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbindgen_cast_0000000000000001: function(arg0, arg1) {
+            // Cast intrinsic for `Ref(String) -> Externref`.
+            const ret = getStringFromWasm0(arg0, arg1);
+            return addHeapObject(ret);
+        },
+    };
+    return {
+        __proto__: null,
+        "./toon_wasm_bg.js": import0,
+    };
+}
+
+function addHeapObject(obj) {
+    if (heap_next === heap.length) heap.push(heap.length + 1);
+    const idx = heap_next;
+    heap_next = heap[idx];
+
+    heap[idx] = obj;
+    return idx;
+}
+
+function dropObject(idx) {
+    if (idx < 132) return;
+    heap[idx] = heap_next;
+    heap_next = idx;
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function getObject(idx) { return heap[idx]; }
+
+let heap = new Array(128).fill(undefined);
+heap.push(undefined, null, true, false);
+
+let heap_next = heap.length;
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeObject(idx) {
+    const ret = getObject(idx);
+    dropObject(idx);
+    return ret;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+function decodeText(ptr, len) {
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+const wasmPath = `${__dirname}/toon_wasm_bg.wasm`;
+const wasmBytes = require('fs').readFileSync(wasmPath);
+const wasmModule = new WebAssembly.Module(wasmBytes);
+const wasm = new WebAssembly.Instance(wasmModule, __wbg_get_imports()).exports;

package/wasm/toon_wasm.d.ts

@@ -0,0 +1,16 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Decode a TOON string back into compact JSON format.
+ *
+ * Returns the JSON string, or throws a JS error if the input is not valid TOON.
+ */
+export function decode(toon: string): string;
+
+/**
+ * Encode a JSON string into TOON v3.0 format.
+ *
+ * Returns the TOON string, or throws a JS error if the input is not valid JSON.
+ */
+export function encode(json: string): string;

package/wasm/toon_wasm_bg.wasm.d.ts

@@ -0,0 +1,9 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const decode: (a: number, b: number, c: number) => void;
+export const encode: (a: number, b: number, c: number) => void;
+export const __wbindgen_add_to_stack_pointer: (a: number) => number;
+export const __wbindgen_export: (a: number, b: number) => number;
+export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_export3: (a: number, b: number, c: number) => void;