@typed/id 1.0.0-beta.1 → 1.0.0-beta.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present The Contributors
+
+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.

package/README.md

@@ -8,6 +8,27 @@
 
 - `effect`
 
+Install both packages in an ESM project:
+
+```sh
+pnpm add @typed/id effect
+```
+
+`@typed/id` publishes ES modules; use `import` rather than CommonJS `require`.
+
+## Runtime requirements
+
+The default layers target runtimes with the standard Web Crypto and encoding globals:
+
+- `crypto.getRandomValues` supplies entropy for `RandomValues.Default`.
+- `crypto.subtle.digest` is used by CUID and UUID v5 generation.
+- `TextEncoder` and `BigInt` are used by the string and time encoders.
+
+These globals are available in modern browsers and current Node.js releases. Runtimes without the
+encoding or digest globals must install equivalents. Custom `RandomValues` and `DateTimes` services
+can replace the default entropy and clock sources, but they do not replace `crypto.subtle.digest`
+for CUID or UUID v5 generation.
+
 ## API overview
 
 - **Cuid** — Schema + type; `CuidState` service; Effect to generate Cuid.
@@ -23,39 +44,119 @@
 
 ```ts
 import { Ids, Uuid5Namespace } from "@typed/id";
+import { IdsTest } from "@typed/id/IdsTest";
+import * as Effect from "effect/Effect";
+
+const program = Effect.gen(function* () {
+  const cuid = yield* Ids.cuid;
+  const ksuid = yield* Ids.ksuid;
+  const nanoId = yield* Ids.nanoId;
+  const ulid = yield* Ids.ulid;
+  const uuid4 = yield* Ids.uuid4;
+  const uuid5 = yield* Ids.uuid5("https://effect.website", Uuid5Namespace.URL);
+  const uuid7 = yield* Ids.uuid7;
+
+  return { cuid, ksuid, nanoId, ulid, uuid4, uuid5, uuid7 };
+});
+
+const ids = await Effect.runPromise(Effect.provide(program, Ids.Default));
+console.log(ids);
+```
+
+Use `IdsTest()` from `@typed/id/IdsTest` instead of `Ids.Default` when the same program needs
+deterministic test data.
+
+## Values and serialization
+
+Generated IDs are branded strings: the brand exists only in TypeScript, while runtime equality,
+`Map`/`Set` keys, JSON, and structured clone use ordinary string semantics. Store and transmit the
+string directly. Deserialization or structured clone does not restore the TypeScript brand;
+validate untrusted or persisted strings with the matching exported Schema or `is*` predicate
+before treating them as branded values.
+
+| Generator | Serialized output from this package                              |
+| --------- | ---------------------------------------------------------------- |
+| CUID      | 24 lowercase base36 characters; the first character is a letter. |
+| KSUID     | 27 base62 characters.                                            |
+| Nano ID   | 21 characters from `0-9a-zA-Z_-`.                                |
+| ULID      | 26 uppercase Crockford base32 characters.                        |
+| UUID      | Canonical lowercase hyphenated UUID text.                        |
 
