@zingage/scheduling 1.0.0 → 1.2.0

package/src/index.ts

@@ -9,3 +9,26 @@ export {
   TimeSliceBudget,
 } 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/synchronous-result.ts

@@ -0,0 +1,28 @@
+export const GENERATOR_HINT =
+  "For async work, use a generator callback with `yield* waitFor(...)`.";
+export const TRAVERSAL_HINT =
+  "For async work, use a generator callback with `yield* waitFor(...)` in timeSlicedMap or timeSlicedForEach first.";
+
+/**
+ * Returns `value` unchanged, or throws a `TypeError` if it is a thenable.
+ *
+ * TypeScript cannot reject a promise result without also rejecting generic
+ * results, so the synchronous callback rule is checked here at runtime.
+ */
+export function assertNotThenable<Value>(
+  value: Value,
+  helper: string,
+  hint: string,
+): Value {
+  if (
+    ((typeof value === "object" && value !== null) ||
+      typeof value === "function") &&
+    "then" in value &&
+    typeof value.then === "function"
+  ) {
+    throw new TypeError(
+      `${helper} received a promise or other thenable from a synchronous callback. ${hint}`,
+    );
+  }
+  return value;
+}

package/src/time-sliced-search.ts

@@ -0,0 +1,98 @@
+import { TRAVERSAL_HINT, assertNotThenable } from "./synchronous-result.js";
+import { TimeSliceBudget } from "./time-slicing.js";
+
+async function findFirstMatch<Item>(
+  helper: string,
+  items: Iterable<Item>,
+  predicate: (item: Item, index: number) => boolean,
+  budget: TimeSliceBudget,
+): Promise<{ item: Item } | undefined> {
+  const position = { index: 0 };
+  // oxlint-disable-next-line zingage/no-restricted-syntax -- Stop at the first match; native iteration closes the iterator without advancing it.
+  for (const item of items) {
+    const matched = budget.measure(() =>
+      assertNotThenable(
+        predicate(item, position.index),
+        helper,
+        TRAVERSAL_HINT,
+      ),
+    );
+    position.index += 1;
+    const pending = budget.yieldIfNeeded();
+    if (pending !== undefined) await pending;
+    if (matched) return { item };
+  }
+  return undefined;
+}
+
+/**
+ * Returns whether any item matches a synchronous predicate, in input order.
+ *
+ * Stops at the first match. It does not advance the iterable past that item,
+ * and it builds no intermediate array. Measures each predicate call, including
+ * calls that throw. One predicate call cannot be interrupted. Throws a
+ * `TypeError` if the predicate returns a promise or other thenable.
+ * The optional budget defaults to a new independent `TimeSliceBudget`.
+ *
+ * @example Check for a negative number.
+ * const hasNegative = await timeSlicedSome([3, -1, 2], (value) => value < 0);
+ *
+ * @example Share a budget with other work, and stop early on a lazy source.
+ * const budget = new TimeSliceBudget();
+ * const found = await timeSlicedSome(map.values(), (entry) => entry.active, budget);
+ */
+export async function timeSlicedSome<Item>(
+  items: Iterable<Item>,
+  predicate: (item: Item, index: number) => boolean,
+  budget = new TimeSliceBudget(),
+): Promise<boolean> {
+  return (
+    (await findFirstMatch("timeSlicedSome", items, predicate, budget)) !==
+    undefined
+  );
+}
+
+/**
+ * Returns the first item that matches a type-guard predicate, narrowed.
+ *
+ * @example Find the first string.
+ * const text = await timeSlicedFind(
+ *   [1, "a", 2],
+ *   (value): value is string => typeof value === "string",
+ * );
+ */
+export function timeSlicedFind<Item, Found extends Item>(
+  items: Iterable<Item>,
+  predicate: (item: Item, index: number) => item is Found,
+  budget?: TimeSliceBudget,
+): Promise<Found | undefined>;
+/**
+ * Returns the first item that matches a synchronous predicate, or `undefined`.
+ *
+ * Stops at the first match. It does not advance the iterable past that item,
+ * and it builds no intermediate array. Measures each predicate call, including
+ * calls that throw. One predicate call cannot be interrupted. Throws a
+ * `TypeError` if the predicate returns a promise or other thenable. As with
+ * `Array.prototype.find`, a matching `undefined` item also returns `undefined`.
+ * The optional budget defaults to a new independent `TimeSliceBudget`.
+ *
+ * @example Find the first even number.
+ * const even = await timeSlicedFind([1, 4, 6], (value) => value % 2 === 0);
+ *
+ * @example Use the index and a shared budget.
+ * const budget = new TimeSliceBudget();
+ * const late = await timeSlicedFind(["a", "b"], (_, index) => index > 0, budget);
+ */
+export function timeSlicedFind<Item>(
+  items: Iterable<Item>,
+  predicate: (item: Item, index: number) => boolean,
+  budget?: TimeSliceBudget,
+): Promise<Item | undefined>;
+export async function timeSlicedFind<Item>(
+  items: Iterable<Item>,
+  predicate: (item: Item, index: number) => boolean,
+  budget = new TimeSliceBudget(),
+): Promise<Item | undefined> {
+  return (await findFirstMatch("timeSlicedFind", items, predicate, budget))
+    ?.item;
+}

