effect 4.0.5 → 4.0.7

package/src/http-api/HttpApiClient.ts

@@ -12,11 +12,14 @@
  * @since 4.0.0
  */
 import * as Arr from "../Array.ts"
+import * as ByteSize from "../ByteSize.ts"
 import * as Cause from "../Cause.ts"
 import type * as Context from "../Context.ts"
 import * as Effect from "../Effect.ts"
+import * as Ndjson from "../encoding/Ndjson.ts"
 import * as Sse from "../encoding/Sse.ts"
 import { identity } from "../Function.ts"
+import type * as Headers from "../http/Headers.ts"
 import * as HttpBody from "../http/HttpBody.ts"
 import * as HttpClient from "../http/HttpClient.ts"
 import * as HttpClientError from "../http/HttpClientError.ts"
@@ -31,6 +34,7 @@ import * as Schema from "../Schema.ts"
 import * as SchemaAST from "../SchemaAST.ts"
 import * as SchemaIssue from "../SchemaIssue.ts"
 import * as SchemaTransformation from "../SchemaTransformation.ts"
+import type * as Socket from "../socket/Socket.ts"
 import * as Stream from "../Stream.ts"
 import type { Simplify } from "../Types.ts"
 import * as UndefinedOr from "../UndefinedOr.ts"
@@ -96,9 +100,32 @@ export type SuccessType<S> = S extends HttpApiSchema.WithHeaders<
       never
     >
   : S extends HttpApiSchema.StreamUint8Array ? Stream.Stream<Uint8Array, HttpClientError.HttpClientError, never>
+  : S extends HttpApiSchema.StreamNdjson<infer _S> ?
+    Stream.Stream<_S["Type"], HttpClientError.HttpClientError | Schema.SchemaError, never>
+  : S extends HttpApiSchema.Upgrade<infer _Headers> ? [_Headers] extends [never] ? Upgraded : Upgraded<_Headers["Type"]>
   : S extends Schema.Constraint ? S["Type"]
   : never
 
