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

package/dist/Ids.js

@@ -1,6 +1,7 @@
 import * as Effect from "effect/Effect";
 import { dual } from "effect/Function";
 import * as Layer from "effect/Layer";
+import * as Random from "effect/Random";
 import * as Context from "effect/Context";
 import { cuid, CuidState } from "./Cuid.js";
 import { DateTimes } from "./DateTimes.js";
@@ -12,6 +13,24 @@ import { uuid4 } from "./Uuid4.js";
 import { uuid5, Uuid5Namespace } from "./Uuid5.js";
 import { uuid7, Uuid7State } from "./Uuid7.js";
 import { TestClock } from "effect/testing";
+const testRandomValues = () => Layer.effect(RandomValues, RandomValues.pipe(Effect.provide(RandomValues.Random), Random.withSeed("@typed/id/Ids.Test")));
+/**
+ * Unified Effect service for every Typed ID generator.
+ * @remarks
+ * ## Why
+ * One facade captures time, entropy, and state services once, so application code composes generators through a single explicit dependency without hiding their behavior.
+ * ## Ownership and lifetime
+ * Each Ids Layer owns its captured services plus lazy CUID and UUIDv7 state. Recreating the Layer resets process-local sequences; serialize server IDs when identity must survive hydration.
+ * @example
+ * ```ts
+ * import { Ids } from "@typed/id/Ids"
+ * import { Effect } from "effect"
+ * const program = Effect.gen(function* () { return yield* Ids.uuid7 }).pipe(Effect.provide(Ids.Default))
+ * ```
+ * See [Effect services](https://effect.website/docs/requirements-management/services/) and [Layers](https://effect.website/docs/requirements-management/layers/).
+ * @category Services
+ * @since 1.0.0
+ */
 export class Ids extends Context.Service()("@typed/id/Ids", {
     make: Effect.gen(function* () {
         const services = yield* Effect.context();
@@ -32,21 +51,145 @@ export class Ids extends Context.Service()("@typed/id/Ids", {
         };
     }),
 }) {
-    static cuid = Effect.flatMap(Ids.asEffect(), ({ cuid }) => cuid);
-    static ksuid = Effect.flatMap(Ids.asEffect(), ({ ksuid }) => ksuid);
-    static nanoId = Effect.flatMap(Ids.asEffect(), ({ nanoId }) => nanoId);
-    static ulid = Effect.flatMap(Ids.asEffect(), ({ ulid }) => ulid);
-    static uuid4 = Effect.flatMap(Ids.asEffect(), ({ uuid4 }) => uuid4);
-    static uuid5 = Object.assign(dual(2, (name, namespace) => Effect.flatMap(Ids.asEffect(), ({ uuid5 }) => uuid5(name, namespace))), {
-        dns: (name) => Effect.flatMap(Ids.asEffect(), ({ uuid5 }) => uuid5.dns(name)),
-        url: (name) => Effect.flatMap(Ids.asEffect(), ({ uuid5 }) => uuid5.url(name)),
-        oid: (name) => Effect.flatMap(Ids.asEffect(), ({ uuid5 }) => uuid5.oid(name)),
-        x500: (name) => Effect.flatMap(Ids.asEffect(), ({ uuid5 }) => uuid5.x500(name)),
+    /**
+     * Generates a CUID using the current Ids service.
+     * @remarks
+     * ## Why
+     * The facade shares the Ids-owned CuidState instead of allocating a new sequence for every call.
+     * ## Ownership and lifetime
+     * This Effect acquires no resources and uses state owned by the provided Ids Layer.
+     * @category Generators
+     * @since 1.0.0
+     */
+    static cuid = Effect.flatMap(Ids, ({ cuid }) => cuid);
+    /**
+     * Generates a KSUID using the current Ids service.
+     * @remarks
+     * ## Why
+     * The facade reuses captured time and entropy while retaining `IllegalArgumentError` for invalid KSUID timestamps.
+     * ## Ownership and lifetime
+     * This Effect acquires no persistent resource and uses services owned by the provided Ids Layer.
+     * @category Generators
+     * @since 1.0.0
+     */
+    static ksuid = Effect.flatMap(Ids, ({ ksuid }) => ksuid);
+    /**
+     * Generates a NanoId using the current Ids service.
+     * @remarks
+     * ## Why
+     * The facade makes the selected entropy implementation available through one application dependency.
+     * ## Ownership and lifetime
+     * This Effect acquires no persistent resource and uses entropy owned by the provided Ids Layer.
+     * @category Generators
+     * @since 1.0.0
+     */
+    static nanoId = Effect.flatMap(Ids, ({ nanoId }) => nanoId);
+    /**
+     * Generates a ULID using the current Ids service.
+     * @remarks
+     * ## Why
+     * The facade reuses captured time and entropy while retaining `IllegalArgumentError` for invalid 48-bit timestamps.
+     * ## Ownership and lifetime
+     * This Effect acquires no persistent resource and uses services owned by the provided Ids Layer.
+     * @category Generators
+     * @since 1.0.0
+     */
+    static ulid = Effect.flatMap(Ids, ({ ulid }) => ulid);
+    /**
+     * Generates a random UUID version 4 using the current Ids service.
+     * @remarks
+     * ## Why
+     * The facade keeps entropy selection replaceable while preserving UUID version and variant semantics.
+     * ## Ownership and lifetime
+     * This Effect acquires no persistent resource and uses entropy owned by the provided Ids Layer.
+     * @category Generators
+     * @since 1.0.0
+     */
+    static uuid4 = Effect.flatMap(Ids, ({ uuid4 }) => uuid4);
+    /**
+     * Derives deterministic UUID version 5 values through the current Ids service, with DNS, URL, OID, and X.500 helpers.
+     * @remarks
+     * ## Why
+     * The facade supports data-first and namespace-first calls while keeping namespace choice and `IllegalArgumentError` explicit.
+     * ## Ownership and lifetime
+     * Each Effect acquires no persistent resources and reads the Ids service for one invocation; helper namespaces are stable captured copies.
+     * @example
+     * ```ts
+     * import { Ids } from "@typed/id/Ids"
+     * import { Effect } from "effect"
+     * const program = Ids.uuid5.dns("example.com").pipe(Effect.provide(Ids.Default))
+     * ```
+     * @category Generators
+     * @since 1.0.0
+     */
+    static uuid5 = Object.assign(dual(2, (name, namespace) => Effect.flatMap(Ids, ({ uuid5 }) => uuid5(name, namespace))), {
+        dns: (name) => Effect.flatMap(Ids, ({ uuid5 }) => uuid5.dns(name)),
+        url: (name) => Effect.flatMap(Ids, ({ uuid5 }) => uuid5.url(name)),
+        oid: (name) => Effect.flatMap(Ids, ({ uuid5 }) => uuid5.oid(name)),
+        x500: (name) => Effect.flatMap(Ids, ({ uuid5 }) => uuid5.x500(name)),
+    });
+    /**
+     * Generates a UUID version 7 using the current Ids service.
+     * @remarks
+     * ## Why
+     * The facade shares one lazy Uuid7State per Ids Layer, preserving local monotonicity and typed timestamp errors.
+     * ## Ownership and lifetime
+     * This Effect acquires no resources and uses sequence state owned by the provided Ids Layer.
+     * @category Generators
+     * @since 1.0.0
+     */
+    static uuid7 = Effect.flatMap(Ids, ({ uuid7 }) => uuid7);
+    /**
+     * Provides production Ids, DateTimes, and RandomValues services.
+     * @remarks
+     * ## Why
+     * The standard Layer uses system time and Web Crypto while lazily creating sequence state only when CUID or UUIDv7 is first requested.
+     * ## Ownership and lifetime
+     * The surrounding Layer Scope owns captured services and lazy sequence state; Web Crypto must exist in the runtime.
+     * @category Layers
+     * @since 1.0.0
+     */
+    static Default = Layer.effect(Ids, makeLazyIds("node")).pipe(Layer.provideMerge([DateTimes.Default, RandomValues.Default]));
+    /**
+     * Provides deterministic Ids, time, entropy, and TestClock services.
+     * @remarks
+     * ## Why
+     * Reproducible generators make exact sequences testable; the deterministic entropy is for tests and simulations, not security.
+     * ## Ownership and lifetime
+     * Each Layer construction owns an independent clock, random sequence, and lazy CUID/UUIDv7 state for its Scope.
+     * @example
+     * ```ts
+     * import { Ids } from "@typed/id/Ids"
+     * import { Effect } from "effect"
+     * const deterministic = Ids.uuid7.pipe(Effect.provide(Ids.Test({ currentTime: 0 })))
+     * ```
+     * @category Testing
+     * @since 1.0.0
+     */
+    static Test = (options = {}) => {
+        const services = Layer.mergeAll(DateTimes.Fixed(options.currentTime ?? 1400000000000), testRandomValues());
+        return Layer.effect(Ids, makeLazyIds(options.envData ?? "node")).pipe(Layer.provide(services), Layer.provideMerge(services), Layer.provideMerge(TestClock.layer({})));
+    };
+}
+function makeLazyIds(envData) {
+    return Effect.gen(function* () {
+        const services = yield* Effect.context();
+        const getCuidState = yield* Effect.cached(Effect.provide(CuidState.make(envData), services));
+        const getUuid7State = yield* Effect.cached(Effect.provide(Uuid7State.make, services));
+        const uuid5_ = Object.assign(dual(2, (name, namespace) => Effect.provide(uuid5(name, namespace), services)), {
+            dns: uuid5(Uuid5Namespace.DNS),
+            url: uuid5(Uuid5Namespace.URL),
+            oid: uuid5(Uuid5Namespace.OID),
+            x500: uuid5(Uuid5Namespace.X500),
+        });
+        return {
+            cuid: Effect.flatMap(getCuidState, (state) => Effect.provideService(cuid, CuidState, state)),
+            ksuid: Effect.provide(ksuid, services),
+            nanoId: Effect.provide(nanoId, services),
+            ulid: Effect.provide(ulid, services),
+            uuid4: Effect.provide(uuid4, services),
+            uuid5: uuid5_,
+            uuid7: Effect.flatMap(getUuid7State, (state) => Effect.provideService(uuid7, Uuid7State, state)),
+        };
     });
-    static uuid7 = Effect.flatMap(Ids.asEffect(), ({ uuid7 }) => uuid7);
-    static Default = Layer.effect(Ids, Ids.make).pipe(Layer.provide([CuidState.Default, Uuid7State.Default]), Layer.provideMerge([DateTimes.Default, RandomValues.Default]));
-    static Test = (options) => Layer.effect(Ids, Ids.make).pipe(Layer.provide([
-        Layer.effect(CuidState, CuidState.make(options?.envData ?? "node")),
-        Uuid7State.Default,
-    ]), Layer.provideMerge([DateTimes.Fixed(options?.currentTime ?? 0), RandomValues.Random]), Layer.provideMerge(TestClock.layer({})));
 }

package/dist/Ksuid.d.ts

@@ -1,9 +1,59 @@
+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 27-character KSUID values.
+ * @remarks
+ * ## Why
+ * The schema validates transported values before restoring the compile-time brand; lexical time ordering is not a global generation-order guarantee.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { Ksuid } from "@typed/id/Ksuid"
+ * import { Schema } from "effect"
+ * const id = Schema.decodeUnknownSync(Ksuid)("0ujtsYcgvSTl8PAuAdqWYSMnLOv")
+ * ```
+ * @category Schemas
+ * @since 1.0.0
+ */
 export declare const Ksuid: Schema.brand<Schema.String, "@typed/id/KSUID">;
 export type Ksuid = typeof Ksuid.Type;
+/**
+ * Tests whether a string has the KSUID encoding shape.
+ * @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 { isKsuid } from "@typed/id/Ksuid"
+ * isKsuid("0ujtsYcgvSTl8PAuAdqWYSMnLOv")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export declare const isKsuid: (value: string) => value is Ksuid;
-export declare const ksuid: Effect.Effect<Ksuid, never, DateTimes | RandomValues>;
+/**
+ * Generates a KSUID from the current time and 16 random bytes.
+ * @remarks
+ * ## Why
+ * Time and entropy remain explicit Effect services; timestamps outside KSUID's 32-bit seconds field fail with `IllegalArgumentError`.
+ * ## Ownership and lifetime
+ * The Effect acquires no persistent resources and uses DateTimes and RandomValues only for the invocation.
+ * @example
+ * ```ts
+ * import { ksuid } from "@typed/id/Ksuid"
+ * import { DateTimes } from "@typed/id/DateTimes"
+ * import { RandomValues } from "@typed/id/RandomValues"
+ * import { Effect, Layer } from "effect"
+ * const id = Effect.provide(ksuid, Layer.merge(DateTimes.Default, RandomValues.Default))
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
+export declare const ksuid: Effect.Effect<Ksuid, Cause.IllegalArgumentError, DateTimes | RandomValues>;
 //# sourceMappingURL=Ksuid.d.ts.map

package/dist/Ksuid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Ksuid.d.ts","sourceRoot":"","sources":["../src/Ksuid.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;AAUjD,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;AAM3E,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,GAAG,YAAY,CAyBvE,CAAC"}
+{"version":3,"file":"Ksuid.d.ts","sourceRoot":"","sources":["../src/Ksuid.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;AAWjD;;;;;;;;;;;;;;;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;AAM3E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,oBAAoB,EAAE,SAAS,GAAG,YAAY,CAyBzF,CAAC"}

package/dist/Ksuid.js

@@ -1,24 +1,76 @@
+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";
 // Constants
-const EPOCH = 14e11; // 2014-03-01T00:00:00Z
+const EPOCH = 14e11; // 2014-05-13T16:53:20Z
+const TIMESTAMP_MAX = EPOCH + 2 ** 32 * 1000 - 1;
 const TIMESTAMP_BYTES = 4;
 const PAYLOAD_BYTES = 16;
 const TOTAL_BYTES = TIMESTAMP_BYTES + PAYLOAD_BYTES;
 const STRING_LENGTH = 27;
 // Schema
+/**
+ * Effect Schema and branded string type for 27-character KSUID values.
+ * @remarks
+ * ## Why
+ * The schema validates transported values before restoring the compile-time brand; lexical time ordering is not a global generation-order guarantee.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { Ksuid } from "@typed/id/Ksuid"
+ * import { Schema } from "effect"
+ * const id = Schema.decodeUnknownSync(Ksuid)("0ujtsYcgvSTl8PAuAdqWYSMnLOv")
+ * ```
+ * @category Schemas
+ * @since 1.0.0
+ */
 export const Ksuid = Schema.String.pipe(Schema.check(Schema.isPattern(/^[0-9A-Za-z]{27}$/)), Schema.brand("@typed/id/KSUID"));
+/**
+ * Tests whether a string has the KSUID encoding shape.
+ * @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 { isKsuid } from "@typed/id/Ksuid"
+ * isKsuid("0ujtsYcgvSTl8PAuAdqWYSMnLOv")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export const isKsuid = Schema.is(Ksuid);
 // Public API
-export const ksuid = Effect.zipWith(DateTimes.now, RandomValues.call(PAYLOAD_BYTES), (timestamp, payload) => {
+/**
+ * Generates a KSUID from the current time and 16 random bytes.
+ * @remarks
+ * ## Why
+ * Time and entropy remain explicit Effect services; timestamps outside KSUID's 32-bit seconds field fail with `IllegalArgumentError`.
+ * ## Ownership and lifetime
+ * The Effect acquires no persistent resources and uses DateTimes and RandomValues only for the invocation.
+ * @example
+ * ```ts
+ * import { ksuid } from "@typed/id/Ksuid"
+ * import { DateTimes } from "@typed/id/DateTimes"
+ * import { RandomValues } from "@typed/id/RandomValues"
+ * import { Effect, Layer } from "effect"
+ * const id = Effect.provide(ksuid, Layer.merge(DateTimes.Default, RandomValues.Default))
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
+export const ksuid = Effect.gen(function* () {
+    const timestamp = yield* DateTimes.now;
+    if (!Number.isSafeInteger(timestamp) || timestamp < EPOCH || timestamp > TIMESTAMP_MAX) {
+        return yield* new Cause.IllegalArgumentError(`KSUID timestamp must be a safe integer between ${EPOCH} and ${TIMESTAMP_MAX}, received ${timestamp}`);
+    }
+    const payload = yield* RandomValues.call(PAYLOAD_BYTES);
     // Create the combined bytes
     const bytes = new Uint8Array(TOTAL_BYTES);
-    // Support for timestamps before the epoch, usually for testing
-    if (timestamp < EPOCH) {
-        timestamp += EPOCH;
-    }
     // Write timestamp (4 bytes, big-endian)
     const seconds = Math.floor((timestamp - EPOCH) / 1000);
     bytes[0] = (seconds >>> 24) & 0xff;

package/dist/NanoId.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 URL-safe Nano IDs.
+ * @remarks
+ * ## Why
+ * Runtime validation restores the brand after transport and prevents arbitrary strings from entering NanoId-specific APIs.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { NanoId } from "@typed/id/NanoId"
+ * const id = NanoId.make("V1StGXR8_Z5jdHi6B-myT")
+ * ```
+ * @category Schemas
+ * @since 1.0.0
+ */
 export declare const NanoId: Schema.brand<Schema.String, "@typed/id/NanoId">;
 export type NanoId = typeof NanoId.Type;
+/**
+ * Tests whether a string has the NanoId alphabet and brandable shape.
+ * @remarks
+ * ## Why
+ * Refinement is the lightweight boundary check when full schema decoding is unnecessary.
+ * ## Ownership and lifetime
+ * This pure predicate acquires no resources and retains no input.
+ * @example
+ * ```ts
+ * import { isNanoId } from "@typed/id/NanoId"
+ * isNanoId("V1StGXR8_Z5jdHi6B-myT")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export declare const isNanoId: (value: string) => value is NanoId;
+/**
+ * Generates a 21-character NanoId from the current RandomValues service.
+ * @remarks
+ * ## Why
+ * Effectful generation exposes entropy as a service so production and deterministic test sources are interchangeable.
+ * ## Ownership and lifetime
+ * The Effect acquires no persistent resource and consumes one fresh 21-byte buffer owned by the invocation.
+ * @example
+ * ```ts
+ * import { nanoId } from "@typed/id/NanoId"
+ * import { RandomValues } from "@typed/id/RandomValues"
+ * import { Effect } from "effect"
+ * const id = Effect.provide(nanoId, RandomValues.Default)
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
 export declare const nanoId: Effect.Effect<NanoId, never, RandomValues>;
 //# sourceMappingURL=NanoId.d.ts.map

package/dist/NanoId.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NanoId.d.ts","sourceRoot":"","sources":["../src/NanoId.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,eAAO,MAAM,MAAM,iDAGlB,CAAC;AACF,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAC;AAExC,eAAO,MAAM,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,MAA0B,CAAC;AAI9E,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,YAAY,CAG7D,CAAC"}
+{"version":3,"file":"NanoId.d.ts","sourceRoot":"","sources":["../src/NanoId.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,iDAGlB,CAAC;AACF,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAC;AAExC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,MAA0B,CAAC;AAI9E;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,YAAY,CAG7D,CAAC"}

package/dist/NanoId.js

@@ -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 URL-safe Nano IDs.
+ * @remarks
+ * ## Why
+ * Runtime validation restores the brand after transport and prevents arbitrary strings from entering NanoId-specific APIs.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { NanoId } from "@typed/id/NanoId"
+ * const id = NanoId.make("V1StGXR8_Z5jdHi6B-myT")
+ * ```
+ * @category Schemas
+ * @since 1.0.0
+ */
 export const NanoId = Schema.String.pipe(Schema.check(Schema.isPattern(/^[0-9a-zA-Z_-]+$/)), Schema.brand("@typed/id/NanoId"));
+/**
+ * Tests whether a string has the NanoId alphabet and brandable shape.
+ * @remarks
+ * ## Why
+ * Refinement is the lightweight boundary check when full schema decoding is unnecessary.
+ * ## Ownership and lifetime
+ * This pure predicate acquires no resources and retains no input.
+ * @example
+ * ```ts
+ * import { isNanoId } from "@typed/id/NanoId"
+ * isNanoId("V1StGXR8_Z5jdHi6B-myT")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export const isNanoId = Schema.is(NanoId);
+/**
+ * Generates a 21-character NanoId from the current RandomValues service.
+ * @remarks
+ * ## Why
+ * Effectful generation exposes entropy as a service so production and deterministic test sources are interchangeable.
+ * ## Ownership and lifetime
+ * The Effect acquires no persistent resource and consumes one fresh 21-byte buffer owned by the invocation.
+ * @example
+ * ```ts
+ * import { nanoId } from "@typed/id/NanoId"
+ * import { RandomValues } from "@typed/id/RandomValues"
+ * import { Effect } from "effect"
+ * const id = Effect.provide(nanoId, RandomValues.Default)
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
 export const nanoId = Effect.map(RandomValues.call(21), (seed) => NanoId.make(Array.from(seed, numToCharacter).join("")));
 function numToCharacter(byte) {
     byte &= 63;

package/dist/RandomValues.d.ts

@@ -1,12 +1,71 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Context from "effect/Context";
-declare const RandomValues_base: Context.ServiceClass<RandomValues, "@typed/id/RandomValues", <A extends Uint8Array>(length: A["length"]) => Effect.Effect<A>> & {
-    readonly make: Effect.Effect<(<A extends Uint8Array>(length: A["length"]) => Effect.Effect<A>), never, never>;
+declare const RandomValues_base: Context.ServiceClass<RandomValues, "@typed/id/RandomValues", <const N extends number>(length: N) => Effect.Effect<Uint8Array & {
+    readonly length: N;
+}>> & {
+    readonly make: Effect.Effect<<const N extends number>(length: N) => Effect.Effect<Uint8Array & {
+        readonly length: N;
+    }>, never, never>;
 };
+/**
+ * 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 declare class RandomValues extends RandomValues_base {
-    static readonly call: <A extends Uint8Array>(length: A["length"]) => Effect.Effect<A, never, RandomValues>;
+    /**
+     * 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 readonly call: <const N extends number>(length: N) => Effect.Effect<Uint8Array & {
+        readonly length: N;
+    }, never, RandomValues>;
+    /**
+     * 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 readonly Default: Layer.Layer<RandomValues, never, never>;
+    /**
+     * 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 readonly Random: Layer.Layer<RandomValues, never, never>;
 }
 export {};

package/dist/RandomValues.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RandomValues.d.ts","sourceRoot":"","sources":["../src/RandomValues.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;+FAIrC,CAAC,SAAS,UAAU,UAAU,CAAC,CAAC,QAAQ,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;mCAA5D,CAAC,SAAS,UAAU,UAAU,CAAC,CAAC,QAAQ,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;;AAFjE,qBAAa,YAAa,SAAQ,iBAKhC;IACA,gBAAyB,IAAI,GAAI,CAAC,SAAS,UAAU,EACnD,QAAQ,CAAC,CAAC,QAAQ,CAAC,KAClB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAC+C;IAEvF,MAAM,CAAC,QAAQ,CAAC,OAAO,0CAAiD;IAExE,MAAM,CAAC,QAAQ,CAAC,MAAM,0CAapB;CACH"}
+{"version":3,"file":"RandomValues.d.ts","sourceRoot":"","sources":["../src/RandomValues.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;qGAkD/B,CAAC,SAAS,MAAM,UAAU,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,UAAU,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC;wCAAhF,CAAC,SAAS,MAAM,UAAU,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,UAAU,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC;;AAnB3F;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,YAAa,SAAQ,iBAKhC;IACA;;;;;;;;;;;;;;;OAeG;IACH,gBAAyB,IAAI,GAAI,KAAK,CAAC,CAAC,SAAS,MAAM,UAC7C,CAAC,KACR,MAAM,CAAC,MAAM,CAAC,UAAU,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;KAAE,EAAE,KAAK,EAAE,YAAY,CAAC,CACE;IAE5E;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,0CAAiD;IAExE;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,MAAM,0CAMpB;CACH"}

package/dist/RandomValues.js

@@ -2,18 +2,82 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Random from "effect/Random";
 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(() => crypto.getRandomValues(new Uint8Array(length)))),
+    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);
     }));
 }