@zingage/scheduling 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# @zingage/scheduling
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cooperative collection helpers for synchronous work and generator callbacks in Node.js. Each helper defaults to a new independent budget with a 4 ms processing allowance.
+
+```ts
+import {
+  TimeSliceBudget,
+  timeSlicedForEach,
+  timeSlicedMap,
+} from "@zingage/scheduling";
+
+// Independent calls do not consume each other's budget.
+await Promise.all([
+  timeSlicedMap(firstItems, transform),
+  timeSlicedMap(secondItems, transform),
+]);
+
+// Connected calls share the remaining allowance explicitly.
+const budget = new TimeSliceBudget();
+await Promise.all([
+  timeSlicedMap(firstItems, transform, budget),
+  timeSlicedForEach(secondItems, processItem, budget),
+]);
+```
+
+## Budget semantics
+
+The package measures elapsed time around synchronous callbacks and result accumulation. It subtracts that measured time from the budget. Waiting at a yield and unrelated work between measured steps do not consume the budget.
+
+If A uses 1 ms and finishes, connected B gets the remaining 3 ms. If A exhausts the budget, A replenishes it before yielding. B can then use the new 4 ms while A waits. A does not replenish the budget when it resumes. Unrelated C uses a separate budget and cannot consume A/B's allowance.
+
+One callback or iterator step cannot be interrupted. Nested helpers started inside a synchronous callback cannot interrupt that containing callback. Their work counts once toward a shared budget. Garbage collection and operating-system pauses inside a measured step count as elapsed processing time. This is not CPU-time accounting or a hard event-loop delay bound. Work outside the helpers does not count. Ordinary callbacks must be synchronous. `timeSlicedMap` and `timeSlicedForEach` also accept generator callbacks. They do not accept async functions.
+
+The constructor is `new TimeSliceBudget(sliceMs = DEFAULT_TIME_SLICE_MS, now = performance.now, yieldToEventLoop = setImmediate)`. `sliceMs` must be positive and finite. `now` must be a monotonic clock in milliseconds. The budget binds the clock to `performance` because Node's default clock requires that receiver. The default yield function is Node's promise-based `setImmediate`. A custom yield function must let the event loop advance; `Promise.resolve()` does not provide that behavior. Optionally pass a budget directly as each helper's last argument to share its allowance.
+
+## Helpers
+
+| Helper                     | Result                                                                       |
+| -------------------------- | ---------------------------------------------------------------------------- |
+| `timeSlicedForEach`        | Runs callbacks in input order; returns `Promise<void>`.                      |
+| `timeSlicedMap`            | Returns transformed values in input order.                                   |
+| `timeSlicedFlatMap`        | Flattens each callback's list incrementally, including large lists.          |
+| `timeSlicedFilter`         | Returns matching items in input order.                                       |
+| `timeSlicedGroupBy`        | Returns a `Map` with first-seen key order and input order within each group. |
+| `timeSlicedSort`           | Returns a new stable sorted array with a synchronous comparator.             |
+| `timeSlicedMapFromEntries` | Builds a `Map`; the last value wins for repeated keys.                       |
+
+All helpers accept synchronous iterables. Callbacks receive the item and its zero-based index. Callback, iterator, and yield errors reject the operation. Callback failures still consume their measured processing time. The loops use native `for…of` cleanup rules. Callback and yield failures close the active iterator when it provides `return()`, while failures from `next()` do not. An existing callback or yield error takes precedence if cleanup also throws. Iterator advancement does not consume the budget.
+
+The package does not infer parent operations or use global budgets. It does not serialize mutations or impose ordering between concurrent calls. Backend consumers use this package. The former `time-sliced-map.ts` utility has been removed.
+
+## Generator callbacks
+
+`timeSlicedMap` and `timeSlicedForEach` finish each generator callback before starting the next item. Use `yield* waitFor(promise)` to suspend with an inferred result type:
+
+```ts
+import { timeSlicedMap, waitFor } from "@zingage/scheduling";
+
+const results = await timeSlicedMap(
+  items,
+  function* (item) {
+    const data = yield* waitFor(load(item));
+    return process(data);
+  },
+  budget,
+);
+```
+
+The budget measures every `next()` and `throw()` call, including synchronous work after suspension. Promise waits do not consume the budget. A rejected promise enters the generator through `throw()`, so generator `catch` and `finally` blocks run normally. Recovery can yield another promise. An unhandled error rejects the traversal and prevents later callbacks from starting. If the scheduler fails, the helper closes the callback generator and awaits its yielded cleanup. Cleanup does not call the failed scheduler again. The original scheduler error takes precedence over cleanup errors.
+
+Generator callbacks may also yield promises directly, but their resumed values have type `unknown`. Use `waitFor` for typed values. A synchronous segment cannot be interrupted. Break expensive callbacks into smaller generator segments. Nested helpers share accounting, but cannot interrupt the synchronous segment that starts them.
+
+## Sorting
+
+`timeSlicedSort(items, compare, budget?)` returns a new array and preserves the
+input order of values that compare equal. It uses a stable merge sort and checks
+the budget after each merge write, including tail copies. Input copying and
+result extraction also use the budget. Comparators must be synchronous; one
+comparator call cannot be interrupted. The comparator receives all values,
+including `undefined`. A `NaN` comparison result acts like zero.
+
+```ts
+const budget = new TimeSliceBudget();
+const sorted = await timeSlicedSort(
+  [3, 1, 2],
+  (left, right) => left - right,
+  budget,
+);
+```
+
+For async sort keys, use generator callbacks with `timeSlicedMap` to load the
+keys, then pass a synchronous comparator to `timeSlicedSort`.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { waitFor, timeSlicedFilter, timeSlicedFlatMap, timeSlicedForEach, timeSlicedGroupBy, timeSlicedMap, timeSlicedMapFromEntries, TimeSliceBudget, } from "./time-slicing.js";
+export { timeSlicedSort } from "./time-sliced-sort.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,wBAAwB,EACxB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { waitFor, timeSlicedFilter, timeSlicedFlatMap, timeSlicedForEach, timeSlicedGroupBy, timeSlicedMap, timeSlicedMapFromEntries, TimeSliceBudget, } from "./time-slicing.js";
+export { timeSlicedSort } from "./time-sliced-sort.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,wBAAwB,EACxB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/time-sliced-sort.d.ts

