@nifrajs/client 1.13.0 → 2.1.0

package/src/index.ts

@@ -6,9 +6,11 @@
  */
 export {
   type ClientOptions,
+  type ClientRetryOptions,
   client,
   type FetchFn,
   type InProcessClient,
+  type InProcessClientOptions,
   inProcessClient,
   testClient,
 } from "./client.ts"
@@ -21,4 +23,7 @@ export type {
   Subscription,
   Treaty,
   TreatyFromRegistry,
+  WsCallOptions,
+  WsHandle,
 } from "./treaty.ts"
+export { ResponseContractViolation } from "./validate-responses.ts"

package/src/result.ts

@@ -8,18 +8,96 @@ export interface ApiError {
 }
 
 /**
- * The outcome of a client call. The client never throws — inspect `ok` to branch.
- * `data` is the parsed response body, **typed by `ok`**: on success it's the route's
- * response type; on failure it's the parsed error body, typed from the route's
- * `errors` contract (`unknown` when the route declares none, `null` on a transport
- * error with no response body). `error` is always the server's normalized
- * `{ error, issues? }` summary on failure (or a transport error), `null` on success.
+ * The failure statuses a call can carry (the IANA registry's 3xx/4xx/5xx set). Finite on purpose:
+ * the undeclared-status fallback arm of {@link Result} is `Exclude<ErrorStatus, declared>` - with a
+ * bare `number` there instead, `status === 404` could not narrow `data` to the declared 404 body,
+ * because 404 would still inhabit the fallback arm.
  */
-export type Result<Data, ErrData = unknown> =
+export type ErrorStatus =
+  | 300
+  | 301
+  | 302
+  | 303
+  | 304
+  | 305
+  | 306
+  | 307
+  | 308
+  | 400
+  | 401
+  | 402
+  | 403
+  | 404
+  | 405
+  | 406
+  | 407
+  | 408
+  | 409
+  | 410
+  | 411
+  | 412
+  | 413
+  | 414
+  | 415
+  | 416
+  | 417
+  | 418
+  | 421
+  | 422
+  | 423
+  | 424
+  | 425
+  | 426
+  | 428
+  | 429
+  | 431
+  | 451
+  | 500
+  | 501
+  | 502
+  | 503
+  | 504
+  | 505
+  | 506
+  | 507
+  | 508
+  | 510
+  | 511
+
+/** One failure arm per declared error status: `status` is the literal, `data` its declared body. */
+type DeclaredFailures<Errors extends Record<number, unknown>> = {
+  [K in Extract<keyof Errors, number>]: {
+    readonly ok: false
+    readonly status: K
+    readonly data: Errors[K]
+    readonly error: ApiError
+  }
+}[Extract<keyof Errors, number>]
+
+/**
+ * The outcome of a client call. The client never throws - inspect `ok` to branch.
+ *
+ * On success, `data` is the route's response type. On failure the union is DISCRIMINATED BY
+ * `status` when the route declares an `errors` record: `status === 404` narrows `data` to the
+ * declared 404 body; every undeclared status (plus `0` for a transport error with no response)
+ * falls into a fallback arm whose `data` is `unknown`. A route with no `errors` contract keeps a
+ * single failure arm with `data: Errors` (`unknown`). `error` is always the server's normalized
+ * `{ error, issues? }` summary on failure, `null` on success.
+ */
+export type Result<Data, Errors = unknown> =
   | { readonly ok: true; readonly status: number; readonly data: Data; readonly error: null }
-  | {
-      readonly ok: false
-      readonly status: number
-      readonly data: ErrData
-      readonly error: ApiError
-    }
+  | ([Errors] extends [Record<number, unknown>]
+      ?
+          | DeclaredFailures<Errors>
+          | {
+              readonly ok: false
+              readonly status: Exclude<ErrorStatus, Extract<keyof Errors, number>> | 0
+              readonly data: unknown
+              readonly error: ApiError
+            }
+      : {
+          readonly ok: false
+          readonly status: number
+          readonly data: Errors
+          readonly error: ApiError
+        })

package/src/routes.ts

