effect 4.0.0-beta.102 → 4.0.0-beta.104

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.
  *
@@ -140,7 +157,7 @@ const StreamSchemaTypeId = "~effect/httpapi/HttpApiSchema/Stream"
 /**
  * Common HTTP status code literals accepted by {@link status}.
  *
- * @category status
+ * @category models
  * @since 4.0.0
  */
 export type StatusLiteral = keyof typeof statusCodeByLiteral
@@ -154,7 +171,7 @@ export type StatusLiteral = keyof typeof statusCodeByLiteral
  * schema. You can pass either a numeric status code (for example, `201`) or a
  * common literal name (for example, `"Created"`).
  *
- * @category status
+ * @category schemas
  * @since 4.0.0
  */
 export function status(code: number): {
@@ -174,7 +191,7 @@ export function status(code: number | StatusLiteral) {
  *
  * @see {@link NoContent} for the predefined 204 no content schema.
  *
- * @category Empty
+ * @category constructors
  * @since 4.0.0
  */
 export const Empty = (code: number): Schema.Void => Schema.Void.pipe(status(code))
@@ -190,7 +207,7 @@ export interface NoContent extends Schema.Void {}
 /**
  * Schema for empty HTTP responses with status code 204.
  *
- * @category Empty
+ * @category schemas
  * @since 4.0.0
  */
 export const NoContent: NoContent = Empty(204)
@@ -206,7 +223,7 @@ export interface Created extends Schema.Void {}
 /**
  * Schema for empty HTTP responses with status code 201.
  *
- * @category Empty
+ * @category schemas
  * @since 4.0.0
  */
 export const Created: Created = Empty(201)
@@ -222,7 +239,7 @@ export interface Accepted extends Schema.Void {}
 /**
  * Schema for empty HTTP responses with status code 202.
  *
- * @category Empty
+ * @category schemas
  * @since 4.0.0
  */
 export const Accepted: Accepted = Empty(202)
@@ -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)
+}