@solidjs/web 2.0.0-beta.3 → 2.0.0-beta.30

package/types/response.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Envelope pairing HTTP metadata (a `Response`) with an in-memory value.
+ * Produced by `respond()` and by server-function `transformResult`
+ * implementations (e.g. single-flight payloads). The HTTP handler forwards
+ * `response`'s headers and (non-redirect) status and encodes `value` as the
+ * body through the codec, while client-only integrations read `value`
+ * directly — no reparse. Mostly consumed by integrations (routers);
+ * application code usually just returns what `respond()` gives it.
+ */
+export class ResponseEnvelope<T = unknown> {
+  constructor(response: Response | undefined, value: T);
+  /** The HTTP metadata: status and headers to forward (body ignored by integrations). */
+  response: Response | undefined;
+  /** The structured value the caller receives. */
+  value: T;
+}
+
+/**
+ * Whether `value` is a `ResponseEnvelope`. Uses a registered-symbol brand
+ * rather than `instanceof`, so it stays correct when separately bundled
+ * entries each carry a copy of the class. Integrations should always use
+ * this over `instanceof`.
+ */
+export function isResponseEnvelope(value: unknown): value is ResponseEnvelope;
+
+/**
+ * Registered-symbol brand (`Symbol.for("solid.Href")`) marking URL-bearing
+ * values. Declared `unique symbol` type-side; the runtime value is the
+ * registered symbol, so separately bundled copies agree on identity.
+ */
+export declare const HREF: unique symbol;
+
+/**
+ * A URL-bearing value: coerces to its URL via `toString()` and carries the
+ * `HREF` registered-symbol brand. Integrations mint these (e.g. a router's
+ * typed path objects answer the brand from their proxy) and URL-accepting
+ * APIs like `redirect()` accept them alongside plain strings. The brand is
+ * what makes the type meaningful — every object has `toString()`.
+ */
+export interface Href {
+  [HREF]: true;
+  toString(): string;
+}
+
+/**
+ * Whether `value` is an `Href`-branded URL-bearing value. Registered-symbol
+ * check, so it stays correct across duplicated module instances — same
+ * rationale as `isResponseEnvelope`.
+ */
+export function isHref(value: unknown): value is Href;
+
+/**
+ * Response header naming the cache keys a mutation invalidated
+ * (`"X-Revalidate"`), comma separated. The response helpers below set it
+ * from their `revalidate` option; the client transport treats its presence
+ * as control flow, and integrations read it to invalidate their own cache.
+ * Core never inspects the keys, so how they are matched (prefixes, exact
+ * names, namespaces) is the integration's business.
+ */
+export const REVALIDATE_HEADER: string;
+
+/** `ResponseInit` accepted by the response helpers, plus `revalidate`. */
+export interface ResponseHelperInit extends ResponseInit {
+  /**
+   * Cache keys the mutation invalidated, carried in the `X-Revalidate`
+   * header. Opaque to the protocol — the integration's keyed cache (e.g.
+   * the router's `query` cache) assigns them meaning.
+   */
+  revalidate?: string | string[];
+}
+
+/**
+ * Response redirecting to `url` (default status 302). Return (or throw) it
+ * from a server function — the HTTP handler forwards the redirect for the
+ * client integration to follow — or return it from a client-side action,
+ * where the integration interprets it in memory. Same object, same
+ * meaning, both sides.
+ *
+ * @example
+ * ```ts
+ * import { redirect } from "@solidjs/web";
+ *
+ * async function login(form: FormData) {
+ *   "use server";
+ *   // ...
+ *   return redirect("/dashboard", { revalidate: "session" });
+ * }
+ * ```
+ */
+export function redirect(url: string | Href, init?: number | ResponseHelperInit): Response;
+
+/**
+ * Empty response requesting revalidation of the named cache keys — all of
+ * them when omitted. For mutations whose only effect the caller needs is
+ * "refetch your data".
+ *
+ * @example
+ * ```ts
+ * import { reload } from "@solidjs/web";
+ *
+ * async function addTodo(title: string) {
+ *   "use server";
+ *   await db.insert(title);
+ *   return reload({ revalidate: "todos" });
+ * }
+ * ```
+ */
+export function reload(init?: ResponseHelperInit): Response;
+
+/**
+ * A value paired with response metadata (status, headers, `revalidate`) —
+ * for the things a naked return can't express. Scripted callers receive
+ * `value` transparently (the transport unwraps the envelope), and
+ * progressive enhancement stays invisible: the carried response holds a
+ * plain JSON body so consumers without the client runtime (no-JS form
+ * posts, direct HTTP) get real JSON.
+ *
+ * @example
+ * ```ts
+ * import { respond } from "@solidjs/web";
+ *
+ * async function createItem(input: Item) {
+ *   "use server";
+ *   const item = await db.create(input);
+ *   return respond(item, { status: 201, revalidate: "items" });
+ * }
+ * ```
+ */
+export function respond<T>(value: T, init?: ResponseHelperInit): ResponseEnvelope<T>;