@@ -1,4 +1,4 @@
-import type { ContractShape, RegistryFor } from "@nifrajs/core"
+import type { ContractShape, RegistryFor } from "@nifrajs/core/contract"
 import type { Treaty, TreatyFromRegistry } from "./treaty.ts"
 
 /**

package/src/treaty.ts

@@ -1,4 +1,4 @@
-import type { RouteInfo, Server } from "@nifrajs/core"
+import type { RouteInfo, Server } from "@nifrajs/core/server"
 import type { Jsonify } from "./jsonify.ts"
 import type { Result } from "./result.ts"
 
@@ -84,12 +84,60 @@ type SseMethods<MethodMap> = MethodMap extends { GET: infer G }
     : { subscribe: SubscribeCall<G & RouteInfo> }
   : unknown
 
+// --- typed WebSocket handles ---
+
+/** The WS frame contract of a route (from `app.ws()`'s schemas); `never` for ordinary routes. */
+type WsOf<I> = I extends { ws: infer W extends { in: unknown; out: unknown } } ? W : never
+
+export interface WsCallOptions {
+  query?: Record<string, string | number | boolean>
+  /** WebSocket subprotocols. A browser handshake cannot carry custom headers - authenticate via
+   * `upgrade()` reading cookies/query/subprotocol, not an Authorization header. */
+  protocols?: string | string[]
+  /** Abort to close the socket (same effect as calling `close()`). */
+  signal?: AbortSignal
+  /** Socket-level failures (connection refused, abnormal close). */
+  onError?: (error: unknown) => void
+}
+
+/**
+ * A live typed WebSocket connection to an `app.ws()` route. `send` accepts the route's
+ * `messageSchema` input type (validated server-side at the trust boundary); received frames are
+ * typed from its `sendSchema` and JSON-parsed. Binary frames are not part of the typed contract
+ * and are ignored by `messages()`/`onMessage` - use `raw` for them.
+ */
+export interface WsHandle<In, Out> {
+  /** Send one typed frame (JSON-encoded). Queued until the socket opens, so it never throws. */
+  send(message: In): void
+  /** Async-iterate incoming typed frames. Ends when the socket closes (or `signal` aborts). */
+  messages(options?: { signal?: AbortSignal }): AsyncIterableIterator<Out>
+  /** Callback form of {@link messages}; returns an unsubscribe. */
+  onMessage(callback: (message: Out) => void): () => void
+  /** Resolves when the socket is open (rejects on a connect failure). */
+  readonly opened: Promise<void>
+  close(code?: number, reason?: string): void
+  /** The underlying socket, for anything off the typed contract (binary frames, bufferedAmount…). */
+  readonly raw: WebSocket
+}
+
+type WsCall<I extends RouteInfo> = (
+  options?: WsCallOptions,
+) => WsHandle<WsOf<I>["in"], Jsonify<WsOf<I>["out"]>>
+
+/** Routes declared via `app.ws()` (pseudo-method `"WS"`) grow a `.ws()` handle. */
+type WsMethods<MethodMap> = MethodMap extends { WS: infer G }
+  ? [WsOf<G>] extends [never]
+    ? unknown
+    : { ws: WsCall<G & RouteInfo> }
+  : unknown
+
 type Methods<MethodMap> = {
-  [M in keyof MethodMap as Lowercase<M & string>]: MethodCall<
+  [M in Exclude<keyof MethodMap, "WS"> as Lowercase<M & string>]: MethodCall<
     MethodMap[M] & RouteInfo,
     IsBodyVerb<M & string>
   >
-} & SseMethods<MethodMap>
+} & SseMethods<MethodMap> &
+  WsMethods<MethodMap>
 
 // --- path-tree construction over the registry ---
 

package/src/validate-responses.ts