+/**
+ * The value a client method returns for an endpoint declared with
+ * `HttpApiSchema.Upgrade`: the headers of the `101 Switching Protocols`
+ * response and the upgraded connection.
+ *
+ * **Details**
+ *
+ * `headers` is decoded with the upgrade's `headers` schema when it declares
+ * one. See `HttpClientResponse.upgrade` for how the connection behaves and
+ * when it closes.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface Upgraded<Headers = Headers.Headers> {
+  readonly headers: Headers
+  readonly socket: Socket.Socket
+}
+
 type SuccessDecodingServices<S> = S extends HttpApiSchema.StreamSse<
   infer _Events,
   infer _Error,
@@ -107,9 +134,17 @@ type SuccessDecodingServices<S> = S extends HttpApiSchema.StreamSse<
     | _Events["DecodingServices"]
     | _Error["DecodingServices"]
   : S extends HttpApiSchema.StreamUint8Array ? never
+  : S extends HttpApiSchema.StreamNdjson<infer _S> ? _S["DecodingServices"]
+  : S extends HttpApiSchema.Upgrade<infer _Headers> ? _Headers["DecodingServices"]
   : S extends Schema.Constraint ? S["DecodingServices"]
   : never
 
+// An uninferred type parameter is instantiated with its constraint, so methods
+// without a streaming payload must constrain `PayloadR` to `never`. `StreamNdjson<any>`
+// also matches item schemas that are only a `Schema.Constraint` (`disableCodecs`)
+type PayloadServicesConstraint<Payload> =
+  [Extract<Payload, HttpApiSchema.StreamUint8Array | HttpApiSchema.StreamNdjson<any>>] extends [never] ? never : unknown
+
 /**
  * Helper types used to describe generated HTTP API clients, including endpoint
  * methods, response modes, and grouped client shapes.
@@ -161,7 +196,8 @@ export declare namespace Client {
     Endpoint extends HttpApiEndpoint.ConstraintRequest,
     E,
     R,
-    Mode extends ResponseMode
+    Mode extends ResponseMode,
+    PayloadR
   > = Effect.Effect<
     Response<SuccessType<Endpoint["~Success"]>, Mode>,
     | HttpApiMiddleware.Error<Endpoint["~Middleware"]>
@@ -170,6 +206,7 @@ export declare namespace Client {
     | HttpClientError.HttpClientError
     | ([Mode] extends ["response-only"] ? never : Endpoint["~Error"]["Type"] | Schema.SchemaError),
     | R
+    | PayloadR
     | Endpoint["~Params"]["EncodingServices"]
     | Endpoint["~Query"]["EncodingServices"]
     | Endpoint["~Payload"]["EncodingServices"]
@@ -186,6 +223,11 @@ export declare namespace Client {
    * error, and service channels reflect the endpoint schemas, middleware, and
    * selected response mode.
    *
+   * **Details**
+   *
+   * The services of a streaming `payload` are inferred and added to the
+   * returned effect.
+   *
    * @stability unstable
    * @category models
    * @since 4.0.0
@@ -194,17 +236,21 @@ export declare namespace Client {
     Endpoint extends HttpApiEndpoint.ConstraintRequest,
     E,
     R
-  > = <Mode extends ResponseMode = "decoded-only">(
+  > = <
+    Mode extends ResponseMode = "decoded-only",
+    PayloadR extends PayloadServicesConstraint<Endpoint["~Payload"]> = never
+  >(
     request: Simplify<
       HttpApiEndpoint.ClientRequest<
         Endpoint["~Params"],
         Endpoint["~Query"],
         Endpoint["~Payload"],
         Endpoint["~Headers"],
-        Mode
+        Mode,
+        PayloadR
       >
     >
-  ) => MethodReturn<Endpoint, E, R, Mode>
+  ) => MethodReturn<Endpoint, E, R, Mode, NoInfer<PayloadR>>
 
   /**
    * Extracts client methods for endpoints in top-level groups so they can be exposed
@@ -352,73 +398,30 @@ export const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Con
         options.onGroup?.(onGroupOptions)
       },
       onEndpoint(onEndpointOptions) {
-        const { group, endpoint, errors, successes, mergedAnnotations } = onEndpointOptions
+        const { group, endpoint, mergedAnnotations } = onEndpointOptions
         const parseOptions = HttpApi.getSlotParseOptions(mergedAnnotations)
         const makeUrl = compilePath(endpoint.path, endpoint.params)
-        const decodeMap: Record<number | "orElse", ResponseDecoder> = { orElse: statusOrElse }
-        const errorAlternatives = new Map<number, Array<ResponseAlternative>>()
-        for (const [status, schemas] of errors.entries()) {
-          const grouped = groupSchemasByContentType(schemas)
-          for (const [contentType, schemas] of grouped.entries()) {
-            addResponseAlternative(
-              errorAlternatives,
-              status,
-              contentType,
-              schemasToResponse(schemas, parseOptions.error, parseOptions.headers)
-            )
-          }
-        }
-        for (const [status, alternatives] of errorAlternatives.entries()) {
-          const decode = makeResponseDecoder(alternatives)
-          decodeMap[status] = (response) =>
-            Effect.flatMap(
-              Effect.catchCause(decode(response), (cause) =>
-                Effect.failCause(Cause.combine(
-                  Cause.fail(
-                    new HttpClientError.HttpClientError({
-                      reason: new HttpClientError.StatusCodeError({
-                        request: response.request,
-                        response
-                      })
-                    })
-                  ),
-                  cause
-                ))),
-              Effect.fail
-            )
-        }
-
-        const successAlternatives = new Map<number, Array<ResponseAlternative>>()
-        for (const [status, schemas] of successes.entries()) {
-          const grouped = groupSchemasByContentType(schemas)
-          for (const [contentType, schemas] of grouped.entries()) {
-            addResponseAlternative(
-              successAlternatives,
-              status,
-              contentType,
-              schemasToResponse(schemas, parseOptions.success, parseOptions.headers)
-            )
-          }
-        }
-        for (const streamSuccess of getStreamSuccessSchemas(endpoint)) {
-          const streamSchema = isWithHeadersStreamSuccess(streamSuccess) ? streamSuccess.schema : streamSuccess
-          addResponseAlternative(
-            successAlternatives,
-            HttpApiSchema.getStatusSuccessSchema(streamSuccess),
-            streamSchema.contentType,
-            streamToResponse(streamSuccess, parseOptions.success, parseOptions.headers)
-          )
-        }
-        for (const [status, alternatives] of successAlternatives.entries()) {
-          decodeMap[status] = makeResponseDecoder(alternatives)
-        }
+        const upgrade = getUpgradeSuccessSchema(endpoint)
+        const decodeEndpointResponse = makeEndpointDecoder(onEndpointOptions)
 
         const encodeParams = UndefinedOr.map(
           endpoint.params,
           (schema) => Schema.encodeUnknownEffect(schema, parseOptions.params)
         )
 
-        const payloadSchemas = HttpApiEndpoint.getPayloadSchemas(endpoint)
+        const payloadSchemas: Array<Schema.Top> = []
+        let streamPayload: StreamPayloadSchema | undefined
+        for (const schema of HttpApiEndpoint.getPayloadSchemas(endpoint)) {
+          if (HttpApiSchema.isStreamUint8Array(schema) || HttpApiSchema.isStreamNdjson(schema)) {
+            streamPayload = schema
+          } else {
+            payloadSchemas.push(schema)
+          }
+        }
+        const streamPayloadEncoder = UndefinedOr.map(streamPayload, (schema) => ({
+          contentType: schema.contentType,
+          encode: makeStreamPayloadEncoder(schema, parseOptions.payload)
+        }))
         const encodePayload = Arr.isArrayNonEmpty(payloadSchemas) ?
           Schema.encodeUnknownEffect(
             HttpMethod.hasBody(endpoint.method)
@@ -459,7 +462,19 @@ export const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Con
             }
 
             // payload
-            if (encodePayload !== undefined) {
+            if (streamPayloadEncoder !== undefined && Stream.isStream(request.payload)) {
+              const context = yield* Effect.context<never>()
+              httpRequest = HttpClientRequest.setBody(
+                httpRequest,
+                HttpBody.stream(
+                  Stream.provideContext(
+                    streamPayloadEncoder.encode(request.payload),
+                    context as Context.Context<unknown>
+                  ),
+                  streamPayloadEncoder.contentType
+                )
+              )
+            } else if (encodePayload !== undefined) {
               if (HttpMethod.hasBody(endpoint.method)) {
                 if (request.payload instanceof FormData) {
                   httpRequest = HttpClientRequest.bodyFormData(httpRequest, request.payload)
@@ -471,6 +486,10 @@ export const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Con
                 const urlParams = (yield* encodePayload(request.payload)) as Record<string, string>
                 httpRequest = HttpClientRequest.appendUrlParams(httpRequest, urlParams)
               }
+            } else if (streamPayloadEncoder !== undefined) {
+              return yield* new Schema.SchemaError(
+                new SchemaIssue.InvalidValue({ message: "Expected a Stream payload" }, request.payload)
+              )
             }
 
             // headers
@@ -486,6 +505,10 @@ export const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Con
             }
           }
 
+          if (upgrade !== undefined) {
+            httpRequest = HttpClientRequest.upgrade(httpRequest, upgrade.protocol)
+          }
+
           const response = yield* executeMiddleware(
             group,
             endpoint,
@@ -498,7 +521,7 @@ export const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Con
             return response
           }
 
-          const decoded = (decodeMap[response.status] ?? decodeMap.orElse)(response, request?.sseOptions)
+          const decoded = decodeEndpointResponse(response, request?.sseOptions)
           const value = yield* (options.transformResponse === undefined
             ? decoded
             : options.transformResponse(decoded))
@@ -676,6 +699,111 @@ export const endpoint = <
   }).pipe(Effect.map(() => client)) as any
 }
 
+type DecodeResponse<
+  Groups extends HttpApiGroup.Constraint,
+  GroupIdentifier extends HttpApiGroup.Identifier<Groups>,
+  EndpointIdentifier extends HttpApiGroup.EndpointsWithIdentifier<Groups, GroupIdentifier>["identifier"],
+  Endpoint extends HttpApiEndpoint.ConstraintRequest = Extract<
+    HttpApiEndpoint.WithIdentifier<HttpApiGroup.EndpointsWithIdentifier<Groups, GroupIdentifier>, EndpointIdentifier>,
+    HttpApiEndpoint.ConstraintRequest
+  >
+> = (
+  response: HttpClientResponse.HttpClientResponse,
+  options?: {
+    readonly sseOptions?: Sse.DecodeOptions | undefined
+  }
+) => Effect.Effect<
+  SuccessType<Endpoint["~Success"]>,
+  HttpApiEndpoint.Errors<Endpoint> | HttpClientError.HttpClientError | Schema.SchemaError,
+  SuccessDecodingServices<Endpoint["~Success"]> | HttpApiEndpoint.ErrorServicesDecode<Endpoint>
+>
+
+/**
+ * Builds a decoder for raw responses of one endpoint in one API group, using
+ * the same success and error decoding as a generated client method in
+ * `"decoded-only"` mode.
+ *
+ * **When to use**
+ *
+ * Use with `responseMode: "response-only"` when the response head and body
+ * arrive at different times, such as long polling, and the body should be
+ * decoded later.
+ *
+ * **Details**
+ *
+ * The response does not need to come from a generated client. Declared error
+ * responses fail with the decoded error, and undeclared statuses fail with an
+ * `HttpClientError` whose reason is a `DecodeError`. Parse options are resolved
+ * from the API, group and endpoint annotations. The body is only read when the
+ * returned effect runs, so it must run inside the scope that owns the response.
+ * Middleware and `transformResponse` are not applied.
+ *
+ * Building the decoder walks the API declaration, so build it once per
+ * endpoint and reuse it.
+ *
+ * **Example** (Decoding a response body after the head arrives)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Schema } from "effect"
+ * import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/http-api"
+ *
+ * const Api = HttpApi.make("Api").add(
+ *   HttpApiGroup.make("containers").add(
+ *     HttpApiEndpoint.post("wait", "/containers/:id/wait", {
+ *       params: { id: Schema.String },
+ *       success: Schema.Struct({ StatusCode: Schema.Number })
+ *     })
+ *   )
+ * )
+ *
+ * const decodeWait = HttpApiClient.decodeResponse(Api, {
+ *   group: "containers",
+ *   endpoint: "wait"
+ * })
+ *
+ * const program = Effect.gen(function*() {
+ *   const client = yield* HttpApiClient.make(Api)
+ *   // Succeeds as soon as the response head arrives
+ *   const response = yield* client.containers.wait({
+ *     params: { id: "my-container" },
+ *     responseMode: "response-only"
+ *   })
+ *   // Waits for the body, then decodes it with the endpoint schemas
+ *   return yield* decodeWait(response)
+ * })
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.7
+ */
+export const decodeResponse = <
+  ApiId extends string,
+  Groups extends HttpApiGroup.Constraint,
+  const GroupIdentifier extends HttpApiGroup.Identifier<Groups>,
+  const EndpointIdentifier extends HttpApiGroup.EndpointsWithIdentifier<Groups, GroupIdentifier>["identifier"]
+>(
+  api: HttpApi.HttpApi<ApiId, Groups>,
+  options: {
+    readonly group: GroupIdentifier
+    readonly endpoint: EndpointIdentifier
+  }
+): DecodeResponse<Groups, GroupIdentifier, EndpointIdentifier> => {
+  let decode: ResponseDecoder | undefined
+  HttpApi.reflect(api, {
+    predicate: ({ endpoint, group }) => group.identifier === options.group && endpoint.identifier === options.endpoint,
+    onGroup() {},
+    onEndpoint(endpointOptions) {
+      decode = makeEndpointDecoder(endpointOptions)
+    }
+  })
+  return ((response, decodeOptions) => decode!(response, decodeOptions?.sseOptions)) as DecodeResponse<
+    Groups,
+    GroupIdentifier,
+    EndpointIdentifier
+  >
+}
+
 /**
  * Creates a type-safe URL builder that mirrors `HttpApiClient.make`.
  *
@@ -765,28 +893,22 @@ export const urlBuilder = <Api extends HttpApi.Constraint>(api: Api, options?: {
 
 // ----------------------------------------------------------------------------
 
-const paramsRegExp = /(\/?):(\w+)(\?)?/g
-
 const compilePath = (path: string, schema: Schema.Top | undefined) => {
   if (schema === undefined || !path.includes(":")) {
     return (_: any) => path
   }
   const paramNames = HttpApiPath.getParamNames(schema)
-  return (params: Record<string, string | undefined>) => {
-    return path.replace(paramsRegExp, (match, slash: string, key: string, optional: string | undefined) => {
-      if (paramNames !== undefined && !paramNames.has(key)) {
-        return match
-      }
+  return (params: Record<string, string | undefined>) =>
+    HttpApiPath.replaceParams(path, paramNames, (key, optional) => {
       const value = params[key]
-      if (value === undefined) {
-        if (optional !== undefined) {
-          return ""
-        }
-        throw new Error(`Missing path parameter: ${key}`)
+      if (value === "." || value === "..") {
+        // dot segments survive encoding and would be resolved by URL normalization
+        throw new Error(`Invalid path parameter: ${key}`)
       }
-      return `${slash}${encodeURIComponent(value)}`
+      if (value !== undefined) return encodeURIComponent(value)
+      if (optional) return undefined
+      throw new Error(`Missing path parameter: ${key}`)
     })
-  }
 }
 
 function schemasToResponse(
@@ -845,6 +967,91 @@ function toCodecArrayBufferWithHeaders(
   ))
 }
 
+const makeEndpointDecoder = (options: {
+  readonly endpoint: HttpApiEndpoint.Top
+  readonly mergedAnnotations: Context.Context<never>
+  readonly successes: ReadonlyMap<number, readonly [Schema.Top, ...Array<Schema.Top>]>
+  readonly errors: ReadonlyMap<number, readonly [Schema.Top, ...Array<Schema.Top>]>
+}): ResponseDecoder => {
+  const { endpoint, errors, successes, mergedAnnotations } = options
+  const parseOptions = HttpApi.getSlotParseOptions(mergedAnnotations)
+  const decodeMap: Record<number | "orElse", ResponseDecoder> = { orElse: statusOrElse }
+  const errorAlternatives = new Map<number, Array<ResponseAlternative>>()
+  for (const [status, schemas] of errors.entries()) {
+    const grouped = groupSchemasByContentType(schemas)
+    for (const [contentType, schemas] of grouped.entries()) {
+      addResponseAlternative(
+        errorAlternatives,
+        status,
+        contentType,
+        schemasToResponse(schemas, parseOptions.error, parseOptions.headers)
+      )
+    }
+  }
+  for (const [status, alternatives] of errorAlternatives.entries()) {
+    const decode = makeResponseDecoder(alternatives)
+    decodeMap[status] = (response) =>
+      Effect.flatMap(
+        Effect.catchCause(decode(response), (cause) =>
+          Effect.failCause(Cause.combine(
+            Cause.fail(
+              new HttpClientError.HttpClientError({
+                reason: new HttpClientError.StatusCodeError({
+                  request: response.request,
+                  response
+                })
+              })
+            ),
+            cause
+          ))),
+        Effect.fail
+      )
+  }
+
+  const successAlternatives = new Map<number, Array<ResponseAlternative>>()
+  for (const [status, schemas] of successes.entries()) {
+    const grouped = groupSchemasByContentType(schemas)
+    for (const [contentType, schemas] of grouped.entries()) {
+      addResponseAlternative(
+        successAlternatives,
+        status,
+        contentType,
+        schemasToResponse(schemas, parseOptions.success, parseOptions.headers)
+      )
+    }
+  }
+  for (const streamSuccess of getStreamSuccessSchemas(endpoint)) {
+    const streamSchema = isWithHeadersStreamSuccess(streamSuccess) ? streamSuccess.schema : streamSuccess
+    const status = HttpApiSchema.getStatusSuccessSchema(streamSuccess)
+    const decode = streamToResponse(streamSuccess, parseOptions.success, parseOptions.headers)
+    for (const contentType of streamSchema.contentTypes) {
+      addResponseAlternative(successAlternatives, status, contentType, decode)
+    }
+  }
+  for (const [status, alternatives] of successAlternatives.entries()) {
+    decodeMap[status] = makeResponseDecoder(alternatives)
+  }
+  const upgrade = getUpgradeSuccessSchema(endpoint)
+  if (upgrade !== undefined) {
+    const decodeHeaders = upgrade.headers === undefined
+      ? Effect.succeed
+      : Schema.decodeUnknownEffect(upgrade.headers, parseOptions.headers)
+    decodeMap[101] = (response) =>
+      // the cleanup must be in place before an interruption can be observed
+      Effect.uninterruptibleMask((restore) =>
+        Effect.flatMap(response.upgrade, (socket) =>
+          restore(decodeHeaders(response.headers)).pipe(
+            Effect.map((headers): Upgraded<unknown> => ({ headers, socket })),
+            // nothing takes the connection on failure, so close it: releasing
+            // the reader's scope closes the connection
+            Effect.onError(() => Effect.ignore(Effect.scoped(socket.reader)))
+          ))
+      )
+  }
+
+  return (response, sseOptions) => (decodeMap[response.status] ?? decodeMap.orElse)(response, sseOptions)
+}
+
 type ResponseDecoder = (
   response: HttpClientResponse.HttpClientResponse,
   sseOptions?: Sse.DecodeOptions
@@ -872,7 +1079,7 @@ function addResponseAlternative(
 
 function makeResponseDecoder(alternatives: ReadonlyArray<ResponseAlternative>): ResponseDecoder {
   const first = alternatives[0]
-  if (alternatives.length === 1 && first !== undefined) {
+  if (first !== undefined && alternatives.every((alternative) => alternative.decode === first.decode)) {
     return first.decode
   }
   return (response, sseOptions) => {
@@ -932,6 +1139,12 @@ const isWithHeadersStreamSuccess = (
   schema: StreamSuccessSchema
 ): schema is HttpApiSchema.WithHeaders<HttpApiSchema.StreamSchema, Schema.Top> => HttpApiSchema.isWithHeaders(schema)
 
+function getUpgradeSuccessSchema(endpoint: HttpApiEndpoint.Top): HttpApiSchema.Upgrade | undefined {
+  for (const schema of endpoint.success) {
+    if (HttpApiSchema.isUpgrade(schema)) return schema
+  }
+}
+
 function getStreamSuccessSchemas(endpoint: HttpApiEndpoint.Top): Array<StreamSuccessSchema> {
   const schemas: Array<StreamSuccessSchema> = []
   for (const schema of endpoint.success) {
@@ -950,18 +1163,11 @@ function streamToResponse(
 ) {
   const isWithHeaders = isWithHeadersStreamSuccess(successSchema)
   const streamSchema = isWithHeaders ? successSchema.schema : successSchema
-  const sse = HttpApiSchema.isStreamUint8Array(streamSchema)
-    ? undefined
-    : {
-      declaration: streamSchema,
-      decoder: makeSseDecoder(streamSchema, options)
-    }
+  const decodeBody = makeStreamBodyDecoder(streamSchema, options)
   const toStream: ResponseDecoder = (response, sseOptions) =>
     Effect.map(Effect.context<never>(), (context) =>
       Stream.provideContext(
-        sse === undefined ?
-          response.stream :
-          decodeSseStream(response.stream, sse.declaration, sse.decoder(sseOptions)),
+        decodeBody(response, sseOptions),
         context as Context.Context<unknown>
       ))
   if (!isWithHeaders) return toStream
@@ -974,6 +1180,55 @@ function streamToResponse(
     )
 }
 
+function makeStreamBodyDecoder(
+  streamSchema: HttpApiSchema.StreamSchema,
+  options: SchemaAST.ParseOptions | undefined
+): (
+  response: HttpClientResponse.HttpClientResponse,
+  sseOptions: Sse.DecodeOptions | undefined
+) => Stream.Stream<unknown, unknown, unknown> {
+  if (HttpApiSchema.isStreamUint8Array(streamSchema)) {
+    return (response) => response.stream
+  }
+  if (HttpApiSchema.isStreamNdjson(streamSchema)) {
+    const decodeElement = Schema.decodeUnknownEffect(Schema.toCodecJson(streamSchema.schema), options)
+    const maxElementBytes = ByteSize.toNumberUnsafe(streamSchema.maxElementBytes)
+    return (response) =>
+      response.stream.pipe(
+        Stream.pipeThroughChannel(Ndjson.decode({ ignoreEmptyLines: true, maxLineBytes: maxElementBytes })),
+        Stream.mapError((error) => {
+          if (!Ndjson.isNdjsonError(error)) return error
+          if (error.reason !== "LineTooLarge") return ndjsonSchemaError(error)
+          return new HttpClientError.HttpClientError({
+            reason: new HttpClientError.DecodeError({
+              request: response.request,
+              response,
+              description: `NDJSON line exceeds maxElementBytes of ${maxElementBytes} bytes`
+            })
+          })
+        }),
+        Stream.mapEffect((json) => decodeElement(json))
+      )
+  }
+  const decoder = makeSseDecoder(streamSchema, options)
+  return (response, sseOptions) => decodeSseStream(response.stream, streamSchema, decoder(sseOptions))
+}
+
+// `JSON.stringify` found no JSON representation for an encoded element
+const isNdjsonPackError = (error: unknown): error is Ndjson.NdjsonError =>
+  Ndjson.isNdjsonError(error) && error.kind === "Pack"
+
+const ndjsonSchemaError = (error: Ndjson.NdjsonError): Schema.SchemaError =>
+  new Schema.SchemaError(
+    new SchemaIssue.InvalidValue({
+      message: error.reason === "InvalidUtf8"
+        ? "Expected valid UTF-8"
+        : error.unterminated
+        ? "Expected a valid JSON line, got an unterminated final line"
+        : "Expected a valid JSON line"
+    })
+  )
+
 function makeSseDecoder(
   declaration: HttpApiSchema.StreamSse<Sse.EventCodec, Schema.Constraint, unknown>,
   parseOptions: SchemaAST.ParseOptions | undefined
@@ -1131,13 +1386,32 @@ const statusOrElse = (response: HttpClientResponse.HttpClientResponse) =>
     new HttpClientError.HttpClientError({
       reason: new HttpClientError.DecodeError({
         request: response.request,
-        response
+        response,
+        description: "undeclared status code"
       })
     })
   )
 
 const $HttpBody = Schema.declare(HttpBody.isHttpBody)
 
+type StreamPayloadSchema = HttpApiSchema.StreamUint8Array | HttpApiSchema.StreamNdjson<Schema.Top>
+
+function makeStreamPayloadEncoder(
+  schema: StreamPayloadSchema,
+  options: SchemaAST.ParseOptions | undefined
+): (stream: Stream.Stream<unknown, unknown, unknown>) => Stream.Stream<Uint8Array, unknown, unknown> {
+  if (HttpApiSchema.isStreamUint8Array(schema)) {
+    return (stream) => stream as Stream.Stream<Uint8Array, unknown, unknown>
+  }
+  const encodeElements = Schema.encodeUnknownEffect(Schema.NonEmptyArray(Schema.toCodecJson(schema.schema)), options)
+  return (stream) =>
+    stream.pipe(
+      Stream.mapArrayEffect((elements) => encodeElements(elements)),
+      Stream.pipeThroughChannel(Ndjson.encode()),
+      Stream.catchIf(isNdjsonPackError, Stream.die)
+    )
+}
+
 function getEncodePayloadSchema(
   schemas: readonly [Schema.Constraint, ...Array<Schema.Constraint>],
   method: HttpMethod.HttpMethod