package/types/serializer.d.ts

@@ -0,0 +1,157 @@
+import { Plugin, Serializer, SerovalNode } from "seroval";
+
+/**
+ * Seroval's node shape — the intermediate representation `serializeJSON`
+ * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
+ */
+export type { SerovalNode };
+
+/**
+ * A Seroval plugin usable with the web serializers — teaches the codec how
+ * to encode/decode a custom value type. Supply matching plugins on both
+ * peers of a transport.
+ */
+export type SerializerPlugin = Plugin<any, any>;
+
+/**
+ * Baseline plugin set for serializing web-platform values (AbortSignal,
+ * Event, FormData, Headers, ReadableStream, Request, Response, URL, ...).
+ * Applied by every serializer in this module; custom plugins compose ahead
+ * of it via `resolveSerializerPlugins`.
+ */
+export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
+
+/**
+ * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
+ * first so they can shadow a default for values both would match. Returns a
+ * fresh array; the defaults are never mutated. Useful when handing a full
+ * plugin list to another serialization layer.
+ */
+export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
+
+/** Options for `createSerializer`. */
+export interface WebSerializerOptions {
+  /** Name of the global object the emitted scripts write resolved values into. */
+  globalIdentifier: string;
+  /** Cross-reference scope id, for isolating multiple streams on one page. */
+  scopeId?: string;
+  /**
+   * Seroval feature bitflags to exclude from output. Defaults to disabling
+   * post-ES2017 features (AggregateError, BigInt typed arrays). Outside
+   * development, `Error.prototype.stack` is additionally stripped on top of
+   * any override — serialized stacks leak server paths to the client.
+   */
+  disabledFeatures?: number;
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. */
+  plugins?: SerializerPlugin[];
+  /** Receives each emitted script chunk. */
+  onData: (result: string) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once all async values have settled. */
+  onDone?: () => void;
+}
+
+/**
+ * Creates a streaming Seroval serializer preconfigured with the web plugin
+ * set and the default feature policy. Emits JavaScript chunks (through
+ * `onData`) that reconstruct the values under `globalIdentifier` when
+ * evaluated — the script-injection form of serialization renderers build
+ * on. For a JSON-based wire codec (no eval on the receiving side), use
+ * `serializeJSON` / `createJSONDeserializer` instead.
+ */
+export function createSerializer(options: WebSerializerOptions): Serializer;
+
+/**
+ * Options for `createHydrationSerializer` — `WebSerializerOptions` minus
+ * the knobs hydration pins (`globalIdentifier`, `disabledFeatures`).
+ * @internal
+ */
+export type HydrationSerializerOptions = Omit<
+  WebSerializerOptions,
+  "globalIdentifier" | "disabledFeatures"
+>;
+
+/**
+ * Renderer primitive — the serializer SSR uses for hydration output. Pins
+ * the hydration global (`_$HY.r`) and feature policy; only the wiring
+ * options (callbacks, scope, extra plugins) are configurable. Not meant
+ * for hand-written code — custom serialization should use
+ * `createSerializer` or the JSON codec.
+ * @internal
+ */
+export function createHydrationSerializer(options: HydrationSerializerOptions): Serializer;
+
+/**
+ * Renderer primitive — returns the cross-reference bootstrap script SSR
+ * emits ahead of hydration data for a render scope. Not meant for
+ * hand-written code.
+ * @internal
+ */
+export function getLocalHeaderScript(id?: string): string;
+
+// ---- JSON codec (server function transports) ----
+
+/**
+ * Options shared by both halves of the JSON codec. All of them must match
+ * on the serializing and deserializing peer or payloads will not
+ * round-trip — for server functions, set them once through the
+ * client/server `codec` config option.
+ */
+export interface JSONCodecOptions {
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
+  plugins?: SerializerPlugin[];
+  /**
+   * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
+   * (payloads may come from an untrusted peer). Must match on both peers.
+   * Outside development, the encoding side additionally strips
+   * `Error.prototype.stack` on top of any override — serialized stacks leak
+   * server paths to the client. Decoding stays permissive, so payloads from
+   * a development peer still round-trip.
+   */
+  disabledFeatures?: number;
+  /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
+  depthLimit?: number;
+}
+
+/** Options for `serializeJSON`. */
+export interface JSONSerializeOptions extends JSONCodecOptions {
+  /**
+   * Receives each serialized node; `initial` is true for the first chunk
+   * (the source value itself). Async values produce additional chunks as
+   * they resolve.
+   */
+  onParse: (node: SerovalNode, initial: boolean) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once all async values have settled. */
+  onDone?: () => void;
+}
+
+/**
+ * Serializes `value` as SerovalNode chunks delivered through `onParse` —
+ * the encoding half of the eval-free JSON codec (RPC-style transports;
+ * the deserializing peer needs no script evaluation, so CSP-safe). Wire
+ * framing of the nodes is the transport's concern. Returns a cancel
+ * function that aborts pending async serialization.
+ */
+export function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
+
+/**
+ * Creates the decoding counterpart of `serializeJSON`. Cross-references
+ * between chunks resolve through state shared across calls, so all chunks
+ * from one stream must go through the same deserializer instance. The first
+ * chunk's return value is the decoded source value; feeding later chunks
+ * settles the async values referenced inside it.
+ */
+export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
+
+/**
+ * A resident, response-scoped decode table over the keyed JSON codec: apply
+ * each frame `data` chunk with `apply`, resolve `{ $ref }` slot args with
+ * `resolve`. The frames client host wires one per response
+ * (`applyData: c => table.apply(c)`).
+ */
+export interface JSONDataTable {
+  apply(chunk: { key?: string; node?: unknown; initial?: boolean }): void;
+  resolve<T = unknown>(ref: { $ref: string }): T;
+}
+export function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;

