swarpc 0.11.0 → 0.13.0

package/src/types.ts

@@ -1,239 +1,264 @@
-/**
- * @module
- * @mergeModuleWith <project>
- */
-
-import { type, type Type } from "arktype"
-import { RequestBoundLogger } from "./log.js"
-
-/**
- * A procedure declaration
- */
-export type Procedure<I extends Type, P extends Type, S extends Type> = {
-  /**
-   * ArkType type for the input (first argument) of the procedure, when calling it from the client.
-   */
-  input: I
-  /**
-   * ArkType type for the data as the first argument given to the `onProgress` callback
-   * when calling the procedure from the client.
-   */
-  progress: P
-  /**
-   * ArkType type for the output (return value) of the procedure, when calling it from the client.
-   */
-  success: S
-  /**
-   * When should the procedure automatically add ArrayBuffers and other transferable objects
-   * to the [transfer list](https://developer.mozilla.org/en-US/docs/Web/API/DedicatedWorkerGlobalScope/postMessage#transfer)
-   * when sending messages, both from the client to the server and vice versa.
-   *
-   * Transferring objects can improve performance by avoiding copies of large objects,
-   * but _moves_ them to the other context, meaning that they cannot be used in the original context after being sent.
-   *
-   * 'output-only' by default: only transferables sent from the server to the client will be transferred.
-   */
-  autotransfer?: "always" | "never" | "output-only"
-}
-
-/**
- * A promise that you can cancel by calling `.cancel(reason)` on it:
- *
- * ```js
- * const { request, cancel } = client.runProcedure.cancelable(input, onProgress)
- * setTimeout(() => cancel("Cancelled by user"), 1000)
- * const result = await request
- * ```
- */
-export type CancelablePromise<T = unknown> = {
-  request: Promise<T>
-  /**
-   * Abort the request.
-   * @param reason The reason for cancelling the request.
-   */
-  cancel: (reason: string) => void
-}
-
-/**
- * An implementation of a procedure
- */
-export type ProcedureImplementation<
-  I extends Type,
-  P extends Type,
-  S extends Type,
-> = (
-  /**
-   * Input data for the procedure
-   */
-  input: I["inferOut"],
-  /**
-   * Callback to call with progress updates.
-   */
-  onProgress: (progress: P["inferIn"]) => void,
-  /**
-   * Additional tools useful when implementing the procedure.
-   */
-  tools: {
-    /**
-     * AbortSignal that can be used to handle request cancellation -- see [Make cancellable requests](https://gwennlbh.github.io/swarpc/docs/#make-cancelable-requests)
-     */
-    abortSignal?: AbortSignal
-    /**
-     * Logger instance to use for logging messages related to this procedure call, using the same format as SWARPC's built-in logging.
-     */
-    logger: RequestBoundLogger
-  }
-) => Promise<S["inferIn"]>
-
-/**
- * Declarations of procedures by name.
- *
- * An example of declaring procedures:
- * {@includeCode ../example/src/lib/procedures.ts}
- */
-export type ProceduresMap = Record<string, Procedure<Type, Type, Type>>
-
-/**
- * Implementations of procedures by name
- */
-export type ImplementationsMap<Procedures extends ProceduresMap> = {
-  [F in keyof Procedures]: ProcedureImplementation<
-    Procedures[F]["input"],
-    Procedures[F]["progress"],
-    Procedures[F]["success"]
-  >
-}
-
-/**
- * Declaration of hooks to run on messages received from the server
- */
-export type Hooks<Procedures extends ProceduresMap> = {
-  /**
-   * Called when a procedure call has been successful.
-   */
-  success?: <Procedure extends keyof ProceduresMap>(
-    procedure: Procedure,
-    data: Procedures[Procedure]["success"]["inferOut"]
-  ) => void
-  /**
-   * Called when a procedure call has failed.
-   */
-  error?: <Procedure extends keyof ProceduresMap>(
-    procedure: Procedure,
-    error: Error
-  ) => void
-  /**
-   * Called when a procedure call sends progress updates.
-   */
-  progress?: <Procedure extends keyof ProceduresMap>(
-    procedure: Procedure,
-    data: Procedures[Procedure]["progress"]["inferOut"]
-  ) => void
-}
-
-export const PayloadInitializeSchema = type({
-  by: '"sw&rpc"',
-  functionName: '"#initialize"',
-  localStorageData: "Record<string, unknown>",
-})
-
-export type PayloadInitialize = typeof PayloadInitializeSchema.infer
-
-/**
- * @source
- */
-export const PayloadHeaderSchema = type("<Name extends string>", {
-  by: '"sw&rpc"',
-  functionName: "Name",
-  requestId: "string >= 1",
-})
-
-export type PayloadHeader<
-  PM extends ProceduresMap,
-  Name extends keyof PM = keyof PM,
-> = {
-  by: "sw&rpc"
-  functionName: Name & string
-  requestId: string
-}
-
-/**
- * @source
- */
-export const PayloadCoreSchema = type("<I, P, S>", {
-  "input?": "I",
-  "progress?": "P",
-  "result?": "S",
-  "abort?": { reason: "string" },
-  "error?": { message: "string" },
-})
-
-export type PayloadCore<
-  PM extends ProceduresMap,
-  Name extends keyof PM = keyof PM,
-> =
-  | {
-      input: PM[Name]["input"]["inferOut"]
-    }
-  | {
-      progress: PM[Name]["progress"]["inferOut"]
-    }
-  | {
-      result: PM[Name]["success"]["inferOut"]
-    }
-  | {
-      abort: { reason: string }
-    }
-  | {
-      error: { message: string }
-    }
-
-/**
- * @source
- */
-export const PayloadSchema = type
-  .scope({ PayloadCoreSchema, PayloadHeaderSchema, PayloadInitializeSchema })
-  .type("<Name extends string, I, P, S>", [
-    ["PayloadHeaderSchema<Name>", "&", "PayloadCoreSchema<I, P, S>"],
-    "|",
-    "PayloadInitializeSchema",
-  ])
-
-/**
- * The effective payload as sent by the server to the client
- */
-export type Payload<
-  PM extends ProceduresMap,
-  Name extends keyof PM = keyof PM,
-> = (PayloadHeader<PM, Name> & PayloadCore<PM, Name>) | PayloadInitialize
-
-/**
- * A procedure's corresponding method on the client instance -- used to call the procedure. If you want to be able to cancel the request, you can use the `cancelable` method instead of running the procedure directly.
- */
-export type ClientMethod<P extends Procedure<Type, Type, Type>> = ((
-  input: P["input"]["inferIn"],
-  onProgress?: (progress: P["progress"]["inferOut"]) => void
-) => Promise<P["success"]["inferOut"]>) & {
-  /**
-   * A method that returns a `CancelablePromise`. Cancel it by calling `.cancel(reason)` on it, and wait for the request to resolve by awaiting the `request` property on the returned object.
-   */
-  cancelable: (
-    input: P["input"]["inferIn"],
-    onProgress?: (progress: P["progress"]["inferOut"]) => void,
-    requestId?: string
-  ) => CancelablePromise<P["success"]["inferOut"]>
-}
-
-/**
- * Symbol used as the key for the procedures map on the server instance
- * @internal
- * @source
- */
-export const zImplementations = Symbol("SWARPC implementations")
-
-/**
- * Symbol used as the key for the procedures map on instances
- * @internal
- * @source
- */
-export const zProcedures = Symbol("SWARPC procedures")
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+
+import { type, type Type } from "arktype";
+import { RequestBoundLogger } from "./log.js";
+
+/**
+ * A procedure declaration
+ */
+export type Procedure<I extends Type, P extends Type, S extends Type> = {
+  /**
+   * ArkType type for the input (first argument) of the procedure, when calling it from the client.
+   */
+  input: I;
+  /**
+   * ArkType type for the data as the first argument given to the `onProgress` callback
+   * when calling the procedure from the client.
+   */
+  progress: P;
+  /**
+   * ArkType type for the output (return value) of the procedure, when calling it from the client.
+   */
+  success: S;
+  /**
+   * When should the procedure automatically add ArrayBuffers and other transferable objects
+   * to the [transfer list](https://developer.mozilla.org/en-US/docs/Web/API/DedicatedWorkerGlobalScope/postMessage#transfer)
+   * when sending messages, both from the client to the server and vice versa.
+   *
+   * Transferring objects can improve performance by avoiding copies of large objects,
+   * but _moves_ them to the other context, meaning that they cannot be used in the original context after being sent.
+   *
+   * 'output-only' by default: only transferables sent from the server to the client will be transferred.
+   */
+  autotransfer?: "always" | "never" | "output-only";
+};
+
+/**
+ * A promise that you can cancel by calling `.cancel(reason)` on it:
+ *
+ * ```js
+ * const { request, cancel } = client.runProcedure.cancelable(input, onProgress)
+ * setTimeout(() => cancel("Cancelled by user"), 1000)
+ * const result = await request
+ * ```
+ */
+export type CancelablePromise<T = unknown> = {
+  request: Promise<T>;
+  /**
+   * Abort the request.
+   * @param reason The reason for cancelling the request.
+   */
+  cancel: (reason: string) => void;
+};
+
+/**
+ * An implementation of a procedure
+ */
+export type ProcedureImplementation<
+  I extends Type,
+  P extends Type,
+  S extends Type,
+> = (
+  /**
+   * Input data for the procedure
+   */
+  input: I["inferOut"],
+  /**
+   * Callback to call with progress updates.
+   */
+  onProgress: (progress: P["inferIn"]) => void,
+  /**
+   * Additional tools useful when implementing the procedure.
+   */
+  tools: {
+    /**
+     * AbortSignal that can be used to handle request cancellation -- see [Make cancellable requests](https://gwennlbh.github.io/swarpc/docs/#make-cancelable-requests)
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * Logger instance to use for logging messages related to this procedure call, using the same format as SWARPC's built-in logging.
+     */
+    logger: RequestBoundLogger;
+    /**
+     * ID of the Node the request is being processed on.
+     */
+    nodeId: string;
+  },
+) => Promise<S["inferIn"]>;
+
+/**
+ * Declarations of procedures by name.
+ *
+ * An example of declaring procedures:
+ * {@includeCode ../example/src/lib/procedures.ts}
+ */
+export type ProceduresMap = Record<string, Procedure<Type, Type, Type>>;
+
+/**
+ * Implementations of procedures by name
+ */
+export type ImplementationsMap<Procedures extends ProceduresMap> = {
+  [F in keyof Procedures]: ProcedureImplementation<
+    Procedures[F]["input"],
+    Procedures[F]["progress"],
+    Procedures[F]["success"]
+  >;
+};
+
+/**
+ * Declaration of hooks to run on messages received from the server
+ */
+export type Hooks<Procedures extends ProceduresMap> = {
+  /**
+   * Called when a procedure call has been successful.
+   */
+  success?: <Procedure extends keyof ProceduresMap>(
+    procedure: Procedure,
+    data: Procedures[Procedure]["success"]["inferOut"],
+  ) => void;
+  /**
+   * Called when a procedure call has failed.
+   */
+  error?: <Procedure extends keyof ProceduresMap>(
+    procedure: Procedure,
+    error: Error,
+  ) => void;
+  /**
+   * Called when a procedure call sends progress updates.
+   */
+  progress?: <Procedure extends keyof ProceduresMap>(
+    procedure: Procedure,
+    data: Procedures[Procedure]["progress"]["inferOut"],
+  ) => void;
+};
+
+export const PayloadInitializeSchema = type({
+  by: '"sw&rpc"',
+  functionName: '"#initialize"',
+  isInitializeRequest: "true",
+  localStorageData: "Record<string, unknown>",
+  nodeId: "string",
+});
+
+export type PayloadInitialize = typeof PayloadInitializeSchema.infer;
+
+/**
+ * @source
+ */
+export const PayloadHeaderSchema = type("<Name extends string>", {
+  by: '"sw&rpc"',
+  functionName: "Name",
+  requestId: "string >= 1",
+});
+
+export type PayloadHeader<
+  PM extends ProceduresMap,
+  Name extends keyof PM = keyof PM,
+> = {
+  by: "sw&rpc";
+  functionName: Name & string;
+  requestId: string;
+};
+
+/**
+ * @source
+ */
+export const PayloadCoreSchema = type("<I, P, S>", {
+  "input?": "I",
+  "progress?": "P",
+  "result?": "S",
+  "abort?": { reason: "string" },
+  "error?": { message: "string" },
+});
+
+export type PayloadCore<
+  PM extends ProceduresMap,
+  Name extends keyof PM = keyof PM,
+> =
+  | {
+      input: PM[Name]["input"]["inferOut"];
+    }
+  | {
+      progress: PM[Name]["progress"]["inferOut"];
+    }
+  | {
+      result: PM[Name]["success"]["inferOut"];
+    }
+  | {
+      abort: { reason: string };
+    }
+  | {
+      error: { message: string };
+    };
+
+/**
+ * @source
+ */
+export const PayloadSchema = type
+  .scope({ PayloadCoreSchema, PayloadHeaderSchema, PayloadInitializeSchema })
+  .type("<Name extends string, I, P, S>", [
+    ["PayloadHeaderSchema<Name>", "&", "PayloadCoreSchema<I, P, S>"],
+    "|",
+    "PayloadInitializeSchema",
+  ]);
+
+/**
+ * The effective payload as sent by the server to the client
+ */
+export type Payload<
+  PM extends ProceduresMap,
+  Name extends keyof PM = keyof PM,
+> = (PayloadHeader<PM, Name> & PayloadCore<PM, Name>) | PayloadInitialize;
+
+/**
+ * A procedure's corresponding method on the client instance -- used to call the procedure. If you want to be able to cancel the request, you can use the `cancelable` method instead of running the procedure directly.
+ */
+export type ClientMethod<P extends Procedure<Type, Type, Type>> = ((
+  input: P["input"]["inferIn"],
+  onProgress?: (progress: P["progress"]["inferOut"]) => void,
+) => Promise<P["success"]["inferOut"]>) & {
+  /**
+   * A method that returns a `CancelablePromise`. Cancel it by calling `.cancel(reason)` on it, and wait for the request to resolve by awaiting the `request` property on the returned object.
+   */
+  cancelable: (
+    input: P["input"]["inferIn"],
+    onProgress?: (progress: P["progress"]["inferOut"]) => void,
+    requestId?: string,
+  ) => CancelablePromise<P["success"]["inferOut"]>;
+  /**
+   * Send the request to specific nodes, or all nodes.
+   * Returns an array of results, one for each node the request was sent to.
+   * Each result is a {@link PromiseSettledResult}, with also an additional property, the node ID of the request
+   */
+  broadcast: (
+    input: P["input"]["inferIn"],
+    onProgress?: (progress: P["progress"]["inferOut"]) => void,
+    /** Number of nodes to send the request to. Leave undefined to send to all nodes */
+    nodes?: number,
+  ) => Promise<
+    Array<PromiseSettledResult<P["success"]["inferOut"]> & { node: string }>
+  >;
+};
+
+/**
+ * Symbol used as the key for the procedures map on the server instance
+ * @internal
+ * @source
+ */
+export const zImplementations = Symbol("SWARPC implementations");
+
+/**
+ * Symbol used as the key for the procedures map on instances
+ * @internal
+ * @source
+ */
+export const zProcedures = Symbol("SWARPC procedures");
+
+export type WorkerConstructor<
+  T extends Worker | SharedWorker = Worker | SharedWorker,
+> = {
+  new (opts?: { name?: string }): T;
+};

