@nifrajs/core 5.5.0 → 5.6.0

package/src/server/respond.ts

@@ -13,6 +13,7 @@ import {
   EMPTY_RESPONSE_CONTROLS,
   type HandlerResult,
   isResponseResult,
+  JSON_CONTENT_TYPE,
   type PlainRender,
   plainRenderHeaders,
   type ResponseResult,
@@ -41,10 +42,9 @@ function plainRenderSet(plain: PlainRender, set: CtxSet): CtxSet {
   } as CtxSet
 }
 
-// Keep the fast JSON respond path byte-identical to `Response.json` without probing it at module
-// scope: workerd forbids `Response.json()` during startup. A shared `Headers` is safe to reuse
-// across responses: the Response constructor copies `init.headers` into its own list.
-const JSON_CONTENT_TYPE = "application/json;charset=utf-8"
+// Keep the fast JSON respond path byte-identical to `Response.json` (see `JSON_CONTENT_TYPE`). A
+// shared `Headers` is safe to reuse across responses: the Response constructor copies
+// `init.headers` into its own list.
 const JSON_CT_HEADERS = new Headers({ "content-type": JSON_CONTENT_TYPE })
 const JSON_INIT_200: ResponseInit = { status: 200, headers: JSON_CT_HEADERS }
 
@@ -212,7 +212,7 @@ function denoResponseWithJsonBody(
  * it exactly as `withJsonContentType` did.
  */
 function jsonResponseWithOwnHeaders(
-  result: object,
+  result: unknown,
   status: number,
   headers: Record<string, string>,
 ): Response {
@@ -499,9 +499,16 @@ function tagged(
       )
 }
 
-/** Fused-lane respond when `c.set` is untouched. Bun 1.3's native `Response.json` now beats the
- * older hand-inlined stringify + Response construction on this lane while preserving the exact
- * body/content-type contract; keep the generic fallback for non-JSON values. */
+/** A plain 200 JSON response. On Bun and Deno the native `Response.json` beats a hand-inlined
+ * stringify + Response construction; on Node undici's is 18-26% slower than stringify into the
+ * prebuilt init. Both keep the exact body/content-type contract. */
+function plainJsonResponse(result: object): Response {
+  // `undefined` from stringify (a `toJSON` returning nothing) keeps `Response.json`'s TypeError.
+  const body = IS_BUN || IS_DENO ? undefined : (JSON.stringify(result) as string | undefined)
+  return body === undefined ? Response.json(result) : new Response(body, JSON_INIT_200)
+}
+
+/** Fused-lane respond when `c.set` is untouched; keep the generic fallback for non-JSON values. */
 export function fusedRespondNoSet(
   result: unknown,
   tagResponseBody: ResponseBodyTagOption = false,
@@ -527,7 +534,7 @@ export function fusedRespondNoSet(
     !(result instanceof Response) &&
     !isResponseResult(result)
   ) {
-    const response = Response.json(result)
+    const response = plainJsonResponse(result)
     return residentBodiesRecorded ? markResidentBody(response) : response
   }
   if (
@@ -579,7 +586,7 @@ export function fusedRespondNoSet(
     }
     return withBody(
       statics === undefined
-        ? Response.json(result)
+        ? plainJsonResponse(result)
         : Response.json(result, statics.responseJsonInit200()),
     )
   }
@@ -757,7 +764,7 @@ function renderValue(
               body,
               status,
               headers as Record<string, string>,
-              JSON_CT_HEADERS.get("content-type") ?? "application/json;charset=utf-8",
+              JSON_CONTENT_TYPE,
             )
           : // lgtm [js/stack-trace-exposure] the serialized body is not a caught error stack.
             new Response(body, { status, headers: withJsonContentType(headers) })
@@ -769,8 +776,9 @@ function renderValue(
     }
   }
   if (IS_DENO && headers !== undefined && !(headers instanceof Headers)) {
-    const body = JSON.stringify(result) as string | undefined
-    if (body !== undefined) return withBody(denoResponseWithJsonBody(body, status, headers))
+    // Deno's own `Response.json` then header writes measured ~10% under stringify, construction and
+    // the same writes plus a content-type one; a declared content-type still overrides the default.
+    return jsonResponseWithOwnHeaders(result, status, headers)
   }
   return withBody(Response.json(result, init))
 }
