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

package/dist/Ids.js

@@ -1,8 +1,8 @@
 import * as Effect from "effect/Effect";
 import { dual } from "effect/Function";
 import * as Layer from "effect/Layer";
-import * as ServiceMap from "effect/ServiceMap";
-import { cuid, CuidState } from "./Cuid.js";
+import * as Context from "effect/Context";
+import { cuid } from "./Cuid.js";
 import { DateTimes } from "./DateTimes.js";
 import { ksuid } from "./Ksuid.js";
 import { nanoId } from "./NanoId.js";
@@ -10,11 +10,28 @@ import { RandomValues } from "./RandomValues.js";
 import { ulid } from "./Ulid.js";
 import { uuid4 } from "./Uuid4.js";
 import { uuid5, Uuid5Namespace } from "./Uuid5.js";
-import { uuid7, Uuid7State } from "./Uuid7.js";
-import { TestClock } from "effect/testing";
-export class Ids extends ServiceMap.Service()("@typed/id/Ids", {
+import { uuid7 } from "./Uuid7.js";
+import { makeLazyIds } from "./internal/Ids.js";
+/**
+ * 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.services();
+        const services = yield* Effect.context();
         const uuid5_ = Object.assign(dual(2, (name, namespace) => Effect.provide(uuid5(name, namespace), services)), {
             dns: uuid5(Uuid5Namespace.DNS),
             url: uuid5(Uuid5Namespace.URL),
@@ -32,21 +49,103 @@ export class Ids extends ServiceMap.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 ID generation
+     * @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 ID generation
+     * @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 ID generation
+     * @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 ID generation
+     * @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 ID generation
+     * @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 ID generation
+     * @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)),
     });
-    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({})));
+    /**
+     * 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 ID generation
+     * @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 Production layers
+     * @since 1.0.0
+     */
+    static Default = Layer.effect(Ids, makeLazyIds("node")).pipe(Layer.provideMerge([DateTimes.Default, RandomValues.Default]));
 }

package/dist/IdsTest.d.ts

@@ -0,0 +1,34 @@
+import * as Cause from "effect/Cause";
+import * as Layer from "effect/Layer";
+import * as TestClock from "effect/testing/TestClock";
+import { DateTimes } from "./DateTimes.js";
+import { Ids } from "./Ids.js";
+import { RandomValues } from "./RandomValues.js";
+import { Uuid7State } from "./Uuid7.js";
+/**
+ * Provides deterministic IDs, time, entropy, and TestClock services.
+ *
+ * @remarks
+ * This test-only entry point keeps Effect's testing runtime out of production imports of `Ids`.
+ * Each invocation owns an independent clock, random sequence, and lazy CUID/UUIDv7 state.
+ *
+ * @example
+ * ```ts
+ * import { Ids } from "@typed/id/Ids"
+ * import { IdsTest } from "@typed/id/IdsTest"
+ * import { Effect } from "effect"
+ * const deterministic = Ids.uuid7.pipe(Effect.provide(IdsTest({ currentTime: 0 })))
+ * ```
+ *
+ * @category Deterministic testing
+ * @since 1.0.0
+ */
+export declare const IdsTest: (options?: IdsTestOptions) => Layer.Layer<Ids | DateTimes | RandomValues | Uuid7State | TestClock.TestClock, Cause.IllegalArgumentError>;
+/** Configuration for the deterministic ID test layer. @since 1.0.0 */
+export type IdsTestOptions = {
+    /** Fixed generator time; invalid dates fail Layer acquisition. @since 1.0.0 */
+    readonly currentTime?: number | string | Date;
+    /** CUID caller discriminator used when the test CuidState is created. @since 1.0.0 */
+    readonly envData?: string;
+};
+//# sourceMappingURL=IdsTest.d.ts.map

package/dist/IdsTest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IdsTest.d.ts","sourceRoot":"","sources":["../src/IdsTest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,KAAK,SAAS,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAyBxC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,OAAO,aACT,cAAc,KACtB,KAAK,CAAC,KAAK,CACZ,GAAG,GAAG,SAAS,GAAG,YAAY,GAAG,UAAU,GAAG,SAAS,CAAC,SAAS,EACjE,KAAK,CAAC,oBAAoB,CAe3B,CAAC;AAEF,sEAAsE;AACtE,MAAM,MAAM,cAAc,GAAG;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC9C,sFAAsF;IACtF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC"}

package/dist/IdsTest.js

@@ -0,0 +1,44 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Random from "effect/Random";
+import * as TestClock from "effect/testing/TestClock";
+import { DateTimes } from "./DateTimes.js";
+import { Ids } from "./Ids.js";
+import { makeLazyIds } from "./internal/Ids.js";
+import { RandomValues } from "./RandomValues.js";
+import { Uuid7State } from "./Uuid7.js";
+const testRandomValues = () => Layer.effect(RandomValues, RandomValues.pipe(Effect.provide(RandomValues.Random), Random.withSeed("@typed/id/IdsTest")));
+const fixedDateTimes = (baseDate) => Layer.effect(DateTimes, Effect.gen(function* () {
+    const millis = new Date(baseDate).getTime();
+    if (!Number.isFinite(millis)) {
+        return yield* new Cause.IllegalArgumentError(`Invalid base date: ${String(baseDate)}`);
+    }
+    return DateTimes.of({
+        now: Effect.succeed(millis),
+        date: Effect.sync(() => new Date(millis)),
+    });
+}));
+/**
+ * Provides deterministic IDs, time, entropy, and TestClock services.
+ *
+ * @remarks
+ * This test-only entry point keeps Effect's testing runtime out of production imports of `Ids`.
+ * Each invocation owns an independent clock, random sequence, and lazy CUID/UUIDv7 state.
+ *
+ * @example
+ * ```ts
+ * import { Ids } from "@typed/id/Ids"
+ * import { IdsTest } from "@typed/id/IdsTest"
+ * import { Effect } from "effect"
+ * const deterministic = Ids.uuid7.pipe(Effect.provide(IdsTest({ currentTime: 0 })))
+ * ```
+ *
+ * @category Deterministic testing
+ * @since 1.0.0
+ */
+export const IdsTest = (options = {}) => {
+    const services = Layer.mergeAll(fixedDateTimes(options.currentTime ?? 1400000000000), testRandomValues());
+    const uuid7State = Layer.effect(Uuid7State, Uuid7State.make).pipe(Layer.provide(services));
+    return Layer.effect(Ids, makeLazyIds(options.envData ?? "node")).pipe(Layer.provide(services), Layer.provideMerge(services), Layer.provideMerge(TestClock.layer({})), Layer.provideMerge(uuid7State));
+};

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 ID 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 ID validation
+ * @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 ID generation
+ * @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 ID 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 ID validation
+ * @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 ID generation
+ * @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;
@@ -28,7 +80,7 @@ export const ksuid = Effect.zipWith(DateTimes.now, RandomValues.call(PAYLOAD_BYT
     // Copy payload
     bytes.set(payload, TIMESTAMP_BYTES);
     // Encode as base62
-    return Ksuid.makeUnsafe(base62Encode(bytes));
+    return Ksuid.make(base62Encode(bytes));
 });
 // Utilities
 const base62Chars = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";

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 ID 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 ID validation
+ * @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 ID generation
+ * @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,9 +1,56 @@
 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 ID 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 ID validation
+ * @since 1.0.0
+ */
 export const isNanoId = Schema.is(NanoId);
-export const nanoId = Effect.map(RandomValues.call(21), (seed) => NanoId.makeUnsafe(Array.from(seed, numToCharacter).join("")));
+/**
+ * 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 ID generation
+ * @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;
     if (byte < 36) {

package/dist/RandomValues.d.ts

@@ -1,12 +1,71 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as ServiceMap from "effect/ServiceMap";
-declare const RandomValues_base: ServiceMap.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>;
+import * as Context from "effect/Context";
+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 Entropy 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 Entropy 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 Entropy 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 Entropy 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,UAAU,MAAM,mBAAmB,CAAC;kGAI3C,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"}