@smonn/ids 0.3.4 → 0.4.0

package/README.md

@@ -6,16 +6,16 @@ Public-facing branded IDs for TypeScript apps.
 pnpm add @smonn/ids
 ```
 
-Each ID looks like `usr_01h7b3k9rqxn4cw3p9r8t2sgkz`: a three-letter brand, an underscore, then 26 Crockford base32 characters of payload. The Timestamp codec encodes a 48-bit millisecond Unix timestamp followed by 80 random bits — same byte layout as a [ULID](https://github.com/ulid/spec); see [ADR-0002](./docs/adr/0002-payload-layout.md) for the deliberate divergences. The Opaque codec (`@smonn/ids/opaque`) keeps the same wire shape but encrypts the payload under a key, so the timestamp isn't readable from the ID.
+Each ID looks like `usr_01h7b3k9rqxn4cw3p9r8t2sgkz`: a three-letter brand, an underscore, then 26 Crockford base32 characters of payload. The Timestamp codec encodes a 48-bit millisecond Unix timestamp followed by 80 random bits — same byte layout as a [ULID](https://github.com/ulid/spec); see [ADR-0002](./docs/adr/0002-payload-layout.md) for the deliberate divergences. The Opaque Timestamp codec (`@smonn/ids/opaque`) keeps the same wire shape but encrypts the payload under a key, so the timestamp isn't readable from the ID.
 
 ## What this is for
 
 ### "Give my entities IDs that are safe to expose in URLs, dashboards, and support tickets"
 
 ```ts
-import { createId } from "@smonn/ids";
+import { createTimestampId } from "@smonn/ids";
 
-const users = createId("usr");
+const users = createTimestampId("usr");
 const id = users.generate(); // "usr_01h7b3k9rqxn4cw3p9r8t2sgkz"
 ```
 
@@ -24,10 +24,10 @@ The three-letter brand tells you what kind of thing the ID refers to without an
 ### "Catch me passing a `UserId` where I needed an `OrgId`"
 
 ```ts
-import { type Id, createId } from "@smonn/ids";
+import { type Id, createTimestampId } from "@smonn/ids";
 