@@ -787,12 +795,12 @@ function withJsonContentType(
 ): Record<string, string> | Headers {
   if (headers === undefined) return JSON_CT_HEADERS
   if (headers instanceof Headers) {
-    if (!headers.has("content-type")) headers.set("content-type", "application/json;charset=utf-8")
+    if (!headers.has("content-type")) headers.set("content-type", JSON_CONTENT_TYPE)
     return headers
   }
   return Object.hasOwn(headers, "content-type")
     ? headers
-    : { ...headers, "content-type": "application/json;charset=utf-8" }
+    : { ...headers, "content-type": JSON_CONTENT_TYPE }
 }
 
 /** Headers that describe a Response's body or its framing: a `c.set` value for one describes a body

package/src/server/response-contract-lane.ts

@@ -32,13 +32,23 @@
  * carries its JSON Schema as `jsonSchema` (every `t` schema does) CAN list its declared keys, so for
  * those the payload is projected onto the declared shape before it is validated.
  *
+ * ## What is judged is what is written
+ *
+ * `JSON.stringify` writes what a `toJSON` hook returns, not the fields a validator reads off the
+ * object. So a value's hooks are applied first, as the serializer would, and that result is validated
+ * and sent: a class whose `toJSON` adds a private field fails a closed schema instead of passing on its
+ * public ones. `strip` keeps the declared fields of what the hook writes, so a hook that writes `id`
+ * from private state keeps it. A `Date` is the exception; it stays a `Date` for a date schema and is
+ * written as its ISO string.
+ *
  * ## What enforcement costs
  *
  * Less than it looks like it should. With a compiled validator (`@nifrajs/schema`'s `t` compiles at
  * construction; zod/valibot equivalents are similarly cheap), the check itself measures in the
  * ~100ns-per-response range - on a realistic middleware-carrying route, enforce mode benchmarks
- * within measurement noise of the same route with no contract at all, on Bun and Node alike. The
- * one real cost is structural: a contracted route cannot take the bare-route fused lane, because
+ * within measurement noise of the same route with no contract at all, on Bun and Node alike. Looking
+ * for `toJSON` hooks visits every object in the payload, about 13 ns each, so a 50-row list pays near
+ * 0.7 us. The other cost is structural: a contracted route cannot take the bare-route fused lane, because
  * the check needs the handler's VALUE before it becomes bytes. A route with any middleware, derive,
  * or lifecycle hook has already left that lane, so for the routes that look like production the
  * contract is effectively free - declare it.
@@ -166,7 +176,12 @@ function compileProjector(node: unknown): Projector | undefined {
     const item = Array.isArray(items) ? undefined : compileProjector(items)
     return item === undefined
       ? undefined
-      : (value) => (Array.isArray(value) ? value.map(item) : value)
+      : (value) => {
+          if (!Array.isArray(value)) return value
+          const out: unknown[] = []
+          for (let i = 0; i < value.length; i++) out.push(item(writtenAt(value[i], i)))
+          return out
+        }
   }
   if (type !== "object") return undefined
   const properties = objectField(schema, "properties") ?? {}
@@ -196,7 +211,7 @@ function compileProjector(node: unknown): Projector | undefined {
     for (const key of closed ? keys : nested.keys()) {
       if (!hasField(value, key)) continue
       const projector = nested.get(key)
-      define(out, key, projector === undefined ? value[key] : projector(value[key]))
+      define(out, key, projector === undefined ? value[key] : projector(writtenAt(value[key], key)))
     }
     if (patterns.length > 0) projectPatternKeys(value, out, declared, patterns, closed)
     return out
@@ -340,7 +355,8 @@ function projectPatternKeys(
         matches++
       }
     if (matches === 0) continue
-    if (matches === 1 && projector !== undefined) define(out, key, projector(value[key]))
+    if (matches === 1 && projector !== undefined)
+      define(out, key, projector(writtenAt(value[key], key)))
     else if (closed) define(out, key, value[key])
   }
 }
@@ -352,6 +368,101 @@ function define(out: Record<string, unknown>, key: string, value: unknown): void
   else out[key] = value
 }
 
+const DATE_TO_JSON = Date.prototype.toJSON
+
+// Deeper than this, the copying walk takes over with its own cycle check.
+const MAX_HOOK_SCAN_DEPTH = 64
+
+/** Whether `value` holds a `toJSON` hook other than a `Date`'s. Allocates nothing: most payloads
+ * have none, and this is the price every contracted response pays. */
+function hasHook(value: object, depth: number): boolean {
+  if (depth > MAX_HOOK_SCAN_DEPTH) return true
+  const hook: unknown = Reflect.get(value, "toJSON")
+  if (typeof hook === "function") return !(hook === DATE_TO_JSON && value instanceof Date)
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      const item: unknown = value[i]
+      if (typeof item === "object" && item !== null && hasHook(item, depth + 1)) return true
+    }
+    return false
+  }
+  // Inherited enumerable keys are scanned too; that only ever sends a value to the copying walk.
+  for (const key in value) {
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: `key` was enumerated from `value`; `Reflect.get` here halves the speed of this for-in.
+    const field: unknown = (value as Record<string, unknown>)[key]
+    if (typeof field === "object" && field !== null && hasHook(field, depth + 1)) return true
+  }
+  return false
+}
+
+/**
+ * What `JSON.stringify` writes for `value`: every `toJSON` hook applied as the serializer applies it,
+ * so the contract judges the bytes that go out rather than fields a hook then replaces. Copies only the
+ * containers above a hook. A `Date` keeps its object, since its own hook writes nothing but the ISO
+ * string a date schema declares.
+ */
+const wireValueOf = (value: unknown): unknown =>
+  typeof value === "object" && value !== null && hasHook(value, 0)
+    ? wireValue(value, "", [])
+    : value
+
+const wireValue = (value: unknown, key: string | number, path: object[]): unknown =>
+  wireChildren(writtenAt(value, key), path)
+
+/** `value` as the serializer takes it under `key`: its own hook applied, its fields still as they are. */
+function writtenAt(value: unknown, key: string | number): unknown {
+  if (typeof value !== "object" || value === null) return value
+  const hook: unknown = Reflect.get(value, "toJSON")
+  if (typeof hook !== "function" || (hook === DATE_TO_JSON && value instanceof Date)) return value
+  return fieldsOf(Reflect.apply(hook, value, [String(key)]))
+}
+
+/**
+ * The serializer calls one hook per value, so a hook's result that has a hook of its own is written
+ * by its fields. Copying them out keeps that second hook from running when the checked value is sent.
+ */
+function fieldsOf(value: unknown): unknown {
+  if (typeof value !== "object" || value === null) return value
+  if (typeof Reflect.get(value, "toJSON") !== "function") return value
+  if (Array.isArray(value)) return Array.from({ length: value.length }, (_, i): unknown => value[i])
+  const fields: Record<string, unknown> = {}
+  for (const name of Object.keys(value))
+    if (name !== "toJSON") define(fields, name, Reflect.get(value, name))
+  return fields
+}
+
+function wireChildren(value: unknown, path: object[]): unknown {
+  // A cycle is left as it is for `JSON.stringify` to refuse.
+  if (typeof value !== "object" || value === null || path.includes(value)) return value
+  path.push(value)
+  if (Array.isArray(value)) {
+    let items: unknown[] | undefined
+    for (let i = 0; i < value.length; i++) {
+      const item: unknown = value[i]
+      const written = wireValue(item, i, path)
+      if (written !== item) items ??= value.slice(0, i)
+      if (items !== undefined) items[i] = written
+    }
+    path.pop()
+    return items ?? value
+  }
+  const keys = Object.keys(value)
+  let out: Record<string, unknown> | undefined
+  let index = 0
+  for (const name of keys) {
+    const field: unknown = Reflect.get(value, name)
+    const written = wireValue(field, name, path)
+    if (written !== field && out === undefined) {
+      out = {}
+      for (const earlier of keys.slice(0, index)) define(out, earlier, Reflect.get(value, earlier))
+    }
+    if (out !== undefined) define(out, name, written)
+    index++
+  }
+  path.pop()
+  return out ?? value
+}
+
 const MAX_STRIPPED_NAMES = 20
 const MAX_NAME_LENGTH = 64
 const MAX_REPORTED_SETS = 32
