@solidjs/web 2.0.0-beta.2 → 2.0.0-beta.21

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

@@ -0,0 +1,139 @@
+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).
+   */
+  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.
+   */
+  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;

package/serialization/types-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/server-functions/dist/client.cjs

@@ -0,0 +1,448 @@
+'use strict';
+
+var seroval = require('seroval');
+var web = require('seroval-plugins/web');
+
+seroval.Feature.AggregateError | seroval.Feature.BigIntTypedArray;
+const DEFAULT_WEB_PLUGINS = Object.freeze([web.AbortSignalPlugin,
+web.CustomEventPlugin, web.DOMExceptionPlugin, web.EventPlugin,
+web.FormDataPlugin, web.HeadersPlugin, web.ReadableStreamPlugin, web.RequestPlugin, web.ResponsePlugin, web.URLSearchParamsPlugin, web.URLPlugin]);
+function resolveSerializerPlugins(customPlugins) {
+  return customPlugins ? [...customPlugins, ...DEFAULT_WEB_PLUGINS] : [...DEFAULT_WEB_PLUGINS];
+}
+const JSON_CODEC_DISABLED_FEATURES = seroval.Feature.RegExp;
+const JSON_CODEC_DEPTH_LIMIT = 64;
+function resolveCodecOptions({
+  plugins,
+  disabledFeatures,
+  depthLimit
+} = {}) {
+  return {
+    plugins: resolveSerializerPlugins(plugins),
+    disabledFeatures: disabledFeatures === undefined ? JSON_CODEC_DISABLED_FEATURES : disabledFeatures,
+    depthLimit: depthLimit === undefined ? JSON_CODEC_DEPTH_LIMIT : depthLimit
+  };
+}
+function serializeJSON(value, {
+  onParse,
+  onDone,
+  onError,
+  ...codecOptions
+}) {
+  return seroval.toCrossJSONStream(value, {
+    onParse,
+    onDone,
+    onError,
+    ...resolveCodecOptions(codecOptions)
+  });
+}
+function createJSONDeserializer(options) {
+  const refs = new Map();
+  const resolved = resolveCodecOptions(options);
+  return function deserializeJSONChunk(node) {
+    return seroval.fromCrossJSON(node, {
+      refs,
+      ...resolved
+    });
+  };
+}
+
+const codecConfig = {
+  codec: undefined
+};
+function configureServerFunctionsCodec(codec) {
+  codecConfig.codec = codec;
+}
+function getServerFunctionsCodec() {
+  return codecConfig.codec;
+}
+const flightConfig = {
+  consumer: undefined
+};
+function subscribeFlightData(consumer) {
+  flightConfig.consumer = consumer;
+  return () => {
+    if (flightConfig.consumer === consumer) flightConfig.consumer = undefined;
+  };
+}
+function getFlightDataConsumer() {
+  return flightConfig.consumer;
+}
+const SERVER_FUNCTION_METADATA = Symbol.for("solid.ServerFunctionMetadata");
+function getServerFunctionMetadata(fn) {
+  if (typeof fn !== "function") return undefined;
+  return fn[SERVER_FUNCTION_METADATA] || undefined;
+}
+function isServerFunction(fn) {
+  return typeof fn === "function" && !!fn[SERVER_FUNCTION_METADATA];
+}
+function withMeta(fn, meta) {
+  const metadata = getServerFunctionMetadata(fn);
+  if (!metadata) {
+    throw new Error("withMeta expects a server function reference");
+  }
+  Object.assign(metadata, meta);
+  return fn;
+}
+const FUNCTION_HEADER = "X-Server-Function-Id";
+const INSTANCE_HEADER = "X-Server-Function-Instance";
+const BODY_FORMAT_HEADER = "X-Server-Function-Format";
+const SINGLE_FLIGHT_HEADER = "X-Single-Flight";
+const FILE_FORM_KEY = "__server_function_file__";
+const BodyFormat = {
+  Serialized: "0",
+  String: "1",
+  FormData: "2",
+  URLSearchParams: "3",
+  Blob: "4",
+  File: "5",
+  ArrayBuffer: "6",
+  Uint8Array: "7"
+};
+function getHeadersAndBody(body) {
+  switch (true) {
+    case typeof body === "string":
+      return {
+        headers: {
+          "Content-Type": "text/plain",
+          [BODY_FORMAT_HEADER]: BodyFormat.String
+        },
+        body
+      };
+    case body instanceof FormData:
+      return {
+        headers: {
+          [BODY_FORMAT_HEADER]: BodyFormat.FormData
+        },
+        body
+      };
+    case body instanceof URLSearchParams:
+      return {
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          [BODY_FORMAT_HEADER]: BodyFormat.URLSearchParams
+        },
+        body
+      };
+    case typeof File !== "undefined" && body instanceof File:
+      {
+        const formData = new FormData();
+        formData.append(FILE_FORM_KEY, body, body.name);
+        return {
+          headers: {
+            [BODY_FORMAT_HEADER]: BodyFormat.File
+          },
+          body: formData
+        };
+      }
+    case body instanceof Blob:
+      return {
+        headers: {
+          [BODY_FORMAT_HEADER]: BodyFormat.Blob
+        },
+        body
+      };
+    case body instanceof ArrayBuffer:
+      return {
+        headers: {
+          [BODY_FORMAT_HEADER]: BodyFormat.ArrayBuffer
+        },
+        body
+      };
+    case body instanceof Uint8Array:
+      return {
+        headers: {
+          [BODY_FORMAT_HEADER]: BodyFormat.Uint8Array
+        },
+        body: new Uint8Array(body)
+      };
+    default:
+      return undefined;
+  }
+}
+async function extractBody(source, codecOptions) {
+  const contentType = source.headers.get("content-type");
+  const format = source.headers.get(BODY_FORMAT_HEADER);
+  const clone = source.clone();
+  switch (true) {
+    case format === BodyFormat.Serialized:
+      return await deserializeStream(clone, codecOptions);
+    case format === BodyFormat.String:
+      return await clone.text();
+    case format === BodyFormat.File:
+      {
+        const formData = await clone.formData();
+        return formData.get(FILE_FORM_KEY);
+      }
+    case format === BodyFormat.FormData:
+    case contentType && contentType.startsWith("multipart/form-data"):
+      return await clone.formData();
+    case format === BodyFormat.URLSearchParams:
+    case contentType && contentType.startsWith("application/x-www-form-urlencoded"):
+      return new URLSearchParams(await clone.text());
+    case format === BodyFormat.Blob:
+      return await clone.blob();
+    case format === BodyFormat.ArrayBuffer:
+      return await clone.arrayBuffer();
+    case format === BodyFormat.Uint8Array:
+      return new Uint8Array(await clone.arrayBuffer());
+  }
+  return undefined;
+}
+function createChunk(data) {
+  const encodeData = new TextEncoder().encode(data);
+  const bytes = encodeData.length;
+  const baseHex = bytes.toString(16);
+  const totalHex = "00000000".substring(0, 8 - baseHex.length) + baseHex;
+  const head = new TextEncoder().encode(`;0x${totalHex};`);
+  const chunk = new Uint8Array(12 + bytes);
+  chunk.set(head);
+  chunk.set(encodeData, 12);
+  return chunk;
+}
+class ChunkReader {
+  constructor(stream) {
+    this.reader = stream.getReader();
+    this.buffer = new Uint8Array(0);
+    this.done = false;
+  }
+  async readChunk() {
+    const chunk = await this.reader.read();
+    if (!chunk.done) {
+      const newBuffer = new Uint8Array(this.buffer.length + chunk.value.length);
+      newBuffer.set(this.buffer);
+      newBuffer.set(chunk.value, this.buffer.length);
+      this.buffer = newBuffer;
+    } else {
+      this.done = true;
+    }
+  }
+  async next() {
+    if (this.buffer.length === 0) {
+      if (this.done) {
+        return {
+          done: true,
+          value: undefined
+        };
+      }
+      await this.readChunk();
+      return await this.next();
+    }
+    const head = new TextDecoder().decode(this.buffer.subarray(1, 11));
+    const bytes = Number.parseInt(head, 16);
+    if (Number.isNaN(bytes)) {
+      throw new Error("Malformed server function stream.");
+    }
+    while (bytes > this.buffer.length - 12) {
+      if (this.done) {
+        throw new Error("Malformed server function stream.");
+      }
+      await this.readChunk();
+    }
+    const partial = new TextDecoder().decode(this.buffer.subarray(12, 12 + bytes));
+    this.buffer = this.buffer.subarray(12 + bytes);
+    return {
+      done: false,
+      value: partial
+    };
+  }
+  async drain(interpret) {
+    while (true) {
+      const result = await this.next();
+      if (result.done) {
+        break;
+      }
+      interpret(result.value);
+    }
+  }
+}
+function serializeStream(value, codecOptions) {
+  return new ReadableStream({
+    start(controller) {
+      serializeJSON(value, {
+        ...codecOptions,
+        onParse(node) {
+          controller.enqueue(createChunk(JSON.stringify(node)));
+        },
+        onDone() {
+          controller.close();
+        },
+        onError(error) {
+          controller.error(error);
+        }
+      });
+    }
+  });
+}
+async function serializeString(value, codecOptions) {
+  const response = new Response(serializeStream(value, codecOptions));
+  return await response.text();
+}
+async function deserializeStream(source, codecOptions) {
+  if (!source.body) {
+    throw new Error("missing body");
+  }
+  const reader = new ChunkReader(source.body);
+  const result = await reader.next();
+  if (!result.done) {
+    const deserializeChunk = createJSONDeserializer(codecOptions);
+    function interpretChunk(chunk) {
+      return deserializeChunk(JSON.parse(chunk));
+    }
+    void reader.drain(interpretChunk);
+    return interpretChunk(result.value);
+  }
+  return undefined;
+}
+async function decodeResponse(response, codecOptions) {
+  if (!response.body) return undefined;
+  return await extractBody(response, codecOptions === undefined ? codecConfig.codec : codecOptions);
+}
+
+const config = {
+  endpoint: "/_server",
+  prepareRequest: undefined
+};
+function configureServerFunctionsClient({
+  endpoint,
+  codec,
+  prepareRequest
+} = {}) {
+  if (endpoint !== undefined) config.endpoint = endpoint;
+  if (codec !== undefined) configureServerFunctionsCodec(codec);
+  if (prepareRequest !== undefined) config.prepareRequest = prepareRequest;
+}
+let INSTANCE = 0;
+async function createRequest(base, id, instance, options, meta) {
+  const headers = {
+    ...options.headers,
+    [FUNCTION_HEADER]: id,
+    [INSTANCE_HEADER]: instance
+  };
+  if (getFlightDataConsumer() && (!options.method || options.method.toUpperCase() !== "GET")) {
+    headers[SINGLE_FLIGHT_HEADER] = "true";
+  }
+  let init = {
+    method: "POST",
+    ...options,
+    headers
+  };
+  if (config.prepareRequest) {
+    init = (await config.prepareRequest(init, {
+      id,
+      meta
+    })) || init;
+  }
+  return fetch(base, init);
+}
+async function initializeResponse(base, id, instance, options, args, meta) {
+  if (args.length === 0) {
+    return createRequest(base, id, instance, options, meta);
+  }
+  if (args.length === 1) {
+    const result = getHeadersAndBody(args[0]);
+    if (result) {
+      return createRequest(base, id, instance, {
+        ...options,
+        body: result.body,
+        headers: {
+          ...options.headers,
+          ...result.headers
+        }
+      }, meta);
+    }
+  }
+  return createRequest(base, id, instance, {
+    ...options,
+    body: await serializeString(args, getServerFunctionsCodec()),
+    headers: {
+      ...options.headers,
+      "Content-Type": "text/plain",
+      [BODY_FORMAT_HEADER]: BodyFormat.Serialized
+    }
+  }, meta);
+}
+async function fetchServerFunction(base, id, options, args, meta) {
+  const instance = `server-function:${INSTANCE++}`;
+  const response = await initializeResponse(base, id, instance, options, args, meta);
+  if (response.headers.has(SINGLE_FLIGHT_HEADER)) {
+    const consumer = getFlightDataConsumer();
+    if (consumer) {
+      const payload = await decodeResponse(response);
+      await consumer(payload.data, {
+        response
+      });
+      if (response.headers.has("X-Server-Function-Error") && !response.headers.has("Location") && !response.headers.has("X-Revalidate")) {
+        throw payload.value;
+      }
+      return payload.value;
+    }
+  }
+  if (response.headers.has("Location") || response.headers.has("X-Revalidate") || response.headers.has(SINGLE_FLIGHT_HEADER)) {
+    return response;
+  }
+  const result = await decodeResponse(response.clone());
+  if (response.headers.has("X-Server-Function-Error")) {
+    throw result;
+  }
+  return result;
+}
+function createServerReference(id, name) {
+  const metadata = name === undefined ? {} : {
+    name
+  };
+  const fn = (...args) => fetchServerFunction(config.endpoint, id, {}, args, metadata);
+  fn[SERVER_FUNCTION_METADATA] = metadata;
+  return new Proxy(fn, {
+    get(target, prop) {
+      if (prop === "id") return id;
+      if (prop === "url") {
+        return `${config.endpoint}?id=${encodeURIComponent(id)}`;
+      }
+      return target[prop];
+    }
+  });
+}
+function GET(fn) {
+  if (!isServerFunction(fn)) {
+    throw new Error("GET expects a server function reference");
+  }
+  const id = fn.id;
+  const metadata = {
+    ...getServerFunctionMetadata(fn)
+  };
+  const wrapped = async (...args) => {
+    let base = `${config.endpoint}?id=${encodeURIComponent(id)}`;
+    if (args.length) {
+      base += `&args=${encodeURIComponent(await serializeString(args, getServerFunctionsCodec()))}`;
+    }
+    return fetchServerFunction(base, id, {
+      method: "GET"
+    }, [], metadata);
+  };
+  wrapped[SERVER_FUNCTION_METADATA] = metadata;
+  wrapped.id = id;
+  Object.defineProperty(wrapped, "url", {
+    get: () => `${config.endpoint}?id=${encodeURIComponent(id)}`,
+    configurable: true
+  });
+  return withMeta(wrapped, {
+    method: "GET"
+  });
+}
+function registerServerReference() {
+  throw new Error("registerServerReference must not be called in the client build");
+}
+
+exports.FUNCTION_HEADER = FUNCTION_HEADER;
+exports.GET = GET;
+exports.INSTANCE_HEADER = INSTANCE_HEADER;
+exports.SINGLE_FLIGHT_HEADER = SINGLE_FLIGHT_HEADER;
+exports.configureServerFunctionsClient = configureServerFunctionsClient;
+exports.createServerReference = createServerReference;
+exports.decodeResponse = decodeResponse;
+exports.getServerFunctionMetadata = getServerFunctionMetadata;
+exports.isServerFunction = isServerFunction;
+exports.registerServerReference = registerServerReference;
+exports.subscribeFlightData = subscribeFlightData;
+exports.withMeta = withMeta;