@marianmeres/uid 1.0.0

package/AGENTS.md

@@ -0,0 +1,111 @@
+# @marianmeres/uid — Agent Guide
+
+## Quick Reference
+
+- **Stack**: Deno, TypeScript. Core has zero runtime deps; `rhr` is an optional
+  peer dep (`@marianmeres/random-human-readable`).
+- **Test**: `deno task test` | **Watch**: `deno task test:watch`
+- **Lint**: `deno lint` | **Format**: `deno fmt`
+- **JSR check**: `deno publish --dry-run --allow-dirty` (must report no slow types)
+- **Build npm**: `deno task npm:build` | **Publish**: `deno task publish`
+- **Targets**: browsers, Deno, Node 19+, Bun (Web Crypto global required).
+
+## Project Structure
+
+```
+/src
+  mod.ts        — core entry point (re-exports everything except rhr)
+  uid.ts        — uid() dispatcher, strategy registry, per-strategy option types
+  random.ts     — crypto core: randomBytes, randomString (rejection sampling),
+                  ALPHABETS, DEFAULT_LENGTH, assert helpers
+  uuid.ts       — uuid (v4), uuidv7, ulid
+  base56.ts     — base56 random + reversible uuid<->base56 (fixed 23 chars)
+  alphabet.ts   — nanoid, hex, base32, base36, base58, base62, numeric
+  counter.ts    — counter (shared, per-prefix), createCounter, resetCounters
+  reversible.ts — encodeInt / decodeInt (salt-shuffled, reversible)
+  rhr.ts        — OPT-IN subpath "@marianmeres/uid/rhr": rhr() + self-registers
+/tests          — one *.test.ts per src module
+/scripts
+  build-npm.ts  — npm distribution builder (dnt via @marianmeres/npmbuild)
+mcp.ts          — MCP tool definitions (generate-uid + base56 / integer codecs)
+mcp-include.txt — MCP discovery description (opts the package into the MCP server)
+```
+
+## MCP Tools (mcp.ts)
+
+Exposed to AI agents via `@marianmeres/mcp-server` (namespaced `uid:<tool>`):
+`generate-uid` (any strategy + options; imports `./src/rhr.ts` so `rhr` works),
+`uuid-to-base56`, `base56-to-uuid`, `encode-int`, `decode-int`. Handlers return
+plain strings; every param uses `.describe()`. Keep tools in sync with the public
+API when strategies change.
+
+## Public API
+
+Entry `@marianmeres/uid`: `uid(strategy?, options?)` dispatcher plus standalone
+named exports for every strategy.
+
+| Export                                                                   | Signature                                                           |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| `uid`                                                                    | `(strategy?: string, options?) => string` (overloaded per strategy) |
+| `uuid` / `uuidv7` / `ulid`                                               | `() => string` / `(timestamp?) => string`                           |
+| `base56` / `base56Uuid`                                                  | `(length?) => string` / `() => string`                              |
+| `uuidToBase56` / `base56ToUuid`                                          | `(string) => string` (reversible)                                   |
+| `nanoid` / `hex` / `base32` / `base36` / `base58` / `base62` / `numeric` | `(length?, …) => string`                                            |
+| `randomString` / `randomBytes`                                           | `(length, alphabet?) => string` / `(size) => Uint8Array`            |
+| `counter` / `createCounter` / `resetCounters`                            | counter helpers                                                     |
+| `encodeInt` / `decodeInt`                                                | reversible integer codec                                            |
+| `registerStrategy` / `listStrategies`                                    | registry                                                            |
+| `ALPHABETS` / `DEFAULT_LENGTH`                                           | constants                                                           |
+
+Subpath `@marianmeres/uid/rhr`: `rhr(options?) => string` (also registers the
+`rhr` strategy on import).
+
+## Critical Conventions
+
+1. **Core is zero-dependency.** Never import `@marianmeres/random-human-readable`
+   from any module except `src/rhr.ts`. It is an _optional peer dep_ surfaced
+   only via the `./rhr` subpath so its word lists stay out of the core bundle.
+2. **All randomness flows through `random.ts`** (`randomBytes` / `randomString`,
+   Web Crypto + rejection sampling). Never use `Math.random`.
+3. **Adding a strategy** = (a) implement it as a standalone named export in the
+   relevant file, (b) `registerStrategy("name", …)` in `src/uid.ts`, (c) add a
+   typed overload signature to `uid` and an options interface. Keep both the
+   named export and the dispatcher path working.
+4. **Explicit return types on every exported symbol** — JSR rejects slow types.
+   Verify with `deno publish --dry-run` before publishing.
+5. **base56-from-uuid is fixed-width 23 chars** (128 bits need 23 base56 digits;
+   `56^22 < 2^128`). Do not "fix" it back to 22.
+6. **Multi-file layout is intentional** (tree-shaking). Keep pure modules pure;
+   `counter.ts` holds the only module-level mutable state (the shared counters).
+7. **rhr strategy is opt-in**: `uid("rhr")` throws a helpful error until
+   `import "@marianmeres/uid/rhr"` registers it. Tests must isolate this (see
+   `tests/rhr.test.ts` — dynamic import, the only file touching the subpath).
+
+## Validation Rules (enforced at runtime)
+
+| Input                                     | Constraint                                | Throws                     |
+| ----------------------------------------- | ----------------------------------------- | -------------------------- |
+| `randomString` length, `randomBytes` size | positive integer                          | `TypeError`                |
+| `randomString` alphabet                   | string, 1–256 chars                       | `TypeError` / `RangeError` |
+| `uuidv7` / `ulid` timestamp               | integer in `[0, 2^48)`                    | `RangeError`               |
+| `uuidToBase56` input                      | valid 32-hex-digit UUID                   | `TypeError`                |
+| `counter` prefix/start/step/pad           | string / int / positive int / non-neg int | `TypeError`                |
+| `encodeInt` value                         | safe non-negative integer                 | `RangeError`               |
+| reversible alphabet                       | ≥ 2 unique characters                     | `RangeError`               |
+| `uid(strategy)` unknown name              | —                                         | `Error` (lists available)  |
+| `uid("custom")` / `uid("reversible")`     | required `alphabet` / `value`             | `TypeError`                |
+
+## Documentation Index
+
+- [README.md](./README.md) — user-facing overview and usage
+- [API.md](./API.md) — complete API reference
+
+## Before Making Changes
+
+- [ ] Check existing patterns in the relevant `src/*.ts` and its test
+- [ ] `deno task test` (add/extend tests for new behavior)
+- [ ] `deno fmt` and `deno lint`
+- [ ] `deno publish --dry-run --allow-dirty` (no slow types)
+- [ ] `deno task npm:build` if deps, entry points, or build config changed
+- [ ] If the public API changed: update [README.md](./README.md),
+      [API.md](./API.md), and this file

