recurram 0.1.0

package/dist/runtime/types.d.ts

@@ -0,0 +1,35 @@
+export type RuntimeKind = "napi" | "wasm";
+export interface TransportValueObj {
+    t: string;
+    v?: unknown;
+}
+export interface RuntimeSessionEncoder {
+    encodeTransportJson(valueJson: string): Uint8Array;
+    encodeWithSchemaTransportJson(schemaJson: string, valueJson: string): Uint8Array;
+    encodeBatchTransportJson(valuesJson: string): Uint8Array;
+    encodePatchTransportJson(valueJson: string): Uint8Array;
+    encodeMicroBatchTransportJson(valuesJson: string): Uint8Array;
+    encodeDirect(value: TransportValueObj): Uint8Array;
+    encodeBatchDirect(values: TransportValueObj[]): Uint8Array;
+    encodePatchDirect(value: TransportValueObj): Uint8Array;
+    encodeMicroBatchDirect(values: TransportValueObj[]): Uint8Array;
+    encodeCompactJson(json: string): Uint8Array;
+    encodeBatchCompactJson(json: string): Uint8Array;
+    encodePatchCompactJson(json: string): Uint8Array;
+    encodeMicroBatchCompactJson(json: string): Uint8Array;
+    reset(): void;
+}
+export interface RuntimeBackend {
+    kind: RuntimeKind;
+    encodeTransportJson(valueJson: string): Uint8Array;
+    decodeToTransportJson(bytes: Uint8Array): string;
+    decodeToCompactJson(bytes: Uint8Array): string;
+    encodeWithSchemaTransportJson(schemaJson: string, valueJson: string): Uint8Array;
+    encodeBatchTransportJson(valuesJson: string): Uint8Array;
+    encodeDirect(value: TransportValueObj): Uint8Array;
+    decodeDirect(bytes: Uint8Array): TransportValueObj;
+    encodeBatchDirect(values: TransportValueObj[]): Uint8Array;
+    encodeCompactJson(json: string): Uint8Array;
+    encodeBatchCompactJson(json: string): Uint8Array;
+    createSessionEncoder(optionsJson?: string): RuntimeSessionEncoder;
+}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/wasm-backend.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeBackend } from "./types.js";
+export declare function loadWasmBackend(wasmInput?: unknown): Promise<RuntimeBackend>;

package/dist/runtime/wasm-backend.js

@@ -0,0 +1,44 @@
+export async function loadWasmBackend(wasmInput) {
+    const moduleUrl = new URL("../../wasm/pkg/recurram_wasm.js", import.meta.url);
+    const wasm = (await import(moduleUrl.href));
+    await wasm.default(wasmInput);
+    return {
+        kind: "wasm",
+        encodeTransportJson: (valueJson) => wasm.encodeTransportJson(valueJson),
+        decodeToTransportJson: (bytes) => wasm.decodeToTransportJson(bytes),
+        decodeToCompactJson: (bytes) => wasm.decodeToTransportJson(bytes), // WASM fallback
+        encodeWithSchemaTransportJson: (schemaJson, valueJson) => wasm.encodeWithSchemaTransportJson(schemaJson, valueJson),
+        encodeBatchTransportJson: (valuesJson) => wasm.encodeBatchTransportJson(valuesJson),
+        // WASM fallback: serialize to JSON then use JSON API
+        encodeDirect: (value) => wasm.encodeTransportJson(JSON.stringify(value)),
+        decodeDirect: (bytes) => JSON.parse(wasm.decodeToTransportJson(bytes)),
+        encodeBatchDirect: (values) => wasm.encodeBatchTransportJson(JSON.stringify(values)),
+        // WASM fallback: compact not available, fall through to transport JSON
+        encodeCompactJson: (json) => wasm.encodeTransportJson(json),
+        encodeBatchCompactJson: (json) => wasm.encodeBatchTransportJson(json),
+        createSessionEncoder: (optionsJson) => {
+            const inner = wasm.createSessionEncoder(optionsJson);
+            return wrapSessionEncoder(inner);
+        },
+    };
+}
+function wrapSessionEncoder(inner) {
+    return {
+        encodeTransportJson: (valueJson) => inner.encodeTransportJson(valueJson),
+        encodeWithSchemaTransportJson: (schemaJson, valueJson) => inner.encodeWithSchemaTransportJson(schemaJson, valueJson),
+        encodeBatchTransportJson: (valuesJson) => inner.encodeBatchTransportJson(valuesJson),
+        encodePatchTransportJson: (valueJson) => inner.encodePatchTransportJson(valueJson),
+        encodeMicroBatchTransportJson: (valuesJson) => inner.encodeMicroBatchTransportJson(valuesJson),
+        // WASM fallback: serialize to JSON then use JSON API
+        encodeDirect: (value) => inner.encodeTransportJson(JSON.stringify(value)),
+        encodeBatchDirect: (values) => inner.encodeBatchTransportJson(JSON.stringify(values)),
+        encodePatchDirect: (value) => inner.encodePatchTransportJson(JSON.stringify(value)),
+        encodeMicroBatchDirect: (values) => inner.encodeMicroBatchTransportJson(JSON.stringify(values)),
+        // WASM fallback: compact not available, fall through to transport JSON
+        encodeCompactJson: (json) => inner.encodeTransportJson(json),
+        encodeBatchCompactJson: (json) => inner.encodeBatchTransportJson(json),
+        encodePatchCompactJson: (json) => inner.encodePatchTransportJson(json),
+        encodeMicroBatchCompactJson: (json) => inner.encodeMicroBatchTransportJson(json),
+        reset: () => inner.reset(),
+    };
+}

