modeid

HAID (Hybrid Adaptive Identifier) — npm package modeid. Source repo: sagarchive/modeid.

Hybrid Adaptive Identifier — 128-bit IDs with explicit profiles for row-store DBs, hash-partitioned stores, and public-facing opaque tokens.

• Profile-based — db, shard, opaque; pick by storage engine and threat model, not one global format
• 128-bit — Same size as UUID/ULID; 26-character Crockford base32 strings (URL-safe, no hyphens on output)
• Documented wire format — SPEC.md frozen at v0.1.0; conformance tests in-repo
• Sortable — db and opaque (with key) approximate creation-time lex order; shard spreads partitions
• Monotonic semantics — Shared generator core: same-ms counter, clock-rollback handling, drift guard (SPEC.md §6)
• Zero runtime dependencies — TypeScript compiled to ESM; tree-shakable subpath exports
• Cross-runtime — Node 18+, browsers, Workers, Deno, Bun (Web Crypto for opaque)

Status: v0.1.0 — wire format and encoding are frozen. Public API may change until v1.0. Not a drop-in replacement for RFC UUID or ULID bytes on the wire.

Quickstart

1. Install

npm install modeid

Local development (before publish):

npm install file:../modeid

2. Generate an ID

import { db } from 'modeid';

const id = db.generate();
id.toString();   // ⇨ '400sw0shksqbv0pgr1f4m0y31w' (26 chars)
id.timestamp();  // ⇨ 1715000000000
id.profile();    // ⇨ 'db'

3. Parse and validate

import { parse, validate } from 'modeid';

const back = parse(id.toString());
back.equals(id);              // ⇨ true
validate(id.toString());      // ⇨ true
validate('not-a-modeid');       // ⇨ false

When to use which profile

| Profile | Use instead of | Storage / exposure | |---------|----------------|-------------------| | db | UUIDv7, ULID (B-tree PK) | Postgres/MySQL uuid / binary(16) PK | | shard | UUIDv7 on Cassandra/Dynamo | Hash-partitioned writes; prefix spread | | opaque | UUIDv4 in public URLs | External IDs; hide creation time without key |

There is no single profile that replaces all UUID and ULID uses. See Migration.

API summary

| Export | Description | |--------|-------------| | db.generate() | Default row-store ID (sync) | | DbGenerator | Configurable db generator | | shard.generate() | Default sharded-store ID (sync) | | ShardGenerator | Keyed / generatorId shard generator | | OpaqueGenerator | Public opaque IDs (async) | | unwrapOpaque() | Recover time + counter with key | | parse(str) | Parse string → HaidId | | validate(str) | true if valid HAID string | | compare(a, b) | Lexicographic byte compare | | HaidId | Opaque token type |

Subpath imports (tree-shaking)

import { generate } from 'modeid/db';
import { ShardGenerator } from 'modeid/shard';
import { OpaqueGenerator, unwrapOpaque } from 'modeid/opaque';
import { parse, validate } from 'modeid';

API

HaidId

Returned by all generators and parse().

| Method | Returns | Notes | |--------|---------|-------| | toString() | string | 26-char lowercase Crockford; canonical form | | toBytes() | Uint8Array | 16 bytes; store in uuid / bytea columns | | profile() | 'db' \| 'shard' \| 'opaque' | From header byte | | timestamp() | number | Unix ms; throws on opaque (use unwrapOpaque) | | equals(other) | boolean | Constant-time-ish byte compare | | debug() | object | Unstable; debugging only |

parse(str)

| | | |-|-| | str | 26-char HAID string (hyphens allowed, stripped) | | returns | HaidId | | throws | Invalid length, charset, version, profile, or trailing bits |

import { parse } from 'modeid';

parse('400sw0shksqbv0pgr1f4m0y31w');

validate(str)

| | | |-|-| | str | Candidate string | | returns | boolean — never throws |

import { validate } from 'modeid';

validate('400sw0shksqbv0pgr1f4m0y31w'); // true

compare(a, b)

| | | |-|-| | returns | -1 \| 0 \| 1 — lexicographic on 16-byte form |

For db IDs, byte order ≈ creation-time order. For shard, use .timestamp() for time ordering.

import { compare, db } from 'modeid';

const a = db.generate();
const b = db.generate();
compare(a, b); // -1 | 0 | 1

db profile

Row-store primary keys. Layout: 48-bit unix_ms + 16-bit monotonic counter + 56-bit entropy. Header 0x20.

Module convenience

