@smonn/ids 0.0.0 → 0.0.1

package/README.md

@@ -86,14 +86,14 @@ Caveat: two IDs generated in the same millisecond by the same process have indep
 
 ```ts
 const users = createId("usr", {
-  now: () => new Date("2026-01-01T00:00:00Z"),
-  rng: (bytes) => new Uint8Array(bytes),
+  now: () => new Date("2026-01-01T00:00:00Z").getTime(),
+  rng: (target) => {}, // leave target as zero-filled
 });
 
 users.generate(); // deterministic snapshot-friendly output
 ```
 
-Both `Options` fields are optional. Defaults are `() => new Date()` and `crypto.getRandomValues`.
+Both `Options` fields are optional. Defaults are `Date.now` and a wrapper around `crypto.getRandomValues`. `now` returns milliseconds since the Unix epoch. `rng` writes random bytes into the provided target (a 10-byte view into the codec's persistent buffer), so a custom RNG never has to allocate.
 
 ## What this is **not** for
 

package/dist/index.d.mts

@@ -0,0 +1,28 @@
+//#region src/id.d.ts
+type Options = {
+  now: () => number;
+  rng: (target: Uint8Array) => void;
+};
+type Prefix<Brand extends string> = `${Brand}_`;
+type Id<Brand extends string> = `${Prefix<Brand>}${string}` & {
+  readonly __brand: Brand;
+};
+type ParseError = "not_string" | "invalid_prefix" | "invalid_base32";
+type ParseResult<Brand extends string> = {
+  ok: true;
+  id: Id<Brand>;
+} | {
+  ok: false;
+  error: ParseError;
+};
+type Codec<Brand extends string> = {
+  generate(): Id<Brand>;
+  is(value: unknown): value is Id<Brand>;
+  parse(value: unknown): Id<Brand>;
+  safeParse(value: unknown): ParseResult<Brand>;
+  extractTimestamp(id: Id<Brand>): Date;
+};
+declare function createId<Brand extends string>(brand: Brand, opts?: Partial<Options>): Codec<Brand>;
+//#endregion
+export { type Codec, type Id, type Options, type ParseError, type ParseResult, createId };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/id.ts"],"mappings":";KAEY,OAAA;EACV,GAAA;EACA,GAAA,GAAM,MAAA,EAAQ,UAAA;AAAA;AAAA,KA2CX,MAAA,4BAAkC,KAAA;AAAA,KAE3B,EAAA,4BAA8B,MAAA,CAAO,KAAA;EAAA,SACtC,OAAA,EAAS,KAAA;AAAA;AAAA,KAGR,UAAA;AAAA,KAEA,WAAA;EACN,EAAA;EAAU,EAAA,EAAI,EAAA,CAAG,KAAA;AAAA;EACjB,EAAA;EAAW,KAAA,EAAO,UAAA;AAAA;AAAA,KAEZ,KAAA;EACV,QAAA,IAAY,EAAA,CAAG,KAAA;EACf,EAAA,CAAG,KAAA,YAAiB,KAAA,IAAS,EAAA,CAAG,KAAA;EAChC,KAAA,CAAM,KAAA,YAAiB,EAAA,CAAG,KAAA;EAC1B,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;EACvC,gBAAA,CAAiB,EAAA,EAAI,EAAA,CAAG,KAAA,IAAS,IAAA;AAAA;AAAA,iBAmBnB,QAAA,uBACd,KAAA,EAAO,KAAA,EACP,IAAA,GAAM,OAAA,CAAQ,OAAA,IACb,KAAA,CAAM,KAAA"}

package/dist/index.mjs

@@ -0,0 +1,153 @@
+//#region src/base32.ts
+const alphabet = "0123456789abcdefghjkmnpqrstvwxyz";
+const valueToCharCode = new Uint8Array(32);
+for (let i = 0; i < 32; i++) valueToCharCode[i] = alphabet.charCodeAt(i);
+const charCodeToValue = new Uint8Array(256).fill(255);
+for (let i = 0; i < 32; i++) {
+	const code = alphabet.charCodeAt(i);
+	charCodeToValue[code] = i;
+	if (code >= 97 && code <= 122) charCodeToValue[code - 32] = i;
+}
+charCodeToValue["o".charCodeAt(0)] = charCodeToValue["O".charCodeAt(0)] = 0;
+charCodeToValue["i".charCodeAt(0)] = charCodeToValue["I".charCodeAt(0)] = 1;
+charCodeToValue["l".charCodeAt(0)] = charCodeToValue["L".charCodeAt(0)] = 1;
+function encodeBase32(bytes) {
+	const codes = new Array(Math.floor(bytes.length * 8 / 5) + 1);
+	let chi = 0;
+	let bits = 0;
+	let value = 0;
+	for (let i = 0; i < bytes.length; i++) {
+		value = value << 8 | bytes[i];
+		bits += 8;
+		while (bits >= 5) {
+			bits -= 5;
+			codes[chi++] = valueToCharCode[value >>> bits & 31];
+		}
+	}
+	codes[chi] = valueToCharCode[value << 5 - bits & 31];
+	return String.fromCharCode.apply(null, codes);
+}
+function decodeBase32(str) {
+	const result = new Uint8Array(Math.floor(str.length * 5 / 8));
+	let bits = 0;
+	let value = 0;
+	let index = 0;
+	for (let i = 0; i < str.length; i++) {
+		const v = charCodeToValue[str.charCodeAt(i)];
+		value = value << 5 | v;
+		bits += 5;
+		if (bits >= 8) {
+			bits -= 8;
+			result[index++] = value >>> bits & 255;
+		}
+	}
+	return result;
+}
+//#endregion
+//#region src/id.ts
+const hexCharCodeToNibble = new Uint8Array(128);
+for (let i = 0; i < 10; i++) hexCharCodeToNibble[48 + i] = i;
+for (let i = 0; i < 6; i++) hexCharCodeToNibble[97 + i] = 10 + i;
+const defaultOptions = {
+	now: Date.now,
+	rng: (target) => {
+		const s = crypto.randomUUID();
+		target[0] = hexCharCodeToNibble[s.charCodeAt(0)] << 4 | hexCharCodeToNibble[s.charCodeAt(1)];
+		target[1] = hexCharCodeToNibble[s.charCodeAt(2)] << 4 | hexCharCodeToNibble[s.charCodeAt(3)];
+		target[2] = hexCharCodeToNibble[s.charCodeAt(4)] << 4 | hexCharCodeToNibble[s.charCodeAt(5)];
+		target[3] = hexCharCodeToNibble[s.charCodeAt(6)] << 4 | hexCharCodeToNibble[s.charCodeAt(7)];
+		target[4] = hexCharCodeToNibble[s.charCodeAt(9)] << 4 | hexCharCodeToNibble[s.charCodeAt(10)];
+		target[5] = hexCharCodeToNibble[s.charCodeAt(11)] << 4 | hexCharCodeToNibble[s.charCodeAt(12)];
+		target[6] = hexCharCodeToNibble[s.charCodeAt(24)] << 4 | hexCharCodeToNibble[s.charCodeAt(25)];
+		target[7] = hexCharCodeToNibble[s.charCodeAt(26)] << 4 | hexCharCodeToNibble[s.charCodeAt(27)];
+		target[8] = hexCharCodeToNibble[s.charCodeAt(28)] << 4 | hexCharCodeToNibble[s.charCodeAt(29)];
+		target[9] = hexCharCodeToNibble[s.charCodeAt(30)] << 4 | hexCharCodeToNibble[s.charCodeAt(31)];
+	}
+};
+const timestampByteLength = 6;
+const randomByteLength = 10;
+const totalByteLength = 16;
+const base32Length = Math.ceil(totalByteLength * 8 / 5);
+const timestampBase32Length = Math.ceil(timestampByteLength * 8 / 5);
+const replacePattern = /[ilo]/g;
+const aliasTestPattern = /[ilo]/;
+const replaceMap = {
+	o: "0",
+	i: "1",
+	l: "1"
+};
+const replacer = (match) => {
+	if (match !== "o" && match !== "i" && match !== "l") throw new Error("invalid match");
+	return replaceMap[match];
+};
+const base32Pattern = new RegExp(`^[${alphabet}]{${base32Length}}$`);
+const brandPattern = /^[a-z]{3}$/;
+function createId(brand, opts = {}) {
+	if (!brandPattern.test(brand)) throw new Error("invalid brand, expected three lowercase a-z characters");
+	const options = {
+		...defaultOptions,
+		...opts
+	};
+	const prefix = `${brand}_`;
+	const buffer = new Uint8Array(totalByteLength);
+	const randomView = new Uint8Array(buffer.buffer, timestampByteLength, randomByteLength);
+	return {
+		generate: () => generate(prefix, options, buffer, randomView),
+		is: (value) => is(prefix, value),
+		parse: (value) => parse(prefix, value),
+		safeParse: (value) => safeParse(prefix, value),
+		extractTimestamp: (id) => extractTimestamp(prefix, id)
+	};
+}
+function safeParse(prefix, value) {
+	if (typeof value !== "string") return {
+		ok: false,
+		error: "not_string"
+	};
+	const lowercase = value.toLowerCase();
+	if (!lowercase.startsWith(prefix)) return {
+		ok: false,
+		error: "invalid_prefix"
+	};
+	const sliced = lowercase.slice(prefix.length);
+	const base32 = aliasTestPattern.test(sliced) ? sliced.replaceAll(replacePattern, replacer) : sliced;
+	if (!base32Pattern.test(base32)) return {
+		ok: false,
+		error: "invalid_base32"
+	};
+	return {
+		ok: true,
+		id: prefix + base32
+	};
+}
+function parse(prefix, value) {
+	const result = safeParse(prefix, value);
+	if (result.ok) return result.id;
+	throw new Error(`Invalid ID: ${result.error}`);
+}
+function is(prefix, value) {
+	if (typeof value !== "string") return false;
+	if (!value.startsWith(prefix)) return false;
+	return base32Pattern.test(value.slice(prefix.length));
+}
+function generate(prefix, options, buffer, randomView) {
+	let ms = options.now();
+	if (ms < 0) throw new Error("timestamp is negative");
+	if (ms >= 2 ** (timestampByteLength * 8)) throw new Error("timestamp exceeds 48-bit range");
+	for (let i = timestampByteLength - 1; i >= 0; i--) {
+		buffer[i] = ms % 256;
+		ms = Math.floor(ms / 256);
+	}
+	options.rng(randomView);
+	return prefix + encodeBase32(buffer);
+}
+function extractTimestamp(prefix, id) {
+	const bytes = decodeBase32(id.slice(prefix.length, prefix.length + timestampBase32Length));
+	let ms = 0;
+	for (const byte of bytes) ms = ms * 256 + byte;
+	return new Date(ms);
+}
+//#endregion
+export { createId };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/base32.ts","../src/id.ts"],"sourcesContent":["/*\n  This is based on Crockford's Base32 spec: https://www.crockford.com/base32.html\n  One difference is that it uses lowercase instead of uppercase when encoding.\n\n  These functions are internal: callers (id.ts) guarantee that input is a\n  16-byte buffer for encode, or a string of characters drawn from the alphabet\n  for decode. Invalid input produces silent garbage rather than a thrown error,\n  consistent with the trust-the-type rule in ADR-0003.\n*/\n\nexport const alphabet = \"0123456789abcdefghjkmnpqrstvwxyz\";\n\n// 0–31 → ASCII char code, for write-into-codes-then-fromCharCode encoding.\nconst valueToCharCode = new Uint8Array(32);\nfor (let i = 0; i < 32; i++) valueToCharCode[i] = alphabet.charCodeAt(i);\n\n// charCode → 0–31 value. Covers both cases and the Crockford o/i/l aliases.\nconst INVALID = 0xff;\nconst charCodeToValue = new Uint8Array(256).fill(INVALID);\nfor (let i = 0; i < alphabet.length; i++) {\n  const code = alphabet.charCodeAt(i);\n  charCodeToValue[code] = i;\n  if (code >= 97 && code <= 122) charCodeToValue[code - 32] = i;\n}\ncharCodeToValue[\"o\".charCodeAt(0)] = charCodeToValue[\"O\".charCodeAt(0)] = 0;\ncharCodeToValue[\"i\".charCodeAt(0)] = charCodeToValue[\"I\".charCodeAt(0)] = 1;\ncharCodeToValue[\"l\".charCodeAt(0)] = charCodeToValue[\"L\".charCodeAt(0)] = 1;\n\nexport function encodeBase32(bytes: Uint8Array): string {\n  // Build an Array<number> of char codes and pass it to fromCharCode.apply.\n  // Faster than `result += char` (avoids cons-string overhead) and than\n  // Uint8Array variants (apply has a fast path for plain Arrays).\n  // oxlint-disable-next-line no-new-array\n  const codes = new Array<number>(Math.floor((bytes.length * 8) / 5) + 1);\n  let chi = 0;\n  let bits = 0;\n  let value = 0;\n\n  for (let i = 0; i < bytes.length; i++) {\n    value = (value << 8) | bytes[i]!;\n    bits += 8;\n    while (bits >= 5) {\n      bits -= 5;\n      codes[chi++] = valueToCharCode[(value >>> bits) & 0x1f]!;\n    }\n  }\n  codes[chi] = valueToCharCode[(value << (5 - bits)) & 0x1f]!;\n  return String.fromCharCode.apply(null, codes);\n}\n\nexport function decodeBase32(str: string): Uint8Array {\n  const result = new Uint8Array(Math.floor((str.length * 5) / 8));\n  let bits = 0;\n  let value = 0;\n  let index = 0;\n\n  for (let i = 0; i < str.length; i++) {\n    const v = charCodeToValue[str.charCodeAt(i)]!;\n    value = (value << 5) | v;\n    bits += 5;\n    if (bits >= 8) {\n      bits -= 8;\n      result[index++] = (value >>> bits) & 0xff;\n    }\n  }\n  return result;\n}\n","import { alphabet, decodeBase32, encodeBase32 } from \"./base32.js\";\n\nexport type Options = {\n  now: () => number;\n  rng: (target: Uint8Array) => void;\n};\n\n// hex charCode → 0–15 nibble, for decoding UUIDv4 strings into bytes.\n// Covers ['0'-'9' = 48–57] and ['a'-'f' = 97–102]; UUIDs are lowercase per spec.\nconst hexCharCodeToNibble = new Uint8Array(128);\nfor (let i = 0; i < 10; i++) hexCharCodeToNibble[48 + i] = i;\nfor (let i = 0; i < 6; i++) hexCharCodeToNibble[97 + i] = 10 + i;\n\nconst defaultOptions: Options = {\n  now: Date.now,\n  // crypto.randomUUID is ~7× faster than crypto.getRandomValues in Node 24\n  // (~84 ns vs ~610 ns for a 16-byte fill — likely because the UUID path has\n  // a tight fixed-format fast path). We use the 122 random bits of a UUIDv4\n  // string as our entropy source, harvesting 10 fully-random bytes from\n  // positions where no version (hex 12) or variant (hex 16) bits sit.\n  // String layout: \"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\" — bytes 0–5 are\n  // string[0..7]+string[9..12], bytes 6–9 are string[24..31].\n  rng: (target) => {\n    const s = crypto.randomUUID();\n    target[0] =\n      (hexCharCodeToNibble[s.charCodeAt(0)]! << 4) | hexCharCodeToNibble[s.charCodeAt(1)]!;\n    target[1] =\n      (hexCharCodeToNibble[s.charCodeAt(2)]! << 4) | hexCharCodeToNibble[s.charCodeAt(3)]!;\n    target[2] =\n      (hexCharCodeToNibble[s.charCodeAt(4)]! << 4) | hexCharCodeToNibble[s.charCodeAt(5)]!;\n    target[3] =\n      (hexCharCodeToNibble[s.charCodeAt(6)]! << 4) | hexCharCodeToNibble[s.charCodeAt(7)]!;\n    target[4] =\n      (hexCharCodeToNibble[s.charCodeAt(9)]! << 4) | hexCharCodeToNibble[s.charCodeAt(10)]!;\n    target[5] =\n      (hexCharCodeToNibble[s.charCodeAt(11)]! << 4) | hexCharCodeToNibble[s.charCodeAt(12)]!;\n    target[6] =\n      (hexCharCodeToNibble[s.charCodeAt(24)]! << 4) | hexCharCodeToNibble[s.charCodeAt(25)]!;\n    target[7] =\n      (hexCharCodeToNibble[s.charCodeAt(26)]! << 4) | hexCharCodeToNibble[s.charCodeAt(27)]!;\n    target[8] =\n      (hexCharCodeToNibble[s.charCodeAt(28)]! << 4) | hexCharCodeToNibble[s.charCodeAt(29)]!;\n    target[9] =\n      (hexCharCodeToNibble[s.charCodeAt(30)]! << 4) | hexCharCodeToNibble[s.charCodeAt(31)]!;\n  },\n};\n\ntype Prefix<Brand extends string> = `${Brand}_`;\n\nexport type Id<Brand extends string> = `${Prefix<Brand>}${string}` & {\n  readonly __brand: Brand;\n};\n\nexport type ParseError = \"not_string\" | \"invalid_prefix\" | \"invalid_base32\";\n\nexport type ParseResult<Brand extends string> =\n  | { ok: true; id: Id<Brand> }\n  | { ok: false; error: ParseError };\n\nexport type Codec<Brand extends string> = {\n  generate(): Id<Brand>;\n  is(value: unknown): value is Id<Brand>;\n  parse(value: unknown): Id<Brand>;\n  safeParse(value: unknown): ParseResult<Brand>;\n  extractTimestamp(id: Id<Brand>): Date;\n};\n\nconst timestampByteLength = 6;\nconst randomByteLength = 10;\nconst totalByteLength = timestampByteLength + randomByteLength;\nconst base32Length = Math.ceil((totalByteLength * 8) / 5);\nconst timestampBase32Length = Math.ceil((timestampByteLength * 8) / 5);\nconst replacePattern = /[ilo]/g;\nconst aliasTestPattern = /[ilo]/;\nconst replaceMap = { o: \"0\", i: \"1\", l: \"1\" } as const;\nconst replacer = (match: string): string => {\n  if (match !== \"o\" && match !== \"i\" && match !== \"l\") throw new Error(\"invalid match\");\n  return replaceMap[match];\n};\n\nconst base32Pattern = new RegExp(`^[${alphabet}]{${base32Length}}$`);\nconst brandPattern = /^[a-z]{3}$/;\n\nexport function createId<Brand extends string>(\n  brand: Brand,\n  opts: Partial<Options> = {},\n): Codec<Brand> {\n  if (!brandPattern.test(brand)) {\n    throw new Error(\"invalid brand, expected three lowercase a-z characters\");\n  }\n\n  const options = {\n    ...defaultOptions,\n    ...opts,\n  } satisfies Options;\n\n  const prefix: Prefix<Brand> = `${brand}_`;\n  // Per-codec scratch buffer. Reused across generate() calls — generate is\n  // synchronous, so successive callers see the buffer overwritten, not the\n  // previous result. encodeBase32 reads the buffer and returns an independent\n  // string, so the caller never sees the buffer itself.\n  const buffer = new Uint8Array(totalByteLength);\n  const randomView = new Uint8Array(buffer.buffer, timestampByteLength, randomByteLength);\n\n  return {\n    generate: () => generate(prefix, options, buffer, randomView),\n    is: (value: unknown) => is(prefix, value),\n    parse: (value: unknown) => parse(prefix, value),\n    safeParse: (value: unknown) => safeParse(prefix, value),\n    extractTimestamp: (id: Id<Brand>) => extractTimestamp(prefix, id),\n  };\n}\n\nfunction safeParse<Brand extends string>(\n  prefix: Prefix<Brand>,\n  value: unknown,\n): ParseResult<Brand> {\n  if (typeof value !== \"string\") return { ok: false, error: \"not_string\" };\n  const lowercase = value.toLowerCase();\n  if (!lowercase.startsWith(prefix)) return { ok: false, error: \"invalid_prefix\" };\n\n  const sliced = lowercase.slice(prefix.length);\n  const base32 = aliasTestPattern.test(sliced)\n    ? sliced.replaceAll(replacePattern, replacer)\n    : sliced;\n\n  if (!base32Pattern.test(base32)) return { ok: false, error: \"invalid_base32\" };\n\n  const id = (prefix + base32) as Id<Brand>;\n  return { ok: true, id };\n}\n\nfunction parse<Brand extends string>(prefix: Prefix<Brand>, value: unknown): Id<Brand> {\n  const result = safeParse(prefix, value);\n  if (result.ok) return result.id;\n  throw new Error(`Invalid ID: ${result.error}`);\n}\n\nfunction is<Brand extends string>(prefix: Prefix<Brand>, value: unknown): value is Id<Brand> {\n  if (typeof value !== \"string\") return false;\n  if (!value.startsWith(prefix)) return false;\n  return base32Pattern.test(value.slice(prefix.length));\n}\n\nfunction generate<Brand extends string>(\n  prefix: Prefix<Brand>,\n  options: Options,\n  buffer: Uint8Array,\n  randomView: Uint8Array,\n): Id<Brand> {\n  let ms = options.now();\n  if (ms < 0) throw new Error(\"timestamp is negative\");\n  if (ms >= 2 ** (timestampByteLength * 8)) throw new Error(\"timestamp exceeds 48-bit range\");\n  // write the timestamp in big-endian; encoded via mod-256 to avoid 32-bit bitwise coercion\n  for (let i = timestampByteLength - 1; i >= 0; i--) {\n    buffer[i] = ms % 256;\n    ms = Math.floor(ms / 256);\n  }\n  options.rng(randomView);\n  return (prefix + encodeBase32(buffer)) as Id<Brand>;\n}\n\nfunction extractTimestamp<Brand extends string>(prefix: Prefix<Brand>, id: Id<Brand>): Date {\n  const base32 = id.slice(prefix.length, prefix.length + timestampBase32Length);\n  const bytes = decodeBase32(base32);\n  let ms = 0;\n  for (const byte of bytes) {\n    ms = ms * 256 + byte;\n  }\n  return new Date(ms);\n}\n"],"mappings":"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"}

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@smonn/ids",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "license": "MIT",
+  "author": "Simon Ingeson (https://github.com/smonn)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smonn/ids.git"
+  },
+  "files": [
+    "dist"
+  ],
   "type": "module",
   "exports": {
     ".": "./dist/index.mjs",
@@ -12,6 +20,7 @@
     "@types/node": "25.9.1",
     "@vitest/coverage-v8": "4.1.7",
     "knip": "6.14.2",
+    "mitata": "1.0.34",
     "oxfmt": "0.52.0",
     "oxlint": "1.67.0",
     "tsdown": "0.22.1",
@@ -31,6 +40,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "knip": "knip"
+    "knip": "knip",
+    "bench:build": "tsdown -c tsdown.bench.config.ts",
+    "bench": "pnpm -s bench:build 1>&2 && node bench/dist/index.mjs",
+    "bench:compare": "pnpm -s bench:build 1>&2 && node bench/dist/compare.mjs"
   }
 }