@@ -0,0 +1,121 @@
+/**
+ * Runtime response-contract assertion for the in-process test client
+ * (`testClient(app, { validateResponses: true })`).
+ *
+ * The `response` / `errors` schemas on a route are a compile-time contract on the handler; nothing
+ * re-checks the bytes that actually leave the app. This wrapper closes that gap in tests: every
+ * JSON response is validated against the route's declared schema for its status - `response` for
+ * 2xx, `errors[status]` for declared failures - and a mismatch THROWS (failing the test loudly)
+ * instead of letting a drifted payload pass. Responses with no declared schema for their status,
+ * non-JSON bodies (SSE, streams, HTML), and 204/205/HEAD are passed through untouched.
+ *
+ * Route lookup reuses the framework's own `Router` over `app.routes()`, so pattern matching can
+ * never drift from what the server itself does.
+ */
+
+import { type Method, Router } from "@nifrajs/core/router"
+import type { FetchFn } from "./client.ts"
+
+/** The slice of a Standard Schema this wrapper runs. */
+interface SchemaLike {
+  readonly "~standard": {
+    readonly validate: (value: unknown) =>
+      | { readonly issues?: ReadonlyArray<IssueLike> | undefined; readonly value?: unknown }
+      | Promise<{
+          readonly issues?: ReadonlyArray<IssueLike> | undefined
+          readonly value?: unknown
+        }>
+  }
+}
+
+interface IssueLike {
+  readonly message: string
+  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> | undefined
+}
+
+interface RouteSchemaLike {
+  readonly response?: SchemaLike
+  readonly errors?: Readonly<Record<number, SchemaLike>>
+}
+
+interface RouteDescriptorLike {
+  readonly method: string
+  readonly path: string
+  readonly schema: RouteSchemaLike | undefined
+}
+
+/** What `validateResponses` needs from the app beyond `fetch`: the route table. */
+export interface RouteIntrospectable {
+  routes(): ReadonlyArray<RouteDescriptorLike>
+}
+
+/**
+ * A response body that broke its route's declared contract. Thrown THROUGH the "never throws"
+ * client on purpose: this is a test assertion about the server's honesty, not a call outcome the
+ * caller should branch on - swallowing it into a `Result` would let the drift pass the test.
+ */
+export class ResponseContractViolation extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "ResponseContractViolation"
+  }
+}
+
+function formatIssues(issues: ReadonlyArray<IssueLike>): string {
+  return issues
+    .map((issue) => {
+      const path = (issue.path ?? [])
+        .map((seg) => String(typeof seg === "object" && seg !== null ? seg.key : seg))
+        .join(".")
+      return path === "" ? issue.message : `${path}: ${issue.message}`
+    })
+    .join("; ")
+}
+
+/**
+ * Wrap the in-process bridge so every response is checked against its route's declared contract.
+ * Throws at wrap time when the app cannot enumerate routes - a misconfiguration, not a soft skip.
+ */
+export function withResponseValidation(app: unknown, bridge: FetchFn): FetchFn {
+  const routesOf = (app as Partial<RouteIntrospectable>).routes
+  if (typeof routesOf !== "function") {
+    throw new Error(
+      "validateResponses needs an app that exposes .routes() (a nifra server); this app does not",
+    )
+  }
+  // One router per client, built once: match by the server's own engine, payload = the schema.
+  const router = new Router<RouteSchemaLike | undefined>()
+  for (const route of routesOf.call(app)) {
+    router.add(route.method as Method, route.path, route.schema)
+  }
+
+  return async (url, init) => {
+    const response = await bridge(url, init)
+    const method = (init?.method ?? "GET").toUpperCase()
+    const status = response.status
+    if (method === "HEAD" || status === 204 || status === 205) return response
+
+    const match = router.find(method, new URL(url).pathname)
+    if (!match.found) return response
+    const schema = match.payload
+    const declared = status >= 200 && status < 300 ? schema?.response : schema?.errors?.[status]
+    if (declared === undefined) return response
+
+    const contentType = response.headers.get("content-type") ?? ""
+    if (!contentType.includes("application/json")) return response
+    // Clone so the caller still gets an unconsumed body; unparseable JSON is the transport's problem.
+    let body: unknown
+    try {
+      body = await response.clone().json()
+    } catch {
+      return response
+    }
+    const result = await declared["~standard"].validate(body)
+    if (result.issues !== undefined) {
+      throw new ResponseContractViolation(
+        `response contract violation: ${method} ${new URL(url).pathname} → ${status}: ${formatIssues(result.issues)}`,
+      )
+    }
+    return response
+  }
+}

package/src/ws.ts

