@zingage/scheduling 0.0.0-stage → 1.0.0

package/dist/time-slicing.js

@@ -0,0 +1,301 @@
+import assert from "node:assert/strict";
+import { setImmediate } from "node:timers/promises";
+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 {
+    #sliceMs;
+    #now;
+    #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 = 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.
+     *
+     * @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(work) {
+        const outermost = this.#depth === 0;
+        const startedAt = outermost ? this.#now() : 0;
+        this.#depth += 1;
+        try {
+            return work();
+        }
+        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() {
+        if (this.#remainingMs > 0)
+            return undefined;
+        this.#remainingMs = this.#sliceMs;
+        return this.#yieldToEventLoop();
+    }
+}
+/**
+ * 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(promise) {
+    const result = {};
+    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(value) {
+    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, budget) {
+    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", value }), (error) => ({ status: "rejected", error }));
+        state.step =
+            outcome.status === "fulfilled"
+                ? budget.measure(() => generator.next(outcome.value))
+                : budget.measure(() => generator.throw(outcome.error));
+    }
+}
+async function runCallbackGenerator(generator, budget) {
+    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", value }), (error) => ({ status: "rejected", 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(items, callback, accept, budget) {
+    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(() => callback(item, position.index));
+        const result = isCallbackGenerator(value)
+            ? await runCallbackGenerator(value, budget)
+            : value;
+        budget.measure(() => accept(result));
+        position.index += 1;
+        const pending = budget.yieldIfNeeded();
+        if (pending !== undefined)
+            await pending;
+    }
+}
+export async function timeSlicedForEach(items, callback, budget = new TimeSliceBudget()) {
+    await traverse(items, callback, () => { }, budget);
+}
+export async function timeSlicedMap(items, callback, budget = new TimeSliceBudget()) {
+    const results = [];
+    await traverse(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(items, callback, budget = new TimeSliceBudget()) {
+    const results = [];
+    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. 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(items, predicate, budget = new TimeSliceBudget()) {
+    const results = [];
+    await timeSlicedForEach(items, (item, index) => {
+        if (predicate(item, index)) {
+            // 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.
+ * 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(items, keyOf, budget = new TimeSliceBudget()) {
+    const groups = new Map();
+    await timeSlicedForEach(items, (item, index) => {
+        const key = keyOf(item, index);
+        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(entries, budget = new TimeSliceBudget()) {
+    const result = new Map();
+    await timeSlicedForEach(entries, ([key, value]) => {
+        result.set(key, value);
+    }, budget);
+    return result;
+}
+//# sourceMappingURL=time-slicing.js.map

package/dist/time-slicing.js.map

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

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@zingage/scheduling",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joinava/sensitive-packages.git",
+    "directory": "packages/scheduling"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!dist/**/*.test.*",
+    "!src/**/*.test.ts",
+    "!dist/.tsbuildinfo"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@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"
+  },
+  "scripts": {
+    "tsc:watch": "tsc -b --watch",
+    "tsc:full-emit": "tsc -b --noCheck",
+    "tsc:check": "tsc -b --emitDeclarationOnly",
+    "lint:oxlint": "oxlint --type-aware src",
+    "test": "node --test  \"./dist/**/*.test.js\"",
+    "test:watch": "node --test --watch \"./dist/**/*.test.js\"",
+    "test:ci": "NODE_OPTIONS=\"--test-reporter=junit --test-reporter-destination=./test-report.xml --test-reporter=spec --test-reporter-destination=stdout\" pnpm run test",
+    "dev": "pnpm run tsc:watch"
+  }
 }

package/src/index.ts

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

package/src/time-sliced-sort.ts

@@ -0,0 +1,95 @@
+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<Item>(
+  items: Iterable<Item>,
+  compare: (left: Item, right: Item) => number,
+  budget = new TimeSliceBudget(),
+): Promise<Item[]> {
+  // Boxing distinguishes an absent buffer entry from a valid undefined input value.
+  type Entry = { value: Item };
+  const buffers: { source: Entry[]; target: Entry[]; width: number } = {
+    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: Item[] = [];
+  await timeSlicedForEach(
+    buffers.source,
+    (entry) => {
+      result.push(entry.value);
+    },
+    budget,
+  );
+  /* oxlint-enable zingage/no-restricted-syntax */
+  return result;
+}