effect-start 0.9.0 → 0.11.0

package/src/Route.ts

@@ -1,13 +1,13 @@
 import * as HttpMethod from "@effect/platform/HttpMethod"
+import * as HttpMiddleware from "@effect/platform/HttpMiddleware"
 import * as HttpServerRequest from "@effect/platform/HttpServerRequest"
-import * as HttpServerRespondable from "@effect/platform/HttpServerRespondable"
 import * as HttpServerResponse from "@effect/platform/HttpServerResponse"
 import * as Effect from "effect/Effect"
 import * as Pipeable from "effect/Pipeable"
 import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
 import type { YieldWrap } from "effect/Utils"
-import * as HyperHtml from "./HyperHtml.ts"
+import * as RouteRender from "./RouteRender.ts"
 
 export {
   pipe,
@@ -63,12 +63,14 @@ type Self =
 
 const TypeId: unique symbol = Symbol.for("effect-start/Route")
 const RouteSetTypeId: unique symbol = Symbol.for("effect-start/RouteSet")
+const RouteLayerTypeId: unique symbol = Symbol.for("effect-start/RouteLayer")
 
 export type RouteMethod =
   | "*"
   | HttpMethod.HttpMethod
 
-export type RoutePath = `/${string}`
+// TODO: This should be a RouterPattern and moved to its file?
+export type RoutePattern = `/${string}`
 
 /**
  * Route media type used for content negotiation.
@@ -76,55 +78,24 @@ export type RoutePath = `/${string}`
  * for the same path & method, depending on the `Accept` header
  * of the request.
  */
-type RouteMedia =
+export type RouteMedia =
   | "*"
   | "text/plain"
   | "text/html"
   | "application/json"
 
+/**
+ * A handler function that produces a raw value.
+ * The value will be rendered to an HttpServerResponse by RouteRender
+ * based on the route's media type.
+ *
+ * Receives RouteContext which includes an optional next() for layers.
+ */
 export type RouteHandler<
   A = unknown,
   E = any,
   R = any,
-> =
-  /**
-   * A handler that contains raw value.
-   * Can be consumed from other handlers to build more complex responses.
-   * For example, a Route can render markdown for API/AI consumption
-   * and another Route can wrap it in HTML for browsers.
-   */
-  | RouteHandler.Value<A, E, R>
-  /**
-   * A handler returns `HttpServerResponse`.
-   * Should not be consumed with caution: if body is a stream,
-   * consuming it in another handler may break the stream.
-   */
-  | RouteHandler.Encoded<E, R>
-
-export namespace RouteHandler {
-  export type Value<
-    A = unknown,
-    E = any,
-    R = any,
-  > = Effect.Effect<
-    {
-      [HttpServerRespondable.symbol]: () => Effect.Effect<
-        HttpServerResponse.HttpServerResponse,
-        E,
-        R
-      >
-      raw: A
-    },
-    E,
-    R
-  >
-
-  export type Encoded<E = any, R = any> = Effect.Effect<
-    HttpServerResponse.HttpServerResponse,
-    E,
-    R
-  >
-}
+> = (context: RouteContext) => Effect.Effect<A, E, R>
 
 /**
  * Helper type for a value that can be a single item or an array.
@@ -213,7 +184,7 @@ type RouteBuilder = {
   get: typeof get
   put: typeof put
   patch: typeof patch
-  del: typeof del
+  delete: typeof _delete
   options: typeof options
   head: typeof head
 
@@ -262,36 +233,84 @@ export namespace RouteSet {
     & RouteBuilder
 }
 
+/**
+ * Type for HTTP middleware function
+ */
+export type HttpMiddlewareFunction = ReturnType<typeof HttpMiddleware.make>
+
+/**
+ * Marker type for route middleware specification.
+ * Used to distinguish middleware from routes in Route.layer() arguments.
+ */
+export interface RouteMiddleware {
+  readonly _tag: "RouteMiddleware"
+  readonly middleware: HttpMiddlewareFunction
+}
+
+export type RouteLayer<
+  M extends ReadonlyArray<Route.Default> = ReadonlyArray<Route.Default>,
+  Schemas extends RouteSchemas = RouteSchemas.Empty,
+> =
+  & Pipeable.Pipeable
+  & {
+    [RouteLayerTypeId]: typeof RouteLayerTypeId
+    [RouteSetTypeId]: typeof RouteSetTypeId
+    set: M
+    schema: Schemas
+    httpMiddleware?: HttpMiddlewareFunction
+  }
+  & RouteBuilder
+
+export const isRouteLayer = (u: unknown): u is RouteLayer =>
+  Predicate.hasProperty(u, RouteLayerTypeId)
+
+/**
+ * Check if two routes match based on method and media type.
+ * Returns true if both method and media type match, accounting for wildcards.
+ */
+export function matches(
+  a: Route.Default,
+  b: Route.Default,
+): boolean {
+  const methodMatches = a.method === "*"
+    || b.method === "*"
+    || a.method === b.method
+
+  const mediaMatches = a.media === "*"
+    || b.media === "*"
+    || a.media === b.media
+
+  return methodMatches && mediaMatches
+}
+
 export const post = makeMethodModifier("POST")
 export const get = makeMethodModifier("GET")
 export const put = makeMethodModifier("PUT")
 export const patch = makeMethodModifier("PATCH")
-export const del = makeMethodModifier("DELETE")
 export const options = makeMethodModifier("OPTIONS")
 export const head = makeMethodModifier("HEAD")
+const _delete = makeMethodModifier("DELETE")
+export {
+  _delete as delete,
+}
 
-export const text = makeMediaFunction(
+export const text = makeMediaFunction<"GET", "text/plain", string>(
   "GET",
   "text/plain",
-  makeValueHandler<string>(HttpServerResponse.text),
 )
 
-export const html = makeMediaFunction(
+export const html = makeMediaFunction<
+  "GET",
+  "text/html",
+  string | GenericJsxObject
+>(
   "GET",
   "text/html",
-  makeValueHandler<string | JsxObject>((raw) => {
-    // Check if it's a JSX element (has type and props properties)
-    if (isJsxObject(raw)) {
-      return HttpServerResponse.html(HyperHtml.renderToString(raw))
-    }
-    return HttpServerResponse.html(raw as string)
-  }),
 )
 
-export const json = makeMediaFunction(
+export const json = makeMediaFunction<"GET", "application/json", JsonValue>(
   "GET",
   "application/json",
-  makeValueHandler<JsonValue>((raw) => HttpServerResponse.unsafeJson(raw)),
 )
 
 /**
@@ -379,7 +398,7 @@ function makeSingleStringSchemaModifier<
   {
     const baseRoutes = isRouteSet(this)
       ? this.set
-      : []
+      : [] as const
     const baseSchema = isRouteSet(this)
       ? this.schema
       : {} as RouteSchemas.Empty
@@ -389,12 +408,12 @@ function makeSingleStringSchemaModifier<
       : Schema.Struct(fieldsOrSchema as Schema.Struct.Fields)
 
     return makeSet(
-      baseRoutes as any,
+      baseRoutes as ReadonlyArray<Route.Default>,
       {
         ...baseSchema,
         [key]: schema,
-      } as any,
-    ) as any
+      },
+    ) as never
   }
 }
 
@@ -430,7 +449,7 @@ function makeMultiStringSchemaModifier<
   {
     const baseRoutes = isRouteSet(this)
       ? this.set
-      : []
+      : [] as const
     const baseSchema = isRouteSet(this)
       ? this.schema
       : {} as RouteSchemas.Empty
@@ -440,12 +459,12 @@ function makeMultiStringSchemaModifier<
       : Schema.Struct(fieldsOrSchema as Schema.Struct.Fields)
 
     return makeSet(
-      baseRoutes as any,
+      baseRoutes as ReadonlyArray<Route.Default>,
       {
         ...baseSchema,
         [key]: schema,
-      } as any,
-    ) as any
+      },
+    ) as never
   }
 }
 
@@ -478,7 +497,7 @@ function makeUnionSchemaModifier<
   {
     const baseRoutes = isRouteSet(this)
       ? this.set
-      : []
+      : [] as const
     const baseSchema = isRouteSet(this)
       ? this.schema
       : {} as RouteSchemas.Empty
@@ -488,12 +507,12 @@ function makeUnionSchemaModifier<
       : Schema.Struct(fieldsOrSchema as Schema.Struct.Fields)
 
     return makeSet(
-      baseRoutes as any,
+      baseRoutes as ReadonlyArray<Route.Default>,
       {
         ...baseSchema,
         [key]: schema,
-      } as any,
-    ) as any
+      },
+    ) as never
   }
 }
 
@@ -511,7 +530,7 @@ const SetProto = {
   get,
   put,
   patch,
-  del,
+  delete: _delete,
   options,
   head,
 
@@ -538,6 +557,13 @@ const RouteProto = Object.assign(
   } satisfies Route.Proto,
 )
 
+const RouteLayerProto = Object.assign(
+  Object.create(SetProto),
+  {
+    [RouteLayerTypeId]: RouteLayerTypeId,
+  },
+)
+
 export function isRoute(input: unknown): input is Route {
   return Predicate.hasProperty(input, TypeId)
 }
@@ -558,24 +584,6 @@ export type JsonValue =
     [key: string]: JsonValue
   }
 
-/**
- * Constructs a URL from HttpServerRequest.
- * Handles relative URLs by using headers to determine the base URL.
- */
-function makeUrlFromRequest(
-  request: HttpServerRequest.HttpServerRequest,
-): URL {
-  const origin = request.headers.origin
-    ?? request.headers.host
-    ?? "http://localhost"
-  const protocol = request.headers["x-forwarded-proto"] ?? "http"
-  const host = request.headers.host ?? "localhost"
-  const base = origin.startsWith("http")
-    ? origin
-    : `${protocol}://${host}`
-  return new URL(request.url, base)
-}
-
 type RouteContextDecoded = {
   readonly pathParams?: Record<string, any>
   readonly urlParams?: Record<string, any>
@@ -607,20 +615,22 @@ export type DecodeRouteSchemas<Schemas extends RouteSchemas> =
     : {})
 
 /**
- * Context passed to route handler generator functions.
+ * Context passed to route handler functions.
+ *
+ * @template {Input} Decoded schema values (pathParams, urlParams, etc.)
+ * @template {Next}  Return type of next() based on media type
  */
 export type RouteContext<
   Input extends RouteContextDecoded = {},
-> = {
-  request: HttpServerRequest.HttpServerRequest
-  get url(): URL
-} & Input
-
-/**
- * Extracts fields from a Schema.Struct or returns never if not a struct.
- */
-type ExtractStructFields<S> = S extends Schema.Struct<infer Fields> ? Fields
-  : never
+  Next = unknown,
+> =
+  & {
+    request: HttpServerRequest.HttpServerRequest
+    get url(): URL
+    slots: Record<string, string>
+    next: <E = unknown, R = unknown>() => Effect.Effect<Next, E, R>
+  }
+  & Input
 
 /**
  * Merges two RouteSchemas types.
@@ -730,7 +740,7 @@ function mergeSchemas<
   return result
 }
 
-function make<
+export function make<
   Method extends RouteMethod = "*",
   Media extends RouteMedia = "*",
   Handler extends RouteHandler = never,
@@ -784,40 +794,62 @@ function makeSet<
   ) as RouteSet<M, Schemas>
 }
 
+type HandlerInput<A, E, R> =
+  | A
+  | Effect.Effect<A, E, R>
+  | ((context: RouteContext) =>
+    | Effect.Effect<A, E, R>
+    | Generator<YieldWrap<Effect.Effect<A, E, R>>, A, never>)
+
+function normalizeHandler<A, E, R>(
+  handler: HandlerInput<A, E, R>,
+): RouteHandler<A, E, R> {
+  if (typeof handler === "function") {
+    return (context): Effect.Effect<A, E, R> => {
+      const result = (handler as Function)(context)
+      if (Effect.isEffect(result)) {
+        return result as Effect.Effect<A, E, R>
+      }
+      return Effect.gen(() => result) as Effect.Effect<A, E, R>
+    }
+  }
+  if (Effect.isEffect(handler)) {
+    return () => handler
+  }
+  return () => Effect.succeed(handler as A)
+}
+
 /**
  * Factory function that creates Route for a specific method & media.
- * Supports both Effect values and generator functions that receive context.
+ * Accepts Effect, function that returns Effect, and effectful generator.
  */
 function makeMediaFunction<
   Method extends HttpMethod.HttpMethod,
   Media extends RouteMedia,
-  HandlerFn extends (
-    handler: any,
-  ) => any,
+  ExpectedValue,
 >(
   method: Method,
   media: Media,
-  handlerFn: HandlerFn,
 ) {
   return function<
     S extends Self,
-    A,
+    A extends ExpectedValue,
     E = never,
     R = never,
   >(
     this: S,
     handler: S extends RouteSet<infer _Routes, infer Schemas> ?
+        | A
         | Effect.Effect<A, E, R>
         | ((
-          context: RouteContext<DecodeRouteSchemas<Schemas>>,
+          context: RouteContext<DecodeRouteSchemas<Schemas>, ExpectedValue>,
         ) =>
           | Effect.Effect<A, E, R>
           | Generator<YieldWrap<Effect.Effect<A, E, R>>, A, never>)
       :
+        | A
         | Effect.Effect<A, E, R>
-        | ((
-          context: RouteContext<{}>,
-        ) =>
+        | ((context: RouteContext<{}, ExpectedValue>) =>
           | Effect.Effect<A, E, R>
           | Generator<YieldWrap<Effect.Effect<A, E, R>>, A, never>),
   ): S extends RouteSet<infer Routes, infer Schemas> ? RouteSet<[
@@ -825,7 +857,7 @@ function makeMediaFunction<
       Route<
         Method,
         Media,
-        ReturnType<HandlerFn>,
+        RouteHandler<A, E, R>,
         Schemas
       >,
     ], Schemas>
@@ -833,32 +865,14 @@ function makeMediaFunction<
       Route<
         Method,
         Media,
-        ReturnType<HandlerFn>,
+        RouteHandler<A, E, R>,
         RouteSchemas.Empty
       >,
     ], RouteSchemas.Empty>
   {
-    const effect = typeof handler === "function"
-      ? Effect.gen(function*() {
-        const request = yield* HttpServerRequest.HttpServerRequest
-        const context: RouteContext<any> = {
-          request,
-          get url() {
-            return makeUrlFromRequest(request)
-          },
-        }
-        const result = handler(context)
-        return yield* (typeof result === "object"
-            && result !== null
-            && Symbol.iterator in result
-          ? Effect.gen(() => result as any)
-          : result as Effect.Effect<A, E, R>)
-      })
-      : handler
-
     const baseRoutes = isRouteSet(this)
       ? this.set
-      : []
+      : [] as const
     const baseSchema = isRouteSet(this)
       ? this.schema
       : {} as RouteSchemas.Empty
@@ -869,36 +883,12 @@ function makeMediaFunction<
         make({
           method,
           media,
-          handler: handlerFn(effect as any) as any,
-          schemas: baseSchema as any,
+          handler: normalizeHandler(handler),
+          schemas: baseSchema,
         }),
-      ] as any,
-      baseSchema as any,
-    ) as any
-  }
-}
-
-/**
- * Factory to create RouteHandler.Value.
- * Useful for structural handlers like JSON
- * or content that can be embedded in other formats,
- * like text or HTML.
- */
-function makeValueHandler<ExpectedRaw = string>(
-  responseFn: (raw: ExpectedRaw) => HttpServerResponse.HttpServerResponse,
-) {
-  return <A extends ExpectedRaw, E = never, R = never>(
-    handler: Effect.Effect<A, E, R>,
-  ): RouteHandler.Value<A, E, R> => {
-    return Effect.gen(function*() {
-      const raw = yield* handler
-
-      return {
-        [HttpServerRespondable.symbol]: () =>
-          Effect.succeed(responseFn(raw as ExpectedRaw)),
-        raw,
-      }
-    }) as RouteHandler.Value<A, E, R>
+      ] as ReadonlyArray<Route.Default>,
+      baseSchema,
+    ) as never
   }
 }
 
