@solidjs/web 2.0.0-beta.26 → 2.0.0-beta.28

package/types-cjs/server-functions/server.d.cts

@@ -4,13 +4,17 @@ import { RequestEvent } from "../server.cjs";
 
 export {
   ERROR_HEADER,
+  FLASH_COOKIE,
   FUNCTION_HEADER,
   INSTANCE_HEADER,
   SINGLE_FLIGHT_HEADER,
+  clearFlashCookie,
   decodeErrorHeaderValue,
   decodeResponse,
+  decodeResponsePayload,
   encodeErrorHeaderValue,
   getServerFunctionMetadata,
+  hasFlashCookie,
   isServerFunction,
   subscribeFlightData,
   withMeta
@@ -22,6 +26,8 @@ export type {
   ServerFunctionMetadata,
   SingleFlightPayload
 } from "./shared.cjs";
+export { decodeFlashCookie, encodeFlashCookie } from "./flash.cjs";
+export type { FlashSubmission } from "./flash.cjs";
 import { ServerFunction } from "./shared.cjs";
 
 /**
@@ -63,6 +69,29 @@ export interface ServerFunctionOutcome {
   request: Request;
   /** Whether the result was thrown rather than returned. */
   thrown: boolean;
+  /**
+   * The URL the client will show after the mutation — the redirect
+   * `Location` when the outcome carries one (resolved against the request
+   * URL, as a browser would), the referring page otherwise. Undefined
+   * without a usable referer (a non-browser caller has no page to produce
+   * data for) and for redirects leaving the app's origin: produce no data
+   * when this is undefined.
+   */
+  targetUrl: string | undefined;
+  /**
+   * The outcome's `X-Revalidate` keys, split — the invalidation scope the
+   * mutation declared. Undefined when the outcome carries none (integrations
+   * typically collect everything for the target in that case).
+   */
+  revalidateKeys: string[] | undefined;
+  /**
+   * The request headers with the mutation's cookie effects applied: the
+   * event response's `Set-Cookie`s (set during the call), then the
+   * outcome's own (e.g. `redirect(to, { headers })`), later winning on
+   * conflict, deletions honored. Build the data-collection request from
+   * these so re-run reads observe post-mutation cookie state.
+   */
+  foldedHeaders: Headers;
 }
 
 /**
@@ -77,14 +106,69 @@ export interface ServerFunctionOutcome {
  * Runs after `transformResult`, only for scripted calls that sent
  * `SINGLE_FLIGHT_HEADER` on the request, on returned results and thrown
  * `Response`/`ResponseEnvelope` control-flow signals alike (plain thrown
- * errors never collect). The handler owns the enveloping: contributed data
- * ships as `{ value, data }` under the single-flight response header.
+ * errors never collect, and neither do raw body-carrying `Response` values
+ * — those are the caller's verbatim payload). The handler owns the
+ * enveloping: contributed data ships as `{ value, data }` under the
+ * single-flight response header. The generic halves of collection arrive
+ * pre-digested on the outcome (`targetUrl`, `revalidateKeys`,
+ * `foldedHeaders`); the hook supplies only the data strategy.
  */
 export type CollectFlightDataHook = (
   event: ServerFunctionEvent,
   outcome: ServerFunctionOutcome
 ) => unknown | Promise<unknown>;
 
