@zingage/scheduling 1.1.0 → 1.2.0

package/dist/pending-promises-tracker.js

@@ -0,0 +1,60 @@
+/**
+ * Tracks promises until they settle, so that an owner's `close` can wait for
+ * the work it accepted.
+ *
+ * Each tracked promise leaves the tracker when it settles. Tracking never
+ * creates an unhandled rejection: the tracker observes a rejection, but the
+ * caller still owns the promise and its rejection.
+ *
+ * The tracker has no closed state. Each owner decides what new work does
+ * after its own `close` starts, and in what order it drains its trackers.
+ */
+export class PendingPromisesTracker {
+    #pending = new Set();
+    /** The number of tracked promises that have not settled yet. */
+    get size() {
+        return this.#pending.size;
+    }
+    /** Tracks `promise` until it settles, and returns it unchanged. */
+    // oxlint-disable-next-line typescript/promise-function-async -- Returns the same promise it tracks.
+    track(promise) {
+        this.#pending.add(promise);
+        const untrack = () => {
+            this.#pending.delete(promise);
+        };
+        // oxlint-disable-next-line no-void -- Untracks on settle; the caller owns the promise and its rejection.
+        void promise.then(untrack, untrack);
+        return promise;
+    }
+    /**
+     * Calls `start` and tracks its result. The promise is tracked before
+     * `start` runs, so a `drain` that `start` itself triggers synchronously
+     * still waits for it. A synchronous throw from `start` becomes a rejection.
+     */
+    // oxlint-disable-next-line typescript/promise-function-async -- Returns the tracked promise, and must call start synchronously.
+    run(start) {
+        const { promise, resolve, reject } = Promise.withResolvers();
+        // oxlint-disable-next-line no-void -- track returns the same promise, which run returns.
+        void this.track(promise);
+        try {
+            resolve(start());
+        }
+        catch (error) {
+            reject(error);
+        }
+        return promise;
+    }
+    /**
+     * Resolves once no tracked promise is pending, including promises tracked
+     * while it waits. It loops because settling work can start more work, for
+     * example a producer that reads other keys from its own wrapper. It never
+     * rejects.
+     */
+    async drain() {
+        // oxlint-disable-next-line zingage/no-restricted-syntax -- Loops until nothing is pending, because settling work can track more.
+        while (this.#pending.size > 0) {
+            await Promise.allSettled(this.#pending);
+        }
+    }
+}
+//# sourceMappingURL=pending-promises-tracker.js.map

package/dist/pending-promises-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-promises-tracker.js","sourceRoot":"","sources":["../src/pending-promises-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,sBAAsB;IACxB,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAEhD,gEAAgE;IAChE,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED,mEAAmE;IACnE,oGAAoG;IACpG,KAAK,CAAI,OAAmB;QAC1B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3B,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC,CAAC;QACF,yGAAyG;QACzG,KAAK,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACpC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,gIAAgI;IAChI,GAAG,CAAI,KAAuB;QAC5B,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,EAAK,CAAC;QAChE,yFAAyF;QACzF,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACzB,IAAI,CAAC;YACH,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK;QACT,iIAAiI;QACjI,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;CACF"}

package/dist/performance-now.d.ts

@@ -0,0 +1,14 @@
+import type { Tagged } from "type-fest";
+/**
+ * A reading of `performance.now()`, in milliseconds since the time origin.
+ *
+ * The tag keeps other numbers out of a parameter that expects a reading of
+ * this clock. Examples are a `Date.now()` time, which uses a different
+ * origin, and a duration.
+ */
+export type PerformanceNow = Tagged<number, "PerformanceNow">;
+/** Reads `performance.now()`. */
+export declare function performanceNow(): PerformanceNow;
+/** The milliseconds that passed between `start` and now. */
+export declare function msSince(start: PerformanceNow): number;
+//# sourceMappingURL=performance-now.d.ts.map

package/dist/performance-now.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance-now.d.ts","sourceRoot":"","sources":["../src/performance-now.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGxC;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE9D,iCAAiC;AACjC,wBAAgB,cAAc,IAAI,cAAc,CAE/C;AAED,4DAA4D;AAC5D,wBAAgB,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAErD"}

package/dist/performance-now.js

@@ -0,0 +1,10 @@
+import { instantiateTaggedType } from "type-party/runtime/tagged-types.js";
+/** Reads `performance.now()`. */
+export function performanceNow() {
+    return instantiateTaggedType(performance.now());
+}
+/** The milliseconds that passed between `start` and now. */
+export function msSince(start) {
+    return performance.now() - start;
+}
+//# sourceMappingURL=performance-now.js.map

package/dist/performance-now.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance-now.js","sourceRoot":"","sources":["../src/performance-now.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAW3E,iCAAiC;AACjC,MAAM,UAAU,cAAc;IAC5B,OAAO,qBAAqB,CAAiB,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;AAClE,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,OAAO,CAAC,KAAqB;IAC3C,OAAO,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;AACnC,CAAC"}

package/dist/scheduling-contract-error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reports that a caller broke a contract of this package. Examples are a
+ * `dispatch` or `schedule` callback that returns the wrong number of results,
+ * and a `schedule` callback that requests a key it is starting a task for.
+ */
+export declare class SchedulingContractError extends Error {
+    readonly name: string;
+}
+//# sourceMappingURL=scheduling-contract-error.d.ts.map

package/dist/scheduling-contract-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduling-contract-error.d.ts","sourceRoot":"","sources":["../src/scheduling-contract-error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,SAAkB,IAAI,EAAE,MAAM,CAA6B;CAC5D"}

package/dist/scheduling-contract-error.js

@@ -0,0 +1,9 @@
+/**
+ * Reports that a caller broke a contract of this package. Examples are a
+ * `dispatch` or `schedule` callback that returns the wrong number of results,
+ * and a `schedule` callback that requests a key it is starting a task for.
+ */
+export class SchedulingContractError extends Error {
+    name = "SchedulingContractError";
+}
+//# sourceMappingURL=scheduling-contract-error.js.map

package/dist/scheduling-contract-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduling-contract-error.js","sourceRoot":"","sources":["../src/scheduling-contract-error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAC9B,IAAI,GAAW,yBAAyB,CAAC;CAC5D"}

package/dist/wrap-with-task-collapsing.d.ts

@@ -0,0 +1,30 @@
+import { type Logger } from "./logger.js";
+/**
+ * Wraps a function that starts a task and returns a promise for its result.
+ * The returned function behaves like the original, except that a call reuses
+ * the promise of an earlier call if and only if: 1) the calls have the same
+ * key, which `makeKey` derives from their arguments [a la memoize]; 2) less
+ * than `collapseTasksMs` milliseconds have passed since the earlier call
+ * started its task [a la throttle]; and 3) that task is still running
+ * [unique]. Otherwise, the call calls through to the original function. So it
+ * is sort of a combination of memoize, throttle, and promise chaining.
+ *
+ * It runs on {@link CollapsedTaskCreator}: each call is one task request,
+ * whose input carries the call's arguments and key. See that class for why
+ * these semantics are useful.
+ *
+ * It does not support task cancellation. A call takes no `AbortSignal`, so no
+ * individual caller can cancel a task that other callers share. Users who
+ * need cancellation should use `CollapsedTaskCreator` directly.
+ *
+ * @param taskCreator The task creation function
+ * @param collapseTasksMs The number of milliseconds up until which, if a caller
+ *   tries to start the same task while a previous version of the task is still
+ *   running, the promise for the result of the currently-running task will be
+ *   returned instead.
+ * @param makeKey A function for converting the arguments passed to the task
+ *   creation into a cache key, like in your standard memoize implementation.
+ * @param logger Receives the trace lines that each call writes.
+ */
+export declare function wrapWithTaskCollapsing<Args extends unknown[], Key, Result>(taskCreator: (...args: Args) => Promise<Result>, collapseTasksMs: number, makeKey: (args: Args) => Key, logger?: Logger): (...args: Args) => Promise<Result>;
+//# sourceMappingURL=wrap-with-task-collapsing.d.ts.map

package/dist/wrap-with-task-collapsing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-with-task-collapsing.d.ts","sourceRoot":"","sources":["../src/wrap-with-task-collapsing.ts"],"names":[],"mappings":"AAIA,OAAO,EAA6B,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAuBrE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,GAAG,EAAE,MAAM,EACxE,WAAW,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,EAC/C,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,GAAG,EAC5B,MAAM,GAAE,MAA4D,aA2B7C,IAAI,qBAiB5B"}

package/dist/wrap-with-task-collapsing.js

@@ -0,0 +1,80 @@
+import { CollapsedTaskCreator, } from "./collapsed-task-creator.js";
+import { defaultLoggersByComponent } from "./logger.js";
+// The creator reserves `undefined` for inputs that never share work, but here
+// `undefined` is an ordinary key. So it stands in for `undefined` with a
+// key that no caller can produce.
+const undefinedKey = Symbol("undefined key");
+/**
+ * The "started" log line for each reason a call starts a task. A call here
+ * has no signal, so its task is never cancelled, and its key is never
+ * `undefined` for the creator. But every reason has a line, so the log stays
+ * accurate if that changes.
+ */
+const startedMessages = {
+    noPendingTask: "started new task b/c there was no in-progress task for these args",
+    pendingTaskTooOld: "started new task; there _was_ an in-progress one, but it's too old",
+    pendingTaskCancelled: "started new task; there _was_ an in-progress one, but it was cancelled",
+    noKey: "started new task b/c these args have no key",
+};
+/**
+ * Wraps a function that starts a task and returns a promise for its result.
+ * The returned function behaves like the original, except that a call reuses
+ * the promise of an earlier call if and only if: 1) the calls have the same
+ * key, which `makeKey` derives from their arguments [a la memoize]; 2) less
+ * than `collapseTasksMs` milliseconds have passed since the earlier call
+ * started its task [a la throttle]; and 3) that task is still running
+ * [unique]. Otherwise, the call calls through to the original function. So it
+ * is sort of a combination of memoize, throttle, and promise chaining.
+ *
+ * It runs on {@link CollapsedTaskCreator}: each call is one task request,
+ * whose input carries the call's arguments and key. See that class for why
+ * these semantics are useful.
+ *
+ * It does not support task cancellation. A call takes no `AbortSignal`, so no
+ * individual caller can cancel a task that other callers share. Users who
+ * need cancellation should use `CollapsedTaskCreator` directly.
+ *
+ * @param taskCreator The task creation function
+ * @param collapseTasksMs The number of milliseconds up until which, if a caller
+ *   tries to start the same task while a previous version of the task is still
+ *   running, the promise for the result of the currently-running task will be
+ *   returned instead.
+ * @param makeKey A function for converting the arguments passed to the task
+ *   creation into a cache key, like in your standard memoize implementation.
+ * @param logger Receives the trace lines that each call writes.
+ */
+export function wrapWithTaskCollapsing(taskCreator, collapseTasksMs, makeKey, logger = defaultLoggersByComponent["collapsed-task-creator"]) {
+    const logTrace = logger.bind(null, "collapsed-task-creator", "trace");
+    // The creator's input carries the key, so `makeKey` runs once per call and
+    // every log line below can include the key.
+    const creator = new CollapsedTaskCreator({
+        collapseTasksMs,
+        makeKey: ({ taskKey }) => taskKey === undefined ? undefinedKey : taskKey,
+        schedule: (toStart) => toStart.map(({ input: { args, taskKey }, startReason }) => {
+            logTrace(startedMessages[startReason], args);
+            const taskRes = taskCreator(...args);
+            logTrace("pending = new state for taskKey/args", { args, taskKey });
+            return {
+                result: taskRes.finally(() => {
+                    logTrace("completed = new state for taskKey/args", {
+                        args,
+                        taskKey,
+                    });
+                }),
+                handle: undefined,
+            };
+        }),
+    });
+    return async (...args) => {
+        const taskKey = makeKey(args);
+        logTrace("requested = new state for taskKey/args", { args, taskKey });
+        const [{ result, rode }] = creator.startOrRideTasks([
+            { input: { args, taskKey } },
+        ]);
+        if (rode) {
+            logTrace("reusing result from prior, still-in-progress run of task for args/taskKey", { args, taskKey });
+        }
+        return result;
+    };
+}
+//# sourceMappingURL=wrap-with-task-collapsing.js.map

package/dist/wrap-with-task-collapsing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-with-task-collapsing.js","sourceRoot":"","sources":["../src/wrap-with-task-collapsing.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,GAErB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,yBAAyB,EAAe,MAAM,aAAa,CAAC;AAErE,8EAA8E;AAC9E,yEAAyE;AACzE,kCAAkC;AAClC,MAAM,YAAY,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,eAAe,GAAoC;IACvD,aAAa,EACX,mEAAmE;IACrE,iBAAiB,EACf,oEAAoE;IACtE,oBAAoB,EAClB,wEAAwE;IAC1E,KAAK,EAAE,6CAA6C;CACrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,sBAAsB,CACpC,WAA+C,EAC/C,eAAuB,EACvB,OAA4B,EAC5B,MAAM,GAAW,yBAAyB,CAAC,wBAAwB,CAAC;IAEpE,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,wBAAwB,EAAE,OAAO,CAAC,CAAC;IAEtE,2EAA2E;IAC3E,4CAA4C;IAC5C,MAAM,OAAO,GAAG,IAAI,oBAAoB,CAAC;QACvC,eAAe;QACf,OAAO,EAAE,CAAC,EAAE,OAAO,EAAgC,EAAE,EAAE,CACrD,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO;QAChD,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CACpB,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE;YACxD,QAAQ,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC,CAAC;YAC7C,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC;YACrC,QAAQ,CAAC,sCAAsC,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YACpE,OAAO;gBACL,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE;oBAC3B,QAAQ,CAAC,wCAAwC,EAAE;wBACjD,IAAI;wBACJ,OAAO;qBACR,CAAC,CAAC;gBACL,CAAC,CAAC;gBACF,MAAM,EAAE,SAAS;aAClB,CAAC;QACJ,CAAC,CAAC;KACL,CAAC,CAAC;IAEH,OAAO,KAAK,EAAE,GAAG,IAAU,EAAE,EAAE;QAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC9B,QAAQ,CAAC,wCAAwC,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAEtE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAClD,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;SAC7B,CAAC,CAAC;QAEH,IAAI,IAAI,EAAE,CAAC;YACT,QAAQ,CACN,2EAA2E,EAC3E,EAAE,IAAI,EAAE,OAAO,EAAE,CAClB,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zingage/scheduling",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/joinava/sensitive-packages.git",
@@ -24,16 +24,22 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "dependencies": {},
+  "dependencies": {
+    "debug": "^4.4.1",
+    "es-toolkit": "1.47.1",
+    "type-fest": "5.8.0",
+    "type-party": "0.10.2"
+  },
   "devDependencies": {
+    "@types/debug": "^4.1.12",
     "@types/node": "^26.1.1",
     "fast-check": "^4.2.0",
     "oxlint": "^1.83.0",
     "oxlint-tsgolint": "^7.0.2001",
     "typescript": "npm:@typescript/typescript6@^6.0.0",
     "typescript-7": "npm:typescript@^7.0.2",
-    "@zingage/base-configs-oxlint": "1.0.0",
-    "@zingage/base-configs-ts": "1.0.0"
+    "@zingage/base-configs-ts": "1.0.0",
+    "@zingage/base-configs-oxlint": "1.0.0"
   },
   "scripts": {
     "tsc:watch": "tsc -b --watch",