package/types/server-functions/client.d.ts

@@ -0,0 +1,200 @@
+import { JSONCodecOptions } from "../serializer.js";
+import { ServerFunction, ServerFunctionMetadata } from "./shared.js";
+
+export {
+  ChunkReader,
+  ERROR_HEADER,
+  FLASH_COOKIE,
+  FUNCTION_HEADER,
+  INSTANCE_HEADER,
+  SINGLE_FLIGHT_HEADER,
+  clearFlashCookie,
+  createChunk,
+  decodeErrorHeaderValue,
+  decodeResponse,
+  decodeResponsePayload,
+  deserializeStream,
+  encodeErrorHeaderValue,
+  frameAddress,
+  getFlightDataConsumer,
+  getServerFunctionMetadata,
+  getServerFunctionsCodec,
+  hasFlashCookie,
+  isServerFunction,
+  subscribeFlightData,
+  withMeta
+} from "./shared.js";
+export { REVALIDATE_HEADER } from "../response.js";
+export type {
+  FlightDataConsumer,
+  FlightDataContext,
+  ServerFunction,
+  ServerFunctionMetadata,
+  SingleFlightPayload
+} from "./shared.js";
+
+/** The context `prepareRequest` receives alongside the outgoing RequestInit. */
+export interface PrepareRequestContext {
+  /** The build-stable id of the function being called. */
+  id: string;
+  /**
+   * The reference's declaration metadata (e.g. `method: "GET"` for
+   * `GET(fn)` references). Plain references carry an empty object.
+   */
+  meta: ServerFunctionMetadata | undefined;
+}
+
+/**
+ * Client-side session-dynamic transport hook: runs before every
+ * server-function fetch. Return (or mutate and return) the RequestInit the
+ * transport will use — the hook sees the final init, transport headers
+ * included. The motivating case is dynamic credentials that rotate during
+ * a session and apply uniformly to every call (OAuth bearer tokens); it is
+ * the client-side symmetric of the server handler hooks. Single hook, not
+ * a chain — compose by wrapping functions in userland.
+ */
+export type PrepareRequestHook = (
+  init: RequestInit,
+  context: PrepareRequestContext
+) => RequestInit | Promise<RequestInit>;
+
+/** Options for `configureServerFunctionsClient`. */
+export interface ServerFunctionsClientConfig {
+  /**
+   * Endpoint the server's HTTP handler is mounted on. Must match the
+   * server configuration — SSR'd reference `url`s (e.g. form actions) and
+   * client fetches both derive from it. Prefix it when the app serves from
+   * a base path (e.g. `` `${BASE_URL}_server` ``).
+   * @default "/_server"
+   */
+  endpoint?: string;
+  /**
+   * Codec options (extra plugins etc.) for encoding arguments and decoding
+   * results — must match the server's. Stored in the shared layer, so
+   * `decodeResponse` sees them too.
+   */
+  codec?: JSONCodecOptions;
+  /**
+   * Runs before every server-function fetch. Return (or mutate and return)
+   * the RequestInit the transport will use; `context.meta` is the
+   * reference's declaration metadata (e.g. method). For session-dynamic
+   * cross-cutting concerns — bearer tokens, tracing headers:
+   *
+   * ```ts
+   * configureServerFunctionsClient({
+   *   prepareRequest(init) {
+   *     return {
+   *       ...init,
+   *       headers: { ...init.headers, Authorization: `Bearer ${session.token()}` }
+   *     };
+   *   }
+   * });
+   * ```
+   */
+  prepareRequest?: PrepareRequestHook;
+  /**
+   * Response-side integration seam — the client mirror of the handler's
+   * `transformResult`. `handle(response, ctx)` sees every response before
+   * the transport decodes it; returning anything but undefined resolves the
+   * call with that value. `capture(info)` runs synchronously at the call
+   * site (before any await) and its return arrives as `ctx.context`, so
+   * ambient per-call state (e.g. a reactive owner) survives to response
+   * time. See `createServerComponentHandler` in frame-transport for the
+   * canonical implementation.
+   */
+  responseHandler?: {
+    capture?(info: { id: string; meta: unknown }): unknown;
+    handle(
+      response: Response,
+      ctx: { id: string; meta: unknown; args: unknown[]; context: unknown }
+    ): unknown;
+  };
+  /**
+   * Encoder for argument lists JSON can't carry faithfully. JSON-safe args
+   * always go as plain JSON (no codec in the bundle); anything else throws
+   * unless this is set. Installed by `enableRichArguments()` from the
+   * rich-args entry — set directly only for custom wire encodings.
+   */
+  serializeArgs?(args: unknown[]): string | Promise<string>;
+}
+
+/**
+ * Configures the client transport. Call once, before any server function is
+ * invoked — typically in the client entry, next to `hydrate()`. Only needed
+ * when deviating from the defaults (custom endpoint, codec plugins, or a
+ * `prepareRequest` hook).
+ */
+export function configureServerFunctionsClient(config?: ServerFunctionsClientConfig): void;
+
+/**
+ * Declares a server function callable over HTTP GET: calls to the returned
+ * reference go out as GET requests with the arguments codec-encoded in the
+ * query string — cacheable by HTTP infrastructure. Cache headers flow
+ * through the handler's header forwarding
+ * (`respond(data, { headers: { "cache-control": "max-age=60" } })`).
+ *
+ * The declaration rides the metadata channel
+ * (`getServerFunctionMetadata(fn)?.method === "GET"`) for routers and
+ * integrations to detect, and the server honors it: GET-declared functions
+ * accept GET requests in addition to the default POST transport (declaring
+ * GET grants, it does not revoke); functions that never declared GET answer
+ * GET requests with 405. Server-side the wrapper is identity-flavored — SSR
+ * calls stay in-process.
+ *
+ * Wrap the reference at its declaration; the compiler round-trips the call
+ * in both builds:
+ *
+ * ```ts
+ * export const getUser = GET(async (id: string) => {
+ *   "use server";
+ *   return db.users.find(id);
+ * });
+ * ```
+ */
+export function GET<A extends readonly any[], R>(
+  fn: (...args: A) => R
+): ServerFunction<A, Awaited<R>>;
+
+/**
+ * Compiler ABI — emitted by compiled `"use server"` client output where a
+ * server function was referenced; produces the fetch-backed callable for
+ * the function's build-stable id. Development builds pass the function's
+ * source name as the trailing argument (dev-only metadata seeded on the
+ * metadata channel; never emitted in production). Not meant for
+ * hand-written code.
+ *
+ * The optional `base` targets calls at that url verbatim instead of the
+ * configured endpoint — for integrations reconstructing a callable from a
+ * server-rendered action url (e.g. a router intercepting a form submit whose
+ * `action="/_server?id=...&args=..."` came off the wire): bound arguments
+ * stay in the query string, where the server reads them for natural-encoding
+ * bodies (FormData, urlencoded).
+ * @internal
+ */
+export function createServerReference(id: string, name?: string, base?: string): ServerFunction;
+
+/**
+ * Compiler ABI — only ever referenced by server-mode compiler output;
+ * throws so a misconfigured build (server transform feeding a client
+ * bundle) fails loudly instead of with a missing-export error. Not meant
+ * for hand-written code.
+ * @internal
+ */
+export function registerServerReference(): never;
+
+/**
+ * Identity of the currently executing server function call — see the
+ * server entry. Named here so isomorphic code can import the type from
+ * either entry.
+ */
+export interface ServerFunctionInvocation {
+  id: string;
+}
+
+/**
+ * Client no-op mirror of the server entry's accessor: there is never a
+ * server function call in flight on the client, so this always returns
+ * undefined. Present so `"use server"` modules that import it stay
+ * import-stable in client builds before dead-code elimination.
+ */
+export function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;

