@marianmeres/uid 1.0.0

package/dist/random.js

@@ -0,0 +1,102 @@
+/**
+ * Crypto-backed randomness primitives shared by every strategy.
+ *
+ * All randomness goes through the Web Crypto API (`crypto.getRandomValues`),
+ * which is available in every modern runtime (browsers, Deno, Node 19+, Bun)
+ * without any external dependency. This is good-quality randomness, but the
+ * library is NOT intended for cryptographic secrets (tokens, keys, etc.).
+ */
+/** Default length for random, fixed-length strategies (nanoid, base*, hex, …). */
+export const DEFAULT_LENGTH = 21;
+/**
+ * Named alphabets used by the built-in strategies.
+ *
+ * The "no-ambiguous" alphabets (`base56`, `base58`, `base32`) drop visually
+ * confusable characters so the output is safe to read aloud / retype.
+ */
+export const ALPHABETS = {
+    // lowercase hex
+    hex: "0123456789abcdef",
+    // Crockford base32 (no I, L, O, U) — power of two, sorts case-insensitively
+    base32: "0123456789ABCDEFGHJKMNPQRSTVWXYZ",
+    // lowercase base36
+    base36: "0123456789abcdefghijklmnopqrstuvwxyz",
+    // no 0 O o 1 l I — safe to read aloud / retype
+    base56: "23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnpqrstuvwxyz",
+    // Bitcoin base58 (no 0 O I l)
+    base58: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz",
+    // full base62
+    base62: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
+    // digits only — handy for OTPs / numeric coupon codes
+    numeric: "0123456789",
+    // alias of base62
+    alphanumeric: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
+    // URL-safe 64-char set (A–Z a–z 0–9 _ -)
+    nanoid: "-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz",
+};
+/** Throws `TypeError` unless `n` is an integer `>= 1`. */
+export function assertPositiveInt(n, label) {
+    if (typeof n !== "number" || !Number.isInteger(n) || n < 1) {
+        throw new TypeError(`"${label}" must be a positive integer, got ${String(n)}`);
+    }
+}
+/** Throws `TypeError` unless `n` is an integer `>= 0`. */
+export function assertNonNegativeInt(n, label) {
+    if (typeof n !== "number" || !Number.isInteger(n) || n < 0) {
+        throw new TypeError(`"${label}" must be a non-negative integer, got ${String(n)}`);
+    }
+}
+/**
+ * Returns `size` cryptographically-strong random bytes.
+ *
+ * Transparently chunks calls larger than the 65536-byte `getRandomValues`
+ * limit so any `size` is supported.
+ */
+export function randomBytes(size) {
+    assertPositiveInt(size, "size");
+    const bytes = new Uint8Array(size);
+    const MAX = 65536; // crypto.getRandomValues hard limit per call
+    for (let offset = 0; offset < size; offset += MAX) {
+        crypto.getRandomValues(bytes.subarray(offset, Math.min(offset + MAX, size)));
+    }
+    return bytes;
+}
+/**
+ * Generates a random string of `length` characters from `alphabet`.
+ *
+ * Uses rejection sampling (the nanoid algorithm) so the output is unbiased
+ * even when `alphabet.length` is not a power of two — no modulo skew.
+ *
+ * @param length   Number of characters to produce (positive integer).
+ * @param alphabet Characters to choose from (1–256 chars). Defaults to the
+ *                 URL-safe nanoid alphabet.
+ */
+export function randomString(length, alphabet = ALPHABETS.nanoid) {
+    assertPositiveInt(length, "length");
+    if (typeof alphabet !== "string") {
+        throw new TypeError(`"alphabet" must be a string, got ${typeof alphabet}`);
+    }
+    const alen = alphabet.length;
+    if (alen < 1 || alen > 256) {
+        throw new RangeError(`"alphabet" length must be between 1 and 256, got ${alen}`);
+    }
+    // degenerate single-char alphabet: every position is that char
+    if (alen === 1)
+        return alphabet.repeat(length);
+    // smallest 2^k - 1 mask that can index the whole alphabet
+    const mask = (2 << Math.floor(Math.log2(alen - 1))) - 1;
+    // over-fetch factor (1.6) keeps the rejection loop fast on average
+    const step = Math.ceil((1.6 * mask * length) / alen);
+    let id = "";
+    while (true) {
+        const bytes = randomBytes(step);
+        for (let i = 0; i < step; i++) {
+            const idx = bytes[i] & mask;
+            if (idx < alen) {
+                id += alphabet[idx];
+                if (id.length === length)
+                    return id;
+            }
+        }
+    }
+}

