effect-start 0.18.0 → 0.20.0

package/dist/PlatformError.js

@@ -0,0 +1,43 @@
+import * as Data from "effect/Data";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import { TypeId as TypeId_ } from "@effect/platform/Error";
+export const TypeId = TypeId_;
+export const isPlatformError = (u) => Predicate.hasProperty(u, TypeId);
+export const TypeIdError = (typeId, tag) => {
+    class Base extends Data.Error {
+        _tag = tag;
+    }
+    ;
+    Base.prototype[typeId] = typeId;
+    Base.prototype.name = tag;
+    return Base;
+};
+export const Module = Schema.Literal("Clipboard", "Command", "FileSystem", "KeyValueStore", "Path", "Stream", "Terminal");
+export class BadArgument extends Schema.TaggedError("@effect/platform/Error/BadArgument")("BadArgument", {
+    module: Module,
+    method: Schema.String,
+    description: Schema.optional(Schema.String),
+    cause: Schema.optional(Schema.Defect),
+}) {
+    [TypeId] = TypeId;
+    get message() {
+        return `${this.module}.${this.method}${this.description ? `: ${this.description}` : ""}`;
+    }
+}
+export const SystemErrorReason = Schema.Literal("AlreadyExists", "BadResource", "Busy", "InvalidData", "NotFound", "PermissionDenied", "TimedOut", "UnexpectedEof", "Unknown", "WouldBlock", "WriteZero");
+export class SystemError extends Schema.TaggedError("@effect/platform/Error/SystemError")("SystemError", {
+    reason: SystemErrorReason,
+    module: Module,
+    method: Schema.String,
+    description: Schema.optional(Schema.String),
+    syscall: Schema.optional(Schema.String),
+    pathOrDescriptor: Schema.optional(Schema.Union(Schema.String, Schema.Number)),
+    cause: Schema.optional(Schema.Defect),
+}) {
+    [TypeId] = TypeId;
+    get message() {
+        return `${this.reason}: ${this.module}.${this.method}${this.pathOrDescriptor !== undefined ? ` (${this.pathOrDescriptor})` : ""}${this.description ? `: ${this.description}` : ""}`;
+    }
+}
+export const PlatformError = Schema.Union(BadArgument, SystemError);

package/dist/PlatformRuntime.d.ts

@@ -0,0 +1,27 @@
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import type * as Fiber from "effect/Fiber";
+export interface Teardown {
+    <E, A>(exit: Exit.Exit<E, A>, onExit: (code: number) => void): void;
+}
+export declare const defaultTeardown: Teardown;
+export interface RunMain {
+    (options?: {
+        readonly disableErrorReporting?: boolean | undefined;
+        readonly disablePrettyLogger?: boolean | undefined;
+        readonly teardown?: Teardown | undefined;
+    }): <E, A>(effect: Effect.Effect<A, E>) => void;
+    <E, A>(effect: Effect.Effect<A, E>, options?: {
+        readonly disableErrorReporting?: boolean | undefined;
+        readonly disablePrettyLogger?: boolean | undefined;
+        readonly teardown?: Teardown | undefined;
+    }): void;
+}
+export declare const makeRunMain: (f: <E, A>(options: {
+    readonly fiber: Fiber.RuntimeFiber<A, E>;
+    readonly teardown: Teardown;
+}) => void) => RunMain;
+/**
+ * Are we running within an agent harness, like Claude Code?
+ */
+export declare function isAgentHarness(): string | false | undefined;

package/dist/PlatformRuntime.js

