@tnid/core 0.0.1

package/script/types.d.ts

@@ -0,0 +1,93 @@
+/** Valid characters for TNID names (5-bit encoding): 0-4, a-z */
+export type NameChar = "0" | "1" | "2" | "3" | "4" | "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
+/** Recursive validation - check one character at a time to avoid type explosion */
+type ValidateNameChars<S extends string> = S extends "" ? true : S extends `${infer First}${infer Rest}` ? First extends NameChar ? ValidateNameChars<Rest> : false : false;
+/** Check string length is 1-4 using tuple length trick */
+type StringLength<S extends string, Acc extends unknown[] = []> = S extends "" ? Acc["length"] : S extends `${infer _}${infer Rest}` ? StringLength<Rest, [...Acc, unknown]> : never;
+type ValidLength = 1 | 2 | 3 | 4;
+/**
+ * Validate a TNID name at compile time.
+ * Must be 1-4 characters, each being a valid NameChar.
+ */
+export type ValidateName<S extends string> = ValidateNameChars<S> extends true ? StringLength<S> extends ValidLength ? S : never : never;
+/**
+ * A TNID value branded with its name. At runtime this is just a string.
+ *
+ * @example
+ * ```ts
+ * // Define a NamedTnid and matching type
+ * const UserId = Tnid("user");
+ * type UserId = TnidType<typeof UserId>;
+ *
+ * // Generate IDs
+ * const id: UserId = UserId.new_v0();          // time-sortable
+ * const id2: UserId = UserId.new_v1();         // high-entropy random
+ *
+ * // Parse from strings
+ * const parsed = UserId.parse("user.abc...");  // validates name matches
+ * const fromUuid = UserId.parseUuidString("d6157329-4640-8e30-...");
+ *
+ * // DynamicTnid - runtime name validation
+ * DynamicTnid.new_v0("item");                  // create with runtime name
+ * DynamicTnid.new_v1("item");                  // create with runtime name
+ * DynamicTnid.parse("post.xyz...");            // parse any TNID
+ * DynamicTnid.getName(id);                     // "user"
+ * DynamicTnid.getVariant(id);                  // "v0" | "v1" | "v2" | "v3"
+ *
+ * // UuidLike - wrapper for any UUID hex string
+ * UuidLike.fromTnid(id);                       // TNID to UUID string
+ * UuidLike.parse("d6157329-...");              // parse any UUID (format only)
+ * UuidLike.toTnid(uuid);                       // UUID to DynamicTnid (validates)
+ *
+ * // Type safety: different names are incompatible
+ * const PostId = Tnid("post");
+ * type PostId = TnidType<typeof PostId>;
+ * const postId: PostId = PostId.new_v0();
+ * // id = postId;  // Compile error!
+ *
+ * // DynamicTnid type accepts any TNID
+ * function log(id: DynamicTnid) { console.log(DynamicTnid.getName(id)); }
+ * log(id);      // works
+ * log(postId);  // works
+ * ```
+ */
+export type TnidValue<Name extends string> = string & {
+    tnid: Name;
+};
+/** TNID variant: v0=time-ordered, v1=random, v2/v3=reserved */
+export type TnidVariant = "v0" | "v1" | "v2" | "v3";
+/** Case for UUID hex string formatting. */
+export type Case = "lower" | "upper";
+export interface NamedTnid<Name extends string> {
+    /** The TNID name */
+    readonly name: Name;
+    /** Generate a new time-sortable TNID (variant 0) */
+    new_v0(): TnidValue<Name>;
+    /** Generate a new random TNID (variant 1) */
+    new_v1(): TnidValue<Name>;
+    /** Construct a V0 TNID from specific parts (for deterministic testing) */
+    v0_from_parts(timestampMs: bigint, randomBits: bigint): TnidValue<Name>;
+    /** Construct a V1 TNID from specific parts (for deterministic testing) */
+    v1_from_parts(randomBits: bigint): TnidValue<Name>;
+    /**
+     * Parse and validate a TNID string.
+     * @throws Error if the string is invalid or the name doesn't match
+     */
+    parse(s: string): TnidValue<Name>;
+    /**
+     * Parse a UUID hex string into a TNID.
+     * Validates that it's a valid UUIDv8 TNID and the name matches.
+     * @throws Error if the UUID is invalid or the name doesn't match
+     */
+    parseUuidString(uuid: string): TnidValue<Name>;
+    /** Get the name encoded as a 5-character hex string. */
+    nameHex(): string;
+    /** Get the variant of a TNID. */
+    variant(id: TnidValue<Name>): TnidVariant;
+    /** Convert a TNID to UUID hex string format. */
+    toUuidString(id: TnidValue<Name>, caseFormat?: Case): string;
+}
+/** Extract the `TnidValue` type from a NamedTnid. */
+export type TnidType<T> = T extends NamedTnid<infer N> ? TnidValue<N> : never;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/script/types.d.ts.map

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

