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

package/serialization/types-cjs/serializer.d.cts

@@ -0,0 +1,94 @@
+import { Serializer } from "seroval";
+import type { JSONCodecOptions, PluginInfo, SerializerPlugin, SerovalNode } from "./serializer-decode.cjs";
+export { DEFAULT_WEB_PLUGINS, createJSONDataTable, createJSONDeserializer, resolveSerializerPlugins } from "./serializer-decode.cjs";
+export type * from "./serializer-decode.cjs";
+/**
+ * Options for `createSerializer`.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+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;
+}
+/**
+ * Options for `createHydrationSerializer` — `WebSerializerOptions` minus
+ * the knobs hydration pins (`globalIdentifier`, `disabledFeatures`).
+ * @internal
+ */
+export type HydrationSerializerOptions = Omit<WebSerializerOptions, "globalIdentifier" | "disabledFeatures">;
+/**
+ * Options for `serializeJSON`.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+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;
+}
+/** Options for `createJSONSerializer`. */
+export interface JSONSerializerOptions extends JSONCodecOptions {
+    /**
+     * Receives each keyed record — `initial` is true for a key's first node
+     * (the written value itself); async values patch through later records
+     * under the same key. The decoding peer is `createJSONDataTable`.
+     */
+    onData: (record: {
+        key: string;
+        node: SerovalNode;
+        initial: boolean;
+    }) => void;
+    onError?: (error: unknown) => void;
+    /** Fires once `flush()` has been called and every pending value settled. */
+    onDone?: () => void;
+}
+export declare const createPlugin: <Value, Info extends PluginInfo>(plugin: SerializerPlugin<Value, Info>) => SerializerPlugin<Value, Info>;
+export interface OpaqueReference<V = unknown, R = undefined> {
+    readonly value: V;
+    readonly replacement?: R;
+}
+export declare const OpaqueReference: {
+    new <V, R = undefined>(value: V, replacement?: R): OpaqueReference<V, R>;
+};
+/**
+ * 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.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+export declare function createSerializer(options: WebSerializerOptions): Serializer;
+export declare function createHydrationSerializer(options: HydrationSerializerOptions): Serializer;
+export declare function getLocalHeaderScript(id?: string): string;
+export declare function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
+export declare function createJSONSerializer(options: JSONSerializerOptions): {
+    write(key: string, value: unknown): void;
+    flush(): void;
+    close(): void;
+};

package/server-functions/dist/client.cjs

@@ -18,6 +18,32 @@ function withMeta(fn, meta) {
   Object.assign(metadata, meta);
   return fn;
 }
+const SERVER_FUNCTION_INVOKE = Symbol.for("solid.ServerFunctionInvoke");
+const INVOKE_OPTION_REDIRECTS = {
+  headers: "Session-dynamic headers belong to the prepareRequest hook, declaration metadata to " + "withMeta(fn, meta), and data belongs in the arguments, where it is serialized, typed, " + "and part of the cache key.",
+  method: "The method is declaration-scoped: declare the function with GET(fn).",
+  body: "The arguments are the body: pass them in the args array.",
+  timeout: "Compose timeouts through `signal` with AbortSignal.timeout(ms) (and AbortSignal.any to " + "combine it with a caller signal)."
+};
+function invoke(fn, options, ...args) {
+  const channel = typeof fn === "function" && fn[SERVER_FUNCTION_INVOKE];
+  if (!channel) {
+    throw new Error(isServerFunction(fn) ? "invoke: this wrapper does not forward the invocation channel " + "(SERVER_FUNCTION_INVOKE). Wrappers that share calls (caches, channels) opt in " + "deliberately — a caller's signal cannot own a wire other callers share. Invoke " + "the underlying reference directly, or use the wrapper's own per-call idioms." : "invoke expects a server function reference (or a wrapper that forwards its " + "invocation channel). Per-call options apply at the transport; for a data " + "layer's calls, use its per-call options instead.");
+  }
+  if (options === null || typeof options !== "object") {
+    throw new Error("invoke's second argument is the invocation options bag: invoke(fn, { signal }, ...args)");
+  }
+  const picked = {};
+  for (const key in options) {
+    if (key !== "signal" && key !== "keepalive" && key !== "priority") {
+      throw new Error(`\`${key}\` is not an invocation option. ` + (INVOKE_OPTION_REDIRECTS[key] || "Options here are strictly invocation-scoped (they vary between calls of the " + "same function): signal, keepalive, priority."));
+    }
+  }
+  if (options.signal !== undefined) picked.signal = options.signal;
+  if (options.keepalive !== undefined) picked.keepalive = options.keepalive;
+  if (options.priority !== undefined) picked.priority = options.priority;
+  return channel(args, picked);
+}
 const LIVE_SOURCE = Symbol.for("solid.LiveSource");
 const SERVER_FUNCTION_RPC = Symbol.for("solid.ServerFunctionRPC");
 function provideServerFunctionRPC(rpc) {
@@ -98,7 +124,23 @@ function stableString(value, seen) {
   }
   return out + "}";
 }
-const FUNCTION_HEADER = "X-Server-Function-Id";
+function serverFunctionAddress(endpoint, id) {
+  const mount = endpoint.endsWith("/") ? endpoint.slice(0, -1) : endpoint;
+  return `${mount}/${encodeURIComponent(id)}`;
+}
+function parseServerFunctionAddress(pathname, endpoint) {
+  const mount = endpoint.endsWith("/") ? endpoint.slice(0, -1) : endpoint;
+  if (!pathname.startsWith(mount)) return null;
+  const rest = pathname.slice(mount.length);
+  if (!rest.startsWith("/")) return null;
+  const segment = rest.slice(1);
+  if (!segment || segment.includes("/")) return null;
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return null;
+  }
+}
 const ERROR_HEADER = "X-Server-Function-Error";
 const ERROR_HEADER_MARKER = "=?1?";
 const NEEDS_ENCODING = /[^\x20-\x7e\xa0-\xff]/;
@@ -137,7 +179,8 @@ const BodyFormat = {
   File: "5",
   ArrayBuffer: "6",
   Uint8Array: "7",
-  Json: "8"
+  Json: "8",
+  Void: "9"
 };
 const JSON_SAFE_DEPTH_LIMIT = 4096;
 const EXIT = {};
@@ -392,6 +435,7 @@ async function decodeResponsePayload(response, codecOptions) {
 
 const config = {
   endpoint: "/_server",
+  fetch: undefined,
   prepareRequest: undefined,
   responseHandler: undefined,
   serializeArgs: undefined
@@ -420,6 +464,17 @@ function observeServerFunctionCalls(observer) {
   CALL_OBSERVERS.add(observer);
   return () => CALL_OBSERVERS.delete(observer);
 }
+function serverFunctionUrl(id, boundArgs) {
+  const address = serverFunctionAddress(config.endpoint, id);
+  if (!boundArgs || !boundArgs.length) return address;
+  if (!isJSONSafe(boundArgs)) {
+    throw new Error("Bound arguments in an action url must be JSON-safe: the server reads them the way it " + "reads a form post's, and that convention has no codec. Pass the value through the " + "function's body, or call the reference instead of rendering a url for it.");
+  }
+  return `${address}?args=${encodeURIComponent(JSON.stringify(boundArgs))}`;
+}
+function parseServerFunctionUrl(url) {
+  return parseServerFunctionAddress(new URL(url, globalThis.location?.href || "http://localhost").pathname, config.endpoint);
+}
 function serializeArguments(args) {
   if (!config.serializeArgs) {
     throw new Error("Server function arguments are sent as JSON by default and these " + "arguments are not JSON-serializable. Call enableRichArguments() " + '(from "@solidjs/web/server-functions/rich-args") once at startup ' + "to send Dates, Maps, Sets, typed arrays, etc. through the codec — " + "or pass a single Blob/FormData/File argument, which has a native " + "HTTP encoding.");
@@ -429,17 +484,20 @@ function serializeArguments(args) {
 function configureServerFunctionsClient({
   endpoint,
   codec,
+  fetch,
   prepareRequest,
   responseHandler,
   serializeArgs
 } = {}) {
   if (endpoint !== undefined) config.endpoint = endpoint;
   if (codec !== undefined) configureServerFunctionsCodec(codec);
+  if (fetch !== undefined) config.fetch = fetch;
   if (prepareRequest !== undefined) config.prepareRequest = prepareRequest;
   if (responseHandler !== undefined) config.responseHandler = responseHandler;
   if (serializeArgs !== undefined) config.serializeArgs = serializeArgs;
 }
 let INSTANCE = 0;
+const MAX_GET_URL_LENGTH = 2000;
 let rpcProvided = false;
 function provideRPC() {
   if (rpcProvided) return;
@@ -457,7 +515,6 @@ function serverFunctionFailure(response, value) {
 async function createRequest(base, id, instance, options, meta) {
   const headers = {
     ...options.headers,
-    [FUNCTION_HEADER]: id,
     [INSTANCE_HEADER]: instance
   };
   if (getFlightDataConsumer() && !options.read && (!options.method || options.method.toUpperCase() !== "GET")) {
@@ -474,10 +531,14 @@ async function createRequest(base, id, instance, options, meta) {
       meta
     })) || init;
   }
-  if (CALL_OBSERVERS.size === 0) return fetch(base, init);
-  const request = new Request(new URL(base, globalThis.location?.href || "http://localhost"), init);
+  const send = config.fetch || fetch;
+  if (CALL_OBSERVERS.size === 0) return send(base, init);
+  const request = new Request(new URL(base, globalThis.location?.href || "http://localhost"), {
+    ...init,
+    body: init.body instanceof ReadableStream ? undefined : init.body
+  });
   notifyCallObservers("request", id, instance, request, meta);
-  const response = await fetch(request);
+  const response = await send(base, init);
   notifyCallObservers("response", id, instance, response, meta);
   return response;
 }
@@ -562,6 +623,9 @@ async function fetchServerFunction(base, id, options, args, meta, callArgs = arg
     });
     if (handled !== undefined) return handled;
   }
+  if (response.status >= 400 && !response.headers.has(BODY_FORMAT_HEADER)) {
+    throw serverFunctionFailure(response, undefined);
+  }
   const failed = response.headers.has(ERROR_HEADER) || response.status >= 500;
   if (response.headers.has(SINGLE_FLIGHT_HEADER)) {
     const consumer = getFlightDataConsumer();
@@ -604,7 +668,7 @@ function createServerReference(id, name, base) {
   const metadata = name === undefined ? {} : {
     name
   };
-  const fn = (...args) => {
+  const run = (args, invokeOptions) => {
     const handler = config.responseHandler;
     if (handler && handler.intercept) {
       const hit = handler.intercept({
@@ -614,14 +678,18 @@ function createServerReference(id, name, base) {
       });
       if (hit !== undefined) return hit;
     }
-    return fetchServerFunction(base || config.endpoint, id, {}, args, metadata);
+    return fetchServerFunction(base || serverFunctionAddress(config.endpoint, id), id, invokeOptions ? {
+      ...invokeOptions
+    } : {}, args, metadata);
   };
+  const fn = (...args) => run(args);
   fn[SERVER_FUNCTION_METADATA] = metadata;
+  fn[SERVER_FUNCTION_INVOKE] = run;
   return new Proxy(fn, {
     get(target, prop) {
       if (prop === "id") return id;
       if (prop === "url") {
-        return base || `${config.endpoint}?id=${encodeURIComponent(id)}`;
+        return base || serverFunctionAddress(config.endpoint, id);
       }
       return target[prop];
     }
@@ -636,7 +704,7 @@ function GET(fn) {
   const metadata = {
     ...getServerFunctionMetadata(fn)
   };
-  const wrapped = async (...args) => {
+  const run = async (args, invokeOptions) => {
     const handler = config.responseHandler;
     if (handler && handler.intercept) {
       const hit = handler.intercept({
@@ -646,19 +714,34 @@ function GET(fn) {
       });
       if (hit !== undefined) return hit;
     }
-    let base = `${config.endpoint}?id=${encodeURIComponent(id)}`;
-    if (args.length) {
-      const encoded = isJSONSafe(args) ? JSON.stringify(args) : await serializeArguments(args);
-      base += `&args=${encodeURIComponent(encoded)}`;
+    const opts = invokeOptions || {};
+    const address = serverFunctionAddress(config.endpoint, id);
+    if (!args.length) {
+      return fetchServerFunction(address, id, {
+        ...opts,
+        method: "GET"
+      }, [], metadata, args);
+    }
+    const encoded = isJSONSafe(args) ? JSON.stringify(args) : await serializeArguments(args);
+    const url = `${address}?args=${encodeURIComponent(encoded)}`;
+    const absolute = new URL(url, globalThis.location?.href || "http://localhost").href;
+    if (absolute.length > MAX_GET_URL_LENGTH) {
+      return fetchServerFunction(address, id, {
+        ...opts,
+        read: true
+      }, args, metadata);
     }
-    return fetchServerFunction(base, id, {
+    return fetchServerFunction(url, id, {
+      ...opts,
       method: "GET"
     }, [], metadata, args);
   };
+  const wrapped = (...args) => run(args);
   wrapped[SERVER_FUNCTION_METADATA] = metadata;
+  wrapped[SERVER_FUNCTION_INVOKE] = run;
   wrapped.id = id;
   Object.defineProperty(wrapped, "url", {
-    get: () => `${config.endpoint}?id=${encodeURIComponent(id)}`,
+    get: () => serverFunctionAddress(config.endpoint, id),
     configurable: true
   });
   return withMeta(wrapped, {
@@ -674,7 +757,7 @@ function live(fn) {
     ...getServerFunctionMetadata(fn),
     live: true
   };
-  const wrapped = (...args) => {
+  const makeIterable = (args, invokeOptions) => {
     const iterable = {
       [LIVE_SOURCE]: true,
       [Symbol.asyncIterator]() {
@@ -688,6 +771,12 @@ function live(fn) {
           done: true,
           value: undefined
         };
+        const invokeSignal = invokeOptions && invokeOptions.signal;
+        const controller = new AbortController();
+        const wireOptions = {
+          ...invokeOptions,
+          signal: invokeSignal ? AbortSignal.any([invokeSignal, controller.signal]) : controller.signal
+        };
         const emit = (state, error) => {
           try {
             iterable.onstatus && iterable.onstatus(state, error);
@@ -709,7 +798,7 @@ function live(fn) {
           }
         };
         const callOnce = () => {
-          if (metadata.method === "GET") return fn(...args);
+          if (metadata.method === "GET") return fn[SERVER_FUNCTION_INVOKE](args, wireOptions);
           const handler = config.responseHandler;
           if (handler && handler.intercept) {
             const hit = handler.intercept({
@@ -720,6 +809,7 @@ function live(fn) {
             if (hit !== undefined) return hit;
           }
           return fetchServerFunction(fn.url, id, {
+            ...wireOptions,
             read: true
           }, args, metadata, args);
         };
@@ -734,6 +824,7 @@ function live(fn) {
                 }();
                 if (stopped) {
                   closeIt();
+                  controller.abort();
                   return DONE;
                 }
                 emit("connected");
@@ -747,7 +838,13 @@ function live(fn) {
               attempts = 0;
               return r;
             } catch (error) {
+              if (stopped) return DONE;
               if (!connected) throw error;
+              if (invokeSignal && invokeSignal.aborted) {
+                stopped = true;
+                emitClosed(error);
+                throw error;
+              }
               if (error !== null && typeof error === "object" && typeof error.status === "number" && error.status >= 400 && error.status < 500) {
                 stopped = true;
                 emitClosed(error);
@@ -761,9 +858,13 @@ function live(fn) {
                 if (typeof addEventListener === "function") addEventListener("online", resolve, {
                   once: true
                 });
+                if (invokeSignal) invokeSignal.addEventListener("abort", resolve, {
+                  once: true
+                });
               });
               clearTimeout(timer);
               if (typeof removeEventListener === "function") removeEventListener("online", wake);
+              if (invokeSignal) invokeSignal.removeEventListener("abort", wake);
               timer = wake = undefined;
             }
           }
@@ -776,6 +877,7 @@ function live(fn) {
             if (timer !== undefined) clearTimeout(timer);
             if (wake) wake();
             closeIt(value);
+            controller.abort();
             emitClosed();
             return Promise.resolve({
               done: true,
@@ -787,7 +889,9 @@ function live(fn) {
     };
     return iterable;
   };
+  const wrapped = (...args) => makeIterable(args);
   wrapped[SERVER_FUNCTION_METADATA] = metadata;
+  wrapped[SERVER_FUNCTION_INVOKE] = makeIterable;
   wrapped.id = id;
   Object.defineProperty(wrapped, "url", {
     get: () => fn.url,
@@ -805,10 +909,10 @@ function getServerFunctionInvocation() {
 exports.ChunkReader = ChunkReader;
 exports.ERROR_HEADER = ERROR_HEADER;
 exports.FLASH_COOKIE = FLASH_COOKIE;
-exports.FUNCTION_HEADER = FUNCTION_HEADER;
 exports.GET = GET;
 exports.INSTANCE_HEADER = INSTANCE_HEADER;
 exports.REVALIDATE_HEADER = REVALIDATE_HEADER;
+exports.SERVER_FUNCTION_INVOKE = SERVER_FUNCTION_INVOKE;
 exports.SINGLE_FLIGHT_HEADER = SINGLE_FLIGHT_HEADER;
 exports.clearFlashCookie = clearFlashCookie;
 exports.configureServerFunctionsClient = configureServerFunctionsClient;
@@ -825,10 +929,13 @@ exports.getServerFunctionInvocation = getServerFunctionInvocation;
 exports.getServerFunctionMetadata = getServerFunctionMetadata;
 exports.getServerFunctionsCodec = getServerFunctionsCodec;
 exports.hasFlashCookie = hasFlashCookie;
+exports.invoke = invoke;
 exports.isServerFunction = isServerFunction;
 exports.live = live;
 exports.observeServerFunctionCalls = observeServerFunctionCalls;
+exports.parseServerFunctionUrl = parseServerFunctionUrl;
 exports.registerServerReference = registerServerReference;
 exports.serializeString = serializeString;
+exports.serverFunctionUrl = serverFunctionUrl;
 exports.subscribeFlightData = subscribeFlightData;
 exports.withMeta = withMeta;