package/dist/reversible.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Reversible integer ↔ short-string codec (a small "sqids/hashids-lite").
+ *
+ * Encodes a non-negative integer into a short opaque string and back. With a
+ * `salt`, the alphabet is deterministically shuffled so sequential ids do not
+ * produce obviously sequential output — handy for exposing database row ids in
+ * URLs without leaking the row count.
+ *
+ * NOT a security mechanism: like hashids, the mapping is reversible by anyone
+ * who knows (or guesses) the salt and alphabet. Do not use it to protect data.
+ */
+/** Options for {@link encodeInt}. */
+export interface EncodeIntOptions {
+    /** Alphabet of unique characters to encode into (default: base62). */
+    alphabet?: string;
+    /** Salt that deterministically shuffles the alphabet (default: none). */
+    salt?: string;
+    /** Left-pad the result to at least this length (default: `0`). */
+    minLength?: number;
+}
+/** Options for {@link decodeInt}. */
+export interface DecodeIntOptions {
+    /** Must match the alphabet used to encode (default: base62). */
+    alphabet?: string;
+    /** Must match the salt used to encode (default: none). */
+    salt?: string;
+}
+/**
+ * Encodes a non-negative integer into a short string.
+ *
+ * @example
+ * encodeInt(12345);                         // base62, e.g. "3D7"
+ * encodeInt(12345, { salt: "secret" });     // shuffled, e.g. "Yq9"
+ * encodeInt(7, { minLength: 5 });           // "00007"-style padding
+ */
+export declare function encodeInt(value: number, options?: EncodeIntOptions): string;
+/**
+ * Decodes a string produced by {@link encodeInt}. The `alphabet` and `salt`
+ * must match those used to encode.
+ */
+export declare function decodeInt(str: string, options?: DecodeIntOptions): number;

package/dist/reversible.js

@@ -0,0 +1,93 @@
+/**
+ * Reversible integer ↔ short-string codec (a small "sqids/hashids-lite").
+ *
+ * Encodes a non-negative integer into a short opaque string and back. With a
+ * `salt`, the alphabet is deterministically shuffled so sequential ids do not
+ * produce obviously sequential output — handy for exposing database row ids in
+ * URLs without leaking the row count.
+ *
+ * NOT a security mechanism: like hashids, the mapping is reversible by anyone
+ * who knows (or guesses) the salt and alphabet. Do not use it to protect data.
+ */
+import { ALPHABETS } from "./random.js";
+/**
+ * Deterministically shuffles `alphabet` based on `salt` (the hashids
+ * "consistent shuffle" — stable across runtimes, no RNG involved).
+ */
+function consistentShuffle(alphabet, salt) {
+    if (!salt.length)
+        return alphabet;
+    const a = alphabet.split("");
+    for (let i = a.length - 1, v = 0, p = 0; i > 0; i--, v++) {
+        v %= salt.length;
+        const int = salt.charCodeAt(v);
+        p += int;
+        const j = (int + v + p) % i;
+        const tmp = a[i];
+        a[i] = a[j];
+        a[j] = tmp;
+    }
+    return a.join("");
+}
+/**
+ * The codec requires an alphabet of at least 2 *unique* characters — duplicates
+ * would make `indexOf`-based decoding ambiguous and silently corrupt the
+ * round-trip, so we reject them up front rather than return wrong values.
+ */
+function assertReversibleAlphabet(alphabet, fn) {
+    if (alphabet.length < 2) {
+        throw new RangeError(`${fn}: "alphabet" needs at least 2 characters`);
+    }
+    if (new Set(alphabet).size !== alphabet.length) {
+        throw new RangeError(`${fn}: "alphabet" must have unique characters`);
+    }
+}
+/**
+ * Encodes a non-negative integer into a short string.
+ *
+ * @example
+ * encodeInt(12345);                         // base62, e.g. "3D7"
+ * encodeInt(12345, { salt: "secret" });     // shuffled, e.g. "Yq9"
+ * encodeInt(7, { minLength: 5 });           // "00007"-style padding
+ */
+export function encodeInt(value, options = {}) {
+    const { alphabet = ALPHABETS.base62, salt = "", minLength = 0 } = options;
+    if (!Number.isInteger(value) || value < 0 || value > Number.MAX_SAFE_INTEGER) {
+        throw new RangeError(`encodeInt: value must be a safe non-negative integer, got ${String(value)}`);
+    }
+    assertReversibleAlphabet(alphabet, "encodeInt");
+    const a = consistentShuffle(alphabet, salt);
+    const base = a.length;
+    let n = value;
+    let out = "";
+    do {
+        out = a[n % base] + out;
+        n = Math.floor(n / base);
+    } while (n > 0);
+    // pad with the alphabet's zero char; harmless because leading "zeros"
+    // decode back to 0 in positional notation.
+    while (out.length < minLength)
+        out = a[0] + out;
+    return out;
+}
+/**
+ * Decodes a string produced by {@link encodeInt}. The `alphabet` and `salt`
+ * must match those used to encode.
+ */
+export function decodeInt(str, options = {}) {
+    const { alphabet = ALPHABETS.base62, salt = "" } = options;
+    assertReversibleAlphabet(alphabet, "decodeInt");
+    const a = consistentShuffle(alphabet, salt);
+    const base = a.length;
+    let n = 0;
+    for (const ch of str) {
+        const idx = a.indexOf(ch);
+        if (idx < 0)
+            throw new Error(`decodeInt: invalid character "${ch}"`);
+        n = n * base + idx;
+        if (n > Number.MAX_SAFE_INTEGER) {
+            throw new RangeError(`decodeInt: decoded value exceeds safe integer range`);
+        }
+    }
+    return n;
+}