@@ -970,23 +960,188 @@ function makeMethodModifier<
           return make({
             ...route,
             method,
-            schemas: mergeSchemas(baseSchema, route.schemas) as any,
+            schemas: mergeSchemas(baseSchema, route.schemas),
           })
         }),
-      ] as any,
-      baseSchema as any,
-    ) as any
+      ] as ReadonlyArray<Route.Default>,
+      baseSchema,
+    ) as never
   }
 }
 
-type JsxObject = {
+export type GenericJsxObject = {
   type: any
   props: any
 }
 
-function isJsxObject(value: any) {
+export function isGenericJsxObject(value: unknown): value is GenericJsxObject {
   return typeof value === "object"
     && value !== null
     && "type" in value
     && "props" in value
 }
+
+/**
+ * Create HTTP middleware spec for Route.layer().
+ * Multiple middleware can be composed by passing multiple Route.http() to Route.layer().
+ *
+ * @example
+ * Route.layer(
+ *   Route.http(middleware1),
+ *   Route.http(middleware2),
+ *   Route.http(middleware3)
+ * )
+ */
+export function http(
+  middleware: HttpMiddlewareFunction,
+): RouteMiddleware {
+  return {
+    _tag: "RouteMiddleware",
+    middleware,
+  }
+}
+
+/**
+ * Create a RouteLayer from routes and middleware.
+ *
+ * Accepts:
+ * - Route.http(middleware) - HTTP middleware to apply to all child routes
+ * - Route.html/text/json/etc handlers - Wrapper routes that receive props.children
+ * - Other RouteSets - Routes to include in the layer
+ *
+ * Multiple middleware are composed in order - first middleware wraps second, etc.
+ * Routes in the layer act as wrappers for child routes with matching method + media type.
+ *
+ * @example
+ * Route.layer(
+ *   Route.http(loggingMiddleware),
+ *   Route.http(authMiddleware),
+ *   Route.html(function*(props) {
+ *     return <html><body>{props.children}</body></html>
+ *   })
+ * )
+ */
+export function layer(
+  ...items: Array<RouteMiddleware | RouteSet.Default>
+): RouteLayer {
+  const routeMiddleware: RouteMiddleware[] = []
+  const routeSets: RouteSet.Default[] = []
+
+  for (const item of items) {
+    if ("_tag" in item && item._tag === "RouteMiddleware") {
+      routeMiddleware.push(item)
+    } else if (isRouteSet(item)) {
+      routeSets.push(item)
+    }
+  }
+
+  const layerRoutes: Route.Default[] = []
+
+  for (const routeSet of routeSets) {
+    layerRoutes.push(...routeSet.set)
+  }
+
+  const middlewareFunctions = routeMiddleware.map((spec) => spec.middleware)
+  const httpMiddleware = middlewareFunctions.length === 0
+    ? undefined
+    : middlewareFunctions.length === 1
+    ? middlewareFunctions[0]
+    : (app: any) => middlewareFunctions.reduceRight((acc, mw) => mw(acc), app)
+
+  return Object.assign(
+    Object.create(RouteLayerProto),
+    {
+      set: layerRoutes,
+      schema: {},
+      httpMiddleware,
+    },
+  )
+}
+
+/**
+ * Extract method union from a RouteSet's routes
+ */
+
+type ExtractMethods<T extends ReadonlyArray<Route.Default>> =
+  T[number]["method"]
+
+/**
+ * Extract media union from a RouteSet's routes
+ */
+type ExtractMedia<T extends ReadonlyArray<Route.Default>> = T[number]["media"]
+
+/**
+ * Merge two RouteSets into one with content negotiation.
+ * Properly infers union types for method/media and merges schemas.
+ */
+export function merge<
+  RoutesA extends ReadonlyArray<Route.Default>,
+  SchemasA extends RouteSchemas,
+  RoutesB extends ReadonlyArray<Route.Default>,
+  SchemasB extends RouteSchemas,
+>(
+  self: RouteSet<RoutesA, SchemasA>,
+  other: RouteSet<RoutesB, SchemasB>,
+): RouteSet<
+  [
+    Route<
+      ExtractMethods<RoutesA> | ExtractMethods<RoutesB>,
+      ExtractMedia<RoutesA> | ExtractMedia<RoutesB>,
+      RouteHandler<HttpServerResponse.HttpServerResponse, any, never>,
+      MergeSchemas<SchemasA, SchemasB>
+    >,
+  ],
+  MergeSchemas<SchemasA, SchemasB>
+> {
+  const allRoutes = [...self.set, ...other.set]
+  const mergedSchemas = mergeSchemas(self.schema, other.schema)
+
+  const handler: RouteHandler<HttpServerResponse.HttpServerResponse> = (
+    context,
+  ) =>
+    Effect.gen(function*() {
+      const accept = context.request.headers.accept ?? ""
+
+      if (accept.includes("application/json")) {
+        const jsonRoute = allRoutes.find((r) => r.media === "application/json")
+        if (jsonRoute) {
+          return yield* RouteRender.render(jsonRoute, context)
+        }
+      }
+
+      if (accept.includes("text/plain")) {
+        const textRoute = allRoutes.find((r) => r.media === "text/plain")
+        if (textRoute) {
+          return yield* RouteRender.render(textRoute, context)
+        }
+      }
+
+      if (
+        accept.includes("text/html") || accept.includes("*/*") || !accept
+      ) {
+        const htmlRoute = allRoutes.find((r) => r.media === "text/html")
+        if (htmlRoute) {
+          return yield* RouteRender.render(htmlRoute, context)
+        }
+      }
+
+      const firstRoute = allRoutes[0]
+      if (firstRoute) {
+        return yield* RouteRender.render(firstRoute, context)
+      }
+
+      return HttpServerResponse.empty({ status: 406 })
+    })
+
+  return makeSet(
+    [
+      make({
+        method: allRoutes[0]?.method ?? "*",
+        media: allRoutes[0]?.media ?? "*",
+        handler,
+        schemas: mergedSchemas,
+      }),
+    ] as any,
+    mergedSchemas,
+  ) as any
+}