@nifrajs/client 3.5.0 → 4.0.0

package/src/index.ts

@@ -12,6 +12,7 @@ export {
   type InProcessClient,
   type InProcessClientOptions,
   inProcessClient,
+  type TestClientOptions,
   testClient,
 } from "./client.ts"
 export type { Jsonify } from "./jsonify.ts"
@@ -22,7 +23,20 @@ export {
   reservedKeyFor,
 } from "./reserved.ts"
 export type { ApiError, Result } from "./result.ts"
-export type { ActionArgs, ActionData, ApiProxy, LoaderArgs, LoaderData } from "./routes.ts"
+export type {
+  ActionArgs,
+  ActionData,
+  ApiProxy,
+  LoaderArgs,
+  LoaderData,
+  LoaderResponseControls,
+  OutputOf,
+  Register,
+  RegisteredBackend,
+  RegisteredEnv,
+  RouteLoaderArgs,
+  SearchSchemaOf,
+} from "./routes.ts"
 export type {
   RegistryOf,
   SubscribeOptions,

package/src/routes.ts

@@ -1,5 +1,5 @@
 import type { ContractShape, RegistryFor } from "@nifrajs/core/contract"
-import type { InferOutput, StandardSchemaV1 } from "@nifrajs/core/server"
+import type { CookieOptions, InferOutput, StandardSchemaV1 } from "@nifrajs/core/server"
 import type { Treaty, TreatyFromRegistry } from "./treaty.ts"
 
 /**
@@ -11,6 +11,31 @@ export type ApiProxy<Api> = Api extends ContractShape
   ? TreatyFromRegistry<RegistryFor<Api>>
   : Treaty<Api>
 
+/**
+ * Response controls a loader or action reaches as `ctx.set` - the page counterpart of a route
+ * handler's `c.set`. Write before the loader or action returns; a write from a deferred promise that
+ * settles later throws.
+ */
+export interface LoaderResponseControls {
+  /**
+   * Headers for the rendered document (`cache-control`, `x-robots-tag`, `link`, ...). A layout's
+   * headers are applied first, then the page's, then the action's, so the most specific writer wins a
+   * name. They are not applied to a redirect, a status page, an error page, or a navigation data
+   * response. `content-type`, `set-cookie`, `location`, transport headers, and the `x-nifra-` prefix
+   * are refused.
+   */
+  readonly headers: Record<string, string>
+  /**
+   * Queue a `Set-Cookie`, with the same secure defaults as `c.set.cookie`
+   * (`HttpOnly; Secure; SameSite=Lax; Path=/`). The cookie rides every outcome - the document, a
+   * navigation data response, a redirect, a status or error page - and makes the response
+   * `cache-control: private, no-store`.
+   */
+  cookie(name: string, value: string, options?: CookieOptions): void
+  /** Queue a cookie deletion. Match the `path`/`domain` the cookie was set with. */
+  deleteCookie(name: string, options?: Pick<CookieOptions, "path" | "domain">): void
+}
+
 /**
  * Context a route `loader` receives: the route params, the request, a typed in-process `api` (an
  * {@link ApiProxy} for the app contract `Api`), and the platform `env`. Pair with `inProcessClient`.
@@ -41,8 +66,53 @@ export interface LoaderArgs<Api, Env = unknown, Search = undefined> {
       ? InferOutput<Search>
       : never
     : Record<string, unknown>
+  /** Response headers and cookies for this page request: `ctx.set.headers["cache-control"] = ...`,
+   * `ctx.set.cookie("theme", "dark")`. */
+  readonly set: LoaderResponseControls
 }
 
+/**
+ * The app's registered types. `nifra types` writes `.nifra/types/register.d.ts`, which fills it in
+ * from `backend/app.ts`, so a route's generated `Route.LoaderArgs` types `api` without the route
+ * importing the backend:
+ *
+ *     declare module "@nifrajs/client" { interface Register { backend: typeof backend } }
+ *
+ * `env` may be registered the same way, for the platform bindings `ctx.env` carries.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: filled in by declaration merging
+export interface Register {}
+
+/** The registered backend (`Register["backend"]`), or `unknown` before one is registered. */
+export type RegisteredBackend = Register extends { readonly backend: infer Backend }
+  ? Backend
+  : unknown
+
+/** The registered platform bindings (`Register["env"]`), or `unknown`. */
+export type RegisteredEnv = Register extends { readonly env: infer Env } ? Env : unknown
+
+/**
+ * What a route module's output schema lets through to the browser: the output type of its `Name`
+ * export (`loaderOutput`, `actionOutput`), or `null` when the module declares none - a loader without
+ * one sends no data.
+ */
+export type OutputOf<Module, Name extends string> = Module extends { readonly [K in Name]: infer S }
+  ? S extends StandardSchemaV1
+    ? InferOutput<S>
+    : never
+  : null
+
+/** The `searchSchema` a route's frontend half declares, or `undefined`. */
+export type SearchSchemaOf<Module> = Module extends { readonly searchSchema: infer S }
+  ? S
+  : undefined
+
+/** A route's loader or action context: its own `params`, and `api` typed by the registered backend. */
+export type RouteLoaderArgs<Params, Search = undefined> = Omit<
+  LoaderArgs<RegisteredBackend, RegisteredEnv, Search>,
+  "params"
+> & { readonly params: Params }
+
 /** The (awaited) return of a `loader`, for typing a page component's `data` prop. */
 export type LoaderData<L> = L extends (...args: never[]) => infer R ? Awaited<R> : never
 