-const id = yield * Ids.cuid;
-const id = yield * Ids.ksuid;
-const id = yield * Ids.nanoId;
-const id = yield * Ids.ulid;
-const id = yield * Ids.uuid4;
-const id = yield * Ids.uuid5("https://effect.website", Uuid5Namespace.URL);
-const id = yield * Ids.uuid7;
-
-// Provide Ids services
-Effect.provide(Ids.Default);
-Effect.provide(Ids.Test());
+UUID v5 is deterministic for the same UTF-8 name and namespace bytes. The other default
+generators incorporate time, entropy, or state and should not be treated as reproducible values.
+
+## Service and seed lifecycle
+
+`Ids.Default` is the usual production layer. It wires the clock, secure randomness, and the
+stateful CUID and UUID v7 generators into the `Ids` facade. Build and share that layer at the
+application scope where IDs must belong to one sequence; rebuilding a state layer resets its
+in-memory counter.
+
+The standalone generators have narrower requirements:
+
+| Generator         | Required services              |
+| ----------------- | ------------------------------ |
+| `cuid`            | `CuidState`                    |
+| `uuid7`           | `Uuid7State`                   |
+| `ksuid`, `ulid`   | `DateTimes` and `RandomValues` |
+| `nanoId`, `uuid4` | `RandomValues`                 |
+| `uuid5`           | None                           |
+
+`RandomValues.Default` uses Web Crypto and is the production entropy source. `RandomValues.Random`
+derives bytes from Effect's current `Random` service and is intended for controlled tests or
+simulations, not as a cryptographic entropy source. `IdsTest()` supplies fixed internal entropy
+and a controllable clock; its output is for repeatable tests, not production IDs. Service state is
+process-local and is not a serialization format or a persistence mechanism.
+
+`CuidSeed` and `Uuid7Seed` describe one generation step; they are not serialized IDs or snapshots
+of the state service. `CuidState` and `Uuid7State` are themselves Effect-valued services that yield
+the next seed. When assembling one manually, construct the service with `Layer.effect` and provide
+its clock and entropy dependencies to that layer:
+
+```ts
+import { CuidState, DateTimes, RandomValues, cuid } from "@typed/id";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Random from "effect/Random";
+
+const deterministicRandomValues = Layer.effect(
+  RandomValues,
+  RandomValues.pipe(Effect.provide(RandomValues.Random), Random.withSeed("documentation-example")),
+);
+
+const deterministicCuidState = Layer.effect(
+  CuidState,
+  CuidState.make("documentation-example"),
+).pipe(Layer.provide([DateTimes.Fixed(1_700_000_000_000), deterministicRandomValues]));
+
+const id = await Effect.runPromise(Effect.provide(cuid, deterministicCuidState));
 ```
 
+This provider is deterministic and is therefore test-only. Application code normally uses
+`Ids.Default` or `CuidState.Default`.
+
 ## API reference
 
-### Ids
+### Ids and IdsTest
 
-Unified service for generating all ID types. Requires `DateTimes`, `RandomValues`, `CuidState`, and `Uuid7State` (use `Ids.Default` or `Ids.Test()` to provide them).
+Unified service for generating all ID types. Requires `DateTimes`, `RandomValues`, `CuidState`, and `Uuid7State` (use `Ids.Default` or `IdsTest()` to provide them).
 
-| Member               | Type                                             | Description                                                                                                             |
-| -------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| `Ids.cuid`           | `Effect<Cuid, never, Ids>`                       | Generate a Cuid.                                                                                                        |
-| `Ids.ksuid`          | `Effect<Ksuid, never, Ids>`                      | Generate a Ksuid.                                                                                                       |
-| `Ids.nanoId`         | `Effect<NanoId, never, Ids>`                     | Generate a NanoId.                                                                                                      |
-| `Ids.ulid`           | `Effect<Ulid, never, Ids>`                       | Generate a ULID.                                                                                                        |
-| `Ids.uuid4`          | `Effect<Uuid4, never, Ids>`                      | Generate a UUID v4.                                                                                                     |
-| `Ids.uuid5`          | `(name, namespace) => Effect<Uuid5, never, Ids>` | Generate a UUID v5 from a name and namespace. Also has `Ids.uuid5.dns`, `.url`, `.oid`, `.x500` taking a single `name`. |
-| `Ids.uuid7`          | `Effect<Uuid7, never, Ids>`                      | Generate a UUID v7.                                                                                                     |
-| `Ids.Default`        | `Layer<Ids \| DateTimes \| RandomValues>`        | Layer that provides `Ids` with default Cuid/Uuid7/DateTimes/RandomValues.                                               |
-| `Ids.Test(options?)` | `Layer<Ids \| DateTimes \| RandomValues>`        | Layer for tests; optional `currentTime` and `envData`.                                                                  |
+| Member               | Type                                                            | Description                                                                                             |
+| -------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `Ids.cuid`           | `Effect<Cuid, never, Ids>`                                      | Generate a Cuid.                                                                                        |
+| `Ids.ksuid`          | `Effect<Ksuid, IllegalArgumentError, Ids>`                      | Generate a Ksuid; invalid service timestamps fail.                                                      |
+| `Ids.nanoId`         | `Effect<NanoId, never, Ids>`                                    | Generate a NanoId.                                                                                      |
+| `Ids.ulid`           | `Effect<Ulid, IllegalArgumentError, Ids>`                       | Generate a ULID; invalid service timestamps fail.                                                       |
+| `Ids.uuid4`          | `Effect<Uuid4, never, Ids>`                                     | Generate a UUID v4.                                                                                     |
+| `Ids.uuid5`          | `(name, namespace) => Effect<Uuid5, IllegalArgumentError, Ids>` | Generate a UUID v5; namespaces not exactly 16 bytes fail. Also has `.dns`, `.url`, `.oid`, and `.x500`. |
+| `Ids.uuid7`          | `Effect<Uuid7, IllegalArgumentError, Ids>`                      | Generate a UUID v7; timestamps outside its 48-bit field fail before state mutation.                     |
+| `Ids.Default`        | `Layer<Ids \| DateTimes \| RandomValues>`                       | Layer that provides `Ids` with default Cuid/Uuid7/DateTimes/RandomValues.                               |
+| `IdsTest(options?)` | `Layer<Ids \| DateTimes \| RandomValues, IllegalArgumentError>` | Reproducible test layer; invalid `currentTime` values fail.                                             |
 
