@solidjs/web 2.0.0-beta.18 → 2.0.0-beta.19

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@solidjs/web",
   "description": "Solid's web runtime: client rendering, hydration, SSR, and DOM-specific control flow (Portal, Dynamic).",
-  "version": "2.0.0-beta.18",
+  "version": "2.0.0-beta.19",
   "author": "Ryan Carniato",
   "license": "MIT",
   "homepage": "https://solidjs.com",
@@ -15,7 +15,8 @@
   },
   "main": "./dist/server.cjs",
   "module": "./dist/server.js",
-  "unpkg": "./dist/web.cjs",
+  "unpkg": "./dist/web.js",
+  "jsdelivr": "./dist/web.js",
   "types": "./types/index.d.ts",
   "type": "module",
   "sideEffects": false,
@@ -31,7 +32,9 @@
     "serialization/dist",
     "serialization/types",
     "serialization/types-cjs",
-    "serialization/package.json"
+    "serialization/package.json",
+    "server-functions/dist",
+    "server-functions/package.json"
   ],
   "exports": {
     ".": {
@@ -144,6 +147,76 @@
         "default": "./serialization/dist/serialization.cjs"
       }
     },
+    "./server-functions": {
+      "worker": {
+        "import": {
+          "types": "./types/server-functions/server.d.ts",
+          "default": "./server-functions/dist/server.js"
+        },
+        "require": {
+          "types": "./types-cjs/server-functions/server.d.cts",
+          "default": "./server-functions/dist/server.cjs"
+        }
+      },
+      "browser": {
+        "import": {
+          "types": "./types/server-functions/client.d.ts",
+          "default": "./server-functions/dist/client.js"
+        },
+        "require": {
+          "types": "./types-cjs/server-functions/client.d.cts",
+          "default": "./server-functions/dist/client.cjs"
+        }
+      },
+      "deno": {
+        "import": {
+          "types": "./types/server-functions/server.d.ts",
+          "default": "./server-functions/dist/server.js"
+        },
+        "require": {
+          "types": "./types-cjs/server-functions/server.d.cts",
+          "default": "./server-functions/dist/server.cjs"
+        }
+      },
+      "node": {
+        "import": {
+          "types": "./types/server-functions/server.d.ts",
+          "default": "./server-functions/dist/server.js"
+        },
+        "require": {
+          "types": "./types-cjs/server-functions/server.d.cts",
+          "default": "./server-functions/dist/server.cjs"
+        }
+      },
+      "import": {
+        "types": "./types/server-functions/client.d.ts",
+        "default": "./server-functions/dist/client.js"
+      },
+      "require": {
+        "types": "./types-cjs/server-functions/client.d.cts",
+        "default": "./server-functions/dist/client.cjs"
+      }
+    },
+    "./server-functions/server": {
+      "import": {
+        "types": "./types/server-functions/server.d.ts",
+        "default": "./server-functions/dist/server.js"
+      },
+      "require": {
+        "types": "./types-cjs/server-functions/server.d.cts",
+        "default": "./server-functions/dist/server.cjs"
+      }
+    },
+    "./server-functions/client": {
+      "import": {
+        "types": "./types/server-functions/client.d.ts",
+        "default": "./server-functions/dist/client.js"
+      },
+      "require": {
+        "types": "./types-cjs/server-functions/client.d.cts",
+        "default": "./server-functions/dist/client.cjs"
+      }
+    },
     "./types/*": "./types/*"
   },
   "dependencies": {
@@ -151,23 +224,24 @@
     "seroval-plugins": "~1.5.4"
   },
   "peerDependencies": {
-    "solid-js": "^2.0.0-beta.18"
+    "solid-js": "^2.0.0-beta.19"
   },
   "devDependencies": {
-    "solid-js": "2.0.0-beta.18"
+    "solid-js": "2.0.0-beta.19"
   },
   "scripts": {
     "build": "npm-run-all -nl build:clean types:copy-jsx build:js",
     "build:clean": "rimraf dist/",
     "build:js": "rollup -c",
     "link": "symlink-dir . node_modules/@solidjs/web",
-    "types": "npm-run-all -nl types:clean types:copy-jsx types:web types:copy-web types:web-storage types:copy-serialization types:cjs",
+    "types": "npm-run-all -nl types:clean types:copy-jsx types:web types:copy-web types:web-storage types:copy-serialization types:copy-server-functions types:cjs",
     "types:clean": "rimraf types/ types-cjs/ storage/types/ storage/types-cjs/ serialization/types/ serialization/types-cjs/",
     "types:copy-jsx": "ncp ../../node_modules/@dom-expressions/runtime/src/jsx.d.ts ./src/jsx.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/jsx-properties.d.ts ./src/jsx-properties.d.ts && dom-expressions-jsx-types --input ./src/jsx.d.ts --element \"SolidElement | Node | ArrayElement\" --import 'import type { Element as SolidElement } from \"solid-js\";'",
     "types:web": "tsc --project ./tsconfig.build.json",
-    "types:copy-web": "ncp ../../node_modules/@dom-expressions/runtime/src/client.d.ts ./types/client.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/server.d.ts ./types/server.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/serializer.d.ts ./types/serializer.d.ts && ncp ./src/jsx.d.ts ./types/jsx.d.ts && ncp ./src/jsx-properties.d.ts ./types/jsx-properties.d.ts",
+    "types:copy-web": "ncp ../../node_modules/@dom-expressions/runtime/src/client.d.ts ./types/client.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/server.d.ts ./types/server.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/serializer.d.ts ./types/serializer.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/response.d.ts ./types/response.d.ts && ncp ./src/jsx.d.ts ./types/jsx.d.ts && ncp ./src/jsx-properties.d.ts ./types/jsx-properties.d.ts",
     "types:web-storage": "tsc --project ./storage/tsconfig.build.json",
     "types:copy-serialization": "node -e \"fs.mkdirSync('./serialization/types', { recursive: true }); fs.copyFileSync('../../node_modules/@dom-expressions/runtime/src/serializer.d.ts', './serialization/types/index.d.ts');\"",
+    "types:copy-server-functions": "node -e \"fs.mkdirSync('./types/server-functions', { recursive: true }); for (const f of ['shared', 'client', 'server']) fs.copyFileSync('../../node_modules/@dom-expressions/runtime/src/server-functions/' + f + '.d.ts', './types/server-functions/' + f + '.d.ts');\"",
     "types:cjs": "node ../../scripts/sync-dual-types.mjs ./types ./types-cjs ./storage/types ./storage/types-cjs ./serialization/types ./serialization/types-cjs",
     "test": "vitest run && vitest run --config vite.config.server.mjs && vitest run --config vite.config.hydrate.mjs",
     "test:server": "vitest run --config vite.config.server.mjs",

package/serialization/types/index.d.ts

@@ -1,26 +1,39 @@
 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. */
+/**
+ * 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.
+ * 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
@@ -29,34 +42,59 @@ export interface WebSerializerOptions {
   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.
+ * 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"
 >;
 
 /**
- * Serializer for SSR hydration output. Pins the hydration global (`_$HY.r`)
- * and feature policy — only the wiring options (callbacks, scope, extra
- * plugins) are configurable.
+ * 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;
 
-/** Returns the cross-reference bootstrap script for a render scope. */
+/**
+ * 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[];
@@ -69,6 +107,7 @@ export interface JSONCodecOptions {
   depthLimit?: number;
 }
 
+/** Options for `serializeJSON`. */
 export interface JSONSerializeOptions extends JSONCodecOptions {
   /**
    * Receives each serialized node; `initial` is true for the first chunk
@@ -82,8 +121,10 @@ export interface JSONSerializeOptions extends JSONCodecOptions {
 }
 
 /**
- * Serializes `value` as SerovalNode chunks delivered through `onParse`.
- * Wire framing of the nodes is the transport's concern. Returns a cancel
+ * 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;
@@ -92,6 +133,7 @@ export function serializeJSON(value: unknown, options: JSONSerializeOptions): ()
  * 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.
+ * 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/index.d.cts

@@ -1,26 +1,39 @@
 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. */
+/**
+ * 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.
+ * 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
@@ -29,34 +42,59 @@ export interface WebSerializerOptions {
   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.
+ * 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"
 >;
 
 /**
- * Serializer for SSR hydration output. Pins the hydration global (`_$HY.r`)
- * and feature policy — only the wiring options (callbacks, scope, extra
- * plugins) are configurable.
+ * 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;
 
-/** Returns the cross-reference bootstrap script for a render scope. */
+/**
+ * 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[];
@@ -69,6 +107,7 @@ export interface JSONCodecOptions {
   depthLimit?: number;
 }
 
+/** Options for `serializeJSON`. */
 export interface JSONSerializeOptions extends JSONCodecOptions {
   /**
    * Receives each serialized node; `initial` is true for the first chunk
@@ -82,8 +121,10 @@ export interface JSONSerializeOptions extends JSONCodecOptions {
 }
 
 /**
- * Serializes `value` as SerovalNode chunks delivered through `onParse`.
- * Wire framing of the nodes is the transport's concern. Returns a cancel
+ * 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;
@@ -92,6 +133,7 @@ export function serializeJSON(value: unknown, options: JSONSerializeOptions): ()
  * 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.
+ * 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;