effect 4.0.0-beta.103 → 4.0.0-beta.104

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",
@@ -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",
@@ -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",
@@ -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",
@@ -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",
@@ -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",
@@ -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",
@@ -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",
@@ -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",
@@ -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)
@@ -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)
   }
@@ -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",
@@ -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)
   }
@@ -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/HttpApiMiddleware.ts

@@ -404,7 +404,7 @@ function getError(error: ErrorConstraint | undefined): ReadonlySet<Schema.Top> {
  *   HttpApiMiddleware
  * } from "effect/unstable/httpapi"
  *
- * class CustomError extends Schema.TaggedErrorClass<CustomError>()("CustomError", {}) {}
+ * class CustomError extends Schema.TaggedError<CustomError>()("CustomError", {}) {}
  *
  * class ErrorHandler extends HttpApiMiddleware.Service<ErrorHandler>()("api/ErrorHandler", {
  *   error: CustomError

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -29,10 +29,27 @@ declare module "../../Schema.ts" {
        * @internal
        */
       readonly "~httpApiEncoding"?: Encoding | undefined
+      /**
+       * Marks schemas produced by `encodeToWithHeaders`, carrying the body and
+       * headers schemas so integrations can split the encoded pair.
+       * @internal
+       */
+      readonly "~httpApiWithHeaders"?: WithHeadersAnnotation | undefined
     }
   }
 }
 
