effect 4.0.0-beta.103 → 4.0.0-beta.105

package/src/unstable/httpapi/HttpApiEndpoint.ts

@@ -44,11 +44,15 @@ const TypeId = "~effect/httpapi/HttpApiEndpoint"
  */
 export const isHttpApiEndpoint = (u: unknown): u is Top => Predicate.hasProperty(u, TypeId)
 
-type SuccessType<S> = S extends HttpApiSchema.StreamSse<
-  infer _Events,
-  infer _Error,
-  infer _Value
-> ? Stream.Stream<_Value, _Error["Type"], never>
+type SuccessType<S> = S extends HttpApiSchema.WithHeaders<
+  infer _Inner,
+  infer _Headers
+> ? HttpApiSchema.withHeaders<SuccessType<_Inner>, _Headers["Type"]>
+  : S extends HttpApiSchema.StreamSse<
+    infer _Events,
+    infer _Error,
+    infer _Value
+  > ? Stream.Stream<_Value, _Error["Type"], never>
   : S extends HttpApiSchema.StreamUint8Array ? Stream.Stream<Uint8Array, unknown, never>
   : S extends Schema.Constraint ? S["Type"]
   : never
@@ -75,15 +79,24 @@ type UnwrapReadonlyArray<S> = S extends ReadonlyArray<infer A> ? A : S
 
 type ExtractBufferedSuccess<S extends SuccessConstraint> = Exclude<
   Extract<UnwrapReadonlyArray<S>, Schema.Top>,
-  HttpApiSchema.StreamSchema
+  HttpApiSchema.StreamSchema | HttpApiSchema.WithHeaders<Schema.Top, Schema.Top>
 >
 
 type ExtractStreamSuccess<S extends SuccessConstraint> = UnwrapReadonlyArray<S> extends infer Success ?
   Success extends HttpApiSchema.StreamSchema ? Success : never
   : never
 
-type ToSuccessCodec<S extends SuccessConstraint> = [ExtractBufferedSuccess<S>] extends [never] ? ExtractStreamSuccess<S>
-  : Schema.toCodecJson<ExtractBufferedSuccess<S>> | ExtractStreamSuccess<S>
+type ExtractWithHeadersSuccess<S extends SuccessConstraint> = UnwrapReadonlyArray<S> extends infer Success ?
+  Success extends HttpApiSchema.WithHeaders<infer _Inner, infer _Headers> ? HttpApiSchema.WithHeaders<
+      _Inner extends HttpApiSchema.StreamSchema ? _Inner : Schema.toCodecJson<_Inner>,
+      Schema.toCodecStringTree<_Headers>
+    > :
+  never
+  : never
+
+type ToSuccessCodec<S extends SuccessConstraint> = [ExtractBufferedSuccess<S>] extends [never] ?
+  ExtractStreamSuccess<S> | ExtractWithHeadersSuccess<S>
+  : Schema.toCodecJson<ExtractBufferedSuccess<S>> | ExtractStreamSuccess<S> | ExtractWithHeadersSuccess<S>
 
 type ToJsonCodec<S> = [S] extends [never] ? never
   : [S] extends [Schema.Constraint] ? Schema.toCodecJson<S>
@@ -945,9 +958,11 @@ export type SuccessConstraint = Schema.Top | ReadonlyArray<Schema.Top>
  */
 export type ErrorConstraint = Schema.Top | ReadonlyArray<Schema.Top>
 
+type ErrorSchema<S> = S extends HttpApiSchema.WithHeaders<infer Inner, Schema.Top> ? Inner : S
+
 type ErrorNoStream<S extends ErrorConstraint> = [
   Extract<
-    S extends ReadonlyArray<Schema.Constraint> ? S[number] : S,
+    ErrorSchema<S extends ReadonlyArray<Schema.Constraint> ? S[number] : S>,
     HttpApiSchema.StreamSchema
   >
 ] extends [never] ? S : never
