effect 4.0.0-beta.99 → 4.0.0-rc.108

package/src/unstable/httpapi/HttpApiError.ts

@@ -1,7 +1,7 @@
 /**
  * Built-in error schemas for common HTTP API failure responses.
  *
- * This module provides reusable `Schema.ErrorClass` values for common HTTP
+ * This module provides reusable `Schema.Error` values for common HTTP
  * status codes, plus `HttpApiSchemaError` for request decoding failures raised
  * by the HTTP API runtime. The status errors can be used in endpoint or
  * middleware error declarations and are understood by builders, generated
@@ -39,7 +39,7 @@ const serviceUnavailableResponse = HttpServerResponse.empty({ status: 503 })
  * @category errors
  * @since 4.0.0
  */
-export class BadRequest extends Schema.ErrorClass<BadRequest>("effect/HttpApiError/BadRequest")({
+export class BadRequest extends Schema.Error<BadRequest>("effect/HttpApiError/BadRequest")({
   _tag: Schema.tag("BadRequest")
 }, {
   description: "BadRequest",
@@ -56,7 +56,7 @@ export class BadRequest extends Schema.ErrorClass<BadRequest>("effect/HttpApiErr
  * No-content schema variant for `BadRequest`, decoding an empty 400 response into
  * a `BadRequest` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const BadRequestNoContent = BadRequest.pipe(HttpApiSchema.asNoContent({
@@ -70,7 +70,7 @@ export const BadRequestNoContent = BadRequest.pipe(HttpApiSchema.asNoContent({
  * @category errors
  * @since 4.0.0
  */
-export class Unauthorized extends Schema.ErrorClass<Unauthorized>("effect/HttpApiError/Unauthorized")({
+export class Unauthorized extends Schema.Error<Unauthorized>("effect/HttpApiError/Unauthorized")({
   _tag: Schema.tag("Unauthorized")
 }, {
   description: "Unauthorized",
@@ -86,7 +86,7 @@ export class Unauthorized extends Schema.ErrorClass<Unauthorized>("effect/HttpAp
  * No-content schema variant for `Unauthorized`, decoding an empty 401 response
  * into an `Unauthorized` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const UnauthorizedNoContent = Unauthorized.pipe(HttpApiSchema.asNoContent({
@@ -100,7 +100,7 @@ export const UnauthorizedNoContent = Unauthorized.pipe(HttpApiSchema.asNoContent
  * @category errors
  * @since 4.0.0
  */
-export class Forbidden extends Schema.ErrorClass<Forbidden>("effect/HttpApiError/Forbidden")({
+export class Forbidden extends Schema.Error<Forbidden>("effect/HttpApiError/Forbidden")({
   _tag: Schema.tag("Forbidden")
 }, {
   description: "Forbidden",
@@ -116,7 +116,7 @@ export class Forbidden extends Schema.ErrorClass<Forbidden>("effect/HttpApiError
  * No-content schema variant for `Forbidden`, decoding an empty 403 response into a
  * `Forbidden` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const ForbiddenNoContent = Forbidden.pipe(HttpApiSchema.asNoContent({
@@ -130,7 +130,7 @@ export const ForbiddenNoContent = Forbidden.pipe(HttpApiSchema.asNoContent({
  * @category errors
  * @since 4.0.0
  */
-export class NotFound extends Schema.ErrorClass<NotFound>("effect/HttpApiError/NotFound")({
+export class NotFound extends Schema.Error<NotFound>("effect/HttpApiError/NotFound")({
   _tag: Schema.tag("NotFound")
 }, {
   description: "NotFound",
@@ -146,7 +146,7 @@ export class NotFound extends Schema.ErrorClass<NotFound>("effect/HttpApiError/N
  * No-content schema variant for `NotFound`, decoding an empty 404 response into a
  * `NotFound` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const NotFoundNoContent = NotFound.pipe(HttpApiSchema.asNoContent({
@@ -160,7 +160,7 @@ export const NotFoundNoContent = NotFound.pipe(HttpApiSchema.asNoContent({
  * @category errors
  * @since 4.0.0
  */
-export class MethodNotAllowed extends Schema.ErrorClass<MethodNotAllowed>("effect/HttpApiError/MethodNotAllowed")({
+export class MethodNotAllowed extends Schema.Error<MethodNotAllowed>("effect/HttpApiError/MethodNotAllowed")({
   _tag: Schema.tag("MethodNotAllowed")
 }, {
   description: "MethodNotAllowed",
@@ -176,7 +176,7 @@ export class MethodNotAllowed extends Schema.ErrorClass<MethodNotAllowed>("effec
  * No-content schema variant for `MethodNotAllowed`, decoding an empty 405 response
  * into a `MethodNotAllowed` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const MethodNotAllowedNoContent = MethodNotAllowed.pipe(HttpApiSchema.asNoContent({
@@ -190,7 +190,7 @@ export const MethodNotAllowedNoContent = MethodNotAllowed.pipe(HttpApiSchema.asN
  * @category errors
  * @since 4.0.0
  */
-export class NotAcceptable extends Schema.ErrorClass<NotAcceptable>("effect/HttpApiError/NotAcceptable")({
+export class NotAcceptable extends Schema.Error<NotAcceptable>("effect/HttpApiError/NotAcceptable")({
   _tag: Schema.tag("NotAcceptable")
 }, {
   description: "NotAcceptable",
@@ -206,7 +206,7 @@ export class NotAcceptable extends Schema.ErrorClass<NotAcceptable>("effect/Http
  * No-content schema variant for `NotAcceptable`, decoding an empty 406 response
  * into a `NotAcceptable` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const NotAcceptableNoContent = NotAcceptable.pipe(HttpApiSchema.asNoContent({
@@ -220,7 +220,7 @@ export const NotAcceptableNoContent = NotAcceptable.pipe(HttpApiSchema.asNoConte
  * @category errors
  * @since 4.0.0
  */
-export class RequestTimeout extends Schema.ErrorClass<RequestTimeout>("effect/HttpApiError/RequestTimeout")({
+export class RequestTimeout extends Schema.Error<RequestTimeout>("effect/HttpApiError/RequestTimeout")({
   _tag: Schema.tag("RequestTimeout")
 }, {
   description: "RequestTimeout",
@@ -236,7 +236,7 @@ export class RequestTimeout extends Schema.ErrorClass<RequestTimeout>("effect/Ht
  * No-content schema variant for `RequestTimeout`, decoding an empty 408 response
  * into a `RequestTimeout` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const RequestTimeoutNoContent = RequestTimeout.pipe(HttpApiSchema.asNoContent({
@@ -250,7 +250,7 @@ export const RequestTimeoutNoContent = RequestTimeout.pipe(HttpApiSchema.asNoCon
  * @category errors
  * @since 4.0.0
  */
-export class Conflict extends Schema.ErrorClass<Conflict>("effect/HttpApiError/Conflict")({
+export class Conflict extends Schema.Error<Conflict>("effect/HttpApiError/Conflict")({
   _tag: Schema.tag("Conflict")
 }, {
   description: "Conflict",
@@ -266,7 +266,7 @@ export class Conflict extends Schema.ErrorClass<Conflict>("effect/HttpApiError/C
  * No-content schema variant for `Conflict`, decoding an empty 409 response into a
  * `Conflict` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const ConflictNoContent = Conflict.pipe(HttpApiSchema.asNoContent({
@@ -280,7 +280,7 @@ export const ConflictNoContent = Conflict.pipe(HttpApiSchema.asNoContent({
  * @category errors
  * @since 4.0.0
  */
-export class Gone extends Schema.ErrorClass<Gone>("effect/HttpApiError/Gone")({
+export class Gone extends Schema.Error<Gone>("effect/HttpApiError/Gone")({
   _tag: Schema.tag("Gone")
 }, {
   description: "Gone",
@@ -296,7 +296,7 @@ export class Gone extends Schema.ErrorClass<Gone>("effect/HttpApiError/Gone")({
  * No-content schema variant for `Gone`, decoding an empty 410 response into a
  * `Gone` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const GoneNoContent = Gone.pipe(HttpApiSchema.asNoContent({
@@ -310,14 +310,12 @@ export const GoneNoContent = Gone.pipe(HttpApiSchema.asNoContent({
  * @category errors
  * @since 4.0.0
  */
-export class UnprocessableEntity
-  extends Schema.ErrorClass<UnprocessableEntity>("effect/HttpApiError/UnprocessableEntity")({
-    _tag: Schema.tag("UnprocessableEntity")
-  }, {
-    description: "UnprocessableEntity",
-    httpApiStatus: 422
-  })
-{
+export class UnprocessableEntity extends Schema.Error<UnprocessableEntity>("effect/HttpApiError/UnprocessableEntity")({
+  _tag: Schema.tag("UnprocessableEntity")
+}, {
+  description: "UnprocessableEntity",
+  httpApiStatus: 422
+}) {
   override readonly [ErrorReporter.ignore] = true;
   [HttpServerRespondable.symbol]() {
     return Effect.succeed(unprocessableEntityResponse)
@@ -328,7 +326,7 @@ export class UnprocessableEntity
  * No-content schema variant for `UnprocessableEntity`, decoding an empty 422
  * response into an `UnprocessableEntity` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const UnprocessableEntityNoContent = UnprocessableEntity.pipe(HttpApiSchema.asNoContent({
@@ -342,14 +340,12 @@ export const UnprocessableEntityNoContent = UnprocessableEntity.pipe(HttpApiSche
  * @category errors
  * @since 4.0.0
  */
-export class InternalServerError
-  extends Schema.ErrorClass<InternalServerError>("effect/HttpApiError/InternalServerError")({
-    _tag: Schema.tag("InternalServerError")
-  }, {
-    description: "InternalServerError",
-    httpApiStatus: 500
-  })
-{
+export class InternalServerError extends Schema.Error<InternalServerError>("effect/HttpApiError/InternalServerError")({
+  _tag: Schema.tag("InternalServerError")
+}, {
+  description: "InternalServerError",
+  httpApiStatus: 500
+}) {
   [HttpServerRespondable.symbol]() {
     return Effect.succeed(internalServerErrorResponse)
   }
@@ -359,7 +355,7 @@ export class InternalServerError
  * No-content schema variant for `InternalServerError`, decoding an empty 500
  * response into an `InternalServerError` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const InternalServerErrorNoContent = InternalServerError.pipe(HttpApiSchema.asNoContent({
@@ -373,7 +369,7 @@ export const InternalServerErrorNoContent = InternalServerError.pipe(HttpApiSche
  * @category errors
  * @since 4.0.0
  */
-export class NotImplemented extends Schema.ErrorClass<NotImplemented>("effect/HttpApiError/NotImplemented")({
+export class NotImplemented extends Schema.Error<NotImplemented>("effect/HttpApiError/NotImplemented")({
   _tag: Schema.tag("NotImplemented")
 }, {
   description: "NotImplemented",
@@ -388,7 +384,7 @@ export class NotImplemented extends Schema.ErrorClass<NotImplemented>("effect/Ht
  * No-content schema variant for `NotImplemented`, decoding an empty 501 response
  * into a `NotImplemented` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const NotImplementedNoContent = NotImplemented.pipe(HttpApiSchema.asNoContent({
@@ -402,14 +398,12 @@ export const NotImplementedNoContent = NotImplemented.pipe(HttpApiSchema.asNoCon
  * @category errors
  * @since 4.0.0
  */
-export class ServiceUnavailable
-  extends Schema.ErrorClass<ServiceUnavailable>("effect/HttpApiError/ServiceUnavailable")({
-    _tag: Schema.tag("ServiceUnavailable")
-  }, {
-    description: "ServiceUnavailable",
-    httpApiStatus: 503
-  })
-{
+export class ServiceUnavailable extends Schema.Error<ServiceUnavailable>("effect/HttpApiError/ServiceUnavailable")({
+  _tag: Schema.tag("ServiceUnavailable")
+}, {
+  description: "ServiceUnavailable",
+  httpApiStatus: 503
+}) {
   [HttpServerRespondable.symbol]() {
     return Effect.succeed(serviceUnavailableResponse)
   }
@@ -419,7 +413,7 @@ export class ServiceUnavailable
  * No-content schema variant for `ServiceUnavailable`, decoding an empty 503
  * response into a `ServiceUnavailable` error value.
  *
- * @category NoContent errors
+ * @category schemas
  * @since 4.0.0
  */
 export const ServiceUnavailableNoContent = ServiceUnavailable.pipe(HttpApiSchema.asNoContent({
@@ -443,15 +437,15 @@ export type HttpApiSchemaErrorTypeId = "~effect/httpapi/HttpApiError/HttpApiSche
 export const HttpApiSchemaErrorTypeId: HttpApiSchemaErrorTypeId = "~effect/httpapi/HttpApiError/HttpApiSchemaError"
 
 /**
- * Error raised when an HTTP API request component fails schema decoding. It records
- * which component failed and responds as an empty `400 Bad Request` when rendered
- * as a server response.
+ * Error raised when an HTTP API request or response component fails schema
+ * decoding or encoding. It records which component failed and responds as an
+ * empty `400 Bad Request` when rendered as a server response.
  *
  * @category errors
  * @since 4.0.0
  */
 export class HttpApiSchemaError extends Data.TaggedClass("HttpApiSchemaError")<{
-  readonly kind: "Params" | "Headers" | "Query" | "Body" | "Payload"
+  readonly kind: "Params" | "Headers" | "Query" | "Body" | "Payload" | "ResponseHeaders"
   readonly cause: Schema.SchemaError
 }> {
   readonly [HttpApiSchemaErrorTypeId]: HttpApiSchemaErrorTypeId = HttpApiSchemaErrorTypeId

package/src/unstable/httpapi/HttpApiGroup.ts

@@ -12,7 +12,7 @@
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
 import * as Context from "../../Context.ts"
-import * as internalRecord from "../../internal/record.ts"
+import * as InternalRecord from "../../internal/record.ts"
 import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Record from "../../Record.ts"
@@ -136,7 +136,7 @@ export interface HttpApiGroup<
  * id and the group identifier so the relationship between an API and its
  * implemented groups is checked at compile time.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface Service<ApiId extends string, Identifier extends string> {
@@ -154,7 +154,7 @@ export interface Service<ApiId extends string, Identifier extends string> {
  * When given an API id and a group or union of groups, this type maps each group
  * to the `Service` identity that must be provided by `HttpApiBuilder.group`.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ToService<ApiId extends string, Group extends Constraint> = Group extends Constraint ?
@@ -187,7 +187,7 @@ export interface Top extends HttpApiGroup<string, HttpApiEndpoint.Top, boolean>
 /**
  * Selects the group with the specified identifier from a union of groups.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type WithIdentifier<Group, Identifier extends string> = Extract<Group, { readonly identifier: Identifier }>
@@ -195,7 +195,7 @@ export type WithIdentifier<Group, Identifier extends string> = Extract<Group, {
 /**
  * Extracts the identifier literal from an `HttpApiGroup`.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Identifier<Group> = Group extends Constraint ? Group["identifier"] : never
@@ -203,7 +203,7 @@ export type Identifier<Group> = Group extends Constraint ? Group["identifier"] :
 /**
  * Extracts the endpoint union contained in an `HttpApiGroup`.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Endpoints<Group> = Group extends HttpApiGroup<infer _Identifier, infer _Endpoints, infer _TopLevel> ?
@@ -214,7 +214,7 @@ export type Endpoints<Group> = Group extends HttpApiGroup<infer _Identifier, inf
  * Computes the services required to encode error responses for every endpoint in a
  * group.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorServicesEncode<Group> = HttpApiEndpoint.ErrorServicesEncode<Endpoints<Group>>
@@ -223,7 +223,7 @@ export type ErrorServicesEncode<Group> = HttpApiEndpoint.ErrorServicesEncode<End
  * Computes the services required to decode error responses for every endpoint in a
  * group.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorServicesDecode<Group> = HttpApiEndpoint.ErrorServicesDecode<Endpoints<Group>>
@@ -231,7 +231,7 @@ export type ErrorServicesDecode<Group> = HttpApiEndpoint.ErrorServicesDecode<End
 /**
  * Computes the middleware error union for every endpoint in a group.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareError<Group> = HttpApiEndpoint.MiddlewareError<Endpoints<Group>>
@@ -240,7 +240,7 @@ export type MiddlewareError<Group> = HttpApiEndpoint.MiddlewareError<Endpoints<G
  * Computes the services provided by middleware attached to any endpoint in a
  * group.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareProvides<Group> = HttpApiEndpoint.MiddlewareProvides<Endpoints<Group>>
@@ -248,7 +248,7 @@ export type MiddlewareProvides<Group> = HttpApiEndpoint.MiddlewareProvides<Endpo
 /**
  * Computes the client-side middleware services required by endpoints in a group.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareClient<Group> = HttpApiEndpoint.MiddlewareClient<Endpoints<Group>>
@@ -256,7 +256,7 @@ export type MiddlewareClient<Group> = HttpApiEndpoint.MiddlewareClient<Endpoints
 /**
  * Extracts the runtime services required by middleware attached to the endpoints in an `HttpApiGroup`.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareServices<Group> = HttpApiEndpoint.MiddlewareServices<Endpoints<Group>>
@@ -264,7 +264,7 @@ export type MiddlewareServices<Group> = HttpApiEndpoint.MiddlewareServices<Endpo
 /**
  * Extracts the endpoint union from the group with the specified identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type EndpointsWithIdentifier<Group extends Constraint, Identifier extends string> = Endpoints<
@@ -274,7 +274,7 @@ export type EndpointsWithIdentifier<Group extends Constraint, Identifier extends
 /**
  * Computes the schema encoding and decoding services required by clients for all endpoints in a group.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ClientServices<Group> = Group extends HttpApiGroup<infer _Identifier, infer _Endpoints, infer _TopLevel> ?
@@ -284,7 +284,7 @@ export type ClientServices<Group> = Group extends HttpApiGroup<infer _Identifier
 /**
  * Returns the type of a group after adding the supplied path prefix to each endpoint in the group.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type AddPrefix<Group, Prefix extends PathInput> = Group extends
@@ -295,7 +295,7 @@ export type AddPrefix<Group, Prefix extends PathInput> = Group extends
 /**
  * Returns the type of a group after applying a middleware identifier to every endpoint in the group.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type AddMiddleware<Group, Id extends HttpApiMiddleware.AnyId> = Group extends
@@ -308,7 +308,7 @@ const Proto = {
   add(this: Top, ...toAdd: NonEmptyReadonlyArray<HttpApiEndpoint.Top>) {
     const endpoints = { ...this.endpoints }
     for (const endpoint of toAdd) {
-      internalRecord.set(endpoints, endpoint.identifier, endpoint)
+      InternalRecord.assignProperty(endpoints, endpoint.identifier, endpoint)
     }
     return makeProto({
       ...optionsFromGroup(this),

package/src/unstable/httpapi/HttpApiMiddleware.ts

@@ -125,7 +125,7 @@ export interface HttpApiMiddlewareClient<_E, CE, R> {
 /**
  * Client-side service marker required when a middleware declares `requiredForClient`.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export interface ForClient<Id> {
@@ -136,7 +136,7 @@ export interface ForClient<Id> {
 /**
  * Base service key shape for HTTP API middleware services, including provided services, declared error schemas, and client requirements.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface AnyService extends Context.Key<any, any> {
@@ -150,7 +150,7 @@ export interface AnyService extends Context.Key<any, any> {
 /**
  * Middleware service key shape for security middleware, including the security schemes handled by the service.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface AnyServiceSecurity extends AnyService {
@@ -161,7 +161,7 @@ export interface AnyServiceSecurity extends AnyService {
 /**
  * Type-level identifier carried by middleware services to track provided services, required services, errors, client errors, and client requirements.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export interface AnyId {
@@ -177,7 +177,7 @@ export interface AnyId {
 /**
  * Extracts the services provided by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Provides<A> = A extends { readonly [TypeId]: { readonly provides: infer P } } ? P : never
@@ -185,7 +185,7 @@ export type Provides<A> = A extends { readonly [TypeId]: { readonly provides: in
 /**
  * Extracts the services required to run a middleware implementation.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Requires<A> = A extends { readonly [TypeId]: { readonly requires: infer R } } ? R : never
@@ -193,7 +193,7 @@ export type Requires<A> = A extends { readonly [TypeId]: { readonly requires: in
 /**
  * Applies a middleware's service changes to an existing requirement type by removing services it provides and adding services it requires.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ApplyServices<A extends AnyId, R> = Exclude<R, Provides<A>> | Requires<A>
@@ -201,7 +201,7 @@ export type ApplyServices<A extends AnyId, R> = Exclude<R, Provides<A>> | Requir
 /**
  * Extracts the schema or schema union used for errors declared by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorSchema<A> = A extends { readonly [TypeId]: { readonly error: infer E } } ? ErrorSchemaFromConstraint<E>
@@ -210,7 +210,7 @@ export type ErrorSchema<A> = A extends { readonly [TypeId]: { readonly error: in
 /**
  * Extracts the decoded error type declared by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type Error<A> = ErrorSchema<A>["Type"]
@@ -218,7 +218,7 @@ export type Error<A> = ErrorSchema<A>["Type"]
 /**
  * Extracts the client-side error type for middleware that is required on generated clients.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ClientError<A> = A extends {
@@ -232,7 +232,7 @@ export type ClientError<A> = A extends {
 /**
  * Computes the client-side service marker required for middleware that must also run in generated clients.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type MiddlewareClient<A> = A extends {
@@ -245,7 +245,7 @@ export type MiddlewareClient<A> = A extends {
 /**
  * Extracts the schema services required to encode errors declared by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorServicesEncode<A> = ErrorSchema<A>["EncodingServices"]
@@ -253,7 +253,7 @@ export type ErrorServicesEncode<A> = ErrorSchema<A>["EncodingServices"]
 /**
  * Extracts the schema services required to decode errors declared by a middleware identifier.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type ErrorServicesDecode<A> = ErrorSchema<A>["DecodingServices"]
@@ -266,7 +266,7 @@ export type ErrorServicesDecode<A> = ErrorSchema<A>["DecodingServices"]
  * It combines a `Context.Service` class with the middleware metadata used by
  * endpoints, builders, and generated clients.
  *
- * @category schemas
+ * @category services
  * @since 4.0.0
  */
 export type ServiceClass<
@@ -314,7 +314,7 @@ export type ServiceClass<
  * required services, provided services, typed error schemas, security schemes,
  * client errors, or a matching client middleware requirement.
  *
- * @category schemas
+ * @category constructors
  * @since 4.0.0
  */
 export const Service = <
@@ -394,26 +394,73 @@ function getError(error: ErrorConstraint | undefined): ReadonlySet<Schema.Top> {
  *
  * **Example** (Mapping schema errors to custom errors)
  *
- * ```ts
- * import { Effect, Schema } from "effect"
- * import { HttpApiMiddleware } from "effect/unstable/httpapi"
+ * ```ts import.meta.vitest
+ * import { Effect, Schema, type Types } from "effect"
+ * import { HttpRouter, HttpServerResponse } from "effect/unstable/http"
+ * import {
+ *   HttpApiEndpoint,
+ *   HttpApiError,
+ *   HttpApiGroup,
+ *   HttpApiMiddleware
+ * } from "effect/unstable/httpapi"
  *
- * export class CustomError extends Schema.TaggedErrorClass<CustomError>()("CustomError", {}) {}
+ * class CustomError extends Schema.TaggedError<CustomError>()("CustomError", {}) {}
  *
- * export class ErrorHandler extends HttpApiMiddleware.Service<ErrorHandler>()("api/ErrorHandler", {
+ * class ErrorHandler extends HttpApiMiddleware.Service<ErrorHandler>()("api/ErrorHandler", {
  *   error: CustomError
  * }) {}
  *
- * export const ErrorHandlerLayer = HttpApiMiddleware.layerSchemaErrorTransform(
+ * const messages: Array<string> = []
+ * const ErrorHandlerLayer = HttpApiMiddleware.layerSchemaErrorTransform(
  *   ErrorHandler,
  *   (schemaError) =>
- *     Effect.log("Got SchemaError", schemaError).pipe(
+ *     Effect.sync(() => messages.push(`Mapping ${schemaError.kind} schema error`)).pipe(
  *       Effect.andThen(Effect.fail(new CustomError()))
  *     )
  * )
+ *
+ * const endpoint = HttpApiEndpoint.get("example", "/")
+ * const group = HttpApiGroup.make("examples").add(endpoint)
+ * const middlewareContext = {
+ *   endpoint: endpoint as unknown as HttpApiEndpoint.Top,
+ *   group: group as unknown as HttpApiGroup.Top
+ * }
+ * const Routes = HttpRouter.add(
+ *   "GET",
+ *   "/",
+ *   Effect.gen(function*() {
+ *     const applySchemaErrorTransform = yield* ErrorHandler
+ *     const schemaError = yield* HttpApiError.HttpApiSchemaError.wrap(
+ *       "Body",
+ *       Schema.decodeUnknownEffect(Schema.String)(42)
+ *     ).pipe(Effect.flip)
+ *     const failingResponse = Effect.fail(schemaError as unknown as Types.unhandled)
+ *     const result = yield* applySchemaErrorTransform(failingResponse, middlewareContext).pipe(
+ *       Effect.match({
+ *         onFailure: (error) => error instanceof CustomError ? error._tag : "UnexpectedError",
+ *         onSuccess: () => "Success"
+ *       })
+ *     )
+ *     return HttpServerResponse.text(result)
+ *   })
+ * ).pipe(HttpRouter.provideRequest(ErrorHandlerLayer))
+ *
+ * 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/")))
+ *       const body = yield* Effect.promise(() => response.text())
+ *       return body
+ *     }),
+ *   ({ dispose }) => Effect.promise(dispose)
+ * )
+ *
+ * const body = await Effect.runPromise(program)
+ * const result = [messages, body] // => [["Mapping Body schema error"], "CustomError"]
  * ```
  *
- * @category SchemaError transform
+ * @category layers
  * @since 4.0.0
  */
 export const layerSchemaErrorTransform = <Id, E extends ErrorConstraint, Requires>(
@@ -451,7 +498,7 @@ export const layerSchemaErrorTransform = <Id, E extends ErrorConstraint, Require
  * The layer captures the surrounding services and makes the middleware available
  * through the `ForClient` service marker used by HTTP API clients.
  *
- * @category client
+ * @category layers
  * @since 4.0.0
  */
 export const layerClient = <Id extends AnyId, S, R, EX = never, RX = never>(