+/**
+ * Request headers with `setCookies` folded into the `Cookie` header, as the
+ * browser would have applied them before its next request. Later entries
+ * win on conflict, and deletions are honored (`Max-Age` at or below zero,
+ * `Expires` in the past). The input headers are not modified.
+ *
+ * For work re-run on the server after a mutation — a
+ * `CollectFlightDataHook` gathering fresh data, typically. That pass starts
+ * from the request that triggered the mutation, whose cookies are
+ * pre-mutation by definition, so a read depending on a session the mutation
+ * just established would otherwise see the old state. Which responses
+ * contribute their `Set-Cookie`s, and in what order, is the caller's
+ * decision.
+ *
+ * @example
+ * ```ts
+ * const headers = foldSetCookies(event.request.headers, [
+ *   ...(event.response?.headers?.getSetCookie() ?? []),
+ *   ...(outcome.response?.headers?.getSetCookie() ?? [])
+ * ]);
+ * ```
+ */
+export function foldSetCookies(headers: Headers, setCookies: readonly string[]): Headers;
+
+/** Options for `createNoJSHandler`. */
+export interface NoJSHandlerOptions {
+  /** The app's mount path, for resolving a relative redirect `Location`. */
+  base?: string;
+}
+
+/**
+ * Builds the `handleNoJS` implementation for the no-JS form convention: a
+ * form posted without the client runtime has no way to receive a value, so
+ * the call redirects back to the referring page (or to the result's own
+ * `Location`, resolved against `base`) with the outcome riding a one-shot
+ * flash cookie. `303 See Other` turns the POST into a GET unless the result
+ * names a redirect status of its own. A result that is already a `Response`
+ * carries its meaning in its metadata and is not flashed.
+ *
+ * The render that follows reads the cookie with `decodeFlashCookie` and
+ * surfaces the outcome however it likes — that half is the integration's.
+ *
+ * The handler applies to every call it receives. `handleServerFunctionRequest`
+ * already uses it for browser form posts, so wire it explicitly only to set
+ * a `base`, or to extend the convention to direct HTTP calls by registering
+ * it through `configureServerFunctionsServer`.
+ */
+export function createNoJSHandler(
+  options?: NoJSHandlerOptions
+): (result: unknown, request: Request, args: unknown[], thrown?: boolean) => Response;
+
 /** Options for `configureServerFunctionsServer`. */
 export interface ServerFunctionsServerConfig {
   /**
@@ -119,6 +203,23 @@ export interface ServerFunctionsServerConfig {
    * calls during document SSR — e.g. frames' `frameTransformDirectResult`.
    */
   transformDirectResult?(value: unknown, options: { id: string }): unknown;
+  /**
+   * Server-wide response builder for calls made without the client runtime
+   * (see `handleNoJS` in `HandleServerFunctionRequestOptions`); a
+   * per-request option overrides it. Set it to `createNoJSHandler({ base })`
+   * to apply the convention to every non-scripted call rather than only to
+   * browser form posts, to a handler of your own to replace it, or to
+   * `null` to disable the built-in convention and answer form posts with
+   * the plain serialized response.
+   */
+  handleNoJS?:
+    | ((
+        result: unknown,
+        request: Request,
+        args: unknown[],
+        thrown?: boolean
+      ) => Response | Promise<Response>)
+    | null;
   /**
    * Endpoint the HTTP handler is mounted on, used for the `url` of SSR'd
    * references (e.g. form actions) — must match the client configuration.
@@ -285,11 +386,13 @@ export interface HandleServerFunctionOptions {
   collectFlightData?: CollectFlightDataHook;
   /**
    * Builds the response for calls made without the client runtime (no
-   * instance header — no-JS form posts, direct HTTP) — the extension
-   * point for conventions like redirect-with-flash-cookie. Receives the
+   * instance header — no-JS form posts, direct HTTP). Receives the
    * (transformed) result, the request, and the decoded arguments; `thrown`
-   * is set when the result was thrown rather than returned. Defaults to
-   * the normal serialized response.
+   * is set when the result was thrown rather than returned.
+   *
+   * Overrides the configured hook, which in turn overrides the built-in
+   * `createNoJSHandler()` applied to browser form posts. Other
+   * no-instance callers get the normal serialized response.
    */
   handleNoJS?(
     result: unknown,

package/types-cjs/server-functions/shared.d.cts

@@ -136,6 +136,41 @@ export type FlightDataConsumer<D = unknown> = (
  */
 export function subscribeFlightData<D = unknown>(consumer: FlightDataConsumer<D>): () => void;
 
+/**
+ * Name of the cookie carrying the outcome of a call made without the client
+ * runtime (`"flash"`). A no-JS form post has no way to receive a value —
+ * the browser follows the redirect and renders the next page — so the
+ * handler stashes the outcome here for the render after it to pick up,
+ * which is how a form submitted without JavaScript still shows its result.
+ *
+ * The name, detection and clearing are isomorphic (integrations read the
+ * cookie from code that also ships to the browser); the codec that fills it
+ * is server-only and lives behind the server entry.
+ */
+export const FLASH_COOKIE: string;
+
+/**
+ * Whether a Cookie header carries a flash cookie, readable or not. Cheap
+ * enough to call on every render so the clear can be queued before the
+ * response headers flush.
+ */
+export function hasFlashCookie(cookieHeader: string | null): boolean;
+
+/**
+ * The `Set-Cookie` value clearing the flash cookie. The outcome is
+ * one-shot: append this as soon as the cookie is detected, whether or not
+ * it decodes, so a stale outcome cannot resurface on a later request.
+ */
+export function clearFlashCookie(): string;
+
+/**
+ * The raw encoded flash payload out of a Cookie header, if present — the
+ * codec's own accessor.
+ *
+ * @internal
+ */
+export function matchFlashCookie(cookieHeader: string | null): string | undefined;
+
 /**
  * The currently registered single-flight consumer.
  *
@@ -370,6 +405,19 @@ export function decodeResponse<T = unknown>(
   codecOptions?: JSONCodecOptions
 ): Promise<T | undefined>;
 
+/**
+ * `decodeResponse` plus the single-flight envelope split: when the response
+ * carries the single-flight header the decoded `{ value, data }` payload is
+ * unwrapped into `{ value, flightData }`; otherwise the decoded body (or
+ * undefined for body-less responses) rides as `{ value }`. Integrations
+ * that apply response metadata themselves use this so the payload shape
+ * stays core's own.
+ */
+export function decodeResponsePayload<T = unknown, D = unknown>(
+  response: Response,
+  codecOptions?: JSONCodecOptions
+): Promise<{ value: T | undefined; flightData?: D }>;
+
 /**
  * Frame one payload for the server-function wire: a `;0x<len32>;` length
  * prefix followed by the utf-8 data. Both transports (server-function