@marianmeres/uid 1.0.0

package/README.md

@@ -0,0 +1,183 @@
+# @marianmeres/uid
+
+[![JSR](https://jsr.io/badges/@marianmeres/uid)](https://jsr.io/@marianmeres/uid)
+[![NPM](https://img.shields.io/npm/v/@marianmeres/uid)](https://www.npmjs.com/package/@marianmeres/uid)
+[![License](https://img.shields.io/npm/l/@marianmeres/uid)](LICENSE)
+
+One `uid()` function, many id strategies — UUIDs, sortable ids (UUID v7 / ULID),
+URL-safe random ids (nanoid-style), human-friendly alphabets (base56/58/62/…),
+in-memory counters, reversible integer codecs, and human-readable ids.
+
+- **Works everywhere** — browsers, Deno, Node 19+, Bun.
+- **Crypto-backed** — all randomness comes from the Web Crypto API, with
+  rejection sampling so non-power-of-two alphabets stay unbiased.
+- **Zero dependencies** in the core (the optional `rhr` strategy is the only
+  add-on, and it's opt-in).
+- **Type-safe** — `options` are checked per strategy, and every strategy is also
+  a standalone, tree-shakeable named export.
+
+> Good-quality randomness, but **not** intended for cryptographic secrets
+> (tokens, keys, password resets). Use a dedicated crypto routine for those.
+
+## Installation
+
+```bash
+# deno
+deno add jsr:@marianmeres/uid
+
+# npm (or pnpm / yarn / bun)
+npx jsr add @marianmeres/uid
+```
+
+## Quick start
+
+```typescript
+import { uid } from "@marianmeres/uid";
+
+uid(); // uuid v4 (default)
+uid("uuidv7"); // sortable, UUID-compatible
+uid("ulid"); // sortable, 26-char Crockford base32
+uid("nanoid", { length: 12 }); // "V1StGXR8_Z5j"
+uid("base58", { length: 10 }); // "3kP9xQ2mWz"
+uid("numeric", { length: 6 }); // "048217"  (OTP / coupon)
+uid("counter", { prefix: "n" }); // "n0", "n1", "n2", …
+```
+
+Every strategy is also a direct, tree-shakeable named export — handy when you
+want one specific generator without the dispatcher:
+
+```typescript
+import { base62, nanoid, ulid, uuidv7 } from "@marianmeres/uid";
+
+uuidv7(); // "0192f6c4-1d2e-7a3b-8c4d-5e6f7a8b9c0d"
+nanoid(); // 21-char URL-safe id
+base62(8); // "aZ09Kp3X"
+```
+
+## Strategies
+
+| Strategy                                            | `uid(...)`                                         | Output                                  |
+| --------------------------------------------------- | -------------------------------------------------- | --------------------------------------- |
+| `uuid` / `uuidv4`                                   | `uid()` / `uid("uuid")`                            | RFC 9562 UUID v4                        |
+| `uuidv7`                                            | `uid("uuidv7", { timestamp? })`                    | Time-sortable UUID                      |
+| `ulid`                                              | `uid("ulid", { timestamp? })`                      | 26-char Crockford base32, sortable      |
+| `base56`                                            | `uid("base56", { length?, uuid? })`                | No-ambiguous random / reversible uuid   |
+| `nanoid`                                            | `uid("nanoid", { length?, alphabet? })`            | URL-safe random id                      |
+| `hex` `base32` `base36` `base58` `base62` `numeric` | `uid("base58", { length? })`                       | Random string over a named alphabet     |
+| `custom`                                            | `uid("custom", { alphabet, length? })`             | Random string over your alphabet        |
+| `counter`                                           | `uid("counter", { prefix?, start?, step?, pad? })` | In-memory incrementing id               |
+| `reversible`                                        | `uid("reversible", { value, salt?, … })`           | Short reversible encoding of an integer |
+| `rhr`                                               | `uid("rhr", { … })` _(opt-in, see below)_          | Human-readable id                       |
+
+Default length for random strategies is **21**. A UUID encoded as base56 is
+always **23** characters (128 bits need 23 base56 digits).
+
+### Sortable ids — `uuidv7` vs `ulid`
+
+Both embed a 48-bit millisecond timestamp prefix and sort by creation time.
+`uuidv7` is a valid UUID (drops into any `uuid` DB column); `ulid` is shorter,
+dash-free, and case-insensitive but not a valid UUID string.
+
+```typescript
+uid("uuidv7"); // "0192f6c4-1d2e-7a3b-..."
+uid("ulid"); // "01J9Z7Q8K3M4N5P6R7S8T9V0W1"
+uid("uuidv7", { timestamp: 0 }); // back-dated / deterministic time for tests
+```
+
+### base56 — random or reversible UUID
+
+`base56` drops visually ambiguous characters (`0 O o 1 l I`), so it's safe to
+read aloud or retype.
+
+```typescript
+import { base56, base56ToUuid, base56Uuid, uuidToBase56 } from "@marianmeres/uid";
+
+base56(10); // random, e.g. "7vNpRmXj4Q"
+base56Uuid(); // fresh uuid, 23-char base56 (reversible)
+
+const enc = uuidToBase56("550e8400-e29b-41d4-a716-446655440000");
+base56ToUuid(enc); // back to the original uuid
+```
+
+### counter — in-memory sequence
+
+State lives for the lifetime of the process/page (it resets on reload) and is
+**not** for cross-process uniqueness. Each prefix has its own sequence.
+
+```typescript
+import { createCounter } from "@marianmeres/uid";
+
+uid("counter", { prefix: "node_" }); // "node_0", "node_1", …
+uid("counter", { prefix: "x", pad: 4 }); // "x0000", "x0001", …
+
+// fully isolated instance (best for tests / multiple independent sequences):
+const next = createCounter({ prefix: "row-", start: 1, pad: 4 });
+next(); // "row-0001"
+next(); // "row-0002"
+```
+
+### reversible — encode integers ↔ short strings
+
+A small "sqids/hashids-lite". With a `salt` the alphabet is deterministically
+shuffled so sequential ids don't look sequential — useful for exposing database
+row ids in URLs without leaking the row count.
+
+```typescript
+import { decodeInt, encodeInt } from "@marianmeres/uid";
+
+const code = encodeInt(12345, { salt: "my-secret" }); // e.g. "Yq9"
+decodeInt(code, { salt: "my-secret" }); // 12345
+```
+
+> Like hashids, this is **obfuscation, not encryption** — anyone who knows the
+> salt and alphabet can reverse it. Don't use it to protect data.
+
+### rhr — human-readable ids (opt-in)
+
+Human-readable ids are built on
+[`@marianmeres/random-human-readable`](https://jsr.io/@marianmeres/random-human-readable).
+To keep its word lists out of the core bundle, this strategy lives behind a
+subpath you import explicitly:
+
+```typescript
+// register the strategy once (e.g. in your entry file):
+import "@marianmeres/uid/rhr";
+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 });
+```
+
+On npm, install the peer dependency yourself:
+`npm install @marianmeres/random-human-readable`.
+
+## Custom alphabets & strategies
+
+```typescript
+import { randomString, registerStrategy, uid } from "@marianmeres/uid";
+
+// arbitrary alphabet, one-off:
+uid("custom", { alphabet: "ABCDEF01", length: 8 });
+randomString(8, "ABCDEF01");
+
+// register your own reusable strategy:
+registerStrategy("order", () => "ORD-" + uid("numeric", { length: 8 }));
+uid("order"); // "ORD-40582193"
+```
+
+## Validation
+
+Options are validated rather than coerced: non-positive/fractional lengths,
+out-of-range UUID v7 / ULID timestamps, missing required options (`custom`'s
+`alphabet`, `reversible`'s `value`), duplicate reversible alphabets, and invalid
+counter options all throw `TypeError` / `RangeError`.
+
+## API
+
+See [API.md](API.md) for the complete API reference.
+
+## License
+
+[MIT](LICENSE)

package/dist/alphabet.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Fixed-length random strings over the built-in named alphabets.
+ *
+ * These are thin, well-named wrappers around {@link randomString} so the most
+ * common cases read cleanly: `hex(32)`, `numeric(6)`, `base62()`, …
+ */
+/**
+ * nanoid-style id: URL-safe (`A–Z a–z 0–9 _ -`), crypto-backed, unbiased.
+ *
+ * @param length   Number of characters (default: {@link DEFAULT_LENGTH}).
+ * @param alphabet Override the alphabet (default: URL-safe 64-char set).
+ */
+export declare function nanoid(length?: number, alphabet?: string): string;
+/** Random lowercase hex string. */
+export declare function hex(length?: number): string;
+/** Random Crockford base32 string (no I, L, O, U). */
+export declare function base32(length?: number): string;
+/** Random lowercase base36 string. */
+export declare function base36(length?: number): string;
+/** Random Bitcoin base58 string (no 0, O, I, l). */
+export declare function base58(length?: number): string;
+/** Random full base62 string. */
+export declare function base62(length?: number): string;
+/** Random digits-only string — handy for OTPs / numeric coupon codes. */
+export declare function numeric(length?: number): string;

package/dist/alphabet.js

@@ -0,0 +1,40 @@
+/**
+ * Fixed-length random strings over the built-in named alphabets.
+ *
+ * These are thin, well-named wrappers around {@link randomString} so the most
+ * common cases read cleanly: `hex(32)`, `numeric(6)`, `base62()`, …
+ */
+import { ALPHABETS, DEFAULT_LENGTH, randomString } from "./random.js";
+/**
+ * nanoid-style id: URL-safe (`A–Z a–z 0–9 _ -`), crypto-backed, unbiased.
+ *
+ * @param length   Number of characters (default: {@link DEFAULT_LENGTH}).
+ * @param alphabet Override the alphabet (default: URL-safe 64-char set).
+ */
+export function nanoid(length = DEFAULT_LENGTH, alphabet = ALPHABETS.nanoid) {
+    return randomString(length, alphabet);
+}
+/** Random lowercase hex string. */
+export function hex(length = DEFAULT_LENGTH) {
+    return randomString(length, ALPHABETS.hex);
+}
+/** Random Crockford base32 string (no I, L, O, U). */
+export function base32(length = DEFAULT_LENGTH) {
+    return randomString(length, ALPHABETS.base32);
+}
+/** Random lowercase base36 string. */
+export function base36(length = DEFAULT_LENGTH) {
+    return randomString(length, ALPHABETS.base36);
+}
+/** Random Bitcoin base58 string (no 0, O, I, l). */
+export function base58(length = DEFAULT_LENGTH) {
+    return randomString(length, ALPHABETS.base58);
+}
+/** Random full base62 string. */
+export function base62(length = DEFAULT_LENGTH) {
+    return randomString(length, ALPHABETS.base62);
+}
+/** Random digits-only string — handy for OTPs / numeric coupon codes. */
+export function numeric(length = DEFAULT_LENGTH) {
+    return randomString(length, ALPHABETS.numeric);
+}

package/dist/base56.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Base56 strategy — human-friendly, no ambiguous characters (no 0 O o 1 l I).
+ *
+ * Two modes:
+ *  - {@link base56}      random fixed-length string (coupon-style)
+ *  - {@link uuidToBase56} / {@link base56ToUuid} fully reversible 23-char
+ *    encoding of a UUID
+ *
+ * Note: 128 bits need ceil(128 / log2(56)) = 23 base56 characters in the worst
+ * case (since 56^22 ≈ 2^127.76 < 2^128), so the encoded width is fixed at 23.
+ */
+/**
+ * Generates a random base56 string.
+ *
+ * @param length Number of characters (default: {@link DEFAULT_LENGTH}).
+ */
+export declare function base56(length?: number): string;
+/**
+ * Encodes a UUID into a 23-character base56 string. Fully reversible via
+ * {@link base56ToUuid}.
+ *
+ * @param uuid A UUID string, with or without dashes.
+ */
+export declare function uuidToBase56(uuid: string): string;
+/**
+ * Decodes a base56 string produced by {@link uuidToBase56} back into a
+ * canonical UUID string.
+ */
+export declare function base56ToUuid(encoded: string): string;
+/**
+ * Generates a fresh UUID and returns its 23-character base56 encoding.
+ * Equivalent to `uuidToBase56(uuid())`.
+ */
+export declare function base56Uuid(): string;

package/dist/base56.js

@@ -0,0 +1,69 @@
+/**
+ * Base56 strategy — human-friendly, no ambiguous characters (no 0 O o 1 l I).
+ *
+ * Two modes:
+ *  - {@link base56}      random fixed-length string (coupon-style)
+ *  - {@link uuidToBase56} / {@link base56ToUuid} fully reversible 23-char
+ *    encoding of a UUID
+ *
+ * Note: 128 bits need ceil(128 / log2(56)) = 23 base56 characters in the worst
+ * case (since 56^22 ≈ 2^127.76 < 2^128), so the encoded width is fixed at 23.
+ */
+import { ALPHABETS, DEFAULT_LENGTH, randomString } from "./random.js";
+const BASE56 = ALPHABETS.base56;
+/**
+ * Generates a random base56 string.
+ *
+ * @param length Number of characters (default: {@link DEFAULT_LENGTH}).
+ */
+export function base56(length = DEFAULT_LENGTH) {
+    return randomString(length, BASE56);
+}
+/**
+ * Encodes a UUID into a 23-character base56 string. Fully reversible via
+ * {@link base56ToUuid}.
+ *
+ * @param uuid A UUID string, with or without dashes.
+ */
+export function uuidToBase56(uuid) {
+    const hex = uuid.replace(/-/g, "").toLowerCase();
+    if (!/^[0-9a-f]{32}$/.test(hex)) {
+        throw new TypeError(`uuidToBase56: invalid uuid "${uuid}"`);
+    }
+    let num = BigInt("0x" + hex);
+    let result = "";
+    while (num > 0n) {
+        result = BASE56[Number(num % 56n)] + result;
+        num = num / 56n;
+    }
+    return result.padStart(23, BASE56[0]);
+}
+/**
+ * Decodes a base56 string produced by {@link uuidToBase56} back into a
+ * canonical UUID string.
+ */
+export function base56ToUuid(encoded) {
+    let num = 0n;
+    for (const ch of encoded) {
+        const idx = BASE56.indexOf(ch);
+        if (idx < 0) {
+            throw new Error(`base56ToUuid: invalid character "${ch}"`);
+        }
+        num = num * 56n + BigInt(idx);
+    }
+    const hex = num.toString(16).padStart(32, "0");
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20),
+    ].join("-");
+}
+/**
+ * Generates a fresh UUID and returns its 23-character base56 encoding.
+ * Equivalent to `uuidToBase56(uuid())`.
+ */
+export function base56Uuid() {
+    return uuidToBase56(crypto.randomUUID());
+}

package/dist/counter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Counter strategy — a simple, monotonically increasing, in-memory counter
+ * with an optional prefix. State lives for the lifetime of the running
+ * process/page; it is NOT persisted and resets on reload. Suitable for
+ * within-process unique ids (tree nodes, DOM ids, test fixtures), not for
+ * cross-process uniqueness.
+ */
+/** Options shared by {@link counter} and {@link createCounter}. */
+export interface CounterOptions {
+    /** String prepended to the number (also the key for the shared counter). */
+    prefix?: string;
+    /** First value emitted (default: `0`). */
+    start?: number;
+    /** Increment between successive values (default: `1`). */
+    step?: number;
+    /** Zero-pad the numeric part to this width (default: `0`, no padding). */
+    pad?: number;
+}
+/**
+ * Returns the next value of the shared, per-prefix counter.
+ *
+ * Each distinct `prefix` has its own independent sequence. The **first** call
+ * for a given prefix configures it (`start`, `step`, `pad`) and returns `start`;
+ * subsequent calls advance it by the captured `step` and reuse the captured
+ * `pad`, so option overrides passed to later calls for the same prefix are
+ * ignored (and the id width stays stable). Use {@link createCounter} when you
+ * want explicit per-instance configuration.
+ *
+ * Options are still validated on every call, so malformed input throws even when
+ * the values would be ignored.
+ *
+ * @example
+ * counter({ prefix: "node_" });            // "node_0"
+ * counter({ prefix: "node_" });            // "node_1"
+ * counter({ prefix: "x", pad: 3 });        // "x000"
+ */
+export declare function counter(options?: CounterOptions): string;
+/**
+ * Creates an isolated counter function with its own private state — no sharing
+ * with {@link counter} or with other instances. Prefer this when you need
+ * several independent sequences or deterministic behavior in tests.
+ *
+ * @example
+ * const next = createCounter({ prefix: "row-", start: 1, pad: 4 });
+ * next(); // "row-0001"
+ * next(); // "row-0002"
+ */
+export declare function createCounter(options?: CounterOptions): () => string;
+/**
+ * Clears the shared per-prefix counter state used by {@link counter}.
+ * Mainly useful in tests. Does not affect {@link createCounter} instances.
+ *
+ * @param prefix If given, resets only that prefix; otherwise resets all.
+ */
+export declare function resetCounters(prefix?: string): void;

package/dist/counter.js

@@ -0,0 +1,87 @@
+/**
+ * Counter strategy — a simple, monotonically increasing, in-memory counter
+ * with an optional prefix. State lives for the lifetime of the running
+ * process/page; it is NOT persisted and resets on reload. Suitable for
+ * within-process unique ids (tree nodes, DOM ids, test fixtures), not for
+ * cross-process uniqueness.
+ */
+import { assertNonNegativeInt } from "./random.js";
+function validate(o) {
+    const { prefix = "", start = 0, step = 1, pad = 0 } = o;
+    if (typeof prefix !== "string") {
+        throw new TypeError(`counter: "prefix" must be a string`);
+    }
+    if (!Number.isInteger(start)) {
+        throw new TypeError(`counter: "start" must be an integer`);
+    }
+    if (!Number.isInteger(step) || step < 1) {
+        throw new TypeError(`counter: "step" must be a positive integer`);
+    }
+    assertNonNegativeInt(pad, "pad");
+    return { prefix, start, step, pad };
+}
+function format(prefix, n, pad) {
+    const s = pad > 0 ? String(n).padStart(pad, "0") : String(n);
+    return prefix + s;
+}
+// One independent counter per prefix, shared across the module. The full config
+// (current value + step + pad) is captured on first use so a prefix's sequence
+// stays consistent regardless of options passed to later calls.
+const _counters = new Map();
+/**
+ * Returns the next value of the shared, per-prefix counter.
+ *
+ * Each distinct `prefix` has its own independent sequence. The **first** call
+ * for a given prefix configures it (`start`, `step`, `pad`) and returns `start`;
+ * subsequent calls advance it by the captured `step` and reuse the captured
+ * `pad`, so option overrides passed to later calls for the same prefix are
+ * ignored (and the id width stays stable). Use {@link createCounter} when you
+ * want explicit per-instance configuration.
+ *
+ * Options are still validated on every call, so malformed input throws even when
+ * the values would be ignored.
+ *
+ * @example
+ * counter({ prefix: "node_" });            // "node_0"
+ * counter({ prefix: "node_" });            // "node_1"
+ * counter({ prefix: "x", pad: 3 });        // "x000"
+ */
+export function counter(options = {}) {
+    const { prefix, start, step, pad } = validate(options);
+    const existing = _counters.get(prefix);
+    const entry = existing
+        ? { ...existing, value: existing.value + existing.step }
+        : { value: start, step, pad };
+    _counters.set(prefix, entry);
+    return format(prefix, entry.value, entry.pad);
+}
+/**
+ * Creates an isolated counter function with its own private state — no sharing
+ * with {@link counter} or with other instances. Prefer this when you need
+ * several independent sequences or deterministic behavior in tests.
+ *
+ * @example
+ * const next = createCounter({ prefix: "row-", start: 1, pad: 4 });
+ * next(); // "row-0001"
+ * next(); // "row-0002"
+ */
+export function createCounter(options = {}) {
+    const { prefix, start, step, pad } = validate(options);
+    let current = start - step;
+    return () => {
+        current += step;
+        return format(prefix, current, pad);
+    };
+}
+/**
+ * Clears the shared per-prefix counter state used by {@link counter}.
+ * Mainly useful in tests. Does not affect {@link createCounter} instances.
+ *
+ * @param prefix If given, resets only that prefix; otherwise resets all.
+ */
+export function resetCounters(prefix) {
+    if (prefix === undefined)
+        _counters.clear();
+    else
+        _counters.delete(prefix);
+}

package/dist/mod.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @marianmeres/uid — one `uid()` function, many id strategies.
+ *
+ * The core entry point is zero-dependency and works in every modern runtime.
+ * The `rhr` strategy (human-readable ids) is opt-in via the `./rhr` subpath to
+ * keep its word lists out of the core bundle.
+ *
+ * @example
+ * import { uid, nanoid, uuidv7 } from "@marianmeres/uid";
+ * uid();                         // uuid v4
+ * nanoid(12);                    // tree-shakeable named export
+ * uid("uuidv7");                 // sortable database key
+ */
+export * from "./random.js";
+export * from "./uuid.js";
+export * from "./base56.js";
+export * from "./alphabet.js";
+export * from "./counter.js";
+export * from "./reversible.js";
+export * from "./uid.js";

package/dist/mod.js

@@ -0,0 +1,20 @@
+/**
+ * @marianmeres/uid — one `uid()` function, many id strategies.
+ *
+ * The core entry point is zero-dependency and works in every modern runtime.
+ * The `rhr` strategy (human-readable ids) is opt-in via the `./rhr` subpath to
+ * keep its word lists out of the core bundle.
+ *
+ * @example
+ * import { uid, nanoid, uuidv7 } from "@marianmeres/uid";
+ * uid();                         // uuid v4
+ * nanoid(12);                    // tree-shakeable named export
+ * uid("uuidv7");                 // sortable database key
+ */
+export * from "./random.js";
+export * from "./uuid.js";
+export * from "./base56.js";
+export * from "./alphabet.js";
+export * from "./counter.js";
+export * from "./reversible.js";
+export * from "./uid.js";

package/dist/random.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 declare 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 declare const ALPHABETS: {
+    hex: string;
+    base32: string;
+    base36: string;
+    base56: string;
+    base58: string;
+    base62: string;
+    numeric: string;
+    alphanumeric: string;
+    nanoid: string;
+};
+/** Throws `TypeError` unless `n` is an integer `>= 1`. */
+export declare function assertPositiveInt(n: unknown, label: string): asserts n is number;
+/** Throws `TypeError` unless `n` is an integer `>= 0`. */
+export declare function assertNonNegativeInt(n: unknown, label: string): asserts n is number;
+/**
+ * Returns `size` cryptographically-strong random bytes.
+ *
+ * Transparently chunks calls larger than the 65536-byte `getRandomValues`
+ * limit so any `size` is supported.
+ */
+export declare function randomBytes(size: number): Uint8Array;
+/**
+ * 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 declare function randomString(length: number, alphabet?: string): string;