package/src/utils.ts

@@ -1,34 +1,34 @@
-type Constructor<T> = new (...args: any[]) => T
-
-// TODO: keep it in sync with web standards, how?
-const transferableClasses: Constructor<Transferable>[] = [
-  MessagePort,
-  ReadableStream,
-  WritableStream,
-  TransformStream,
-  ArrayBuffer,
-]
-
-export function findTransferables(value: any): Transferable[] {
-  if (value === null || value === undefined) {
-    return []
-  }
-
-  if (typeof value === "object") {
-    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
-      return [value]
-    }
-
-    if (transferableClasses.some((cls) => value instanceof cls)) {
-      return [value as Transferable]
-    }
-
-    if (Array.isArray(value)) {
-      return value.flatMap(findTransferables)
-    }
-
-    return Object.values(value).flatMap(findTransferables)
-  }
-
-  return []
-}
+type Constructor<T> = new (...args: any[]) => T;
+
+// TODO: keep it in sync with web standards, how?
+const transferableClasses: Constructor<Transferable>[] = [
+  MessagePort,
+  ReadableStream,
+  WritableStream,
+  TransformStream,
+  ArrayBuffer,
+];
+
+export function findTransferables(value: any): Transferable[] {
+  if (value === null || value === undefined) {
+    return [];
+  }
+
+  if (typeof value === "object") {
+    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+      return [value];
+    }
+
+    if (transferableClasses.some((cls) => value instanceof cls)) {
+      return [value as Transferable];
+    }
+
+    if (Array.isArray(value)) {
+      return value.flatMap(findTransferables);
+    }
+
+    return Object.values(value).flatMap(findTransferables);
+  }
+
+  return [];
+}