react-inp-chunker 0.1.2 → 0.2.0

package/dist/deferred-task-CwjZA3K-.js

@@ -0,0 +1,713 @@
+// src/core/chunk-machine.ts
+const initialChunkState = { status: "idle" };
+const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+	"done",
+	"cancelled",
+	"error"
+]);
+function isTerminal(status) {
+	return TERMINAL_STATUSES.has(status);
+}
+function transitionIdle(state, event) {
+	switch (event.type) {
+		case "START": return { status: "processing" };
+		case "CANCEL": return { status: "cancelled" };
+		case "PAUSE":
+		case "RESUME":
+		case "COMPLETE":
+		case "ERROR": return state;
+	}
+}
+function transitionProcessing(state, event) {
+	switch (event.type) {
+		case "PAUSE": return { status: "paused" };
+		case "CANCEL": return { status: "cancelled" };
+		case "COMPLETE": return { status: "done" };
+		case "ERROR": return {
+			status: "error",
+			error: event.error
+		};
+		case "START":
+		case "RESUME": return state;
+	}
+}
+function transitionPaused(state, event) {
+	switch (event.type) {
+		case "RESUME": return { status: "processing" };
+		case "CANCEL": return { status: "cancelled" };
+		case "START":
+		case "PAUSE":
+		case "COMPLETE":
+		case "ERROR": return state;
+	}
+}
+/**
+* Advances the machine by one event. Pure: same inputs always produce an
+* equal output, and the input state is never mutated.
+*/
+function transition(state, event) {
+	switch (state.status) {
+		case "idle": return transitionIdle(state, event);
+		case "processing": return transitionProcessing(state, event);
+		case "paused": return transitionPaused(state, event);
+		case "done":
+		case "cancelled":
+		case "error": return state;
+	}
+}
+// src/core/diagnostics.ts
+/**
+* Development-only guidance for the two ways a chunked task quietly fails
+* to do what the caller wanted:
+*
+*  1. A single item takes longer than a long task. Chunking cannot help:
+*     a slice is never shorter than one item, so the page still freezes.
+*  2. Items are so cheap that reading the clock — around 300ns in a
+*     browser, where it is coarsened to 0.1ms anyway — costs more than the
+*     work between reads. `batchSize` exists for exactly this.
+*
+* Neither is visible from the outside without a profiler, and both have a
+* concrete fix, which is what makes them worth a warning.
+*
+* Nothing here costs anything in production. The engines guard every call
+* with `isDevelopment`, which the production build (see tsdown.config.ts)
+* replaces with a literal `false`, so the calls and this module both
+* disappear. The checks also ride on clock reads the loop already makes and
+* keep their own baselines, so the hot loop needs no extra bookkeeping.
+*/
+const isDevelopment = typeof process !== "undefined" && process.env["NODE_ENV"] !== "production";
+/** The Long Tasks API's definition: past this, the browser calls it a long task. */
+const LONG_UNIT_MS = 50;
+/** Below this average cost, the clock read dominates the work. */
+const CLOCK_BOUND_UNIT_MS = .002;
+/** Units per slice below which the sample is too small to judge. */
+const MIN_UNITS_TO_JUDGE = 64;
+/** A suggested batch should take about this long, bounding the overshoot it buys. */
+const TARGET_BATCH_MS = .1;
+const MAX_SUGGESTED_BATCH = 512;
+function warn(message) {
+	console.warn(`[react-inp-chunker] ${message}`);
+}
+/**
+* A batch that should take about TARGET_BATCH_MS, which is also the
+* overshoot the caller takes on by accepting it. No lower bound is needed:
+* the warning only fires below CLOCK_BOUND_UNIT_MS, so the result is
+* always at least TARGET_BATCH_MS / CLOCK_BOUND_UNIT_MS.
+*/
+function suggestedBatchSize(unitCostMs) {
+	const target = Math.round(TARGET_BATCH_MS / unitCostMs);
+	return target > MAX_SUGGESTED_BATCH ? MAX_SUGGESTED_BATCH : target;
+}
+/**
+* `unit` names what one step of this task is, so the message can say
+* "item" for a chunked array and "segment" for a generator.
+*/
+function createDiagnostics(unit, batchSize) {
+	let lastCheckAt = 0;
+	let lastCheckUnits = 0;
+	let sliceStartedAt = 0;
+	let sliceStartUnits = 0;
+	let started = false;
+	let warnedAboutLongUnit = false;
+	let warnedAboutClockCost = false;
+	const rebase = (at, unitsDone) => {
+		lastCheckAt = at;
+		lastCheckUnits = unitsDone;
+		sliceStartedAt = at;
+		sliceStartUnits = unitsDone;
+		started = true;
+	};
+	return {
+		check(at, unitsDone) {
+			if (!started) {
+				rebase(at, unitsDone);
+				return;
+			}
+			const batchMs = at - lastCheckAt;
+			const unitsInBatch = unitsDone - lastCheckUnits;
+			lastCheckAt = at;
+			lastCheckUnits = unitsDone;
+			if (warnedAboutLongUnit || batchMs <= LONG_UNIT_MS) return;
+			warnedAboutLongUnit = true;
+			warn(`${unitsInBatch === 1 ? `One ${unit} (index ${String(unitsDone - 1)}) took ${batchMs.toFixed(0)}ms` : `A batch of ${String(unitsInBatch)} ${unit}s took ${batchMs.toFixed(0)}ms`}. A slice can never be shorter than that, so this still blocks the main thread. ${unit === "item" ? "Split the work inside processItem into smaller items, or move it to useDeferredTask and yield part-way through." : "Add more yield points, so each segment is shorter."} (development only)`);
+		},
+		sliceEnded(at, unitsDone) {
+			const sliceMs = at - sliceStartedAt;
+			const unitsInSlice = unitsDone - sliceStartUnits;
+			sliceStartedAt = at;
+			sliceStartUnits = unitsDone;
+			if (warnedAboutClockCost || batchSize > 1) return;
+			if (unitsInSlice < MIN_UNITS_TO_JUDGE || sliceMs <= 0) return;
+			const unitCostMs = sliceMs / unitsInSlice;
+			if (unitCostMs >= CLOCK_BOUND_UNIT_MS) return;
+			warnedAboutClockCost = true;
+			warn(`${unit}s are averaging ${(unitCostMs * 1e3).toFixed(2)}µs, so checking the clock after each one costs more than the work itself. Pass batchSize: ${String(suggestedBatchSize(unitCostMs))} to check once per batch instead. (development only)`);
+		},
+		resumed(at, unitsDone) {
+			rebase(at, unitsDone);
+		}
+	};
+}
+// src/core/scheduler.ts
+/** Default time slice: roughly the granularity React's own scheduler uses. */
+const DEFAULT_TIME_SLICE_MS = 5;
+/** True when `scheduler.yield()` is present on this runtime. */
+function supportsSchedulerYield() {
+	return typeof globalThis.scheduler?.yield === "function";
+}
+/** True when the `MessageChannel` constructor is present on this runtime. */
+function supportsMessageChannel() {
+	return typeof MessageChannel === "function";
+}
+/** True when `navigator.scheduling.isInputPending()` is present. */
+function supportsInputPending() {
+	return typeof globalThis.navigator?.scheduling?.isInputPending === "function";
+}
+/**
+* Resolves the input-pending probe once, for callers that would otherwise
+* run the feature detection on every item of a long task: walking
+* `navigator.scheduling.isInputPending` through optional calls is wasted
+* work a million times over. Returns a function that always answers
+* `false` where the API is missing, so callers need no second branch.
+*/
+function resolveInputPending() {
+	return supportsInputPending() ? isInputPending : returnsFalse;
+}
+function returnsFalse() {
+	return false;
+}
+/**
+* Best-effort read of whether the browser has pending input right now.
+* Returns `false` — never throws — when the API is unavailable or errors,
+* since the caller's fallback (a plain time budget) is always safe.
+*/
+function isInputPending() {
+	try {
+		return globalThis.navigator?.scheduling?.isInputPending?.() ?? false;
+	} catch {
+		return false;
+	}
+}
+/** Picks the best strategy this runtime actually supports. */
+function resolveYieldStrategy() {
+	if (supportsSchedulerYield()) return "scheduler-yield";
+	if (supportsMessageChannel()) return "message-channel";
+	return "set-timeout";
+}
+function yieldViaMessageChannel() {
+	return new Promise((resolve) => {
+		const channel = new MessageChannel();
+		channel.port1.onmessage = () => {
+			channel.port1.close();
+			resolve();
+		};
+		channel.port2.postMessage(null);
+	});
+}
+function yieldViaSetTimeout() {
+	return new Promise((resolve) => {
+		setTimeout(resolve, 0);
+	});
+}
+/**
+* Yields control back to the browser's main thread, resolving once the
+* browser has had a chance to handle any pending input, then resuming the
+* caller. Never rejects: a runtime that half-implements `scheduler.yield()`
+* (the property exists but the call throws, or the returned promise
+* rejects) falls through to the next strategy rather than propagating the
+* failure into unrelated application code.
+*/
+async function yieldToMain(options) {
+	const strategy = options?.strategy ?? resolveYieldStrategy();
+	if (strategy === "scheduler-yield") {
+		const schedulerGlobal = globalThis.scheduler;
+		if (typeof schedulerGlobal?.yield === "function") try {
+			await schedulerGlobal.yield();
+			return;
+		} catch {}
+		await (supportsMessageChannel() ? yieldViaMessageChannel() : yieldViaSetTimeout());
+		return;
+	}
+	if (strategy === "message-channel") {
+		if (supportsMessageChannel()) {
+			await yieldViaMessageChannel();
+			return;
+		}
+		await yieldViaSetTimeout();
+		return;
+	}
+	await yieldViaSetTimeout();
+}
+/** `performance.now()` when available, `Date.now()` otherwise. Never throws. */
+function now() {
+	try {
+		if (typeof performance !== "undefined" && typeof performance.now === "function") return performance.now();
+	} catch {}
+	return Date.now();
+}
+/**
+* A time slice of zero, a negative number or NaN is meaningless, so those
+* fall back to the default rather than producing a task that yields after
+* every item (or never).
+*/
+function normalizeTimeSliceMs(value) {
+	if (typeof value !== "number" || Number.isNaN(value) || value <= 0) return 5;
+	return value;
+}
+/**
+* Batch sizes are whole items, at least one. Anything else — a fraction,
+* zero, a negative, NaN — falls back to 1, the safe default.
+*/
+function normalizeBatchSize(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return 1;
+	return Math.floor(value);
+}
+/**
+* Whether the caller should yield right now: either the time slice has run
+* out, or the browser is reporting pending input (a stronger, earlier
+* signal than the clock — used only when the runtime exposes it).
+*/
+function shouldYieldNow(options) {
+	const timeSliceMs = options.timeSliceMs ?? 5;
+	if (now() - options.sliceStartedAt >= timeSliceMs) return true;
+	return isInputPending();
+}
+// src/core/chunk-scheduler.ts
+/**
+* `items[index]` for an index the caller has already bounds-checked.
+*
+* The loop below only ever indexes below `items.length`, but
+* `noUncheckedIndexedAccess` widens every index read to `T | undefined`,
+* and `T` may itself include `undefined` — so no runtime check can narrow
+* it. This states the invariant in one place instead of asserting at each
+* use, and compiles to a plain index read.
+*/
+function at(items, index) {
+	return items[index];
+}
+/**
+* Builds a one-shot, controllable scheduler that processes `items` through
+* `processItem`, yielding to the main thread on a time budget (and sooner,
+* if the browser reports pending input) so a large array never produces a
+* single long task.
+*
+* One-shot means exactly that: once the task reaches `done`, `cancelled` or
+* `error`, this instance is finished — start()/pause()/resume() on it are
+* no-ops from then on. To run another task, create another scheduler. For a
+* React hook, that falls out naturally: new deps → new effect → new
+* scheduler, which is the idiomatic React data-flow anyway.
+*/
+function createChunkScheduler(options) {
+	const { items, processItem, onItem, signal, yieldStrategy } = options;
+	const timeSliceMs = normalizeTimeSliceMs(options.timeSliceMs);
+	const batchSize = normalizeBatchSize(options.batchSize);
+	const collectResults = options.collectResults ?? true;
+	const total = items.length;
+	const inputPending = resolveInputPending();
+	const diagnostics = createDiagnostics("item", batchSize);
+	let machineState = initialChunkState;
+	let processed = 0;
+	let loopStarted = false;
+	let settledFlag = false;
+	const results = [];
+	let finalResults;
+	let snapshot = {
+		status: machineState.status,
+		processed,
+		total
+	};
+	let snapshotStale = false;
+	const listeners = /* @__PURE__ */ new Set();
+	let settleFn;
+	const settledPromise = new Promise((resolve) => {
+		settleFn = resolve;
+	});
+	let pauseResolve;
+	let pausePromise;
+	function waitForWake() {
+		pausePromise ??= new Promise((resolve) => {
+			pauseResolve = resolve;
+		});
+		return pausePromise;
+	}
+	function openGate() {
+		pauseResolve?.();
+		pauseResolve = void 0;
+		pausePromise = void 0;
+	}
+	function notify() {
+		for (const listener of listeners) listener();
+	}
+	function getSnapshot() {
+		if (snapshotStale) {
+			snapshotStale = false;
+			snapshot = {
+				status: machineState.status,
+				processed,
+				total,
+				...machineState.error !== void 0 ? { error: machineState.error } : {},
+				...finalResults !== void 0 ? { results: finalResults } : {}
+			};
+		}
+		return snapshot;
+	}
+	function dispatch(event) {
+		const next = transition(machineState, event);
+		const changed = next !== machineState;
+		if (changed) {
+			machineState = next;
+			snapshotStale = true;
+			notify();
+		}
+		return { changed };
+	}
+	function settle(result) {
+		/* v8 ignore next */
+		if (settledFlag) return;
+		settledFlag = true;
+		detachSignal();
+		settleFn(result);
+	}
+	/**
+	* Publishes the accumulated results exactly once, at the moment the task
+	* settles — not per item, and never as a second copy. Always called
+	* *before* the terminal status is announced, so the notification that
+	* reports `done` already carries the results: a subscriber can never
+	* observe one without the other.
+	*/
+	function publishResults() {
+		finalResults = results;
+		snapshotStale = true;
+		return finalResults;
+	}
+	function settleWith(status, published, error) {
+		settle(status === "error" ? {
+			status,
+			error,
+			results: published
+		} : {
+			status,
+			results: published
+		});
+	}
+	/**
+	* Settling as cancelled, for both places that can do it: the loop
+	* noticing, and cancel() on a task whose loop never ran. The CANCEL
+	* transition was announced earlier, before there were any results to
+	* carry, so this notifies again now that there are.
+	*/
+	function finishCancelled() {
+		settleWith("cancelled", publishResults());
+		notify();
+	}
+	function settleIfNeverStarted() {
+		const { status } = machineState;
+		if (loopStarted || !isTerminal(status)) return;
+		loopStarted = true;
+		finishCancelled();
+	}
+	function handleAbort() {
+		cancel();
+	}
+	function detachSignal() {
+		signal?.removeEventListener("abort", handleAbort);
+	}
+	if (signal?.aborted) dispatch({ type: "CANCEL" });
+	else signal?.addEventListener("abort", handleAbort);
+	async function runLoop() {
+		let sliceStartedAt = now();
+		let index = 0;
+		try {
+			while (index < total) {
+				const status = machineState.status;
+				if (status === "cancelled") break;
+				if (status === "paused") {
+					await waitForWake();
+					sliceStartedAt = now();
+					if (isDevelopment) diagnostics.resumed(sliceStartedAt, index);
+					continue;
+				}
+				const batchEnd = index + batchSize <= total ? index + batchSize : total;
+				while (index < batchEnd) {
+					const item = at(items, index);
+					const result = processItem(item, index);
+					if (collectResults) results.push(result);
+					processed = index + 1;
+					onItem?.(result, item, index);
+					index += 1;
+				}
+				snapshotStale = true;
+				const checkedAt = now();
+				if (isDevelopment) diagnostics.check(checkedAt, index);
+				if (checkedAt - sliceStartedAt >= timeSliceMs || inputPending()) {
+					if (isDevelopment) diagnostics.sliceEnded(checkedAt, index);
+					await yieldToMain(yieldStrategy !== void 0 ? { strategy: yieldStrategy } : void 0);
+					notify();
+					sliceStartedAt = now();
+					if (isDevelopment) diagnostics.resumed(sliceStartedAt, index);
+				}
+			}
+		} catch (error) {
+			const published = publishResults();
+			dispatch({
+				type: "ERROR",
+				error
+			});
+			settleWith("error", published, error);
+			return;
+		}
+		if (machineState.status === "cancelled") {
+			finishCancelled();
+			return;
+		}
+		const published = publishResults();
+		dispatch({ type: "COMPLETE" });
+		settleWith("done", published);
+	}
+	function start() {
+		dispatch({ type: "START" });
+		if (machineState.status === "processing" && !loopStarted) {
+			loopStarted = true;
+			runLoop();
+		}
+		settleIfNeverStarted();
+	}
+	function pause() {
+		dispatch({ type: "PAUSE" });
+	}
+	function resume() {
+		const { changed } = dispatch({ type: "RESUME" });
+		if (changed) openGate();
+	}
+	function cancel() {
+		dispatch({ type: "CANCEL" });
+		openGate();
+		settleIfNeverStarted();
+	}
+	return {
+		start,
+		pause,
+		resume,
+		cancel,
+		getSnapshot,
+		getResults: () => finalResults,
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		settled: settledPromise
+	};
+}
+// src/core/deferred-task.ts
+/**
+* The generator-driven sibling of `createChunkScheduler`, for heavy work
+* that isn't shaped like "one function applied to each item of an array".
+* Same state machine, same yield primitives, same one-shot-instance
+* contract — see that file's doc comment for the reasoning, which applies
+* here unchanged.
+*/
+function createDeferredTask(options) {
+	const { task, signal, yieldStrategy } = options;
+	const timeSliceMs = normalizeTimeSliceMs(options.timeSliceMs);
+	const batchSize = normalizeBatchSize(options.batchSize);
+	const inputPending = resolveInputPending();
+	const diagnostics = createDiagnostics("segment", batchSize);
+	let machineState = initialChunkState;
+	let loopStarted = false;
+	let settledFlag = false;
+	let settledValue;
+	let snapshot = { status: machineState.status };
+	let snapshotStale = false;
+	const listeners = /* @__PURE__ */ new Set();
+	let settleFn;
+	const settledPromise = new Promise((resolve) => {
+		settleFn = resolve;
+	});
+	let pauseResolve;
+	let pausePromise;
+	function waitForWake() {
+		pausePromise ??= new Promise((resolve) => {
+			pauseResolve = resolve;
+		});
+		return pausePromise;
+	}
+	function openGate() {
+		pauseResolve?.();
+		pauseResolve = void 0;
+		pausePromise = void 0;
+	}
+	function notify() {
+		for (const listener of listeners) listener();
+	}
+	function getSnapshot() {
+		if (snapshotStale) {
+			snapshotStale = false;
+			snapshot = {
+				status: machineState.status,
+				...machineState.error !== void 0 ? { error: machineState.error } : {},
+				...settledValue !== void 0 ? { value: settledValue } : {}
+			};
+		}
+		return snapshot;
+	}
+	function dispatch(event) {
+		const next = transition(machineState, event);
+		const changed = next !== machineState;
+		if (changed) {
+			machineState = next;
+			snapshotStale = true;
+			notify();
+		}
+		return { changed };
+	}
+	function settle(result) {
+		/* v8 ignore next */
+		if (settledFlag) return;
+		settledFlag = true;
+		detachSignal();
+		settleFn(result);
+	}
+	/**
+	* Publishes the returned value before the terminal status is announced,
+	* so the notification that reports `done` already carries it.
+	*/
+	function publishValue(resolvedValue) {
+		settledValue = resolvedValue;
+		snapshotStale = true;
+	}
+	function settleWith(status, resolvedValue, error) {
+		if (status === "done") {
+			settle({
+				status,
+				...resolvedValue !== void 0 ? { value: resolvedValue } : {}
+			});
+			return;
+		}
+		settle(status === "error" ? {
+			status,
+			error
+		} : { status });
+	}
+	/**
+	* Settling as cancelled, for both places that can do it. The CANCEL
+	* transition was announced earlier, so this notifies again now that the
+	* task has actually settled.
+	*/
+	function finishCancelled() {
+		settleWith("cancelled");
+		notify();
+	}
+	function settleIfNeverStarted() {
+		const { status } = machineState;
+		if (loopStarted || !isTerminal(status)) return;
+		loopStarted = true;
+		finishCancelled();
+	}
+	function handleAbort() {
+		cancel();
+	}
+	function detachSignal() {
+		signal?.removeEventListener("abort", handleAbort);
+	}
+	if (signal?.aborted) dispatch({ type: "CANCEL" });
+	else signal?.addEventListener("abort", handleAbort);
+	async function runLoop() {
+		let sliceStartedAt = now();
+		let segment = 0;
+		const generator = task();
+		let step = {
+			done: false,
+			value: void 0
+		};
+		try {
+			for (;;) {
+				const status = machineState.status;
+				if (status === "cancelled") {
+					generator.return(void 0);
+					break;
+				}
+				if (status === "paused") {
+					await waitForWake();
+					sliceStartedAt = now();
+					if (isDevelopment) diagnostics.resumed(sliceStartedAt, segment);
+					continue;
+				}
+				let done = false;
+				for (let inBatch = 0; inBatch < batchSize; inBatch++) {
+					step = generator.next();
+					segment += 1;
+					if (step.done) {
+						done = true;
+						break;
+					}
+				}
+				if (done) break;
+				const checkedAt = now();
+				if (isDevelopment) diagnostics.check(checkedAt, segment);
+				if (checkedAt - sliceStartedAt >= timeSliceMs || inputPending()) {
+					if (isDevelopment) diagnostics.sliceEnded(checkedAt, segment);
+					await yieldToMain(yieldStrategy !== void 0 ? { strategy: yieldStrategy } : void 0);
+					notify();
+					sliceStartedAt = now();
+					if (isDevelopment) diagnostics.resumed(sliceStartedAt, segment);
+				}
+			}
+		} catch (error) {
+			dispatch({
+				type: "ERROR",
+				error
+			});
+			settleWith("error", void 0, error);
+			return;
+		}
+		if (machineState.status === "cancelled") {
+			finishCancelled();
+			return;
+		}
+		/* v8 ignore next */
+		const returned = step.done ? step.value : void 0;
+		publishValue(returned);
+		dispatch({ type: "COMPLETE" });
+		settleWith("done", returned);
+	}
+	function start() {
+		dispatch({ type: "START" });
+		if (machineState.status === "processing" && !loopStarted) {
+			loopStarted = true;
+			runLoop();
+		}
+		settleIfNeverStarted();
+	}
+	function pause() {
+		dispatch({ type: "PAUSE" });
+	}
+	function resume() {
+		const { changed } = dispatch({ type: "RESUME" });
+		if (changed) openGate();
+	}
+	function cancel() {
+		dispatch({ type: "CANCEL" });
+		openGate();
+		settleIfNeverStarted();
+	}
+	return {
+		start,
+		pause,
+		resume,
+		cancel,
+		getSnapshot,
+		getValue: () => settledValue,
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		settled: settledPromise
+	};
+}
+export { now as a, supportsInputPending as c, yieldToMain as d, initialChunkState as f, isInputPending as i, supportsMessageChannel as l, transition as m, createChunkScheduler as n, resolveYieldStrategy as o, isTerminal as p, DEFAULT_TIME_SLICE_MS as r, shouldYieldNow as s, createDeferredTask as t, supportsSchedulerYield as u };
+
+//# sourceMappingURL=deferred-task-CwjZA3K-.js.map