effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/unstable/http/HttpRouter.ts

@@ -41,7 +41,7 @@ const TypeId = "~effect/http/HttpRouter"
  * and expose the registered routes as an Effect that handles the current server
  * request.
  *
- * @category HttpRouter
+ * @category services
  * @since 4.0.0
  */
 export interface HttpRouter {
@@ -97,7 +97,7 @@ export interface HttpRouter {
  * Route and middleware layers require this service to register themselves with
  * the router.
  *
- * @category HttpRouter
+ * @category services
  * @since 4.0.0
  */
 export const HttpRouter: Context.Service<HttpRouter, HttpRouter> = Context.Service<HttpRouter>(
@@ -112,7 +112,7 @@ export const HttpRouter: Context.Service<HttpRouter, HttpRouter> = Context.Servi
  * The returned router accepts route and middleware registrations and later routes
  * the current `HttpServerRequest` to the matching `HttpServerResponse`.
  *
- * @category HttpRouter
+ * @category constructors
  * @since 4.0.0
  */
 export const make = Effect.gen(function*() {
@@ -190,8 +190,8 @@ export const make = Effect.gen(function*() {
       }),
     asHttpEffect() {
       let handler = Effect.withFiber<HttpServerResponse.HttpServerResponse, unknown>((fiber) => {
-        const contextMap = new Map(fiber.context.mapUnsafe)
-        const request = contextMap.get(HttpServerRequest.HttpServerRequest.key) as HttpServerRequest.HttpServerRequest
+        let context = fiber.context
+        const request = Context.getUnsafe(context, HttpServerRequest.HttpServerRequest)
         let result = router.find(request.method, request.url)
         if (result === undefined && request.method === "HEAD") {
           result = router.find("GET", request.url)
@@ -205,26 +205,30 @@ export const make = Effect.gen(function*() {
         }
         const route = result.handler
         if (Option.isSome(route.prefix)) {
-          contextMap.set(HttpServerRequest.HttpServerRequest.key, sliceRequestUrl(request, route.prefix.value))
+          context = Context.add(
+            context,
+            HttpServerRequest.HttpServerRequest,
+            sliceRequestUrl(request, route.prefix.value)
+          )
         }
-        contextMap.set(HttpServerRequest.ParsedSearchParams.key, result.searchParams)
-        contextMap.set(RouteContext.key, {
+        context = Context.add(context, HttpServerRequest.ParsedSearchParams, result.searchParams)
+        context = Context.add(context, RouteContext, {
           route,
           params: result.params
         })
 
-        const span = contextMap.get(Tracer.ParentSpan.key) as Tracer.Span | undefined
+        const span = Context.getOrUndefined(context, Tracer.ParentSpan)
         if (span && span._tag === "Span") {
           span.attribute("http.route", route.path)
         }
-        return Effect.provideContext(
+        return Effect.updateContext(
           (route.uninterruptible ?
             route.handler :
             Effect.interruptible(route.handler)) as Effect.Effect<
               HttpServerResponse.HttpServerResponse,
               unknown
             >,
-          Context.makeUnsafe(contextMap)
+          () => context
         )
       })
       if (middleware.size === 0) return handler
@@ -249,7 +253,7 @@ function sliceRequestUrl(request: HttpServerRequest.HttpServerRequest, prefix: s
  * The value is passed to the route matcher when an `HttpRouter` is created and
  * defaults to an empty configuration.
  *
- * @category configuration
+ * @category services
  * @since 4.0.0
  */
 export const RouterConfig = Context.Reference<Partial<FindMyWay.RouterConfig>>(
@@ -446,18 +450,29 @@ export const schemaPathParams = <A, I extends Readonly<Record<string, string | u
  *
  * **Example** (Registering routes during layer construction)
  *
- * ```ts
- * import { Effect, Layer } from "effect"
- * import { HttpRouter } from "effect/unstable/http"
+ * ```ts import.meta.vitest
+ * import { Effect } from "effect"
+ * import { HttpRouter, HttpServerResponse } from "effect/unstable/http"
  *
- * const MyRoute = Layer.effectDiscard(Effect.gen(function*() {
- *   const router = yield* HttpRouter.HttpRouter
+ * const Routes = HttpRouter.use((router) =>
+ *   router.add("GET", "/health", HttpServerResponse.text("ready"))
+ * )
+ *
+ * const program = Effect.acquireUseRelease(
+ *   Effect.sync(() => HttpRouter.toWebHandler(Routes, { disableLogger: true })),
+ *   ({ handler }) =>
+ *     Effect.gen(function*() {
+ *       const response = yield* Effect.promise(() => handler(new Request("http://localhost/health")))
+ *       const body = yield* Effect.promise(() => response.text())
+ *       return body
+ *     }),
+ *   ({ dispose }) => Effect.promise(dispose)
+ * )
  *
- *   // then use `yield* router.add(...)` to add a route
- * }))
+ * await Effect.runPromise(program) // => "ready"
  * ```
  *
- * @category HttpRouter
+ * @category layers
  * @since 4.0.0
  */
 export const use = <A, E, R>(
@@ -469,18 +484,19 @@ export const use = <A, E, R>(
  *
  * **Example** (Adding a GET route)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Layer } from "effect"
  * import { HttpRouter, HttpServerResponse } from "effect/unstable/http"
  *
  * const Route = HttpRouter.add(
  *   "GET",
  *   "/hello",
- *   Effect.succeed(HttpServerResponse.text("Hello, World!"))
+ *   HttpServerResponse.text("Hello, World!")
  * )
+ * Layer.isLayer(Route) // => true
  * ```
  *
- * @category HttpRouter
+ * @category layers
  * @since 4.0.0
  */
 export const add = <E = never, R = never>(
@@ -501,20 +517,21 @@ export const add = <E = never, R = never>(
  *
  * **Example** (Adding multiple routes)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Layer } from "effect"
  * import { HttpRouter, HttpServerResponse } from "effect/unstable/http"
  *
  * const Routes = HttpRouter.addAll([
  *   HttpRouter.route(
  *     "GET",
  *     "/hello",
- *     Effect.succeed(HttpServerResponse.text("Hello, World!"))
+ *     HttpServerResponse.text("Hello, World!")
  *   )
  * ])
+ * Layer.isLayer(Routes) // => true
  * ```
  *
- * @category HttpRouter
+ * @category layers
  * @since 4.0.0
  */
 export const addAll = <Routes extends ReadonlyArray<Route<any, any>>, EX = never, RX = never>(
@@ -542,7 +559,7 @@ export const addAll = <Routes extends ReadonlyArray<Route<any, any>>, EX = never
 /**
  * Layer that provides a newly constructed `HttpRouter`.
  *
- * @category HttpRouter
+ * @category layers
  * @since 4.0.0
  */
 export const layer: Layer.Layer<HttpRouter> = Layer.effect(HttpRouter)(make)
@@ -557,7 +574,7 @@ export const layer: Layer.Layer<HttpRouter> = Layer.effect(HttpRouter)(make)
  * `Scope`; route request markers are converted into the ordinary requirements of
  * the returned handler.
  *
- * @category HttpRouter
+ * @category converting
  * @since 4.0.0
  */
 export const toHttpEffect = <A, E, R>(
@@ -588,7 +605,7 @@ const RouteTypeId = "~effect/http/HttpRouter/Route"
  * A route pairs an HTTP method and path pattern with a response handler, plus
  * metadata used for prefix handling and interruptibility.
  *
- * @category Route
+ * @category routes
  * @since 4.0.0
  */
 export interface Route<E = never, R = never> {
@@ -610,7 +627,7 @@ export declare namespace Route {
   /**
    * Extracts the error type produced by a `Route` handler.
    *
-   * @category Route
+   * @category routes
    * @since 4.0.0
    */
   export type Error<R extends Route<any, any>> = R extends Route<infer E, infer _R> ? E : never
@@ -618,7 +635,7 @@ export declare namespace Route {
   /**
    * Extracts the context requirements of a `Route` handler.
    *
-   * @category Route
+   * @category routes
    * @since 4.0.0
    */
   export type Context<T extends Route<any, any>> = T extends Route<infer _E, infer R> ? R : never
@@ -646,7 +663,7 @@ const makeRoute = <E, R>(options: {
  * function from the current request to a response effect. Set `uninterruptible` to
  * prevent the route handler from being made interruptible while it runs.
  *
- * @category Route
+ * @category routes
  * @since 4.0.0
  */
 export const route = <E = never, R = never>(
@@ -676,7 +693,7 @@ export const route = <E = never, R = never>(
  * Path pattern accepted by the router. Routes must use an absolute path
  * beginning with `/` or the wildcard `*`.
  *
- * @category PathInput
+ * @category models
  * @since 4.0.0
  */
 export type PathInput = `/${string}` | "*"
@@ -693,7 +710,7 @@ const removeTrailingSlash = (
  * Trailing slashes are removed from the prefix; `/` becomes the prefix itself and
  * `*` becomes a wildcard route under the prefix.
  *
- * @category PathInput
+ * @category transforming
  * @since 4.0.0
  */
 export const prefixPath: {
@@ -705,7 +722,7 @@ export const prefixPath: {
    * Trailing slashes are removed from the prefix; `/` becomes the prefix itself and
    * `*` becomes a wildcard route under the prefix.
    *
-   * @category PathInput
+   * @category transforming
    * @since 4.0.0
    */
   (prefix: string): (self: string) => string
@@ -717,7 +734,7 @@ export const prefixPath: {
    * Trailing slashes are removed from the prefix; `/` becomes the prefix itself and
    * `*` becomes a wildcard route under the prefix.
    *
-   * @category PathInput
+   * @category transforming
    * @since 4.0.0
    */
   (self: string, prefix: string): string
@@ -737,7 +754,7 @@ export const prefixPath: {
  * request, the matched prefix can be removed from the request URL seen by the
  * handler.
  *
- * @category Route
+ * @category routes
  * @since 4.0.0
  */
 export const prefixRoute: {
@@ -750,7 +767,7 @@ export const prefixRoute: {
    * request, the matched prefix can be removed from the request URL seen by the
    * handler.
    *
-   * @category Route
+   * @category routes
    * @since 4.0.0
    */
   (prefix: string): <E, R>(self: Route<E, R>) => Route<E, R>
@@ -763,7 +780,7 @@ export const prefixRoute: {
    * request, the matched prefix can be removed from the request URL seen by the
    * handler.
    *
-   * @category Route
+   * @category routes
    * @since 4.0.0
    */
   <E, R>(self: Route<E, R>, prefix: string): Route<E, R>
@@ -781,7 +798,7 @@ export const prefixRoute: {
  * Represents a request-level dependency, that needs to be provided by
  * middleware.
  *
- * @category Request types
+ * @category utility types
  * @since 4.0.0
  */
 export interface Request<Kind extends string, T> {
@@ -800,7 +817,7 @@ export declare namespace Request {
   /**
    * Wraps a type in a request-level marker of the supplied kind.
    *
-   * @category Request types
+   * @category utility types
    * @since 4.0.0
    */
   export type From<Kind extends string, R> = R extends infer T ? Request<Kind, T> : never
@@ -809,7 +826,7 @@ export declare namespace Request {
    * Extracts the payload types from request-level markers that have the supplied
    * kind.
    *
-   * @category Request types
+   * @category utility types
    * @since 4.0.0
    */
   export type Only<Kind extends string, A> = A extends Request<Kind, infer T> ? T : never
@@ -818,7 +835,7 @@ export declare namespace Request {
    * Removes request-level markers from a union, leaving only ordinary requirement
    * or error types.
    *
-   * @category Request types
+   * @category utility types
    * @since 4.0.0
    */
   export type Without<A> = A extends Request<infer _Kind, infer _> ? never : A
@@ -828,7 +845,7 @@ export declare namespace Request {
  * Services provided by the HTTP router, which are available in the
  * request context.
  *
- * @category Request types
+ * @category utility types
  * @since 4.0.0
  */
 export type Provided =
@@ -840,7 +857,7 @@ export type Provided =
 /**
  * Services provided to global middleware.
  *
- * @category Request types
+ * @category utility types
  * @since 4.0.0
  */
 export type GlobalProvided =
@@ -913,50 +930,35 @@ export interface Middleware<
  *
  * **Example** (Applying route and global middleware)
  *
- * ```ts
- * import { Context, Effect, Layer } from "effect"
- * import { HttpMiddleware, HttpRouter, HttpServerResponse } from "effect/unstable/http"
- *
- * // Here we are defining a CORS middleware
- * const CorsMiddleware = HttpRouter.middleware(HttpMiddleware.cors()).layer
- * // You can also use HttpRouter.cors() to create a CORS middleware
- *
- * class CurrentSession extends Context.Service<CurrentSession, {
- *   readonly token: string
- * }>()("CurrentSession") {}
- *
- * // You can create middleware that provides a service to the HTTP requests.
- * const SessionMiddleware = HttpRouter.middleware<{
- *   provides: CurrentSession
- * }>()(
- *   Effect.gen(function*() {
- *     yield* Effect.log("SessionMiddleware initialized")
- *
- *     return (httpEffect) =>
- *       Effect.provideService(httpEffect, CurrentSession, {
- *         token: "dummy-token"
- *       })
- *   })
+ * ```ts import.meta.vitest
+ * import { Effect, Layer } from "effect"
+ * import { HttpRouter, HttpServerResponse } from "effect/unstable/http"
+ *
+ * const RouteMiddleware = HttpRouter.middleware((httpEffect) =>
+ *   Effect.map(httpEffect, HttpServerResponse.setHeader("x-route", "route"))
  * ).layer
  *
- * Effect.gen(function*() {
- *   const router = yield* HttpRouter.HttpRouter
- *   yield* router.add(
- *     "GET",
- *     "/hello",
+ * const GlobalMiddleware = HttpRouter.middleware(
+ *   (httpEffect) => Effect.map(httpEffect, HttpServerResponse.setHeader("x-global", "global")),
+ *   { global: true }
+ * )
+ *
+ * const Routes = HttpRouter.add("GET", "/hello", HttpServerResponse.text("Hello")).pipe(
+ *   Layer.provide(RouteMiddleware)
+ * )
+ * const App = Layer.mergeAll(Routes, GlobalMiddleware)
+ *
+ * const program = Effect.acquireUseRelease(
+ *   Effect.sync(() => HttpRouter.toWebHandler(App, { disableLogger: true })),
+ *   ({ handler }) =>
  *     Effect.gen(function*() {
- *       // Requests can now access the current session
- *       const session = yield* CurrentSession
- *       return HttpServerResponse.text(
- *         `Hello, World! Your token is ${session.token}`
- *       )
- *     })
- *   )
- * }).pipe(
- *   Layer.effectDiscard,
- *   // Provide the SessionMiddleware & CorsMiddleware to some routes
- *   Layer.provide([SessionMiddleware, CorsMiddleware])
+ *       const response = yield* Effect.promise(() => handler(new Request("http://localhost/hello")))
+ *       return [response.headers.get("x-route"), response.headers.get("x-global")]
+ *     }),
+ *   ({ dispose }) => Effect.promise(dispose)
  * )
+ *
+ * await Effect.runPromise(program) // => ["route", "global"]
  * ```
  *
  * @category middleware
@@ -1193,7 +1195,7 @@ export declare namespace middleware {
 /**
  * Middleware that applies CORS headers to the HTTP response.
  *
- * @category middleware
+ * @category layers
  * @since 4.0.0
  */
 export const cors = (
@@ -1212,21 +1214,22 @@ export const cors = (
  *
  * **Example** (Disabling route logging)
  *
- * ```ts
- * import { Effect, Layer } from "effect"
+ * ```ts import.meta.vitest
+ * import { Layer } from "effect"
  * import { HttpRouter, HttpServerResponse } from "effect/unstable/http"
  *
  * const Route = HttpRouter.add(
  *   "GET",
  *   "/hello",
- *   Effect.succeed(HttpServerResponse.text("Hello, World!"))
+ *   HttpServerResponse.text("Hello, World!")
  * ).pipe(
  *   // disable the logger for this route
  *   Layer.provide(HttpRouter.disableLogger)
  * )
+ * Layer.isLayer(Route) // => true
  * ```
  *
- * @category middleware
+ * @category layers
  * @since 4.0.0
  */
 export const disableLogger: Layer.Layer<never> = middleware(HttpMiddleware.withLoggerDisabled).layer
@@ -1234,7 +1237,7 @@ export const disableLogger: Layer.Layer<never> = middleware(HttpMiddleware.withL
 /**
  * Provides request-level dependencies to some routes.
  *
- * @category middleware
+ * @category layers
  * @since 4.0.0
  */
 export const provideRequest =
@@ -1259,7 +1262,7 @@ export const provideRequest =
 /**
  * Runs the provided application layer as an HTTP server.
  *
- * @category server
+ * @category layers
  * @since 4.0.0
  */
 export const serve = <A, E, R, HE, HR = Request.Only<"Requires", R> | Request.Only<"GlobalRequires", R>>(
@@ -1323,7 +1326,7 @@ export const serve = <A, E, R, HE, HR = Request.Only<"Requires", R> | Request.On
  * Web `Response` values and a `dispose` function for releasing the layer
  * resources.
  *
- * @category server
+ * @category converting
  * @since 4.0.0
  */
 export const toWebHandler = <
@@ -1336,7 +1339,8 @@ export const toWebHandler = <
     | Request<"Error", any>
     | Request<"GlobalError", any>,
   HE,
-  HR = Exclude<Request.Only<"Requires", R> | Request.Only<"GlobalRequires", R>, A>
+  HR = Exclude<Request.Only<"Requires", R> | Request.Only<"GlobalRequires", R>, A>,
+  ReqR = Exclude<HR, A | Scope.Scope | HttpServerRequest.HttpServerRequest>
 >(
   appLayer: Layer.Layer<A, E, R>,
   options?: {
@@ -1365,11 +1369,11 @@ export const toWebHandler = <
     ) => Effect.Effect<HttpServerResponse.HttpServerResponse, HE, HR | GlobalProvided>
   }
 ): {
-  readonly handler: [Exclude<HR, GlobalProvided>] extends [never]
+  readonly handler: [ReqR] extends [never]
     ? ((request: globalThis.Request, context?: Context.Context<never> | undefined) => Promise<Response>)
     : ((
       request: globalThis.Request,
-      context: Context.Context<Exclude<HR, GlobalProvided>>
+      context: Context.Context<ReqR>
     ) => Promise<Response>)
   readonly dispose: () => Promise<void>
 } => {

package/src/unstable/http/HttpServer.ts

@@ -32,7 +32,7 @@ import type { HttpServerResponse } from "./HttpServerResponse.ts"
  * The service can serve an HTTP response effect and exposes the address where the
  * server is listening.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export class HttpServer extends Context.Service<HttpServer, {
@@ -62,7 +62,7 @@ export class HttpServer extends Context.Service<HttpServer, {
  *
  * The address is either a TCP host and port or a Unix domain socket path.
  *
- * @category address
+ * @category models
  * @since 4.0.0
  */
 export type Address = UnixAddress | TcpAddress
@@ -70,7 +70,7 @@ export type Address = UnixAddress | TcpAddress
 /**
  * TCP address for an HTTP server, identified by hostname and port.
  *
- * @category address
+ * @category models
  * @since 4.0.0
  */
 export interface TcpAddress {
@@ -82,7 +82,7 @@ export interface TcpAddress {
 /**
  * Unix domain socket address for an HTTP server.
  *
- * @category address
+ * @category models
  * @since 4.0.0
  */
 export interface UnixAddress {
@@ -117,7 +117,7 @@ export const make = (
  * layer still requires the server, a scope, and any non-request dependencies of
  * the response effect or middleware.
  *
- * @category accessors
+ * @category layers
  * @since 4.0.0
  */
 export const serve: {
@@ -131,7 +131,7 @@ export const serve: {
    * layer still requires the server, a scope, and any non-request dependencies of
    * the response effect or middleware.
    *
-   * @category accessors
+   * @category layers
    * @since 4.0.0
    */
   (): <E, R>(
@@ -147,7 +147,7 @@ export const serve: {
    * layer still requires the server, a scope, and any non-request dependencies of
    * the response effect or middleware.
    *
-   * @category accessors
+   * @category layers
    * @since 4.0.0
    */
   <E, R, App extends Effect.Effect<HttpServerResponse, any, any>>(middleware: Middleware.HttpMiddleware.Applied<App, E, R>): (
@@ -167,7 +167,7 @@ export const serve: {
    * layer still requires the server, a scope, and any non-request dependencies of
    * the response effect or middleware.
    *
-   * @category accessors
+   * @category layers
    * @since 4.0.0
    */
   <E, R>(effect: Effect.Effect<HttpServerResponse, E, R>): Layer.Layer<never, never, HttpServer | Exclude<R, HttpServerRequest | Scope.Scope>>
@@ -181,7 +181,7 @@ export const serve: {
    * layer still requires the server, a scope, and any non-request dependencies of
    * the response effect or middleware.
    *
-   * @category accessors
+   * @category layers
    * @since 4.0.0
    */
   <E, R, App extends Effect.Effect<HttpServerResponse, any, any>>(
@@ -306,7 +306,7 @@ export const serveEffect: {
  * TCP addresses are formatted as `http://host:port`; Unix socket addresses are
  * formatted as `unix://path`.
  *
- * @category address
+ * @category converting
  * @since 4.0.0
  */
 export const formatAddress = (address: Address): string => {
@@ -322,7 +322,7 @@ export const formatAddress = (address: Address): string => {
  * Reads the current server address, formats it with `formatAddress`, and passes
  * the formatted address to the supplied effectful function.
  *
- * @category address
+ * @category accessors
  * @since 4.0.0
  */
 export const addressFormattedWith = <A, E, R>(
@@ -336,7 +336,7 @@ export const addressFormattedWith = <A, E, R>(
 /**
  * Logs the formatted address of the current HTTP server.
  *
- * @category address
+ * @category logging
  * @since 4.0.0
  */
 export const logAddress: Effect.Effect<void, never, HttpServer> = addressFormattedWith((_) =>
@@ -346,7 +346,7 @@ export const logAddress: Effect.Effect<void, never, HttpServer> = addressFormatt
 /**
  * Adds address logging to a layer that provides an `HttpServer`.
  *
- * @category address
+ * @category layers
  * @since 4.0.0
  */
 export const withLogAddress = <A, E, R>(

package/src/unstable/http/HttpServerError.ts

@@ -178,7 +178,7 @@ export class InternalError extends Data.TaggedError("InternalError")<{
 /**
  * Returns `true` when the supplied value is an `HttpServerError`.
  *
- * @category predicates
+ * @category guards
  * @since 4.0.0
  */
 export const isHttpServerError = (u: unknown): u is HttpServerError => hasProperty(u, TypeId)
@@ -249,7 +249,7 @@ export class ServeError extends Data.TaggedError("ServeError")<{
  * `causeResponse` uses this annotation to map a pure client abort to a `499`
  * response instead of a server abort response.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export class ClientAbort extends Context.Service<ClientAbort, true>()("effect/http/HttpServerError/ClientAbort") {

package/src/unstable/http/HttpServerRequest.ts

@@ -45,7 +45,7 @@ export {
    * Use to configure the maximum body size accepted while reading server
    * request bodies.
    *
-   * @category fiber refs
+   * @category references
    * @since 4.0.0
    */
   MaxBodySize
@@ -105,7 +105,7 @@ export interface HttpServerRequest extends HttpIncomingMessage.HttpIncomingMessa
  * Use to access the request currently being handled by HTTP server routes and
  * middleware.
  *
- * @category context
+ * @category services
  * @since 4.0.0
  */
 export const HttpServerRequest: Context.Service<HttpServerRequest, HttpServerRequest> = Context.Service(
@@ -125,7 +125,7 @@ export const HttpServerRequest: Context.Service<HttpServerRequest, HttpServerReq
  * Each key maps to a string value, or to an array when the parameter appears more
  * than once.
  *
- * @category search params
+ * @category services
  * @since 4.0.0
  */
 export class ParsedSearchParams extends Context.Service<
@@ -140,7 +140,7 @@ export class ParsedSearchParams extends Context.Service<
  *
  * Repeated parameters are represented as arrays in insertion order.
  *
- * @category search params
+ * @category parsing
  * @since 4.0.0
  */
 export const searchParamsFromURL = (url: URL): ReadonlyRecord<string, string | Array<string>> => {