@@ -1139,11 +1154,18 @@ function getSuccessResponse(
   if (success === undefined) return new Set()
   const schemas = Arr.ensure(success)
   validateSuccessResponse(schemas, method)
-  return new Set(
-    disableCodecs ?
-      schemas :
-      schemas.map((schema) => HttpApiSchema.isStreamSchema(schema) ? schema : transformResponse(schema))
-  )
+  return new Set(disableCodecs ? schemas : schemas.map(transformResponseSchema))
+}
+
+function transformResponseSchema(schema: Schema.Top): Schema.Top {
+  if (HttpApiSchema.isStreamSchema(schema)) return schema
+  if (HttpApiSchema.isWithHeaders(schema)) {
+    const inner = HttpApiSchema.isStreamSchema(schema.schema)
+      ? schema.schema
+      : applyResponseEncoding(schema.schema, HttpApiSchema.getResponseEncodingSchema(schema))
+    return HttpApiSchema.rebuildWithHeaders(schema, inner, Schema.toCodecStringTree(schema.headers))
+  }
+  return transformResponse(schema)
 }
 
 function getErrorResponse(
@@ -1153,14 +1175,17 @@ function getErrorResponse(
   if (error === undefined) return new Set()
   const schemas = Arr.ensure(error)
   for (const schema of schemas) {
-    if (HttpApiSchema.isStreamSchema(schema)) {
+    const body = HttpApiSchema.isWithHeaders(schema) ? schema.schema : schema
+    if (HttpApiSchema.isStreamSchema(body)) {
       throw new Error("Streaming schemas are not supported in error responses")
     }
   }
-  return new Set(disableCodecs ? schemas : schemas.map(transformResponse))
+  validateResponseExclusivity(schemas, HttpApiSchema.getStatusErrorSchema)
+  return new Set(disableCodecs ? schemas : schemas.map(transformResponseSchema))
 }
 
 function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, method: HttpMethod) {
+  let hasStream = false
   const statuses = new Map<number, {
     readonly stream?: HttpApiSchema.StreamSchema | undefined
     bufferedContentTypes: Set<string>
@@ -1168,31 +1193,32 @@ function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, meth
   }>()
 
   for (const schema of schemas) {
-    if (HttpApiSchema.isStreamSchema(schema)) {
-      validateStreamSuccess(schema, method)
-      const status = HttpApiSchema.getStatusStream(schema)
-      const entry = getStatusEntry(statuses, status)
-      if (entry.stream !== undefined) {
-        throw new Error(`Multiple streaming success responses for status: ${status}`)
+    const inner = HttpApiSchema.isWithHeaders(schema) ? schema.schema : schema
+    const status = HttpApiSchema.getStatusSuccessSchema(schema)
+    if (HttpApiSchema.isStreamSchema(inner)) {
+      validateStreamSuccess(inner, method)
+      if (hasStream) {
+        throw new Error("Multiple streaming success responses are not supported")
       }
+      hasStream = true
+      const entry = getStatusEntry(statuses, status)
       if (entry.noContent) {
         throw new Error(`Cannot combine no-content and streaming success responses for status: ${status}`)
       }
-      if (entry.bufferedContentTypes.has(MediaType.normalize(schema.contentType))) {
+      if (entry.bufferedContentTypes.has(MediaType.normalize(inner.contentType))) {
         throw new Error(
-          `Cannot combine buffered and streaming success responses for status ${status} and content-type: ${schema.contentType}`
+          `Cannot combine buffered and streaming success responses for status ${status} and content-type: ${inner.contentType}`
         )
       }
-      statuses.set(status, { ...entry, stream: schema })
+      statuses.set(status, { ...entry, stream: inner })
     } else {
-      const status = HttpApiSchema.getStatusSuccess(schema.ast)
       const entry = getStatusEntry(statuses, status)
-      const noContent = HttpApiSchema.isNoContent(schema.ast)
+      const noContent = HttpApiSchema.isNoContent(inner.ast)
       if (entry.stream !== undefined) {
         if (noContent) {
           throw new Error(`Cannot combine no-content and streaming success responses for status: ${status}`)
         }
-        const encoding = HttpApiSchema.getResponseEncoding(schema.ast)
+        const encoding = HttpApiSchema.getResponseEncodingSchema(schema)
         if (
           MediaType.normalize(encoding.contentType) === MediaType.normalize(entry.stream.contentType)
         ) {
@@ -1203,12 +1229,14 @@ function validateSuccessResponse(schemas: ReadonlyArray<Schema.Constraint>, meth
       }
       if (!noContent) {
         entry.bufferedContentTypes.add(
-          MediaType.normalize(HttpApiSchema.getResponseEncoding(schema.ast).contentType)
+          MediaType.normalize(HttpApiSchema.getResponseEncodingSchema(schema).contentType)
         )
       }
       entry.noContent = entry.noContent || noContent
     }
   }
+
+  validateResponseExclusivity(schemas, HttpApiSchema.getStatusSuccessSchema)
 }
 
 function getStatusEntry(
@@ -1227,6 +1255,49 @@ function getStatusEntry(
   return entry
 }
 
+function validateResponseExclusivity(
+  schemas: ReadonlyArray<Schema.Constraint>,
+  getStatus: (schema: Schema.Constraint) => number
+) {
+  const statuses = new Map<number, {
+    headerContentType: string | undefined
+    readonly plainContentTypes: Set<string>
+  }>()
+  for (const schema of schemas) {
+    const status = getStatus(schema)
+    const withHeadersAnnotation = HttpApiSchema.getWithHeadersAnnotation(schema.ast)
+    const body = HttpApiSchema.isWithHeaders(schema) ? schema.schema : withHeadersAnnotation?.body ?? schema
+    const contentType = HttpApiSchema.isNoContent(body.ast)
+      ? ""
+      : MediaType.normalize(
+        HttpApiSchema.isStreamSchema(body)
+          ? body.contentType
+          : HttpApiSchema.getResponseEncodingSchema(schema).contentType
+      )
+    let entry = statuses.get(status)
+    if (entry === undefined) {
+      entry = { headerContentType: undefined, plainContentTypes: new Set() }
+      statuses.set(status, entry)
+    }
+    const combineError = () =>
+      new Error(
+        `Cannot combine a response with headers with another response for status ${status} and content-type: ${
+          contentType || "<no content>"
+        }`
+      )
+    if (HttpApiSchema.isWithHeaders(schema) || withHeadersAnnotation !== undefined) {
+      if (entry.headerContentType !== undefined) {
+        throw new Error(`Cannot declare multiple responses with headers for status ${status}`)
+      }
+      if (entry.plainContentTypes.has(contentType)) throw combineError()
+      entry.headerContentType = contentType
+    } else {
+      if (entry.headerContentType === contentType) throw combineError()
+      entry.plainContentTypes.add(contentType)
+    }
+  }
+}
+
 function validateStreamSuccess(schema: HttpApiSchema.StreamSchema, method: HttpMethod) {
   if (method === "HEAD") {
     throw new Error("HEAD endpoints cannot declare streaming success responses")
@@ -1275,6 +1346,23 @@ function hasReservedEventLiteral(ast: AST.AST, seen: Set<AST.AST>): boolean {
 
 function transformResponse(schema: Schema.Top): Schema.Top {
   const encoding = HttpApiSchema.getResponseEncoding(schema.ast)
+  const withHeaders = HttpApiSchema.getWithHeadersAnnotation(schema.ast)
+  if (withHeaders === undefined) {
+    return applyResponseEncoding(schema, encoding)
+  }
+  const headers = Schema.toEncoded(withHeaders.headers)
+  return Schema.Struct({
+    body: applyResponseEncoding(Schema.toEncoded(withHeaders.body), encoding),
+    headers
+  }).pipe(Schema.decodeTo(schema)).annotate({
+    "~httpApiWithHeaders": {
+      ...withHeaders,
+      headersCodec: Schema.toCodecStringTree(headers)
+    }
+  })
+}
+
+function applyResponseEncoding(schema: Schema.Top, encoding: HttpApiSchema.ResponseEncoding): Schema.Top {
   switch (encoding._tag) {
     case "Json":
       return Schema.toCodecJson(schema)

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