@@ -0,0 +1,26 @@
+import { TimeSliceBudget } from "./time-slicing.js";
+/**
+ * Returns a new, stably sorted array using a synchronous comparator.
+ *
+ * A negative result puts the left value first; a positive result puts the right
+ * value first. Zero and NaN preserve input order. The comparator receives every
+ * input value, including undefined. The input is not reordered.
+ *
+ * Measures copying, comparisons, and merge writes. Checks the budget after each
+ * merge write, including writes that need no comparison. One comparator call
+ * cannot be interrupted. A nested helper cannot interrupt its containing
+ * measured segment. Uses O(n log n) work and O(n) additional memory.
+ * The optional budget defaults to a new independent `TimeSliceBudget`.
+ *
+ * @example Sort a readonly input without reordering it.
+ * const sorted = await timeSlicedSort([3, 1, 2] as const, (left, right) => left - right);
+ *
+ * @example Load values in a generator and share its budget with sorting.
+ * const budget = new TimeSliceBudget();
+ * const sortedPages = await timeSlicedMap([1, 2], function* (page) {
+ *   const values = yield* waitFor(Promise.resolve([page + 1, page]));
+ *   return yield* waitFor(timeSlicedSort(values, (left, right) => left - right, budget));
+ * }, budget);
+ */
+export declare function timeSlicedSort<Item>(items: Iterable<Item>, compare: (left: Item, right: Item) => number, budget?: TimeSliceBudget): Promise<Item[]>;
+//# sourceMappingURL=time-sliced-sort.d.ts.map

package/dist/time-sliced-sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-sliced-sort.d.ts","sourceRoot":"","sources":["../src/time-sliced-sort.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAqB,MAAM,mBAAmB,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,cAAc,CAAC,IAAI,EACvC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,KAAK,MAAM,EAC5C,MAAM,kBAAwB,GAC7B,OAAO,CAAC,IAAI,EAAE,CAAC,CAgEjB"}

