effect 4.0.0-beta.2 → 4.0.0-beta.21

package/src/unstable/httpapi/HttpApiEndpoint.ts

@@ -4,7 +4,6 @@
 import * as Arr from "../../Array.ts"
 import type { Brand } from "../../Brand.ts"
 import type { Effect } from "../../Effect.ts"
-import { format } from "../../Formatter.ts"
 import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
@@ -71,14 +70,14 @@ export interface HttpApiEndpoint<
   readonly name: Name
   readonly path: Path
   readonly method: Method
-  readonly params: Schema.Struct.Fields | undefined
-  readonly query: Schema.Struct.Fields | undefined
-  readonly headers: Schema.Struct.Fields | undefined
+  readonly params: Schema.Top | undefined
+  readonly query: Schema.Top | undefined
+  readonly headers: Schema.Top | undefined
   readonly payload: PayloadMap
   readonly success: ReadonlySet<Schema.Top>
   readonly error: ReadonlySet<Schema.Top>
   readonly annotations: ServiceMap.ServiceMap<never>
-  readonly middlewares: ReadonlySet<ServiceMap.Service<Middleware, any>>
+  readonly middlewares: ReadonlySet<ServiceMap.Key<Middleware, any>>
 
   /**
    * Add a prefix to the path of the endpoint.
@@ -102,7 +101,7 @@ export interface HttpApiEndpoint<
   /**
    * Add an `HttpApiMiddleware` to the endpoint.
    */
-  middleware<I extends HttpApiMiddleware.AnyId, S>(middleware: ServiceMap.Service<I, S>): HttpApiEndpoint<
+  middleware<I extends HttpApiMiddleware.AnyId, S>(middleware: ServiceMap.Key<I, S>): HttpApiEndpoint<
     Name,
     Method,
     Path,
@@ -120,7 +119,7 @@ export interface HttpApiEndpoint<
    * Add an annotation on the endpoint.
    */
   annotate<I, S>(
-    key: ServiceMap.Service<I, S>,
+    key: ServiceMap.Key<I, S>,
     value: Types.NoInfer<S>
   ): HttpApiEndpoint<
     Name,
@@ -156,21 +155,6 @@ export interface HttpApiEndpoint<
   >
 }
 
