urn-anbs

Canonical ANBS URNs in the form urn:anbs:<SchemaOrgType>.<OpaqueIdentifier>. The Schema.org type comes from @sovereignbase/schema-crdt, and the opaque identifier presentation is validated through @sovereignbase/cryptosuite.

• Check the docs
• Read the specification

Compatibility

• Runtimes: Node >= 20; Browsers: modern browsers with WebCrypto; Workers/Edge: runtimes with WebCrypto.
• Module format: ESM and CJS.
• Required globals / APIs: crypto, crypto.subtle, crypto.getRandomValues.
• TypeScript: bundled types.

Goals

• Persistent, globally unique ANBS resource names.
• Canonical urn:anbs generation and deterministic derivation.
• Namespace-specific validation, parsing, assertion, and type narrowing.
• Stable typed errors for invalid ANBS URNs.
• Side-effect-free package entrypoint.

Installation

npm install @sovereignbase/urn-anbs
# or
pnpm add @sovereignbase/urn-anbs
# or
yarn add @sovereignbase/urn-anbs
# or
bun add @sovereignbase/urn-anbs
# or
deno add jsr:@sovereignbase/urn-anbs
# or
vlt install jsr:@sovereignbase/urn-anbs
Copy

Usage

import { UrnAnbs } from '@sovereignbase/urn-anbs'

const generated = UrnAnbs.generate('Person')
const derived = await UrnAnbs.derive('Thing', new Uint8Array([1, 2, 3]))

if (UrnAnbs.is(generated)) {
  const { type, id } = UrnAnbs.parse(generated)
  console.log(type, id)
}

UrnAnbs.assert(derived)
Copy

Runtime behavior

Node

Uses @sovereignbase/cryptosuite for opaque identifier generation, derivation, and validation. Node must provide WebCrypto.

Browsers / Edge runtimes

Uses the same cryptosuite API surface and requires WebCrypto-compatible runtime globals.

Validation & errors

UrnAnbs.is(value) first validates the ANBS URN lexical prefix and Schema.org type segment, then validates the opaque identifier with Cryptographic.identifier.validate(...).

UrnAnbs.assert(value) throws UrnAnbsError with code URN_ANBS_INVALID_IDENTIFIER when validation fails.

Tests

npm run test
Copy

What the current test suite covers:

• Coverage on built dist/**/*.js: 100% statements, 100% branches, 100% functions, and 100% lines via c8.
• Canonical generation, deterministic derivation, validation, assertion, and parsing.
• Typed UrnAnbsError failure paths.
• Package root exports.
• End-to-end runtime matrix for:
  • Node ESM
  • Node CJS
  • Bun ESM
  • Bun CJS
  • Deno ESM
  • Cloudflare Workers ESM
  • Edge Runtime ESM
  • Browsers via Playwright: Chromium, Firefox, WebKit, mobile Chrome, mobile Safari
• Current status: npm run test passes on Node v22.14.0 (win32 x64).

Benchmarks

npm run bench
Copy

The benchmark suite measures the public ANBS URN operations.

Last measured on Node v22.14.0 (win32 x64):

Benchmark	Result
generate	104,791 ops/s (95.4 ms)
derive	13,990 ops/s (71.5 ms)
is valid	1,623,635 ops/s (61.6 ms)
parse valid	768,429 ops/s (130.1 ms)

License

Apache-2.0