@@ -54,7 +54,7 @@ declare module "../Schema.ts" {
5454 */
5555export interface WithHeadersAnnotation {
5656 readonly body: Schema.Top
57- readonly headers: Schema.Top
57+ readonly headers: Schema.Struct<Schema.Struct.Fields>
5858 /**
5959 * Codecs from the body and headers types to their response representation.
6060 * `HttpApiEndpoint` replaces them with the response encoding codecs.
@@ -1458,6 +1458,44 @@ const resolveHttpApiEncoding = SchemaAST.resolveAt<Encoding>("~httpApiEncoding")
14581458 */
14591459export const getWithHeadersAnnotation = SchemaAST.resolveAt<WithHeadersAnnotation>("~httpApiWithHeaders")
14601460
1461+ /**
1462+ * Returns the declared body and headers schemas of an `encodeToWithHeaders`
1463+ * response, or `undefined` for any other schema.
1464+ *
1465+ * **When to use**
1466+ *
1467+ * Use to inspect response schemas for code generation before a response exists,
1468+ * including schemas obtained through `HttpApi.reflect`.
1469+ *
1470+ * **Details**
1471+ *
1472+ * Both schemas keep their declared identity through endpoint construction and
1473+ * reflection, with or without `disableCodecs`. The headers schema is a
1474+ * `Schema.Struct`, so its fields can be inspected directly.
1475+ *
1476+ * **Gotchas**
1477+ *
1478+ * These are declared schemas, not the response codecs installed by an endpoint.
1479+ * Plain schemas, `WithHeaders` wrappers, and ordinary transformations from an
1480+ * identical `{ body, headers }` struct return `undefined`. So do schemas derived
1481+ * from the result with operations such as `.check`, `Schema.Union`, or
1482+ * `Schema.decodeTo` with a target that lacks this metadata, while `.annotate`,
1483+ * `Schema.brand`, and `Schema.decode` keep the parts.
1484+ *
1485+ * @see encodeToWithHeaders
1486+ * @see getResponseEncodingSchema
1487+ * @stability unstable
1488+ * @category getters
1489+ * @since 4.1.4
1490+ */
1491+ export function getEncodeToWithHeadersParts(schema: Schema.Constraint): {
1492+ readonly body: Schema.Top
1493+ readonly headers: Schema.Struct<Schema.Struct.Fields>
1494+ } | undefined {
1495+ const annotation = getWithHeadersAnnotation(schema.ast)
1496+ return annotation === undefined ? undefined : { body: annotation.body, headers: annotation.headers }
1497+ }
1498+
14611499function findHttpApiStatusAnnotation(
14621500 ast: SchemaAST.AST | SchemaAST.FilterGroup<any>
14631501): Schema.Annotations.Annotations | undefined {
@@ -1533,7 +1571,35 @@ export function getStatusSuccessSchema(schema: Schema.Constraint): number {
15331571}
15341572
15351573/**
1536- * @internal
1574+ * Returns the buffered response encoding resolved from a schema's annotations,
1575+ * defaulting to `{ _tag: "Json", contentType: "application/json" }`.
1576+ *
1577+ * **When to use**
1578+ *
1579+ * Use to read response media types from declared schemas or schemas obtained
1580+ * through `HttpApi.reflect` without encoding a response value.
1581+ *
1582+ * **Details**
1583+ *
1584+ * For `WithHeaders`, the wrapper's encoding takes precedence over the inner
1585+ * schema's encoding. For `encodeToWithHeaders`, the body schema's encoding is
1586+ * used. Re-annotating the result changes what this function returns, not what
1587+ * the server sends.
1588+ *
1589+ * **Gotchas**
1590+ *
1591+ * - No-content schemas also receive the JSON default. Check `isNoContent` on
1592+ * the body AST first: `schema.schema.ast` for `WithHeaders`, `parts.body.ast`
1593+ * from `getEncodeToWithHeadersParts`, or `schema.ast` otherwise.
1594+ * - Streaming and upgrade schemas are outside this buffered-response contract;
1595+ * their JSON fallback does not describe their wire representation.
1596+ * - Multipart encoding throws because multipart responses are not supported.
1597+ *
1598+ * @see getEncodeToWithHeadersParts
1599+ * @see isNoContent
1600+ * @stability unstable
1601+ * @category getters
1602+ * @since 4.1.4
15371603 */
15381604export function getResponseEncodingSchema(schema: Schema.Constraint): ResponseEncoding {
15391605 if (isWithHeaders(schema) && resolveHttpApiEncoding(schema.ast) === undefined) {
0 commit comments