@ingram-tech/nk-db 0.4.0 → 0.5.0

package/dist/id.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The Ingram id codec — a UUIDv7 and its base58 skin. It lives here in nk-db
+ * (the lowest package in the graph) behind the `@ingram-tech/nk-db/id` subpath,
+ * so it stays `node:crypto`-only — no `pg` / `drizzle` — and any site can mint
+ * ids without pulling a heavier slice.
+ *
+ * The Python twin lives in cloud.ingram.tech's `v1/core.py` (`new_id`); the
+ * byte → string vectors in `id.test.ts` and that repo's `tests/test_ids.py` are
+ * kept identical, so a stored UUIDv7 and an `agt_` / `smt_` id from the API are
+ * the same encoding of the same 16 bytes. That cross-impl contract is the most
+ * important property of this file — keep the vectors in lockstep.
+ *
+ * Store the hyphenated UUIDv7 at rest (uuid columns stay native and time-ordered
+ * for index locality) and use {@link toPrefixedId} to skin it as a prefixed
+ * base58 id for the wire / display, {@link fromPrefixedId} to recover it.
+ * {@link base58Id} mints a fresh one directly; {@link createIdRegistry} builds a
+ * typed, prefix-validated set of helpers for a project's entities.
+ */
+/**
+ * Mint a **UUIDv7** (RFC 9562): a 48-bit Unix-ms timestamp prefix + random tail,
+ * version `7`, variant `10`. UUID-shaped (drops straight into a `uuid` column)
+ * while staying time-ordered for index locality. Used as Better Auth's
+ * `advanced.database.generateId`. Node/Bun's `randomUUID` is v4-only, so we lay
+ * the bytes out by hand.
+ */
+export declare const uuidGenerateId: () => string;
+/** Skin a stored hyphenated UUIDv7 as a prefixed base58 id, e.g. `team_…`. */
+export declare function toPrefixedId(uuid: string, prefix: string): string;
+/** Inverse of {@link toPrefixedId}: recover the hyphenated UUIDv7. */
+export declare function fromPrefixedId(id: string): string;
+/** Mint a fresh prefixed base58 id (UUIDv7 core), for text-id sites / API parity. */
+export declare function base58Id(prefix: string): string;
+/** Typed helpers for one entity's prefixed ids — built by {@link createIdRegistry}. */
+export interface IdHelper {
+    /** This entity's prefix, e.g. `"agt"` (no trailing underscore). */
+    readonly prefix: string;
+    /** Mint a fresh prefixed id (new UUIDv7 core). */
+    mint(): string;
+    /** Skin a stored hyphenated UUIDv7 as this entity's prefixed id. */
+    encode(uuid: string): string;
+    /** Recover the hyphenated UUIDv7; throws if the prefix / shape doesn't match. */
+    decode(id: string): string;
+    /** Whether `id` is a well-formed prefixed id for this entity. */
+    is(id: string): boolean;
+}
+/** The map returned by {@link createIdRegistry}: one {@link IdHelper} per key. */
+export type IdRegistry<K extends string> = Record<K, IdHelper>;
+/**
+ * Build a typed, prefix-validated id registry for a project's entities — one
+ * place to declare every prefix instead of hand-rolling encode/decode wrappers:
+ *
+ * ```ts
+ * const ids = createIdRegistry({ org: "org", agent: "agt", session: "cs" });
+ * ids.org.mint();          // "org_3k9…"
+ * ids.org.encode(uuid);    // "org_…"
+ * ids.org.decode("org_…"); // uuid — throws on a wrong / missing prefix
+ * ids.agent.is(someId);    // boolean
+ * ```
+ */
+export declare function createIdRegistry<const T extends Record<string, string>>(prefixes: T): {
+    [K in keyof T]: IdHelper;
+};
+//# sourceMappingURL=id.d.ts.map

package/dist/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAAO,MAYjC,CAAC;AAuDF,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,uFAAuF;AACvF,MAAM,WAAW,QAAQ;IACxB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,IAAI,IAAI,MAAM,CAAC;IACf,oEAAoE;IACpE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,iFAAiF;IACjF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,iEAAiE;IACjE,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,kFAAkF;AAClF,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;AAiB/D;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtE,QAAQ,EAAE,CAAC,GACT;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,QAAQ;CAAE,CAM9B"}

package/dist/id.js