@@ -0,0 +1,181 @@
+/**
+ * The typed client's WebSocket transport - the runtime behind `api.chat.ws()` for routes declared
+ * with `app.ws()`. Uses the platform's global `WebSocket` (browser, Bun, Node 22+, Deno, workerd),
+ * mapping the client's `http(s)` base to `ws(s)`. Frames are JSON on the typed surface: `send`
+ * encodes, `messages()`/`onMessage` parse text frames (binary frames bypass the typed contract -
+ * read them off `raw`). Sends before the socket opens are queued, so the handle never throws.
+ */
+
+import {
+  createTransportCodecRegistry,
+  decodeTransportFrame,
+  encodeTransportFrame,
+  plainJsonCodec,
+  type TransportCodec,
+  type TransportCodecRegistry,
+} from "@nifrajs/core/transport-codec"
+import type { WsCallOptions, WsHandle } from "./treaty.ts"
+
+/** Internal handshake between `inProcessClient` and the proxy: in-process apps have no socket. */
+export const NO_SOCKET = Symbol.for("@nifrajs/client/no-socket")
+
+interface WsRuntimeOptions extends WsCallOptions {
+  headers?: Record<string, string> | undefined
+  transport?: {
+    readonly codec: TransportCodec
+    readonly registry?: TransportCodecRegistry
+    readonly maxBytes?: number
+  }
+}
+
+function toWsUrl(base: string, path: string, query: WsCallOptions["query"]): string {
+  const url = new URL(base + (path === "" ? "/" : path))
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:"
+  for (const [key, value] of Object.entries(query ?? {})) {
+    url.searchParams.set(key, String(value))
+  }
+  return url.toString()
+}
+
+export function openWebSocket(
+  base: string,
+  path: string,
+  callOptions: WsRuntimeOptions | undefined,
+  noSocket: boolean,
+): WsHandle<unknown, unknown> {
+  if (noSocket) {
+    throw new Error(
+      "the in-process client cannot open WebSockets (app.fetch has no socket) - listen() the app and connect with client(baseUrl)",
+    )
+  }
+  const WebSocketImpl = (globalThis as { WebSocket?: typeof WebSocket }).WebSocket
+  if (WebSocketImpl === undefined) {
+    throw new Error(
+      "no global WebSocket in this runtime - .ws() needs one (browser, Bun, Node 22+)",
+    )
+  }
+
+  const url = toWsUrl(base, path, callOptions?.query)
+  const socket =
+    callOptions?.protocols !== undefined
+      ? new WebSocketImpl(url, callOptions.protocols)
+      : new WebSocketImpl(url)
+
+  const sendQueue: string[] = []
+  const listeners = new Set<(message: unknown) => void>()
+  const transport = callOptions?.transport
+  const registry =
+    transport?.registry ??
+    (transport === undefined || transport.codec === plainJsonCodec
+      ? createTransportCodecRegistry([plainJsonCodec])
+      : createTransportCodecRegistry([plainJsonCodec, transport.codec]))
+
+  const opened = new Promise<void>((resolve, reject) => {
+    socket.addEventListener("open", () => resolve(), { once: true })
+    socket.addEventListener(
+      "error",
+      (event) => {
+        callOptions?.onError?.(event)
+        reject(new Error("websocket_connect_failed"))
+      },
+      { once: true },
+    )
+  })
+  // The rejection is surfaced via `opened` (and `onError`) only for those who look - an unconsumed
+  // `opened` on a failed connect must not crash the process with an unhandled rejection.
+  opened.catch(() => {})
+
+  socket.addEventListener("open", () => {
+    for (const frame of sendQueue) socket.send(frame)
+    sendQueue.length = 0
+  })
+  socket.addEventListener("message", (event: MessageEvent) => {
+    if (typeof event.data !== "string") return // binary frames live off the typed contract
+    let parsed: unknown
+    try {
+      parsed =
+        transport === undefined
+          ? JSON.parse(event.data)
+          : decodeTransportFrame(event.data, registry, {
+              ...(transport.maxBytes === undefined ? {} : { maxBytes: transport.maxBytes }),
+            })
+    } catch {
+      return // a non-JSON text frame is outside the contract too
+    }
+    for (const listener of listeners) listener(parsed)
+  })
+
+  if (callOptions?.signal !== undefined) {
+    if (callOptions.signal.aborted) socket.close()
+    else callOptions.signal.addEventListener("abort", () => socket.close(), { once: true })
+  }
+
+  const onMessage = (callback: (message: unknown) => void): (() => void) => {
+    listeners.add(callback)
+    return () => listeners.delete(callback)
+  }
+
+  return {
+    raw: socket,
+    opened,
+    send(message: unknown): void {
+      const frame =
+        transport === undefined
+          ? JSON.stringify(message)
+          : encodeTransportFrame(message, transport.codec)
+      if (socket.readyState === WebSocketImpl.OPEN) socket.send(frame)
+      else sendQueue.push(frame)
+    },
+    close(code?: number, reason?: string): void {
+      socket.close(code, reason)
+    },
+    onMessage,
+    messages(options?: { signal?: AbortSignal }): AsyncIterableIterator<unknown> {
+      const buffered: unknown[] = []
+      let pending: ((result: IteratorResult<unknown>) => void) | undefined
+      let done = false
+
+      const push = (message: unknown): void => {
+        if (pending !== undefined) {
+          const resolve = pending
+          pending = undefined
+          resolve({ value: message, done: false })
+        } else {
+          buffered.push(message)
+        }
+      }
+      const end = (): void => {
+        if (done) return
+        done = true
+        unsubscribe()
+        pending?.({ value: undefined, done: true })
+        pending = undefined
+      }
+
+      const unsubscribe = onMessage(push)
+      socket.addEventListener("close", end, { once: true })
+      socket.addEventListener("error", end, { once: true })
+      options?.signal?.addEventListener("abort", end, { once: true })
+
+      const iterator: AsyncIterableIterator<unknown> = {
+        [Symbol.asyncIterator]() {
+          return this
+        },
+        next(): Promise<IteratorResult<unknown>> {
+          if (buffered.length > 0) {
+            return Promise.resolve({ value: buffered.shift(), done: false })
+          }
+          if (done) return Promise.resolve({ value: undefined, done: true })
+          return new Promise((resolve) => {
+            pending = resolve
+          })
+        },
+        return(): Promise<IteratorResult<unknown>> {
+          end()
+          return Promise.resolve({ value: undefined, done: true })
+        },
+      }
+      return iterator
+    },
+  }
+}