@@ -61,9 +131,13 @@ export type ActionArgs<Api, Env = unknown, Search = undefined> = LoaderArgs<Api,
  * stays decoupled from `@nifrajs/web`) and unwrapped to its inner `data` - what the component receives.
  */
 export type ActionData<A> = A extends (...args: never[]) => infer R
-  ? Awaited<R> extends { readonly __nifraRevalidate: readonly string[]; readonly data: infer D }
-    ? Exclude<D, Response>
-    : Exclude<Awaited<R>, Response>
+  ? // `infer D` makes the check distribute, so an action mixing `revalidate(...)` and plain returns
+    // unwraps each branch.
+    Awaited<R> extends infer D
+    ? D extends { readonly __nifraRevalidate: readonly string[]; readonly data: infer W }
+      ? Exclude<W, Response>
+      : Exclude<D, Response>
+    : never
   : never
 
 // Why a type annotation, not a `createRoutes()` factory: a module-level factory call defeats

package/src/sendable-path.ts

@@ -0,0 +1,14 @@
+/**
+ * Whether a request path has a `.` or `..` segment.
+ *
+ * Such a path cannot be sent as written. URL parsing removes those segments before the request
+ * leaves - the percent-encoded spellings (`%2e`, `%2E`) included - so the server would be asked for
+ * a different path than the call names: `/users/../posts` arrives as `/posts`. No encoding survives
+ * that step, so the client refuses the call instead of sending it somewhere else. A backslash counts
+ * as a separator because an `http(s)` URL reads it as one.
+ */
+const DOT_SEGMENT = /(?:^|[/\\])(?:\.|%2e){1,2}(?:[/\\]|$)/i
+
+export function hasDotSegment(path: string): boolean {
+  return DOT_SEGMENT.test(path)
+}

package/src/treaty.ts

@@ -1,4 +1,4 @@
-import type { RouteInfo, Server } from "@nifrajs/core/server"
+import type { RequestPath, RouteInfo, Server } from "@nifrajs/core/server"
 import type { Jsonify } from "./jsonify.ts"
 import type { Result } from "./result.ts"
 
@@ -199,12 +199,34 @@ type NextSegs<R, Prefix extends string> = {
   [P in Sub<R, Prefix> & string]: NextSeg<Prefix, P>
 }[Sub<R, Prefix> & string]
 
-// Static segments exclude params (`:`), wildcards (`*`), and the root's empty (``).
-type StaticSegs<R, Prefix extends string> = Exclude<
-  NextSegs<R, Prefix>,
-  `:${string}` | `*${string}` | ""
->
-type ParamSeg<R, Prefix extends string> = Extract<NextSegs<R, Prefix>, `:${string}` | `*${string}`>
+/**
+ * What a request carries in place of one route segment: a static segment is itself, `:id` and
+ * `*path` are any `string`, and a segment that is part literal, part parameter keeps its literal
+ * text - `:name.json` is `` `${string}.json` ``. Read with the router's own rules, so a name ends
+ * where the router ends it and a constraint is not part of the text.
+ */
+type SegText<Seg extends string> = RequestPath<`/${Seg}`> extends `/${infer Text}` ? Text : never
+
+// A segment is static when its text is the segment, a param when its text is any string (a whole
+// `:name`, with or without a constraint, or a wildcard), and mixed otherwise.
+type SegKind<Seg extends string> = string extends Seg
+  ? "static"
+  : SegText<Seg> extends Seg
+    ? "static"
+    : string extends SegText<Seg>
+      ? "param"
+      : "mixed"
+
+// The root's empty segment (``) is never a child.
+type SegsOf<Seg extends string, Kind extends string> = Seg extends ""
+  ? never
+  : SegKind<Seg> extends Kind
+    ? Seg
+    : never
+
+type StaticSegs<R, Prefix extends string> = SegsOf<NextSegs<R, Prefix>, "static">
+type ParamSeg<R, Prefix extends string> = SegsOf<NextSegs<R, Prefix>, "param">
+type MixedSegs<R, Prefix extends string> = SegsOf<NextSegs<R, Prefix>, "mixed">
 
 // `unknown` (not `{}`/`never`) is the intersection identity, so empty branches
 // don't poison the node - and we never `Prettify` the node (it would strip the
