Recurram (JS)

JavaScript/TypeScript bindings for recurram-rust with two backends:

• Node.js: N-API (recurram-napi)
• Browser/JS runtime: WebAssembly (recurram-wasm)

Integers decode as bigint by default (i64/u64 safe handling).

Requirements

• Node.js 24+
• Rust stable
• wasm-pack for WASM builds

Build

pnpm install
pnpm build

Build steps:

1. Build N-API addon (native/recurram_napi.node)
2. Build WASM package (wasm/pkg/*)
3. Build TypeScript output (dist/*)

Formatting

pnpm format
pnpm format:check

Test

pnpm test

What it validates:

• Rust bridge tests (test:rust)
• Node API tests (test:node) covering init, encode, decode, schema, batch, and session APIs
• TypeScript API usage against built output

Usage (Node)

import {
  init,
  encode,
  decode,
  createSessionEncoder,
  toTransportJson,
  encodeTransportJson,
  type RecurramValue,
} from "recurram";

await init({ prefer: "napi" });

const value: RecurramValue = {
  id: 1001n,
  name: "alice",
  active: true,
};

const bytes = encode(value);
const roundtrip = decode(bytes);

const session = createSessionEncoder();
const first = session.encode(value);
const patch = session.encodePatch({ ...value, name: "alicia" });

const prepared = toTransportJson(value);
const fastest = encodeTransportJson(prepared);

High-throughput transport JSON APIs

For hot paths where you can prepare payloads ahead of time, use transport JSON APIs to reduce JS-side conversion overhead:

• toTransportJson(value) / fromTransportJson(json)
• toTransportJsonBatch(values)
• encodeTransportJson(valueJson) / decodeToTransportJson(bytes)
• encodeBatchTransportJson(valuesJson)

SessionEncoder also supports raw methods:

• encodeTransportJson(valueJson)
• encodeBatchTransportJson(valuesJson)
• encodePatchTransportJson(valueJson)
• encodeMicroBatchTransportJson(valuesJson)

Usage (Browser)

import { init, encode, decode } from "recurram";

await init({ prefer: "wasm" });

const bytes = encode({ id: 1n, role: "admin" });
const value = decode(bytes);

If you want to pass a custom WASM source, use wasmInput:

await init({ prefer: "wasm", wasmInput: "/assets/recurram_wasm_bg.wasm" });

TypeScript types

Main exported types:

• RecurramValue
• Schema, SchemaField
• SessionOptions

RecurramValue includes bigint and Uint8Array support:

type RecurramValue =
  | null
  | boolean
  | number
  | bigint
  | string
  | Uint8Array
  | RecurramValue[]
  | { [key: string]: RecurramValue };

Publish to npm

The package is configured for npm publish and ships build artifacts from dist/, native/, and wasm/pkg/.

Local dry run:

pnpm build
pnpm pack

GitHub Actions publish:

1. Add repository secret NPM_TOKEN.
2. Bump version in package.json.
3. Create and push matching tag v<version>.

Example:

git tag v0.1.0
git push origin v0.1.0

The workflow .github/workflows/publish-npm.yml verifies tag/version match and then runs pnpm publish.

License

This project is licensed under the MIT License - see the LICENSE file for details.