package/.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets).
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

package/.changeset/config.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}

package/.github/workflows/ci.yml

@@ -1,35 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-  push:
-    branches: [main]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  ci:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: pnpm/action-setup@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 24
-          cache: pnpm
-
-      - run: pnpm install --frozen-lockfile
-
-      - run: pnpm lint
-
-      - run: pnpm fmt:check
-
-      - run: pnpm typecheck
-
-      - run: pnpm test
-
-      - run: pnpm build

package/.github/workflows/release.yml

@@ -1,42 +0,0 @@
-name: Release
-
-on:
-  push:
-    branches: [main]
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    environment: npm
-    permissions:
-      contents: write
-      pull-requests: write
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: pnpm/action-setup@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 24
-          cache: pnpm
-          registry-url: https://registry.npmjs.org
-
-      - run: npm install -g npm@latest
-
-      - run: pnpm install --frozen-lockfile
-
-      - run: pnpm build
-
-      - name: Create release PR or publish
-        uses: changesets/action@v1
-        with:
-          publish: pnpm changeset publish
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_CONFIG_PROVENANCE: "true"

package/.oxfmtrc.json

@@ -1,4 +0,0 @@
-{
-  "$schema": "./node_modules/oxfmt/configuration_schema.json",
-  "ignorePatterns": []
-}