package/script/types.js

@@ -0,0 +1,5 @@
+"use strict";
+// =============================================================================
+// TNID Type Definitions
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/script/uuid.d.ts

@@ -0,0 +1,17 @@
+import type { TnidVariant } from "./types.js";
+export declare const UUID_REGEX: RegExp;
+/** Convert a 128-bit value to UUID hex string format */
+export declare function valueToUuidString(value: bigint, upperCase?: boolean): string;
+/** Parse a UUID hex string to a 128-bit value */
+export declare function parseUuidStringToValue(uuid: string): bigint;
+/** Extract name bits from a 128-bit TNID value */
+export declare function extractNameBitsFromValue(value: bigint): number;
+/** Extract TNID variant from a 128-bit value */
+export declare function extractVariantFromValue(value: bigint): TnidVariant;
+/** Validate that a 128-bit value has correct UUIDv8 version and variant bits */
+export declare function validateUuidBits(value: bigint): boolean;
+/** Convert bytes to TNID string */
+export declare function bytesToTnidString(bytes: Uint8Array, name: string): string;
+/** Convert 128-bit value to TNID string */
+export declare function valueToTnidString(value: bigint): string;
+//# sourceMappingURL=uuid.d.ts.map

package/script/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,eAAO,MAAM,UAAU,QAC4C,CAAC;AAEpE,wDAAwD;AACxD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,OAAe,GACzB,MAAM,CAMR;AAED,iDAAiD;AACjD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM3D;AAED,kDAAkD;AAClD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,gDAAgD;AAChD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAIlE;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAUvD;AAED,mCAAmC;AACnC,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED,2CAA2C;AAC3C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKvD"}

package/script/uuid.js

@@ -0,0 +1,65 @@
+"use strict";
+// =============================================================================
+// UUID String Utilities
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UUID_REGEX = void 0;
+exports.valueToUuidString = valueToUuidString;
+exports.parseUuidStringToValue = parseUuidStringToValue;
+exports.extractNameBitsFromValue = extractNameBitsFromValue;
+exports.extractVariantFromValue = extractVariantFromValue;
+exports.validateUuidBits = validateUuidBits;
+exports.bytesToTnidString = bytesToTnidString;
+exports.valueToTnidString = valueToTnidString;
+const name_encoding_js_1 = require("./name_encoding.js");
+const data_encoding_js_1 = require("./data_encoding.js");
+const bits_js_1 = require("./bits.js");
+exports.UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Convert a 128-bit value to UUID hex string format */
+function valueToUuidString(value, upperCase = false) {
+    const hex = value.toString(16).padStart(32, "0");
+    const uuid = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    return upperCase ? uuid.toUpperCase() : uuid.toLowerCase();
+}
+/** Parse a UUID hex string to a 128-bit value */
+function parseUuidStringToValue(uuid) {
+    if (!exports.UUID_REGEX.test(uuid)) {
+        throw new Error(`Invalid UUID format: ${uuid}`);
+    }
+    const hex = uuid.replace(/-/g, "");
+    return BigInt("0x" + hex);
+}
+/** Extract name bits from a 128-bit TNID value */
+function extractNameBitsFromValue(value) {
+    return Number((value >> 108n) & 0xfffffn);
+}
+/** Extract TNID variant from a 128-bit value */
+function extractVariantFromValue(value) {
+    const variantBits = Number((value >> 60n) & 3n);
+    const variants = ["v0", "v1", "v2", "v3"];
+    return variants[variantBits];
+}
+/** Validate that a 128-bit value has correct UUIDv8 version and variant bits */
+function validateUuidBits(value) {
+    // Check UUID version (bits 76-79 should be 0x8)
+    const version = Number((value >> 76n) & 0xfn);
+    if (version !== 8)
+        return false;
+    // Check UUID variant (bits 62-63 should be 0b10)
+    const variant = Number((value >> 62n) & 3n);
+    if (variant !== 0b10)
+        return false;
+    return true;
+}
+/** Convert bytes to TNID string */
+function bytesToTnidString(bytes, name) {
+    const dataEncoded = (0, data_encoding_js_1.encodeData)(bytes);
+    return `${name}.${dataEncoded}`;
+}
+/** Convert 128-bit value to TNID string */
+function valueToTnidString(value) {
+    const nameBits = extractNameBitsFromValue(value);
+    const name = (0, name_encoding_js_1.decodeName)(nameBits);
+    const bytes = (0, bits_js_1.valueToBytes)(value);
+    return bytesToTnidString(bytes, name);
+}