package/types/server-functions/flash.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The outcome of a call made without the client runtime, as it rides the
+ * flash cookie: what was submitted, where, and what came back. `result` and
+ * `error` are mutually exclusive — a thrown outcome fills `error`, a
+ * returned one fills `result` — mirroring the split a scripted call sees.
+ */
+export interface FlashSubmission {
+  /** The arguments the call was made with (files are dropped). */
+  input: any[];
+  /** The call's url: pathname + search of the server function request. */
+  url: string;
+  /** The returned value, when the call returned. */
+  result?: any;
+  /** The thrown value, when the call threw. */
+  error?: any;
+}
+
+/**
+ * Encodes the outcome of a no-JS call as a `Set-Cookie` value, for the
+ * handler to send with its redirect. `url` identifies which submission the
+ * outcome belongs to; pass `thrown` when the call threw rather than
+ * returned.
+ *
+ * The payload is JSON inside the cookie: `FormData` and `URLSearchParams`
+ * arguments are captured as entry pairs and revived on decode, and `File`
+ * entries are dropped (they cannot ride a cookie). Keep in mind the 4 KB
+ * cookie budget — outcomes larger than that will not survive the round
+ * trip.
+ */
+export function encodeFlashCookie(url: string, result: any, input: any[], thrown?: boolean): string;
+
+/**
+ * Decodes the flash cookie out of a request's `Cookie` header, for the
+ * render that follows the redirect. Returns undefined when the cookie is
+ * absent or unreadable — a malformed cookie never takes down the render,
+ * and `clearFlashCookie` should be appended regardless.
+ */
+export function decodeFlashCookie(cookieHeader: string | null): FlashSubmission | undefined;