package/dist/transport.d.ts

@@ -0,0 +1,39 @@
+import type { RecurramValue, Schema, SessionOptions } from "./types.js";
+export type TransportValue = {
+    t: "null";
+} | {
+    t: "bool";
+    v: boolean;
+} | {
+    t: "i64";
+    v: string;
+} | {
+    t: "u64";
+    v: string;
+} | {
+    t: "f64";
+    v: number;
+} | {
+    t: "string";
+    v: string;
+} | {
+    t: "binary";
+    v: string;
+} | {
+    t: "array";
+    v: TransportValue[];
+} | {
+    t: "map";
+    v: Array<[string, TransportValue]>;
+};
+export declare function serializeValue(value: RecurramValue): string;
+export declare function deserializeValue(json: string): RecurramValue;
+export declare function serializeValues(values: RecurramValue[]): string;
+export declare function serializeSchema(schema: Schema): string;
+export declare function serializeSessionOptions(options?: SessionOptions): string;
+export declare function toTransportValue(value: RecurramValue): TransportValue;
+export declare function toTransportValues(values: RecurramValue[]): TransportValue[];
+export declare function fromTransportValue(value: TransportValue): RecurramValue;
+export declare function serializeCompact(value: RecurramValue): string;
+export declare function deserializeCompact(json: string): RecurramValue;
+export declare function serializeCompactBatch(values: RecurramValue[]): string;

package/dist/transport.js

