orion-192 — JavaScript / TypeScript

JavaScript / TypeScript reference implementation of ORION-192 — Ordered, Resilient, Independent, Opaque-ish, Non-coordinated 192-bit identifiers for distributed systems.

ORION-192 produces fixed-width, URL-safe, lexicographically sortable IDs without a central coordinator, worker ID, or machine identity in the wire format. This package is byte-compatible with the Python and Rust reference implementations.

Highlights

• Zero runtime dependencies. The only requirement at runtime is a CSPRNG (globalThis.crypto.getRandomValues or node:crypto).
• Dual ESM + CJS entry points with full TypeScript declarations and a types export condition.
• Universal runtime support: Node.js ≥ 20, Bun, Deno, and modern browsers.
• Strictly monotonic within a generator instance, including across clock rollback.
• Wire-compatible with the Python and Rust packages — same 24-byte layout, same 32-character canonical form.

Install

npm install orion-192
# or: pnpm add orion-192
# or: yarn add orion-192

Note: the npm package is published as orion-192 (sibling implementations on PyPI and crates.io are published as o192). The unscoped name o192 is reserved by npm's anti-typosquat policy.

Quick start

import { orionid, OrionIdGenerator, parse, isValid } from 'orion-192';

// 1. One-shot helper
console.log(orionid()); // → "0Pu_iDKVO9012BwIEM28oFojPMWLWeLU"

// 2. Long-lived generator (recommended for sustained throughput)
const gen = new OrionIdGenerator({ epochMs: Date.UTC(2025, 0, 1) });
const a = gen.next();
const b = gen.next();
console.log(a < b); // true — strictly monotonic per generator

// 3. Parse and inspect
if (isValid(a)) {
  const view = parse(a, { epochMs: Date.UTC(2025, 0, 1) });
  console.log(view.unixDate, view.fraction4096, view.counter);
}

API

Top-level helpers

function orionid(): string;
function parse(id: string, options?: { epochMs?: number }): ParsedOrionId;
function isValid(id: string): boolean;
function encodeSortable64(bytes: Uint8Array): string;
function decodeSortable64(id: string): Uint8Array;

OrionIdGenerator

new OrionIdGenerator(options?: {
  epochMs?: number;          // private epoch in ms                    (default: 0)
  randomPoolBytes?: number;  // CSPRNG pool size, 14 .. 16 MiB         (default: 65 536)
  clock?: () => bigint;      // custom Unix-ns clock (test-only)
  randomFill?: RandomFiller; // custom CSPRNG (test-only)
});

generator.next(): string;            // 32-char canonical string
generator.nextBytes(): Uint8Array;   // 24-byte binary form
generator.parse(id: string): ParsedOrionId;

// Read-only telemetry
generator.epochMs: bigint;           // configured epoch as bigint
generator.lastTimeKey: bigint;       // last logical 60-bit time key
generator.counter: number;           // current 20-bit counter value
generator.clockRollbacks: number;    // observed backward jumps
generator.syntheticTicks: number;    // counter-overflow advances

ParsedOrionId

interface ParsedOrionId {
  id: string;            // original canonical string
  bytes: Uint8Array;     // 24-byte binary form
  unixMs: bigint;        // relative_ms + epochMs
  unixDate: Date;        // unixMs as a JS Date
  relativeMs: bigint;    // 48-bit ms field
  fraction4096: number;  // 12-bit sub-ms fraction
  approxSubMs: number;   // fraction4096 / 4096, in ms
  counter: number;       // 20-bit counter
  randomHex: string;     // 14-byte tail as lower-case hex
}

Errors

class OrionIdError extends Error {
  code:
    | 'INVALID_LENGTH'
    | 'INVALID_CHARACTER'
    | 'INVALID_OPTION'
    | 'TIMESTAMP_OVERFLOW'
    | 'COUNTER_OVERFLOW'
    | 'RANDOM_FAILURE';
}

Every error thrown by the package extends OrionIdError. Use error.code for programmatic handling rather than parsing messages.

Browser usage

The package is browser-safe and requires no bundler-specific shims. The single runtime requirement is globalThis.crypto.getRandomValues, which is available in every modern browser, Deno, and Bun.

Performance

A single OrionIdGenerator saturates a modern CPU core at roughly 5–10 M IDs/second depending on the runtime. The dominant cost is Uint8Array allocation; reuse a generator across requests for the highest throughput. Numbers are indicative — run the bundled benchmark on your target hardware:

npm run bench

Status

ORION-192 is at spec v0 — implementation-complete, cross-language conformant, and wire-frozen. See the project status for the full stability statement.

Specification & related

• Specification (SPEC.md) — normative wire format and algorithm.
• Design rationale (docs/RATIONALE.md) — why 192 bits, why this layout.
• Storage guide (docs/DATABASE.md) — column types, collation, indexing.
• Security policy (SECURITY.md) — threat model and disclosure process.
• Sibling implementations: Python · Rust.

License

Licensed under the MIT License — Copyright © 2026 Lam Hieu and contributors.