@tryengrave/core

Zero-dependency primitives shared across Engrave — branded IDs, a Result type, ULIDs, and RFC 8785 JSON canonicalization. No runtime dependencies, runs anywhere (Node, Bun, Deno, Cloudflare Workers, the browser).

npm install @tryengrave/core

What's inside

• Branded types — TenantId, LedgerId, StreamId, TxId, RunId, SpanId, ApiKeyId, Hash32. A raw string is never assignable to one, so you can't cross the streams by accident.
• Result<T, E> — errors as values (ok, err, map, andThen, unwrapOr, …) for the paths where exceptions are the wrong tool.
• ULIDs — lexicographically sortable, time-prefixed ids via an injectable factory (createUlidFactory) so tests stay deterministic.
• RFC 8785 JCS — canonicalize / canonicalBytes produce the exact byte sequence Engrave hashes. This is a spec, not JSON.stringify.

Usage

import { TenantId, ok, err, canonicalBytes, createUlidFactory } from "@tryengrave/core"

const tenant = TenantId("acme")            // branded — not just a string
const id = createUlidFactory()()           // deterministic when you inject the clock/rng

const bytes = canonicalBytes({ b: 1, a: 2 }) // RFC 8785 ordering, ready to hash

function parsePort(s: string) {
  const n = Number(s)
  return Number.isInteger(n) ? ok(n) : err("not an integer")
}

Determinism

The same inputs produce byte-identical output on any machine — that's the whole point. Clock and randomness are injected, never read ambiently, so hashes computed here match hashes computed anywhere else.

Part of Engrave — immutable audit evidence, verifiable by anyone. · Docs · MIT