@@ -0,0 +1,51 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FiberRef from "effect/FiberRef";
+import * as FiberRefs from "effect/FiberRefs";
+import * as Function from "effect/Function";
+import * as HashSet from "effect/HashSet";
+import * as Logger from "effect/Logger";
+export const defaultTeardown = (exit, onExit) => {
+    onExit(Exit.isFailure(exit) && !Cause.isInterruptedOnly(exit.cause) ? 1 : 0);
+};
+const addPrettyLogger = (refs, fiberId) => {
+    const loggers = FiberRefs.getOrDefault(refs, FiberRef.currentLoggers);
+    if (!HashSet.has(loggers, Logger.defaultLogger)) {
+        return refs;
+    }
+    return FiberRefs.updateAs(refs, {
+        fiberId,
+        fiberRef: FiberRef.currentLoggers,
+        value: loggers.pipe(HashSet.remove(Logger.defaultLogger), HashSet.add(Logger.prettyLoggerDefault)),
+    });
+};
+export const makeRunMain = (f) => Function.dual((args) => Effect.isEffect(args[0]), (effect, options) => {
+    const fiber = options?.disableErrorReporting === true
+        ? Effect.runFork(effect, {
+            updateRefs: options?.disablePrettyLogger === true
+                ? undefined
+                : addPrettyLogger,
+        })
+        : Effect.runFork(Effect.tapErrorCause(effect, (cause) => {
+            if (Cause.isInterruptedOnly(cause)) {
+                return Effect.void;
+            }
+            return Effect.logError(cause);
+        }), {
+            updateRefs: options?.disablePrettyLogger === true
+                ? undefined
+                : addPrettyLogger,
+        });
+    const teardown = options?.teardown ?? defaultTeardown;
+    return f({ fiber, teardown });
+});
+/**
+ * Are we running within an agent harness, like Claude Code?
+ */
+export function isAgentHarness() {
+    return typeof process !== "undefined"
+        && !process.stdout.isTTY
+        && (process.env.CLAUDECODE
+            || process.env.CURSOR_AGENT);
+}

package/dist/Route.d.ts

@@ -1,8 +1,8 @@
 import * as Context from "effect/Context";
-import type * as Effect from "effect/Effect";
+import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Pipeable from "effect/Pipeable";
-import type * as Entity from "./Entity.ts";
+import * as Entity from "./Entity.ts";
 import * as RouteBody from "./RouteBody.ts";
 import * as RouteTree from "./RouteTree.ts";
 import * as Values from "./Values.ts";
@@ -91,8 +91,12 @@ export declare const json: RouteBody.BuildReturn<Values.Json, "json">;
 export declare const bytes: RouteBody.BuildReturn<Uint8Array<ArrayBufferLike>, "bytes">;
 export { render, } from "./RouteBody.ts";
 export { sse, } from "./RouteSse.ts";
+export declare function redirect(url: string | URL, status?: 301 | 302 | 303 | 307 | 308): Entity.Entity<"">;
 declare const Routes_base: Context.TagClass<Routes, "effect-start/Routes", RouteTree.RouteTree<RouteTree.RouteMap>>;
 export declare class Routes extends Routes_base {
 }
 export declare function layer(routes: RouteTree.RouteMap | RouteTree.RouteTree): Layer.Layer<Routes, never, never>;
 export { make as tree, } from "./RouteTree.ts";
+export declare function lazy<T extends RouteSet.Any>(load: () => Promise<{
+    default: T;
+}>): Effect.Effect<T, never, never>;

package/dist/Route.js

@@ -1,7 +1,9 @@
 import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Pipeable from "effect/Pipeable";
 import * as Predicate from "effect/Predicate";
+import * as Entity from "./Entity.js";
 import * as RouteBody from "./RouteBody.js";
 import * as RouteTree from "./RouteTree.js";
 export const RouteItems = Symbol();
@@ -71,6 +73,14 @@ export const bytes = RouteBody.build({
 });
 export { render, } from "./RouteBody.js";
 export { sse, } from "./RouteSse.js";
+export function redirect(url, status = 302) {
+    return Entity.make("", {
+        status,
+        headers: {
+            location: url instanceof URL ? url.href : url,
+        },
+    });
+}
 export class Routes extends Context.Tag("effect-start/Routes")() {
 }
 export function layer(routes) {
@@ -79,3 +89,15 @@ export function layer(routes) {
         : RouteTree.make(routes));
 }
 export { make as tree, } from "./RouteTree.js";
+export function lazy(load) {
+    let cached;
+    return Effect.suspend(() => {
+        if (cached !== undefined) {
+            return Effect.succeed(cached);
+        }
+        return Effect.promise(load).pipe(Effect.map((mod) => {
+            cached = mod.default;
+            return cached;
+        }));
+    });
+}

package/dist/RouteBody.d.ts

@@ -8,7 +8,7 @@ export type Format = "text" | "html" | "json" | "bytes" | "*";
 type UnwrapStream<T> = T extends Stream.Stream<infer V, any, any> ? V : T;
 type YieldError<T> = T extends Utils.YieldWrap<Effect.Effect<any, infer E, any>> ? E : never;
 type YieldContext<T> = T extends Utils.YieldWrap<Effect.Effect<any, any, infer R>> ? R : never;
