galbe 0.15.6 → 0.16.0

package/src/util.ts

@@ -1,7 +1,7 @@
-import type { Method, Route, RouteNode } from '.'
+import type { GalbeMiddleware, Method, Route, RouteNode } from '.'
 import type { RouteFileMeta, RouteMeta } from './routes'
 
-const METHOD_COLOR: Record<string, string> = {
+export const METHOD_COLOR: Record<string, string> = {
   get: '\x1b[32m',
   post: '\x1b[34m',
   put: '\x1b[36m',
@@ -26,6 +26,75 @@ export const softMerge = <T>(base: T, override: T): T => {
   }
   return base
 }
+/**
+ * Split a route's JSDoc head into its `summary`/`description` pair: the first
+ * paragraph is the summary, whatever follows the first blank line is the
+ * description. A head with no blank line is a summary alone — the single
+ * source of truth for every consumer (route log, OpenAPI spec).
+ */
+export const splitHead = (head?: string): { summary?: string; description?: string } => {
+  if (!head) return {}
+  const blank = head.indexOf('\n\n')
+  if (blank === -1) {
+    const nl = head.indexOf('\n')
+    return { summary: (nl === -1 ? head : head.slice(0, nl)).trim() || undefined }
+  }
+  return {
+    summary: head.slice(0, blank).trim() || undefined,
+    description: head.slice(blank + 2).trim() || undefined,
+  }
+}
+/**
+ * An operation's `summary` / `description` pair. The JSDoc head is the default
+ * — first paragraph is the summary, whatever follows the first blank line is
+ * the description — and an explicit `@summary` / `@description` tag overrides
+ * its half of it. A bare `@summary` with no text means "explicitly no summary",
+ * which is the one way to write a description without one.
+ *
+ * Repeated `@description` lines join into a multi-line description; a repeated
+ * `@summary` keeps the first.
+ */
+export const routeHead = (meta?: Record<string, any>): { summary?: string; description?: string } => {
+  const split = splitHead(meta?.head)
+  const first = (v: unknown) => (Array.isArray(v) ? v[0] : v)
+  const summaryTag = first(meta?.summary)
+  const descriptionTag = meta?.description
+  // a bare tag carries `true`: the author named the field and left it empty
+  const summary = summaryTag === true ? '' : typeof summaryTag === 'string' ? summaryTag.trim() : split.summary
+  const description =
+    descriptionTag === true
+      ? ''
+      : Array.isArray(descriptionTag)
+        ? descriptionTag.filter(d => typeof d === 'string').join('\n')
+        : typeof descriptionTag === 'string'
+          ? descriptionTag
+          : split.description
+  return { summary, description }
+}
+
+/** The wildcard status ranges a response map may be keyed by, as OpenAPI spells them. */
+export const RESPONSE_RANGES = ['1XX', '2XX', '3XX', '4XX', '5XX'] as const
+/** The range key covering `status` — `404` → `'4XX'`. */
+export const responseRangeOf = (status: number) => `${Math.floor(status / 100)}XX`
+/** Default descriptions for the range keys, used when a response declares none. */
+export const RESPONSE_RANGE_DESCRIPTION: Record<string, string> = {
+  '1XX': 'Informational',
+  '2XX': 'Successful',
+  '3XX': 'Redirection',
+  '4XX': 'Client error',
+  '5XX': 'Server error',
+}
+/**
+ * The response-map entry that governs `status`. Precedence is OpenAPI's: an
+ * exact status wins over the `NXX` range containing it, which wins over
+ * `default`. Every consumer of a response map resolves through this, so
+ * validation, content-type inference and the spec agree on one answer.
+ */
+export const responseEntryFor = <T>(
+  response: Partial<Record<string | number, T>> | undefined,
+  status: number
+): T | undefined => response?.[status] ?? response?.[responseRangeOf(status)] ?? response?.['default']
+
 export const logRoute = (
   r: { method: string; path: string; static?: { path: string; root: string } },
   meta?: RouteMeta,
@@ -44,11 +113,10 @@ export const logRoute = (
     if (meta?.deprecated) routeLog = `\x1b[0;9m\x1b[38;5;244m${routeLog.replaceAll(ansiRegex, '')}\x1b[0m`
   } else {
     let color = METHOD_COLOR?.[method] || ''
-    let [_, summary, _description] = meta?.head?.match(/^([^\n]*)\n\n(.*)/) || []
-    if (!summary) _description = meta?.head || ''
+    const { summary } = routeHead(meta)
     routeLog = `[${color}${`${method.toUpperCase()}\x1b[0m]`.padEnd(12, ' ')} ${path
       .padEnd(format?.maxPathLength ?? path.length, ' ')
-      .replaceAll(/:([^\/]+)/g, '\x1b[0;33m:$1\x1b[0m')}${(summary ? `  ${summary}` : '').replace(/\n/, '')}\x1b[0m`
+      .replaceAll(/:([^\/]+)/g, '\x1b[0;33m:$1\x1b[0m')}${summary ? `  ${summary.replaceAll(/\s+/g, ' ')}` : ''}\x1b[0m`
     if (meta?.deprecated) routeLog = `\x1b[0;9m\x1b[38;5;244m${routeLog.replaceAll(ansiRegex, '')}\x1b[0m`
   }
 
@@ -82,6 +150,64 @@ export const walkMetaRoutes = (
 
 export const isIterator = (obj: any) => typeof obj?.next === 'function'
 
+export const joinPath = (prefix: string, path: string) => {
+  if (prefix && prefix[0] !== '/') prefix = `/${prefix}`
+  prefix = prefix.replace(/\/+$/, '')
+  return `${prefix}${path[0] === '/' ? path : `/${path}`}`
+}
+
+// middleware pattern segments are literals or '*'; ':params' are a routing
+// concept and rejected here ('*' already matches any single segment)
+export const parseMiddlewarePattern = (pattern: string): string[] => {
+  const segments = pattern.split('/').filter(s => s !== '')
+  const valid = pattern === '/' || (segments.length && segments.every(s => s === '*' || !/[:*\s]/.test(s)))
+  if (!valid) throw new SyntaxError(`${pattern} is not a valid middleware pattern (segments are literals or '*')`)
+  return segments
+}
+
+// literal segments match identical route segments, '*' matches any single
+// segment (including ':params'), a trailing '*' matches the whole subtree and
+// the prefix itself (like the router's terminal wildcard)
+export const matchMiddleware = (pattern: string[], path: string[]): boolean => {
+  for (let i = 0; i < pattern.length; i++) {
+    const p = pattern[i]!
+    if (p === '*' && i === pattern.length - 1) return true
+    if (i >= path.length || (p !== '*' && p !== path[i])) return false
+  }
+  return pattern.length === path.length
+}
+
+/** The route's schema as declared, kept aside so recomposition re-merges from a clean base. */
+const Declared = Symbol.for('Galbe.Route.DeclaredSchema')
+
+/**
+ * Merges the matched middlewares' schema fragments into a route's request
+ * schema — fragments in registration order, route-declared keys last, so a
+ * route can always tighten or override. Returns false when there was nothing
+ * to merge.
+ *
+ * Merging is always redone from the declared schema, never from the result of
+ * a previous merge: a route recomposes whenever a later `middleware()` call
+ * matches it, and a fragment key already merged in would otherwise shadow the
+ * newcomer's, making the outcome depend on registration order.
+ *
+ * Copy-on-merge: a `RequestSchema` object may be shared by several routes, so
+ * the route gets its own copy instead of the user's being mutated.
+ */
+export const mergeMiddlewareSchema = (route: Route, middlewares: GalbeMiddleware[]): boolean => {
+  const fragments = middlewares.flatMap(m => (m.schema ? [m.schema] : []))
+  if (!fragments.length) return false
+  const declared: Record<string, any> = (route as any)[Declared] ?? route.schema ?? {}
+  ;(route as any)[Declared] = declared
+  const schema: Record<string, any> = { ...declared }
+  for (const key of ['headers', 'query', 'params'] as const) {
+    const parts = fragments.flatMap(f => (f[key] ? [f[key]] : []))
+    if (parts.length) schema[key] = Object.assign({}, ...parts, declared[key])
+  }
+  route.schema = schema
+  return true
+}
+
 export const HttpStatus = {
   100: 'Continue',
   101: 'Switching Protocols',
@@ -160,3 +286,143 @@ export const inferBodyType = (contentType?: string | null): ParseMode => {
   if (BA_HEADER_RX.test(contentType)) return 'byteArray'
   return 'default'
 }
+
+/**
+ * Trusted proxy resolution: turning the socket peer and an `X-Forwarded-For`
+ * header into the address of the actual client. Everything below is fed
+ * attacker-controlled text, so nothing here throws and nothing is trusted
+ * before it parses as an IP.
+ */
+
+/** Beyond this many hops the header is treated as unusable and the socket peer wins. */
+const MAX_FORWARDED_HOPS = 32
+const IPV4_RX = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/
+const IPV6_GROUP_RX = /^[0-9a-f]{1,4}$/
+
+/** Dotted quad → 4 bytes. Leading zeros are rejected: one address, one spelling. */
+const ipv4Bytes = (ip: string) => {
+  const m = IPV4_RX.exec(ip)
+  if (!m) return undefined
+  const bytes = new Uint8Array(4)
+  for (let i = 0; i < 4; i++) {
+    const part = m[i + 1]!
+    const value = Number(part)
+    if (value > 255 || (part.length > 1 && part[0] === '0')) return undefined
+    bytes[i] = value
+  }
+  return bytes
+}
+
+/** RFC 4291 text form → 16 bytes: one `::` run, and an optional trailing dotted quad. */
+const ipv6Bytes = (ip: string) => {
+  const [head, tail, extra] = ip.split('::')
+  if (extra !== undefined) return undefined
+  const left = head ? head.split(':') : []
+  const right = tail ? tail.split(':') : []
+  const groups = right.length ? right : left
+  let v4: Uint8Array | undefined
+  if (groups.at(-1)?.includes('.')) {
+    v4 = ipv4Bytes(groups.pop()!)
+    if (!v4) return undefined
+  }
+  const count = left.length + right.length + (v4 ? 2 : 0)
+  // without a `::` run every group must be spelled out
+  if (count > 8 || (tail === undefined && count !== 8)) return undefined
+  const bytes = new Uint8Array(16)
+  const write = (group: string, at: number) => {
+    if (!IPV6_GROUP_RX.test(group)) return false
+    const value = parseInt(group, 16)
+    bytes[at] = value >> 8
+    bytes[at + 1] = value & 0xff
+    return true
+  }
+  for (let i = 0; i < left.length; i++) if (!write(left[i]!, i * 2)) return undefined
+  const start = 16 - right.length * 2 - (v4 ? 4 : 0)
+  for (let i = 0; i < right.length; i++) if (!write(right[i]!, start + i * 2)) return undefined
+  if (v4) bytes.set(v4, 12)
+  return bytes
+}
+
+const ipBytes = (ip: string) => (ip.includes(':') ? ipv6Bytes(ip) : ipv4Bytes(ip))
+
+/**
+ * Reads one hop — a socket peer or an `X-Forwarded-For` entry — into its
+ * canonical text form and its bytes. Brackets and a trailing port are stripped
+ * (`[::1]:8080`, `192.0.2.1:8080`) and an IPv4-mapped address is unwrapped, so
+ * one client cannot present itself under several spellings.
+ */
+const parseHop = (raw: string) => {
+  let address = raw.trim().toLowerCase()
+  if (address[0] === '[') {
+    const close = address.indexOf(']')
+    if (close < 0) return undefined
+    address = address.slice(1, close)
+  } else {
+    const colon = address.indexOf(':')
+    if (colon > 0 && address.includes('.') && address.indexOf(':', colon + 1) < 0) address = address.slice(0, colon)
+  }
+  if (address.startsWith('::ffff:') && address.includes('.')) address = address.slice(7)
+  const bytes = ipBytes(address)
+  return bytes && { address, bytes }
+}
+
+type Cidr = { bytes: Uint8Array; bits: number }
+const parseCidr = (entry: string): Cidr => {
+  const slash = entry.lastIndexOf('/')
+  const suffix = slash < 0 ? undefined : entry.slice(slash + 1)
+  const hop = parseHop(slash < 0 ? entry : entry.slice(0, slash))
+  if (!hop) throw new SyntaxError(`trustProxy: '${entry}' is not an IP address or CIDR range`)
+  const bits = suffix === undefined ? hop.bytes.length * 8 : Number(suffix)
+  if (suffix !== undefined && (!/^\d+$/.test(suffix) || bits > hop.bytes.length * 8))
+    throw new SyntaxError(`trustProxy: '${entry}' has an out-of-range prefix length`)
+  return { bytes: hop.bytes, bits }
+}
+const inRange = (ip: Uint8Array, { bytes, bits }: Cidr) => {
+  if (ip.length !== bytes.length) return false
+  const whole = bits >> 3
+  for (let i = 0; i < whole; i++) if (ip[i] !== bytes[i]) return false
+  const rest = bits & 7
+  return !rest || (ip[whole]! ^ bytes[whole]!) >> (8 - rest) === 0
+}
+
+/**
+ * Compiles a `trustProxy` config into the per-request client address resolver.
+ * The hop chain is the socket peer followed by the `X-Forwarded-For` entries
+ * **right to left** — the rightmost entry is the nearest hop, and the only one
+ * your own infrastructure wrote. A hop count discards that many entries; a list
+ * of ranges discards hops it recognizes and stops at the first it does not.
+ *
+ * The socket peer wins whenever the chain cannot be walked as configured — an
+ * unparseable hop, a header shorter than the hop count, more than
+ * {@link MAX_FORWARDED_HOPS} hops — rather than falling through to the
+ * leftmost, client-controlled entry. Config errors throw here, at boot.
+ */
+export const clientAddressResolver = (trustProxy?: false | number | string[]) => {
+  const hops = typeof trustProxy === 'number' ? trustProxy : undefined
+  if (hops !== undefined && (!Number.isInteger(hops) || hops < 0))
+    throw new SyntaxError('trustProxy: hop count must be a positive integer')
+  const trusted = Array.isArray(trustProxy) ? trustProxy.map(parseCidr) : undefined
+  if (!hops && !trusted?.length) return (_req: Request, peer: string | null) => peer
+
+  return (req: Request, peer: string | null) => {
+    const socket = peer ? parseHop(peer) : undefined
+    const header = req.headers.get('x-forwarded-for')
+    if (!socket || !header) return peer
+    let hop: { address: string; bytes: Uint8Array } | undefined
+    let end = header.length
+    for (let i = 0; i < MAX_FORWARDED_HOPS; i++) {
+      // is the hop under examination one of ours? if not, it is the client
+      if (hops !== undefined ? i >= hops : !trusted!.some(range => inRange((hop ?? socket).bytes, range)))
+        return hop?.address ?? peer
+      // out of entries: a hop count that overruns the header is a misconfiguration
+      // and falls back, whereas an all-trusted chain leaves the leftmost entry
+      if (end <= 0) return hops !== undefined ? peer : (hop?.address ?? peer)
+      const comma = header.lastIndexOf(',', end - 1)
+      const next = parseHop(header.slice(comma + 1, end))
+      if (!next) return peer
+      hop = next
+      end = comma
+    }
+    return peer
+  }
+}

package/src/validator.compile.ts

@@ -0,0 +1,343 @@
+import type {
+  STArray,
+  STByteArray,
+  STInteger,
+  STIntersection,
+  STJson,
+  STLiteral,
+  STMultipartForm,
+  STNumber,
+  STObject,
+  STSchema,
+  STString,
+  STUnion,
+} from './schema'
+import type { RequestSchema, STBody } from './types'
+import { Kind, Optional, NUMBER_FORMAT_RANGES } from './schema'
+import { validate, preview, isMultipleOf } from './validator'
+
+/** A validator specialized to a single schema, with the same contract as `validate`. */
+export type CompiledValidator = (elt: any, opt?: { parse?: boolean }) => any
+
+// Compiled validators live on their schema object under a symbol key, so they
+// stay invisible to Object.entries, JSON.stringify and the spec serializers.
+export const Compiled = Symbol.for('Galbe.Validator.Compiled')
+
+/** Runs the compiled validator attached to `schema`, falling back to the `validate` interpreter. */
+export const runCompiled = (elt: any, schema: STSchema, opt?: { parse?: boolean }): any => {
+  const c = (schema as any)[Compiled] as CompiledValidator | undefined
+  return c ? c(elt, opt) : validate(elt, schema, opt)
+}
+
+/**
+ * Compiles `schema` into a specialized validator, cached on the schema object
+ * itself. Nested schemas are compiled recursively, so per-prop parsers
+ * (paramParser, multipart) find compiled validators too. Returns undefined for
+ * kinds the compiler doesn't support — callers fall back to the interpreter.
+ */
+export const compile = (schema?: STSchema): CompiledValidator | undefined => {
+  if (!schema?.[Kind]) return undefined
+  const cached = (schema as any)[Compiled] as CompiledValidator | undefined
+  if (cached) return cached
+  let fn: CompiledValidator | undefined
+  try {
+    fn = build(schema)
+  } catch {
+    // a malformed schema must not break boot — the interpreter reports it at request time
+    fn = undefined
+  }
+  if (fn) (schema as any)[Compiled] = fn
+  return fn
+}
+
+/** Compiles every schema reachable from a route's request schema. Called at route registration time. */
+export const compileRoute = (schema: RequestSchema) => {
+  for (const props of [schema.headers, schema.params, schema.query, schema.cookies])
+    if (props) for (const s of Object.values(props)) compile(s as STSchema)
+  const body = schema.body as STBody | undefined
+  if (body) {
+    if ((body as STSchema)[Kind]) compile(body as STSchema)
+    else for (const s of Object.values(body)) compile(s as STSchema)
+  }
+  for (const entry of Object.values(schema.response ?? {})) {
+    if (!entry) continue
+    if ((entry as STSchema)[Kind]) compile(entry as STSchema)
+    // response content maps also carry non-schema keys (description, responseHeaders) — compile ignores them
+    else for (const s of Object.values(entry)) compile(s as STSchema)
+  }
+}
+
+// Compiled equivalents of schemaValidation(): bounds and messages are closed
+// over at compile time. Like the interpreter, a single failure throws the
+// message, several throw an array of messages.
+const constraintRunner = (checks: ((v: any) => string | undefined)[]) => {
+  if (!checks.length) return undefined
+  return (v: any) => {
+    const errors: string[] = []
+    for (const check of checks) {
+      const msg = check(v)
+      if (msg !== undefined) errors.push(msg)
+    }
+    if (errors.length === 1) throw errors[0]
+    if (errors.length > 1) throw errors
+  }
+}
+
+const numberConstraints = (n: STNumber | STInteger) => {
+  const checks: ((v: number) => string | undefined)[] = []
+  if (n.exclusiveMin !== undefined) {
+    const b = n.exclusiveMin
+    checks.push(v => (v <= b ? `Is less or equal to ${b}` : undefined))
+  }
+  if (n.exclusiveMax !== undefined) {
+    const b = n.exclusiveMax
+    checks.push(v => (v >= b ? `Is greater or equal to ${b}` : undefined))
+  }
+  if (n.min !== undefined) {
+    const b = n.min
+    checks.push(v => (v < b ? `Is less than ${b}` : undefined))
+  }
+  if (n.max !== undefined) {
+    const b = n.max
+    checks.push(v => (v > b ? `Is greater than ${b}` : undefined))
+  }
+  if (n.multipleOf !== undefined) {
+    const m = n.multipleOf
+    const msg = `Is not a multiple of ${m}`
+    checks.push(v => (!isMultipleOf(v, m) ? msg : undefined))
+  }
+  const range = n.format ? NUMBER_FORMAT_RANGES[n.format] : undefined
+  if (range) {
+    const [lo, hi] = range
+    const msg = `Is out of ${n.format} range`
+    checks.push(v => (v < lo || v > hi ? msg : undefined))
+  }
+  return constraintRunner(checks)
+}
+
+const stringConstraints = (s: STString) => {
+  const checks: ((v: string) => string | undefined)[] = []
+  if (s.minLength !== undefined) {
+    const b = s.minLength
+    checks.push(v => (v.length < b ? `Length is too small (${b} char min)` : undefined))
+  }
+  if (s.maxLength !== undefined) {
+    const b = s.maxLength
+    checks.push(v => (v.length > b ? `Length is too large (${b} char max)` : undefined))
+  }
+  if (s.pattern !== undefined) {
+    const p = s.pattern
+    const msg = `Does not match pattern ${p}`
+    checks.push(v => (!v.match(p) ? msg : undefined))
+  }
+  return constraintRunner(checks)
+}
+
+const byteArrayConstraints = (ba: STByteArray) => {
+  const checks: ((v: Uint8Array) => string | undefined)[] = []
+  if (ba.minLength !== undefined) {
+    const b = ba.minLength
+    checks.push(v => (v.length < b ? `Length is too small (${b} bytes min)` : undefined))
+  }
+  if (ba.maxLength !== undefined) {
+    const b = ba.maxLength
+    checks.push(v => (v.length > b ? `Length is too large (${b} bytes max)` : undefined))
+  }
+  return constraintRunner(checks)
+}
+
+const arrayConstraints = (arr: STArray) => {
+  const checks: ((v: any[]) => string | undefined)[] = []
+  if (arr.minLength !== undefined) {
+    const b = arr.minLength
+    checks.push(v => (v.length < b ? `Must contain at least ${b} item${b > 1 ? 's' : ''}` : undefined))
+  }
+  if (arr.maxLength !== undefined) {
+    const b = arr.maxLength
+    checks.push(v => (v.length > b ? `Must contain at most ${b} item${b > 1 ? 's' : ''}` : undefined))
+  }
+  if (arr.unique === true) checks.push(v => (new Set(v).size !== v.length ? `Has duplicate values` : undefined))
+  return constraintRunner(checks)
+}
+
+// Builds the specialized validator for one schema. Must accept/reject exactly
+// the same inputs and throw the same plain-string errors as `validate`.
+const build = (schema: STSchema): CompiledValidator | undefined => {
+  switch (schema[Kind]) {
+    case 'null':
+      return elt => {
+        if (elt !== null) throw `Expected null value got ${preview(elt)}`
+        return elt
+      }
+    case 'boolean':
+      return (elt, opt) => {
+        if (typeof elt === 'string') {
+          if (opt?.parse) elt = elt === 'true' ? true : elt === 'false' ? false : null
+          else throw `Expected boolean, got string.`
+        }
+        if (elt !== true && elt !== false) throw `Not a valid boolean. Should be 'true' or 'false'`
+        return elt
+      }
+    case 'integer': {
+      const constraints = numberConstraints(schema as STInteger)
+      return (elt, opt) => {
+        if (elt === '') throw `Not a valid integer`
+        if (opt?.parse && typeof elt === 'string') elt = Number(elt)
+        if (!Number.isInteger(elt)) throw `Not a valid integer`
+        constraints?.(elt)
+        return elt
+      }
+    }
+    case 'number': {
+      const constraints = numberConstraints(schema as STNumber)
+      return (elt, opt) => {
+        if (elt === '') throw `Not a valid number`
+        if (opt?.parse && typeof elt === 'string') elt = Number(elt)
+        if (!Number.isFinite(elt)) throw `Not a valid number`
+        constraints?.(elt)
+        return elt
+      }
+    }
+    case 'string': {
+      const constraints = stringConstraints(schema as STString)
+      return elt => {
+        if (typeof elt !== 'string') throw `Not a valid string`
+        constraints?.(elt)
+        return elt
+      }
+    }
+    case 'literal': {
+      const value = (schema as STLiteral).value
+      return elt => {
+        if (elt !== value) throw `Not a valid value. Found "${preview(elt)}" but expected "${value}"`
+        return elt
+      }
+    }
+    case 'object': {
+      const props = Object.entries((schema as STObject).props ?? {}).map(([k, s]) => ({
+        k,
+        s: s as STSchema,
+        c: compile(s as STSchema),
+        required: !(s as STSchema)?.[Optional],
+      }))
+      const declared = new Set(props.map(p => p.k))
+      const ap = (schema as STObject).additionalProperties
+      const apCompiled = ap ? compile(ap) : undefined
+      return (elt, opt) => {
+        if (opt?.parse && typeof elt === 'string') {
+          try {
+            elt = JSON.parse(elt)
+          } catch {
+            throw `Not a valid object`
+          }
+        }
+        if (elt === null || typeof elt !== 'object') throw `Not a valid object`
+        if (Array.isArray(elt)) throw `Expected an object, not an array`
+        let err: Record<string, any> | undefined
+        for (const { k, s, c, required } of props) {
+          if (!(k in elt)) {
+            if (required) (err ??= {})[k] = 'Required'
+            continue
+          }
+          try {
+            if (c) c(elt[k], opt)
+            else validate(elt[k], s, opt)
+          } catch (e) {
+            ;(err ??= {})[k] = e
+          }
+        }
+        if (ap !== undefined) {
+          for (const k of Object.keys(elt)) {
+            if (declared.has(k)) continue
+            if (ap === false) {
+              ;(err ??= {})[k] = 'Unexpected property'
+              continue
+            }
+            try {
+              if (apCompiled) apCompiled(elt[k], opt)
+              else validate(elt[k], ap, opt)
+            } catch (e) {
+              ;(err ??= {})[k] = e
+            }
+          }
+        }
+        if (err) throw err
+        return elt
+      }
+    }
+    case 'json': {
+      const value = (schema as STJson).value as STSchema
+      const c = compile(value)
+      return (elt, opt) => (c ? c(elt, opt) : validate(elt, value, opt))
+    }
+    case 'array': {
+      const arr = schema as STArray
+      const items = arr.items
+      const c = compile(items)
+      const constraints = arrayConstraints(arr)
+      return (elt, opt) => {
+        if (opt?.parse && typeof elt === 'string') {
+          try {
+            elt = JSON.parse(elt)
+          } catch {
+            throw 'Not a valid array'
+          }
+        }
+        if (!Array.isArray(elt)) throw 'Not a valid array'
+        // the interpreter validates items without parse mode — keep parity
+        for (const i of elt) {
+          if (c) c(i)
+          else validate(i, items)
+        }
+        constraints?.(elt)
+        return elt
+      }
+    }
+    case 'byteArray': {
+      const constraints = byteArrayConstraints(schema as STByteArray)
+      return (elt, opt) => {
+        if (opt?.parse && typeof elt === 'string') elt = Uint8Array.from(elt, chr => chr.charCodeAt(0))
+        else if (opt?.parse && Array.isArray(elt)) elt = new Uint8Array(elt)
+        if (!(elt instanceof Uint8Array)) throw 'Not a valid byteArray'
+        constraints?.(elt)
+        return elt
+      }
+    }
+    case 'anyOf':
+    case 'oneOf': {
+      const members = Object.values((schema as STUnion).members) as STSchema[]
+      const failMsg = `Could not be parsed to any of [${members.map(u => (u as any)?.value ?? u[Kind]).join(', ')}]`
+      const pairs = members.map(m => ({ m, c: compile(m) }))
+      return (elt, opt) => {
+        for (const { m, c } of pairs) {
+          try {
+            return c ? c(elt, opt) : validate(elt, m, opt)
+          } catch {
+            continue
+          }
+        }
+        throw failMsg
+      }
+    }
+    case 'intersection': {
+      const allOf = Object.values((schema as STIntersection<any>).allOf) as STSchema[]
+      const pairs = allOf.map(m => ({ m, c: compile(m) }))
+      return (elt, opt) => {
+        for (const { m, c } of pairs) {
+          if (c) c(elt, opt)
+          else validate(elt, m, opt)
+        }
+        return elt
+      }
+    }
+    case 'any':
+      return elt => elt
+    case 'multipartForm':
+      // validate() has no multipartForm branch — its props are validated
+      // individually by the multipart parser, so only compile those
+      for (const s of Object.values((schema as STMultipartForm).props ?? {})) compile(s as STSchema)
+      return undefined
+    default:
+      return undefined
+  }
+}