+/**
+ * Annotation payload attached by `encodeToWithHeaders`.
+ *
+ * @internal
+ */
+export interface WithHeadersAnnotation {
+  readonly body: Schema.Top
+  readonly headers: Schema.Top
+  readonly headersCodec: Schema.Top
+}
+
 /**
  * HTTP API body encoding metadata used by payloads and responses.
  *
@@ -483,6 +500,315 @@ function defaultStreamContentType(mode: StreamMode): string {
   }
 }
 
+/**
+ * Runtime brand key used to mark `WithHeaders` response schemas.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export const WithHeadersTypeId = "~effect/httpapi/HttpApiSchema/WithHeaders"
+
+/**
+ * Type-level brand identifier used by `WithHeaders`.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export type WithHeadersTypeId = typeof WithHeadersTypeId
+
+/**
+ * Runtime brand key used to mark `WithHeaders` response values.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export const WithHeadersValueTypeId = "~effect/httpapi/HttpApiSchema/WithHeadersValue"
+
+/**
+ * Type-level brand identifier used by `WithHeaders` response values.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export type WithHeadersValueTypeId = typeof WithHeadersValueTypeId
+
+/**
+ * A response schema wrapping a body schema together with a response headers
+ * schema.
+ *
+ * **Details**
+ *
+ * `WithHeaders` is a branded declaration schema: it carries the inner success
+ * schema and the headers schema as properties, and server, client, and OpenAPI
+ * integrations detect the brand and handle body and headers separately. It is
+ * supported for error responses, though {@link encodeToWithHeaders} is usually
+ * more convenient there because handlers can fail with the domain error value.
+ *
+ * - `schema` is the inner response schema. Success responses may wrap
+ *   `StreamSse` and `StreamUint8Array`; error responses remain non-streaming.
+ *   Nesting `WithHeaders` is rejected at construction.
+ * - `headers` is any schema; endpoint construction applies
+ *   `Schema.toCodecStringTree` unless codecs are disabled, so leaves become
+ *   `string | undefined` on the wire and `undefined` leaves are omitted from the response.
+ * - Status and response-encoding annotations are resolved from the wrapper
+ *   first, falling through to the inner schema.
+ * - A header-carrying response cannot share its status and content type with
+ *   another response in the same success or error union. Endpoint construction
+ *   rejects ambiguous declarations, including those made with
+ *   {@link encodeToWithHeaders}.
+ * - `Rebuild` preserves the brand and both parts, so `.annotate` keeps the
+ *   wrapper intact.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface WithHeaders<S extends Schema.Top, H extends Schema.Top> extends
+  Schema.Bottom<
+    withHeaders<S["Type"], H["Type"]>,
+    withHeaders<S["Encoded"], Schema.StringTree>,
+    S["DecodingServices"] | H["DecodingServices"],
+    S["EncodingServices"] | H["EncodingServices"],
+    SchemaAST.Declaration,
+    WithHeaders<S, H>
+  >
+{
+  readonly "Rebuild": WithHeaders<S, H>
+  readonly [WithHeadersTypeId]: typeof WithHeadersTypeId
+  readonly schema: S
+  readonly headers: H
+}
+
+/**
+ * The Type of a `WithHeaders` schema: what handlers return and what the
+ * client resolves to, constructed via {@link withHeaders}.
+ *
+ * `body` is the inner success value. For stream success schemas it is the
+ * `Stream` itself, so headers are decided before the body starts streaming.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface withHeaders<A, H> {
+  readonly [WithHeadersValueTypeId]: WithHeadersValueTypeId
+  readonly body: A
+  readonly headers: H
+}
+
+/** @internal */
+export const isWithHeadersValue = (u: unknown): u is withHeaders<unknown, unknown> =>
+  Predicate.hasProperty(u, WithHeadersValueTypeId)
+
+const withHeadersValueSchema = Schema.declare(isWithHeadersValue)
+
+/**
+ * Wraps a success schema with a response headers schema.
+ *
+ * Headers accept either a schema or a fields shorthand, mirroring the
+ * request-side headers option.
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ * import { HttpApiSchema } from "effect/unstable/httpapi"
+ *
+ * const schema = HttpApiSchema.WithHeaders(Schema.String, {
+ *   "x-total-count": Schema.FiniteFromString
+ * })
+ * const response: typeof schema.Type = HttpApiSchema.withHeaders({
+ *   body: "created",
+ *   headers: { "x-total-count": 1 }
+ * })
+ *
+ * HttpApiSchema.isWithHeaders(schema) // => true
+ * response.body // => "created"
+ * response.headers // => { "x-total-count": 1 }
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export function WithHeaders<S extends Schema.Top, H extends Schema.Struct.Fields>(
+  schema: S,
+  headers: H
+): WithHeaders<S, Schema.Struct<H>>
+export function WithHeaders<S extends Schema.Top, H extends Schema.Top>(
+  schema: S,
+  headers: H
+): WithHeaders<S, H>
+export function WithHeaders(
+  schema: Schema.Top,
+  headers: Schema.Top | Schema.Struct.Fields
+): WithHeaders<Schema.Top, Schema.Top> {
+  if (isWithHeaders(schema)) {
+    throw new Error("WithHeaders schemas cannot be nested")
+  }
+  return Schema.make<WithHeaders<Schema.Top, Schema.Top>>(withHeadersValueSchema.ast, {
+    [WithHeadersTypeId]: WithHeadersTypeId,
+    schema,
+    headers: Schema.isSchema(headers) ? headers : Schema.Struct(headers)
+  })
+}
+
+/**
+ * Constructs a `WithHeaders` response value from a body and headers.
+ *
+ * The returned value is branded so servers and clients can detect it exactly,
+ * including in mixed success unions. The same shape is used on both sides: a
+ * value received from a client can be returned from another handler unchanged.
+ *
+ * See {@link WithHeaders} for an example that constructs a schema and its
+ * corresponding response value.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const withHeaders = <A, H>(options: {
+  readonly body: A
+  readonly headers: H
+}): withHeaders<A, H> => ({
+  [WithHeadersValueTypeId]: WithHeadersValueTypeId,
+  body: options.body,
+  headers: options.headers
+})
+
+/**
+ * Returns `true` when a schema is a `WithHeaders` response schema.
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ * import { HttpApiSchema } from "effect/unstable/httpapi"
+ *
+ * const schema = HttpApiSchema.WithHeaders(Schema.String, {
+ *   "x-request-id": Schema.String
+ * })
+ *
+ * HttpApiSchema.isWithHeaders(schema) // => true
+ * HttpApiSchema.isWithHeaders(Schema.String) // => false
+ * ```
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+export const isWithHeaders = (u: unknown): u is WithHeaders<Schema.Top, Schema.Top> =>
+  Schema.isSchema(u) && Predicate.hasProperty(u, WithHeadersTypeId)
+
+/** @internal */
+export function rebuildWithHeaders(
+  self: WithHeaders<Schema.Top, Schema.Top>,
+  schema: Schema.Top,
+  headers: Schema.Top
+): WithHeaders<Schema.Top, Schema.Top> {
+  return Schema.make<WithHeaders<Schema.Top, Schema.Top>>(self.ast, {
+    [WithHeadersTypeId]: WithHeadersTypeId,
+    schema,
+    headers
+  })
+}
+
+/**
+ * Schema type returned by `encodeToWithHeaders`, encoding as a `{ body, headers }`
+ * pair while decoding to the source schema type.
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+export interface encodeToWithHeaders<
+  S extends Schema.Top,
+  Body extends Schema.Top,
+  Headers extends Schema.Struct.Fields
+> extends
+  Schema.decodeTo<
+    Schema.toType<S>,
+    Schema.Struct<{
+      readonly body: Body
+      readonly headers: Schema.Struct<Headers>
+    }>
+  >
+{}
+
+/**
+ * Encodes a schema as a `{ body, headers }` pair, folding response headers into
+ * an opaque domain type such as an error class.
+ *
+ * **Details**
+ *
+ * The encoded side is the pair of the body schema and the headers fields; the
+ * Type stays the source schema's Type. The body schema is authoritative for
+ * everything wire-level: status, content type, and response encoding resolve
+ * from the body schema's annotations.
+ *
+ * The mappings are pure total functions: validation lives in the body and
+ * header schemas, the mappings only reshape valid data.
+ *
+ * Streams used as the body schema turn mid-stream transport errors into
+ * defects on the client. Stream responses should use {@link WithHeaders},
+ * which preserves the body stream's error channel in the generated client.
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ * import { HttpApiSchema } from "effect/unstable/httpapi"
+ *
+ * class UserNotFound extends Schema.TaggedError<UserNotFound>()("UserNotFound", {
+ *   userId: Schema.Int
+ * }) {}
+ *
+ * const UserNotFoundWithHeaders = UserNotFound.pipe(
+ *   HttpApiSchema.encodeToWithHeaders({
+ *     body: HttpApiSchema.Empty(404),
+ *     headers: {
+ *       "x-user-id": Schema.Int
+ *     }
+ *   }, {
+ *     decode: ({ headers }) => new UserNotFound({ userId: headers["x-user-id"] }),
+ *     encode: (error) => ({
+ *       headers: { "x-user-id": error.userId },
+ *       body: undefined
+ *     })
+ *   })
+ * )
+ *
+ * const encoded = Schema.encodeSync(UserNotFoundWithHeaders)(new UserNotFound({ userId: 123 }))
+ * encoded // => { body: undefined, headers: { "x-user-id": 123 } }
+ * ```
+ *
+ * @see {@link WithHeaders} for the structural wrapper recommended for success
+ * responses, including streams.
+ *
+ * @category encoding
+ * @since 4.0.0
+ */
+export function encodeToWithHeaders<
+  S extends Schema.Top,
+  Body extends Schema.Top,
+  Headers extends Schema.Struct.Fields
+>(options: {
+  readonly body: Body
+  readonly headers: Headers
+}, transformation: {
+  readonly decode: (
+    value: Schema.Struct.Type<{ readonly body: Body; readonly headers: Schema.Struct<Headers> }>
+  ) => S["Type"]
+  readonly encode: (
+    value: S["Type"]
+  ) => Schema.Struct.Type<{ readonly body: Body; readonly headers: Schema.Struct<Headers> }>
+}) {
+  return (self: S): encodeToWithHeaders<S, Body, Headers> => {
+    const body = options.body
+    const headers = Schema.Struct(options.headers)
+    const status = resolveHttpApiStatus(body.ast)
+    const encoding = resolveHttpApiEncoding(body.ast)
+    return Schema.Struct({ body, headers }).pipe(
+      Schema.decodeTo(
+        Schema.toType(self),
+        SchemaTransformation.transform(transformation)
+      )
+    ).annotate({
+      "~httpApiWithHeaders": { body, headers, headersCodec: Schema.toEncoded(headers) },
+      ...(status !== undefined ? { httpApiStatus: status } : undefined),
+      ...(encoding !== undefined ? { "~httpApiEncoding": encoding } : undefined)
+    })
+  }
+}
+
 /**
  * Runtime brand key used to mark schemas as buffered multipart payloads.
  *
@@ -683,6 +1009,9 @@ export const isNoContent = (ast: SchemaAST.AST): boolean => {
 
 const resolveHttpApiEncoding = SchemaAST.resolveAt<Encoding>("~httpApiEncoding")
 
+/** @internal */
+export const getWithHeadersAnnotation = SchemaAST.resolveAt<WithHeadersAnnotation>("~httpApiWithHeaders")
+
 const resolveHttpApiStatus = SchemaAST.resolveAt<number>("httpApiStatus")
 
 const defaultJsonEncoding: Encoding = {
@@ -719,6 +1048,22 @@ export function getStatusSuccess(self: SchemaAST.AST): number {
   return resolveHttpApiStatus(self) ?? 200
 }
 
+/** @internal */
+export function getStatusSuccessSchema(schema: Schema.Constraint): number {
+  if (isWithHeaders(schema)) {
+    return resolveHttpApiStatus(schema.ast) ?? getStatusSuccess(schema.schema.ast)
+  }
+  return getStatusSuccess(schema.ast)
+}
+
+/** @internal */
+export function getResponseEncodingSchema(schema: Schema.Constraint): ResponseEncoding {
+  if (isWithHeaders(schema) && resolveHttpApiEncoding(schema.ast) === undefined) {
+    return getResponseEncoding(schema.schema.ast)
+  }
+  return getResponseEncoding(schema.ast)
+}
+
 /** @internal */
 export function getStatusStream(self: StreamSchema): number {
   return getStatusSuccess(self.ast)
@@ -728,3 +1073,11 @@ export function getStatusStream(self: StreamSchema): number {
 export function getStatusError(self: SchemaAST.AST): number {
   return resolveHttpApiStatus(self) ?? 500
 }
+
+/** @internal */
+export function getStatusErrorSchema(schema: Schema.Constraint): number {
+  if (isWithHeaders(schema)) {
+    return resolveHttpApiStatus(schema.ast) ?? getStatusError(schema.schema.ast)
+  }
+  return getStatusError(schema.ast)
+}