-export type GeneratorHandler<B, A, Y> = (context: Values.Simplify<B>, next: (context?: Partial<B> & Record<string, unknown>) => Entity.Entity<UnwrapStream<A>>) => Generator<Y, A | Entity.Entity<A>, unknown>;
+export type GeneratorHandler<B, A, Y> = (context: Values.Simplify<B>, next: (context?: Partial<B> & Record<string, unknown>) => Entity.Entity<UnwrapStream<A>>) => Generator<Y, A | Entity.Entity<A>, never>;
 export type HandlerInput<B, A, E, R> = A | Entity.Entity<A> | Effect.Effect<A | Entity.Entity<A>, E, R> | ((context: Values.Simplify<B>, next: (context?: Partial<B> & Record<string, unknown>) => Entity.Entity<UnwrapStream<A>>) => Effect.Effect<A | Entity.Entity<A>, E, R> | Generator<Utils.YieldWrap<Effect.Effect<unknown, E, R>>, A | Entity.Entity<A>, unknown>);
 export declare function handle<B, A, Y extends Utils.YieldWrap<Effect.Effect<any, any, any>>>(handler: GeneratorHandler<B, A, Y>): Route.Route.Handler<B, A, YieldError<Y>, YieldContext<Y>>;
 export declare function handle<B, A, E, R>(handler: HandlerInput<B, A, E, R>): Route.Route.Handler<B, A, E, R>;

package/dist/RouteHttp.d.ts

@@ -5,7 +5,6 @@ import * as Route from "./Route.ts";
 import * as RouteBody from "./RouteBody.ts";
 import * as RouteMount from "./RouteMount.ts";
 import * as RouteTree from "./RouteTree.ts";