package/dist/rhr.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Opt-in `rhr` strategy — human-readable ids built on
+ * `@marianmeres/random-human-readable`.
+ *
+ * Kept out of the core entry point because its word lists add weight to browser
+ * bundles. Import this module to use it:
+ *
+ * ```ts
+ * import "@marianmeres/uid/rhr";       // registers the strategy
+ * import { uid } from "@marianmeres/uid";
+ * uid("rhr");                          // "happy-blue-otter-canyon"
+ *
+ * // …or call it directly (tree-shakeable, no registration needed):
+ * import { rhr } from "@marianmeres/uid/rhr";
+ * rhr({ nounsCount: 1 });
+ * ```
+ */
+import { type RhrOptions } from "./uid.js";
+/**
+ * Generates a random human-readable id (e.g. `"happy-blue-otter-canyon"`).
+ * Joined with `-` by default; pass any `getRandomHumanReadable` options.
+ */
+export declare function rhr(options?: RhrOptions): string;

package/dist/rhr.js

@@ -0,0 +1,28 @@
+/**
+ * Opt-in `rhr` strategy — human-readable ids built on
+ * `@marianmeres/random-human-readable`.
+ *
+ * Kept out of the core entry point because its word lists add weight to browser
+ * bundles. Import this module to use it:
+ *
+ * ```ts
+ * import "@marianmeres/uid/rhr";       // registers the strategy
+ * import { uid } from "@marianmeres/uid";
+ * uid("rhr");                          // "happy-blue-otter-canyon"
+ *
+ * // …or call it directly (tree-shakeable, no registration needed):
+ * import { rhr } from "@marianmeres/uid/rhr";
+ * rhr({ nounsCount: 1 });
+ * ```
+ */
+import { getRandomHumanReadable } from "@marianmeres/random-human-readable";
+import { registerStrategy } from "./uid.js";
+/**
+ * Generates a random human-readable id (e.g. `"happy-blue-otter-canyon"`).
+ * Joined with `-` by default; pass any `getRandomHumanReadable` options.
+ */
+export function rhr(options = {}) {
+    return getRandomHumanReadable({ joinWith: "-", ...options });
+}
+// Self-register so `uid("rhr", …)` works once this module is imported.
+registerStrategy("rhr", (o = {}) => rhr(o));