package/.oxlintrc.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "plugins": ["typescript", "unicorn", "oxc"],
-  "categories": {
-    "correctness": "error"
-  },
-  "rules": {},
-  "env": {
-    "builtin": true
-  }
-}

package/AGENTS.md

@@ -1,15 +0,0 @@
-# smonn-ids
-
-## Agent skills
-
-### Issue tracker
-
-Issues live in GitHub Issues on `smonn/ids`, accessed via the `gh` CLI. See `docs/agents/issue-tracker.md`.
-
-### Triage labels
-
-Default canonical vocabulary (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
-
-### Domain docs
-
-Single-context repo: `CONTEXT.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`.

package/CONTEXT.md

@@ -1,51 +0,0 @@
-# IDs
-
-Library for generating, parsing, and validating public-facing entity IDs in TypeScript apps. IDs are k-sortable by creation time, type-safe at compile time, and tolerant of human transcription (case + visually-ambiguous characters).
-
-## Language
-
-**Brand**:
-The string that identifies an entity type (e.g. `"usr"`, `"org"`). Exists simultaneously at runtime (the literal characters embedded at the start of every ID) and at the type level (the nominal tag on `Id<Brand>` that prevents cross-type assignment). One concept, two materialisations — the runtime brand IS the type-level brand.
-_Avoid_: prefix, tag (overloaded with HTML/hashtag), type code, object prefix, resource prefix.
-
-**Prefix**:
-The brand plus the trailing separator — `"usr_"`. Distinct from the brand itself: the brand is `"usr"`, the prefix is what actually appears at the start of an encoded ID.
-_Avoid_: brand (use **Brand** for the unsuffixed form), header.
-
-**Codec**:
-The brand-scoped object returned by `createId(brand)`, exposing `generate`, `is`, `parse`, `safeParse`, and `extractTimestamp`. The brand is validated once at codec creation; the prefix is then captured by each method. One codec per entity type, typically constructed at module init.
-_Avoid_: factory, generator, encoder.
-
-**Canonical form**:
-The unique representation of an ID — lowercase, with Crockford base32 aliases (`o`, `i`, `l`) already resolved to `0`, `1`, `1`. Two strings denote the same ID iff their canonical forms are equal. `Id<Brand>` always holds a canonical string: `generate()` produces canonical, `parse()`/`safeParse()` normalise to canonical at the boundary, and `is()` is strict — see [ADR-0003](./docs/adr/0003-canonical-strict-is.md).
-_Avoid_: normalised form (use **Canonical form**), valid form.
-
-**Payload**:
-The 16 raw bytes that follow the prefix in an encoded ID: 6 bytes of millisecond-precision Unix timestamp (big-endian) followed by 10 bytes of randomness. ULID-shaped — same byte layout as a [ULID](https://github.com/ulid/spec), but encoded in lowercase Crockford base32 and wrapped in a brand envelope rather than emitted bare.
-_Avoid_: ULID (use **Payload** when talking about our bytes; reserve "ULID" for the spec itself), body, contents.
-
-## Example dialogue
-
-> **Dev:** I'm storing user IDs in a column. Do I store the string the user typed, or transform it first?
->
-> **Domain expert:** Store the canonical form. Two strings that decode to the same ID are distinct as JS strings — `===` is wrong unless both are canonical. `safeParse()` returns canonical; that's what goes in the database.
->
-> **Dev:** So `is()` is the wrong check at the boundary?
->
-> **Domain expert:** Right. `is()` is strict — it only returns `true` for already-canonical strings. Use it to discriminate between brands on input you already trust. For untrusted external input, use `safeParse()`; it normalises and hands back an `Id<Brand>` you can rely on.
->
-> **Dev:** What if I have a string I know is a user ID and just want the timestamp out of it?
->
-> **Domain expert:** It has to be typed as an `Id<"usr">` first — `extractTimestamp` trusts the type. The honest way to get one is `usr.safeParse(...)`. If you cast a raw string to `Id<"usr">`, you own the consequences.
->
-> **Dev:** Why does everything hang off `usr` instead of being top-level functions?
->
-> **Domain expert:** `usr` is a codec. One codec per brand, built at module init. The brand is validated once at construction and the prefix is captured by each method. Standalone functions would either re-validate every call or let bad brands silently corrupt data.
->
-> **Dev:** And the part after `usr_` is just random?
->
-> **Domain expert:** No — it's the payload. First 6 bytes are a millisecond Unix timestamp, then 10 random bytes. ULID-shaped, but lowercase and wrapped in a brand envelope. That's why IDs sort by creation time.
-
-## Flagged ambiguities / known gaps
-
-**Same-millisecond sort order is non-deterministic.** Two IDs generated in the same ms by the same process have independent random tails; they sort randomly relative to each other rather than by generation order. This is deliberate — see ADR-0002. Adding ULID-style monotonic increment would require a stateful generator and a breaking change to `Options`, and is a separate design exercise if the need ever arises.

package/CONTRIBUTING.md

@@ -1,53 +0,0 @@
-# Contributing
-
-## Before you open a PR
-
-- **Open or comment on a [GitHub issue](https://github.com/smonn/ids/issues) first** if your change is more than a small bug fix or doc tweak. Especially for anything that touches the wire format, the public API, or the validation contract — these have been deliberated and "I built it, please merge" PRs may not be accepted.
-- **Read [`CONTEXT.md`](./CONTEXT.md).** Use its vocabulary in code, commit messages, and PR descriptions; avoid the synonyms listed under each `_Avoid_:` line.
-- **Skim the [ADRs](./docs/adr/).** They record the constraints your change has to live with.
-
-## Closed design questions
-
-These were considered and rejected for specific reasons. If you have a genuinely new argument, raise it as an issue with that argument explicit — don't ship a PR that silently reopens the decision.
-
-- **Brand width or charset.** Fixed at three lowercase a–z chars. Changing it invalidates every previously-issued ID. See [ADR-0001](./docs/adr/0001-brand-format.md).
-- **Payload byte split, byte order, precision, or epoch.** Fixed at 6 bytes big-endian ms Unix timestamp + 10 random bytes. Same wire-format constraint. See [ADR-0002](./docs/adr/0002-payload-layout.md).
-- **Lenient `is()`.** `is()` is canonical-only by design; the lenient path is `safeParse()`. Restoring lenient `is()` would re-open the footgun ADR-0003 closed. See [ADR-0003](./docs/adr/0003-canonical-strict-is.md).
-- **Monotonicity inside `generate()`.** A stable intra-ms sort would force a breaking change to `Options.rng`. If you need this, design it as a separate opt-in API (e.g. `createMonotonicId`) and propose it in an issue first.
-- **Custom epoch.** 48 bits of ms gives ~8919 years of headroom from 1970; there's no bit-budget motivation to rebase. A custom epoch would turn time into a magic number every downstream consumer would have to remember. See [ADR-0002](./docs/adr/0002-payload-layout.md).
-
-## Setup
-
-```bash
-pnpm install
-```
-
-Requires Node ≥ 24 and pnpm.
-
-## Dev loop
-
-```bash
-pnpm test              # vitest run
-pnpm test:watch        # vitest in watch mode
-pnpm test:coverage     # vitest with v8 coverage
-pnpm typecheck         # tsc --noEmit
-pnpm lint              # oxlint
-pnpm fmt:check         # oxfmt --check
-pnpm build             # tsdown
-```
-
-Run `pnpm test`, `pnpm typecheck`, `pnpm lint`, and `pnpm fmt:check` before opening a PR.
-
-## Style
-
-- **Don't mock the clock or RNG.** Inject them via `Options` (`now`, `rng`) — see the existing tests for how.
-- **New exports → update the API surface section in [`README.md`](./README.md).**
-- **New domain concept → add a glossary entry to [`CONTEXT.md`](./CONTEXT.md)**, including any synonyms you want future contributors to avoid.
-- **New design decision that's hard to reverse, surprising without context, and the result of a real trade-off → add a new ADR** under `docs/adr/`, numbered sequentially.
-- **Commit subjects:** `<scope>: <what changed>` (e.g. `id: tighten is() to canonical-only`).
-
-## Tests
-
-- Add a test for any new public behaviour.
-- Add boundary tests for any new numeric input (compare with `extracts ms at the 48-bit boundary` and friends in `id.test.ts`).
-- Use deterministic `rng` and `now` in tests that assert on the encoded form — never snapshot a fully-random ID.

package/docs/adr/0001-brand-format.md

@@ -1,10 +0,0 @@
-# Brand format: three lowercase a–z characters
-
-Public-facing IDs need a short, fixed-width type identifier that humans can scan, that doesn't collide with the Crockford base32 payload, and that survives in URLs. We use exactly three lowercase a–z characters, validated at runtime: three gives 17,576 brands (more than any single app needs), lowercase removes case-normalisation from the brand portion, and excluding digits keeps the brand visually distinct from the payload. The brand width is part of the wire format — changing it invalidates every previously-issued ID.
-
-## Considered Options
-
-- **Variable width** — rejected: forces `split("_")` and a brand registry; parsing ambiguity
-- **Alphanumeric brands** (e.g. `s3_…`) — rejected: visual collision with the payload
-- **2 chars** — rejected: too few combinations as an app grows
-- **4+ chars** — rejected: URL cost without scaling benefit

package/docs/adr/0002-payload-layout.md

@@ -1,26 +0,0 @@
-# Payload layout: ULID-shaped, with deliberate divergences
-
-The payload is laid out exactly like a ULID: 48-bit millisecond Unix timestamp (big-endian) followed by 80 random bits, encoded as 26 Crockford base32 characters. We adopt the ULID byte split because it's already k-sortable, fits cleanly into 26 base32 chars, and gives ~80 bits of randomness per millisecond (collision-safe for any plausible single-app throughput).
-
-Three deliberate divergences from the spec:
-
-- **Lowercase encoding.** The brand is lowercase a–z (see [ADR-0001](./0001-brand-format.md)) and lowercasing the payload keeps the whole ID visually uniform. Decoding remains case-insensitive.
-- **Brand envelope.** IDs are emitted with a `<brand>_` prefix rather than as bare 26-char strings. Off-the-shelf ULID parsers will not accept these and shouldn't be expected to.
-- **No monotonicity.** Two IDs generated in the same millisecond by the same process do not sort deterministically. The ULID spec's monotonic-increment recommendation would require a stateful generator and break the `Options.rng` shape. Sort stability within a single ms is a non-goal for public-facing entity IDs.
-
-## Timestamp contract
-
-`Codec.extractTimestamp(id)` is a public, supported method — its existence makes the timestamp layout part of the stability contract, not an implementation detail. Specifically:
-
-- **Position:** first 6 bytes of the payload (immediately after the prefix, before the random bytes)
-- **Encoding:** unsigned big-endian integer
-- **Precision:** milliseconds
-- **Epoch:** Unix (1970-01-01T00:00:00Z) — not a custom epoch
-
-Unix is non-negotiable. 48 bits of ms gives ~8919 years of headroom from 1970, so there is no bit-budget motivation to rebase (the Snowflake/Discord rationale). A custom epoch would burn the only remaining direct ULID compatibility (the timestamp bytes themselves) and turn epoch into a magic number every external consumer of the bytes would have to know.
-
-`extractTimestamp` does not validate its input — it trusts the `Id<Brand>` type. Callers holding raw external strings must pass them through `safeParse()` / `parse()` first (see [ADR-0003](./0003-canonical-strict-is.md)).
-
-## Consequences
-
-The 16-byte payload layout is part of the wire format. Changing the byte split (e.g. 8+8, 4+12), the timestamp precision, the byte order, or the epoch invalidates every previously-issued ID — the same constraint as the brand width.

package/docs/adr/0003-canonical-strict-is.md

@@ -1,12 +0,0 @@
-# Lenient at boundaries, strict everywhere else
-
-`Id<Brand>` denotes a **canonical** ID: lowercase, with Crockford base32 aliases (`o`, `i`, `l`) already resolved. The boundary between an untrusted external string and a typed `Id<Brand>` is `parse()` / `safeParse()`; these accept lenient input (mixed case, `o`/`i`/`l` aliases) and return the canonical form. `is()` is strict — it returns `true` only for strings that are already canonical. Once a value carries the `Id<Brand>` type, `===` reliably tests logical equality.
-
-## Considered Options
-
-- **Lenient `is()`** (rejected) — equivalent to `safeParse().success`. Leaves `Id<Brand>` semantically ambiguous: a value of that type might or might not be canonical, so consumers can't rely on `===` and non-canonical strings can leak into storage if a caller forgets to round-trip through `parse()`.
-
-## Consequences
-
-- Always call `safeParse()` / `parse()` at the boundary (incoming URL params, form fields, request bodies). Never assert that a raw external string is already an `Id<Brand>`.
-- `is()` is the right guard for trusting an already-typed string (e.g. discriminating across brands within already-validated input). It is the wrong guard for ingesting external input.

package/docs/agents/domain.md

@@ -1,37 +0,0 @@
-# Domain Docs
-
-How the engineering skills should consume this repo's domain documentation when exploring the codebase.
-
-## Before exploring, read these
-
-- **`CONTEXT.md`** at the repo root, or
-- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
-- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
-
-If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
-
-## File structure
-
-This repo is **single-context**:
-
-```
-/
-├── CONTEXT.md
-├── docs/adr/
-│   ├── 0001-brand-format.md
-│   ├── 0002-payload-layout.md
-│   └── 0003-canonical-strict-is.md
-└── src/
-```
-
-## Use the glossary's vocabulary
-
-When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
-
-If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
-
-## Flag ADR conflicts
-
-If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
-
-> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -1,22 +0,0 @@
-# Issue tracker: GitHub
-
-Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
-
-## Conventions
-
-- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
-- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
-- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
-- **Comment on an issue**: `gh issue comment <number> --body "..."`
-- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
-- **Close**: `gh issue close <number> --comment "..."`
-
-Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
-
-## When a skill says "publish to the issue tracker"
-
-Create a GitHub issue.
-
-## When a skill says "fetch the relevant ticket"
-
-Run `gh issue view <number> --comments`.

package/docs/agents/triage-labels.md

@@ -1,15 +0,0 @@
-# Triage Labels
-
-The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
-
-| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
-| -------------------------- | -------------------- | ---------------------------------------- |
-| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
-| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
-| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
-| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
-| `wontfix`                  | `wontfix`            | Will not be actioned                     |
-
-When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
-
-Edit the right-hand column to match whatever vocabulary you actually use.

package/src/base32.ts

@@ -1,54 +0,0 @@
-/*
-  This is based on Crockford's Base32 spec: https://www.crockford.com/base32.html
-  One difference is that it uses lowercase instead of uppercase when encoding.
-*/
-
-import { invariant } from "./invariant.js";
-
-export const alphabet = "0123456789abcdefghjkmnpqrstvwxyz";
-
-const numberToCharLookup = alphabet.split("");
-
-const charToNumberLookup = new Map<string, number>([
-  ...numberToCharLookup.map((char, i) => [char, i] as const),
-  ["o", 0],
-  ["i", 1],
-  ["l", 1],
-]);
-
-export function encodeBase32(bytes: Uint8Array): string {
-  let result = "";
-  let bits = 0;
-  let value = 0;
-
-  for (const byte of bytes) {
-    value = (value << 8) | byte;
-    bits += 8;
-    while (bits >= 5) {
-      bits -= 5;
-      result += numberToCharLookup[(value >>> bits) & 0x1f];
-    }
-  }
-  invariant(bits === 3, "expected three leftover bits");
-  result += numberToCharLookup[(value << (5 - bits)) & 0x1f];
-  return result;
-}
-
-export function decodeBase32(str: string): Uint8Array {
-  const result = new Uint8Array(Math.floor((str.length * 5) / 8));
-  let bits = 0;
-  let value = 0;
-  let index = 0;
-
-  for (const char of str) {
-    const v = charToNumberLookup.get(char.toLowerCase());
-    invariant(v !== undefined, "invalid base32");
-    value = (value << 5) | v;
-    bits += 5;
-    if (bits >= 8) {
-      bits -= 8;
-      result[index++] = (value >>> bits) & 0xff;
-    }
-  }
-  return result;
-}

package/src/id.test.ts

@@ -1,124 +0,0 @@
-import { expect, describe, it } from "vitest";
-import { createId } from "./id.js";
-
-describe("id", () => {
-  it("roundtrip", () => {
-    const fixed = new Date("2026-05-28T12:00:00Z");
-    const usr = createId("usr", { now: () => fixed });
-    const id = usr.generate();
-    expect(usr.extractTimestamp(id)).toEqual(fixed);
-  });
-
-  it("deterministic snapshot", () => {
-    const usr = createId("usr", {
-      now: () => new Date(0),
-      rng: (n) => new Uint8Array(n),
-    });
-    expect(usr.generate()).toBe("usr_" + "0".repeat(26)); // adjust to actual
-  });
-
-  it("extracts ms=0 (epoch boundary)", () => {
-    const usr = createId("usr", {
-      now: () => new Date(0),
-      rng: (n) => new Uint8Array(n),
-    });
-    expect(usr.extractTimestamp(usr.generate())).toEqual(new Date(0));
-  });
-
-  it("extracts ms at the 48-bit boundary", () => {
-    const maxMs = 2 ** 48 - 1;
-    const usr = createId("usr", {
-      now: () => new Date(maxMs),
-      rng: (n) => new Uint8Array(n),
-    });
-    expect(usr.extractTimestamp(usr.generate())).toEqual(new Date(maxMs));
-  });
-
-  it("rejects timestamps that overflow 48 bits", () => {
-    const usr = createId("usr", {
-      now: () => new Date(2 ** 48),
-      rng: (n) => new Uint8Array(n),
-    });
-    expect(() => usr.generate()).toThrow();
-  });
-
-  it("rejects pre-epoch timestamps", () => {
-    const usr = createId("usr", {
-      now: () => new Date(-1),
-      rng: (n) => new Uint8Array(n),
-    });
-    expect(() => usr.generate()).toThrow();
-  });
-
-  it("handles maximal random bytes", () => {
-    const usr = createId("usr", {
-      now: () => new Date(0),
-      rng: (n) => new Uint8Array(n).fill(0xff),
-    });
-    const id = usr.generate();
-    expect(usr.is(id)).toBe(true);
-    expect(usr.extractTimestamp(id)).toEqual(new Date(0));
-  });
-
-  it("is() accepts only canonical form", () => {
-    const usr = createId("usr");
-    expect(usr.is("usr_01h7b3k9rqxn1cw3p9r8t2sgkz")).toBe(true);
-    expect(usr.is("USR_01H7B3K9RQXN1CW3P9R8T2SGKZ")).toBe(false); // uppercase
-    expect(usr.is("usr_Olh7b3k9rqxnIcw3p9r8t2sgkz")).toBe(false); // contains o/i/l aliases
-  });
-
-  it("parse() normalises lenient input to canonical form", () => {
-    const usr = createId("usr");
-    expect(usr.parse("USR_01H7B3K9rqxn4cw3p9r8t2sgkz")).toEqual("usr_01h7b3k9rqxn4cw3p9r8t2sgkz");
-    expect(usr.parse("usr_Olh7b3k9rqxnIcw3p9r8t2sgkz")).toEqual("usr_01h7b3k9rqxn1cw3p9r8t2sgkz");
-  });
-
-  it("safeParse() returns canonical form on success", () => {
-    const usr = createId("usr");
-    expect(usr.safeParse("usr_Olh7b3k9rqxnIcw3p9r8t2sgkz")).toEqual({
-      ok: true,
-      id: "usr_01h7b3k9rqxn1cw3p9r8t2sgkz",
-    });
-  });
-
-  it("safeParse() fails on bad input", () => {
-    const usr = createId("usr");
-    expect(usr.safeParse(null)).toEqual({ ok: false, error: "not_string" });
-    expect(usr.safeParse("org_Olh7b3k9rqxnIcw3p9r8t2sgkz")).toEqual({
-      ok: false,
-      error: "invalid_prefix",
-    });
-    expect(usr.safeParse("usr_01h7b3k9rqxn1cw3p9r8t2sgk!")).toEqual({
-      ok: false,
-      error: "invalid_base32",
-    });
-  });
-
-  it("cross-brand rejection", () => {
-    const org = createId("org");
-    const usr = createId("usr");
-    const orgId = org.generate();
-    expect(usr.is(orgId)).toBe(false);
-    expect(() => usr.parse(orgId)).toThrow();
-  });
-
-  it("brands containing o/i/l", () => {
-    const log = createId("log");
-    const logId = log.generate();
-    expect(log.is(logId)).toBe(true);
-  });
-
-  it("is() does not accept malformed inputs", () => {
-    const usr = createId("usr");
-    expect(usr.is(null)).toBe(false);
-    expect(usr.is("usr_")).toBe(false);
-    expect(usr.is("usr_!!!")).toBe(false);
-    expect(usr.is("usr_" + "a".repeat(25))).toBe(false); // wrong length
-  });
-
-  it("fails if brand is not exactly three a-z characters", () => {
-    expect(() => createId("a")).toThrow();
-    expect(() => createId("aaaa")).toThrow();
-    expect(() => createId("!@?")).toThrow();
-  });
-});

package/src/id.ts

@@ -1,133 +0,0 @@
-import { alphabet, decodeBase32, encodeBase32 } from "./base32.js";
-import { invariant } from "./invariant.js";
-
-export type Options = {
-  now: () => Date;
-  rng: (bytes: number) => Uint8Array;
-};
-
-const defaultOptions: Options = {
-  now: () => new Date(),
-  rng: (bytes: number) => crypto.getRandomValues(new Uint8Array(bytes)),
-};
-
-export type Prefix<Brand extends string> = `${Brand}_`;
-
-export type Id<Brand extends string> = `${Prefix<Brand>}${string}` & {
-  readonly __brand: Brand;
-};
-
-export type ParseError = "not_string" | "invalid_prefix" | "invalid_base32";
-
-export type ParseResult<Brand extends string> =
-  | { ok: true; id: Id<Brand> }
-  | { ok: false; error: ParseError };
-
-export type Codec<Brand extends string> = {
-  generate(): Id<Brand>;
-  is(value: unknown): value is Id<Brand>;
-  parse(value: unknown): Id<Brand>;
-  safeParse(value: unknown): ParseResult<Brand>;
-  extractTimestamp(id: Id<Brand>): Date;
-};
-
-const timestampByteLength = 6;
-const randomByteLength = 10;
-const totalByteLength = timestampByteLength + randomByteLength;
-const base32Length = Math.ceil((totalByteLength * 8) / 5);
-const replacePattern = /[ilo]/gi;
-const replaceMap = { o: "0", i: "1", l: "1" } as const;
-const replacer = (match: string) => {
-  invariant(match === "o" || match === "i" || match === "l", "invalid match");
-  return replaceMap[match];
-};
-
-const base32Pattern = new RegExp(`^[${alphabet}]{${base32Length}}$`);
-const brandPattern = /^[a-z]{3}$/;
-
-export function createId<Brand extends string>(
-  brand: Brand,
-  opts: Partial<Options> = {},
-): Codec<Brand> {
-  invariant(brandPattern.test(brand), "invalid brand, expected three lowercase a-z characters");
-
-  const options = {
-    ...defaultOptions,
-    ...opts,
-  } satisfies Options;
-
-  const prefix: Prefix<Brand> = `${brand}_`;
-
-  return {
-    generate: () => generate(prefix, options),
-    is: (value: unknown) => is(prefix, value),
-    parse: (value: unknown) => parse(prefix, value),
-    safeParse: (value: unknown) => safeParse(prefix, value),
-    extractTimestamp: (id: Id<Brand>) => extractTimestamp(prefix, id),
-  };
-}
-
-function safeParse<Brand extends string>(
-  prefix: Prefix<Brand>,
-  value: unknown,
-): ParseResult<Brand> {
-  if (typeof value !== "string") return { ok: false, error: "not_string" };
-  const lowercase = value.toLowerCase();
-  if (!lowercase.startsWith(prefix)) return { ok: false, error: "invalid_prefix" };
-
-  const base32 = lowercase.slice(prefix.length).replaceAll(replacePattern, replacer);
-
-  if (!base32Pattern.test(base32)) return { ok: false, error: "invalid_base32" };
-
-  const id = (prefix + base32) as Id<Brand>;
-  return { ok: true, id };
-}
-
-function parse<Brand extends string>(prefix: Prefix<Brand>, value: unknown): Id<Brand> {
-  const result = safeParse(prefix, value);
-  if (result.ok) return result.id;
-  throw new Error(`Invalid ID: ${result.error}`);
-}
-
-function is<Brand extends string>(prefix: Prefix<Brand>, value: unknown): value is Id<Brand> {
-  if (typeof value !== "string") return false;
-  if (!value.startsWith(prefix)) return false;
-  return base32Pattern.test(value.slice(prefix.length));
-}
-
-function encodeNumberToUint8Array(value: number, bytes: number): Uint8Array {
-  invariant(value >= 0, "value is negative");
-  invariant(value < 2 ** (bytes * 8), `value exceeds ${bytes * 8}-bit range`);
-  const result = new Uint8Array(bytes);
-  // iterate backwards to encode in big-endian
-  for (let i = bytes - 1; i >= 0; i--) {
-    // we encode via 256 as bitwise ops will coerce to 32-bit integers
-    result[i] = value % 256;
-    value = Math.floor(value / 256);
-  }
-  return result;
-}
-
-function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
-  const result = new Uint8Array(a.length + b.length);
-  result.set(a, 0);
-  result.set(b, a.length);
-  return result;
-}
-
-function generate<Brand extends string>(prefix: Prefix<Brand>, options: Options): Id<Brand> {
-  const timestamp = encodeNumberToUint8Array(options.now().getTime(), timestampByteLength);
-  const rand = options.rng(randomByteLength);
-  return (prefix + encodeBase32(concat(timestamp, rand))) as Id<Brand>;
-}
-
-function extractTimestamp<Brand extends string>(prefix: Prefix<Brand>, id: Id<Brand>): Date {
-  const base32 = id.slice(prefix.length);
-  const bytes = decodeBase32(base32);
-  const timestampBytes = bytes.subarray(0, timestampByteLength);
-  let ms = 0;
-  for (const byte of timestampBytes) {
-    ms = ms * 256 + byte;
-  }
-  return new Date(ms);
-}

package/src/index.ts

@@ -1,8 +0,0 @@
-export {
-  type Codec,
-  type Id,
-  type Options,
-  type ParseError,
-  type ParseResult,
-  createId,
-} from "./id.js";

package/src/invariant.ts

@@ -1,3 +0,0 @@
-export function invariant(condition: unknown, message: string): asserts condition {
-  if (!condition) throw new Error(message);
-}

package/tsconfig.json

@@ -1,31 +0,0 @@
-{
-  "$schema": "https://www.schemastore.org/tsconfig",
-  "compilerOptions": {
-    "forceConsistentCasingInFileNames": true,
-    "lib": ["es2024", "ESNext.Array", "ESNext.Collection", "ESNext.Iterator", "ESNext.Promise"],
-    "module": "preserve",
-    "target": "es2024",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "allowUnusedLabels": false,
-    "allowUnreachableCode": false,
-    "exactOptionalPropertyTypes": true,
-    "noFallthroughCasesInSwitch": true,
-    "noImplicitOverride": true,
-    "noImplicitReturns": true,
-    "declaration": true,
-    "noPropertyAccessFromIndexSignature": true,
-    "noUncheckedIndexedAccess": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "isolatedModules": true,
-    "isolatedDeclarations": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "rewriteRelativeImportExtensions": true,
-    "erasableSyntaxOnly": true,
-    "verbatimModuleSyntax": true,
-    "types": ["node"]
-  },
-  "include": ["src"]
-}

package/tsdown.config.ts

@@ -1,10 +0,0 @@
-import { defineConfig } from "tsdown";
-
-export default defineConfig({
-  dts: {
-    sourcemap: true,
-  },
-  sourcemap: true,
-  platform: "node",
-  exports: true,
-});

package/vitest.config.ts

@@ -1,9 +0,0 @@
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    coverage: {
-      provider: "v8",
-    },
-  },
-});