@@ -217,15 +239,35 @@ type StaticChildren<R, Prefix extends string> = {
     : TreatyNode<R, `${Prefix}/${Seg}`>
 }
 
+/**
+ * The call for one param segment. A constraint is not part of the name: `:id{[0-9]+}` is called
+ * with `{ id }`, and the node below is the route as it was registered.
+ */
+type ParamCall<
+  R,
+  Prefix extends string,
+  Seg extends string,
+> = Seg extends `:${infer Name}{${string}}`
+  ? (params: Record<Name, string>) => TreatyNode<R, `${Prefix}/${Seg}`>
+  : Seg extends `:${infer Name}`
+    ? (params: Record<Name, string>) => TreatyNode<R, `${Prefix}/${Seg}`>
+    : Seg extends `*${infer Name}`
+      ? (params: Record<Name extends "" ? "*" : Name, string>) => TreatyNode<R, `${Prefix}/${Seg}`>
+      : never
+
+/** One callable carrying every signature in a union of functions. */
+type EveryCall<Calls> = (Calls extends unknown ? (call: Calls) => void : never) extends (
+  call: infer All,
+) => void
+  ? All
+  : never
+
+// One position can hold several param routes (`:id{[0-9]+}` beside `:slug`, or a param beside a
+// wildcard). Each gets its own signature, picked by the name in the argument - so routes that share
+// a position should not share a name, or the first one's types answer for both.
 type ParamChild<R, Prefix extends string> = [ParamSeg<R, Prefix>] extends [never]
   ? unknown
-  : ParamSeg<R, Prefix> extends `:${infer Name}`
-    ? (params: Record<Name, string>) => TreatyNode<R, `${Prefix}/:${Name}`>
-    : ParamSeg<R, Prefix> extends `*${infer Name}`
-      ? (
-          params: Record<Name extends "" ? "*" : Name, string>,
-        ) => TreatyNode<R, `${Prefix}/*${Name}`>
-      : unknown
+  : EveryCall<ParamCall<R, Prefix, ParamSeg<R, Prefix>>>
 
 /**
  * The call spelling for a static child segment: `api("users").get()` is `api.users.get()`.
@@ -247,10 +289,30 @@ type SegmentCall<R, Prefix extends string> = [StaticSegs<R, Prefix>] extends [ne
   ? unknown
   : <S extends StaticSegs<R, Prefix> & string>(segment: S) => TreatyNode<R, `${Prefix}/${S}`>
 
+type MixedCall<R, Prefix extends string, Seg extends string> = Seg extends unknown
+  ? (segment: SegText<Seg>) => TreatyNode<R, `${Prefix}/${Seg}`>
+  : never
+
+/**
+ * The call for a segment that is part literal, part parameter. It has no single param to name, so
+ * it takes the segment as it appears in the request: `/files/:name.json` is
+ * `api.files("report.json")`, `/v:major.:minor` is `api("v1.2")`. The argument's type is the
+ * segment's literal text around any string, so `api.files("report.txt")` does not compile.
+ *
+ * Placed last in the node intersection. A segment the registry declares as static resolves to
+ * `SegmentCall` first - `api.files("index.json")` is the static `/files/index.json` when there is
+ * one, which is also the route the server picks. Two mixed segments at one position that accept the
+ * same text resolve to whichever was registered first.
+ */
+type MixedChild<R, Prefix extends string> = [MixedSegs<R, Prefix>] extends [never]
+  ? unknown
+  : EveryCall<MixedCall<R, Prefix, MixedSegs<R, Prefix>>>
+
 type TreatyNode<R, Prefix extends string> = MethodsAt<R, Prefix> &
   StaticChildren<R, Prefix> &
   ParamChild<R, Prefix> &
-  SegmentCall<R, Prefix>
+  SegmentCall<R, Prefix> &
+  MixedChild<R, Prefix>
 
 // The root path "/" is reached as `api.index.get()` (Eden convention).
 type RootIndex<R> = "/" extends keyof R ? { readonly index: Methods<R["/"]> } : unknown

package/src/validate-responses.ts

@@ -15,7 +15,14 @@
 
 import { type Method, Router } from "@nifrajs/core/router"
 import { formatStandardIssues } from "@nifrajs/core/schema"