-export { currentSpanNameGenerator, currentTracerDisabledWhen, parentSpanFromHeaders, withSpanNameGenerator, withTracerDisabledWhen, } from "./RouteHttpTracer.ts";
 type UnboundedRouteWithMethod = Route.Route.With<{
     method: RouteMount.RouteMount.Method;
     format?: RouteBody.Format;
@@ -19,3 +18,4 @@ export declare const clientAbortFiberId: FiberId.Runtime;
 export declare const toWebHandlerRuntime: <R>(runtime: Runtime.Runtime<R>) => (routes: Iterable<UnboundedRouteWithMethod>) => Http.WebHandler;
 export declare const toWebHandler: (routes: Iterable<UnboundedRouteWithMethod>) => Http.WebHandler;
 export declare function walkHandles(tree: RouteTree.RouteTree, runtime?: Runtime.Runtime<never>): Generator<[path: string, handler: Http.WebHandler]>;
+export {};

package/dist/RouteHttp.js

@@ -12,7 +12,6 @@ import * as Route from "./Route.js";
 import * as RouteHttpTracer from "./RouteHttpTracer.js";
 import * as RouteTree from "./RouteTree.js";
 import * as StreamExtra from "./StreamExtra.js";
-export { currentSpanNameGenerator, currentTracerDisabledWhen, parentSpanFromHeaders, withSpanNameGenerator, withTracerDisabledWhen, } from "./RouteHttpTracer.js";
 // Used to match Accept headers against available route formats.
 // text/* matches any text type (text/plain, text/event-stream, text/markdown, etc.)
 const formatToMediaType = {
@@ -46,6 +45,10 @@ const getStatusFromCause = (cause) => {
     }
     return 500;
 };
+const respondError = (options) => new Response(JSON.stringify(options, null, 2), {
+    status: options.status,
+    headers: { "content-type": "application/json" },
+});
 function streamResponse(stream, headers, status, runtime) {
     const encoder = new TextEncoder();
     const byteStream = stream.pipe(Stream.map((chunk) => typeof chunk === "string"
@@ -116,9 +119,7 @@ export const toWebHandlerRuntime = (runtime) => {
             const accept = request.headers.get("accept");
             const methodRoutes = methodGroups[method] ?? [];
             if (methodRoutes.length === 0 && wildcards.length === 0) {
-                return Promise.resolve(Response.json({ status: 405, message: "method not allowed" }, {
-                    status: 405,
-                }));
+                return Promise.resolve(respondError({ status: 405, message: "method not allowed" }));
             }
             const allRoutes = [...wildcards, ...methodRoutes];
             const selectedFormat = determineSelectedFormat(accept, allRoutes);
@@ -130,9 +131,7 @@ export const toWebHandlerRuntime = (runtime) => {
             if (selectedFormat === undefined
                 && hasSpecificFormatRoutes
                 && !hasWildcardFormatRoutes) {
-                return Promise.resolve(Response.json({ status: 406, message: "not acceptable" }, {
-                    status: 406,
-                }));
+                return Promise.resolve(respondError({ status: 406, message: "not acceptable" }));
             }
             const createChain = (initialContext) => {
                 let index = 0;
@@ -178,9 +177,7 @@ export const toWebHandlerRuntime = (runtime) => {
                         ? result
                         : Entity.make(result, { status: 200 });
                     if (entity.status === 404 && entity.body === undefined) {
-                        return Response.json({ status: 406, message: "not acceptable" }, {
-                            status: 406,
-                        });
+                        return respondError({ status: 406, message: "not acceptable" });
                     }
                     return yield* toResponse(entity, selectedFormat, runtime);
                 });
@@ -217,9 +214,8 @@ export const toWebHandlerRuntime = (runtime) => {
                 const fiber = runFork(effect.pipe(Effect.scoped, Effect.catchAllCause((cause) => Effect.gen(function* () {
                     yield* Effect.logError(cause);
                     const status = getStatusFromCause(cause);
-                    return Response.json({ status, message: Cause.pretty(cause) }, {
-                        status,
-                    });
+                    const message = Cause.pretty(cause, { renderErrorCause: true });
+                    return respondError({ status, message });
                 }))));
                 request.signal?.addEventListener("abort", () => {
                     fiber.unsafeInterruptAsFork(clientAbortFiberId);
@@ -229,15 +225,12 @@ export const toWebHandlerRuntime = (runtime) => {
                         resolve(exit.value);
                     }
                     else if (isClientAbort(exit.cause)) {
-                        resolve(Response.json({ status: 499, message: "client closed request" }, {
-                            status: 499,
-                        }));
+                        resolve(respondError({ status: 499, message: "client closed request" }));
                     }
                     else {
                         const status = getStatusFromCause(exit.cause);
-                        resolve(Response.json({ status, message: Cause.pretty(exit.cause) }, {
-                            status,
-                        }));
+                        const message = Cause.pretty(exit.cause, { renderErrorCause: true });
+                        resolve(respondError({ status, message }));
                     }
                 });
             });

package/dist/RouteMount.d.ts

@@ -2,6 +2,7 @@ import * as Types from "effect/Types";
 import * as Http from "./Http.ts";
 import * as PathPattern from "./PathPattern.ts";
 import * as Route from "./Route.ts";
+import * as RouteBody from "./RouteBody.ts";
 type Module = typeof import("./RouteMount.ts");
 export type Self = RouteMount.Builder | Module;
 export declare const use: RouteMount.Describer<"*">;
@@ -16,7 +17,7 @@ export declare const add: RouteMount.Add;
 export type MountedRoute = Route.Route.Route<{
     method: RouteMount.Method;
     path: PathPattern.PathPattern;
-    format?: string;
+    format?: RouteBody.Format;
 }, {}, any, any, any>;
 export declare namespace RouteMount {
     export type Method = "*" | Http.Method;

package/dist/Start.d.ts

@@ -1,9 +1,6 @@
 import * as FileSystem from "@effect/platform/FileSystem";
-import * as HttpClient from "@effect/platform/HttpClient";
-import * as HttpRouter from "@effect/platform/HttpRouter";
-import * as HttpServer from "@effect/platform/HttpServer";
 import * as Layer from "effect/Layer";
-import * as BunHttpServer from "./bun/BunHttpServer.ts";
+import * as BunServer from "./bun/BunServer.ts";
 export declare function layer<Layers extends [
     Layer.Layer<never, any, any>,
     ...Array<Layer.Layer<never, any, any>>
@@ -14,6 +11,36 @@ export declare function layer<Layers extends [
 }[number], {
     [k in keyof Layers]: Layer.Layer.Context<Layers[k]>;
 }[number]>;
-export declare function serve<ROut, E>(load: () => Promise<{
-    default: Layer.Layer<ROut, E, HttpServer.HttpServer | HttpClient.HttpClient | HttpRouter.Default | FileSystem.FileSystem | BunHttpServer.BunHttpServer>;
+/**
+ * Bundles layers together, wiring their dependencies automatically.
+ *
+ * Equivalent to chaining `Layer.provide` calls, but more concise.
+ *
+ * **Ordering: dependents first, dependencies last.**
+ *
+ * @example
+ * ```ts
+ * // UserRepo needs Database, Database needs Logger
+ * const AppLayer = Start.pack(
+ *   UserRepoLive,   // needs Database, Logger
+ *   DatabaseLive,   // needs Logger
+ *   LoggerLive,     // no deps
+ * )
+ * // Result: Layer<UserRepo | Database | Logger, never, never>
+ * ```
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare function pack<const Layers extends readonly [Layer.Layer.Any, ...Array<Layer.Layer.Any>]>(...layers: Layers): Layer.Layer<{
+    [K in keyof Layers]: Layer.Layer.Success<Layers[K]>;
+}[number], {
+    [K in keyof Layers]: Layer.Layer.Error<Layers[K]>;
+}[number], Exclude<{
+    [K in keyof Layers]: Layer.Layer.Context<Layers[K]>;
+}[number], {
+    [K in keyof Layers]: Layer.Layer.Success<Layers[K]>;
+}[number]>>;
+export declare function serve<ROut, E, RIn extends BunServer.BunServer | FileSystem.FileSystem>(load: () => Promise<{
+    default: Layer.Layer<ROut, E, RIn>;
 }>): void;

package/dist/Start.js

@@ -1,23 +1,41 @@
-import * as FetchHttpClient from "@effect/platform/FetchHttpClient";
-import * as HttpRouter from "@effect/platform/HttpRouter";
-import * as HttpServer from "@effect/platform/HttpServer";
+import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Function from "effect/Function";
 import * as Layer from "effect/Layer";
-import * as BunHttpServer from "./bun/BunHttpServer.js";
 import * as BunRuntime from "./bun/BunRuntime.js";
-import * as NodeFileSystem from "./node/FileSystem.js";
-import * as StartApp from "./StartApp.js";
+import * as BunServer from "./bun/BunServer.js";
+import * as NodeFileSystem from "./node/NodeFileSystem.js";
 export function layer(...layers) {
     return Layer.mergeAll(...layers);
 }
+/**
+ * Bundles layers together, wiring their dependencies automatically.
+ *
+ * Equivalent to chaining `Layer.provide` calls, but more concise.
+ *
+ * **Ordering: dependents first, dependencies last.**
+ *
+ * @example
+ * ```ts
+ * // UserRepo needs Database, Database needs Logger
+ * const AppLayer = Start.pack(
+ *   UserRepoLive,   // needs Database, Logger
+ *   DatabaseLive,   // needs Logger
+ *   LoggerLive,     // no deps
+ * )
+ * // Result: Layer<UserRepo | Database | Logger, never, never>
+ * ```
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function pack(...layers) {
+    const layerArray = layers;
+    const result = layerArray.reduce((acc, layer) => Layer.provideMerge(acc, layer), Layer.succeedContext(Context.empty()));
+    return result;
+}
 export function serve(load) {
     const appLayer = Function.pipe(Effect.tryPromise(load), Effect.map(v => v.default), Effect.orDie, Layer.unwrapEffect);
-    return Function.pipe(BunHttpServer.layerAuto(), HttpServer.withLogAddress, Layer.provide(appLayer), Layer.provide([
-        FetchHttpClient.layer,
-        HttpRouter.Default.Live,
-        BunHttpServer.layer(),
-        NodeFileSystem.layer,
-        StartApp.layer(),
-    ]), Layer.launch, BunRuntime.runMain);
+    const composed = Function.pipe(BunServer.layer(), BunServer.withLogAddress, Layer.provide(appLayer), Layer.provide(NodeFileSystem.layer), Layer.provide(BunServer.layer()));
+    return Function.pipe(composed, Layer.launch, BunRuntime.runMain);
 }

package/dist/Unique.d.ts

@@ -0,0 +1,50 @@
+export declare const ALPHABET_BASE32_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export declare const ALPHABET_BASE32_RFC4648 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+export declare const ALPHABET_BASE64_URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+export declare const ALPHABET_HEX = "0123456789abcdef";
+/**
+ * Generate a random string for ids, session tokens, and API keys.
+ * It uses human-friendly crockford base32 encoding (5 bit of entropy per char)
+ *
+ * Minimal recommended length:
+ * - public ids: 16 chars (~80 bits)
+ * - API keys: 32 chars (~160 bits)
+ * - session tokens: 32-40 chars (~160-200 bits)
+ */
+export declare function token(length?: number): string;
+export declare function bytes(length: number): Uint8Array;
+export declare const UUID_NIL = "00000000-0000-0000-0000-000000000000";
+export declare function uuid4(): string;
+export declare function uuid7(time?: number): string;
+/**
+ * Decode a 48-bit Unix timestamp (ms) from UUID7 or ULID.
+ *
+ * @example
+ * const bytes = Unique.uuid7Bytes()
+ * const timestamp = Unique.toTimestamp(bytes)
+ *
+ * @example
+ * const bytes = Unique.ulidBytes()
+ * const timestamp = Unique.toTimestamp(bytes)
+ */
+export declare function toTimestamp(bytes: Uint8Array): number;
+export declare function uuid7Bytes(time?: number): Uint8Array;
+/**
+ * Convert UUID bytes to canonical (RFC9562) representation.
+ *
+ * @example
+ * Unique.formatUuid(new Uint8Array(16))
+ */
+export declare function formatUuid(bytes: Uint8Array): string;
+export declare function ulid(time?: number): string;
+export declare function ulidBytes(time?: number): Uint8Array;
+/**
+ * Generate a nanoid-style random string.
+ *
+ * FUN_FACT: Original nanoid implementation uses base64url alphabet
+ * with non-standard custom order where charater form common words found
+ * in source code (like use, random, strict) to make gzip/brotli more efficient.
+ * It's qt lil opt from the times where web developers
+ * were competing to have the smallest possible bundle size.
+ */
+export declare function nanoid(size?: number, alphabet?: string): string;

package/dist/Unique.js

@@ -0,0 +1,187 @@
+export const ALPHABET_BASE32_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export const ALPHABET_BASE32_RFC4648 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+export const ALPHABET_BASE64_URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+export const ALPHABET_HEX = "0123456789abcdef";
+/**
+ * Generate a random string for ids, session tokens, and API keys.
+ * It uses human-friendly crockford base32 encoding (5 bit of entropy per char)
+ *
+ * Minimal recommended length:
+ * - public ids: 16 chars (~80 bits)
+ * - API keys: 32 chars (~160 bits)
+ * - session tokens: 32-40 chars (~160-200 bits)
+ */
+export function token(length = 32) {
+    if (length <= 0)
+        return "";
+    const buf = new Uint8Array(length);
+    crypto.getRandomValues(buf);
+    let result = "";
+    for (let i = 0; i < buf.length; i++) {
+        result += ALPHABET_BASE32_CROCKFORD[buf[i] & 31];
+    }
+    return result;
+}
+export function bytes(length) {
+    const buf = new Uint8Array(length);
+    crypto.getRandomValues(buf);
+    return buf;
+}
+export const UUID_NIL = "00000000-0000-0000-0000-000000000000";
+export function uuid4() {
+    return formatUuid(uuid4bytes());
+}
+export function uuid7(time = Date.now()) {
+    return formatUuid(uuid7Bytes(time));
+}
+function uuid4bytes() {
+    const buf = bytes(16);
+    buf[6] = (buf[6] & 0x0f) | 0x40; // version 4
+    buf[8] = (buf[8] & 0x3f) | 0x80; // variant
+    return buf;
+}
+/**
+ * Decode a 48-bit Unix timestamp (ms) from UUID7 or ULID.
+ *
+ * @example
+ * const bytes = Unique.uuid7Bytes()
+ * const timestamp = Unique.toTimestamp(bytes)
+ *
+ * @example
+ * const bytes = Unique.ulidBytes()
+ * const timestamp = Unique.toTimestamp(bytes)
+ */
+export function toTimestamp(bytes) {
+    if (bytes.length < 6)
+        return 0;
+    return (bytes[0] * 0x10000000000
+        + bytes[1] * 0x100000000
+        + bytes[2] * 0x1000000
+        + bytes[3] * 0x10000
+        + bytes[4] * 0x100
+        + bytes[5]);
+}
+export function uuid7Bytes(time = Date.now()) {
+    const buf = new Uint8Array(16);
+    const timestamp = BigInt(toSafeTime(time));
+    // 48-bit timestamp (6 bytes)
+    buf[0] = Number((timestamp >> 40n) & 0xffn);
+    buf[1] = Number((timestamp >> 32n) & 0xffn);
+    buf[2] = Number((timestamp >> 24n) & 0xffn);
+    buf[3] = Number((timestamp >> 16n) & 0xffn);
+    buf[4] = Number((timestamp >> 8n) & 0xffn);
+    buf[5] = Number(timestamp & 0xffn);
+    // 12-bit random A (1.5 bytes)
+    crypto.getRandomValues(buf.subarray(6, 8));
+    buf[6] = (buf[6] & 0x0f) | 0x70; // version 7
+    // 2-bit variant + 62-bit random B (8 bytes)
+    crypto.getRandomValues(buf.subarray(8, 16));
+    buf[8] = (buf[8] & 0x3f) | 0x80; // variant
+    return buf;
+}
+/**
+ * Convert UUID bytes to canonical (RFC9562) representation.
+ *
+ * @example
+ * Unique.formatUuid(new Uint8Array(16))
+ */
+export function formatUuid(bytes) {
+    if (bytes.length === 0)
+        return "";
+    let result = "";
+    for (let i = 0; i < bytes.length; i++) {
+        const byte = bytes[i];
+        result += ALPHABET_HEX[(byte >> 4) & 0x0f];
+        result += ALPHABET_HEX[byte & 0x0f];
+        if (i === 3 || i === 5 || i === 7 || i === 9)
+            result += "-";
+    }
+    return result;
+}
+export function ulid(time = Date.now()) {
+    const bytes = ulidBytes(time);
+    return formatUlid(bytes);
+}
+export function ulidBytes(time = Date.now()) {
+    const buf = new Uint8Array(16);
+    const timestamp = BigInt(toSafeTime(time));
+    buf[0] = Number((timestamp >> 40n) & 0xffn);
+    buf[1] = Number((timestamp >> 32n) & 0xffn);
+    buf[2] = Number((timestamp >> 24n) & 0xffn);
+    buf[3] = Number((timestamp >> 16n) & 0xffn);
+    buf[4] = Number((timestamp >> 8n) & 0xffn);
+    buf[5] = Number(timestamp & 0xffn);
+    crypto.getRandomValues(buf.subarray(6, 16));
+    return buf;
+}
+function formatUlid(bytes) {
+    if (bytes.length !== 16)
+        return "";
+    const timestamp = toTimestamp(bytes);
+    const timePart = encodeUlidTime(timestamp);
+    const randomPart = toBase32(bytes.subarray(6, 16));
+    return `${timePart}${randomPart}`;
+}
+function encodeUlidTime(time) {
+    let value = BigInt(time);
+    const result = new Array(10);
+    for (let i = 9; i >= 0; i--) {
+        result[i] = ALPHABET_BASE32_CROCKFORD[Number(value & 31n)];
+        value >>= 5n;
+    }
+    return result.join("");
+}
+function toSafeTime(time) {
+    if (!Number.isFinite(time))
+        return 0;
+    return Math.max(0, Math.trunc(time));
+}
+/**
+ * Generate a nanoid-style random string.
+ *
+ * FUN_FACT: Original nanoid implementation uses base64url alphabet
+ * with non-standard custom order where charater form common words found
+ * in source code (like use, random, strict) to make gzip/brotli more efficient.
+ * It's qt lil opt from the times where web developers
+ * were competing to have the smallest possible bundle size.
+ */
+export function nanoid(size = 21, alphabet = ALPHABET_BASE64_URL) {
+    if (size <= 0 || alphabet.length === 0)
+        return "";
+    const length = alphabet.length;
+    const mask = (2 << Math.floor(Math.log2(length - 1))) - 1;
+    const step = Math.ceil((1.6 * mask * size) / length);
+    let id = "";
+    while (id.length < size) {
+        const bytes = new Uint8Array(step);
+        crypto.getRandomValues(bytes);
+        for (let i = 0; i < step && id.length < size; i++) {
+            const index = bytes[i] & mask;
+            if (index < length)
+                id += alphabet[index];
+        }
+    }
+    return id;
+}
+function toBase32(bytes, alphabet = ALPHABET_BASE32_CROCKFORD) {
+    if (bytes.length === 0)
+        return "";
+    let result = "";
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            const index = (buffer >> bits) & 31;
+            result += alphabet[index];
+            buffer &= (1 << bits) - 1;
+        }
+    }
+    if (bits > 0) {
+        const index = (buffer << (5 - bits)) & 31;
+        result += alphabet[index];
+    }
+    return result;
+}