package/dist/uid.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The unified `uid(strategy, options)` dispatcher plus a small strategy
+ * registry. Every built-in strategy is also available as a standalone named
+ * export (see ./mod.ts) for tree-shaking and ergonomics; the dispatcher is the
+ * convenience entry point.
+ */
+import { type CounterOptions } from "./counter.js";
+/** Options for the `uuid` / `uuidv4` strategies (none). */
+export interface UuidOptions {
+}
+/** Options for the `uuidv7` strategy. */
+export interface Uuidv7Options {
+    /** Unix epoch milliseconds to embed (default: now). */
+    timestamp?: number;
+}
+/** Options for the `ulid` strategy. */
+export interface UlidOptions {
+    /** Unix epoch milliseconds to embed (default: now). */
+    timestamp?: number;
+}
+/** Options for the `base56` strategy. */
+export interface Base56Options {
+    /** Length of the random string (ignored when `uuid` is given). */
+    length?: number;
+    /** If given, reversibly encode this UUID instead of generating randomly. */
+    uuid?: string;
+}
+/** Options for the `nanoid` strategy. */
+export interface NanoidOptions {
+    /** Number of characters (default: 21). */
+    length?: number;
+    /** Override the alphabet (default: URL-safe 64-char set). */
+    alphabet?: string;
+}
+/** Options for the alphabet strategies (`hex`, `base32`, `numeric`, …). */
+export interface AlphabetOptions {
+    /** Number of characters (default: 21). */
+    length?: number;
+}
+/** Options for the `custom` strategy. */
+export interface CustomOptions {
+    /** Alphabet to draw from (required, 1–256 chars). */
+    alphabet: string;
+    /** Number of characters (default: 21). */
+    length?: number;
+}
+/** Options for the `reversible` strategy. */
+export interface ReversibleOptions {
+    /** The non-negative integer to encode (required). */
+    value: number;
+    /** Alphabet of unique characters (default: base62). */
+    alphabet?: string;
+    /** Salt that shuffles the alphabet (default: none). */
+    salt?: string;
+    /** Left-pad the result to at least this length. */
+    minLength?: number;
+}
+/**
+ * Options for the `rhr` (random-human-readable) strategy. The strategy is
+ * opt-in: `import "@marianmeres/uid/rhr"` once to register it. Mirrors the
+ * subset of `@marianmeres/random-human-readable` options that yield a string.
+ */
+export interface RhrOptions {
+    adjCount?: number;
+    colorsCount?: number;
+    nounsCount?: number;
+    syllablesCount?: number;
+    digitsCount?: number;
+    specialCharsCount?: number;
+    randomizeCase?: boolean;
+    joinWith?: string;
+}
+/** A strategy implementation: takes its options object, returns a string. */
+export type StrategyFn = (options?: Record<string, unknown>) => string;
+/**
+ * Registers (or overrides) a strategy under `name`, making it callable via
+ * `uid(name, options)`. Used internally for the built-ins and by the opt-in
+ * `./rhr` subpath; also available for your own custom strategies.
+ */
+export declare function registerStrategy(name: string, fn: StrategyFn): void;
+/** Returns the names of all currently registered strategies. */
+export declare function listStrategies(): string[];
+export declare function uid(strategy?: "uuid" | "uuidv4", options?: UuidOptions): string;
+export declare function uid(strategy: "uuidv7", options?: Uuidv7Options): string;
+export declare function uid(strategy: "ulid", options?: UlidOptions): string;
+export declare function uid(strategy: "base56", options?: Base56Options): string;
+export declare function uid(strategy: "nanoid", options?: NanoidOptions): string;
+export declare function uid(strategy: "hex" | "base32" | "base36" | "base58" | "base62" | "numeric", options?: AlphabetOptions): string;
+export declare function uid(strategy: "custom", options: CustomOptions): string;
+export declare function uid(strategy: "counter", options?: CounterOptions): string;
+export declare function uid(strategy: "reversible", options: ReversibleOptions): string;
+export declare function uid(strategy: "rhr", options?: RhrOptions): string;
+export declare function uid(strategy: string, options?: Record<string, unknown>): string;

package/dist/uid.js

