effect 4.0.0-beta.4 → 4.0.0-beta.40

package/src/unstable/httpapi/HttpApiEndpoint.ts

@@ -4,7 +4,7 @@
 import * as Arr from "../../Array.ts"
 import type { Brand } from "../../Brand.ts"
 import type { Effect } from "../../Effect.ts"
-import { format } from "../../Formatter.ts"
+import { identity } from "../../Function.ts"
 import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
@@ -16,7 +16,7 @@ import * as HttpRouter from "../http/HttpRouter.ts"
 import type { HttpServerRequest } from "../http/HttpServerRequest.ts"
 import type { HttpServerResponse } from "../http/HttpServerResponse.ts"
 import type * as Multipart from "../http/Multipart.ts"
-import { HttpApiSchemaError } from "./HttpApiError.ts"
+import { BadRequestFromSchemaError, type BadRequestNoContent } from "./HttpApiError.ts"
 import type * as HttpApiGroup from "./HttpApiGroup.ts"
 import type * as HttpApiMiddleware from "./HttpApiMiddleware.ts"
 import * as HttpApiSchema from "./HttpApiSchema.ts"
@@ -54,7 +54,7 @@ export interface HttpApiEndpoint<
   out Payload extends Schema.Top = never,
   out Headers extends Schema.Top = never,
   out Success extends Schema.Top = typeof HttpApiSchema.NoContent,
-  out Error extends Schema.Top = typeof HttpApiSchemaError,
+  out Error extends Schema.Top = typeof BadRequestNoContent,
   in out Middleware = never,
   out MiddlewareR = never
 > extends Pipeable {
@@ -71,14 +71,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 +102,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 +120,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 +156,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,12 +175,12 @@ 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
-    if (key.error !== undefined) {
-      schemas.add(key.error)
+    const key = middleware as any as HttpApiMiddleware.AnyService
+    for (const schema of key.error) {
+      schemas.add(schema)
     }
   }
-  return Arr.append(Array.from(schemas), HttpApiSchemaError)
+  return Arr.append(Array.from(schemas), BadRequestFromSchemaError)
 }
 
 /**
@@ -492,7 +477,7 @@ export type ClientRequest<
   Query extends Schema.Top,
   Payload extends Schema.Top,
   Headers extends Schema.Top,
-  WithResponse extends boolean
+  ResponseMode extends ClientResponseMode
 > = (
   & ([Params["Type"]] extends [never] ? {} : { readonly params: Params["Type"] })
   & ([Query["Type"]] extends [never] ? {} : { readonly query: Query["Type"] })
@@ -503,10 +488,16 @@ export type ClientRequest<
         ? { readonly payload: FormData }
       : { readonly payload: Payload["Type"] }
     : { readonly payload: Payload["Type"] })
-) extends infer Req ? keyof Req extends never ? (void | { readonly withResponse?: WithResponse }) :
-  Req & { readonly withResponse?: WithResponse } :
+) extends infer Req ? keyof Req extends never ? (void | { readonly responseMode?: ResponseMode }) :
+  Req & { readonly responseMode?: ResponseMode } :
   void
 
+/**
+ * @since 4.0.0
+ * @category models
+ */
+export type ClientResponseMode = "decoded-only" | "decoded-and-response" | "response-only"
+
 /**
  * @since 4.0.0
  * @category models
@@ -529,8 +520,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 +675,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 +794,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 +830,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 +855,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,53 +889,117 @@ 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
+  SuccessConstraint
 
 /**
- * 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>>
+export type PayloadConstraintCodecs<Method extends HttpMethod> = Method extends HttpMethod.NoBody ?
+  Record<string, Schema.Top> :
+  Schema.Top | ReadonlyArray<Schema.Top>
 
 /**
  * @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
  * @category constructors
  */
