@zingage/scheduling 1.1.0 → 1.2.0

package/src/index.ts

@@ -10,3 +10,25 @@ export {
 } from "./time-slicing.js";
 export { timeSlicedSort } from "./time-sliced-sort.js";
 export { timeSlicedFind, timeSlicedSome } from "./time-sliced-search.js";
+export {
+  CollapsedTaskCreator,
+  type ScheduleTasks,
+  type SharedTaskView,
+  type TaskRequestOutcome,
+  type TaskRequestOutcomes,
+  type TaskStartReason,
+} from "./collapsed-task-creator.js";
+export { wrapWithTaskCollapsing } from "./wrap-with-task-collapsing.js";
+export {
+  Batcher,
+  DEFAULT_MAX_BATCH_SIZE,
+  type BatchHandle,
+  type BatchItem,
+  type BatchOptions,
+  type DispatchedItem,
+  type DispatchInfo,
+  type Enqueued,
+} from "./batcher.js";
+export { PendingPromisesTracker } from "./pending-promises-tracker.js";
+export { SchedulingContractError } from "./scheduling-contract-error.js";
+export type { Logger, SchedulingComponentName } from "./logger.js";

package/src/logger.ts

@@ -0,0 +1,32 @@
+import { default as debug } from "debug";
+
+/** The components in this package that write log lines. */
+export type SchedulingComponentName = "batcher" | "collapsed-task-creator";
+
+/**
+ * The signature of a custom log function. `Batcher` and
+ * `wrapWithTaskCollapsing` accept one, and call it when they log a message.
+ *
+ * A logger that accepts more component names, such as a logger shared with
+ * other packages, is also a valid `Logger`.
+ */
+export type Logger = (
+  component: SchedulingComponentName,
+  level: "trace" | "debug" | "info" | "warn" | "error" | "fatal",
+  message: string,
+  data?: unknown,
+) => void;
+
+/** A logger that writes to the `debug` namespace `@zingage/scheduling:<name>`. */
+function debugLogger(name: SchedulingComponentName): Logger {
+  const write = debug(`@zingage/scheduling:${name}`);
+  return (_, level, message, data) => {
+    write(`(${level}) ${message} %O`, data);
+  };
+}
+
+/** The default logger of each component. */
+export const defaultLoggersByComponent = {
+  batcher: debugLogger("batcher"),
+  "collapsed-task-creator": debugLogger("collapsed-task-creator"),
+} satisfies Record<SchedulingComponentName, Logger>;

package/src/pending-promises-tracker.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 {
+  readonly #pending = new Set<Promise<unknown>>();
+
+  /** The number of tracked promises that have not settled yet. */
+  get size(): number {
+    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<T>(promise: Promise<T>): Promise<T> {
+    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<T>(start: () => Promise<T>): Promise<T> {
+    const { promise, resolve, reject } = Promise.withResolvers<T>();
+    // 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(): Promise<void> {
+    // 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);
+    }
+  }
+}

package/src/performance-now.ts

@@ -0,0 +1,21 @@
+import type { Tagged } from "type-fest";
+import { instantiateTaggedType } from "type-party/runtime/tagged-types.js";
+
+/**
+ * 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 function performanceNow(): PerformanceNow {
+  return instantiateTaggedType<PerformanceNow>(performance.now());
+}
+
+/** The milliseconds that passed between `start` and now. */
+export function msSince(start: PerformanceNow): number {
+  return performance.now() - start;
+}

package/src/scheduling-contract-error.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 {
+  override readonly name: string = "SchedulingContractError";
+}

package/src/wrap-with-task-collapsing.ts

@@ -0,0 +1,103 @@
+import {
+  CollapsedTaskCreator,
+  type TaskStartReason,
+} from "./collapsed-task-creator.js";
+import { defaultLoggersByComponent, type Logger } 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: Record<TaskStartReason, string> = {
+  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<Args extends unknown[], Key, Result>(
+  taskCreator: (...args: Args) => Promise<Result>,
+  collapseTasksMs: number,
+  makeKey: (args: Args) => Key,
+  logger: 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 }: { args: Args; taskKey: Key }) =>
+      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: 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;
+  };
+}