-/** @internal */
-export function getParamsSchema(endpoint: AnyWithProps): Schema.Top | undefined {
-  return endpoint.params ? Schema.Struct(endpoint.params) : undefined
-}
-
-/** @internal */
-export function getQuerySchema(endpoint: AnyWithProps): Schema.Top | undefined {
-  return endpoint.query ? Schema.Struct(endpoint.query) : undefined
-}
-
-/** @internal */
-export function getHeadersSchema(endpoint: AnyWithProps): Schema.Top | undefined {
-  return endpoint.headers ? Schema.Struct(endpoint.headers) : undefined
-}
-
 /** @internal */
 export function getPayloadSchemas(endpoint: AnyWithProps): Array<Schema.Top> {
   const result: Array<Schema.Top> = []
@@ -190,7 +174,7 @@ export function getSuccessSchemas(endpoint: AnyWithProps): [Schema.Top, ...Array
 export function getErrorSchemas(endpoint: AnyWithProps): [Schema.Top, ...Array<Schema.Top>] {
   const schemas = new Set<Schema.Top>(endpoint.error)
   for (const middleware of endpoint.middlewares) {
-    const key = middleware as any as HttpApiMiddleware.AnyKey
+    const key = middleware as any as HttpApiMiddleware.AnyService
     if (key.error !== undefined) {
       schemas.add(key.error)
     }
@@ -529,8 +513,8 @@ export type ServerServices<Endpoint> = Endpoint extends HttpApiEndpoint<
     | _Payload["DecodingServices"]
     | _Headers["DecodingServices"]
     | _Success["EncodingServices"]
-  // Error services are handled globally
-  // | _Error["EncodingServices"]
+    | _Error["EncodingServices"]
+    | HttpApiMiddleware.ErrorServicesEncode<_M>
   : never
 
 /**
@@ -684,10 +668,19 @@ export type MiddlewareServicesWithName<Endpoints extends Any, Name extends strin
  * @since 4.0.0
  * @category models
  */
-export type ExcludeProvided<Endpoints extends Any, Name extends string, R> = Exclude<
+export type ExcludeProvidedWithName<Endpoints extends Any, Name extends string, R> = ExcludeProvided<
+  WithName<Endpoints, Name>,
+  R
+>
+
+/**
+ * @since 4.0.0
+ * @category models
+ */
+export type ExcludeProvided<Endpoint extends Any, R> = Exclude<
   R,
   | HttpRouter.Provided
-  | HttpApiMiddleware.Provides<MiddlewareWithName<Endpoints, Name>>
+  | HttpApiMiddleware.Provides<Middleware<Endpoint>>
 >
 
 /**
@@ -794,13 +787,13 @@ const Proto = {
       path: HttpRouter.prefixPath(this.path, prefix)
     })
   },
-  middleware(this: AnyWithProps, middleware: HttpApiMiddleware.AnyKey) {
+  middleware(this: AnyWithProps, middleware: HttpApiMiddleware.AnyService) {
     return makeProto({
       ...this,
       middlewares: new Set([...this.middlewares, middleware as any])
     })
   },
-  annotate(this: AnyWithProps, key: ServiceMap.Service<any, any>, value: any) {
+  annotate(this: AnyWithProps, key: ServiceMap.Key<any, any>, value: any) {
     return makeProto({
       ...this,
       annotations: ServiceMap.add(this.annotations, key, value)
@@ -830,14 +823,14 @@ function makeProto<
   readonly name: Name
   readonly path: Path
   readonly method: Method
-  readonly params: Schema.Struct.Fields | undefined
-  readonly query: Schema.Struct.Fields | undefined
-  readonly headers: Schema.Struct.Fields | undefined
+  readonly params: Schema.Top | undefined
+  readonly query: Schema.Top | undefined
+  readonly headers: Schema.Top | undefined
   readonly payload: PayloadMap
   readonly success: ReadonlySet<Schema.Top>
   readonly error: ReadonlySet<Schema.Top>
   readonly annotations: ServiceMap.ServiceMap<never>
-  readonly middlewares: ReadonlySet<ServiceMap.Service<Middleware, any>>
+  readonly middlewares: ReadonlySet<ServiceMap.Key<Middleware, any>>
 }): HttpApiEndpoint<
   Name,
   Method,
@@ -855,32 +848,28 @@ function makeProto<
 }
 
 /**
- * Params come from the router as `string` (optional params as `undefined`) and
- * must be encodable back into the URL path.
- *
- * We accept "struct fields" (`Record<string, Codec<...>>`) so we can both enforce
- * `Encoded` = `string | undefined` per field and reliably generate OpenAPI
- * `in: path` parameters by iterating object properties.
- *
  * @since 4.0.0
  * @category constraints
  */
-export type ParamsConstraint = Record<string, Schema.Encoder<string | undefined, unknown>>
+export type ParamsConstraint =
+  | Record<string, Schema.Encoder<string | undefined, unknown>>
+  | Schema.Encoder<Record<string, string | undefined>, unknown>
 
 /**
- * URL search params can be repeated, so fields may encode to `string` or
- * `ReadonlyArray<string>` (or be missing).
- *
- * Kept as "struct fields" so OpenAPI can safely expand properties into
- * `in: query` parameters.
- *
  * @since 4.0.0
  * @category constraints
  */
-export type QuerySchemaConstraint = Record<
-  string,
-  Schema.Encoder<string | ReadonlyArray<string> | undefined, unknown>
->
+export type HeadersConstraint =
+  | Record<string, Schema.Encoder<string | undefined, unknown>>
+  | Schema.Encoder<Record<string, string | undefined>, unknown>
+
+/**
+ * @since 4.0.0
+ * @category constraints
+ */
+export type QueryConstraint =
+  | Record<string, Schema.Encoder<string | ReadonlyArray<string> | undefined, unknown>>
+  | Schema.Encoder<Record<string, string | ReadonlyArray<string> | undefined>, unknown>
 
 /**
  * Payload schema depends on the HTTP method:
@@ -893,34 +882,23 @@ export type QuerySchemaConstraint = Record<
  * @since 4.0.0
  * @category constraints
  */
-export type PayloadSchemaConstraint<Method extends HttpMethod> = Method extends HttpMethod.NoBody ? Record<
+export type PayloadConstraint<Method extends HttpMethod> = Method extends HttpMethod.NoBody ? Record<
     string,
     Schema.Encoder<string | ReadonlyArray<string> | undefined, unknown>
   > :
-  SuccessSchemaConstraint
-
-/**
- * HTTP headers are string-valued (or missing).
- *
- * Kept as "struct fields" so OpenAPI can safely expand properties into
- * `in: header` parameters.
- *
- * @since 4.0.0
- * @category constraints
- */
-export type HeadersSchemaConstraint = Record<string, Schema.Encoder<string | undefined, unknown>>
+  SuccessConstraint
 
 /**
  * @since 4.0.0
  * @category constraints
  */
-export type SuccessSchemaConstraint = Schema.Top | ReadonlyArray<Schema.Top>
+export type SuccessConstraint = Schema.Top | ReadonlyArray<Schema.Top>
 
 /**
  * @since 4.0.0
  * @category constraints
  */
-export type ErrorSchemaConstraint = Schema.Top | ReadonlyArray<Schema.Top>
+export type ErrorConstraint = Schema.Top | ReadonlyArray<Schema.Top>
 
 /**
  * @since 4.0.0
@@ -931,11 +909,11 @@ export const make = <Method extends HttpMethod>(method: Method) =>
   const Name extends string,
   const Path extends HttpRouter.PathInput,
   Params extends ParamsConstraint = never,
-  Query extends QuerySchemaConstraint = never,
-  Payload extends PayloadSchemaConstraint<Method> = never,
-  Headers extends HeadersSchemaConstraint = never,
-  const Success extends SuccessSchemaConstraint = HttpApiSchema.NoContent,
-  const Error extends ErrorSchemaConstraint = never
+  Query extends QueryConstraint = never,
+  Payload extends PayloadConstraint<Method> = never,
+  Headers extends HeadersConstraint = never,
+  const Success extends SuccessConstraint = HttpApiSchema.NoContent,
+  const Error extends ErrorConstraint = never
 >(
   name: Name,
   path: Path,
@@ -964,8 +942,8 @@ export const make = <Method extends HttpMethod>(method: Method) =>
     name,
     path,
     method,
-    params: options?.params,
-    query: options?.query,
+    params: getParams(options?.params),
+    query: getQuery(options?.query),
     headers: getHeaders(options?.headers),
     payload: getPayload(options?.payload),
     success: getSuccess(options?.success),
@@ -975,17 +953,23 @@ export const make = <Method extends HttpMethod>(method: Method) =>
   })
 }
 
+function getParams(params: ParamsConstraint | undefined): Schema.Top | undefined {
+  if (params === undefined) return undefined
+  if (Schema.isSchema(params)) return params
+  return Schema.Struct(params)
+}
+
+function getQuery(query: QueryConstraint | undefined): Schema.Top | undefined {
+  if (query === undefined) return undefined
+  if (Schema.isSchema(query)) return query
+  return Schema.Struct(query)
+}
+
 // all keys should be lowercase
-function getHeaders(headers: Schema.Struct.Fields | undefined): Schema.Struct.Fields | undefined {
-  if (headers !== undefined) {
-    for (const key of Object.keys(headers)) {
-      const lowerKey = key.toLowerCase()
-      if (key !== lowerKey) {
-        throw new Error(`Header keys must be lowercase, got ${format(key)} (use ${format(lowerKey)})`)
-      }
-    }
-    return headers
-  }
+function getHeaders(headers: HeadersConstraint | undefined): Schema.Top | undefined {
+  if (headers === undefined) return undefined
+  if (Schema.isSchema(headers)) return headers
+  return Schema.Struct(headers)
 }
 
 function getPayload(

package/src/unstable/httpapi/HttpApiError.ts

@@ -1,6 +1,7 @@
 /**
  * @since 4.0.0
  */
+import * as ErrorReporter from "../../ErrorReporter.ts"
 import * as Schema from "../../Schema.ts"
 import * as HttpApiSchema from "./HttpApiSchema.ts"
 
@@ -21,6 +22,8 @@ export class HttpApiSchemaError extends Schema.ErrorClass<HttpApiSchemaError>("e
   static fromSchemaError(error: Schema.SchemaError): HttpApiSchemaError {
     return new HttpApiSchemaError({ message: error.message })
   }
+
+  override readonly [ErrorReporter.ignore] = true
 }
 
 /**
@@ -32,7 +35,9 @@ export class BadRequest extends Schema.ErrorClass<BadRequest>("effect/HttpApiErr
 }, {
   description: "BadRequest",
   httpApiStatus: 400
-}) {}
+}) {
+  override readonly [ErrorReporter.ignore] = true
+}
 
 /**
  * @category NoContent errors
@@ -51,7 +56,9 @@ export class Unauthorized extends Schema.ErrorClass<Unauthorized>("effect/HttpAp
 }, {
   description: "Unauthorized",
   httpApiStatus: 401
-}) {}
+}) {
+  override readonly [ErrorReporter.ignore] = true
+}
 
 /**
  * @category NoContent errors
@@ -70,7 +77,9 @@ export class Forbidden extends Schema.ErrorClass<Forbidden>("effect/HttpApiError
 }, {
   description: "Forbidden",
   httpApiStatus: 403
-}) {}
+}) {
+  override readonly [ErrorReporter.ignore] = true
+}
 
 /**
  * @category NoContent errors
@@ -89,7 +98,9 @@ export class NotFound extends Schema.ErrorClass<NotFound>("effect/HttpApiError/N
 }, {
   description: "NotFound",
   httpApiStatus: 404
-}) {}
+}) {
+  override readonly [ErrorReporter.ignore] = true
+}
 
 /**
  * @category NoContent errors
@@ -108,7 +119,9 @@ export class MethodNotAllowed extends Schema.ErrorClass<MethodNotAllowed>("effec
 }, {
   description: "MethodNotAllowed",
   httpApiStatus: 405
-}) {}
+}) {
+  override readonly [ErrorReporter.ignore] = true
+}
 
 /**
  * @category NoContent errors
@@ -127,7 +140,9 @@ export class NotAcceptable extends Schema.ErrorClass<NotAcceptable>("effect/Http
 }, {
   description: "NotAcceptable",
   httpApiStatus: 406
-}) {}
+}) {
+  override readonly [ErrorReporter.ignore] = true
+}
 
 /**
  * @category NoContent errors
@@ -146,7 +161,9 @@ export class RequestTimeout extends Schema.ErrorClass<RequestTimeout>("effect/Ht
 }, {
   description: "RequestTimeout",
   httpApiStatus: 408
-}) {}
+}) {
+  override readonly [ErrorReporter.ignore] = true
+}
 
 /**
  * @category NoContent errors
@@ -165,7 +182,9 @@ export class Conflict extends Schema.ErrorClass<Conflict>("effect/HttpApiError/C
 }, {
   description: "Conflict",
   httpApiStatus: 409
-}) {}
+}) {
+  override readonly [ErrorReporter.ignore] = true
+}
 
 /**
  * @since 4.0.0
@@ -184,7 +203,9 @@ export class Gone extends Schema.ErrorClass<Gone>("effect/HttpApiError/Gone")({
 }, {
   description: "Gone",
   httpApiStatus: 410
-}) {}
+}) {
+  override readonly [ErrorReporter.ignore] = true
+}
 
 /**
  * @category NoContent errors

package/src/unstable/httpapi/HttpApiGroup.ts

@@ -61,7 +61,7 @@ export interface HttpApiGroup<
    * Endpoints added after this api is called **will not** have the middleware
    * applied.
    */
-  middleware<I extends HttpApiMiddleware.AnyId, S>(middleware: ServiceMap.Service<I, S>): HttpApiGroup<
+  middleware<I extends HttpApiMiddleware.AnyId, S>(middleware: ServiceMap.Key<I, S>): HttpApiGroup<
     Id,
     HttpApiEndpoint.AddMiddleware<Endpoints, I>,
     TopLevel
@@ -75,7 +75,7 @@ export interface HttpApiGroup<
   /**
    * Add an annotation to an `HttpApiGroup`.
    */
-  annotate<I, S>(key: ServiceMap.Service<I, S>, value: S): HttpApiGroup<Id, Endpoints, TopLevel>
+  annotate<I, S>(key: ServiceMap.Key<I, S>, value: S): HttpApiGroup<Id, Endpoints, TopLevel>
 
   /**
    * For each endpoint in an `HttpApiGroup`, update the annotations with a new
@@ -91,7 +91,7 @@ export interface HttpApiGroup<
    * Note that this will only add the annotation to the endpoints before this api
    * is called.
    */
-  annotateEndpoints<I, S>(key: ServiceMap.Service<I, S>, value: S): HttpApiGroup<Id, Endpoints, TopLevel>
+  annotateEndpoints<I, S>(key: ServiceMap.Key<I, S>, value: S): HttpApiGroup<Id, Endpoints, TopLevel>
 }
 
 /**
@@ -238,7 +238,7 @@ const Proto = {
       annotations: this.annotations
     })
   },
-  middleware(this: AnyWithProps, middleware: HttpApiMiddleware.AnyKey) {
+  middleware(this: AnyWithProps, middleware: HttpApiMiddleware.AnyService) {
     return makeProto({
       identifier: this.identifier,
       topLevel: this.topLevel,
@@ -254,7 +254,7 @@ const Proto = {
       annotations: ServiceMap.merge(this.annotations, annotations)
     })
   },
-  annotate<I, S>(this: AnyWithProps, annotation: ServiceMap.Service<I, S>, value: S) {
+  annotate<I, S>(this: AnyWithProps, annotation: ServiceMap.Key<I, S>, value: S) {
     return makeProto({
       identifier: this.identifier,
       topLevel: this.topLevel,
@@ -270,7 +270,7 @@ const Proto = {
       annotations: this.annotations
     })
   },
-  annotateEndpoints<I, S>(this: AnyWithProps, annotation: ServiceMap.Service<I, S>, value: S) {
+  annotateEndpoints<I, S>(this: AnyWithProps, annotation: ServiceMap.Key<I, S>, value: S) {
     return makeProto({
       identifier: this.identifier,
       topLevel: this.topLevel,

package/src/unstable/httpapi/HttpApiMiddleware.ts

@@ -25,7 +25,7 @@ const SecurityTypeId = "~effect/httpapi/HttpApiMiddleware/Security"
  * @since 4.0.0
  * @category guards
  */
-export const isSecurity = (u: AnyKey): u is AnyKeySecurity => hasProperty(u, SecurityTypeId)
+export const isSecurity = (u: AnyService): u is AnyServiceSecurity => hasProperty(u, SecurityTypeId)
 
 /**
  * @since 4.0.0
@@ -87,7 +87,7 @@ export interface ForClient<Id> {
  * @since 4.0.0
  * @category models
  */
-export interface AnyKey extends ServiceMap.Service<any, any> {
+export interface AnyService extends ServiceMap.Key<any, any> {
   readonly [TypeId]: typeof TypeId
   readonly provides: any
   readonly error: Schema.Top
@@ -99,7 +99,7 @@ export interface AnyKey extends ServiceMap.Service<any, any> {
  * @since 4.0.0
  * @category models
  */
-export interface AnyKeySecurity extends AnyKey {
+export interface AnyServiceSecurity extends AnyService {
   readonly [SecurityTypeId]: typeof SecurityTypeId
   readonly security: Record<string, HttpApiSecurity.HttpApiSecurity>
 }
@@ -297,7 +297,7 @@ export const Service = <
  * @category client
  */
 export const layerClient = <Id extends AnyId, S, R, EX = never, RX = never>(
-  tag: ServiceMap.Service<Id, S>,
+  tag: ServiceMap.Key<Id, S>,
   service:
     | HttpApiMiddlewareClient<Id[typeof TypeId]["error"]["Type"], Id[typeof TypeId]["clientError"], R>
     | Effect.Effect<

package/src/unstable/httpapi/HttpApiScalar.ts

@@ -98,6 +98,12 @@ export type ScalarConfig = {
    * Default: `false`
    */
   defaultOpenAllTags?: boolean
+  /**
+   * Whether to display the operation ID in the operation reference.
+   *
+   * Default: `false`
+   */
+  showOperationId?: boolean
 }
 
 type ScalarSource =

package/src/unstable/httpapi/HttpApiSecurity.ts

@@ -161,15 +161,15 @@ export const annotate: {
    * @since 4.0.0
    * @category annotations
    */
-  <I, S>(service: ServiceMap.Service<I, S>, value: S): <A extends HttpApiSecurity>(self: A) => A
+  <I, S>(service: ServiceMap.Key<I, S>, value: S): <A extends HttpApiSecurity>(self: A) => A
   /**
    * @since 4.0.0
    * @category annotations
    */
-  <A extends HttpApiSecurity, I, S>(self: A, service: ServiceMap.Service<I, S>, value: S): A
+  <A extends HttpApiSecurity, I, S>(self: A, service: ServiceMap.Key<I, S>, value: S): A
 } = dual(
   3,
-  <A extends HttpApiSecurity, I, S>(self: A, service: ServiceMap.Service<I, S>, value: S): A =>
+  <A extends HttpApiSecurity, I, S>(self: A, service: ServiceMap.Key<I, S>, value: S): A =>
     Object.assign(Object.create(Proto), {
       ...self,
       annotations: ServiceMap.add(self.annotations, service, value)

package/src/unstable/httpapi/OpenApi.ts

@@ -111,7 +111,7 @@ export class Transform extends ServiceMap.Service<
   (openApiSpec: Record<string, any>) => Record<string, any>
 >()("effect/httpapi/OpenApi/Transform") {}
 
-const servicesPartial = <Tags extends Record<string, ServiceMap.Service<any, any> | ServiceMap.Service<never, any>>>(
+const servicesPartial = <Tags extends Record<string, ServiceMap.Key<any, any> | ServiceMap.Key<never, any>>>(
   tags: Tags
 ): (
   options: {
@@ -175,7 +175,7 @@ const apiCache = new WeakMap<HttpApi.Any, OpenAPISpec>()
  */
 function processAnnotation<Services, S, I>(
   ctx: ServiceMap.ServiceMap<Services>,
-  annotation: ServiceMap.Service<I, S>,
+  annotation: ServiceMap.Key<I, S>,
   f: (s: S) => void
 ) {
   const o = ServiceMap.getOption(ctx, annotation)
@@ -351,10 +351,9 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Any>(
                   ast: toEncodingAST(ast, encoding),
                   path: ["paths", path, method, "responses", String(status), "content", contentType, "schema"]
                 })
-                op.responses[status].content = {
-                  [contentType]: {
-                    schema: {}
-                  }
+                op.responses[status].content ??= {}
+                op.responses[status].content[contentType] = {
+                  schema: {}
                 }
               })
             })
@@ -362,20 +361,23 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Any>(
         }
       }
 
-      function processParameters(fields: Schema.Struct.Fields | undefined, i: OpenAPISpecParameter["in"]) {
-        if (fields) {
-          for (const [name, field] of Object.entries(fields)) {
-            op.parameters.push({
-              name: String(name),
-              in: i,
-              schema: {},
-              required: i === "path" || !AST.isOptional(field.ast)
-            })
-            pathOps.push({
-              _tag: "parameter",
-              ast: AST.toEncoded(field.ast),
-              path: ["paths", path, method, "parameters", String(op.parameters.length - 1), "schema"]
-            })
+      function processParameters(schema: Schema.Top | undefined, i: OpenAPISpecParameter["in"]) {
+        if (schema) {
+          const ast = AST.toEncoded(schema.ast)
+          if (AST.isObjects(ast)) {
+            for (const ps of ast.propertySignatures) {
+              op.parameters.push({
+                name: String(ps.name),
+                in: i,
+                schema: {},
+                required: i === "path" || !AST.isOptional(ps.type)
+              })
+              pathOps.push({
+                _tag: "parameter",
+                ast: ps.type,
+                path: ["paths", path, method, "parameters", String(op.parameters.length - 1), "schema"]
+              })
+            }
           }
         }
       }
@@ -421,8 +423,7 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Any>(
       processParameters(endpoint.params, "path")
       if (!hasBody && endpoint.payload.size === 1) {
         const entry = endpoint.payload.values().next().value!
-        const schema = entry.schemas[0] as Schema.Struct<Schema.Struct.Fields>
-        processParameters(schema.fields, "query")
+        processParameters(entry.schemas[0], "query")
       }
       processParameters(endpoint.headers, "header")
       processParameters(endpoint.query, "query")
@@ -634,9 +635,26 @@ function toEncodingAST(ast: AST.AST, _tag: HttpApiSchema.Encoding["_tag"]): AST.
       return Schema.String.ast
     case "FormUrlEncoded":
     case "Json":
-    case "Multipart":
       return ast
+    case "Multipart":
+      return persistedFileToBinaryEncoding(ast)
+  }
+}
+
+function persistedFileToBinaryEncoding(ast: AST.AST): AST.AST {
+  if (
+    AST.isDeclaration(ast) &&
+    ((ast.annotations as (Schema.Annotations.Declaration<unknown, readonly []> | undefined))?.typeConstructor?._tag ===
+      "effect/http/PersistedFile")
+  ) {
+    return Uint8ArrayEncoding.ast
   }
+
+  if (typeof (ast as any)?.recur === "function") {
+    return (ast as any).recur(persistedFileToBinaryEncoding)
+  }
+
+  return ast
 }
 
 const makeSecurityScheme = (security: HttpApiSecurity): OpenAPISecurityScheme => {