@@ -0,0 +1,138 @@
+import { randomBytes } from "node:crypto";
+/**
+ * The Ingram id codec — a UUIDv7 and its base58 skin. It lives here in nk-db
+ * (the lowest package in the graph) behind the `@ingram-tech/nk-db/id` subpath,
+ * so it stays `node:crypto`-only — no `pg` / `drizzle` — and any site can mint
+ * ids without pulling a heavier slice.
+ *
+ * The Python twin lives in cloud.ingram.tech's `v1/core.py` (`new_id`); the
+ * byte → string vectors in `id.test.ts` and that repo's `tests/test_ids.py` are
+ * kept identical, so a stored UUIDv7 and an `agt_` / `smt_` id from the API are
+ * the same encoding of the same 16 bytes. That cross-impl contract is the most
+ * important property of this file — keep the vectors in lockstep.
+ *
+ * Store the hyphenated UUIDv7 at rest (uuid columns stay native and time-ordered
+ * for index locality) and use {@link toPrefixedId} to skin it as a prefixed
+ * base58 id for the wire / display, {@link fromPrefixedId} to recover it.
+ * {@link base58Id} mints a fresh one directly; {@link createIdRegistry} builds a
+ * typed, prefix-validated set of helpers for a project's entities.
+ */
+/**
+ * Mint a **UUIDv7** (RFC 9562): a 48-bit Unix-ms timestamp prefix + random tail,
+ * version `7`, variant `10`. UUID-shaped (drops straight into a `uuid` column)
+ * while staying time-ordered for index locality. Used as Better Auth's
+ * `advanced.database.generateId`. Node/Bun's `randomUUID` is v4-only, so we lay
+ * the bytes out by hand.
+ */
+export const uuidGenerateId = () => {
+    const bytes = randomBytes(16);
+    const ts = Date.now();
+    bytes[0] = Math.floor(ts / 2 ** 40) & 0xff;
+    bytes[1] = Math.floor(ts / 2 ** 32) & 0xff;
+    bytes[2] = Math.floor(ts / 2 ** 24) & 0xff;
+    bytes[3] = Math.floor(ts / 2 ** 16) & 0xff;
+    bytes[4] = Math.floor(ts / 2 ** 8) & 0xff;
+    bytes[5] = ts & 0xff;
+    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x70; // version 7
+    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80; // variant 10
+    return bytesToUuid(bytes);
+};
+const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+// ceil(128 / log2(58)): a 16-byte value never needs more than 22 digits. We
+// left-pad to it so every body is uniform width and sorts lexically ==
+// chronologically (UUIDv7's ms-timestamp prefix lives in the high bytes).
+const WIDTH = 22;
+// A bare base58 body: 22 chars, Bitcoin alphabet (no 0 / I / O / l).
+const BODY = "[1-9A-HJ-NP-Za-km-z]{22}";
+/** Big-endian base58 (Bitcoin alphabet) of 16 bytes, left-padded to `WIDTH`. */
+function encode58(bytes) {
+    let n = 0n;
+    for (const b of bytes)
+        n = (n << 8n) | BigInt(b);
+    let out = "";
+    while (n > 0n) {
+        out = B58.charAt(Number(n % 58n)) + out;
+        n /= 58n;
+    }
+    return out.padStart(WIDTH, B58.charAt(0));
+}
+/** Inverse of {@link encode58}: a base58 body back to 16 bytes. */
+function decode58(body) {
+    let n = 0n;
+    for (const ch of body) {
+        const v = B58.indexOf(ch);
+        if (v < 0)
+            throw new Error(`invalid base58 char: ${ch}`);
+        n = n * 58n + BigInt(v);
+    }
+    const bytes = new Uint8Array(16);
+    for (let i = 15; i >= 0; i--) {
+        bytes[i] = Number(n & 0xffn);
+        n >>= 8n;
+    }
+    return bytes;
+}
+/** A hyphenated UUID string → its 16 raw bytes. */
+function uuidToBytes(uuid) {
+    const hex = uuid.replace(/-/g, "");
+    if (!/^[0-9a-fA-F]{32}$/.test(hex))
+        throw new Error(`not a uuid: ${uuid}`);
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) {
+        bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+/** 16 raw bytes → a canonical hyphenated UUID string. */
+function bytesToUuid(bytes) {
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** Skin a stored hyphenated UUIDv7 as a prefixed base58 id, e.g. `team_…`. */
+export function toPrefixedId(uuid, prefix) {
+    return `${prefix}_${encode58(uuidToBytes(uuid))}`;
+}
+/** Inverse of {@link toPrefixedId}: recover the hyphenated UUIDv7. */
+export function fromPrefixedId(id) {
+    const body = id.slice(id.indexOf("_") + 1);
+    return bytesToUuid(decode58(body));
+}
+/** Mint a fresh prefixed base58 id (UUIDv7 core), for text-id sites / API parity. */
+export function base58Id(prefix) {
+    return toPrefixedId(uuidGenerateId(), prefix);
+}
+function makeHelper(prefix) {
+    // Prefixes are developer-controlled identifier constants, never user input.
+    const matcher = new RegExp(`^${prefix}_${BODY}$`);
+    return {
+        prefix,
+        mint: () => base58Id(prefix),
+        encode: (uuid) => toPrefixedId(uuid, prefix),
+        decode: (id) => {
+            if (!matcher.test(id))
+                throw new Error(`not a ${prefix}_ id: ${id}`);
+            return fromPrefixedId(id);
+        },
+        is: (id) => matcher.test(id),
+    };
+}
+/**
+ * Build a typed, prefix-validated id registry for a project's entities — one
+ * place to declare every prefix instead of hand-rolling encode/decode wrappers:
+ *
+ * ```ts
+ * const ids = createIdRegistry({ org: "org", agent: "agt", session: "cs" });
+ * ids.org.mint();          // "org_3k9…"
+ * ids.org.encode(uuid);    // "org_…"
+ * ids.org.decode("org_…"); // uuid — throws on a wrong / missing prefix
+ * ids.agent.is(someId);    // boolean
+ * ```
+ */
+export function createIdRegistry(prefixes) {
+    const reg = {};
+    for (const [key, prefix] of Object.entries(prefixes)) {
+        reg[key] = makeHelper(prefix);
+    }
+    return reg;
+}
+//# sourceMappingURL=id.js.map

package/dist/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-db",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "The Ingram Postgres data layer: one TLS-aware pg pool, raw-SQL helpers, Drizzle wiring, and a PGlite (no-Docker) dev/test harness for Next.js sites.",
 	"license": "MIT",
 	"type": "module",
@@ -23,6 +23,10 @@
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js"
 		},
+		"./id": {
+			"types": "./dist/id.d.ts",
+			"import": "./dist/id.js"
+		},
 		"./pglite": {
 			"types": "./dist/pglite/index.d.ts",
 			"import": "./dist/pglite/index.js"