-**TestOptions:** `{ currentTime?: number | string | Date; envData?: string }`
+**IdsTestOptions:**
+`{ currentTime?: number | string | Date; envData?: string }`
+
+`IdsTest()` defaults to time `1_400_000_000_000` and uses fixed internal test entropy.
 
 ---
 
@@ -63,23 +164,30 @@ Unified service for generating all ID types. Requires `DateTimes`, `RandomValues
 
 | Export              | Type                               | Description                                        |
 | ------------------- | ---------------------------------- | -------------------------------------------------- |
-| `Cuid`              | `Schema<string, Cuid>`             | Branded schema for Cuid strings.                   |
+| `Cuid`              | `Schema<string, Cuid>`             | Branded schema for 24-character Cuid strings.      |
 | `Cuid` (type)       | `string`                           | Branded Cuid type.                                 |
 | `isCuid`            | `(value: string) => value is Cuid` | Type guard.                                        |
 | `CuidState`         | Service                            | Provides `next: Effect<CuidSeed>`. Used by `cuid`. |
 | `CuidState.Default` | `Layer<CuidState>`                 | Default CuidState (uses `"node"` envData).         |
 | `cuid`              | `Effect<Cuid, never, CuidState>`   | Generate a Cuid.                                   |
 
+`envData` is a caller-provided discriminator incorporated into CUID generation. It is not a
+detected machine fingerprint and does not provide a uniqueness guarantee by itself.
+
+> **Beta migration:** CUID generation now consumes the complete seed with domain-separated,
+> unbiased sampling. The 24-character serialized shape is unchanged, but fixed fixtures,
+> persisted expected values, and cross-version deterministic snapshots must be updated.
+
 ---
 
 ### Ksuid
 
-| Export         | Type                                              | Description                               |
-| -------------- | ------------------------------------------------- | ----------------------------------------- |
-| `Ksuid`        | `Schema<string, Ksuid>`                           | Branded schema for 27-char base62 Ksuids. |
-| `Ksuid` (type) | `string`                                          | Branded Ksuid type.                       |
-| `isKsuid`      | `(value: string) => value is Ksuid`               | Type guard.                               |
-| `ksuid`        | `Effect<Ksuid, never, DateTimes \| RandomValues>` | Generate a Ksuid.                         |
+| Export         | Type                                                             | Description                                                              |
+| -------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `Ksuid`        | `Schema<string, Ksuid>`                                          | Branded schema for 27-char base62 Ksuids.                                |
+| `Ksuid` (type) | `string`                                                         | Branded Ksuid type.                                                      |
+| `isKsuid`      | `(value: string) => value is Ksuid`                              | Type guard.                                                              |
+| `ksuid`        | `Effect<Ksuid, IllegalArgumentError, DateTimes \| RandomValues>` | Generate a Ksuid; timestamps must fit its unsigned 32-bit seconds field. |
 
 ---
 
@@ -96,12 +204,12 @@ Unified service for generating all ID types. Requires `DateTimes`, `RandomValues
 
 ### Ulid
 