package/API.md

@@ -0,0 +1,425 @@
+# API
+
+Complete reference for `@marianmeres/uid`.
+
+- Core entry point: `@marianmeres/uid` — everything below **except** `rhr`.
+- Opt-in subpath: `@marianmeres/uid/rhr` — the `rhr` function and strategy.
+
+All generators are crypto-backed (`crypto.getRandomValues` / `crypto.randomUUID`)
+and work in browsers, Deno, Node 19+, and Bun. Randomness is good quality but
+**not** cryptographically secret — do not use for tokens, keys, or password
+resets.
+
+---
+
+## The dispatcher
+
+### `uid(strategy?, options?)`
+
+Generates a unique id using the named `strategy`. Defaults to `uuid` (v4). The
+`options` shape is validated per strategy (TypeScript overloads narrow it from
+the strategy name). The `rhr` strategy must be enabled first via
+`import "@marianmeres/uid/rhr"`.
+
+**Parameters:**
+
+- `strategy` (string, optional) — one of: `uuid`, `uuidv4`, `uuidv7`, `ulid`,
+  `base56`, `nanoid`, `hex`, `base32`, `base36`, `base58`, `base62`, `numeric`,
+  `custom`, `counter`, `reversible`, `rhr`, or any name registered via
+  `registerStrategy`. Default: `"uuid"`.
+- `options` (object, optional) — strategy-specific; see each strategy below.
+
+**Returns:** `string`
+
+**Throws:** `Error` if the strategy is unknown (message lists available
+strategies), or a strategy-specific `TypeError`/`RangeError` for invalid options.
+
+**Example:**
+
+```typescript
+import { uid } from "@marianmeres/uid";
+
+uid(); // uuid v4
+uid("uuidv7"); // sortable uuid
+uid("nanoid", { length: 12 }); // "V1StGXR8_Z5j"
+uid("custom", { alphabet: "AB01", length: 6 });
+```
+
+| Strategy          | Options type        | Backing function                   |
+| ----------------- | ------------------- | ---------------------------------- |
+| `uuid`/`uuidv4`   | `UuidOptions`       | `uuid()`                           |
+| `uuidv7`          | `Uuidv7Options`     | `uuidv7(timestamp)`                |
+| `ulid`            | `UlidOptions`       | `ulid(timestamp)`                  |
+| `base56`          | `Base56Options`     | `base56()` / `uuidToBase56()`      |
+| `nanoid`          | `NanoidOptions`     | `nanoid(length, alphabet)`         |
+| `hex` … `numeric` | `AlphabetOptions`   | `hex(length)`, `base58(length)`, … |
+| `custom`          | `CustomOptions`     | `randomString(length, alphabet)`   |
+| `counter`         | `CounterOptions`    | `counter(options)`                 |
+| `reversible`      | `ReversibleOptions` | `encodeInt(value, options)`        |
+| `rhr`             | `RhrOptions`        | `rhr(options)` _(opt-in)_          |
+
+---
+
+## UUID & sortable strategies
+
+### `uuid()`
+
+Random RFC 9562 UUID v4 via native `crypto.randomUUID()`.
+
+**Returns:** `string` — e.g. `"1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"`
+
+### `uuidv7(timestamp?)`
+
+RFC 9562 UUID v7 — a 48-bit Unix-millisecond timestamp prefix plus random bits.
+Valid UUID **and** lexicographically sortable by creation time. Ideal for
+database primary keys.
+
+**Parameters:**
+
+- `timestamp` (number, optional) — Unix epoch milliseconds to embed. Must be in
+  `[0, 2^48)`. Default: `Date.now()`.
+
+**Returns:** `string`
+**Throws:** `RangeError` if `timestamp` is outside `[0, 2^48)`.
+
+**Example:**
+
+```typescript
+uuidv7(); // "0192f6c4-1d2e-7a3b-8c4d-5e6f7a8b9c0d"
+uuidv7(0); // deterministic time prefix (tests / back-dating)
+```
+
+### `ulid(timestamp?)`
+
+ULID — 26-character Crockford-base32 string: 48-bit ms timestamp (10 chars) +
+80 bits of randomness (16 chars). Sorts by time like UUID v7, but shorter,
+dash-free, and case-insensitive (not a valid UUID string).
+
+**Parameters:**
+
+- `timestamp` (number, optional) — Unix epoch milliseconds. Must be in
+  `[0, 2^48)`. Default: `Date.now()`.
+
+**Returns:** `string` — e.g. `"01J9Z7Q8K3M4N5P6R7S8T9V0W1"`
+**Throws:** `RangeError` if `timestamp` is outside `[0, 2^48)`.
+
+---
+
+## Base56 strategy
+
+Human-friendly alphabet with no ambiguous characters (`0 O o 1 l I`).
+
+### `base56(length?)`
+
+Random base56 string.
+
+**Parameters:** `length` (number, optional) — default `DEFAULT_LENGTH` (21).
+**Returns:** `string`
+
+### `uuidToBase56(uuid)`
+
+Encodes a UUID into a fixed-width **23-character** base56 string. Reversible via
+`base56ToUuid`. (128 bits need 23 base56 digits — `56^22 ≈ 2^127.76 < 2^128`.)
+
+**Parameters:** `uuid` (string) — a UUID, with or without dashes.
+**Returns:** `string` (23 chars)
+**Throws:** `TypeError` if `uuid` is not a valid 32-hex-digit UUID.
+
+### `base56ToUuid(encoded)`
+
+Decodes a base56 string from `uuidToBase56` back to a canonical UUID.
+
+**Parameters:** `encoded` (string)
+**Returns:** `string` — canonical UUID
+**Throws:** `Error` if `encoded` contains characters outside the base56 alphabet.
+
+### `base56Uuid()`
+
+Generates a fresh UUID and returns its 23-character base56 encoding. Equivalent
+to `uuidToBase56(uuid())`.
+
+**Returns:** `string` (23 chars)
+
+**Example:**
+
+```typescript
+const id = base56Uuid(); // "2WjkHTAH3tTuAHceeZxnuDL"
+base56ToUuid(id); // the original uuid
+```
+
+---
+
+## Alphabet strategies
+
+Fixed-length random strings over a named alphabet. Each takes an optional
+`length` (default `DEFAULT_LENGTH` = 21) and returns a `string`.
+
+| Function                     | Alphabet                                                      |
+| ---------------------------- | ------------------------------------------------------------- |
+| `nanoid(length?, alphabet?)` | URL-safe 64-char (`A–Z a–z 0–9 _ -`); custom alphabet allowed |
+| `hex(length?)`               | `0-9 a-f`                                                     |
+| `base32(length?)`            | Crockford (no I L O U)                                        |
+| `base36(length?)`            | `0-9 a-z`                                                     |
+| `base58(length?)`            | Bitcoin (no 0 O I l)                                          |
+| `base62(length?)`            | `0-9 A-Z a-z`                                                 |
+| `numeric(length?)`           | `0-9` (OTP / numeric coupons)                                 |
+
+**Example:**
+
+```typescript
+nanoid(); // 21-char URL-safe id
+hex(32); // 32-char hex
+numeric(6); // "048217"
+nanoid(10, "ABCDEF01"); // custom alphabet
+```
+
+---
+
+## Counter strategy
+
+In-memory, monotonically increasing ids. State lives for the lifetime of the
+process/page and resets on reload — **not** for cross-process uniqueness.
+
+### `counter(options?)`
+
+Returns the next value of a shared, per-prefix counter. Each distinct `prefix`
+has its own sequence. `start`/`step`/`pad` are honored only on the first call
+that creates a prefix's sequence.
+
+**Parameters:** `options` (`CounterOptions`, optional)
+**Returns:** `string`
+**Throws:** `TypeError` for invalid `prefix`/`start`/`step`/`pad`.
+
+### `createCounter(options?)`
+
+Creates an isolated counter function with its own private state — no sharing with
+`counter()` or other instances. Prefer this for independent sequences or
+deterministic tests.
+
+**Parameters:** `options` (`CounterOptions`, optional)
+**Returns:** `() => string`
+
+### `resetCounters(prefix?)`
+
+Clears the shared state used by `counter()`. Mainly for tests. Does not affect
+`createCounter` instances.
+
+**Parameters:** `prefix` (string, optional) — reset only this prefix; omit to
+reset all.
+**Returns:** `void`
+
+**Example:**
+
+```typescript
+const next = createCounter({ prefix: "row-", start: 1, pad: 4 });
+next(); // "row-0001"
+next(); // "row-0002"
+```
+
+---
+
+## Reversible integer codec
+
+A small "sqids/hashids-lite": encode a non-negative integer to a short string
+and back. A `salt` deterministically shuffles the alphabet so sequential ids
+don't look sequential. **Obfuscation, not encryption** — reversible by anyone
+who knows the salt and alphabet.
+
+### `encodeInt(value, options?)`
+
+**Parameters:**
+
+- `value` (number) — non-negative safe integer (`0 … Number.MAX_SAFE_INTEGER`).
+- `options` (`EncodeIntOptions`, optional)
+
+**Returns:** `string`
+**Throws:** `RangeError` if `value` is out of range, or `alphabet` has fewer than
+2 characters or contains duplicates.
+
+### `decodeInt(str, options?)`
+
+**Parameters:**
+
+- `str` (string) — a string produced by `encodeInt`.
+- `options` (`DecodeIntOptions`, optional) — `alphabet`/`salt` must match those
+  used to encode.
+
+**Returns:** `number`
+**Throws:** `Error` for characters outside the alphabet; `RangeError` for a bad
+alphabet or if the decoded value exceeds the safe-integer range.
+
+**Example:**
+
+```typescript
+const code = encodeInt(12345, { salt: "my-secret" }); // "Yq9"
+decodeInt(code, { salt: "my-secret" }); // 12345
+```
+
+---
+
+## Core primitives
+
+### `randomString(length, alphabet?)`
+
+Random string of `length` characters from `alphabet`, using rejection sampling
+(the nanoid algorithm) so output is unbiased even for non-power-of-two alphabets.
+
+**Parameters:**
+
+- `length` (number) — positive integer.
+- `alphabet` (string, optional) — 1–256 characters. Default: the URL-safe nanoid
+  alphabet.
+
+**Returns:** `string`
+**Throws:** `TypeError` for non-positive-integer `length` or non-string
+`alphabet`; `RangeError` if `alphabet` length is outside 1–256.
+
+### `randomBytes(size)`
+
+`size` cryptographically-strong random bytes. Transparently chunks calls larger
+than the 65536-byte `getRandomValues` limit.
+
+**Parameters:** `size` (number) — positive integer.
+**Returns:** `Uint8Array`
+
+### `assertPositiveInt(n, label)` / `assertNonNegativeInt(n, label)`
+
+Throw `TypeError` unless `n` is an integer `>= 1` / `>= 0`. The `label` is used
+in the error message. Exposed for building custom strategies with consistent
+validation.
+
+**Returns:** `void` (assertion functions)
+
+---
+
+## Registry
+
+### `registerStrategy(name, fn)`
+
+Registers (or overrides) a strategy under `name`, making it callable via
+`uid(name, options)`.
+
+**Parameters:**
+
+- `name` (string) — non-empty strategy name.
+- `fn` (`StrategyFn`) — `(options?) => string`.
+
+**Returns:** `void`
+**Throws:** `TypeError` for an empty `name` or non-function `fn`.
+
+### `listStrategies()`
+
+**Returns:** `string[]` — names of all currently registered strategies.
+
+**Example:**
+
+```typescript
+import { registerStrategy, uid } from "@marianmeres/uid";
+
+registerStrategy("order", () => "ORD-" + uid("numeric", { length: 8 }));
+uid("order"); // "ORD-40582193"
+```
+
+---
+
+## Opt-in: `@marianmeres/uid/rhr`
+
+### `rhr(options?)`
+
+Human-readable id built on `@marianmeres/random-human-readable`. Joined with `-`
+by default. Importing this module also registers the `rhr` strategy so
+`uid("rhr", …)` works.
+
+**Parameters:** `options` (`RhrOptions`, optional) — passed through to
+`getRandomHumanReadable` (e.g. `adjCount`, `colorsCount`, `nounsCount`,
+`randomizeCase`, `joinWith`).
+
+**Returns:** `string` — e.g. `"happy-blue-otter-canyon"`
+
+**Example:**
+
+```typescript
+import "@marianmeres/uid/rhr"; // enables uid("rhr")
+import { rhr } from "@marianmeres/uid/rhr";
+
+rhr(); // "happy-blue-otter-canyon"
+rhr({ nounsCount: 1 }); // "otter"
+```
+
+On npm, install the peer dependency:
+`npm install @marianmeres/random-human-readable`.
+
+---
+
+## Types
+
+```typescript
+interface Uuidv7Options {
+	timestamp?: number;
+}
+interface UlidOptions {
+	timestamp?: number;
+}
+interface Base56Options {
+	length?: number;
+	uuid?: string;
+}
+interface NanoidOptions {
+	length?: number;
+	alphabet?: string;
+}
+interface AlphabetOptions {
+	length?: number;
+}
+interface CustomOptions {
+	alphabet: string;
+	length?: number;
+}
+interface CounterOptions {
+	prefix?: string;
+	start?: number;
+	step?: number;
+	pad?: number;
+}
+interface EncodeIntOptions {
+	alphabet?: string;
+	salt?: string;
+	minLength?: number;
+}
+interface DecodeIntOptions {
+	alphabet?: string;
+	salt?: string;
+}
+interface ReversibleOptions {
+	value: number;
+	alphabet?: string;
+	salt?: string;
+	minLength?: number;
+}
+interface RhrOptions {/* getRandomHumanReadable options that return a string */}
+type StrategyFn = (options?: Record<string, unknown>) => string;
+```
+
+---
+
+## Constants
+
+### `DEFAULT_LENGTH`
+
+`21` — default length for random, fixed-length strategies.
+
+### `ALPHABETS`
+
+Named alphabets used by the built-in strategies:
+
+```typescript
+ALPHABETS.hex; // "0123456789abcdef"
+ALPHABETS.base32; // Crockford (no I L O U)
+ALPHABETS.base36; // "0-9a-z"
+ALPHABETS.base56; // no 0 O o 1 l I
+ALPHABETS.base58; // Bitcoin (no 0 O I l)
+ALPHABETS.base62; // "0-9A-Za-z"
+ALPHABETS.numeric; // "0123456789"
+ALPHABETS.alphanumeric; // alias of base62
+ALPHABETS.nanoid; // URL-safe 64-char set
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marian Meres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.