@tnid/core 0.0.1

package/script/data_encoding.js

@@ -0,0 +1,108 @@
+"use strict";
+// =============================================================================
+// Data Encoding - 6-bit encoding for the data portion
+// 64 characters in order: - 0-9 A-Z _ a-z
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeData = encodeData;
+exports.decodeData = decodeData;
+exports.dataBitsToBytes = dataBitsToBytes;
+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.
+ */
+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.
+ */
+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.
+ */
+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/script/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/script/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/script/dynamic.js

@@ -0,0 +1,176 @@
+"use strict";
+// =============================================================================
+// DynamicTnid - Runtime name validation
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamicTnid = void 0;
+exports.getTnidVariantImpl = getTnidVariantImpl;
+exports.toUuidStringImpl = toUuidStringImpl;
+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");
+const uuid_js_1 = require("./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 } = (0, data_encoding_js_1.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 = (0, name_encoding_js_1.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 = (0, name_encoding_js_1.encodeName)(name);
+    const { dataBits } = (0, data_encoding_js_1.decodeData)(dataEncoded);
+    const bytes = (0, data_encoding_js_1.dataBitsToBytes)(dataBits, nameBits);
+    let value = 0n;
+    for (const byte of bytes) {
+        value = (value << 8n) | BigInt(byte);
+    }
+    return (0, uuid_js_1.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 (!(0, name_encoding_js_1.isValidNameRuntime)(name)) {
+        throw new Error(`Invalid TNID name: "${name}"`);
+    }
+    // Validate data portion
+    const nameBits = (0, name_encoding_js_1.encodeName)(name);
+    const { dataBits } = (0, data_encoding_js_1.decodeData)(dataEncoded);
+    // Verify we can reconstruct it (validates the encoding)
+    const reconstructed = (0, data_encoding_js_1.dataBitsToBytes)(dataBits, nameBits);
+    const reencoded = (0, data_encoding_js_1.encodeData)(reconstructed);
+    if (reencoded !== dataEncoded) {
+        throw new Error("Invalid TNID data encoding");
+    }
+    return s;
+}
+function parseDynamicUuidStringImpl(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);
+}
+// -----------------------------------------------------------------------------
+// DynamicTnid Namespace
+// -----------------------------------------------------------------------------
+/** Static methods for working with any TNID regardless of name. */
+exports.DynamicTnid = {
+    /** Generate a new time-sortable TNID (variant 0) with runtime name validation. */
+    new_v0(name) {
+        if (!(0, name_encoding_js_1.isValidNameRuntime)(name)) {
+            throw new Error(`Invalid TNID name: "${name}". Must be 1-4 characters of: 0-4, a-z`);
+        }
+        const nameBits = (0, name_encoding_js_1.encodeName)(name);
+        const bytes = (0, bits_js_1.generateV0)(nameBits);
+        const dataEncoded = (0, data_encoding_js_1.encodeData)(bytes);
+        return `${name}.${dataEncoded}`;
+    },
+    /** Alias for new_v0. */
+    new_time_ordered(name) {
+        return exports.DynamicTnid.new_v0(name);
+    },
+    /** Generate a new time-sortable TNID with a specific timestamp. */
+    new_v0_with_time(name, time) {
+        if (!(0, name_encoding_js_1.isValidNameRuntime)(name)) {
+            throw new Error(`Invalid TNID name: "${name}". Must be 1-4 characters of: 0-4, a-z`);
+        }
+        const nameBits = (0, name_encoding_js_1.encodeName)(name);
+        const timestampMs = BigInt(time.getTime());
+        const bytes = (0, bits_js_1.generateV0)(nameBits, timestampMs);
+        const dataEncoded = (0, data_encoding_js_1.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 (!(0, name_encoding_js_1.isValidNameRuntime)(name)) {
+            throw new Error(`Invalid TNID name: "${name}". Must be 1-4 characters of: 0-4, a-z`);
+        }
+        const nameBits = (0, name_encoding_js_1.encodeName)(name);
+        const bytes = (0, bits_js_1.generateV0)(nameBits, epochMillis, random);
+        const dataEncoded = (0, data_encoding_js_1.encodeData)(bytes);
+        return `${name}.${dataEncoded}`;
+    },
+    /** Generate a new high-entropy TNID (variant 1) with runtime name validation. */
+    new_v1(name) {
+        if (!(0, name_encoding_js_1.isValidNameRuntime)(name)) {
+            throw new Error(`Invalid TNID name: "${name}". Must be 1-4 characters of: 0-4, a-z`);
+        }
+        const nameBits = (0, name_encoding_js_1.encodeName)(name);
+        const bytes = (0, bits_js_1.generateV1)(nameBits);
+        const dataEncoded = (0, data_encoding_js_1.encodeData)(bytes);
+        return `${name}.${dataEncoded}`;
+    },
+    /** Alias for new_v1. */
+    new_high_entropy(name) {
+        return exports.DynamicTnid.new_v1(name);
+    },
+    /** Generate a new high-entropy TNID with explicit random bits. */
+    new_v1_with_random(name, randomBits) {
+        if (!(0, name_encoding_js_1.isValidNameRuntime)(name)) {
+            throw new Error(`Invalid TNID name: "${name}". Must be 1-4 characters of: 0-4, a-z`);
+        }
+        const nameBits = (0, name_encoding_js_1.encodeName)(name);
+        const bytes = (0, bits_js_1.generateV1)(nameBits, randomBits);
+        const dataEncoded = (0, data_encoding_js_1.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");
+    },
+};

package/script/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/script/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/script/factory.js

@@ -0,0 +1,110 @@
+"use strict";
+// =============================================================================
+// Tnid Function
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tnid = Tnid;
+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");
+const uuid_js_1 = require("./uuid.js");
+const dynamic_js_1 = require("./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
+ * ```
+ */
+function Tnid(name) {
+    // Runtime validation (belt and suspenders)
+    if (!(0, name_encoding_js_1.isValidNameRuntime)(name)) {
+        throw new Error(`Invalid TNID name: "${name}". Must be 1-4 characters of: 0-4, a-z`);
+    }
+    const nameBits = (0, name_encoding_js_1.encodeName)(name);
+    const tnid = {
+        name: name,
+        new_v0() {
+            const bytes = (0, bits_js_1.generateV0)(nameBits);
+            const dataEncoded = (0, data_encoding_js_1.encodeData)(bytes);
+            return `${name}.${dataEncoded}`;
+        },
+        new_v1() {
+            const bytes = (0, bits_js_1.generateV1)(nameBits);
+            const dataEncoded = (0, data_encoding_js_1.encodeData)(bytes);
+            return `${name}.${dataEncoded}`;
+        },
+        v0_from_parts(timestampMs, randomBits) {
+            const bytes = (0, bits_js_1.generateV0)(nameBits, timestampMs, randomBits);
+            const dataEncoded = (0, data_encoding_js_1.encodeData)(bytes);
+            return `${name}.${dataEncoded}`;
+        },
+        v1_from_parts(randomBits) {
+            const bytes = (0, bits_js_1.generateV1)(nameBits, randomBits);
+            const dataEncoded = (0, data_encoding_js_1.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 (!(0, name_encoding_js_1.isValidNameRuntime)(parsedName)) {
+                throw new Error(`Invalid TNID name in string: "${parsedName}"`);
+            }
+            // Validate data portion
+            const { dataBits } = (0, data_encoding_js_1.decodeData)(dataEncoded);
+            // Verify we can reconstruct it (validates the encoding)
+            const reconstructed = (0, data_encoding_js_1.dataBitsToBytes)(dataBits, nameBits);
+            const reencoded = (0, data_encoding_js_1.encodeData)(reconstructed);
+            if (reencoded !== dataEncoded) {
+                throw new Error(`Invalid TNID data encoding`);
+            }
+            return s;
+        },
+        parseUuidString(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 uuidNameBits = (0, uuid_js_1.extractNameBitsFromValue)(value);
+            if (uuidNameBits !== nameBits) {
+                const foundName = (0, name_encoding_js_1.decodeName)(uuidNameBits);
+                throw new Error(`TNID name mismatch: expected "${name}", got "${foundName}"`);
+            }
+            return (0, uuid_js_1.valueToTnidString)(value);
+        },
+        nameHex() {
+            return nameBits.toString(16).padStart(5, "0");
+        },
+        variant(id) {
+            return (0, dynamic_js_1.getTnidVariantImpl)(id);
+        },
+        toUuidString(id, caseFormat = "lower") {
+            return (0, dynamic_js_1.toUuidStringImpl)(id, caseFormat === "upper");
+        },
+    };
+    return tnid;
+}

package/script/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/script/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/script/index.js

@@ -0,0 +1,15 @@
+"use strict";
+// =============================================================================
+// @tnid/core - Public API
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tnid = exports.UuidLike = exports.DynamicTnid = void 0;
+// DynamicTnid (type + namespace merged in dynamic.ts)
+var dynamic_js_1 = require("./dynamic.js");
+Object.defineProperty(exports, "DynamicTnid", { enumerable: true, get: function () { return dynamic_js_1.DynamicTnid; } });
+// UuidLike (type + namespace merged in uuidlike.ts)
+var uuidlike_js_1 = require("./uuidlike.js");
+Object.defineProperty(exports, "UuidLike", { enumerable: true, get: function () { return uuidlike_js_1.UuidLike; } });
+// Tnid function
+var factory_js_1 = require("./factory.js");
+Object.defineProperty(exports, "Tnid", { enumerable: true, get: function () { return factory_js_1.Tnid; } });

package/script/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/script/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"}

package/script/name_encoding.js

@@ -0,0 +1,97 @@
+"use strict";
+// =============================================================================
+// Name Encoding - 5-bit encoding for TNID names
+// Valid characters: 0-4, a-z (31 chars + null terminator = 32 = 2^5)
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeName = encodeName;
+exports.decodeName = decodeName;
+exports.isValidNameRuntime = isValidNameRuntime;
+const NAME_CHAR_TO_VALUE = {
+    "0": 1,
+    "1": 2,
+    "2": 3,
+    "3": 4,
+    "4": 5,
+    a: 6,
+    b: 7,
+    c: 8,
+    d: 9,
+    e: 10,
+    f: 11,
+    g: 12,
+    h: 13,
+    i: 14,
+    j: 15,
+    k: 16,
+    l: 17,
+    m: 18,
+    n: 19,
+    o: 20,
+    p: 21,
+    q: 22,
+    r: 23,
+    s: 24,
+    t: 25,
+    u: 26,
+    v: 27,
+    w: 28,
+    x: 29,
+    y: 30,
+    z: 31,
+};
+const NAME_VALUE_TO_CHAR = {};
+for (const [char, value] of Object.entries(NAME_CHAR_TO_VALUE)) {
+    NAME_VALUE_TO_CHAR[value] = char;
+}
+const VALID_NAME_CHARS = new Set("01234abcdefghijklmnopqrstuvwxyz".split(""));
+/**
+ * Encode a name into 20 bits (4 chars * 5 bits each).
+ * Null-pads on the right (least significant bits).
+ */
+function encodeName(name) {
+    let result = 0;
+    for (let i = 0; i < 4; i++) {
+        result <<= 5;
+        if (i < name.length) {
+            const value = NAME_CHAR_TO_VALUE[name[i]];
+            if (value === undefined) {
+                throw new Error(`Invalid name character: ${name[i]}`);
+            }
+            result |= value;
+        }
+        // else: null (0) is already the default
+    }
+    return result;
+}
+/**
+ * Decode 20 bits back to a name string.
+ */
+function decodeName(encoded) {
+    let result = "";
+    for (let i = 0; i < 4; i++) {
+        const shift = (3 - i) * 5;
+        const value = (encoded >> shift) & 0x1f;
+        if (value === 0)
+            break; // null terminator
+        const char = NAME_VALUE_TO_CHAR[value];
+        if (!char) {
+            throw new Error(`Invalid encoded name value: ${value}`);
+        }
+        result += char;
+    }
+    return result;
+}
+/**
+ * Validate a name at runtime.
+ * Must be 1-4 characters, each being 0-4 or a-z.
+ */
+function isValidNameRuntime(name) {
+    if (name.length < 1 || name.length > 4)
+        return false;
+    for (const char of name) {
+        if (!VALID_NAME_CHARS.has(char))
+            return false;
+    }
+    return true;
+}

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}