package/script/uuidlike.d.ts

@@ -0,0 +1,17 @@
+import type { DynamicTnid } from "./dynamic.js";
+/** A UUID hex string (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) that may or may not be a valid TNID. */
+export type UuidLike = string & {
+    __uuidlike: true;
+};
+/** Wrapper for UUID hex strings that may or may not be valid TNIDs. */
+export declare const UuidLike: {
+    /** Create from a TNID (always valid). */
+    readonly fromTnid: (id: DynamicTnid) => UuidLike;
+    /** Parse UUID hex string (format validation only, not TNID validation). */
+    readonly parse: (s: string) => UuidLike;
+    /** Try to convert to DynamicTnid (validates TNID structure). */
+    readonly toTnid: (uuid: UuidLike) => DynamicTnid;
+    /** Format as uppercase UUID hex string. */
+    readonly toUpperCase: (uuid: UuidLike) => UuidLike;
+};
+//# sourceMappingURL=uuidlike.d.ts.map

package/script/uuidlike.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuidlike.d.ts","sourceRoot":"","sources":["../src/uuidlike.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,oGAAoG;AACpG,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,UAAU,EAAE,IAAI,CAAA;CAAE,CAAC;AAWrD,uEAAuE;AACvE,eAAO,MAAM,QAAQ;IACnB,yCAAyC;4BAC5B,WAAW,KAAG,QAAQ;IAInC,2EAA2E;wBAClE,MAAM,KAAG,QAAQ;IAQ1B,gEAAgE;4BACnD,QAAQ,KAAG,WAAW;IAanC,2CAA2C;iCACzB,QAAQ,KAAG,QAAQ;CAG7B,CAAC"}

package/script/uuidlike.js

@@ -0,0 +1,41 @@
+"use strict";
+// =============================================================================
+// UuidLike - Wrapper for UUID hex strings
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UuidLike = void 0;
+const name_encoding_js_1 = require("./name_encoding.js");
+const uuid_js_1 = require("./uuid.js");
+const dynamic_js_1 = require("./dynamic.js");
+/** Wrapper for UUID hex strings that may or may not be valid TNIDs. */
+exports.UuidLike = {
+    /** Create from a TNID (always valid). */
+    fromTnid(id) {
+        return (0, dynamic_js_1.toUuidStringImpl)(id, false);
+    },
+    /** Parse UUID hex string (format validation only, not TNID validation). */
+    parse(s) {
+        // Validate format only
+        if (!uuid_js_1.UUID_REGEX.test(s)) {
+            throw new Error(`Invalid UUID format: ${s}`);
+        }
+        return s.toLowerCase();
+    },
+    /** Try to convert to DynamicTnid (validates TNID structure). */
+    toTnid(uuid) {
+        const value = (0, uuid_js_1.parseUuidStringToValue)(uuid);
+        if (!(0, uuid_js_1.validateUuidBits)(value)) {
+            throw new Error("Invalid TNID: not a valid UUIDv8");
+        }
+        const nameBits = (0, uuid_js_1.extractNameBitsFromValue)(value);
+        const name = (0, name_encoding_js_1.decodeName)(nameBits);
+        if (!(0, name_encoding_js_1.isValidNameRuntime)(name)) {
+            throw new Error("Invalid TNID: invalid name encoding");
+        }
+        return (0, uuid_js_1.valueToTnidString)(value);
+    },
+    /** Format as uppercase UUID hex string. */
+    toUpperCase(uuid) {
+        return uuid.toUpperCase();
+    },
+};