@zingage/scheduling 0.0.0-stage → 1.1.0

package/src/time-slicing.ts

@@ -0,0 +1,490 @@
+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);
+
+/**
+ * Tracks measured synchronous work before yielding to the event loop.
+ *
+ * A new budget allows 4 ms by default. Related operations can share an instance.
+ * Promise waits and unmeasured work do not consume it. One synchronous segment
+ * cannot be interrupted. Nested measurements on the same budget count once.
+ *
+ * @example Share the remaining allowance across related operations.
+ * const budget = new TimeSliceBudget();
+ * const doubled = await timeSlicedMap([1, 2], (value) => value * 2, budget);
+ * await timeSlicedForEach(doubled, (value) => console.log(value), budget);
+ */
+export class TimeSliceBudget {
+  readonly #sliceMs;
+  readonly #now;
+  readonly #yieldToEventLoop;
+  #remainingMs;
+  #depth = 0;
+
+  /**
+   * Creates a budget with a positive, finite allowance in milliseconds.
+   *
+   * `now` must be monotonic and return milliseconds. The default uses
+   * `performance.now`. The default scheduler uses promise-based `setImmediate`.
+   * A custom scheduler must let the event loop advance; a resolved promise does not.
+   *
+   * @example Use a smaller allowance for one operation.
+   * const budget = new TimeSliceBudget(2);
+   */
+  constructor(
+    sliceMs = DEFAULT_TIME_SLICE_MS,
+    now = performanceNow,
+    yieldToEventLoop: () => Promise<void> = setImmediate,
+  ) {
+    assert.ok(
+      Number.isFinite(sliceMs) && sliceMs > 0,
+      "sliceMs must be finite and greater than zero",
+    );
+    this.#sliceMs = sliceMs;
+    this.#remainingMs = sliceMs;
+    this.#now = now.bind(performance);
+    this.#yieldToEventLoop = yieldToEventLoop;
+  }
+
+  /**
+   * Runs synchronous work and charges its elapsed time, including when it throws.
+   *
+   * 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();
+   * const value = budget.measure(() => 2 * 3);
+   * const pending = budget.yieldIfNeeded();
+   * if (pending !== undefined) await pending;
+   */
+  measure<Result>(work: () => Result): Result {
+    const outermost = this.#depth === 0;
+    const startedAt = outermost ? this.#now() : 0;
+    this.#depth += 1;
+    try {
+      return assertNotThenable(
+        work(),
+        "TimeSliceBudget.measure",
+        GENERATOR_HINT,
+      );
+    } finally {
+      this.#depth -= 1;
+      if (outermost) this.#remainingMs -= this.#now() - startedAt;
+    }
+  }
+
+  /**
+   * Returns a yield promise if the allowance is exhausted, or `undefined` otherwise.
+   *
+   * Replenishes before scheduling the yield. Connected work can use the next
+   * allowance while this caller waits. Resuming does not replenish it again.
+   *
+   * @example Avoid a microtask suspension when the budget still has time.
+   * const budget = new TimeSliceBudget();
+   * const pending = budget.yieldIfNeeded();
+   * if (pending !== undefined) await pending;
+   */
+  yieldIfNeeded(): Promise<void> | undefined {
+    if (this.#remainingMs > 0) return undefined;
+    this.#remainingMs = this.#sliceMs;
+    return this.#yieldToEventLoop();
+  }
+}
+
+type CallbackGenerator<Result> = Generator<
+  PromiseLike<unknown>,
+  Result,
+  unknown
+>;
+
+/**
+ * Suspends a generator callback until a promise settles, preserving its value type.
+ *
+ * Use `yield* waitFor(promise)` inside a generator passed to `timeSlicedMap` or
+ * `timeSlicedForEach`. Rejections enter the generator through `throw()`, so its
+ * `catch` and `finally` blocks run normally. Falsy and void results are supported.
+ *
+ * @example Infer the resolved value without annotating the generator.
+ * const lengths = await timeSlicedMap(["Ada"], function* (name) {
+ *   const text = yield* waitFor(Promise.resolve(name));
+ *   return text.length;
+ * });
+ *
+ * @example Recover from a rejected promise inside the generator.
+ * const values = await timeSlicedMap([1], function* (value) {
+ *   try {
+ *     return yield* waitFor(Promise.reject<number>(new TypeError("unavailable")));
+ *   } catch {
+ *     return value;
+ *   }
+ * });
+ */
+export function* waitFor<Value>(
+  promise: PromiseLike<Value>,
+): CallbackGenerator<Value> {
+  const result: { value?: { resolved: Value } } = {};
+  yield promise.then((value) => {
+    result.value = { resolved: value };
+  });
+  assert.ok(result.value, "waitFor must resume after its promise resolves");
+  return result.value.resolved;
+}
+
+function isCallbackGenerator<Result>(
+  value: Result | CallbackGenerator<Result>,
+): value is CallbackGenerator<Result> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "next" in value &&
+    typeof value.next === "function" &&
+    "throw" in value &&
+    typeof value.throw === "function" &&
+    Symbol.iterator in value &&
+    typeof value[Symbol.iterator] === "function"
+  );
+}
+
+async function closeCallbackGenerator(
+  generator: CallbackGenerator<unknown>,
+  budget: TimeSliceBudget,
+): Promise<void> {
+  const state = { step: budget.measure(() => generator.return(undefined)) };
+  // oxlint-disable-next-line zingage/no-restricted-syntax -- Drain yielded cleanup without calling the failed scheduler again.
+  while (!state.step.done) {
+    const outcome = await Promise.resolve(state.step.value).then(
+      (value) => ({ status: "fulfilled" as const, value }),
+      (error: unknown) => ({ status: "rejected" as const, error }),
+    );
+    state.step =
+      outcome.status === "fulfilled"
+        ? budget.measure(() => generator.next(outcome.value))
+        : budget.measure(() => generator.throw(outcome.error));
+  }
+}
+
+async function runCallbackGenerator<Result>(
+  generator: CallbackGenerator<Result>,
+  budget: TimeSliceBudget,
+): Promise<Result> {
+  const state = { step: budget.measure(() => generator.next()) };
+  // oxlint-disable-next-line zingage/no-restricted-syntax -- Each generator segment must settle before the next measured segment starts.
+  while (!state.step.done) {
+    // Attach rejection handling before a budget yield can let the event loop advance.
+    const settled = Promise.resolve(state.step.value).then(
+      (value) => ({ status: "fulfilled" as const, value }),
+      (error: unknown) => ({ status: "rejected" as const, error }),
+    );
+    try {
+      const pending = budget.yieldIfNeeded();
+      if (pending !== undefined) await pending;
+    } catch (error) {
+      try {
+        await closeCallbackGenerator(generator, budget);
+      } catch {
+        // Cleanup failures must not replace the scheduler failure.
+      }
+      throw error;
+    }
+    const outcome = await settled;
+    state.step =
+      outcome.status === "fulfilled"
+        ? budget.measure(() => generator.next(outcome.value))
+        : budget.measure(() => generator.throw(outcome.error));
+  }
+  return state.step.value;
+}
+
+async function traverse<Item, Result>(
+  helper: string,
+  items: Iterable<Item>,
+  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(() =>
+      assertNotThenable(callback(item, position.index), helper, GENERATOR_HINT),
+    );
+    const result = isCallbackGenerator<Result>(value)
+      ? await runCallbackGenerator(value, budget)
+      : value;
+    budget.measure(() => accept(result));
+    position.index += 1;
+    const pending = budget.yieldIfNeeded();
+    if (pending !== undefined) await pending;
+  }
+}
+
+/**
+ * Runs callbacks sequentially in input order and discards their return values.
+ *
+ * Accepts synchronous callbacks or generators that yield promises. Each generator
+ * 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.
+ * await timeSlicedForEach([1, 2], (value) => console.log(value));
+ *
+ * @example Await work sequentially with a typed generator callback.
+ * await timeSlicedForEach([1, 2], function* (value) {
+ *   const doubled = yield* waitFor(Promise.resolve(value * 2));
+ *   console.log(doubled);
+ * });
+ */
+export function timeSlicedForEach<Item, Result>(
+  items: Iterable<Item>,
+  callback: (item: Item, index: number) => CallbackGenerator<Result>,
+  budget?: TimeSliceBudget,
+): Promise<void>;
+/**
+ * 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,
+  budget?: TimeSliceBudget,
+): Promise<void>;
+export async function timeSlicedForEach<Item, Result>(
+  items: Iterable<Item>,
+  callback: (item: Item, index: number) => Result | CallbackGenerator<Result>,
+  budget = new TimeSliceBudget(),
+): Promise<void> {
+  await traverse("timeSlicedForEach", items, callback, () => {}, budget);
+}
+
+/**
+ * Returns transformed values in input order using sequential callbacks.
+ *
+ * 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: 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.
+ * const doubled = await timeSlicedMap([1, 2], (value) => value * 2);
+ *
+ * @example Resume measured work after each promise settles.
+ * const doubled = await timeSlicedMap([1, 2], function* (value) {
+ *   const factor = yield* waitFor(Promise.resolve(2));
+ *   return value * factor;
+ * });
+ */
+export function timeSlicedMap<Item, Result>(
+  items: Iterable<Item>,
+  callback: (item: Item, index: number) => CallbackGenerator<Result>,
+  budget?: TimeSliceBudget,
+): Promise<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,
+  budget?: TimeSliceBudget,
+): Promise<Result[]>;
+export async function timeSlicedMap<Item, Result>(
+  items: Iterable<Item>,
+  callback: (item: Item, index: number) => Result | CallbackGenerator<Result>,
+  budget = new TimeSliceBudget(),
+): Promise<Result[]> {
+  const results: Result[] = [];
+  await traverse(
+    "timeSlicedMap",
+    items,
+    callback,
+    (result) => {
+      // oxlint-disable-next-line zingage/no-restricted-syntax -- Append to the local result to avoid quadratic copying.
+      results.push(result);
+    },
+    budget,
+  );
+  return results;
+}
+
+/**
+ * Maps each item to a synchronous list and flattens the lists in input order.
+ *
+ * Measures callbacks and appends. It can yield within one large returned list.
+ * One callback cannot be interrupted. For asynchronous mapping, first use a
+ * generator callback with `timeSlicedMap`, then flatten the returned lists.
+ * The optional budget defaults to a new independent `TimeSliceBudget`.
+ *
+ * @example Flatten synchronous results.
+ * const values = await timeSlicedFlatMap([1, 2], (value) => [value, value * 2]);
+ *
+ * @example Fetch lists with generators and share their budget with flattening.
+ * const budget = new TimeSliceBudget();
+ * const pages = await timeSlicedMap([1, 2], function* (value) {
+ *   return yield* waitFor(Promise.resolve([value, value * 2]));
+ * }, budget);
+ * const values = await timeSlicedFlatMap(pages, (page) => page, budget);
+ */
+export async function timeSlicedFlatMap<Item, Result>(
+  items: Iterable<Item>,
+  callback: (item: Item, index: number) => readonly Result[],
+  budget = new TimeSliceBudget(),
+): Promise<Result[]> {
+  const results: Result[] = [];
+  const position = { index: 0 };
+  // oxlint-disable-next-line zingage/no-restricted-syntax -- Native outer iteration owns cleanup; inner traversal can also yield.
+  for (const item of items) {
+    const mapped = budget.measure(() => callback(item, position.index));
+    position.index += 1;
+    const pending = budget.yieldIfNeeded();
+    if (pending !== undefined) await pending;
+    await timeSlicedForEach(
+      mapped,
+      (value) => {
+        // oxlint-disable-next-line zingage/no-restricted-syntax -- Append incrementally without argument-spread limits or quadratic copying.
+        results.push(value);
+      },
+      budget,
+    );
+  }
+  const pending = budget.yieldIfNeeded();
+  if (pending !== undefined) await pending;
+  return results;
+}
+
+/**
+ * Returns items whose synchronous predicate is true, preserving input order.
+ *
+ * Measures predicate work and result accumulation. 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 instance.
+ *
+ * @example Keep odd numbers.
+ * const odd = await timeSlicedFilter([1, 2, 3], (value) => value % 2 === 1);
+ *
+ * @example Compose filtering inside a generator with a shared budget.
+ * const budget = new TimeSliceBudget();
+ * const groups = await timeSlicedMap([[1, 2, 3]], function* (values) {
+ *   return yield* waitFor(timeSlicedFilter(values, (value) => value > 1, budget));
+ * }, budget);
+ */
+export async function timeSlicedFilter<Item>(
+  items: Iterable<Item>,
+  predicate: (item: Item, index: number) => boolean,
+  budget = new TimeSliceBudget(),
+): Promise<Item[]> {
+  const results: Item[] = [];
+  await timeSlicedForEach(
+    items,
+    (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);
+      }
+    },
+    budget,
+  );
+  return results;
+}
+
+/**
+ * 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.
+ * const groups = await timeSlicedGroupBy(["a", "bb", "c"], (text) => text.length);
+ *
+ * @example Await grouping inside a generator and share its budget.
+ * const budget = new TimeSliceBudget();
+ * const groupedPages = await timeSlicedMap([[1, 2, 3]], function* (values) {
+ *   return yield* waitFor(timeSlicedGroupBy(values, (value) => value % 2, budget));
+ * }, budget);
+ */
+export async function timeSlicedGroupBy<Item, Key>(
+  items: Iterable<Item>,
+  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 = 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.
+      else group.push(item);
+    },
+    budget,
+  );
+  return groups;
+}
+
+/**
+ * Builds a Map from entries in input order; the last value for a repeated key wins.
+ *
+ * Measures entry insertion. Replacing a value preserves the key's first insertion
+ * position. The optional budget defaults to a new independent `TimeSliceBudget`.
+ *
+ * @example Build a Map while preserving last-value-wins behavior.
+ * const map = await timeSlicedMapFromEntries([["a", 1], ["a", 2]] as const);
+ *
+ * @example Await Map construction inside a generator with a shared budget.
+ * const budget = new TimeSliceBudget();
+ * const maps = await timeSlicedMap([1, 2], function* (value) {
+ *   return yield* waitFor(timeSlicedMapFromEntries([["key", value]] as const, budget));
+ * }, budget);
+ */
+export async function timeSlicedMapFromEntries<Key, Value>(
+  entries: Iterable<readonly [Key, Value]>,
+  budget = new TimeSliceBudget(),
+): Promise<Map<Key, Value>> {
+  const result = new Map<Key, Value>();
+  await timeSlicedForEach(
+    entries,
+    ([key, value]) => {
+      result.set(key, value);
+    },
+    budget,
+  );
+  return result;
+}