effect-start 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-start",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "type": "module",
   "license": "MIT",
   "exports": {
@@ -44,6 +44,11 @@
       "types": "./dist/middlewares/index.d.ts",
       "default": "./dist/middlewares/index.js"
     },
+    "./Unique": {
+      "bun": "./src/Unique.ts",
+      "types": "./dist/Unique.d.ts",
+      "default": "./dist/Unique.js"
+    },
     "./experimental": {
       "bun": "./src/experimental/index.ts",
       "types": "./dist/experimental/index.d.ts",
@@ -96,6 +101,8 @@
   },
   "files": [
     "src/",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
     "dist/",
     "README.md",
     "package.json"

package/src/Development.ts

@@ -1,18 +1,13 @@
-import {
-  Context,
-  Effect,
-  Function,
-  Layer,
-  Option,
-  pipe,
-  PubSub,
-  Stream,
-} from "effect"
-import { globalValue } from "effect/GlobalValue"
-import {
-  Error,
-  FileSystem,
-} from "./node/FileSystem.ts"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Function from "effect/Function"
+import * as GlobalValue from "effect/GlobalValue"
+import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+import * as PubSub from "effect/PubSub"
+import * as Stream from "effect/Stream"
+import * as Error from "./node/PlatformError.ts"
+import * as FileSystem from "@effect/platform/FileSystem"
 
 export type DevelopmentEvent =
   | FileSystem.WatchEvent
@@ -20,7 +15,7 @@ export type DevelopmentEvent =
     readonly _tag: "Reload"
   }
 
