react-cheminfo 0.10.0 → 0.12.0

package/lib/worker/core/chunks.d.ts

@@ -0,0 +1,58 @@
+/** How {@link runInChunks} shares the thread. */
+export interface RunInChunksOptions {
+    /**
+     * Milliseconds of work between two turns handed back to the browser. The
+     * default leaves most of a 60 Hz frame for drawing and input.
+     * @default 12
+     */
+    sliceMs?: number;
+    /**
+     * Items worked through between two looks at the clock. Raise it when one
+     * item takes microseconds; with `sliceMs: 0` it is a fixed count of items
+     * between two turns.
+     * @default 1
+     */
+    chunkSize?: number;
+    /**
+     * How many items there are, for the progress of an iterable that cannot say.
+     * An estimate is fine: a count past it raises it.
+     * @default the length of an array, otherwise the count done so far
+     */
+    total?: number;
+    /**
+     * Called at every turn handed back, and once at the end with the exact count.
+     * @default undefined
+     */
+    onProgress?: (done: number, total: number) => void;
+    /**
+     * Stops the run before the next item; the promise then rejects with the
+     * signal's reason.
+     * @default undefined
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Work through a long list on this thread without freezing the page: the work
+ * runs in slices, and the browser gets a turn — to paint the progress, to
+ * handle a click on Cancel — between two of them.
+ *
+ * Meant for items that each cost real work: a molecule parsed, a row enriched,
+ * a record converted. Numeric inner loops belong in a plain `for` loop.
+ * @param items - The items, an array or any iterable, including an async one such as a streamed file.
+ * @param work - Called with each item and its index; may return a promise, which is awaited.
+ * @param options - See {@link RunInChunksOptions}.
+ * @returns How many items were worked through.
+ */
+export declare function runInChunks<TItem>(items: Iterable<TItem> | AsyncIterable<TItem>, work: (item: TItem, index: number) => unknown, options?: RunInChunksOptions): Promise<number>;
+/**
+ * Give the browser a turn in the middle of long work: it can paint, and read
+ * the click or the message that cancels the work.
+ *
+ * A macrotask rather than a resolved promise, because the browser paints and a
+ * worker reads its messages between tasks, never between microtasks; and
+ * `setTimeout` rather than `requestAnimationFrame`, which a background tab
+ * stops calling and a worker or a test does not have.
+ * @returns When the browser has had its turn.
+ */
+export declare function yieldToBrowser(): Promise<void>;
+//# sourceMappingURL=chunks.d.ts.map

package/lib/worker/core/chunks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../../src/worker/core/chunks.ts"],"names":[],"mappings":"AAKA,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAAC,KAAK,EACrC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,EAC7C,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,EAC7C,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,MAAM,CAAC,CAsDjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAI9C"}

package/lib/worker/core/chunks.js

@@ -0,0 +1,77 @@
+import { clamp } from "../../format/core/clamp.js";
+const DEFAULT_SLICE_MS = 12;
+const DEFAULT_CHUNK_SIZE = 1;
+/**
+ * Work through a long list on this thread without freezing the page: the work
+ * runs in slices, and the browser gets a turn — to paint the progress, to
+ * handle a click on Cancel — between two of them.
+ *
+ * Meant for items that each cost real work: a molecule parsed, a row enriched,
+ * a record converted. Numeric inner loops belong in a plain `for` loop.
+ * @param items - The items, an array or any iterable, including an async one such as a streamed file.
+ * @param work - Called with each item and its index; may return a promise, which is awaited.
+ * @param options - See {@link RunInChunksOptions}.
+ * @returns How many items were worked through.
+ */
+export async function runInChunks(items, work, options = {}) {
+    const { sliceMs = DEFAULT_SLICE_MS, chunkSize = DEFAULT_CHUNK_SIZE, total, onProgress, signal, } = options;
+    const slice = clamp(sliceMs, 0, Number.MAX_SAFE_INTEGER, DEFAULT_SLICE_MS);
+    const every = Math.trunc(clamp(chunkSize, 1, Number.MAX_SAFE_INTEGER, DEFAULT_CHUNK_SIZE));
+    const known = total ?? (Array.isArray(items) ? items.length : 0);
+    signal?.throwIfAborted();
+    let done = 0;
+    let sliceStart = performance.now();
+    function isDue() {
+        return done % every === 0 && performance.now() - sliceStart >= slice;
+    }
+    async function settle(result) {
+        if (result instanceof Promise)
+            await result;
+        signal?.throwIfAborted();
+        if (!isDue())
+            return;
+        onProgress?.(done, Math.max(known, done));
+        await yieldToBrowser();
+        signal?.throwIfAborted();
+        sliceStart = performance.now();
+    }
+    if (Symbol.iterator in items) {
+        // A plain loop, so a synchronous item costs no promise of its own.
+        for (const item of items) {
+            const result = work(item, done);
+            done += 1;
+            if (result instanceof Promise || isDue()) {
+                // eslint-disable-next-line no-await-in-loop -- items run in order, and the thread is handed back between slices
+                await settle(result);
+            }
+            else {
+                signal?.throwIfAborted();
+            }
+        }
+    }
+    else {
+        for await (const item of items) {
+            const result = work(item, done);
+            done += 1;
+            await settle(result);
+        }
+    }
+    onProgress?.(done, done);
+    return done;
+}
+/**
+ * Give the browser a turn in the middle of long work: it can paint, and read
+ * the click or the message that cancels the work.
+ *
+ * A macrotask rather than a resolved promise, because the browser paints and a
+ * worker reads its messages between tasks, never between microtasks; and
+ * `setTimeout` rather than `requestAnimationFrame`, which a background tab
+ * stops calling and a worker or a test does not have.
+ * @returns When the browser has had its turn.
+ */
+export function yieldToBrowser() {
+    return new Promise((resolve) => {
+        setTimeout(resolve, 0);
+    });
+}
+//# sourceMappingURL=chunks.js.map

package/lib/worker/core/chunks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunks.js","sourceRoot":"","sources":["../../../src/worker/core/chunks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAEnD,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAoC7B;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAA6C,EAC7C,IAA6C,EAC7C,UAA8B,EAAE;IAEhC,MAAM,EACJ,OAAO,GAAG,gBAAgB,EAC1B,SAAS,GAAG,kBAAkB,EAC9B,KAAK,EACL,UAAU,EACV,MAAM,GACP,GAAG,OAAO,CAAC;IACZ,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC;IAC3E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CACtB,KAAK,CAAC,SAAS,EAAE,CAAC,EAAE,MAAM,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CACjE,CAAC;IACF,MAAM,KAAK,GAAG,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEjE,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAEnC,SAAS,KAAK;QACZ,OAAO,IAAI,GAAG,KAAK,KAAK,CAAC,IAAI,WAAW,CAAC,GAAG,EAAE,GAAG,UAAU,IAAI,KAAK,CAAC;IACvE,CAAC;IAED,KAAK,UAAU,MAAM,CAAC,MAAe;QACnC,IAAI,MAAM,YAAY,OAAO;YAAE,MAAM,MAAM,CAAC;QAC5C,MAAM,EAAE,cAAc,EAAE,CAAC;QACzB,IAAI,CAAC,KAAK,EAAE;YAAE,OAAO;QACrB,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1C,MAAM,cAAc,EAAE,CAAC;QACvB,MAAM,EAAE,cAAc,EAAE,CAAC;QACzB,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IACjC,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC7B,mEAAmE;QACnE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAChC,IAAI,IAAI,CAAC,CAAC;YACV,IAAI,MAAM,YAAY,OAAO,IAAI,KAAK,EAAE,EAAE,CAAC;gBACzC,gHAAgH;gBAChH,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACN,MAAM,EAAE,cAAc,EAAE,CAAC;YAC3B,CAAC;QACH,CAAC;IACH,CAAC;SAAM,CAAC;QACN,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAChC,IAAI,IAAI,CAAC,CAAC;YACV,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/lib/worker/core/index.d.ts

@@ -1,5 +1,9 @@
+export type { RunInChunksOptions } from './chunks.ts';
+export { runInChunks, yieldToBrowser } from './chunks.ts';
 export { CancelledRequestError, RequestTimeoutError } from './errors.ts';
-export type { WorkerLike } from './messages.ts';
-export type { WorkerChannel, WorkerChannelOptions, WorkerRequestOptions, } from './workerChannel.ts';
+export type { WorkerCancelMessage, WorkerEventLike, WorkerLike, WorkerProgressMessage, WorkerRequestMessage, WorkerResponseMessage, } from './messages.ts';
+export type { ServeWorkerRequestsOptions, WorkerScopeLike, } from './serveWorkerRequests.ts';
+export { serveWorkerRequests } from './serveWorkerRequests.ts';
 export { createWorkerChannel } from './workerChannel.ts';
+export type { WorkerChannel, WorkerChannelOptions, WorkerJobContext, WorkerRequestOptions, WorkerSchedule, WorkerSource, } from './workerChannelTypes.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/worker/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/worker/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/worker/core/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,UAAU,EACV,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,0BAA0B,EAC1B,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,YAAY,GACb,MAAM,yBAAyB,CAAC"}

package/lib/worker/core/index.js

@@ -1,3 +1,5 @@
+export { runInChunks, yieldToBrowser } from "./chunks.js";
 export { CancelledRequestError, RequestTimeoutError } from "./errors.js";
+export { serveWorkerRequests } from "./serveWorkerRequests.js";
 export { createWorkerChannel } from "./workerChannel.js";
 //# sourceMappingURL=index.js.map

package/lib/worker/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/worker/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAOzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/worker/core/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAazE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

package/lib/worker/core/messages.d.ts

@@ -6,8 +6,26 @@ export interface WorkerRequestMessage<TRequest> {
     request: TRequest;
 }
 /**
- * What a worker posts back. An `Error` does not survive the boundary, so a
- * failure travels as its message and becomes an `Error` again on this side.
+ * What a channel created with `cooperativeCancel` posts when nobody waits for
+ * a job any more, so a worker that checks can stop early.
+ */
+export interface WorkerCancelMessage {
+    /** Serial number of the request to stop. */
+    id: number;
+    /** Always `true`: this message asks for a stop. */
+    cancel: true;
+}
+/** What a worker posts while a job runs, as often as it has news. */
+export interface WorkerProgressMessage<TProgress> {
+    /** Serial number of the request the news is about. */
+    id: number;
+    /** How far the job is, in whatever shape the two sides agreed on. */
+    progress: TProgress;
+}
+/**
+ * What a worker posts once a job is over. An `Error` does not survive the
+ * boundary, so a failure travels as its message and becomes an `Error` again
+ * on this side.
  */
 export type WorkerResponseMessage<TResponse> = {
     id: number;
@@ -24,8 +42,8 @@ export type WorkerResponseMessage<TResponse> = {
  * scheduling be unit-tested without a thread.
  */
 export interface WorkerLike {
-    /** Send one message to the worker. */
-    postMessage(message: unknown): void;
+    /** Send one message to the worker, handing over the listed buffers. */
+    postMessage(message: unknown, transfer?: Transferable[]): void;
     /** Listen to what the worker answers, or to its failing outright. */
     addEventListener(type: 'message' | 'error', listener: (event: WorkerEventLike) => void): void;
     /** Stop the worker; whatever it was doing is lost. */
@@ -45,4 +63,28 @@ export interface WorkerEventLike {
      */
     readonly message?: string;
 }
+/**
+ * Whether a message is the answer that ends a job.
+ * @param message - Whatever was posted.
+ * @returns Whether it carries an identifier and a well-formed outcome.
+ */
+export declare function isResponseMessage(message: unknown): message is WorkerResponseMessage<unknown>;
+/**
+ * Whether a message is news about a running job.
+ * @param message - Whatever was posted.
+ * @returns Whether it carries an identifier and a progress, and no outcome.
+ */
+export declare function isProgressMessage(message: unknown): message is WorkerProgressMessage<unknown>;
+/**
+ * Whether a message asks a worker for a job.
+ * @param message - Whatever was posted.
+ * @returns Whether it carries an identifier and a request.
+ */
+export declare function isRequestMessage(message: unknown): message is WorkerRequestMessage<unknown>;
+/**
+ * Whether a message asks a worker to stop a job.
+ * @param message - Whatever was posted.
+ * @returns Whether it carries an identifier and `cancel: true`.
+ */
+export declare function isCancelMessage(message: unknown): message is WorkerCancelMessage;
 //# sourceMappingURL=messages.d.ts.map

package/lib/worker/core/messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../../src/worker/core/messages.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB,CAAC,QAAQ;IAC5C,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,OAAO,EAAE,QAAQ,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,CAAC,SAAS,IACvC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,qEAAqE;IACrE,gBAAgB,CACd,IAAI,EAAE,SAAS,GAAG,OAAO,EACzB,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GACzC,IAAI,CAAC;IACR,sDAAsD;IACtD,SAAS,IAAI,IAAI,CAAC;CACnB;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B"}
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../../src/worker/core/messages.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB,CAAC,QAAQ;IAC5C,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,OAAO,EAAE,QAAQ,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,MAAM,EAAE,IAAI,CAAC;CACd;AAED,qEAAqE;AACrE,MAAM,WAAW,qBAAqB,CAAC,SAAS;IAC9C,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,CAAC,SAAS,IACvC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAC/D,qEAAqE;IACrE,gBAAgB,CACd,IAAI,EAAE,SAAS,GAAG,OAAO,EACzB,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GACzC,IAAI,CAAC;IACR,sDAAsD;IACtD,SAAS,IAAI,IAAI,CAAC;CACnB;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,OAAO,GACf,OAAO,IAAI,qBAAqB,CAAC,OAAO,CAAC,CAK3C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,OAAO,GACf,OAAO,IAAI,qBAAqB,CAAC,OAAO,CAAC,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,GACf,OAAO,IAAI,oBAAoB,CAAC,OAAO,CAAC,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,GACf,OAAO,IAAI,mBAAmB,CAEhC"}

package/lib/worker/core/messages.js

@@ -1,2 +1,43 @@
-export {};
+/**
+ * Whether a message is the answer that ends a job.
+ * @param message - Whatever was posted.
+ * @returns Whether it carries an identifier and a well-formed outcome.
+ */
+export function isResponseMessage(message) {
+    if (!hasId(message))
+        return false;
+    const candidate = message;
+    if (typeof candidate.ok !== 'boolean')
+        return false;
+    return candidate.ok || typeof candidate.message === 'string';
+}
+/**
+ * Whether a message is news about a running job.
+ * @param message - Whatever was posted.
+ * @returns Whether it carries an identifier and a progress, and no outcome.
+ */
+export function isProgressMessage(message) {
+    return hasId(message) && 'progress' in message && !('ok' in message);
+}
+/**
+ * Whether a message asks a worker for a job.
+ * @param message - Whatever was posted.
+ * @returns Whether it carries an identifier and a request.
+ */
+export function isRequestMessage(message) {
+    return hasId(message) && 'request' in message;
+}
+/**
+ * Whether a message asks a worker to stop a job.
+ * @param message - Whatever was posted.
+ * @returns Whether it carries an identifier and `cancel: true`.
+ */
+export function isCancelMessage(message) {
+    return hasId(message) && message.cancel === true;
+}
+function hasId(message) {
+    return (typeof message === 'object' &&
+        message !== null &&
+        typeof message.id === 'number');
+}
 //# sourceMappingURL=messages.js.map

package/lib/worker/core/messages.js.map

@@ -1 +1 @@
-{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../src/worker/core/messages.ts"],"names":[],"mappings":""}
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../src/worker/core/messages.ts"],"names":[],"mappings":"AAoEA;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAgB;IAEhB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAClC,MAAM,SAAS,GAAG,OAA8C,CAAC;IACjE,IAAI,OAAO,SAAS,CAAC,EAAE,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACpD,OAAO,SAAS,CAAC,EAAE,IAAI,OAAO,SAAS,CAAC,OAAO,KAAK,QAAQ,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAgB;IAEhB,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,UAAU,IAAI,OAAO,IAAI,CAAC,CAAC,IAAI,IAAI,OAAO,CAAC,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAgB;IAEhB,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,SAAS,IAAI,OAAO,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAgB;IAEhB,OAAO,KAAK,CAAC,OAAO,CAAC,IAAK,OAAgC,CAAC,MAAM,KAAK,IAAI,CAAC;AAC7E,CAAC;AAED,SAAS,KAAK,CAAC,OAAgB;IAC7B,OAAO,CACL,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,OAAQ,OAA4B,CAAC,EAAE,KAAK,QAAQ,CACrD,CAAC;AACJ,CAAC"}

package/lib/worker/core/serveWorkerRequests.d.ts

@@ -0,0 +1,45 @@
+import type { WorkerJobContext } from './workerChannelTypes.ts';
+/** As much of a dedicated worker's global scope as {@link serveWorkerRequests} uses. */
+export interface WorkerScopeLike {
+    /** Listen to what the page posts. */
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    /** Answer the page, handing over the listed buffers. */
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+}
+/** Where {@link serveWorkerRequests} listens, and what it hands over. */
+export interface ServeWorkerRequestsOptions<TRequest, TResponse> {
+    /**
+     * The scope to serve.
+     * @default the global scope, when the code runs in a dedicated worker
+     */
+    scope?: WorkerScopeLike;
+    /**
+     * Checks that a request has the shape the handler expects; one that does not
+     * is answered with a failure and never reaches the handler.
+     * @default undefined — every request is handed over as it came
+     */
+    accepts?: (request: unknown) => request is TRequest;
+    /**
+     * The buffers of an answer to hand over rather than copy, e.g. the grid of
+     * a sampled orbital.
+     * @default undefined — every answer is copied
+     */
+    transfer?: (response: TResponse) => Transferable[];
+}
+/**
+ * The worker's half of `createWorkerChannel`: answer every request the page
+ * posts with what the handler returns.
+ *
+ * The handler receives a signal that is aborted when the page sends the cancel
+ * message of a `cooperativeCancel` channel, and a `reportProgress` that posts
+ * news the caller's `onProgress` receives. A failure travels back as its
+ * message. Called in a module that the page also imports for its in-process
+ * fallback, it attaches nothing there, because that scope is not a worker's.
+ * @param handler - Runs one job; may be async.
+ * @param options - See {@link ServeWorkerRequestsOptions}.
+ * @returns Whether a scope was found and is now served.
+ */
+export declare function serveWorkerRequests<TRequest, TResponse, TProgress = never>(handler: (request: TRequest, context: WorkerJobContext<TProgress>) => TResponse | Promise<TResponse>, options?: ServeWorkerRequestsOptions<TRequest, TResponse>): boolean;
+//# sourceMappingURL=serveWorkerRequests.d.ts.map

package/lib/worker/core/serveWorkerRequests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serveWorkerRequests.d.ts","sourceRoot":"","sources":["../../../src/worker/core/serveWorkerRequests.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,gBAAgB,CACd,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAC3C,IAAI,CAAC;IACR,wDAAwD;IACxD,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;CAChE;AAED,yEAAyE;AACzE,MAAM,WAAW,0BAA0B,CAAC,QAAQ,EAAE,SAAS;IAC7D;;;OAGG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,IAAI,QAAQ,CAAC;IACpD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,YAAY,EAAE,CAAC;CACpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,KAAK,EACxE,OAAO,EAAE,CACP,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,gBAAgB,CAAC,SAAS,CAAC,KACjC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,EACnC,OAAO,GAAE,0BAA0B,CAAC,QAAQ,EAAE,SAAS,CAAM,GAC5D,OAAO,CAiDT"}

package/lib/worker/core/serveWorkerRequests.js

@@ -0,0 +1,88 @@
+import { errorMessage } from "../../error/core/toError.js";
+import { isCancelMessage, isRequestMessage } from "./messages.js";
+/**
+ * The worker's half of `createWorkerChannel`: answer every request the page
+ * posts with what the handler returns.
+ *
+ * The handler receives a signal that is aborted when the page sends the cancel
+ * message of a `cooperativeCancel` channel, and a `reportProgress` that posts
+ * news the caller's `onProgress` receives. A failure travels back as its
+ * message. Called in a module that the page also imports for its in-process
+ * fallback, it attaches nothing there, because that scope is not a worker's.
+ * @param handler - Runs one job; may be async.
+ * @param options - See {@link ServeWorkerRequestsOptions}.
+ * @returns Whether a scope was found and is now served.
+ */
+export function serveWorkerRequests(handler, options = {}) {
+    const { accepts, transfer } = options;
+    const scope = options.scope ?? dedicatedWorkerScope();
+    if (scope === undefined)
+        return false;
+    const running = new Map();
+    scope.addEventListener('message', (event) => {
+        const message = event.data;
+        if (isCancelMessage(message)) {
+            running.get(message.id)?.abort();
+            return;
+        }
+        if (!isRequestMessage(message))
+            return;
+        const { id, request } = message;
+        if (accepts !== undefined && !accepts(request)) {
+            answer(scope, {
+                id,
+                ok: false,
+                message: 'not a request this worker handles',
+            });
+            return;
+        }
+        const controller = new AbortController();
+        running.set(id, controller);
+        const context = {
+            signal: controller.signal,
+            reportProgress: (progress) => {
+                if (controller.signal.aborted)
+                    return;
+                const news = { id, progress };
+                scope.postMessage(news);
+            },
+        };
+        void Promise.resolve()
+            .then(() => handler(request, context))
+            .then((response) => {
+            answer(scope, { id, ok: true, response }, transfer);
+        }, (error) => {
+            answer(scope, { id, ok: false, message: errorMessage(error) });
+        })
+            .finally(() => {
+            running.delete(id);
+        });
+    });
+    return true;
+}
+function answer(scope, message, transfer) {
+    try {
+        if (transfer === undefined || !message.ok)
+            scope.postMessage(message);
+        else
+            scope.postMessage(message, transfer(message.response));
+    }
+    catch (error) {
+        // An answer that cannot be listed or cloned still has to end the job on the page.
+        scope.postMessage({
+            id: message.id,
+            ok: false,
+            message: errorMessage(error),
+        });
+    }
+}
+function dedicatedWorkerScope() {
+    const candidate = globalThis;
+    if (typeof candidate.postMessage !== 'function' ||
+        typeof candidate.addEventListener !== 'function' ||
+        candidate.window !== undefined) {
+        return undefined;
+    }
+    return globalThis;
+}
+//# sourceMappingURL=serveWorkerRequests.js.map

package/lib/worker/core/serveWorkerRequests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serveWorkerRequests.js","sourceRoot":"","sources":["../../../src/worker/core/serveWorkerRequests.ts"],"names":[],"mappings":"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"}

package/lib/worker/core/workerChannel.d.ts

@@ -1,69 +1,20 @@
-import type { WorkerLike } from './messages.ts';
+import type { WorkerChannel, WorkerChannelOptions, WorkerSource } from './workerChannelTypes.ts';
 /**
  * Turn a worker into something a page can await.
  *
- * Several requests may be in flight at once; each one is tagged with an
- * identifier the answer echoes, so replies are matched to callers whatever
- * order they arrive in. A request that rejects — cancelled, timed out, or
- * failed — drops out of the pending map at that moment, so a page that fires
- * one job per keystroke never accumulates them.
+ * Every request is tagged with an identifier the answer echoes, so replies are
+ * matched to callers whatever order they arrive in, and a request that rejects
+ * — cancelled, superseded, timed out, or failed — drops out of the pending map
+ * at that moment. The worker may post progress about a job while it runs.
  *
- * The worker is the caller's: the channel posts to it and terminates it when
- * asked, but never creates one, which is what lets a site keep its own lazy
- * construction and its own in-process fallback.
- * @param worker - The worker to talk to, or anything that speaks its three calls.
+ * Handed a worker, the channel posts to it and terminates it when asked, but
+ * never creates one. Handed a function, it creates the worker on the first
+ * request, replaces one that failed or was terminated, and can fall back to an
+ * in-process run where there is no `Worker`.
+ * @param source - The worker, or the function that creates it.
  * @param options - See {@link WorkerChannelOptions}.
  * @returns The channel.
+ * @throws {Error} When the `restart` schedule is asked of a single worker, which cannot be restarted.
  */
-export declare function createWorkerChannel<TRequest, TResponse>(worker: WorkerLike, options?: WorkerChannelOptions): WorkerChannel<TRequest, TResponse>;
-/** How a channel names itself and how long it waits. */
-export interface WorkerChannelOptions {
-    /**
-     * What the channel is called in the message of an error it raises, e.g.
-     * `conformers`.
-     * @default 'worker'
-     */
-    name?: string;
-    /**
-     * Milliseconds a request waits before it is given up on, when the call passes
-     * no budget of its own. A value that is not a positive finite number falls
-     * back to two minutes.
-     * @default 120000
-     */
-    defaultTimeoutMs?: number;
-}
-/** What one call may ask of the channel. */
-export interface WorkerRequestOptions {
-    /**
-     * Abort the call. Its promise then rejects with a
-     * {@link CancelledRequestError}; the worker itself is left alone, since a job
-     * already running cannot be interrupted from outside.
-     * @default undefined
-     */
-    signal?: AbortSignal;
-    /**
-     * Milliseconds this call alone waits, overriding the channel default —
-     * a calculation budget is often a user preference. A value that is not a
-     * positive finite number falls back to the channel default.
-     * @default the channel's defaultTimeoutMs
-     */
-    timeoutMs?: number;
-}
-/** A channel to one worker, over which several jobs may be in flight. */
-export interface WorkerChannel<TRequest, TResponse> {
-    /**
-     * Post one job and wait for the answer that carries its identifier.
-     * @param payload - The job.
-     * @param options - Per-call signal and budget.
-     * @returns What the worker answered.
-     */
-    request: (payload: TRequest, options?: WorkerRequestOptions) => Promise<TResponse>;
-    /** How many requests are still waiting for an answer. */
-    readonly pendingCount: number;
-    /**
-     * Terminate the worker, rejecting everything still waiting with a
-     * {@link CancelledRequestError}. The channel accepts no further request.
-     */
-    terminate: () => void;
-}
+export declare function createWorkerChannel<TRequest, TResponse, TProgress = never>(source: WorkerSource, options?: WorkerChannelOptions<TRequest, TResponse, TProgress>): WorkerChannel<TRequest, TResponse, TProgress>;
 //# sourceMappingURL=workerChannel.d.ts.map

package/lib/worker/core/workerChannel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workerChannel.d.ts","sourceRoot":"","sources":["../../../src/worker/core/workerChannel.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,UAAU,EAGX,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,EACrD,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,oBAAyB,GACjC,aAAa,CAAC,QAAQ,EAAE,SAAS,CAAC,CA0GpC;AAED,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa,CAAC,QAAQ,EAAE,SAAS;IAChD;;;;;OAKG;IACH,OAAO,EAAE,CACP,OAAO,EAAE,QAAQ,EACjB,OAAO,CAAC,EAAE,oBAAoB,KAC3B,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB"}
+{"version":3,"file":"workerChannel.d.ts","sourceRoot":"","sources":["../../../src/worker/core/workerChannel.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EAEpB,YAAY,EACb,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,KAAK,EACxE,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,oBAAoB,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAM,GACjE,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,CA6M/C"}