@@ -523,10 +634,21 @@ function validateContract(
   replace: (value: unknown) => unknown,
 ): ResponseContractOutcome | Promise<ResponseContractOutcome> {
   const project = policy.strip ? projectorOf(schema) : undefined
-  const settled = schema["~standard"].validate(project === undefined ? payload : project(payload))
+  // Naming what was stripped compares against everything the payload writes, so it walks it whole.
+  const before =
+    project === undefined || policy.report !== undefined || mode === "warn"
+      ? wireValueOf(payload)
+      : payload
+  // The projection applies the hook of each value it descends into and reads only declared fields,
+  // so a quiet strip never enumerates the payload's own keys. What it copies whole is walked after.
+  const sent = project === undefined ? before : wireValueOf(project(writtenAt(before, "")))
+  const settled = schema["~standard"].validate(sent)
+  // When hooks wrote the payload, `warn` sends what they wrote here rather than calling them again,
+  // so a hook that answers differently on a second call cannot send what was not judged.
+  const shown = mode === "warn" && before !== payload ? replace(before) : served
   return settled instanceof Promise
-    ? settled.then((r) => interpret(r, payload, served, mode, replace, policy.report))
-    : interpret(settled, payload, served, mode, replace, policy.report)
+    ? settled.then((r) => interpret(r, before, shown, mode, replace, policy.report))
+    : interpret(settled, before, shown, mode, replace, policy.report)
 }
 
 function interpret(

package/src/server/runtime-core.ts

@@ -11,6 +11,15 @@ import type { CtxSet, RequestSource } from "./server.ts"
 /** A handler returns a `Response` (used as-is) or any value (serialized to JSON). */
 export type HandlerResult = Response | unknown
 
+/**
+ * The Content-Type the runtime's own `Response.json` writes, which every JSON nifra renders on the Web
+ * lanes carries too, so a handler's JSON and the framework's envelopes (built with `Response.json`)
+ * agree on one runtime. Bun adds `;charset=utf-8`; Deno, workerd and undici do not. Named rather than
+ * probed: workerd forbids `Response.json()` while a module loads.
+ */
+export const JSON_CONTENT_TYPE =
+  "Bun" in globalThis ? "application/json;charset=utf-8" : "application/json"
+
 export const RESPONSE_RESULT = Symbol.for(NODE_BRIDGE_MARKER_KEYS.responseResult)
 export const CONTEXT_SET = Symbol("nifra.context.set")
 export const CONTEXT_SEARCH = Symbol("nifra.context.search")
@@ -178,7 +187,7 @@ export function status(
     toResponse(): Response {
       const headers: Record<string, string> = { ...init?.headers }
       if (body === undefined) return new Response(null, { status: code, headers })
-      headers["content-type"] ??= "application/json;charset=utf-8"
+      headers["content-type"] ??= JSON_CONTENT_TYPE
       return new Response(JSON.stringify(body), { status: code, headers })
     },
   } as StatusResponse<number, unknown>

package/src/server/server-types.ts

@@ -91,9 +91,12 @@ export interface ServerOptions {
   readonly trustBodyFraming?: boolean
   /**
    * Max inbound WebSocket message size (bytes). A larger message never reaches the handler and the
-   * socket closes with `1009`. Default: `maxBodyBytes` (1 MB). Bun and Node stop buffering at the cap,
-   * so a huge frame is never held in memory; on Bun a mounted app's smaller cap, and on Deno and
-   * Workers every cap, is checked after the runtime has buffered the whole message.
+   * socket closes with `1009`; when Bun's own frame limit refuses it, Bun up to 1.4.3 drops the
+   * connection (the client sees `1006`) and Bun 1.4.4 sends `1009`, while the `close` handler gets
+   * `1009` either way. Default: `maxBodyBytes` (1 MB).
+   * Bun and Node stop buffering at the cap, so a huge frame is never held in memory; on Bun a mounted
+   * app's smaller cap, and on Deno and Workers every cap, is checked after the runtime has buffered
+   * the whole message.
    */
   readonly wsMaxPayloadBytes?: number
   /** Per-request timeout (ms): a slower request gets a 503 and `ctx.signal` aborts. 0 disables (default). */