package/src/time-slicing.ts

@@ -1,11 +1,14 @@
 import assert from "node:assert/strict";
 import { setImmediate } from "node:timers/promises";
+import {
+  GENERATOR_HINT,
+  TRAVERSAL_HINT,
+  assertNotThenable,
+} from "./synchronous-result.js";
 
 const DEFAULT_TIME_SLICE_MS = 4;
 const performanceNow = performance.now.bind(performance);
 
-type Synchronous<Result> = Result extends PromiseLike<unknown> ? never : Result;
-
 /**
  * Tracks measured synchronous work before yielding to the event loop.
  *
@@ -55,6 +58,8 @@ export class TimeSliceBudget {
    *
    * Nested measurements on this budget count once. This method does not yield.
    * Call `yieldIfNeeded` at a safe boundary after handling the result.
+   * `work` must be synchronous. If it returns a promise or other thenable, this
+   * method throws a `TypeError` after charging the elapsed time.
    *
    * @example Measure one segment and then check the budget.
    * const budget = new TimeSliceBudget();
@@ -62,12 +67,16 @@ export class TimeSliceBudget {
    * const pending = budget.yieldIfNeeded();
    * if (pending !== undefined) await pending;
    */
-  measure<Result>(work: () => Result & Synchronous<Result>): Result {
+  measure<Result>(work: () => Result): Result {
     const outermost = this.#depth === 0;
     const startedAt = outermost ? this.#now() : 0;
     this.#depth += 1;
     try {
-      return work();
+      return assertNotThenable(
+        work(),
+        "TimeSliceBudget.measure",
+        GENERATOR_HINT,
+      );
     } finally {
       this.#depth -= 1;
       if (outermost) this.#remainingMs -= this.#now() - startedAt;
@@ -197,19 +206,17 @@ async function runCallbackGenerator<Result>(
 }
 
 async function traverse<Item, Result>(
+  helper: string,
   items: Iterable<Item>,
-  callback: (
-    item: Item,
-    index: number,
-  ) => (Result & Synchronous<Result>) | CallbackGenerator<Result>,
+  callback: (item: Item, index: number) => Result | CallbackGenerator<Result>,
   accept: (result: Result) => void,
   budget: TimeSliceBudget,
 ): Promise<void> {
   const position = { index: 0 };
   // oxlint-disable-next-line zingage/no-restricted-syntax -- Native iteration owns cleanup while callbacks and budget yields settle sequentially.
   for (const item of items) {
-    const value = budget.measure<Result | CallbackGenerator<Result>>(() =>
-      callback(item, position.index),
+    const value = budget.measure(() =>
+      assertNotThenable(callback(item, position.index), helper, GENERATOR_HINT),
     );
     const result = isCallbackGenerator<Result>(value)
       ? await runCallbackGenerator(value, budget)
@@ -228,6 +235,9 @@ async function traverse<Item, Result>(
  * finishes before the next item starts. Measures synchronous callback work and
  * every generator `next()`/`throw()` segment, excluding promise waits.
  * Iterator advancement is unmeasured. Unhandled failures stop the traversal.
+ * A non-generator callback must be synchronous. If it returns a promise or
+ * other thenable (an `async` function, for example), the traversal throws a
+ * `TypeError` on that first call. The type checker does not catch this.
  * The optional budget defaults to a new independent `TimeSliceBudget`.
  *
  * @example Run a synchronous visitor.
@@ -247,23 +257,22 @@ export function timeSlicedForEach<Item, Result>(
 /**
  * Runs a synchronous visitor in input order with an optional processing budget.
  *
+ * Throws a `TypeError` if the visitor returns a promise or other thenable.
+ *
  * @example
  * await timeSlicedForEach([1, 2], (value) => console.log(value));
  */
 export function timeSlicedForEach<Item, Result>(
   items: Iterable<Item>,
-  callback: (item: Item, index: number) => Result & Synchronous<Result>,
+  callback: (item: Item, index: number) => Result,
   budget?: TimeSliceBudget,
 ): Promise<void>;
 export async function timeSlicedForEach<Item, Result>(
   items: Iterable<Item>,
-  callback: (
-    item: Item,
-    index: number,
-  ) => (Result & Synchronous<Result>) | CallbackGenerator<Result>,
+  callback: (item: Item, index: number) => Result | CallbackGenerator<Result>,
   budget = new TimeSliceBudget(),
 ): Promise<void> {
-  await traverse(items, callback, () => {}, budget);
+  await traverse("timeSlicedForEach", items, callback, () => {}, budget);
 }
 
 /**
@@ -272,7 +281,9 @@ export async function timeSlicedForEach<Item, Result>(
  * Accepts synchronous callbacks or generators that yield promises. Each generator
  * finishes before the next item starts. Measures every synchronous segment,
  * including `throw()` recovery and result accumulation. Promise waits and iterator
- * advancement are unmeasured. Ordinary async callbacks are not supported.
+ * advancement are unmeasured. Ordinary async callbacks are not supported: if a
+ * non-generator callback returns a promise or other thenable, the traversal
+ * throws a `TypeError` on that first call. The type checker does not catch this.
  * The optional budget defaults to a new independent `TimeSliceBudget`.
  *
  * @example Transform synchronous values.
@@ -292,24 +303,24 @@ export function timeSlicedMap<Item, Result>(
 /**
  * Maps synchronous values in input order with an optional processing budget.
  *
+ * Throws a `TypeError` if the callback returns a promise or other thenable.
+ *
  * @example
  * const doubled = await timeSlicedMap([1, 2], (value) => value * 2);
  */
 export function timeSlicedMap<Item, Result>(
   items: Iterable<Item>,
-  callback: (item: Item, index: number) => Result & Synchronous<Result>,
+  callback: (item: Item, index: number) => Result,
   budget?: TimeSliceBudget,
 ): Promise<Result[]>;
 export async function timeSlicedMap<Item, Result>(
   items: Iterable<Item>,
-  callback: (
-    item: Item,
-    index: number,
-  ) => (Result & Synchronous<Result>) | CallbackGenerator<Result>,
+  callback: (item: Item, index: number) => Result | CallbackGenerator<Result>,
   budget = new TimeSliceBudget(),
 ): Promise<Result[]> {
   const results: Result[] = [];
   await traverse(
+    "timeSlicedMap",
     items,
     callback,
     (result) => {
@@ -370,7 +381,8 @@ export async function timeSlicedFlatMap<Item, Result>(
  * Returns items whose synchronous predicate is true, preserving input order.
  *
  * Measures predicate work and result accumulation. One predicate call cannot be
- * interrupted. The optional budget defaults to a new independent instance.
+ * interrupted. Throws a `TypeError` if the predicate returns a promise or other
+ * thenable. The optional budget defaults to a new independent instance.
  *
  * @example Keep odd numbers.
  * const odd = await timeSlicedFilter([1, 2, 3], (value) => value % 2 === 1);
@@ -390,7 +402,13 @@ export async function timeSlicedFilter<Item>(
   await timeSlicedForEach(
     items,
     (item, index) => {
-      if (predicate(item, index)) {
+      if (
+        assertNotThenable(
+          predicate(item, index),
+          "timeSlicedFilter",
+          TRAVERSAL_HINT,
+        )
+      ) {
         // oxlint-disable-next-line zingage/no-restricted-syntax -- Append to the local result without quadratic copying.
         results.push(item);
       }
@@ -404,6 +422,8 @@ export async function timeSlicedFilter<Item>(
  * Groups items by a synchronous key, preserving key and group insertion order.
  *
  * Uses `Map` key equality. Measures key selection and group accumulation.
+ * `keyOf` must be synchronous. If it returns a promise or other thenable, the
+ * operation throws a `TypeError` before it stores the key.
  * The optional budget defaults to a new independent `TimeSliceBudget`.
  *
  * @example Group strings by length.
@@ -417,14 +437,18 @@ export async function timeSlicedFilter<Item>(
  */
 export async function timeSlicedGroupBy<Item, Key>(
   items: Iterable<Item>,
-  keyOf: (item: Item, index: number) => Key & Synchronous<Key>,
+  keyOf: (item: Item, index: number) => Key,
   budget = new TimeSliceBudget(),
 ): Promise<Map<Key, Item[]>> {
   const groups = new Map<Key, Item[]>();
   await timeSlicedForEach(
     items,
     (item, index) => {
-      const key = keyOf(item, index);
+      const key = assertNotThenable(
+        keyOf(item, index),
+        "timeSlicedGroupBy",
+        TRAVERSAL_HINT,
+      );
       const group = groups.get(key);
       if (group === undefined) groups.set(key, [item]);
       // oxlint-disable-next-line zingage/no-restricted-syntax -- Each local group accumulates without quadratic copying.

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;
+  };
+}