-import type { FetchFn } from "./client.ts"
+import type { Platform } from "@nifrajs/core/server"
+
+/** The in-process bridge: the client's `fetch(url, init)` shape, plus the calling request's platform. */
+export type PlatformFetchFn = (
+  input: string,
+  init?: RequestInit,
+  platform?: Platform,
+) => Promise<Response>
 
 /** The slice of a Standard Schema this wrapper runs. */
 interface SchemaLike {
@@ -66,7 +73,7 @@ export class ResponseContractViolation extends Error {
  * 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 {
+export function withResponseValidation(app: unknown, bridge: PlatformFetchFn): PlatformFetchFn {
   const routesOf = (app as Partial<RouteIntrospectable>).routes
   if (typeof routesOf !== "function") {
     throw new Error(
@@ -79,8 +86,8 @@ export function withResponseValidation(app: unknown, bridge: FetchFn): FetchFn {
     router.add(route.method as Method, route.path, route.schema)
   }
 
-  return async (url, init) => {
-    const response = await bridge(url, init)
+  return async (url, init, platform) => {
+    const response = await bridge(url, init, platform)
     const method = (init?.method ?? "GET").toUpperCase()
     const status = response.status
     if (method === "HEAD" || status === 204 || status === 205) return response

package/src/ws.ts

@@ -14,13 +14,17 @@ import {
   type TransportCodec,
   type TransportCodecRegistry,
 } from "@nifrajs/core/transport-codec"
+import { hasDotSegment } from "./sendable-path.ts"
 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")
 
+// `readyState` values, fixed by the WebSocket standard (an implementation's statics may be absent).
+const CONNECTING = 0
+const CLOSED = 3
+
 interface WsRuntimeOptions extends WsCallOptions {
-  headers?: Record<string, string> | undefined
   transport?: {
     readonly codec: TransportCodec
     readonly registry?: TransportCodecRegistry
@@ -55,6 +59,12 @@ export function openWebSocket(
     )
   }
 
+  if (hasDotSegment(path)) {
+    throw new Error(
+      'cannot open a WebSocket at a path with a "." or ".." segment - URL parsing removes that segment, so the socket would reach a different route',
+    )
+  }
+
   const url = toWsUrl(base, path, callOptions?.query)
   const socket =
     callOptions?.protocols !== undefined
@@ -89,6 +99,10 @@ export function openWebSocket(
     for (const frame of sendQueue) socket.send(frame)
     sendQueue.length = 0
   })
+  // A socket that closed before it opened will never send what was queued for it.
+  socket.addEventListener("close", () => {
+    sendQueue.length = 0
+  })
   socket.addEventListener("message", (event: MessageEvent) => {
     if (typeof event.data !== "string") return // binary frames live off the typed contract
     let parsed: unknown
@@ -105,9 +119,16 @@ export function openWebSocket(
     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 signal = callOptions?.signal
+  if (signal !== undefined) {
+    if (signal.aborted) socket.close()
+    else {
+      const abort = (): void => socket.close()
+      signal.addEventListener("abort", abort, { once: true })
+      socket.addEventListener("close", () => signal.removeEventListener("abort", abort), {
+        once: true,
+      })
+    }
   }
 
   const onMessage = (callback: (message: unknown) => void): (() => void) => {
@@ -124,7 +145,9 @@ export function openWebSocket(
           ? JSON.stringify(message)
           : encodeTransportFrame(message, transport.codec)
       if (socket.readyState === WebSocketImpl.OPEN) socket.send(frame)
-      else sendQueue.push(frame)
+      // Queued only while connecting: a closing or closed socket drops the frame, as
+      // `WebSocket.send` itself does, rather than holding it in a queue nothing will flush.
+      else if (socket.readyState === CONNECTING) sendQueue.push(frame)
     },
     close(code?: number, reason?: string): void {
       socket.close(code, reason)
@@ -134,6 +157,7 @@ export function openWebSocket(
       const buffered: unknown[] = []
       let pending: ((result: IteratorResult<unknown>) => void) | undefined
       let done = false
+      const signal = options?.signal
 
       const push = (message: unknown): void => {
         if (pending !== undefined) {
@@ -148,6 +172,9 @@ export function openWebSocket(
         if (done) return
         done = true
         unsubscribe()
+        socket.removeEventListener("close", end)
+        socket.removeEventListener("error", end)
+        signal?.removeEventListener("abort", end)
         pending?.({ value: undefined, done: true })
         pending = undefined
       }
@@ -155,7 +182,9 @@ export function openWebSocket(
       const unsubscribe = onMessage(push)
       socket.addEventListener("close", end, { once: true })
       socket.addEventListener("error", end, { once: true })
-      options?.signal?.addEventListener("abort", end, { once: true })
+      signal?.addEventListener("abort", end, { once: true })
+      // Already over: no close or abort event is coming to end the iteration.
+      if (socket.readyState === CLOSED || signal?.aborted === true) end()
 
       const iterator: AsyncIterableIterator<unknown> = {
         [Symbol.asyncIterator]() {