@typed/id 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/RandomValues.js

@@ -1,19 +1,83 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Random from "effect/Random";
-import * as ServiceMap from "effect/ServiceMap";
-export class RandomValues extends ServiceMap.Service()("@typed/id/RandomValues", {
-    make: Effect.succeed((length) => Effect.sync(() => crypto.getRandomValues(new Uint8Array(length)))),
+import * as Context from "effect/Context";
+const allocate = (length, fill) => {
+    const view = new Uint8Array(length);
+    fill(view);
+    return view;
+};
+const fillFromWebCrypto = (view) => {
+    const webCrypto = globalThis.crypto;
+    if (typeof webCrypto?.getRandomValues !== "function") {
+        throw new TypeError("RandomValues.Default requires globalThis.crypto.getRandomValues. Provide RandomValues.Random or a custom RandomValues service for unsupported runtimes.");
+    }
+    void webCrypto.getRandomValues(view);
+};
+const fromRandom = (random) => RandomValues.of((length) => Effect.sync(() => allocate(length, (view) => {
+    for (let i = 0; i < length; ++i)
+        view[i] = random.nextIntUnsafe();
+})));
+/**
+ * Effect service that produces fresh byte arrays of an exact requested length.
+ * @remarks
+ * ## Why
+ * Entropy is an explicit dependency so secure production generation and reproducible tests use the same typed generator APIs.
+ * `RandomValues.Default` requires `globalThis.crypto.getRandomValues`; an unavailable implementation or thrown platform error is an Effect defect because the service's typed error channel is `never`.
+ * ## Ownership and lifetime
+ * A Layer owns the entropy source; every call allocates and transfers ownership of a fresh mutable byte array to the caller.
+ * @example
+ * ```ts
+ * import { RandomValues } from "@typed/id/RandomValues"
+ * import { Effect } from "effect"
+ * const bytes = Effect.provide(RandomValues.call(16), RandomValues.Default)
+ * ```
+ * @category Services
+ * @since 1.0.0
+ */
+export class RandomValues extends Context.Service()("@typed/id/RandomValues", {
+    make: Effect.succeed((length) => Effect.sync(() => allocate(length, fillFromWebCrypto))),
 }) {
-    static call = (length) => RandomValues.asEffect().pipe(Effect.flatMap((randomValues) => randomValues(length)));
+    /**
+     * Requests a fresh byte array from the current RandomValues service.
+     * @remarks
+     * ## Why
+     * The static call preserves literal length in the type while keeping the entropy source in Effect's service channel.
+     * ## Ownership and lifetime
+     * Each invocation allocates a new buffer owned by the caller and acquires no persistent resource.
+     * @example
+     * ```ts
+     * import { RandomValues } from "@typed/id/RandomValues"
+     * import { Effect } from "effect"
+     * const bytes = RandomValues.call(32).pipe(Effect.provide(RandomValues.Default))
+     * ```
+     * @category Services
+     * @since 1.0.0
+     */
+    static call = (length) => RandomValues.pipe(Effect.flatMap((randomValues) => randomValues(length)));
+    /**
+     * Provides cryptographic bytes from `globalThis.crypto.getRandomValues`.
+     * @remarks
+     * ## Why
+     * Production IDs need platform entropy. Missing `globalThis.crypto.getRandomValues` and platform exceptions are Effect defects, not typed errors, rather than silently weakening randomness.
+     * ## Ownership and lifetime
+     * The Layer owns no mutable generator state; each request returns a fresh buffer. The runtime must provide Web Crypto or the request defects.
+     * @category Layers
+     * @since 1.0.0
+     */
     static Default = Layer.effect(RandomValues, RandomValues.make);
+    /**
+     * Provides reproducible bytes from Effect Random.
+     * @remarks
+     * ## Why
+     * Deterministic tests and simulations need replaceable entropy; this Layer is not cryptographically secure.
+     * ## Ownership and lifetime
+     * The provided Effect Random service owns sequence state for the Layer lifetime; each request returns a fresh buffer.
+     * @category Layers
+     * @since 1.0.0
+     */
     static Random = Layer.effect(RandomValues, Effect.gen(function* () {
         const random = yield* Random.Random;
-        return RandomValues.of((length) => Effect.sync(() => {
-            const view = new Uint8Array(length);
-            for (let i = 0; i < length; ++i)
-                view[i] = random.nextIntUnsafe();
-            return view;
-        }));
+        return fromRandom(random);
     }));
 }

package/dist/Ulid.d.ts

@@ -1,9 +1,57 @@
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { DateTimes } from "./DateTimes.js";
 import { RandomValues } from "./RandomValues.js";
+/**
+ * Effect Schema and branded string type for canonical ULID values.
+ * @remarks
+ * ## Why
+ * The schema validates values at transport boundaries; encoded time does not imply a total order across independent generators.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { Ulid } from "@typed/id/Ulid"
+ * const id = Ulid.make("01ARZ3NDEKTSV4RRFFQ69G5FAV")
+ * ```
+ * @category Schemas
+ * @since 1.0.0
+ */
 export declare const Ulid: Schema.brand<Schema.String, "@typed/id/ULID">;
 export type Ulid = typeof Ulid.Type;
+/**
+ * Tests whether a string is a canonical ULID.
+ * @remarks
+ * ## Why
+ * Runtime refinement restores trust after serialization has erased the TypeScript brand.
+ * ## Ownership and lifetime
+ * This pure predicate acquires no resources and retains no input.
+ * @example
+ * ```ts
+ * import { isUlid } from "@typed/id/Ulid"
+ * isUlid("01ARZ3NDEKTSV4RRFFQ69G5FAV")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export declare const isUlid: (value: string) => value is Ulid;
-export declare const ulid: Effect.Effect<Ulid, never, RandomValues | DateTimes>;
+/**
+ * Generates a ULID from the current millisecond time and random bytes.
+ * @remarks
+ * ## Why
+ * Time and entropy remain explicit services; unsafe, negative, or out-of-range 48-bit timestamps fail with `IllegalArgumentError`.
+ * ## Ownership and lifetime
+ * The Effect acquires no persistent resources and uses DateTimes and RandomValues only for the invocation.
+ * @example
+ * ```ts
+ * import { ulid } from "@typed/id/Ulid"
+ * import { Ids } from "@typed/id/Ids"
+ * import { Effect } from "effect"
+ * const id = Effect.provide(ulid, Ids.Default)
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
+export declare const ulid: Effect.Effect<Ulid, Cause.IllegalArgumentError, RandomValues | DateTimes>;
 //# sourceMappingURL=Ulid.d.ts.map

package/dist/Ulid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Ulid.d.ts","sourceRoot":"","sources":["../src/Ulid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,eAAO,MAAM,IAAI,+CAGhB,CAAC;AACF,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAC;AAEpC,eAAO,MAAM,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,IAAsB,CAAC;AAWxE,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,YAAY,GAAG,SAAS,CAUrE,CAAC"}
+{"version":3,"file":"Ulid.d.ts","sourceRoot":"","sources":["../src/Ulid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,IAAI,+CAGhB,CAAC;AACF,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAC;AAEpC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,IAAsB,CAAC;AAWxE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,oBAAoB,EAAE,YAAY,GAAG,SAAS,CAWvF,CAAC"}

package/dist/Ulid.js

@@ -1,8 +1,39 @@
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { DateTimes } from "./DateTimes.js";
 import { RandomValues } from "./RandomValues.js";
+/**
+ * Effect Schema and branded string type for canonical ULID values.
+ * @remarks
+ * ## Why
+ * The schema validates values at transport boundaries; encoded time does not imply a total order across independent generators.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { Ulid } from "@typed/id/Ulid"
+ * const id = Ulid.make("01ARZ3NDEKTSV4RRFFQ69G5FAV")
+ * ```
+ * @category Schemas
+ * @since 1.0.0
+ */
 export const Ulid = Schema.String.pipe(Schema.check(Schema.isULID()), Schema.brand("@typed/id/ULID"));
+/**
+ * Tests whether a string is a canonical ULID.
+ * @remarks
+ * ## Why
+ * Runtime refinement restores trust after serialization has erased the TypeScript brand.
+ * ## Ownership and lifetime
+ * This pure predicate acquires no resources and retains no input.
+ * @example
+ * ```ts
+ * import { isUlid } from "@typed/id/Ulid"
+ * isUlid("01ARZ3NDEKTSV4RRFFQ69G5FAV")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export const isUlid = Schema.is(Ulid);
 // Crockford's Base32
 const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
@@ -10,11 +41,30 @@ const ENCODING_LEN = ENCODING.length;
 const TIME_MAX = 2 ** 48 - 1;
 const TIME_LEN = 10;
 const RANDOM_LEN = 16;
-export const ulid = Effect.zipWith(DateTimes.now, RandomValues.call(16), (now, seed) => {
-    if (now > TIME_MAX) {
-        throw new Error("Cannot generate ULID due to timestamp overflow");
+/**
+ * Generates a ULID from the current millisecond time and random bytes.
+ * @remarks
+ * ## Why
+ * Time and entropy remain explicit services; unsafe, negative, or out-of-range 48-bit timestamps fail with `IllegalArgumentError`.
+ * ## Ownership and lifetime
+ * The Effect acquires no persistent resources and uses DateTimes and RandomValues only for the invocation.
+ * @example
+ * ```ts
+ * import { ulid } from "@typed/id/Ulid"
+ * import { Ids } from "@typed/id/Ids"
+ * import { Effect } from "effect"
+ * const id = Effect.provide(ulid, Ids.Default)
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
+export const ulid = Effect.gen(function* () {
+    const now = yield* DateTimes.now;
+    if (!Number.isSafeInteger(now) || now < 0 || now > TIME_MAX) {
+        return yield* new Cause.IllegalArgumentError(`ULID timestamp must be a safe integer between 0 and ${TIME_MAX}, received ${now}`);
     }
-    return Ulid.makeUnsafe(encodeTime(now, TIME_LEN) + encodeRandom(seed));
+    const seed = yield* RandomValues.call(16);
+    return Ulid.make(encodeTime(now, TIME_LEN) + encodeRandom(seed));
 });
 function encodeTime(now, len) {
     let str = "";

package/dist/Uuid4.d.ts

@@ -1,8 +1,55 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { RandomValues } from "./RandomValues.js";
+/**
+ * Effect Schema and branded string type for RFC UUID version 4 values.
+ * @remarks
+ * ## Why
+ * The schema verifies version and variant bits before restoring the compile-time brand after transport.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { Uuid4 } from "@typed/id/Uuid4"
+ * const id = Uuid4.make("550e8400-e29b-41d4-a716-446655440000")
+ * ```
+ * @category Schemas
+ * @since 1.0.0
+ */
 export declare const Uuid4: Schema.brand<Schema.String, "@typed/id/UUID4">;
 export type Uuid4 = typeof Uuid4.Type;
+/**
+ * Tests whether a string is an RFC UUID version 4 value.
+ * @remarks
+ * ## Why
+ * Runtime refinement restores trust after serialization has erased the TypeScript brand.
+ * ## Ownership and lifetime
+ * This pure predicate acquires no resources and retains no input.
+ * @example
+ * ```ts
+ * import { isUuid4 } from "@typed/id/Uuid4"
+ * isUuid4("550e8400-e29b-41d4-a716-446655440000")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export declare const isUuid4: (value: string) => value is Uuid4;
+/**
+ * Generates an RFC UUID version 4 from 16 fresh random bytes.
+ * @remarks
+ * ## Why
+ * Effectful generation exposes entropy as a service and explicitly sets version and variant bits; custom services must return a usable fresh buffer.
+ * ## Ownership and lifetime
+ * The invocation mutates only its fresh byte buffer, acquires no persistent resource, and returns an immutable string.
+ * @example
+ * ```ts
+ * import { uuid4 } from "@typed/id/Uuid4"
+ * import { RandomValues } from "@typed/id/RandomValues"
+ * import { Effect } from "effect"
+ * const id = Effect.provide(uuid4, RandomValues.Default)
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
 export declare const uuid4: Effect.Effect<Uuid4, never, RandomValues>;
 //# sourceMappingURL=Uuid4.d.ts.map

package/dist/Uuid4.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Uuid4.d.ts","sourceRoot":"","sources":["../src/Uuid4.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,eAAO,MAAM,KAAK,gDAGjB,CAAC;AACF,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;AAEtC,eAAO,MAAM,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,KAAwB,CAAC;AAI3E,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,CAQ3D,CAAC"}
+{"version":3,"file":"Uuid4.d.ts","sourceRoot":"","sources":["../src/Uuid4.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK,gDAGjB,CAAC;AACF,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,KAAwB,CAAC;AAI3E;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,CAQ3D,CAAC"}

package/dist/Uuid4.js

@@ -2,11 +2,58 @@ import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { uuidStringify } from "./_uuid-stringify.js";
 import { RandomValues } from "./RandomValues.js";
+/**
+ * Effect Schema and branded string type for RFC UUID version 4 values.
+ * @remarks
+ * ## Why
+ * The schema verifies version and variant bits before restoring the compile-time brand after transport.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { Uuid4 } from "@typed/id/Uuid4"
+ * const id = Uuid4.make("550e8400-e29b-41d4-a716-446655440000")
+ * ```
+ * @category Schemas
+ * @since 1.0.0
+ */
 export const Uuid4 = Schema.String.pipe(Schema.check(Schema.isUUID(4)), Schema.brand("@typed/id/UUID4"));
+/**
+ * Tests whether a string is an RFC UUID version 4 value.
+ * @remarks
+ * ## Why
+ * Runtime refinement restores trust after serialization has erased the TypeScript brand.
+ * ## Ownership and lifetime
+ * This pure predicate acquires no resources and retains no input.
+ * @example
+ * ```ts
+ * import { isUuid4 } from "@typed/id/Uuid4"
+ * isUuid4("550e8400-e29b-41d4-a716-446655440000")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export const isUuid4 = Schema.is(Uuid4);
+/**
+ * Generates an RFC UUID version 4 from 16 fresh random bytes.
+ * @remarks
+ * ## Why
+ * Effectful generation exposes entropy as a service and explicitly sets version and variant bits; custom services must return a usable fresh buffer.
+ * ## Ownership and lifetime
+ * The invocation mutates only its fresh byte buffer, acquires no persistent resource, and returns an immutable string.
+ * @example
+ * ```ts
+ * import { uuid4 } from "@typed/id/Uuid4"
+ * import { RandomValues } from "@typed/id/RandomValues"
+ * import { Effect } from "effect"
+ * const id = Effect.provide(uuid4, RandomValues.Default)
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
 export const uuid4 = Effect.map(RandomValues.call(16), (seed) => {
     // Per 4.4, set bits for version and `clock_seq_hi_and_reserved`
     seed[6] = (seed[6] & 0x0f) | 0x40;
     seed[8] = (seed[8] & 0x3f) | 0x80;
-    return Uuid4.makeUnsafe(uuidStringify(seed));
+    return Uuid4.make(uuidStringify(seed));
 });

package/dist/Uuid5.d.ts

@@ -1,21 +1,193 @@
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
+/**
+ * Effect Schema and branded string type for RFC UUID version 5 values.
+ * @remarks
+ * ## Why
+ * The schema verifies UUID version and variant at transport boundaries before restoring the compile-time brand.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { Uuid5 } from "@typed/id/Uuid5"
+ * import { Schema } from "effect"
+ * const id = Schema.decodeUnknownSync(Uuid5)("21f7f8de-8051-5b89-8680-0195ef798b6a")
+ * ```
+ * @category Schemas
+ * @since 1.0.0
+ */
 export declare const Uuid5: Schema.brand<Schema.String, "@typed/id/UUID5">;
 export type Uuid5 = typeof Uuid5.Type;
+/**
+ * Tests whether a string is an RFC UUID version 5 value.
+ * @remarks
+ * ## Why
+ * Runtime refinement restores trust after serialization has erased the TypeScript brand.
+ * ## Ownership and lifetime
+ * This pure predicate acquires no resources and retains no input.
+ * @example
+ * ```ts
+ * import { isUuid5 } from "@typed/id/Uuid5"
+ * isUuid5("21f7f8de-8051-5b89-8680-0195ef798b6a")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export declare const isUuid5: (value: string) => value is Uuid5;
+/**
+ * The exact 16 namespace bytes used in UUID version 5 hashing.
+ * @remarks
+ * ## Why
+ * Namespace bytes are part of deterministic identity; caller canonicalization of names and namespace selection must remain explicit.
+ * ## Ownership and lifetime
+ * This type acquires no resources. Callers own and may mutate their byte array; generation reads exactly 16 bytes.
+ * @category Models
+ * @since 1.0.0
+ */
 export type Uuid5Namespace = Uint8Array;
+/**
+ * Standard RFC UUID version 5 namespaces, returned as fresh mutable copies.
+ * @remarks
+ * ## Why
+ * Copy-on-access protects canonical constants while allowing callers to own and safely modify their selected namespace bytes.
+ * ## Ownership and lifetime
+ * The module owns canonical bytes for its lifetime; every property access transfers a fresh 16-byte copy to the caller.
+ * @example
+ * ```ts
+ * import { Uuid5Namespace } from "@typed/id/Uuid5"
+ * const namespace = Uuid5Namespace.DNS
+ * ```
+ * @category Namespaces
+ * @since 1.0.0
+ */
 export declare const Uuid5Namespace: {
+    /**
+     * Returns a fresh copy of the RFC DNS namespace bytes.
+     * @remarks
+     * ## Why
+     * DNS names need a stable namespace distinct from URLs, OIDs, and X.500 names.
+     * ## Ownership and lifetime
+     * Each access allocates a mutable byte array owned by the caller.
+     * @category Namespaces
+     * @since 1.0.0
+     */
     readonly DNS: Uint8Array<ArrayBuffer>;
+    /**
+     * Returns a fresh copy of the RFC URL namespace bytes.
+     * @remarks
+     * ## Why
+     * URL names need a stable namespace distinct from DNS, OID, and X.500 names.
+     * ## Ownership and lifetime
+     * Each access allocates a mutable byte array owned by the caller.
+     * @category Namespaces
+     * @since 1.0.0
+     */
     readonly URL: Uint8Array<ArrayBuffer>;
+    /**
+     * Returns a fresh copy of the RFC OID namespace bytes.
+     * @remarks
+     * ## Why
+     * Object identifiers need a stable namespace distinct from DNS, URL, and X.500 names.
+     * ## Ownership and lifetime
+     * Each access allocates a mutable byte array owned by the caller.
+     * @category Namespaces
+     * @since 1.0.0
+     */
     readonly OID: Uint8Array<ArrayBuffer>;
+    /**
+     * Returns a fresh copy of the RFC X.500 namespace bytes.
+     * @remarks
+     * ## Why
+     * X.500 names need a stable namespace distinct from DNS, URL, and OID names.
+     * ## Ownership and lifetime
+     * Each access allocates a mutable byte array owned by the caller.
+     * @category Namespaces
+     * @since 1.0.0
+     */
     readonly X500: Uint8Array<ArrayBuffer>;
 };
+/**
+ * Derives a deterministic UUID version 5 from a UTF-8 name and 16-byte namespace.
+ * @remarks
+ * ## Why
+ * Determinism is exact for the same name bytes and namespace. Invalid namespace length fails in the typed channel with `IllegalArgumentError`; missing Web Crypto or a rejected SHA-1 digest is an Effect defect, not a typed error.
+ * ## Ownership and lifetime
+ * Each Effect acquires no persistent resources, reads but does not retain the namespace, and uses Web Crypto `subtle.digest` for the invocation.
+ * @example
+ * ```ts
+ * import { uuid5, Uuid5Namespace } from "@typed/id/Uuid5"
+ * const id = uuid5("example.com", Uuid5Namespace.DNS)
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
 export declare const uuid5: {
-    (namespace: Uuid5Namespace): (name: string) => Effect.Effect<Uuid5>;
-    (name: string, namespace: Uuid5Namespace): Effect.Effect<Uuid5>;
+    (namespace: Uuid5Namespace): (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+    (name: string, namespace: Uuid5Namespace): Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
 };
-export declare const dnsUuid5: (name: string) => Effect.Effect<Uuid5>;
-export declare const urlUuid5: (name: string) => Effect.Effect<Uuid5>;
-export declare const oidUuid5: (name: string) => Effect.Effect<Uuid5>;
-export declare const x500Uuid5: (name: string) => Effect.Effect<Uuid5>;
+/**
+ * Derives deterministic UUID version 5 values in the standard DNS namespace.
+ * @remarks
+ * ## Why
+ * The pre-bound helper prevents accidental namespace selection drift for DNS identities.
+ * ## Ownership and lifetime
+ * This function acquires no persistent resources and uses a captured namespace copy for module lifetime.
+ * @example
+ * ```ts
+ * import { dnsUuid5 } from "@typed/id/Uuid5"
+ * const id = dnsUuid5("example.com")
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
+export declare const dnsUuid5: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+/**
+ * Derives deterministic UUID version 5 values in the standard URL namespace.
+ * @remarks
+ * ## Why
+ * The pre-bound helper prevents accidental namespace selection drift for URL identities.
+ * ## Ownership and lifetime
+ * This function acquires no persistent resources and uses a captured namespace copy for module lifetime.
+ * @example
+ * ```ts
+ * import { urlUuid5 } from "@typed/id/Uuid5"
+ * const id = urlUuid5("https://example.com")
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
+export declare const urlUuid5: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+/**
+ * Derives deterministic UUID version 5 values in the standard OID namespace.
+ * @remarks
+ * ## Why
+ * The pre-bound helper prevents accidental namespace selection drift for object identifiers.
+ * ## Ownership and lifetime
+ * This function acquires no persistent resources and uses a captured namespace copy for module lifetime.
+ * @example
+ * ```ts
+ * import { oidUuid5 } from "@typed/id/Uuid5"
+ * const id = oidUuid5("1.3.6.1.4.1")
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
+export declare const oidUuid5: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+/**
+ * Derives deterministic UUID version 5 values in the standard X.500 namespace.
+ * @remarks
+ * ## Why
+ * The pre-bound helper prevents accidental namespace selection drift for X.500 identities.
+ * ## Ownership and lifetime
+ * This function acquires no persistent resources and uses a captured namespace copy for module lifetime.
+ * @example
+ * ```ts
+ * import { x500Uuid5 } from "@typed/id/Uuid5"
+ * const id = x500Uuid5("CN=example")
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
+export declare const x500Uuid5: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
 //# sourceMappingURL=Uuid5.d.ts.map

package/dist/Uuid5.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Uuid5.d.ts","sourceRoot":"","sources":["../src/Uuid5.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC,eAAO,MAAM,KAAK,gDAGjB,CAAC;AACF,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;AAEtC,eAAO,MAAM,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,KAAwB,CAAC;AAE3E,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC;AAKxC,eAAO,MAAM,cAAc;;;;;CAgBjB,CAAC;AAEX,eAAO,MAAM,KAAK,EAAE;IAClB,CAAC,SAAS,EAAE,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;CA0BhE,CAAC;AAEH,eAAO,MAAM,QAAQ,SA7BiB,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,CA6BnB,CAAC;AAClD,eAAO,MAAM,QAAQ,SA9BiB,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,CA8BnB,CAAC;AAClD,eAAO,MAAM,QAAQ,SA/BiB,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,CA+BnB,CAAC;AAClD,eAAO,MAAM,SAAS,SAhCgB,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,CAgCjB,CAAC"}
+{"version":3,"file":"Uuid5.d.ts","sourceRoot":"","sources":["../src/Uuid5.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,KAAK,gDAGjB,CAAC;AACF,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,KAAwB,CAAC;AAE3E;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC;AAkBxC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE;IAC3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IACtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IACtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IACtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;CAcvC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK,EAAE;IAClB,CAAC,SAAS,EAAE,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAChG,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;CAmC5F,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,SArDiB,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,oBAAoB,CAqD/C,CAAC;AAClD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,SArEiB,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,oBAAoB,CAqE/C,CAAC;AAClD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,SArFiB,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,oBAAoB,CAqF/C,CAAC;AAClD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS,SArGgB,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,oBAAoB,CAqG7C,CAAC"}