import { db } from 'modeid';

const id = db.generate();

DbGenerator

import { DbGenerator } from 'modeid';

const gen = new DbGenerator({
  timeSource: () => Date.now(),
  maxDriftMs: 3_600_000, // throw if clock drifts >1h (default)
});
const id = gen.generate();

| Option | Default | Description | |--------|---------|-------------| | timeSource | Date.now | Millisecond clock | | maxDriftMs | 3600000 | Max lastMs - now before throw |

shard profile

Hash-partitioned stores. SipHash-2-4 prefix (16 bits) + 48-bit time + 56-bit entropy. Header 0x21. No on-wire counter (entropy only within a ms).

import { shard, ShardGenerator } from 'modeid';

shard.generate();

const gen = new ShardGenerator({
  key: undefined,           // default: zero key (public prefix derivation)
  generatorId: myPodId,     // 8 bytes; default random per process
});
const id = gen.generate();
const prefix = gen.prefixFor(Date.now()); // range-scan helper

| Option | Default | Description | |--------|---------|-------------| | key | 16 zero bytes | SipHash key; set for keyed mode | | generatorId | random 8 bytes | Per-instance; spreads same-ms writes across shards |

opaque profile

Public-facing IDs. AES-128 single-block keystream XOR over encrypted time+counter; 56-bit nonce in plaintext. Header 0x22. Requires 16-byte key.

import { OpaqueGenerator, unwrapOpaque } from 'modeid';

const key = crypto.getRandomValues(new Uint8Array(16));
const gen = new OpaqueGenerator({ key });

const id = await gen.generate();
id.toString(); // looks random to outsiders

const { timestamp, counter } = await unwrapOpaque(id, key);

| | | |-|-| | generate() | Promise<HaidId> — async (Web Crypto) | | unwrapOpaque(id, key) | Promise<{ timestamp, counter }> |

Not provided: MAC/authenticity; treat IDs as opaque tokens and validate existence in your DB.

Encoding

• Alphabet: Crockford base32 lowercase (0123456789abcdefghjkmnpqrstvwxyz)
• Length: 26 characters for 128 bits
• Parse: case-insensitive; I/L→1, O→0; hyphens ignored
• Output: never emits hyphens

Database storage

Store id.toBytes() (16 bytes) in Postgres uuid, MySQL binary(16), or text via id.toString().

-- Postgres example
CREATE TABLE items (
  id uuid PRIMARY KEY DEFAULT NULL,
  ...
);
-- insert: pass 16-byte buffer from id.toBytes()

Migration from UUID / ULID

| From | To | Action | |------|-----|--------| | uuid.v7() / ULID for new PKs | db.generate() | New column or new tables only; re-encode is required | | uuid.v4() in URLs | opaque + key | Add key management; async generate | | Hot partitions with time-sorted UUIDs | shard | Use prefixFor() for range scans | | Existing UUID/ULID columns | — | No in-place wire upgrade; migrate with backfill |

Not supported: RFC v1/v3/v4/v5/v6, namespace UUIDs, hyphenated UUID canonical form, ULID byte compatibility.

Rough equivalence

• ULID: 48-bit time + 80-bit random, monotonic via random increment → HAID db uses explicit 16-bit counter + 56-bit entropy and a profile header.
• uuid v7: RFC layout and 36-char hex → HAID db is 26-char Crockford with different bit layout (SPEC.md).

Support

| Runtime | Support | |---------|---------| | Node.js | 18+ (CI: 20, 22 on Ubuntu + Windows) | | TypeScript | Types included; strict compatible | | Browsers | ESM + Web Crypto (opaque needs crypto.subtle) | | Deno / Bun / Workers | Expected to work; not all matrix-tested in CI | | React Native | Polyfill crypto.getRandomValues / subtle before import (same as uuid) |

Development

Branch naming: Conventional Branch 1.0.0 (main, feature/…, fix/…, release/v0.1.0, etc.).

npm ci
npm run typecheck
npm run build
npm test              # 54 tests
npm run test:smoke    # consumer smoke against dist/

Known issues

opaque generate() is async

Web Crypto AES has no sync API in portable code. Use await or .then().

Not interchangeable with UUID or ULID parsers

Strings and bytes differ. Do not feed HAID strings into uuid.parse() or ULID decoders.

package.json / monorepo CI

If this package lives in a monorepo, point the CI badge at your repo’s workflow path.

Specification & license

• Wire format: SPEC.md
• Changelog: CHANGELOG.md
• License: MIT