@@ -0,0 +1,93 @@
+/**
+ * The unified `uid(strategy, options)` dispatcher plus a small strategy
+ * registry. Every built-in strategy is also available as a standalone named
+ * export (see ./mod.ts) for tree-shaking and ergonomics; the dispatcher is the
+ * convenience entry point.
+ */
+import { DEFAULT_LENGTH, randomString } from "./random.js";
+import { ulid, uuid, uuidv7 } from "./uuid.js";
+import { base56, uuidToBase56 } from "./base56.js";
+import { base32, base36, base58, base62, hex, nanoid, numeric } from "./alphabet.js";
+import { counter } from "./counter.js";
+import { encodeInt } from "./reversible.js";
+const _registry = new Map();
+/**
+ * Registers (or overrides) a strategy under `name`, making it callable via
+ * `uid(name, options)`. Used internally for the built-ins and by the opt-in
+ * `./rhr` subpath; also available for your own custom strategies.
+ */
+export function registerStrategy(name, fn) {
+    if (typeof name !== "string" || !name) {
+        throw new TypeError(`registerStrategy: "name" must be a non-empty string`);
+    }
+    if (typeof fn !== "function") {
+        throw new TypeError(`registerStrategy: "fn" must be a function`);
+    }
+    _registry.set(name, fn);
+}
+/** Returns the names of all currently registered strategies. */
+export function listStrategies() {
+    return [..._registry.keys()];
+}
+// Register the zero-dependency built-ins.
+registerStrategy("uuid", () => uuid());
+registerStrategy("uuidv4", () => uuid());
+registerStrategy("uuidv7", (o = {}) => uuidv7(o.timestamp));
+registerStrategy("ulid", (o = {}) => ulid(o.timestamp));
+registerStrategy("base56", (o = {}) => {
+    const { uuid: u, length } = o;
+    return u != null ? uuidToBase56(u) : base56(length);
+});
+registerStrategy("nanoid", (o = {}) => {
+    const { length, alphabet } = o;
+    return nanoid(length, alphabet);
+});
+registerStrategy("hex", (o = {}) => hex(o.length));
+registerStrategy("base32", (o = {}) => base32(o.length));
+registerStrategy("base36", (o = {}) => base36(o.length));
+registerStrategy("base58", (o = {}) => base58(o.length));
+registerStrategy("base62", (o = {}) => base62(o.length));
+registerStrategy("numeric", (o = {}) => numeric(o.length));
+registerStrategy("custom", (o = {}) => {
+    const { alphabet, length } = o;
+    if (typeof alphabet !== "string") {
+        throw new TypeError(`uid("custom"): "alphabet" option is required`);
+    }
+    return randomString(length ?? DEFAULT_LENGTH, alphabet);
+});
+registerStrategy("counter", (o = {}) => counter(o));
+registerStrategy("reversible", (o = {}) => {
+    const { value, ...rest } = o;
+    if (typeof value !== "number") {
+        throw new TypeError(`uid("reversible"): "value" option is required`);
+    }
+    return encodeInt(value, rest);
+});
+/**
+ * Generates a unique id using the named `strategy`.
+ *
+ * Defaults to `uuid` (v4) when called with no arguments. The `options` shape
+ * depends on the strategy — see the per-strategy option interfaces. The `rhr`
+ * strategy must be enabled first via `import "@marianmeres/uid/rhr"`.
+ *
+ * @example
+ * uid();                                  // uuid v4
+ * uid("uuidv7");                          // sortable uuid
+ * uid("nanoid", { length: 12 });          // "V1StGXR8_Z5j"
+ * uid("numeric", { length: 6 });          // "048217"
+ * uid("counter", { prefix: "n", pad: 3 }); // "n000"
+ */
+export function uid(strategy = "uuid", 
+// deno-lint-ignore no-explicit-any -- implementation signature for overloads
+options = {}) {
+    const fn = _registry.get(strategy);
+    if (!fn) {
+        if (strategy === "rhr") {
+            throw new Error(`The "rhr" strategy is opt-in. Enable it once with:\n` +
+                `  import "@marianmeres/uid/rhr";\n` +
+                `(or use the named export: import { rhr } from "@marianmeres/uid/rhr")`);
+        }
+        throw new Error(`Unknown uid strategy "${strategy}". Available: ${listStrategies().join(", ")}`);
+    }
+    return fn(options);
+}

package/dist/uuid.d.ts

@@ -0,0 +1,33 @@
+/**
+ * UUID and UUID-shaped, time-sortable strategies.
+ */
+/**
+ * Generates a random RFC 9562 UUID v4 via the native `crypto.randomUUID()`.
+ *
+ * @example
+ * uuid(); // "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
+ */
+export declare function uuid(): string;
+/**
+ * Generates a UUID v7 (RFC 9562): a 48-bit Unix-millisecond timestamp prefix
+ * followed by random bits. The result is a valid UUID *and* lexicographically
+ * sortable by creation time — ideal for database primary keys.
+ *
+ * @param timestamp Unix epoch milliseconds to embed (default: `Date.now()`).
+ *                  Useful for tests or back-dating; must be in `[0, 2^48)`.
+ * @example
+ * uuidv7(); // "0192f6c4-1d2e-7a3b-8c4d-5e6f7a8b9c0d"
+ */
+export declare function uuidv7(timestamp?: number): string;
+/**
+ * Generates a ULID: a 26-character Crockford-base32 string with a 48-bit
+ * millisecond timestamp prefix (10 chars) and 80 bits of randomness (16 chars).
+ *
+ * Like UUID v7 it sorts by creation time, but it is shorter, case-insensitive,
+ * and dash-free — not a valid UUID string.
+ *
+ * @param timestamp Unix epoch milliseconds to embed (default: `Date.now()`).
+ * @example
+ * ulid(); // "01J9Z7Q8K3M4N5P6R7S8T9V0W1"
+ */
+export declare function ulid(timestamp?: number): string;