package/dist/time-sliced-sort.js

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import { TimeSliceBudget, timeSlicedForEach } from "./time-slicing.js";
+/**
+ * Returns a new, stably sorted array using a synchronous comparator.
+ *
+ * A negative result puts the left value first; a positive result puts the right
+ * value first. Zero and NaN preserve input order. The comparator receives every
+ * input value, including undefined. The input is not reordered.
+ *
+ * Measures copying, comparisons, and merge writes. Checks the budget after each
+ * merge write, including writes that need no comparison. One comparator call
+ * cannot be interrupted. A nested helper cannot interrupt its containing
+ * measured segment. Uses O(n log n) work and O(n) additional memory.
+ * The optional budget defaults to a new independent `TimeSliceBudget`.
+ *
+ * @example Sort a readonly input without reordering it.
+ * const sorted = await timeSlicedSort([3, 1, 2] as const, (left, right) => left - right);
+ *
+ * @example Load values in a generator and share its budget with sorting.
+ * const budget = new TimeSliceBudget();
+ * const sortedPages = await timeSlicedMap([1, 2], function* (page) {
+ *   const values = yield* waitFor(Promise.resolve([page + 1, page]));
+ *   return yield* waitFor(timeSlicedSort(values, (left, right) => left - right, budget));
+ * }, budget);
+ */
+export async function timeSlicedSort(items, compare, budget = new TimeSliceBudget()) {
+    const buffers = {
+        source: [],
+        target: [],
+        width: 1,
+    };
+    /* oxlint-disable zingage/no-restricted-syntax -- Stable merging uses local buffers and sequential index updates to avoid quadratic copying and per-item promises. */
+    await timeSlicedForEach(items, (value) => {
+        buffers.source.push({ value });
+    }, budget);
+    const length = buffers.source.length;
+    while (buffers.width < length) {
+        const run = { start: 0 };
+        while (run.start < length) {
+            const middle = Math.min(run.start + buffers.width, length);
+            const end = Math.min(run.start + 2 * buffers.width, length);
+            const position = { left: run.start, right: middle, output: run.start };
+            while (position.output < end) {
+                budget.measure(() => {
+                    const left = position.left < middle ? buffers.source[position.left] : undefined;
+                    const right = position.right < end ? buffers.source[position.right] : undefined;
+                    assert.ok(left !== undefined || position.left === middle);
+                    assert.ok(right !== undefined || position.right === end);
+                    if (left !== undefined &&
+                        (right === undefined || !(compare(left.value, right.value) > 0))) {
+                        buffers.target[position.output] = left;
+                        position.left += 1;
+                    }
+                    else {
+                        assert.ok(right);
+                        buffers.target[position.output] = right;
+                        position.right += 1;
+                    }
+                    position.output += 1;
+                });
+                const pending = budget.yieldIfNeeded();
+                if (pending !== undefined)
+                    await pending;
+            }
+            run.start = end;
+        }
+        const previous = buffers.source;
+        buffers.source = buffers.target;
+        buffers.target = previous;
+        buffers.width *= 2;
+    }
+    const result = [];
+    await timeSlicedForEach(buffers.source, (entry) => {
+        result.push(entry.value);
+    }, budget);
+    /* oxlint-enable zingage/no-restricted-syntax */
+    return result;
+}
+//# sourceMappingURL=time-sliced-sort.js.map

package/dist/time-sliced-sort.js.map

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

package/dist/time-slicing.d.ts

@@ -0,0 +1,197 @@
+type Synchronous<Result> = Result extends PromiseLike<unknown> ? never : Result;
+/**
+ * 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 declare class TimeSliceBudget {
+    #private;
+    /**
+     * 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?: number, now?: () => DOMHighResTimeStamp, yieldToEventLoop?: () => Promise<void>);
+    /**
+     * 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.
+     *
+     * @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 & Synchronous<Result>): Result;
+    /**
+     * 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;
+}
+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 declare function waitFor<Value>(promise: PromiseLike<Value>): CallbackGenerator<Value>;
+/**
+ * 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.
+ * 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 declare 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.
+ *
+ * @example
+ * await timeSlicedForEach([1, 2], (value) => console.log(value));
+ */
+export declare function timeSlicedForEach<Item, Result>(items: Iterable<Item>, callback: (item: Item, index: number) => Result & Synchronous<Result>, budget?: TimeSliceBudget): Promise<void>;
+/**
+ * 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.
+ * 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 declare 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.
+ *
+ * @example
+ * const doubled = await timeSlicedMap([1, 2], (value) => value * 2);
+ */
+export declare function timeSlicedMap<Item, Result>(items: Iterable<Item>, callback: (item: Item, index: number) => Result & Synchronous<Result>, budget?: TimeSliceBudget): Promise<Result[]>;
+/**
+ * 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 declare function timeSlicedFlatMap<Item, Result>(items: Iterable<Item>, callback: (item: Item, index: number) => readonly Result[], budget?: TimeSliceBudget): Promise<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.
+ *
+ * @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 declare function timeSlicedFilter<Item>(items: Iterable<Item>, predicate: (item: Item, index: number) => boolean, budget?: TimeSliceBudget): Promise<Item[]>;
+/**
+ * Groups items by a synchronous key, preserving key and group insertion order.
+ *
+ * Uses `Map` key equality. Measures key selection and group accumulation.
+ * 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 declare function timeSlicedGroupBy<Item, Key>(items: Iterable<Item>, keyOf: (item: Item, index: number) => Key & Synchronous<Key>, budget?: TimeSliceBudget): Promise<Map<Key, Item[]>>;
+/**
+ * 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 declare function timeSlicedMapFromEntries<Key, Value>(entries: Iterable<readonly [Key, Value]>, budget?: TimeSliceBudget): Promise<Map<Key, Value>>;
+export {};
+//# sourceMappingURL=time-slicing.d.ts.map

package/dist/time-slicing.d.ts.map

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