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

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,10 +41,29 @@ 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}`);
     }
+    const seed = yield* RandomValues.call(16);
     return Ulid.make(encodeTime(now, TIME_LEN) + encodeRandom(seed));
 });
 function encodeTime(now, len) {

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,8 +2,55 @@ 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;

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"}

package/dist/Uuid5.js

@@ -1,28 +1,105 @@
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import { dual } from "effect/Function";
 import * as Schema from "effect/Schema";
 import { sha1 } from "./_sha.js";
 import { uuidStringify } from "./_uuid-stringify.js";
+/**
+ * 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 const Uuid5 = Schema.String.pipe(Schema.check(Schema.isUUID(5)), Schema.brand("@typed/id/UUID5"));
+/**
+ * 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 const isUuid5 = Schema.is(Uuid5);
 const textEncoder = new TextEncoder();
 // Pre-defined namespaces from RFC 4122
-export const Uuid5Namespace = {
-    DNS: new Uint8Array([
-        0x6b, 0xa7, 0xb8, 0x10, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
-    ]),
-    URL: new Uint8Array([
-        0x6b, 0xa7, 0xb8, 0x11, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
-    ]),
-    OID: new Uint8Array([
-        0x6b, 0xa7, 0xb8, 0x12, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
-    ]),
-    X500: new Uint8Array([
-        0x6b, 0xa7, 0xb8, 0x14, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
-    ]),
-};
+const DNS = new Uint8Array([
+    0x6b, 0xa7, 0xb8, 0x10, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
+]);
+const URL = new Uint8Array([
+    0x6b, 0xa7, 0xb8, 0x11, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
+]);
+const OID = new Uint8Array([
+    0x6b, 0xa7, 0xb8, 0x12, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
+]);
+const X500 = new Uint8Array([
+    0x6b, 0xa7, 0xb8, 0x14, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
+]);
+/**
+ * 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 const Uuid5Namespace = Object.freeze({
+    get DNS() {
+        return DNS.slice(0);
+    },
+    get URL() {
+        return URL.slice(0);
+    },
+    get OID() {
+        return OID.slice(0);
+    },
+    get X500() {
+        return X500.slice(0);
+    },
+});
+/**
+ * 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 const uuid5 = dual(2, function uuid5(name, namespace) {
     return Effect.gen(function* () {
+        if (namespace.length !== 16) {
+            return yield* new Cause.IllegalArgumentError(`UUIDv5 namespace must contain exactly 16 bytes, received ${namespace.length}`);
+        }
         // Convert name to UTF-8 bytes
         const nameBytes = textEncoder.encode(name);
         // Concatenate namespace and name
@@ -41,7 +118,67 @@ export const uuid5 = dual(2, function uuid5(name, namespace) {
         return Uuid5.make(uuidStringify(result));
     });
 });
+/**
+ * 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 const dnsUuid5 = uuid5(Uuid5Namespace.DNS);
+/**
+ * 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 const urlUuid5 = uuid5(Uuid5Namespace.URL);
+/**
+ * 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 const oidUuid5 = uuid5(Uuid5Namespace.OID);
+/**
+ * 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 const x500Uuid5 = uuid5(Uuid5Namespace.X500);