@@ -0,0 +1,341 @@
+const MAX_U64 = (1n << 64n) - 1n;
+const MIN_I64 = -(1n << 63n);
+const MAX_I64 = (1n << 63n) - 1n;
+export function serializeValue(value) {
+    return JSON.stringify(toTransportValue(value));
+}
+export function deserializeValue(json) {
+    const parsed = JSON.parse(json);
+    return fromTransportValue(parsed);
+}
+export function serializeValues(values) {
+    const out = new Array(values.length);
+    for (let index = 0; index < values.length; index += 1) {
+        out[index] = toTransportValue(values[index]);
+    }
+    return JSON.stringify(out);
+}
+export function serializeSchema(schema) {
+    const fields = new Array(schema.fields.length);
+    for (let index = 0; index < schema.fields.length; index += 1) {
+        const field = schema.fields[index];
+        const out = {
+            number: toTransportInteger(field.number, "field.number", true),
+            name: field.name,
+            logicalType: field.logicalType,
+            required: field.required,
+        };
+        if (field.defaultValue !== undefined) {
+            out.defaultValue = toTransportValue(field.defaultValue);
+        }
+        if (field.min !== undefined) {
+            out.min = toTransportInteger(field.min, "field.min", false);
+        }
+        if (field.max !== undefined) {
+            out.max = toTransportInteger(field.max, "field.max", false);
+        }
+        if (field.enumValues !== undefined) {
+            out.enumValues = field.enumValues;
+        }
+        fields[index] = out;
+    }
+    const payload = {
+        schemaId: toTransportInteger(schema.schemaId, "schemaId", true),
+        name: schema.name,
+        fields,
+    };
+    return JSON.stringify(payload);
+}
+export function serializeSessionOptions(options = {}) {
+    const payload = {};
+    if (options.maxBaseSnapshots !== undefined) {
+        if (!Number.isInteger(options.maxBaseSnapshots) ||
+            options.maxBaseSnapshots < 0) {
+            throw new Error("maxBaseSnapshots must be a non-negative integer");
+        }
+        payload.maxBaseSnapshots = options.maxBaseSnapshots;
+    }
+    if (options.enableStatePatch !== undefined) {
+        payload.enableStatePatch = options.enableStatePatch;
+    }
+    if (options.enableTemplateBatch !== undefined) {
+        payload.enableTemplateBatch = options.enableTemplateBatch;
+    }
+    if (options.enableTrainedDictionary !== undefined) {
+        payload.enableTrainedDictionary = options.enableTrainedDictionary;
+    }
+    if (options.unknownReferencePolicy !== undefined) {
+        payload.unknownReferencePolicy = options.unknownReferencePolicy;
+    }
+    return JSON.stringify(payload);
+}
+export function toTransportValue(value) {
+    if (value === null) {
+        return { t: "null" };
+    }
+    if (typeof value === "boolean") {
+        return { t: "bool", v: value };
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("number values must be finite");
+        }
+        if (Number.isInteger(value)) {
+            if (!Number.isSafeInteger(value)) {
+                throw new Error("unsafe integer number detected; use bigint for 64-bit integers");
+            }
+            return value >= 0
+                ? { t: "u64", v: String(value) }
+                : { t: "i64", v: String(value) };
+        }
+        return { t: "f64", v: value };
+    }
+    if (typeof value === "bigint") {
+        if (value >= 0n) {
+            if (value > MAX_U64) {
+                throw new Error("u64 overflow");
+            }
+            return { t: "u64", v: value.toString() };
+        }
+        if (value < MIN_I64 || value > MAX_I64) {
+            throw new Error("i64 overflow");
+        }
+        return { t: "i64", v: value.toString() };
+    }
+    if (typeof value === "string") {
+        return { t: "string", v: value };
+    }
+    if (value instanceof Uint8Array) {
+        return { t: "binary", v: toBase64(value) };
+    }
+    if (Array.isArray(value)) {
+        const length = value.length;
+        const out = new Array(length);
+        for (let index = 0; index < length; index += 1) {
+            out[index] = toTransportValue(value[index]);
+        }
+        return { t: "array", v: out };
+    }
+    if (typeof value !== "object" || value === null) {
+        throw new Error("unsupported value type");
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error("unsupported value type");
+    }
+    const entries = [];
+    const objectValue = value;
+    for (const key in objectValue) {
+        entries.push([key, toTransportValue(objectValue[key])]);
+    }
+    return { t: "map", v: entries };
+}
+export function toTransportValues(values) {
+    const out = new Array(values.length);
+    for (let index = 0; index < values.length; index += 1) {
+        out[index] = toTransportValue(values[index]);
+    }
+    return out;
+}
+export function fromTransportValue(value) {
+    switch (value.t) {
+        case "null":
+            return null;
+        case "bool":
+            return value.v;
+        case "i64":
+            return BigInt(value.v);
+        case "u64":
+            return BigInt(value.v);
+        case "f64":
+            return value.v;
+        case "string":
+            return value.v;
+        case "binary":
+            return fromBase64(value.v);
+        case "array": {
+            const length = value.v.length;
+            const out = new Array(length);
+            for (let index = 0; index < length; index += 1) {
+                out[index] = fromTransportValue(value.v[index]);
+            }
+            return out;
+        }
+        case "map": {
+            const out = {};
+            const length = value.v.length;
+            for (let index = 0; index < length; index += 1) {
+                const entry = value.v[index];
+                out[entry[0]] = fromTransportValue(entry[1]);
+            }
+            return out;
+        }
+        default:
+            throw new Error("unknown transport value kind");
+    }
+}
+function toTransportInteger(value, fieldName, unsigned) {
+    if (typeof value === "number") {
+        if (!Number.isInteger(value) || !Number.isSafeInteger(value)) {
+            throw new Error(`${fieldName} must be a safe integer number or bigint`);
+        }
+        if (unsigned && value < 0) {
+            throw new Error(`${fieldName} must be unsigned`);
+        }
+        return value;
+    }
+    if (unsigned) {
+        if (value < 0n || value > MAX_U64) {
+            throw new Error(`${fieldName} must fit u64`);
+        }
+        return value.toString();
+    }
+    if (value < MIN_I64 || value > MAX_I64) {
+        throw new Error(`${fieldName} must fit i64`);
+    }
+    return value.toString();
+}
+function toBase64(bytes) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+    }
+    if (typeof btoa === "function") {
+        let binary = "";
+        for (let index = 0; index < bytes.length; index += 1) {
+            binary += String.fromCharCode(bytes[index]);
+        }
+        return btoa(binary);
+    }
+    throw new Error("base64 encoding is not available in this runtime");
+}
+function fromBase64(encoded) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(encoded, "base64");
+    }
+    if (typeof atob === "function") {
+        const binary = atob(encoded);
+        const bytes = new Uint8Array(binary.length);
+        for (let index = 0; index < binary.length; index += 1) {
+            bytes[index] = binary.charCodeAt(index);
+        }
+        return bytes;
+    }
+    throw new Error("base64 decoding is not available in this runtime");
+}
+export function serializeCompact(value) {
+    return JSON.stringify(toCompactValue(value));
+}
+export function deserializeCompact(json) {
+    const parsed = JSON.parse(json);
+    return fromCompactValue(parsed);
+}
+export function serializeCompactBatch(values) {
+    const out = new Array(values.length);
+    for (let index = 0; index < values.length; index += 1) {
+        out[index] = toCompactValue(values[index]);
+    }
+    return JSON.stringify(out);
+}
+function toCompactValue(value) {
+    if (value === null) {
+        return [0];
+    }
+    if (typeof value === "boolean") {
+        return [1, value];
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("number values must be finite");
+        }
+        if (Number.isInteger(value)) {
+            if (!Number.isSafeInteger(value)) {
+                throw new Error("unsafe integer number detected; use bigint for 64-bit integers");
+            }
+            return value >= 0 ? [3, String(value)] : [2, String(value)];
+        }
+        return [4, value];
+    }
+    if (typeof value === "bigint") {
+        if (value >= 0n) {
+            if (value > MAX_U64) {
+                throw new Error("u64 overflow");
+            }
+            return [3, value.toString()];
+        }
+        if (value < MIN_I64 || value > MAX_I64) {
+            throw new Error("i64 overflow");
+        }
+        return [2, value.toString()];
+    }
+    if (typeof value === "string") {
+        return [5, value];
+    }
+    if (value instanceof Uint8Array) {
+        return [6, toBase64(value)];
+    }
+    if (Array.isArray(value)) {
+        const length = value.length;
+        const out = new Array(length);
+        for (let index = 0; index < length; index += 1) {
+            out[index] = toCompactValue(value[index]);
+        }
+        return [7, out];
+    }
+    if (typeof value !== "object" || value === null) {
+        throw new Error("unsupported value type");
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error("unsupported value type");
+    }
+    // Map: flat array [key1, val1, key2, val2, ...]
+    const objectValue = value;
+    const keys = Object.keys(objectValue);
+    const flat = new Array(keys.length * 2);
+    for (let index = 0; index < keys.length; index += 1) {
+        flat[index * 2] = keys[index];
+        flat[index * 2 + 1] = toCompactValue(objectValue[keys[index]]);
+    }
+    return [8, flat];
+}
+function fromCompactValue(cv) {
+    const tag = cv[0];
+    switch (tag) {
+        case 0: // null
+            return null;
+        case 1: // bool
+            return cv[1];
+        case 2: // i64
+            return BigInt(cv[1]);
+        case 3: // u64
+            return BigInt(cv[1]);
+        case 4: // f64
+            return cv[1];
+        case 5: // string
+            return cv[1];
+        case 6: // binary
+            return fromBase64(cv[1]);
+        case 7: {
+            // array
+            const items = cv[1];
+            const length = items.length;
+            const out = new Array(length);
+            for (let index = 0; index < length; index += 1) {
+                out[index] = fromCompactValue(items[index]);
+            }
+            return out;
+        }
+        case 8: {
+            // map: flat array [key1, val1, key2, val2, ...]
+            const flat = cv[1];
+            const out = {};
+            const length = flat.length;
+            for (let index = 0; index < length; index += 2) {
+                out[flat[index]] = fromCompactValue(flat[index + 1]);
+            }
+            return out;
+        }
+        default:
+            throw new Error(`unknown compact tag: ${tag}`);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+export type RecurramValue = null | boolean | number | bigint | string | Uint8Array | RecurramValue[] | {
+    [key: string]: RecurramValue;
+};
+export interface SchemaField {
+    number: number | bigint;
+    name: string;
+    logicalType: string;
+    required: boolean;
+    defaultValue?: RecurramValue;
+    min?: number | bigint;
+    max?: number | bigint;
+    enumValues?: string[];
+}
+export interface Schema {
+    schemaId: number | bigint;
+    name: string;
+    fields: SchemaField[];
+}
+export type UnknownReferencePolicy = "failFast" | "statelessRetry";
+export interface SessionOptions {
+    maxBaseSnapshots?: number;
+    enableStatePatch?: boolean;
+    enableTemplateBatch?: boolean;
+    enableTrainedDictionary?: boolean;
+    unknownReferencePolicy?: UnknownReferencePolicy;
+}
+export interface InitOptions {
+    prefer?: "napi" | "wasm";
+    wasmInput?: unknown;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "recurram",
+  "version": "0.1.0",
+  "description": "Node.js and TypeScript implementation of a fast, compact binary wire format for modern data transport.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/recurram/recurram-js.git"
+  },
+  "homepage": "https://github.com/recurram/recurram-js#readme",
+  "bugs": {
+    "url": "https://github.com/recurram/recurram-js/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "native",
+    "wasm/pkg",
+    "crates",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "recurram",
+    "rust",
+    "napi",
+    "wasm",
+    "typescript"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.2"
+  },
+  "scripts": {
+    "build": "pnpm build:napi && pnpm build:wasm && pnpm build:ts",
+    "build:ts": "tsc -p tsconfig.json",
+    "build:napi": "cargo build --manifest-path Cargo.toml -p recurram-napi --release && node ./scripts/copy-napi.mjs",
+    "build:wasm": "wasm-pack build crates/recurram-wasm --target bundler --out-dir ../../wasm/pkg --out-name recurram_wasm --no-opt",
+    "format": "prettier --write \"{README.md,package.json,tsconfig.json,.github/workflows/*.yml,scripts/**/*.mjs,src/**/*.ts,tests/**/*.mjs}\"",
+    "format:check": "prettier --check \"{README.md,package.json,tsconfig.json,.github/workflows/*.yml,scripts/**/*.mjs,src/**/*.ts,tests/**/*.mjs}\"",
+    "typecheck": "tsc --noEmit",
+    "test:rust": "cargo test --manifest-path Cargo.toml -p recurram-bridge",
+    "test:node": "pnpm build:napi && pnpm build:ts && node --test --test-concurrency=1 \"tests/**/*.test.mjs\"",
+    "test": "pnpm test:rust && pnpm test:node",
+    "release:check": "node ./scripts/verify-tag-version.mjs",
+    "clean": "rimraf dist native wasm target"
+  }
+}

package/scripts/copy-napi.mjs

@@ -0,0 +1,27 @@
+import { mkdir, copyFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const root = path.resolve(__dirname, "..");
+const targetDir = path.join(root, "native");
+const targetFile = path.join(targetDir, "recurram_napi.node");
+
+const sourceFile = resolveSourceBinary(path.join(root, "target", "release"));
+
+await mkdir(targetDir, { recursive: true });
+await copyFile(sourceFile, targetFile);
+
+function resolveSourceBinary(releaseDir) {
+  if (process.platform === "darwin") {
+    return path.join(releaseDir, "librecurram_napi.dylib");
+  }
+  if (process.platform === "linux") {
+    return path.join(releaseDir, "librecurram_napi.so");
+  }
+  if (process.platform === "win32") {
+    return path.join(releaseDir, "recurram_napi.dll");
+  }
+  throw new Error(`unsupported platform: ${process.platform}`);
+}

package/scripts/verify-tag-version.mjs

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageJsonPath = path.resolve(__dirname, "..", "package.json");
+const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+
+const tag = process.env.GITHUB_REF_NAME || process.argv[2];
+if (!tag) {
+  throw new Error("tag is required (set GITHUB_REF_NAME or pass tag as arg)");
+}
+
+const normalizedTag = tag.startsWith("v") ? tag.slice(1) : tag;
+if (normalizedTag !== packageJson.version) {
+  throw new Error(
+    `tag/version mismatch: tag=${tag} package.json version=${packageJson.version}`,
+  );
+}