Teptris — the npm package v0.3.11

Installation

npm install teptris

The package is ESM-only ("type": "module", Node ≥ 20, browsers, bundlers). It ships the wasm binary, the JS wrapper and the type declarations — a single self-contained package, no postinstall, no native modules.

Usage

import { init } from "teptris";

const teptris = await init();

const doc = teptris.loads('title = "demo"\npi = 3.5\nat = 2026-10-09T12:00:00Z\n');
// => { title: "demo", pi: 3.5, at: "2026-10-09T12:00:00Z" }

teptris.dump(doc);      // canonical TOML (RFC 3339 strings re-enter as datetimes)
teptris.dumpJson(doc);  // natural JSON — the string a host hands to JSON consumers
teptris.engineVersion();

loads returns the natural-JSON view: real numbers, booleans, and RFC 3339 strings for datetimes; non-finite floats (nan/inf) become null. dump emits canonical TOML through the engine builder; dumpJsonemits the same tree as natural JSON. Errors carryline/column.

Descriptor plans

const plan = teptris.planBuild([
    "title",
    "tags",
    { name: "owner", rows: ["name", { name: "meta", kind: "raw" }] },
  ]);

const view = teptris.planWalk(plan, toml); // only planned keys
teptris.planFree(plan);

Compile a plan once, walk any number of documents: only the planned keys cross the wasm boundary — unplanned keys are never materialized. Rows: a string name is a scalar;kind: "collection" walks an array;kind: "raw" takes the untouched subtree;rows walks a nested table. Typed asPlanRowSpec in the package.

Performance

Against the JS ecosystem’s parsers over the engine bench corpus: 2–4× @iarna/toml — the long-standing standard, which also rejects mixed-type arrays that are legal TOML 1.0 — and parity with smol-toml, the modern fast pure-JS parser: teptris wins the datetime-heavy shapes (1.5×) and deep tables; smol wins string-heavy inputs, where the wasm→JS bridge prices every string. The tier’s real edge is correctness: the full TOML 1.1 draft grammarwith the same parse/emit behavior as the native bindings.

Advanced instantiation

import { initApi } from "teptris";
import createModule from "teptris/dist/teptris.mjs";

// for bundlers with their own wasm loading
const api = initApi(await createModule({ locateFile: ... }));

Source — teptris-ts.