-export const make = <Method extends HttpMethod>(method: Method) =>
+export const make = <Method extends HttpMethod>(method: Method): {
+  <
+    const Name extends string,
+    const Path extends HttpRouter.PathInput,
+    Params extends Schema.Top | Schema.Struct.Fields = never,
+    Query extends Schema.Top | Schema.Struct.Fields = never,
+    Payload extends PayloadConstraintCodecs<Method> = never,
+    Headers extends Schema.Top | Schema.Struct.Fields = never,
+    const Success extends Schema.Top | ReadonlyArray<Schema.Top> = HttpApiSchema.NoContent,
+    const Error extends Schema.Top | ReadonlyArray<Schema.Top> = never
+  >(
+    name: Name,
+    path: Path,
+    options?: {
+      readonly disableCodecs?: false | undefined
+      readonly params?: Params | undefined
+      readonly query?: Query | undefined
+      readonly headers?: Headers | undefined
+      readonly payload?: Payload | undefined
+      readonly success?: Success | undefined
+      readonly error?: Error | undefined
+    }
+  ): HttpApiEndpoint<
+    Name,
+    Method,
+    Path,
+    StringTree<Params extends Schema.Struct.Fields ? Schema.Struct<Params> : Params>,
+    StringTree<Query extends Schema.Struct.Fields ? Schema.Struct<Query> : Query>,
+    Method extends HttpMethod.WithBody ? Json<ExtractSchemaOrArray<Payload>>
+      : StringTree<ExtractSchemaOrArray<Payload>>,
+    StringTree<Headers extends Schema.Struct.Fields ? Schema.Struct<Headers> : Headers>,
+    Json<Success extends ReadonlyArray<Schema.Top> ? Success[number] : Success>,
+    Json<(Error extends ReadonlyArray<Schema.Top> ? Error[number] : Error) | typeof BadRequestNoContent>
+  >
+  <
+    const Name extends string,
+    const Path extends HttpRouter.PathInput,
+    Params extends ParamsConstraint = 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,
+    options?: {
+      readonly disableCodecs: true
+      readonly params?: Params | undefined
+      readonly query?: Query | undefined
+      readonly headers?: Headers | undefined
+      readonly payload?: Payload | undefined
+      readonly success?: Success | undefined
+      readonly error?: Error | undefined
+    }
+  ): HttpApiEndpoint<
+    Name,
+    Method,
+    Path,
+    Params extends Schema.Struct.Fields ? Schema.Struct<Params> : Params,
+    Query extends Schema.Struct.Fields ? Schema.Struct<Query> : Query,
+    ExtractSchemaOrArray<Payload>,
+    ExtractSchemaOrArray<Headers>,
+    Success extends ReadonlyArray<Schema.Top> ? Success[number] : Success,
+    (Error extends ReadonlyArray<Schema.Top> ? Error[number] : Error) | typeof BadRequestNoContent
+  >
+} =>
 <
   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,
   options?: {
+    readonly disableCodecs?: boolean | undefined
     readonly params?: Params | undefined
     readonly query?: Query | undefined
     readonly headers?: Headers | undefined
@@ -958,38 +1018,64 @@ export const make = <Method extends HttpMethod>(method: Method) =>
     : Payload,
   Headers extends Schema.Struct.Fields ? Schema.Struct<Headers> : Headers,
   Success extends ReadonlyArray<Schema.Top> ? Success[number] : Success,
-  (Error extends ReadonlyArray<Schema.Top> ? Error[number] : Error) | typeof HttpApiSchemaError
+  (Error extends ReadonlyArray<Schema.Top> ? Error[number] : Error) | typeof BadRequestNoContent
 > => {
+  const disableCodecs = options?.disableCodecs ?? false
+  const transformStringTree = disableCodecs ? identity : Schema.toCodecStringTree
   return makeProto({
     name,
     path,
     method,
-    params: options?.params,
-    query: options?.query,
-    headers: getHeaders(options?.headers),
-    payload: getPayload(options?.payload),
-    success: getSuccess(options?.success),
-    error: getError(options?.error),
+    params: ensureStruct(options?.params, transformStringTree),
+    query: ensureStruct(options?.query, transformStringTree),
+    headers: ensureStruct(options?.headers, transformStringTree),
+    payload: getPayload(options?.payload, method, disableCodecs),
+    success: getResponse(options?.success, disableCodecs),
+    error: getResponse(options?.error, disableCodecs),
     annotations: ServiceMap.empty(),
     middlewares: new Set()
   })
 }
 
-// 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
-  }
+type ExtractSchemaOrArray<S extends Schema.Struct.Fields | Schema.Top | ReadonlyArray<Schema.Top>> = S extends
+  Schema.Struct.Fields ? Schema.Struct<S>
+  : S extends ReadonlyArray<Schema.Top> ? S[number]
+  : S
+
+/**
+ * @since 4.0.0
+ * @category Codecs
+ */
+export interface Json<S extends Schema.Top>
+  extends Schema.Codec<S["Type"], Schema.Json, S["DecodingServices"], S["EncodingServices"]>
+{}
+
+/**
+ * @since 4.0.0
+ * @category Codecs
+ */
+export interface StringTree<S extends Schema.Top> extends
+  Schema.Codec<
+    S["Type"],
+    Schema.StringTree,
+    S["DecodingServices"],
+    S["EncodingServices"]
+  >
+{}
+
+function ensureStruct(
+  params: Schema.Struct.Fields | Schema.Top | undefined,
+  transform: typeof Schema.toCodecJson | typeof Schema.toCodecStringTree
+): Schema.Top | undefined {
+  if (params === undefined) return undefined
+  if (Schema.isSchema(params)) return transform(params)
+  return transform(Schema.Struct(params))
 }
 
 function getPayload(
-  payload: Schema.Top | ReadonlyArray<Schema.Top> | Schema.Struct.Fields | undefined
+  payload: Schema.Top | ReadonlyArray<Schema.Top> | Schema.Struct.Fields | undefined,
+  method: HttpMethod,
+  disableCodecs: boolean
 ): PayloadMap {
   const result: Map<string, { encoding: HttpApiSchema.PayloadEncoding; schemas: [Schema.Top, ...Array<Schema.Top>] }> =
     new Map()
@@ -998,9 +1084,11 @@ function getPayload(
     ? payload
     : Schema.isSchema(payload)
     ? [payload]
-    : [Schema.Struct(payload as any).pipe(HttpApiSchema.asFormUrlEncoded())]
+    : [(Schema.Struct(payload as any)).pipe(HttpApiSchema.asFormUrlEncoded())]
+  const transform = disableCodecs ? identity : transformPayload
+
   for (const schema of schemas) {
-    const encoding = HttpApiSchema.getPayloadEncoding(schema.ast)
+    const encoding = HttpApiSchema.getPayloadEncoding(schema.ast, method)
     const existing = result.get(encoding.contentType)
     if (existing) {
       if (existing.encoding._tag !== encoding._tag) {
@@ -1009,24 +1097,48 @@ function getPayload(
       if (existing.encoding._tag === "Multipart") {
         throw new Error(`Multiple multipart payloads for content-type: ${encoding.contentType}`)
       }
-      existing.schemas.push(schema)
+      existing.schemas.push(transform(schema, method))
     } else {
-      result.set(encoding.contentType, { encoding, schemas: [schema] })
+      result.set(encoding.contentType, { encoding, schemas: [transform(schema, method)] })
     }
   }
   return result
 }
 
-function getSuccess(
-  success: Schema.Top | ReadonlyArray<Schema.Top> | undefined
+function getResponse(
+  success: Schema.Top | ReadonlyArray<Schema.Top> | undefined,
+  disableCodecs: boolean
 ): Set<Schema.Top> {
   if (success === undefined) return new Set()
-  return new Set(Array.isArray(success) ? success : [success])
+  const arr = Arr.ensure(success)
+  return new Set(disableCodecs ? arr : arr.map(transformResponse))
 }
 
-function getError(error: Schema.Top | ReadonlyArray<Schema.Top> | undefined): Set<Schema.Top> {
-  if (error === undefined) return new Set()
-  return new Set(Array.isArray(error) ? error : [error])
+function transformResponse(schema: Schema.Top): Schema.Top {
+  const encoding = HttpApiSchema.getResponseEncoding(schema.ast)
+  switch (encoding._tag) {
+    case "Json":
+      return Schema.toCodecJson(schema)
+    case "FormUrlEncoded":
+      return Schema.toCodecStringTree(schema)
+    case "Text":
+    case "Uint8Array":
+      return schema
+  }
+}
+
+function transformPayload(schema: Schema.Top, method: HttpMethod): Schema.Top {
+  const encoding = HttpApiSchema.getPayloadEncoding(schema.ast, method)
+  switch (encoding._tag) {
+    case "Json":
+      return Schema.toCodecJson(schema)
+    case "FormUrlEncoded":
+      return Schema.toCodecStringTree(schema)
+    case "Text":
+    case "Uint8Array":
+    case "Multipart":
+      return schema
+  }
 }
 
 /**