@solidjs/web 2.0.0-rc.2 → 2.0.0-rc.3

package/types/response.d.ts

@@ -1,174 +1,62 @@
 /**
- * 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;
+ * Envelope pairing HTTP metadata with a 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.
+ */
+export interface ResponseEnvelope<T = unknown> {
+    response: Response | undefined;
+    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 ResponseEnvelope: {
+    new <T>(response: Response | undefined, value: T): ResponseEnvelope<T>;
+};
+/** Whether `value` is a `ResponseEnvelope` (robust across module copies). */
+export declare function isResponseEnvelope(value: unknown): value is ResponseEnvelope;
 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;
+    [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;
-
-/**
- * Registered-symbol brand (`Symbol.for("solid.SafeError")`) marking a thrown
- * value as safe to serialize to the client verbatim. Declared `unique
- * symbol` type-side; the runtime value is the registered symbol, so
- * separately bundled copies agree on identity.
- */
+/** Whether `value` is an `Href`-branded URL-bearing value. */
+export declare function isHref(value: unknown): value is Href;
 export declare const SAFE_ERROR: unique symbol;
-
 /**
  * Marks `error` as safe to serialize to the client verbatim, opting it out
- * of the server-function handler's production error sanitization.
- *
- * By default a plain `Error` thrown from a server function is sanitized to a
- * generic `Error` outside the dev build (the `development` export condition
- * selects the full-fidelity copy; every other resolution sanitizes):
- * its `message`, `stack`, and own-properties are dropped so a driver/ORM
- * error can't leak a failing query or connection string over the wire.
- * Dev builds keep full fidelity. This is the escape hatch for errors whose
- * content is *intentional* client-facing information — brand them and their
- * message/properties travel intact in every environment.
- *
- * The brand is a non-enumerable, symbol-keyed property, so it never itself
- * serializes as an own-property. Sets the brand and returns the same value.
- *
- * @example
- * ```ts
- * import { markSafeError } from "@solidjs/web";
- *
- * async function transfer(amount: number) {
- *   "use server";
- *   if (amount > balance) {
- *     // The user must see this message; opt out of sanitization.
- *     throw markSafeError(new Error("Insufficient funds"));
- *   }
- * }
- * ```
- */
-export function markSafeError<E>(error: E): E;
-
-/**
- * Whether `value` is branded safe to serialize (via `markSafeError`).
- * Registered-symbol check, correct across duplicated module instances.
+ * of production error sanitization (see `handleServerFunctionRequest`). Use
+ * for errors whose message/properties are intentional client-facing content.
+ * Returns the same value for convenient `throw markSafeError(new Error(...))`.
  */
-export function isSafeError(value: unknown): value is Error;
-
+export declare function markSafeError<E>(error: E): E;
+/** Whether `value` is branded safe to serialize (robust across module copies). */
+export declare function isSafeError(value: unknown): value is Error;
 /**
- * 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.
+ * Response header naming the cache keys a mutation invalidated, comma
+ * separated. Set by the helpers below and read by the client transport and
+ * by integrations; core never inspects the keys, so how they are matched
+ * (prefixes, exact names, namespaces) is the integration's business.
  */
-export const REVALIDATE_HEADER: string;
-
+export declare const REVALIDATE_HEADER = "X-Revalidate";
 /** `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[];
+    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" });
- * }
- * ```
+ * Response redirecting to `url` (default 302). `revalidate` names the
+ * cache keys the mutation invalidated.
  */
-export function redirect(url: string | Href, init?: number | ResponseHelperInit): Response;
-
+export declare 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" });
- * }
- * ```
+ * Empty response requesting revalidation of the named cache keys (all of
+ * them when omitted).
  */
-export function reload(init?: ResponseHelperInit): Response;
-
+export declare 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" });
- * }
- * ```
+ * for the things a naked return can't express. 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, while integrations read `value` — no reparse.
  */
-export function respond<T>(value: T, init?: ResponseHelperInit): ResponseEnvelope<T>;
+export declare function respond<T>(value: T, init?: ResponseHelperInit): ResponseEnvelope<T>;

package/types/serializer-decode.d.ts

@@ -1,23 +1,3 @@
-// The DECODE half of the serialization surface (published as
-// `@solidjs/web/serialization/decode`): what reading a serialized payload
-// needs — `fromCrossJSON`-backed deserializers and the shared plugin set —
-// with none of the encode machinery. Lazy client consumers (the frames
-// data tables, `deserializeStream`) load this module so the encode half
-// never ships to a browser that only reads. The full serializer.d.ts
-// re-exports everything here; see its banner for the stability contract
-// (integration-facing, exempt from the 2.0 stability guarantee).
-// ---- Plugin types ----
-//
-// Declared here by hand (seroval's published d.ts use extensionless
-// ESM-relative imports that `moduleResolution: "nodenext"` cannot follow —
-// a bare type re-export would silently degrade the surface to `any` under
-// skipLibCheck, and an import would make every entry whose types reach
-// this module — the MAIN client entry included, via the server-function
-// seam's `JSONCodecOptions` — unimportable from a strict Node16 CJS
-// consumer). The declarations mirror seroval ~1.5 exactly; the `~` pin is
-// what makes mirroring safe. Plugin AUTHORING (`createPlugin`,
-// `OpaqueReference`) lives on the full serialization entry.
-
 /**
  * Seroval's node shape — the intermediate representation `serializeJSON`
  * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
@@ -29,59 +9,53 @@
  * Integration-facing; may change (see the entry banner).
  */
 export interface SerovalNode {
-  /** Node type tag (seroval-internal enum). */
-  t: number;
-  /** Reference id, when the node participates in cross-referencing. */
-  i?: number | undefined;
-  [key: string]: unknown;
+    /** Node type tag (seroval-internal enum). */
+    t: number;
+    /** Reference id, when the node participates in cross-referencing. */
+    i?: number | undefined;
+    [key: string]: unknown;
 }
-
 /** Per-plugin bookkeeping seroval hands each plugin callback. */
 export interface PluginData {
-  id: number;
+    id: number;
 }
-
 /**
  * The shape of a plugin's parsed payload: a map of `SerovalNode`s produced
  * by the parse contexts, consumed by `serialize`/`deserialize`.
  */
-export type PluginInfo = { [key: string]: SerovalNode };
-
+export type PluginInfo = {
+    [key: string]: SerovalNode;
+};
 /** Parse context for `parse.sync`: turns child values into nodes. */
 export interface SyncParsePluginContext {
-  parse<T>(current: T): SerovalNode;
+    parse<T>(current: T): SerovalNode;
 }
-
 /** Parse context for `parse.async`: like sync, but child parses await. */
 export interface AsyncParsePluginContext {
-  parse<T>(current: T): Promise<SerovalNode>;
+    parse<T>(current: T): Promise<SerovalNode>;
 }
-
 /**
  * Parse context for `parse.stream`: sync parsing plus the streaming
  * lifecycle (pending-state tracking, late node emission, cleanup).
  */
 export interface StreamParsePluginContext {
-  parse<T>(current: T): SerovalNode;
-  parseWithError<T>(current: T): SerovalNode | undefined;
-  isAlive(): boolean;
-  pushPendingState(): void;
-  popPendingState(): void;
-  onParse(node: SerovalNode): void;
-  onError(error: unknown): void;
-  addCleanup(callback: () => void): void;
+    parse<T>(current: T): SerovalNode;
+    parseWithError<T>(current: T): SerovalNode | undefined;
+    isAlive(): boolean;
+    pushPendingState(): void;
+    popPendingState(): void;
+    onParse(node: SerovalNode): void;
+    onError(error: unknown): void;
+    addCleanup(callback: () => void): void;
 }
-
 /** Serialize context: renders child nodes to JS source. */
 export interface SerializePluginContext {
-  serialize(node: SerovalNode): string;
+    serialize(node: SerovalNode): string;
 }
-
 /** Deserialize context: revives child nodes to runtime values. */
 export interface DeserializePluginContext {
-  deserialize<T>(node: SerovalNode): T;
+    deserialize<T>(node: SerovalNode): T;
 }
-
 /**
  * A Seroval plugin usable with the web serializers — teaches the codec how
  * to encode/decode a custom value type (`Value` is the value it matches,
@@ -92,44 +66,23 @@ export interface DeserializePluginContext {
  * Integration-facing; may change (see the entry banner).
  */
 export interface SerializerPlugin<Value = any, Info extends PluginInfo = any> {
-  /** A unique string identifying the plugin — namespace it (`"app/Thing"`). */
-  tag: string;
-  /** Dependency plugins, resolved ahead of this one. */
-  extends?: SerializerPlugin[];
-  /** Whether `value` is this plugin's to encode. */
-  test(value: unknown): boolean;
-  /** Parsing modes — provide the ones the transports you target use. */
-  parse: {
-    sync?: (value: Value, ctx: SyncParsePluginContext, data: PluginData) => Info;
-    async?: (value: Value, ctx: AsyncParsePluginContext, data: PluginData) => Promise<Info>;
-    stream?: (value: Value, ctx: StreamParsePluginContext, data: PluginData) => Info;
-  };
-  /** Renders the parsed payload as JS source (script-injection form). */
-  serialize(node: Info, ctx: SerializePluginContext, data: PluginData): string;
-  /** Revives the parsed payload back into the runtime value. */
-  deserialize(node: Info, ctx: DeserializePluginContext, data: PluginData): Value;
+    /** A unique string identifying the plugin — namespace it (`"app/Thing"`). */
+    tag: string;
+    /** Dependency plugins, resolved ahead of this one. */
+    extends?: SerializerPlugin[];
+    /** Whether `value` is this plugin's to encode. */
+    test(value: unknown): boolean;
+    /** Parsing modes — provide the ones the transports you target use. */
+    parse: {
+        sync?: (value: Value, ctx: SyncParsePluginContext, data: PluginData) => Info;
+        async?: (value: Value, ctx: AsyncParsePluginContext, data: PluginData) => Promise<Info>;
+        stream?: (value: Value, ctx: StreamParsePluginContext, data: PluginData) => Info;
+    };
+    /** Renders the parsed payload as JS source (script-injection form). */
+    serialize(node: Info, ctx: SerializePluginContext, data: PluginData): string;
+    /** Revives the parsed payload back into the runtime value. */
+    deserialize(node: Info, ctx: DeserializePluginContext, data: PluginData): Value;
 }
-
-/**
- * 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`.
- *
- * Integration-facing; may change (see the entry banner).
- */
-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.
- *
- * Integration-facing; may change (see the entry banner).
- */
-export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
-
 /**
  * Options shared by both halves of the JSON codec. All of them must match
  * on the serializing and deserializing peer or payloads will not
@@ -139,32 +92,20 @@ export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): Se
  * Integration-facing; may change (see the entry banner).
  */
 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;
+    /** 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;
 }
-
-/**
- * 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.
- *
- * Integration-facing; may change (see the entry banner).
- */
-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
@@ -176,7 +117,43 @@ export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: Se
  * it internally rather than re-exporting it.
  */
 export interface JSONDataTable {
-  apply(chunk: { key?: string; node?: unknown; initial?: boolean }): void;
-  resolve<T = unknown>(ref: { $ref: string }): T;
+    apply(chunk: {
+        key?: string;
+        node?: unknown;
+        initial?: boolean;
+    }): void;
+    resolve<T = unknown>(ref: {
+        $ref: string;
+    }): T;
 }
-export function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;
+/**
+ * Baseline plugin set for serializing web-platform values. Shared by the
+ * hydration serializer and any consumer building its own serializer (e.g.
+ * server function transports). Plugin objects carry both their serialize
+ * and deserialize halves, so the set lives on the decode side and the
+ * encode module composes over it.
+ */
+export declare const DEFAULT_WEB_PLUGINS: any; /**
+ * 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.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+export declare function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
+export declare function resolveCodecOptions({ plugins, disabledFeatures, depthLimit }?: JSONCodecOptions): {
+    plugins: SerializerPlugin<any, any>[];
+    disabledFeatures: any;
+    depthLimit: number;
+}; /**
+ * 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.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+export declare function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
+export declare function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;