-| Export        | Type                                             | Description                      |
-| ------------- | ------------------------------------------------ | -------------------------------- |
-| `Ulid`        | `Schema<string, Ulid>`                           | Branded schema for ULID strings. |
-| `Ulid` (type) | `string`                                         | Branded Ulid type.               |
-| `isUlid`      | `(value: string) => value is Ulid`               | Type guard.                      |
-| `ulid`        | `Effect<Ulid, never, DateTimes \| RandomValues>` | Generate a ULID.                 |
+| Export        | Type                                                            | Description                                                        |
+| ------------- | --------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `Ulid`        | `Schema<string, Ulid>`                                          | Branded schema for ULID strings.                                   |
+| `Ulid` (type) | `string`                                                        | Branded Ulid type.                                                 |
+| `isUlid`      | `(value: string) => value is Ulid`                              | Type guard.                                                        |
+| `ulid`        | `Effect<Ulid, IllegalArgumentError, DateTimes \| RandomValues>` | Generate a ULID; timestamps must fit its 48-bit millisecond field. |
 
 ---
 
@@ -118,47 +226,47 @@ Unified service for generating all ID types. Requires `DateTimes`, `RandomValues
 
 ### Uuid5
 
-| Export                                          | Type                                                                             | Description                                            |
-| ----------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| `Uuid5`                                         | `Schema<string, Uuid5>`                                                          | Branded schema for UUID v5.                            |
-| `Uuid5` (type)                                  | `string`                                                                         | Branded Uuid5 type.                                    |
-| `Uuid5Namespace`                                | `Uint8Array` (type) + const object                                               | Namespace type; const has `DNS`, `URL`, `OID`, `X500`. |
-| `isUuid5`                                       | `(value: string) => value is Uuid5`                                              | Type guard.                                            |
-| `uuid5`                                         | `(name, namespace) => Effect<Uuid5>` or `(namespace) => (name) => Effect<Uuid5>` | Generate UUID v5 from name + namespace.                |
-| `dnsUuid5`, `urlUuid5`, `oidUuid5`, `x500Uuid5` | `(name: string) => Effect<Uuid5>`                                                | Pre-bound effects for standard namespaces.             |
+| Export                                          | Type                                                                  | Description                                                                         |
+| ----------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `Uuid5`                                         | `Schema<string, Uuid5>`                                               | Branded schema for UUID v5.                                                         |
+| `Uuid5` (type)                                  | `string`                                                              | Branded Uuid5 type.                                                                 |
+| `Uuid5Namespace`                                | `Uint8Array` (type) + const object                                    | Namespace type; `DNS`, `URL`, `OID`, and `X500` each return a fresh canonical copy. |
+| `isUuid5`                                       | `(value: string) => value is Uuid5`                                   | Type guard.                                                                         |
+| `uuid5`                                         | `(name, namespace) => Effect<Uuid5, IllegalArgumentError>` or curried | Generate UUID v5; the namespace must contain exactly 16 bytes.                      |
+| `dnsUuid5`, `urlUuid5`, `oidUuid5`, `x500Uuid5` | `(name: string) => Effect<Uuid5, IllegalArgumentError>`               | Pre-bound effects for standard namespaces.                                          |
 
 ---
 
 ### Uuid7
 
-| Export               | Type                                | Description                                          |
-| -------------------- | ----------------------------------- | ---------------------------------------------------- |
-| `Uuid7`              | `Schema<string, Uuid7>`             | Branded schema for UUID v7.                          |
-| `Uuid7` (type)       | `string`                            | Branded Uuid7 type.                                  |
-| `isUuid7`            | `(value: string) => value is Uuid7` | Type guard.                                          |
-| `Uuid7State`         | Service                             | Provides `next: Effect<Uuid7Seed>`. Used by `uuid7`. |
-| `Uuid7State.Default` | `Layer<Uuid7State>`                 | Default Uuid7State.                                  |
-| `uuid7`              | `Effect<Uuid7, never, Uuid7State>`  | Generate a UUID v7.                                  |
+| Export               | Type                                              | Description                                                                |
+| -------------------- | ------------------------------------------------- | -------------------------------------------------------------------------- |
+| `Uuid7`              | `Schema<string, Uuid7>`                           | Branded schema for UUID v7.                                                |
+| `Uuid7` (type)       | `string`                                          | Branded Uuid7 type.                                                        |
+| `isUuid7`            | `(value: string) => value is Uuid7`               | Type guard.                                                                |
+| `Uuid7State`         | Service                                           | Provides `next: Effect<Uuid7Seed, IllegalArgumentError>`. Used by `uuid7`. |
+| `Uuid7State.Default` | `Layer<Uuid7State>`                               | Default Uuid7State.                                                        |
+| `uuid7`              | `Effect<Uuid7, IllegalArgumentError, Uuid7State>` | Generate a UUID v7; invalid or exhausted timestamps fail.                  |
 
 ---
 
 ### DateTimes
 
-| Export                      | Type                               | Description                                                     |
-| --------------------------- | ---------------------------------- | --------------------------------------------------------------- |
-| `DateTimes`                 | Service                            | Provides `now: Effect<number>`, `date: Effect<Date>`.           |
-| `DateTimes.now`             | `Effect<number, never, DateTimes>` | Current time in ms.                                             |
-| `DateTimes.date`            | `Effect<Date, never, DateTimes>`   | Current date.                                                   |
-| `DateTimes.Default`         | `Layer<DateTimes>`                 | Real clock.                                                     |
-| `DateTimes.Fixed(baseDate)` | `Layer<DateTimes>`                 | Fixed time for tests; `baseDate` is `number \| string \| Date`. |
+| Export                      | Type                                     | Description                                                           |
+| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------- |
+| `DateTimes`                 | Service                                  | Provides `now: Effect<number>`, `date: Effect<Date>`.                 |
+| `DateTimes.now`             | `Effect<number, never, DateTimes>`       | Current time in ms.                                                   |
+| `DateTimes.date`            | `Effect<Date, never, DateTimes>`         | Current date.                                                         |
+| `DateTimes.Default`         | `Layer<DateTimes>`                       | Real clock.                                                           |
+| `DateTimes.Fixed(baseDate)` | `Layer<DateTimes, IllegalArgumentError>` | Fixed time for tests; invalid `number \| string \| Date` inputs fail. |
 
 ---
 
 ### RandomValues
 
-| Export                      | Type                                      | Description                                           |
-| --------------------------- | ----------------------------------------- | ----------------------------------------------------- |
-| `RandomValues`              | Service                                   | Provides a function `(length) => Effect<Uint8Array>`. |
-| `RandomValues.call(length)` | `Effect<Uint8Array, never, RandomValues>` | Request `length` cryptographically random bytes.      |
-| `RandomValues.Default`      | `Layer<RandomValues>`                     | Uses `crypto.getRandomValues`.                        |
-| `RandomValues.Random`       | `Layer<RandomValues>`                     | Uses Effect `Random` (e.g. for tests).                |
+| Export                      | Type                                                               | Description                               |
+| --------------------------- | ------------------------------------------------------------------ | ----------------------------------------- |
+| `RandomValues`              | Service                                                            | Provides exact-length random bytes.       |
+| `RandomValues.call(length)` | `Effect<Uint8Array & { readonly length: N }, never, RandomValues>` | Request exactly `N` random bytes.         |
+| `RandomValues.Default`      | `Layer<RandomValues>`                                              | Uses `crypto.getRandomValues`.            |
+| `RandomValues.Random`       | `Layer<RandomValues>`                                              | Uses the current Effect `Random` service. |

package/dist/Cuid.d.ts

@@ -1,40 +1,155 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
-import * as ServiceMap from "effect/ServiceMap";
+import * as Context from "effect/Context";
 import { DateTimes } from "./DateTimes.js";
 import { RandomValues } from "./RandomValues.js";
+/**
+ * Effect Schema and branded string type for 24-character CUID values.
+ * @remarks
+ * ## Why
+ * The schema validates transport or persisted strings before restoring the compile-time brand; generating a new client ID is not hydration identity.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { Cuid } from "@typed/id/Cuid"
+ * const id = Cuid.make("a00000000000000000000000")
+ * ```
+ * See [Effect Schema](https://effect.website/docs/schema/introduction/).
+ * @category ID schemas
+ * @since 1.0.0
+ */
 export declare const Cuid: Schema.brand<Schema.String, "@typed/id/CUID">;
 export type Cuid = Schema.Schema.Type<typeof Cuid>;
+/**
+ * Tests whether a string is a valid branded CUID.
+ * @remarks
+ * ## Why
+ * Runtime refinement restores trust after JSON, structured clone, or other transport has erased the TypeScript brand.
+ * ## Ownership and lifetime
+ * This pure predicate acquires no resources and retains no input.
+ * @example
+ * ```ts
+ * import { isCuid } from "@typed/id/Cuid"
+ * isCuid("a00000000000000000000000")
+ * ```
+ * @category ID validation
+ * @since 1.0.0
+ */
 export declare const isCuid: (value: string) => value is Cuid;
+/**
+ * The complete deterministic input used to derive one CUID.
+ * @remarks
+ * ## Why
+ * Keeping time, sequence, entropy, and caller fingerprint explicit makes generator identity rules testable and reviewable.
+ * ## Ownership and lifetime
+ * This data acquires no resources; callers own the random byte array and state services produce fresh seeds.
+ * @example
+ * ```ts
+ * import type { CuidSeed } from "@typed/id/Cuid"
+ * const seed: CuidSeed = { timestamp: 0, counter: 0, random: new Uint8Array(32) as CuidSeed["random"], fingerprint: "test" }
+ * ```
+ * @category ID types
+ * @since 1.0.0
+ */
 export type CuidSeed = {
+    /** Millisecond timestamp sampled for this seed. Inherits the seed's resource-free lifetime. @since 1.0.0 */
     readonly timestamp: number;
+    /** Process-local sequence value for this seed. Inherits the seed's resource-free lifetime. @since 1.0.0 */
     readonly counter: number;
-    readonly random: Uint8Array;
+    /** Fresh 32-byte entropy buffer owned by this seed's consumer. @since 1.0.0 */
+    readonly random: Uint8Array & {
+        readonly length: 32;
+    };
+    /** Caller-derived discriminator captured by the CuidState instance. @since 1.0.0 */
     readonly fingerprint: string;
 };
-declare const CuidState_base: ServiceMap.ServiceClass<CuidState, "@typed/id/CuidState", Effect.Effect<{
-    timestamp: number;
-    counter: number;
-    random: Uint8Array<ArrayBufferLike>;
-    fingerprint: string;
-}, never, never>> & {
-    readonly make: (envData: string) => Effect.Effect<Effect.Effect<{
+declare const CuidState_base: Context.ServiceClass<CuidState, "@typed/id/CuidState", {
+    next: Effect.Effect<{
         timestamp: number;
         counter: number;
-        random: Uint8Array<ArrayBufferLike>;
+        random: Uint8Array<ArrayBufferLike> & {
+            readonly length: 32;
+        };
         fingerprint: string;
-    }, never, never>, never, DateTimes | RandomValues>;
+    }, never, never>;
+}> & {
+    readonly make: (envData: string) => Effect.Effect<{
+        next: Effect.Effect<{
+            timestamp: number;
+            counter: number;
+            random: Uint8Array<ArrayBufferLike> & {
+                readonly length: 32;
+            };
+            fingerprint: string;
+        }, never, never>;
+    }, never, DateTimes | RandomValues>;
 };
+/**
+ * Process-local Effect service that supplies sequential CUID seeds.
+ * @remarks
+ * ## Why
+ * Counter state and caller-provided `envData` live in an explicit service so tests and applications choose the sharing boundary instead of relying on hidden globals.
+ * ## Ownership and lifetime
+ * Each Layer instance owns its mutable counter and captured fingerprint. A new process, worker, or Layer resets that sequence; exact SSR identity must be serialized and reused.
+ * @example
+ * ```ts
+ * import { cuid, CuidState } from "@typed/id/Cuid"
+ * import { Effect } from "effect"
+ * const program = Effect.provide(cuid, CuidState.Default)
+ * ```
+ * See [Effect services](https://effect.website/docs/requirements-management/services/) and [Layers](https://effect.website/docs/requirements-management/layers/).
+ * @category Sequence state
+ * @since 1.0.0
+ */
 export declare class CuidState extends CuidState_base {
+    /**
+     * Reads one seed from the current CuidState service.
+     * @remarks
+     * ## Why
+     * The accessor exposes stateful sequencing through Effect's service channel rather than a module-global counter.
+     * ## Ownership and lifetime
+     * The Effect requires `CuidState`; its Layer owns the counter for the Layer lifetime.
+     * @category Services
+     * @since 1.0.0
+     */
     static readonly next: Effect.Effect<{
         timestamp: number;
         counter: number;
-        random: Uint8Array<ArrayBufferLike>;
+        random: Uint8Array<ArrayBufferLike> & {
+            readonly length: 32;
+        };
         fingerprint: string;
     }, never, CuidState>;
-    static readonly Default: Layer.Layer<DateTimes | RandomValues | CuidState, never, never>;
+    /**
+     * Provides a default CuidState backed by system time and Web Crypto entropy.
+     * @remarks
+     * ## Why
+     * The explicit Layer gives production code a standard service while keeping test and environment-specific alternatives replaceable.
+     * ## Ownership and lifetime
+     * Layer acquisition creates one counter state; the surrounding Layer Scope owns it. Web Crypto must be available in the runtime.
+     * @category Production layers
+     * @since 1.0.0
+     */
+    static readonly Default: Layer.Layer<CuidState, never, never>;
 }
+/**
+ * Generates one CUID from the current CuidState service.
+ * @remarks
+ * ## Why
+ * Generation is an Effect so sequencing and entropy dependencies remain explicit and replaceable; `envData` is only a caller discriminator, not a machine fingerprint guarantee. Missing Web Crypto or rejected SHA-512 work is a defect because the typed error channel is `never`.
+ * ## Ownership and lifetime
+ * The Effect acquires no resources itself and uses the CuidState owned by its provided Layer.
+ * @example
+ * ```ts
+ * import { cuid, CuidState } from "@typed/id/Cuid"
+ * import { Effect } from "effect"
+ * const id = Effect.provide(cuid, CuidState.Default)
+ * ```
+ * @category ID generation
+ * @since 1.0.0
+ */
 export declare const cuid: Effect.Effect<Cuid, never, CuidState>;
 export {};
 //# sourceMappingURL=Cuid.d.ts.map

package/dist/Cuid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cuid.d.ts","sourceRoot":"","sources":["../src/Cuid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAQjD,eAAO,MAAM,IAAI,+CAGhB,CAAC;AACF,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnD,eAAO,MAAM,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,IAAsB,CAAC;AAGxE,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,CAAC;;;;;;;6BAGgB,MAAM;;;;;;;AADxB,qBAAa,SAAU,SAAQ,cA8B7B;IACA,MAAM,CAAC,QAAQ,CAAC,IAAI;;;;;yBAAwC;IAE5D,MAAM,CAAC,QAAQ,CAAC,OAAO,kEAErB;CACH;AAED,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAGtD,CAAC"}
+{"version":3,"file":"Cuid.d.ts","sourceRoot":"","sources":["../src/Cuid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAOjD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI,+CAGhB,CAAC;AACF,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,IAAsB,CAAC;AAGxE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,4GAA4G;IAC5G,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2GAA2G;IAC3G,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAA;KAAE,CAAC;IACtD,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,CAAC;;;;;;;;;;;6BAoBgB,MAAM;;;;;;;;;;;AAlBxB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAU,SAAQ,cAgC7B;IACA;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI;;;;;;;yBAGjB;IAEH;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,uCAErB;CACH;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAGtD,CAAC"}