package/dist/uuid.js

@@ -0,0 +1,74 @@
+/**
+ * UUID and UUID-shaped, time-sortable strategies.
+ */
+import { ALPHABETS, randomBytes, randomString } from "./random.js";
+/** Formats 16 bytes as a canonical lowercase UUID string. */
+function bytesToUuid(bytes) {
+    let h = "";
+    for (let i = 0; i < 16; i++)
+        h += bytes[i].toString(16).padStart(2, "0");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+/**
+ * Generates a random RFC 9562 UUID v4 via the native `crypto.randomUUID()`.
+ *
+ * @example
+ * uuid(); // "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
+ */
+export function uuid() {
+    return crypto.randomUUID();
+}
+/**
+ * Generates a UUID v7 (RFC 9562): a 48-bit Unix-millisecond timestamp prefix
+ * followed by random bits. The result is a valid UUID *and* lexicographically
+ * sortable by creation time — ideal for database primary keys.
+ *
+ * @param timestamp Unix epoch milliseconds to embed (default: `Date.now()`).
+ *                  Useful for tests or back-dating; must be in `[0, 2^48)`.
+ * @example
+ * uuidv7(); // "0192f6c4-1d2e-7a3b-8c4d-5e6f7a8b9c0d"
+ */
+export function uuidv7(timestamp = Date.now()) {
+    const ts = Math.floor(timestamp);
+    if (!Number.isFinite(ts) || ts < 0 || ts > 0xffffffffffff) {
+        throw new RangeError(`uuidv7: timestamp must be in [0, 2^48), got ${String(timestamp)}`);
+    }
+    const bytes = randomBytes(16);
+    // 48-bit big-endian timestamp in the first 6 bytes (division avoids the
+    // 32-bit truncation of bitwise shifts).
+    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] & 0x0f) | 0x70; // version 7
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 10xx
+    return bytesToUuid(bytes);
+}
+/**
+ * Generates a ULID: a 26-character Crockford-base32 string with a 48-bit
+ * millisecond timestamp prefix (10 chars) and 80 bits of randomness (16 chars).
+ *
+ * Like UUID v7 it sorts by creation time, but it is shorter, case-insensitive,
+ * and dash-free — not a valid UUID string.
+ *
+ * @param timestamp Unix epoch milliseconds to embed (default: `Date.now()`).
+ * @example
+ * ulid(); // "01J9Z7Q8K3M4N5P6R7S8T9V0W1"
+ */
+export function ulid(timestamp = Date.now()) {
+    const ts = Math.floor(timestamp);
+    if (!Number.isFinite(ts) || ts < 0 || ts > 0xffffffffffff) {
+        throw new RangeError(`ulid: timestamp must be in [0, 2^48), got ${String(timestamp)}`);
+    }
+    const enc = ALPHABETS.base32;
+    let time = ts;
+    let timeChars = "";
+    for (let i = 0; i < 10; i++) {
+        timeChars = enc[time % 32] + timeChars;
+        time = Math.floor(time / 32);
+    }
+    // base32 is a power of two, so randomString is unbiased and rejection-free
+    return timeChars + randomString(16, enc);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@marianmeres/uid",
+	"version": "1.0.0",
+	"type": "module",
+	"main": "dist/mod.js",
+	"types": "dist/mod.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"import": "./dist/mod.js"
+		},
+		"./rhr": {
+			"types": "./dist/rhr.d.ts",
+			"import": "./dist/rhr.js"
+		}
+	},
+	"files": [
+		"dist",
+		"LICENSE",
+		"README.md",
+		"API.md",
+		"AGENTS.md"
+	],
+	"author": "Marian Meres",
+	"license": "MIT",
+	"dependencies": {},
+	"peerDependencies": {
+		"@marianmeres/random-human-readable": "^1.10"
+	},
+	"peerDependenciesMeta": {
+		"@marianmeres/random-human-readable": {
+			"optional": true
+		}
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/marianmeres/uid.git"
+	},
+	"bugs": {
+		"url": "https://github.com/marianmeres/uid/issues"
+	}
+}