-const devState = globalValue(
+const devState = GlobalValue.globalValue(
   Symbol.for("effect-start/Development"),
   () => ({
     count: 0,
@@ -99,7 +94,7 @@ export const watch = (
       const pubsub = yield* PubSub.unbounded<DevelopmentEvent>()
       devState.pubsub = pubsub
 
-      yield* pipe(
+      yield* Function.pipe(
         watchSource({
           path: opts?.path,
           recursive: opts?.recursive,
@@ -125,7 +120,7 @@ export const layerWatch = (
 
 export const stream = (): Stream.Stream<DevelopmentEvent> =>
   Stream.unwrap(
-    pipe(
+    Function.pipe(
       Effect.serviceOption(Development),
       Effect.map(
         Option.match({

package/src/PlatformRuntime.ts

@@ -0,0 +1,11 @@
+/**
+ * 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/src/Route.ts

@@ -1,9 +1,9 @@
 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 * as Predicate from "effect/Predicate"
-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"
@@ -327,6 +327,18 @@ export {
   sse,
 } from "./RouteSse.ts"
 
+export function redirect(
+  url: string | URL,
+  status: 301 | 302 | 303 | 307 | 308 = 302,
+): Entity.Entity<""> {
+  return Entity.make("", {
+    status,
+    headers: {
+      location: url instanceof URL ? url.href : url,
+    },
+  })
+}
+
 export class Routes extends Context.Tag("effect-start/Routes")<
   Routes,
   RouteTree.RouteTree
@@ -345,3 +357,20 @@ export function layer(routes: RouteTree.RouteMap | RouteTree.RouteTree) {
 export {
   make as tree,
 } from "./RouteTree.ts"
+
+export function lazy<T extends RouteSet.Any>(
+  load: () => Promise<{ default: T }>,
+): Effect.Effect<T, never, never> {
+  let cached: T | undefined
+  return Effect.suspend(() => {
+    if (cached !== undefined) {
+      return Effect.succeed(cached)
+    }
+    return Effect.promise(load).pipe(
+      Effect.map((mod) => {
+        cached = mod.default
+        return cached
+      }),
+    )
+  })
+}

package/src/RouteHttp.ts

@@ -17,14 +17,6 @@ import * as RouteMount from "./RouteMount.ts"
 import * as RouteTree from "./RouteTree.ts"
 import * as StreamExtra from "./StreamExtra.ts"
 
-export {
-  currentSpanNameGenerator,
-  currentTracerDisabledWhen,
-  parentSpanFromHeaders,
-  withSpanNameGenerator,
-  withTracerDisabledWhen,
-} from "./RouteHttpTracer.ts"
-
 type UnboundedRouteWithMethod = Route.Route.With<{
   method: RouteMount.RouteMount.Method
   format?: RouteBody.Format
@@ -74,6 +66,12 @@ const getStatusFromCause = (cause: Cause.Cause<unknown>): number => {
   return 500
 }
 
+const respondError = (options: { status: number; message: string }): Response =>
+  new Response(JSON.stringify(options, null, 2), {
+    status: options.status,
+    headers: { "content-type": "application/json" },
+  })
+
 function streamResponse(
   stream: Stream.Stream<unknown, unknown, unknown>,
   headers: Record<string, string | null | undefined>,
@@ -211,9 +209,7 @@ export const toWebHandlerRuntime = <R>(
 
       if (methodRoutes.length === 0 && wildcards.length === 0) {
         return Promise.resolve(
-          Response.json({ status: 405, message: "method not allowed" }, {
-            status: 405,
-          }),
+          respondError({ status: 405, message: "method not allowed" }),
         )
       }
 
@@ -234,9 +230,7 @@ export const toWebHandlerRuntime = <R>(
         && !hasWildcardFormatRoutes
       ) {
         return Promise.resolve(
-          Response.json({ status: 406, message: "not acceptable" }, {
-            status: 406,
-          }),
+          respondError({ status: 406, message: "not acceptable" }),
         )
       }
 
@@ -315,9 +309,7 @@ export const toWebHandlerRuntime = <R>(
               : 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)
@@ -380,9 +372,8 @@ export const toWebHandlerRuntime = <R>(
               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 })
               })
             ),
           ),
@@ -400,18 +391,11 @@ export const toWebHandlerRuntime = <R>(
           if (exit._tag === "Success") {
             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 }))
           }
         })
       })
@@ -438,6 +422,6 @@ export function* walkHandles(
 
   const toHandler = toWebHandlerRuntime(runtime)
   for (const [path, routes] of pathGroups) {
-    yield [path, toHandler(routes as Iterable<UnboundedRouteWithMethod>)]
+    yield [path, toHandler(routes)]
   }
 }

package/src/RouteMount.ts

@@ -142,7 +142,7 @@ export type MountedRoute = Route.Route.Route<
   {
     method: RouteMount.Method
     path: PathPattern.PathPattern
-    format?: string
+    format?: RouteBody.Format
   },
   {},
   any,

package/src/Start.ts

@@ -1,14 +1,8 @@
-import * as FetchHttpClient from "@effect/platform/FetchHttpClient"
-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 Effect from "effect/Effect"
 import * as Function from "effect/Function"
 import * as Layer from "effect/Layer"
 import * as BunHttpServer from "./bun/BunHttpServer.ts"
 import * as BunRuntime from "./bun/BunRuntime.ts"
-import * as NodeFileSystem from "./node/FileSystem.ts"
 import * as StartApp from "./StartApp.ts"
 
 export function layer<
@@ -29,11 +23,7 @@ export function serve<ROut, E>(
     default: Layer.Layer<
       ROut,
       E,
-      | HttpServer.HttpServer
-      | HttpClient.HttpClient
-      | HttpRouter.Default
-      | FileSystem.FileSystem
-      | BunHttpServer.BunHttpServer
+      BunHttpServer.BunHttpServer
     >
   }>,
 ) {
@@ -46,13 +36,9 @@ export function serve<ROut, E>(
 
   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,

package/src/Unique.ts

@@ -0,0 +1,232 @@
+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): string {
+  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: number): Uint8Array {
+  const buf = new Uint8Array(length)
+  crypto.getRandomValues(buf)
+  return buf
+}
+
+export const UUID_NIL = "00000000-0000-0000-0000-000000000000"
+
+export function uuid4(): string {
+  return formatUuid(uuid4bytes())
+}
+
+export function uuid7(time: number = Date.now()): string {
+  return formatUuid(uuid7Bytes(time))
+}
+
+function uuid4bytes(): Uint8Array {
+  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: Uint8Array): number {
+  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: number = Date.now()): Uint8Array {
+  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: Uint8Array): string {
+  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: number = Date.now()): string {
+  const bytes = ulidBytes(time)
+  return formatUlid(bytes)
+}
+
+export function ulidBytes(time: number = Date.now()): Uint8Array {
+  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: Uint8Array): string {
+  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: number): string {
+  let value = BigInt(time)
+  const result = new Array<string>(10)
+
+  for (let i = 9; i >= 0; i--) {
+    result[i] = ALPHABET_BASE32_CROCKFORD[Number(value & 31n)]
+    value >>= 5n
+  }
+
+  return result.join("")
+}
+
+function toSafeTime(time: number): number {
+  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,
+): string {
+  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: Uint8Array,
+  alphabet = ALPHABET_BASE32_CROCKFORD,
+): string {
+  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
+}

package/src/bun/BunHttpServer.ts

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import * as HttpApp from "@effect/platform/HttpApp"
 import * as HttpServer from "@effect/platform/HttpServer"
 import * as HttpServerError from "@effect/platform/HttpServerError"
@@ -14,12 +13,13 @@ import * as FiberSet from "effect/FiberSet"
 import * as Layer from "effect/Layer"
 import * as Option from "effect/Option"
 import type * as Scope from "effect/Scope"
-import * as FileRouter from "../FileRouter.ts"
 import * as PathPattern from "../PathPattern.ts"
-import * as Random from "../Random.ts"
+import * as PlataformRuntime from "../PlatformRuntime.ts"
 import * as Route from "../Route.ts"
 import * as RouteHttp from "../RouteHttp.ts"
+import * as RouteMount from "../RouteMount.ts"
 import * as RouteTree from "../RouteTree.ts"
+import * as Unique from "../Unique.ts"
 import EmptyHTML from "./_empty.html"
 import {
   makeResponse,
@@ -69,11 +69,8 @@ export const make = (
   Effect.gen(function*() {
     const port = yield* Config.number("PORT").pipe(
       Effect.catchTag("ConfigError", () => {
-        if (
-          typeof process !== "undefined"
-          && !process.stdout.isTTY
-          && process.env.CLAUDECODE
-        ) {
+        if (PlataformRuntime.isAgentHarness()) {
+          // use random port
           return Effect.succeed(0)
         }
 
@@ -95,7 +92,7 @@ export const make = (
     // Bun HMR doesn't work on successive calls to `server.reload` if there are no routes
     // on server start. We workaround that by passing a dummy HTMLBundle [2025-11-26]
     // see: https://github.com/oven-sh/bun/issues/23564
-    currentRoutes[`/.BunEmptyHtml-${Random.token(6)}`] = EmptyHTML
+    currentRoutes[`/.BunEmptyHtml-${Unique.token(10)}`] = EmptyHTML
 
     const websocket: Bun.WebSocketHandler<WebSocketContext> = {
       open(ws) {

package/src/bun/BunRoute.ts

@@ -6,7 +6,7 @@ import * as Option from "effect/Option"
 import * as Entity from "../Entity.ts"
 import * as Hyper from "../hyper/Hyper.ts"
 import * as HyperHtml from "../hyper/HyperHtml.ts"
-import * as Random from "../Random.ts"
+import * as Unique from "../Unique.ts"
 import * as Route from "../Route.ts"
 import * as RouterPattern from "../RouterPattern.ts"
 import * as BunHttpServer from "./BunHttpServer.ts"
@@ -25,7 +25,7 @@ export type BunDescriptors = {
 }
 
 export function descriptors(
-  route: Route.Route.Route,
+  route: Route.Route.Route<any, any, any, any, any>,
 ): BunDescriptors | undefined {
   const descriptor = Route.descriptor(route) as Partial<BunDescriptors>
   if (
@@ -40,7 +40,7 @@ export function descriptors(
 export function htmlBundle(
   load: () => Promise<Bun.HTMLBundle | { default: Bun.HTMLBundle }>,
 ) {
-  const bunPrefix = `/.BunRoute-${Random.token(6)}`
+  const bunPrefix = `/.BunRoute-${Unique.token(10)}`
   const bunLoad = () => load().then(mod => "default" in mod ? mod.default : mod)
   const descriptors = { bunPrefix, bunLoad, format: "html" as const }
 

package/src/index.ts

@@ -2,5 +2,6 @@ export * as Bundle from "./bundler/Bundle.ts"
 export * as Development from "./Development.ts"
 export * as Entity from "./Entity.ts"
 export * as FileRouter from "./FileRouter.ts"
+export * as Unique from "./Unique.ts"
 export * as Route from "./Route.ts"
 export * as Start from "./Start.ts"