@tnid/core 0.0.1

package/esm/bits.js

@@ -0,0 +1,91 @@
+// =============================================================================
+// Bit Manipulation and TNID Generation
+// Mask-based approach matching Rust implementation
+// =============================================================================
+// Masks for UUID version 8 and variant bits
+import * as dntShim from "./_dnt.shims.js";
+export const UUID_V8_MASK = 0x00000000000080008000000000000000n;
+// V1: 100 random bits scattered across the UUID
+export const V1_RANDOM_MASK = 0x00000fffffff0fff0fffffffffffffffn;
+// V0: 57 random bits in the lower portion
+export const V0_RANDOM_MASK = 0x000000000000000001ffffffffffffffn;
+// V0 timestamp masks (for extracting and placing 43-bit timestamp)
+const TIMESTAMP_FIRST_28_MASK = 0x000007ffffff8000n;
+const TIMESTAMP_SECOND_12_MASK = 0x0000000000007ff8n;
+const TIMESTAMP_LAST_3_MASK = 0x0000000000000007n;
+/** Place name bits in their correct position (bits 108-127) */
+export function nameMask(nameBits) {
+    return BigInt(nameBits) << 108n;
+}
+/** Place UUID version/variant and TNID variant in their correct positions */
+export function uuidAndVariantMask(tnidVariant) {
+    return UUID_V8_MASK | ((tnidVariant & 3n) << 60n);
+}
+/** Scatter 43-bit timestamp into its three positions within the 128-bit ID */
+export function millisMask(millisSinceEpoch) {
+    let mask = 0n;
+    // First 28 bits of timestamp → bits 80-107 of UUID
+    const first28LeadingZeros = 64n - 43n; // = 21, so mask starts at bit 42
+    mask |= (millisSinceEpoch & TIMESTAMP_FIRST_28_MASK) <<
+        (first28LeadingZeros + 64n - 20n);
+    // Middle 12 bits of timestamp → bits 64-75 of UUID (after version nibble)
+    const second12LeadingZeros = 64n - 15n; // = 49
+    mask |= (millisSinceEpoch & TIMESTAMP_SECOND_12_MASK) <<
+        (second12LeadingZeros + 64n - 52n);
+    // Last 3 bits of timestamp → bits 57-59 of UUID (after variant bits)
+    const last3LeadingZeros = 64n - 3n; // = 61
+    mask |= (millisSinceEpoch & TIMESTAMP_LAST_3_MASK) <<
+        (last3LeadingZeros + 64n - 68n);
+    return mask;
+}
+/** Build a 128-bit TNID value using mask-based OR operations */
+export function buildTnidValue(nameBits, payloadMask, tnidVariant) {
+    return nameMask(nameBits) | uuidAndVariantMask(tnidVariant) | payloadMask;
+}
+/** Convert 128-bit value to byte array */
+export function valueToBytes(value) {
+    const bytes = new Uint8Array(16);
+    let v = value;
+    for (let i = 15; i >= 0; i--) {
+        bytes[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return bytes;
+}
+/** Generate a V0 (time-ordered) TNID as bytes */
+export function generateV0(nameBits, timestampMs, randomBits) {
+    const timestamp = timestampMs !== undefined
+        ? timestampMs & ((1n << 43n) - 1n)
+        : BigInt(Date.now()) & ((1n << 43n) - 1n);
+    let random;
+    if (randomBits !== undefined) {
+        random = randomBits;
+    }
+    else {
+        const randomBytes = dntShim.crypto.getRandomValues(new Uint8Array(8));
+        random = 0n;
+        for (const byte of randomBytes) {
+            random = (random << 8n) | BigInt(byte);
+        }
+    }
+    const payloadMask = millisMask(timestamp) | (random & V0_RANDOM_MASK);
+    const value = buildTnidValue(nameBits, payloadMask, 0n);
+    return valueToBytes(value);
+}
+/** Generate a V1 (high-entropy random) TNID as bytes */
+export function generateV1(nameBits, randomBits) {
+    let random;
+    if (randomBits !== undefined) {
+        random = randomBits;
+    }
+    else {
+        const randomBytes = dntShim.crypto.getRandomValues(new Uint8Array(16));
+        random = 0n;
+        for (const byte of randomBytes) {
+            random = (random << 8n) | BigInt(byte);
+        }
+    }
+    const payloadMask = random & V1_RANDOM_MASK;
+    const value = buildTnidValue(nameBits, payloadMask, 1n);
+    return valueToBytes(value);
+}

package/esm/data_encoding.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Encode a 16-byte TNID value as a 17-character data string.
+ */
+export declare function encodeData(bytes: Uint8Array): string;
+/**
+ * Decode a 17-character data string to data bits and TNID variant.
+ */
+export declare function decodeData(encoded: string): {
+    dataBits: bigint;
+    tnidVariant: number;
+};
+/**
+ * Convert data bits back to a 16-byte array.
+ */
+export declare function dataBitsToBytes(dataBits: bigint, nameBits: number): Uint8Array;
+//# sourceMappingURL=data_encoding.d.ts.map

package/esm/data_encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data_encoding.d.ts","sourceRoot":"","sources":["../src/data_encoding.ts"],"names":[],"mappings":"AA6BA;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAgCpD;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,GACd;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAmB3C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CA8B9E"}

package/esm/data_encoding.js

@@ -0,0 +1,103 @@
+// =============================================================================
+// Data Encoding - 6-bit encoding for the data portion
+// 64 characters in order: - 0-9 A-Z _ a-z
+// =============================================================================
+const DATA_CHAR_TO_VALUE = {};
+const DATA_VALUE_TO_CHAR = [];
+const DATA_ENCODING_ORDER = "-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz";
+for (let i = 0; i < DATA_ENCODING_ORDER.length; i++) {
+    const char = DATA_ENCODING_ORDER[i];
+    DATA_CHAR_TO_VALUE[char] = i;
+    DATA_VALUE_TO_CHAR[i] = char;
+}
+// The data portion is 102 bits encoded as 17 6-bit characters (102 = 17 * 6)
+//
+// 128-bit layout (MSB = bit 0):
+//   Bits 0-19:   Name (20 bits) - NOT in data encoding
+//   Bits 20-47:  Payload A (28 bits)
+//   Bits 48-51:  UUID version (4 bits) - NOT in data encoding
+//   Bits 52-63:  Payload B (12 bits)
+//   Bits 64-65:  UUID variant (2 bits) - NOT in data encoding
+//   Bits 66-67:  TNID variant (2 bits)
+//   Bits 68-127: Payload C (60 bits)
+//
+// Data bits = PayloadA(28) + PayloadB(12) + TNIDVariant(2) + PayloadC(60) = 102 bits
+/**
+ * Encode a 16-byte TNID value as a 17-character data string.
+ */
+export function encodeData(bytes) {
+    // Convert bytes to BigInt (MSB first)
+    let value = 0n;
+    for (const byte of bytes) {
+        value = (value << 8n) | BigInt(byte);
+    }
+    // Extract the parts (positions from LSB = 127 - MSB_position)
+    // MSB bits 20-47 = LSB bits 80-107 (28 bits)
+    const payloadA = (value >> 80n) & ((1n << 28n) - 1n);
+    // MSB bits 52-63 = LSB bits 64-75 (12 bits)
+    const payloadB = (value >> 64n) & ((1n << 12n) - 1n);
+    // MSB bits 66-67 = LSB bits 60-61 (2 bits)
+    const tnidVariant = (value >> 60n) & 3n;
+    // MSB bits 68-127 = LSB bits 0-59 (60 bits)
+    const payloadC = value & ((1n << 60n) - 1n);
+    // Combine into 102 data bits: A(28) + B(12) + variant(2) + C(60)
+    const dataBits = (payloadA << 74n) | (payloadB << 62n) |
+        (tnidVariant << 60n) | payloadC;
+    // Encode as 17 6-bit characters
+    let result = "";
+    for (let i = 16; i >= 0; i--) {
+        const charValue = Number((dataBits >> BigInt(i * 6)) & 0x3fn);
+        result += DATA_VALUE_TO_CHAR[charValue];
+    }
+    return result;
+}
+/**
+ * Decode a 17-character data string to data bits and TNID variant.
+ */
+export function decodeData(encoded) {
+    if (encoded.length !== 17) {
+        throw new Error(`Invalid data length: expected 17, got ${encoded.length}`);
+    }
+    let dataBits = 0n;
+    for (let i = 0; i < 17; i++) {
+        const char = encoded[i];
+        const value = DATA_CHAR_TO_VALUE[char];
+        if (value === undefined) {
+            throw new Error(`Invalid data character: ${char}`);
+        }
+        dataBits = (dataBits << 6n) | BigInt(value);
+    }
+    // Extract TNID variant (bits 60-61 from the right of the 102-bit value)
+    const tnidVariant = Number((dataBits >> 60n) & 3n);
+    return { dataBits, tnidVariant };
+}
+/**
+ * Convert data bits back to a 16-byte array.
+ */
+export function dataBitsToBytes(dataBits, nameBits) {
+    // Reconstruct the full 128-bit value from 102 data bits
+    // Data bits layout: payloadA(28) + payloadB(12) + tnid_var(2) + payloadC(60) = 102 bits
+    //
+    // 128-bit layout:
+    //   name(20) + payloadA(28) + uuid_ver(4) + payloadB(12) + uuid_var(2) + tnid_var(2) + payloadC(60)
+    // Extract from dataBits (102 bits total):
+    const payloadA = (dataBits >> 74n) & ((1n << 28n) - 1n); // bits 74-101
+    const payloadB = (dataBits >> 62n) & ((1n << 12n) - 1n); // bits 62-73
+    const tnidVariant = (dataBits >> 60n) & 3n; // bits 60-61
+    const payloadC = dataBits & ((1n << 60n) - 1n); // bits 0-59
+    // Reconstruct 128-bit value
+    let value = BigInt(nameBits);
+    value = (value << 28n) | payloadA;
+    value = (value << 4n) | 0x8n; // UUID version 8
+    value = (value << 12n) | payloadB;
+    value = (value << 2n) | 2n; // UUID variant
+    value = (value << 2n) | tnidVariant;
+    value = (value << 60n) | payloadC;
+    // Convert to bytes
+    const bytes = new Uint8Array(16);
+    for (let i = 15; i >= 0; i--) {
+        bytes[i] = Number(value & 0xffn);
+        value >>= 8n;
+    }
+    return bytes;
+}

package/esm/dynamic.d.ts

@@ -0,0 +1,36 @@
+import type { Case, TnidValue, TnidVariant } from "./types.js";
+/** A TNID that can hold any name. Use for generic functions. */
+export type DynamicTnid = TnidValue<string>;
+declare function getTnidVariantImpl(id: DynamicTnid): TnidVariant;
+declare function toUuidStringImpl(id: DynamicTnid, upperCase?: boolean): string;
+/** Static methods for working with any TNID regardless of name. */
+export declare const DynamicTnid: {
+    /** Generate a new time-sortable TNID (variant 0) with runtime name validation. */
+    readonly new_v0: (name: string) => DynamicTnid;
+    /** Alias for new_v0. */
+    readonly new_time_ordered: (name: string) => DynamicTnid;
+    /** Generate a new time-sortable TNID with a specific timestamp. */
+    readonly new_v0_with_time: (name: string, time: Date) => DynamicTnid;
+    /** Generate a new time-sortable TNID with explicit timestamp and random components. */
+    readonly new_v0_with_parts: (name: string, epochMillis: bigint, random: bigint) => DynamicTnid;
+    /** Generate a new high-entropy TNID (variant 1) with runtime name validation. */
+    readonly new_v1: (name: string) => DynamicTnid;
+    /** Alias for new_v1. */
+    readonly new_high_entropy: (name: string) => DynamicTnid;
+    /** Generate a new high-entropy TNID with explicit random bits. */
+    readonly new_v1_with_random: (name: string, randomBits: bigint) => DynamicTnid;
+    /** Parse any valid TNID string. */
+    readonly parse: (s: string) => DynamicTnid;
+    /** Parse a UUID hex string into a DynamicTnid (validates TNID structure). */
+    readonly parse_uuid_string: (uuid: string) => DynamicTnid;
+    /** Get the name from a TNID. */
+    readonly getName: (id: DynamicTnid) => string;
+    /** Get the name encoded as a 5-character hex string. */
+    readonly getNameHex: (id: DynamicTnid) => string;
+    /** Get the variant of a TNID. */
+    readonly getVariant: (id: DynamicTnid) => TnidVariant;
+    /** Convert to UUID hex string format. */
+    readonly toUuidString: (id: DynamicTnid, caseFormat?: Case) => string;
+};
+export { getTnidVariantImpl, toUuidStringImpl, };
+//# sourceMappingURL=dynamic.d.ts.map

package/esm/dynamic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic.d.ts","sourceRoot":"","sources":["../src/dynamic.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE/D,gEAAgE;AAChE,MAAM,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;AAgB5C,iBAAS,kBAAkB,CAAC,EAAE,EAAE,WAAW,GAAG,WAAW,CASxD;AAiBD,iBAAS,gBAAgB,CAAC,EAAE,EAAE,WAAW,EAAE,SAAS,GAAE,OAAe,GAAG,MAAM,CAmB7E;AAmDD,mEAAmE;AACnE,eAAO,MAAM,WAAW;IACtB,kFAAkF;4BACrE,MAAM,KAAG,WAAW;IAYjC,wBAAwB;sCACD,MAAM,KAAG,WAAW;IAI3C,mEAAmE;sCAC5C,MAAM,QAAQ,IAAI,KAAG,WAAW;IAavD,uFAAuF;uCAE/E,MAAM,eACC,MAAM,UACX,MAAM,KACb,WAAW;IAYd,iFAAiF;4BACpE,MAAM,KAAG,WAAW;IAYjC,wBAAwB;sCACD,MAAM,KAAG,WAAW;IAI3C,kEAAkE;wCACzC,MAAM,cAAc,MAAM,KAAG,WAAW;IAYjE,mCAAmC;wBAC1B,MAAM,KAAG,WAAW;IAI7B,6EAA6E;uCACrD,MAAM,KAAG,WAAW;IAI5C,gCAAgC;2BACpB,WAAW,KAAG,MAAM;IAIhC,wDAAwD;8BACzC,WAAW,KAAG,MAAM;IAInC,iCAAiC;8BAClB,WAAW,KAAG,WAAW;IAIxC,yCAAyC;gCACxB,WAAW,eAAc,IAAI,KAAa,MAAM;CAGzD,CAAC;AAGX,OAAO,EACL,kBAAkB,EAClB,gBAAgB,GACjB,CAAC"}

package/esm/dynamic.js

@@ -0,0 +1,173 @@
+// =============================================================================
+// DynamicTnid - Runtime name validation
+// =============================================================================
+import { encodeName, decodeName, isValidNameRuntime } from "./name_encoding.js";
+import { encodeData, decodeData, dataBitsToBytes } from "./data_encoding.js";
+import { generateV0, generateV1 } from "./bits.js";
+import { parseUuidStringToValue, validateUuidBits, extractNameBitsFromValue, valueToTnidString, valueToUuidString, } from "./uuid.js";
+// -----------------------------------------------------------------------------
+// Internal Helper Functions
+// -----------------------------------------------------------------------------
+function getTnidVariantImpl(id) {
+    const dotIndex = id.indexOf(".");
+    if (dotIndex === -1) {
+        throw new Error("Invalid TNID: missing separator");
+    }
+    const dataEncoded = id.substring(dotIndex + 1);
+    const { tnidVariant } = decodeData(dataEncoded);
+    const variants = ["v0", "v1", "v2", "v3"];
+    return variants[tnidVariant];
+}
+function getTnidNameImpl(id) {
+    const dotIndex = id.indexOf(".");
+    if (dotIndex === -1) {
+        throw new Error("Invalid TNID: missing separator");
+    }
+    return id.substring(0, dotIndex);
+}
+function getNameHexImpl(id) {
+    const name = getTnidNameImpl(id);
+    const nameBits = encodeName(name);
+    // Format as 5 hex characters (20 bits)
+    return nameBits.toString(16).padStart(5, "0");
+}
+function toUuidStringImpl(id, upperCase = false) {
+    const dotIndex = id.indexOf(".");
+    if (dotIndex === -1) {
+        throw new Error("Invalid TNID: missing separator");
+    }
+    const name = id.substring(0, dotIndex);
+    const dataEncoded = id.substring(dotIndex + 1);
+    const nameBits = encodeName(name);
+    const { dataBits } = decodeData(dataEncoded);
+    const bytes = dataBitsToBytes(dataBits, nameBits);
+    let value = 0n;
+    for (const byte of bytes) {
+        value = (value << 8n) | BigInt(byte);
+    }
+    return valueToUuidString(value, upperCase);
+}
+function parseDynamicTnidImpl(s) {
+    const dotIndex = s.indexOf(".");
+    if (dotIndex === -1) {
+        throw new Error("Invalid TNID string: missing '.' separator");
+    }
+    const name = s.substring(0, dotIndex);
+    const dataEncoded = s.substring(dotIndex + 1);
+    if (!isValidNameRuntime(name)) {
+        throw new Error(`Invalid TNID name: "${name}"`);
+    }
+    // Validate data portion
+    const nameBits = encodeName(name);
+    const { dataBits } = decodeData(dataEncoded);
+    // Verify we can reconstruct it (validates the encoding)
+    const reconstructed = dataBitsToBytes(dataBits, nameBits);
+    const reencoded = encodeData(reconstructed);
+    if (reencoded !== dataEncoded) {
+        throw new Error("Invalid TNID data encoding");
+    }
+    return s;
+}
+function parseDynamicUuidStringImpl(uuid) {
+    const value = parseUuidStringToValue(uuid);
+    if (!validateUuidBits(value)) {
+        throw new Error("Invalid TNID: not a valid UUIDv8");
+    }
+    const nameBits = extractNameBitsFromValue(value);
+    const name = decodeName(nameBits);
+    if (!isValidNameRuntime(name)) {
+        throw new Error(`Invalid TNID: invalid name encoding`);
+    }
+    return valueToTnidString(value);
+}
+// -----------------------------------------------------------------------------
+// DynamicTnid Namespace
+// -----------------------------------------------------------------------------
+/** Static methods for working with any TNID regardless of name. */
+export const DynamicTnid = {
+    /** Generate a new time-sortable TNID (variant 0) with runtime name validation. */
+    new_v0(name) {
+        if (!isValidNameRuntime(name)) {
+            throw new Error(`Invalid TNID name: "${name}". Must be 1-4 characters of: 0-4, a-z`);
+        }
+        const nameBits = encodeName(name);
+        const bytes = generateV0(nameBits);
+        const dataEncoded = encodeData(bytes);
+        return `${name}.${dataEncoded}`;
+    },
+    /** Alias for new_v0. */
+    new_time_ordered(name) {
+        return DynamicTnid.new_v0(name);
+    },
+    /** Generate a new time-sortable TNID with a specific timestamp. */
+    new_v0_with_time(name, time) {
+        if (!isValidNameRuntime(name)) {
+            throw new Error(`Invalid TNID name: "${name}". Must be 1-4 characters of: 0-4, a-z`);
+        }
+        const nameBits = encodeName(name);
+        const timestampMs = BigInt(time.getTime());
+        const bytes = generateV0(nameBits, timestampMs);
+        const dataEncoded = encodeData(bytes);
+        return `${name}.${dataEncoded}`;
+    },
+    /** Generate a new time-sortable TNID with explicit timestamp and random components. */
+    new_v0_with_parts(name, epochMillis, random) {
+        if (!isValidNameRuntime(name)) {
+            throw new Error(`Invalid TNID name: "${name}". Must be 1-4 characters of: 0-4, a-z`);
+        }
+        const nameBits = encodeName(name);
+        const bytes = generateV0(nameBits, epochMillis, random);
+        const dataEncoded = encodeData(bytes);
+        return `${name}.${dataEncoded}`;
+    },
+    /** Generate a new high-entropy TNID (variant 1) with runtime name validation. */
+    new_v1(name) {
+        if (!isValidNameRuntime(name)) {
+            throw new Error(`Invalid TNID name: "${name}". Must be 1-4 characters of: 0-4, a-z`);
+        }
+        const nameBits = encodeName(name);
+        const bytes = generateV1(nameBits);
+        const dataEncoded = encodeData(bytes);
+        return `${name}.${dataEncoded}`;
+    },
+    /** Alias for new_v1. */
+    new_high_entropy(name) {
+        return DynamicTnid.new_v1(name);
+    },
+    /** Generate a new high-entropy TNID with explicit random bits. */
+    new_v1_with_random(name, randomBits) {
+        if (!isValidNameRuntime(name)) {
+            throw new Error(`Invalid TNID name: "${name}". Must be 1-4 characters of: 0-4, a-z`);
+        }
+        const nameBits = encodeName(name);
+        const bytes = generateV1(nameBits, randomBits);
+        const dataEncoded = encodeData(bytes);
+        return `${name}.${dataEncoded}`;
+    },
+    /** Parse any valid TNID string. */
+    parse(s) {
+        return parseDynamicTnidImpl(s);
+    },
+    /** Parse a UUID hex string into a DynamicTnid (validates TNID structure). */
+    parse_uuid_string(uuid) {
+        return parseDynamicUuidStringImpl(uuid);
+    },
+    /** Get the name from a TNID. */
+    getName(id) {
+        return getTnidNameImpl(id);
+    },
+    /** Get the name encoded as a 5-character hex string. */
+    getNameHex(id) {
+        return getNameHexImpl(id);
+    },
+    /** Get the variant of a TNID. */
+    getVariant(id) {
+        return getTnidVariantImpl(id);
+    },
+    /** Convert to UUID hex string format. */
+    toUuidString(id, caseFormat = "lower") {
+        return toUuidStringImpl(id, caseFormat === "upper");
+    },
+};
+// Export helper functions for use by factory.ts
+export { getTnidVariantImpl, toUuidStringImpl, };

package/esm/factory.d.ts

@@ -0,0 +1,27 @@
+import type { NamedTnid, ValidateName } from "./types.js";
+/**
+ * Create a NamedTnid for the given name.
+ *
+ * The name is validated at **compile time** - only 1-4 characters using `0-4` and `a-z`.
+ * Invalid names will produce a TypeScript error.
+ *
+ * @example
+ * ```ts
+ * const UserId = Tnid("user");
+ * type UserId = TnidType<typeof UserId>;
+ *
+ * const id = UserId.new_v0();        // Generate new ID
+ * const parsed = UserId.parse(str);  // Parse existing ID
+ * ```
+ *
+ * @example
+ * ```ts
+ * // These produce compile errors:
+ * Tnid("users")  // Too long (max 4 chars)
+ * Tnid("User")   // Uppercase not allowed
+ * Tnid("a-b")    // Hyphen not allowed
+ * Tnid("5")      // Only digits 0-4 allowed
+ * ```
+ */
+export declare function Tnid<const Name extends string>(name: ValidateName<Name>): NamedTnid<Name>;
+//# sourceMappingURL=factory.d.ts.map

package/esm/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,SAAS,EAGT,YAAY,EACb,MAAM,YAAY,CAAC;AAapB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,EAC5C,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,GACvB,SAAS,CAAC,IAAI,CAAC,CAsGjB"}

package/esm/factory.js

@@ -0,0 +1,107 @@
+// =============================================================================
+// Tnid Function
+// =============================================================================
+import { encodeName, decodeName, isValidNameRuntime } from "./name_encoding.js";
+import { encodeData, decodeData, dataBitsToBytes } from "./data_encoding.js";
+import { generateV0, generateV1 } from "./bits.js";
+import { parseUuidStringToValue, validateUuidBits, extractNameBitsFromValue, valueToTnidString, } from "./uuid.js";
+import { getTnidVariantImpl, toUuidStringImpl } from "./dynamic.js";
+/**
+ * Create a NamedTnid for the given name.
+ *
+ * The name is validated at **compile time** - only 1-4 characters using `0-4` and `a-z`.
+ * Invalid names will produce a TypeScript error.
+ *
+ * @example
+ * ```ts
+ * const UserId = Tnid("user");
+ * type UserId = TnidType<typeof UserId>;
+ *
+ * const id = UserId.new_v0();        // Generate new ID
+ * const parsed = UserId.parse(str);  // Parse existing ID
+ * ```
+ *
+ * @example
+ * ```ts
+ * // These produce compile errors:
+ * Tnid("users")  // Too long (max 4 chars)
+ * Tnid("User")   // Uppercase not allowed
+ * Tnid("a-b")    // Hyphen not allowed
+ * Tnid("5")      // Only digits 0-4 allowed
+ * ```
+ */
+export function Tnid(name) {
+    // Runtime validation (belt and suspenders)
+    if (!isValidNameRuntime(name)) {
+        throw new Error(`Invalid TNID name: "${name}". Must be 1-4 characters of: 0-4, a-z`);
+    }
+    const nameBits = encodeName(name);
+    const tnid = {
+        name: name,
+        new_v0() {
+            const bytes = generateV0(nameBits);
+            const dataEncoded = encodeData(bytes);
+            return `${name}.${dataEncoded}`;
+        },
+        new_v1() {
+            const bytes = generateV1(nameBits);
+            const dataEncoded = encodeData(bytes);
+            return `${name}.${dataEncoded}`;
+        },
+        v0_from_parts(timestampMs, randomBits) {
+            const bytes = generateV0(nameBits, timestampMs, randomBits);
+            const dataEncoded = encodeData(bytes);
+            return `${name}.${dataEncoded}`;
+        },
+        v1_from_parts(randomBits) {
+            const bytes = generateV1(nameBits, randomBits);
+            const dataEncoded = encodeData(bytes);
+            return `${name}.${dataEncoded}`;
+        },
+        parse(s) {
+            const dotIndex = s.indexOf(".");
+            if (dotIndex === -1) {
+                throw new Error(`Invalid TNID string: missing '.' separator`);
+            }
+            const parsedName = s.substring(0, dotIndex);
+            const dataEncoded = s.substring(dotIndex + 1);
+            if (parsedName !== name) {
+                throw new Error(`TNID name mismatch: expected "${name}", got "${parsedName}"`);
+            }
+            if (!isValidNameRuntime(parsedName)) {
+                throw new Error(`Invalid TNID name in string: "${parsedName}"`);
+            }
+            // Validate data portion
+            const { dataBits } = decodeData(dataEncoded);
+            // Verify we can reconstruct it (validates the encoding)
+            const reconstructed = dataBitsToBytes(dataBits, nameBits);
+            const reencoded = encodeData(reconstructed);
+            if (reencoded !== dataEncoded) {
+                throw new Error(`Invalid TNID data encoding`);
+            }
+            return s;
+        },
+        parseUuidString(uuid) {
+            const value = parseUuidStringToValue(uuid);
+            if (!validateUuidBits(value)) {
+                throw new Error("Invalid TNID: not a valid UUIDv8");
+            }
+            const uuidNameBits = extractNameBitsFromValue(value);
+            if (uuidNameBits !== nameBits) {
+                const foundName = decodeName(uuidNameBits);
+                throw new Error(`TNID name mismatch: expected "${name}", got "${foundName}"`);
+            }
+            return valueToTnidString(value);
+        },
+        nameHex() {
+            return nameBits.toString(16).padStart(5, "0");
+        },
+        variant(id) {
+            return getTnidVariantImpl(id);
+        },
+        toUuidString(id, caseFormat = "lower") {
+            return toUuidStringImpl(id, caseFormat === "upper");
+        },
+    };
+    return tnid;
+}

package/esm/index.d.ts

@@ -0,0 +1,5 @@
+export type { TnidValue, TnidVariant, Case, NamedTnid, TnidType, } from "./types.js";
+export { DynamicTnid } from "./dynamic.js";
+export { UuidLike } from "./uuidlike.js";
+export { Tnid } from "./factory.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,YAAY,EACV,SAAS,EACT,WAAW,EACX,IAAI,EACJ,SAAS,EACT,QAAQ,GACT,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC"}

package/esm/index.js

@@ -0,0 +1,9 @@
+// =============================================================================
+// @tnid/core - Public API
+// =============================================================================
+// DynamicTnid (type + namespace merged in dynamic.ts)
+export { DynamicTnid } from "./dynamic.js";
+// UuidLike (type + namespace merged in uuidlike.ts)
+export { UuidLike } from "./uuidlike.js";
+// Tnid function
+export { Tnid } from "./factory.js";

package/esm/name_encoding.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Encode a name into 20 bits (4 chars * 5 bits each).
+ * Null-pads on the right (least significant bits).
+ */
+export declare function encodeName(name: string): number;
+/**
+ * Decode 20 bits back to a name string.
+ */
+export declare function decodeName(encoded: number): string;
+/**
+ * Validate a name at runtime.
+ * Must be 1-4 characters, each being 0-4 or a-z.
+ */
+export declare function isValidNameRuntime(name: string): boolean;
+//# sourceMappingURL=name_encoding.d.ts.map

package/esm/name_encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"name_encoding.d.ts","sourceRoot":"","sources":["../src/name_encoding.ts"],"names":[],"mappings":"AA8CA;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAc/C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAalD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMxD"}