-const users = createId("usr");
-const orgs = createId("org");
+const users = createTimestampId("usr");
+const orgs = createTimestampId("org");
 
 function loadUser(id: Id<"usr">) {
   /* ... */
@@ -105,7 +105,7 @@ Caveat: two IDs generated in the same millisecond by the same process have indep
 ### "Inject a fixed clock and RNG so my tests are deterministic"
 
 ```ts
-const users = createId("usr", {
+const users = createTimestampId("usr", {
   now: () => new Date("2026-01-01T00:00:00Z").getTime(),
   rng: (target) => {}, // leave target as zero-filled
 });
@@ -113,14 +113,14 @@ const users = createId("usr", {
 users.generate(); // deterministic snapshot-friendly output
 ```
 
-Both `Options` fields are optional. Defaults are `Date.now` and an entropy harvester built on `crypto.randomUUID` (faster than `crypto.getRandomValues` for the 10-byte fills this library needs). `now` returns milliseconds since the Unix epoch. `rng` writes random bytes into the provided target (a 10-byte view into the codec's persistent buffer), so a custom RNG never has to allocate.
+Both injection fields (`now?` and `rng?`) are optional. Defaults are `Date.now` and an entropy harvester built on `crypto.randomUUID` (faster than `crypto.getRandomValues` for the 10-byte fills this library needs). `now` returns milliseconds since the Unix epoch. `rng` writes random bytes into the provided target (a 10-byte view into the codec's persistent buffer), so a custom RNG never has to allocate.
 
 ### "Catch a double-registered brand before it bites in production"
 
-The intended pattern is one codec per brand per process, constructed at module init. Calling `createId(brand)` a second time for the same brand usually means a bundling or import bug (accidental re-export, a test re-importing without resetting). In development (`process.env.NODE_ENV !== "production"`), the second call emits a one-shot `console.warn`; the brand-tracking registry is skipped in production. The same registry covers cross-codec collisions: `createId("usr")` followed by `createOpaqueId("usr")` warns too, because codec choice is a per-brand commitment ([ADR-0007](./docs/adr/0007-wire-indistinguishable-codec-variants.md)). Tests that intentionally re-create codecs can opt out:
+The intended pattern is one codec per brand per process, constructed at module init. Calling `createTimestampId(brand)` a second time for the same brand usually means a bundling or import bug (accidental re-export, a test re-importing without resetting). In development (`process.env.NODE_ENV !== "production"`), the second call emits a one-shot `console.warn`; the brand-tracking registry is skipped in production. The same registry covers cross-codec collisions: `createTimestampId("usr")` followed by `createOpaqueTimestampId("usr")` warns too, because codec choice is a per-brand commitment ([ADR-0007](./docs/adr/0007-wire-indistinguishable-codec-variants.md)). Tests that intentionally re-create codecs can opt out:
 
 ```ts
-const users = createId("usr", { allowDuplicateBrand: true });
+const users = createTimestampId("usr", { allowDuplicateBrand: true });
 ```
 
 The check is a heuristic, not a guarantee. Two physical copies of `@smonn/ids` loaded into the same process (the worst-case bundling bug) each keep their own registry, so neither warns — it catches re-imports of a single module copy, not duplicate copies of the module itself.
@@ -166,13 +166,13 @@ The `pattern` describes the **canonical form only** — it matches `generate()`
 
 ### "Don't leak creation time in IDs that customers can see"
 
-The Timestamp codec exposes the creation timestamp by design — that's what makes `ORDER BY id` work. If that's a leak you can't accept (invoice IDs revealing billing cadence, signup IDs revealing acquisition velocity), use the Opaque codec at `@smonn/ids/opaque`. Same `<brand>_<26 chars>` wire shape, but the payload is AES-encrypted under a key you supply.
+The Timestamp codec exposes the creation timestamp by design — that's what makes `ORDER BY id` work. If that's a leak you can't accept (invoice IDs revealing billing cadence, signup IDs revealing acquisition velocity), use the Opaque Timestamp codec at `@smonn/ids/opaque`. Same `<brand>_<26 chars>` wire shape, but the payload is AES-encrypted under a key you supply.
 
 ```ts
-import { createOpaqueId, importOpaqueKey } from "@smonn/ids/opaque";
+import { createOpaqueTimestampId, importOpaqueKey } from "@smonn/ids/opaque";
 
 const key = await importOpaqueKey(new Uint8Array(16)); // 128- or 256-bit raw key
-const invoices = createOpaqueId("inv", { key });
+const invoices = createOpaqueTimestampId("inv", { key });
 
 const id = await invoices.generate(); // "inv_…", timestamp not extractable without the key
 await invoices.extractTimestamp(id); // Date — same codec, same key required
@@ -181,7 +181,7 @@ await invoices.extractTimestamp(id); // Date — same codec, same key required
 Three differences from the Timestamp codec:
 
 - **Async key-dependent methods.** WebCrypto is async-only, so `generate`, `generateAt`, and `extractTimestamp` return `Promise`s. `is`, `parse`, `safeParse`, `toJsonSchema`, and the Standard Schema adapter stay sync — they work on the wire form only ([ADR-0006](./docs/adr/0006-async-keyed-codec-contract.md)).
-- **No `minIdForTime` / `maxIdForTime`.** Encrypted payloads don't sort by time. If you need time-range scans on Opaque-coded entities, store the timestamp in a separate column.
+- **No `minIdForTime` / `maxIdForTime`.** Encrypted payloads don't sort by time. If you need time-range scans on entities using the Opaque Timestamp codec, store the timestamp in a separate column.
 - **Wire-indistinguishable from the Timestamp codec.** Codec choice is a per-brand commitment; the brand registry warns if you register the same brand against both in dev ([ADR-0007](./docs/adr/0007-wire-indistinguishable-codec-variants.md)).
 
 Encryption is AES-CBC with a zero IV. That's deliberately safe here because the plaintext already carries 80 bits of entropy per ID; see [ADR-0004](./docs/adr/0004-aes-cbc-strip-trick.md) for the full rationale.
@@ -193,45 +193,45 @@ To store or transport key material outside the library, `encodeOpaqueKey` / `dec
 - **Internal surrogate primary keys.** If nobody outside your service ever sees the ID, the brand prefix and lenient parsing are dead weight. Use a `bigint` sequence.
 - **Wire-compatible ULIDs.** The byte layout is ULID-shaped but the encoding is lowercase and wrapped in a brand envelope. Stock ULID parsers will reject these.
 - **Distributed-trace / request-correlation IDs.** Use OpenTelemetry-format IDs.
-- **Hiding creation time with the Timestamp codec.** Anyone with one ID at a known creation time can compute the epoch offset. A custom epoch wouldn't help and isn't supported. To hide creation time per-ID, use the Opaque codec (above).
+- **Hiding creation time with the Timestamp codec.** Anyone with one ID at a known creation time can compute the epoch offset. A custom epoch wouldn't help and isn't supported. To hide creation time per-ID, use the Opaque Timestamp codec (above).
 
 ## API surface
 
 ```ts
 import {
-  createId, // (brand: string, opts?: Partial<Options>) => Codec<Brand>
+  createTimestampId, // (brand: string, opts?: TimestampOptions) => TimestampCodec<Brand>
   type Id, // branded string type
-  type Codec, // returned by createId
-  type Options, // { now, rng, allowDuplicateBrand } injection points
+  type TimestampCodec, // returned by createTimestampId
+  type TimestampOptions, // { now?, rng?, allowDuplicateBrand? } constructor options
   type ParseError, // "not_string" | "invalid_prefix" | "invalid_base32"
   type ParseResult, // safeParse return type
   type JsonSchema, // toJsonSchema return type
 } from "@smonn/ids";
 
 import {
-  createOpaqueId, // (brand: string, opts: { key, now?, rng?, allowDuplicateBrand? }) => OpaqueCodec<Brand>
+  createOpaqueTimestampId, // (brand: string, opts: OpaqueTimestampOptions) => OpaqueTimestampCodec<Brand>
   importOpaqueKey, // (bytes: Uint8Array) => Promise<CryptoKey>
   encodeOpaqueKey, // (bytes: Uint8Array, format: OpaqueKeyFormat) => string
   decodeOpaqueKey, // (encoded: string, format: OpaqueKeyFormat) => Uint8Array
-  type OpaqueCodec, // returned by createOpaqueId
-  type OpaqueOptions, // { key, now, rng, allowDuplicateBrand } injection points
+  type OpaqueTimestampCodec, // returned by createOpaqueTimestampId
+  type OpaqueTimestampOptions, // { key, now?, rng?, allowDuplicateBrand? } constructor options
   type OpaqueKeyFormat, // "hex" | "base64url"
 } from "@smonn/ids/opaque";
 ```
 
 ### Codec methods
 
-| Method                 | `Codec<Brand>` | `OpaqueCodec<Brand>` | Description                                                                   |
-| ---------------------- | -------------- | -------------------- | ----------------------------------------------------------------------------- |
-| `generate()`           | sync           | async                | Produce a fresh ID                                                            |
-| `generateAt(date)`     | sync           | async                | Produce a fresh ID with timestamp bytes from `date` (for backfills)           |
-| `is(value)`            | sync           | sync                 | Strict type guard: `true` only for already-canonical strings                  |
-| `parse(value)`         | sync           | sync                 | Lenient: normalise to canonical, or throw                                     |
-| `safeParse(value)`     | sync           | sync                 | Lenient: normalise to canonical, or return `{ ok: false, error }`             |
-| `extractTimestamp(id)` | sync           | async                | Decode the creation `Date` from an `Id<Brand>` (trusts the type)              |
-| `minIdForTime(date)`   | sync           | —                    | Tight lower bound for any ID generated at `date` (for range queries)          |
-| `maxIdForTime(date)`   | sync           | —                    | Tight upper bound for any ID generated at `date` (for range queries)          |
-| `toJsonSchema()`       | sync           | sync                 | JSON Schema (`type`/`pattern`/`description`/`example`) for the canonical form |
+| Method                 | `TimestampCodec<Brand>` | `OpaqueTimestampCodec<Brand>` | Description                                                                   |
+| ---------------------- | ----------------------- | ----------------------------- | ----------------------------------------------------------------------------- |
+| `generate()`           | sync                    | async                         | Produce a fresh ID                                                            |
+| `generateAt(date)`     | sync                    | async                         | Produce a fresh ID with timestamp bytes from `date` (for backfills)           |
+| `is(value)`            | sync                    | sync                          | Strict type guard: `true` only for already-canonical strings                  |
+| `parse(value)`         | sync                    | sync                          | Lenient: normalise to canonical, or throw                                     |
+| `safeParse(value)`     | sync                    | sync                          | Lenient: normalise to canonical, or return `{ ok: false, error }`             |
+| `extractTimestamp(id)` | sync                    | async                         | Decode the creation `Date` from an `Id<Brand>` (trusts the type)              |
+| `minIdForTime(date)`   | sync                    | —                             | Tight lower bound for any ID generated at `date` (for range queries)          |
+| `maxIdForTime(date)`   | sync                    | —                             | Tight upper bound for any ID generated at `date` (for range queries)          |
+| `toJsonSchema()`       | sync                    | sync                          | JSON Schema (`type`/`pattern`/`description`/`example`) for the canonical form |
 
 ## CLI
 
@@ -249,7 +249,7 @@ canonical: usr_01h7b3k9rqxn1cw3p9r8t2sgkz
 input:     canonical
 ```
 
-Accepts non-canonical input (uppercase, Crockford aliases). Assumes the **Timestamp codec** — if the brand uses the **Opaque codec**, pass `--opaque` and set `IDS_KEY` (below); otherwise the timestamp line is meaningless garbage.
+Accepts non-canonical input (uppercase, Crockford aliases). Assumes the **Timestamp codec** — if the brand uses the **Opaque Timestamp codec**, pass `--opaque` and set `IDS_KEY` (below); otherwise the timestamp line is meaningless garbage.
 
 ```bash
 IDS_KEY=<hex-or-base64url-key> npx @smonn/ids inspect inv_… --opaque
@@ -268,7 +268,7 @@ usr_…
 usr_…
 ```
 
-Flags: `--count` / `-c N` (default 1). Uses the Timestamp codec unless `--opaque` is set.
+Flags: `--count` / `-c N` (default 1, max 10000). Uses the Timestamp codec unless `--opaque` is set.
 
 ```bash
 IDS_KEY=<hex-or-base64url-key> npx @smonn/ids generate inv --opaque --count 2