swarpc 0.15.0 → 0.16.0

package/src/types.ts

@@ -1,300 +0,0 @@
-/**
- * @module
- * @mergeModuleWith <project>
- */
-
-import type {
-  StandardSchemaV1 as Schema,
-  StandardSchemaV1,
-} from "./standardschema.js";
-import { ArkErrors, type } from "arktype";
-import { RequestBoundLogger } from "./log.js";
-
-/**
- * A procedure declaration
- */
-export type Procedure<I extends Schema, P extends Schema, S extends Schema> = {
-  /**
-   * 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 Schema,
-  P extends Schema,
-  S extends Schema,
-> = (
-  /**
-   * Input data for the procedure
-   */
-  input: Schema.InferInput<I>,
-  /**
-   * Callback to call with progress updates.
-   */
-  onProgress: (progress: Schema.InferInput<P>) => 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<Schema.InferInput<S>>;
-
-/**
- * Declarations of procedures by name.
- *
- * An example of declaring procedures:
- * {@includeCode ../example/src/lib/procedures.ts}
- */
-export type ProceduresMap = Record<string, Procedure<Schema, Schema, Schema>>;
-
-/**
- * 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: Schema.InferOutput<Procedures[Procedure]["success"]>,
-  ) => 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: Schema.InferOutput<Procedures[Procedure]["progress"]>,
-  ) => 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: Schema.InferOutput<PM[Name]["input"]>;
-    }
-  | {
-      progress: Schema.InferOutput<PM[Name]["progress"]>;
-    }
-  | {
-      result: Schema.InferOutput<PM[Name]["success"]>;
-    }
-  | {
-      abort: { reason: string };
-    }
-  | {
-      error: { message: string };
-    };
-
-const AbortOrError = type.or(
-  { abort: { reason: "string" } },
-  { error: { message: "string" } },
-);
-
-/**
- * @source
- */
-export function validatePayloadCore<
-  PM extends ProceduresMap,
-  Name extends keyof PM,
->(procedure: PM[Name], payload: unknown): PayloadCore<PM, keyof PM> {
-  if (typeof payload !== "object") throw new Error("payload is not an object");
-  if (payload === null) throw new Error("payload is null");
-
-  if ("input" in payload) {
-    const input = procedure.input["~standard"].validate(payload.input);
-    if ("value" in input) return { input: input.value };
-  }
-
-  if ("progress" in payload) {
-    const progress = procedure.progress["~standard"].validate(payload.progress);
-    if ("value" in progress) return { progress: progress.value };
-  }
-
-  if ("result" in payload) {
-    const result = procedure.success["~standard"].validate(payload.result);
-    if ("value" in result) return { result: result.value };
-  }
-
-  const abortOrError = AbortOrError(payload);
-  if (!(abortOrError instanceof ArkErrors)) {
-    return abortOrError;
-  }
-
-  throw new Error("invalid payload");
-}
-
-/**
- * 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<Schema, Schema, Schema>> = ((
-  input: Schema.InferInput<P["input"]>,
-  onProgress?: (progress: Schema.InferOutput<P["progress"]>) => void,
-) => Promise<Schema.InferOutput<P["success"]>>) & {
-  /**
-   * 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: Schema.InferInput<P["input"]>,
-    onProgress?: (progress: Schema.InferOutput<P["progress"]>) => void,
-    requestId?: string,
-  ) => CancelablePromise<Schema.InferOutput<P["success"]>>;
-  /**
-   * 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: Schema.InferInput<P["input"]>,
-    onProgress?: (
-      /** Map of node IDs to their progress updates */
-      progresses: Map<string, Schema.InferOutput<P["progress"]>>,
-    ) => void,
-    /** Number of nodes to send the request to. Leave undefined to send to all nodes */
-    nodes?: number,
-  ) => Promise<
-    Array<
-      PromiseSettledResult<Schema.InferOutput<P["success"]>> & { 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 +0,0 @@
-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 [];
-}