react-inp-chunker 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { E as ChunkStatus, T as ChunkMachineState, a as DeferredTaskSnapshot, c as ChunkSchedulerOptions, i as DeferredTaskResult, l as ChunkSchedulerResult, m as YieldStrategy, n as DeferredTask, r as DeferredTaskOptions, s as ChunkScheduler, t as DeferredGenerator, u as ChunkSnapshot, w as ChunkEvent } from "./index-DShDP2VN.js";
+import { D as ChunkStatus, E as ChunkMachineState, T as ChunkEvent, a as DeferredTaskSnapshot, c as ChunkSchedulerOptions, d as SkippedChunkItem, h as YieldStrategy, i as DeferredTaskResult, l as ChunkSchedulerResult, n as DeferredTask, r as DeferredTaskOptions, s as ChunkScheduler, t as DeferredGenerator, u as ChunkSnapshot } from "./index-DuUMqnsA.js";
 interface UseChunkedTaskOptions<T, R> {
   /** Max ms of uninterrupted work before yielding. Default 5. */
   readonly timeSliceMs?: number;
@@ -24,14 +24,44 @@ interface UseChunkedTaskOptions<T, R> {
    * without paying for an array copy on every yield checkpoint.
    */
   readonly onItem?: (result: R, item: T, index: number) => void;
+  /**
+   * Called when `processItem` throws. Return `'skip'` to drop that item and
+   * keep going — it shows up in `skipped` — or `'abort'` to end the task as
+   * an error, carrying whatever was collected before the throw. Omitting
+   * this defaults to `'abort'`, so existing callers see no behavior change.
+   */
+  readonly onError?: (error: unknown, item: T, index: number) => 'skip' | 'abort';
+  /**
+   * Called every time a slice ends and the task is about to yield, with how
+   * long that slice ran and how many items are done so far. Ships in the
+   * production build, unlike this package's own dev-only diagnostics — wire
+   * it to your own telemetry to verify, on real traffic, that this task is
+   * actually staying under `timeSliceMs`.
+   */
+  readonly onSlice?: (durationMs: number, processed: number) => void;
+  /** Called right after each yield resolves and work is about to resume. Pairs with `onSlice`. */
+  readonly onYield?: () => void;
+  /**
+   * External cancellation source — aborting it is equivalent to calling
+   * `cancel()`, and its `reason` comes through on `reason` below, so a
+   * cancellation caused by the signal is distinguishable from a direct
+   * `cancel()` call. A new reference restarts the task the same way a new
+   * `items` array does, so memoize it (e.g. from a ref or a parent-owned
+   * `AbortController`) unless you mean to restart on every render.
+   */
+  readonly signal?: AbortSignal;
 }
-interface UseChunkedTaskState<R> {
-  readonly status: ChunkStatus;
+/** Fields every status shares, independent of the `status`/`results`/`error` narrowing below. */
+interface UseChunkedTaskShared {
   readonly processed: number;
   readonly total: number;
-  readonly error: unknown;
-  /** The full results array once the task has settled — `undefined` until then. */
-  readonly results: readonly R[] | undefined;
+  /** Items `onError` has skipped so far, growing live as skips happen. Empty when unused. */
+  readonly skipped: readonly SkippedChunkItem[];
+  /**
+   * The `signal` option's `reason`, present only when cancellation came
+   * from that signal aborting rather than a direct `cancel()` call.
+   */
+  readonly reason: unknown;
   readonly isIdle: boolean;
   readonly isProcessing: boolean;
   readonly isPaused: boolean;
@@ -43,6 +73,26 @@ interface UseChunkedTaskState<R> {
   readonly resume: () => void;
   readonly cancel: () => void;
 }
+/**
+ * Discriminated on `status`. Narrowing to `'done'` or `'cancelled'` narrows
+ * `results` to a defined array, no `=== undefined` check needed alongside
+ * `isDone`; narrowing to `'error'` narrows `error` to defined instead. The
+ * `is*` booleans above remain the simple way to branch when you only care
+ * about one status and don't need the narrowing.
+ */
+type UseChunkedTaskState<R> = UseChunkedTaskShared & ({
+  readonly status: Exclude<ChunkStatus, 'done' | 'cancelled' | 'error'>;
+  readonly results: undefined;
+  readonly error: undefined;
+} | {
+  readonly status: 'done' | 'cancelled';
+  readonly results: readonly R[];
+  readonly error: undefined;
+} | {
+  readonly status: 'error';
+  readonly results: readonly R[];
+  readonly error: unknown;
+});
 /**
  * Chunks a heavy, synchronous per-item computation over `items` so it never
  * blocks the main thread for longer than a time slice — the thing that
@@ -70,12 +120,32 @@ interface UseDeferredTaskOptions {
   readonly batchSize?: number;
   /** Start processing automatically when the task is (re)created. Default `true`. */
   readonly autoStart?: boolean;
+  /**
+   * Called every time a segment-batch ends and the task is about to yield,
+   * with how long that slice ran and how many segments are done so far.
+   * Ships in the production build — see the identical option on
+   * `useChunkedTask`/`createChunkScheduler` for why.
+   */
+  readonly onSlice?: (durationMs: number, segmentsDone: number) => void;
+  /** Called right after each yield resolves and work is about to resume. Pairs with `onSlice`. */
+  readonly onYield?: () => void;
+  /**
+   * External cancellation source — aborting it is equivalent to calling
+   * `cancel()`, and its `reason` comes through on `reason` below, so a
+   * cancellation caused by the signal is distinguishable from a direct
+   * `cancel()` call. A new reference restarts the task the same way a new
+   * entry in `deps` does, so memoize it unless you mean to restart on
+   * every render.
+   */
+  readonly signal?: AbortSignal;
 }
-interface UseDeferredTaskState<T> {
-  readonly status: ChunkStatus;
-  readonly error: unknown;
-  /** The returned value once the task settles with `done` — `undefined` until then. */
-  readonly value: T | undefined;
+/** Fields every status shares, independent of the `status`/`value`/`error` narrowing below. */
+interface UseDeferredTaskShared {
+  /**
+   * The `signal` option's `reason`, present only when cancellation came
+   * from that signal aborting rather than a direct `cancel()` call.
+   */
+  readonly reason: unknown;
   readonly isIdle: boolean;
   readonly isProcessing: boolean;
   readonly isPaused: boolean;
@@ -87,6 +157,25 @@ interface UseDeferredTaskState<T> {
   readonly resume: () => void;
   readonly cancel: () => void;
 }
+/**
+ * Discriminated on `status`. Narrowing to `'done'` narrows `value` to `T`
+ * itself — no `=== undefined` check needed alongside `isDone`, even when
+ * `T` allows `undefined` as a genuine return value. Narrowing to `'error'`
+ * narrows `error` to defined instead.
+ */
+type UseDeferredTaskState<T> = UseDeferredTaskShared & ({
+  readonly status: Exclude<ChunkStatus, 'done' | 'error'>;
+  readonly value: undefined;
+  readonly error: undefined;
+} | {
+  readonly status: 'done';
+  readonly value: T;
+  readonly error: undefined;
+} | {
+  readonly status: 'error';
+  readonly value: undefined;
+  readonly error: unknown;
+});
 /**
  * Runs an arbitrary heavy, synchronous generator function in chunks, so it
  * never produces a long task on its own. Where `useChunkedTask` chunks "one
@@ -99,5 +188,5 @@ interface UseDeferredTaskState<T> {
  * you would for `useMemo` or `useEffect`.
  */
 export declare function useDeferredTask<T>(task: () => DeferredGenerator<T>, deps: readonly unknown[], options?: UseDeferredTaskOptions): UseDeferredTaskState<T>;
-export type { ChunkEvent, ChunkMachineState, ChunkScheduler, ChunkSchedulerOptions, ChunkSchedulerResult, ChunkSnapshot, ChunkStatus, DeferredGenerator, DeferredTask, DeferredTaskOptions, DeferredTaskResult, DeferredTaskSnapshot, UseChunkedTaskOptions, UseChunkedTaskState, UseDeferredTaskOptions, UseDeferredTaskState, YieldStrategy };
+export type { ChunkEvent, ChunkMachineState, ChunkScheduler, ChunkSchedulerOptions, ChunkSchedulerResult, ChunkSnapshot, ChunkStatus, DeferredGenerator, DeferredTask, DeferredTaskOptions, DeferredTaskResult, DeferredTaskSnapshot, SkippedChunkItem, UseChunkedTaskOptions, UseChunkedTaskState, UseDeferredTaskOptions, UseDeferredTaskState, YieldStrategy };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/react/useChunkedTask.ts","../src/react/useDeferredTask.ts"],"mappings":";UAQiB,sBAAsB,GAAG;;WAE/B;;;;;;;WAOA;;;;;;WAMA;;WAEA;;;;;;;WAOA,UAAU,QAAQ,GAAG,MAAM,GAAG;;UAGxB,oBAAoB;WAC1B,QAAQ;WACR;WACA;WACA;;WAEA,kBAAkB;WAClB;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;;;;;;;;;;;;;;;;wBAoBK,eAAe,GAAG,GAChC,gBAAgB,KAChB,cAAc,MAAM,GAAG,kBAAkB,GACzC,UAAU,sBAAsB,GAAG,KAClC,oBAAoB;UC/DN;;WAEN;;;;;;WAMA;;WAEA;;UAGM,qBAAqB;WAC3B,QAAQ;WACR;;WAEA,OAAO;WACP;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;;;;;;;;;;;;wBAgBK,gBAAgB,GAC9B,YAAY,kBAAkB,IAC9B,0BACA,UAAU,yBACT,qBAAqB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/react/useChunkedTask.ts","../src/react/useDeferredTask.ts"],"mappings":";UAeiB,sBAAsB,GAAG;;WAE/B;;;;;;;WAOA;;;;;;WAMA;;WAEA;;;;;;;WAOA,UAAU,QAAQ,GAAG,MAAM,GAAG;;;;;;;WAO9B,WAAW,gBAAgB,MAAM,GAAG;;;;;;;;WAQpC,WAAW,oBAAoB;;WAE/B;;;;;;;;;WASA,SAAS;;;UAIV;WACC;WACA;;WAEA,kBAAkB;;;;;WAKlB;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;;;;;;;;KAUC,oBAAoB,KAAK;WAGpB,QAAQ,QAAQ;WAChB;WACA;;WAGA;WACA,kBAAkB;WAClB;;WAGA;WACA,kBAAkB;WAClB;;;;;;;;;;;;;;;;;wBAwBD,eAAe,GAAG,GAChC,gBAAgB,KAChB,cAAc,MAAM,GAAG,kBAAkB,GACzC,UAAU,sBAAsB,GAAG,KAClC,oBAAoB;UCjIN;;WAEN;;;;;;WAMA;;WAEA;;;;;;;WAOA,WAAW,oBAAoB;;WAE/B;;;;;;;;;WASA,SAAS;;;UAIV;;;;;WAKC;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;;;;;;;KASC,qBAAqB,KAAK;WAGrB,QAAQ,QAAQ;WAChB;WACA;;WAEA;WAAyB,OAAO;WAAY;;WAC5C;WAA0B;WAA2B;;;;;;;;;;;;;wBAkBtD,gBAAgB,GAC9B,YAAY,kBAAkB,IAC9B,0BACA,UAAU,yBACT,qBAAqB"}

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as createChunkScheduler, t as createDeferredTask } from "./deferred-task-CwjZA3K-.js";
+import { n as createChunkScheduler, t as createDeferredTask } from "./deferred-task-Cai4fF4m.js";
 import * as React from "react";
 import { useCallback, useEffect, useInsertionEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 // src/react/task-controller.ts
@@ -36,6 +36,8 @@ function useEffectEventFallback(callback) {
 }
 const useEffectEvent = React.useEffectEvent ?? useEffectEventFallback;
 // src/react/useChunkedTask.ts
+/** Stable empty array so a never-skipped task doesn't hand out a fresh `[]` every render. */
+const NO_SKIPPED = [];
 const IDLE_STATUS = "idle";
 /**
 * Chunks a heavy, synchronous per-item computation over `items` so it never
@@ -53,11 +55,18 @@ const IDLE_STATUS = "idle";
 * same as any other React dependency.
 */
 function useChunkedTask(items, processItem, options) {
-	const { timeSliceMs, batchSize, collectResults, autoStart = true, onItem } = options ?? {};
+	const { timeSliceMs, batchSize, collectResults, autoStart = true, onItem, onError, onSlice, onYield, signal } = options ?? {};
 	const stableProcessItem = useEffectEvent((item, index) => processItem(item, index));
 	const stableOnItem = useEffectEvent((result, item, index) => {
 		onItem?.(result, item, index);
 	});
+	const stableOnError = useEffectEvent((error, item, index) => onError?.(error, item, index) ?? "abort");
+	const stableOnSlice = useEffectEvent((durationMs, processed) => {
+		onSlice?.(durationMs, processed);
+	});
+	const stableOnYield = useEffectEvent(() => {
+		onYield?.();
+	});
 	const [controller] = useState(() => createTaskController());
 	const idleSnapshot = useMemo(() => ({
 		status: IDLE_STATUS,
@@ -70,9 +79,13 @@ function useChunkedTask(items, processItem, options) {
 			items,
 			processItem: stableProcessItem,
 			onItem: stableOnItem,
+			onError: stableOnError,
+			onSlice: stableOnSlice,
+			onYield: stableOnYield,
 			...timeSliceMs !== void 0 ? { timeSliceMs } : {},
 			...batchSize !== void 0 ? { batchSize } : {},
-			...collectResults !== void 0 ? { collectResults } : {}
+			...collectResults !== void 0 ? { collectResults } : {},
+			...signal !== void 0 ? { signal } : {}
 		});
 		controller.replace(scheduler);
 		if (autoStart) scheduler.start();
@@ -86,6 +99,7 @@ function useChunkedTask(items, processItem, options) {
 		batchSize,
 		collectResults,
 		autoStart,
+		signal,
 		controller
 	]);
 	const start = useCallback(() => controller.getCurrent()?.start(), [controller]);
@@ -98,6 +112,8 @@ function useChunkedTask(items, processItem, options) {
 		total: snapshot.total,
 		error: snapshot.error,
 		results: snapshot.results,
+		skipped: snapshot.skipped ?? NO_SKIPPED,
+		reason: snapshot.reason,
 		isIdle: snapshot.status === "idle",
 		isProcessing: snapshot.status === "processing",
 		isPaused: snapshot.status === "paused",
@@ -124,15 +140,24 @@ const IDLE_SNAPSHOT = { status: "idle" };
 * you would for `useMemo` or `useEffect`.
 */
 function useDeferredTask(task, deps, options) {
-	const { timeSliceMs, batchSize, autoStart = true } = options ?? {};
+	const { timeSliceMs, batchSize, autoStart = true, onSlice, onYield, signal } = options ?? {};
 	const stableTask = useEffectEvent(() => task());
+	const stableOnSlice = useEffectEvent((durationMs, segmentsDone) => {
+		onSlice?.(durationMs, segmentsDone);
+	});
+	const stableOnYield = useEffectEvent(() => {
+		onYield?.();
+	});
 	const [controller] = useState(() => createTaskController());
 	const snapshot = useSyncExternalStore(controller.subscribe, () => controller.getSnapshot() ?? IDLE_SNAPSHOT, () => IDLE_SNAPSHOT);
 	useEffect(() => {
 		const deferredTask = createDeferredTask({
 			task: stableTask,
+			onSlice: stableOnSlice,
+			onYield: stableOnYield,
 			...timeSliceMs !== void 0 ? { timeSliceMs } : {},
-			...batchSize !== void 0 ? { batchSize } : {}
+			...batchSize !== void 0 ? { batchSize } : {},
+			...signal !== void 0 ? { signal } : {}
 		});
 		controller.replace(deferredTask);
 		if (autoStart) deferredTask.start();
@@ -145,6 +170,7 @@ function useDeferredTask(task, deps, options) {
 		timeSliceMs,
 		batchSize,
 		autoStart,
+		signal,
 		controller
 	]);
 	const start = useCallback(() => controller.getCurrent()?.start(), [controller]);
@@ -155,6 +181,7 @@ function useDeferredTask(task, deps, options) {
 		status: snapshot.status,
 		error: snapshot.error,
 		value: snapshot.value,
+		reason: snapshot.reason,
 		isIdle: snapshot.status === "idle",
 		isProcessing: snapshot.status === "processing",
 		isPaused: snapshot.status === "paused",

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/react/task-controller.ts","../src/react/use-effect-event.ts","../src/react/useChunkedTask.ts","../src/react/useDeferredTask.ts"],"sourcesContent":["/**\n * The glue between a task handle (`ChunkScheduler<R>`, `DeferredTask<T>` —\n * anything with `subscribe`/`getSnapshot`) recreated from scratch whenever a\n * hook's deps change, inside an effect, and `useSyncExternalStore`, which\n * wants one stable `subscribe` function for a component's whole lifetime.\n *\n * `useSyncExternalStore` resubscribes whenever the `subscribe` function\n * identity changes — fine for correctness, but it means the naive approach\n * (pass the current task's own `.subscribe` directly) either churns\n * subscriptions every render or, worse, drifts: the component keeps\n * `subscribe`d to whichever task was current when it last resubscribed, not\n * necessarily the one `getSnapshot` is reading from after a swap.\n *\n * A controller sidesteps that: it's created once per hook instance (lazy\n * `useState` initializer in the hook, so it's stable without touching a\n * ref), hands `useSyncExternalStore` a `subscribe`/`getSnapshot` pair that\n * never change identity, and internally forwards to whichever task is\n * \"current\" — re-pointing itself via `replace()` every time the effect\n * swaps in a new one. Generic over the task shape so both `useChunkedTask`\n * and `useDeferredTask` share this one implementation.\n *\n * Every property below is an arrow function, deliberately — not method\n * shorthand — so none of them close over `this`, and `controller.subscribe`\n * can be handed to `useSyncExternalStore` directly as a plain function\n * reference without an unbound-method footgun.\n */\nexport interface SubscribableTask<Snapshot> {\n  subscribe(listener: () => void): () => void;\n  getSnapshot(): Snapshot;\n}\n\nexport interface TaskController<Task extends SubscribableTask<unknown>> {\n  subscribe: (listener: () => void) => () => void;\n  getSnapshot: () => ReturnType<Task['getSnapshot']> | undefined;\n  getCurrent: () => Task | null;\n  /** Swaps in a new task (or none), detaching from the previous one first. */\n  replace: (task: Task | null) => void;\n}\n\nexport function createTaskController<\n  Task extends SubscribableTask<unknown>,\n>(): TaskController<Task> {\n  let current: Task | null = null;\n  let detachFromCurrent: (() => void) | undefined;\n  const listeners = new Set<() => void>();\n\n  const notify = (): void => {\n    for (const listener of listeners) listener();\n  };\n\n  return {\n    subscribe: (listener) => {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    getSnapshot: () =>\n      current?.getSnapshot() as ReturnType<Task['getSnapshot']> | undefined,\n    getCurrent: () => current,\n    replace: (task) => {\n      detachFromCurrent?.();\n      current = task;\n      detachFromCurrent = task?.subscribe(notify);\n      notify();\n    },\n  };\n}\n","import * as React from 'react';\nimport { useCallback, useInsertionEffect, useRef } from 'react';\n\n/**\n * `useEffectEvent` only became a stable React export in 19.2. On React 18\n * and 19.0–19.1 it doesn't exist at all — and a named\n * `import { useEffectEvent } from 'react'` then fails outright: at module\n * link time under Node ESM (\"Named export 'useEffectEvent' not found\"), or\n * as \"useEffectEvent is not a function\" on first render in a bundler. Both\n * versions are inside this package's declared peer range, so that has to\n * work, not just type-check.\n *\n * So the native hook is read as a property of the namespace object, where a\n * missing export is plain `undefined` rather than a link error, and used\n * whenever the running React has it. Otherwise the fallback keeps the same\n * contract: a stable function identity that always calls the latest\n * callback. The latest callback is committed from an insertion effect —\n * after render, before any layout or passive effect of the same commit can\n * observe it — so effects always see the current closure, without the\n * render-time ref mutation the React Compiler rejects.\n */\ntype EffectEventHook = <Args extends readonly unknown[], Return>(\n  callback: (...args: Args) => Return,\n) => (...args: Args) => Return;\n\nexport function useEffectEventFallback<Args extends readonly unknown[], Return>(\n  callback: (...args: Args) => Return,\n): (...args: Args) => Return {\n  const latest = useRef(callback);\n  useInsertionEffect(() => {\n    latest.current = callback;\n  });\n  return useCallback((...args: Args) => latest.current(...args), []);\n}\n\n// Through `unknown` on purpose: React 18's types have no `useEffectEvent`\n// member at all, so a direct assertion wouldn't compile against them.\nconst nativeUseEffectEvent = (\n  React as unknown as { readonly useEffectEvent?: EffectEventHook }\n).useEffectEvent;\n\nexport const useEffectEvent: EffectEventHook =\n  nativeUseEffectEvent ?? useEffectEventFallback;\n","import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react';\n\nimport type { ChunkStatus } from '../core/chunk-machine.js';\nimport { createChunkScheduler } from '../core/chunk-scheduler.js';\nimport type { ChunkScheduler, ChunkSnapshot } from '../core/chunk-scheduler.js';\nimport { createTaskController } from './task-controller.js';\nimport { useEffectEvent } from './use-effect-event.js';\n\nexport interface UseChunkedTaskOptions<T, R> {\n  /** Max ms of uninterrupted work before yielding. Default 5. */\n  readonly timeSliceMs?: number;\n  /**\n   * Items to process between clock checks. Default 1. Raise it only for\n   * items measured in nanoseconds, where reading the clock costs more than\n   * the work; a slice can then run up to `batchSize` items past its budget.\n   * See the `batchSize` note on `createChunkScheduler`.\n   */\n  readonly batchSize?: number;\n  /**\n   * Keep every result in `results`. Default true. Set false when results\n   * are consumed through `onItem`, to avoid retaining one result per item;\n   * `results` is then an empty array once the task settles.\n   */\n  readonly collectResults?: boolean;\n  /** Start processing automatically when the task is (re)created. Default `true`. */\n  readonly autoStart?: boolean;\n  /**\n   * Called synchronously after each item is processed. This is the cheap\n   * way to consume results incrementally while the task is still running —\n   * write into a ref-backed buffer, a canvas, a chart, whatever you need —\n   * without paying for an array copy on every yield checkpoint.\n   */\n  readonly onItem?: (result: R, item: T, index: number) => void;\n}\n\nexport interface UseChunkedTaskState<R> {\n  readonly status: ChunkStatus;\n  readonly processed: number;\n  readonly total: number;\n  readonly error: unknown;\n  /** The full results array once the task has settled — `undefined` until then. */\n  readonly results: readonly R[] | undefined;\n  readonly isIdle: boolean;\n  readonly isProcessing: boolean;\n  readonly isPaused: boolean;\n  readonly isDone: boolean;\n  readonly isCancelled: boolean;\n  readonly isError: boolean;\n  readonly start: () => void;\n  readonly pause: () => void;\n  readonly resume: () => void;\n  readonly cancel: () => void;\n}\n\nconst IDLE_STATUS: ChunkStatus = 'idle';\n\n/**\n * Chunks a heavy, synchronous per-item computation over `items` so it never\n * blocks the main thread for longer than a time slice — the thing that\n * costs you Interaction to Next Paint. Starts automatically by default;\n * pass `{ autoStart: false }` to wait for an explicit `start()` call (e.g.\n * behind a button).\n *\n * `processItem` and `onItem` can be fresh closures every render — the hook\n * always calls the latest version (via `useEffectEvent`) without that\n * causing the task to restart. What *does* restart the task is `items`\n * changing identity (a new array reference), or `timeSliceMs`/`autoStart`\n * changing. That's deliberate: a new `items` array means new work, and\n * memoizing it when you don't want that is the caller's call to make, the\n * same as any other React dependency.\n */\nexport function useChunkedTask<T, R>(\n  items: readonly T[],\n  processItem: (item: T, index: number) => R,\n  options?: UseChunkedTaskOptions<T, R>,\n): UseChunkedTaskState<R> {\n  const {\n    timeSliceMs,\n    batchSize,\n    collectResults,\n    autoStart = true,\n    onItem,\n  } = options ?? {};\n\n  // Stable identity, always runs the latest processItem/onItem passed this\n  // render — the React-Compiler-safe replacement for a ref mutated during\n  // render. Effect Events are meant to be called from inside an effect\n  // (here: from the scheduler's async loop, which the effect below owns),\n  // never during render itself.\n  const stableProcessItem = useEffectEvent((item: T, index: number) =>\n    processItem(item, index),\n  );\n  const stableOnItem = useEffectEvent((result: R, item: T, index: number) => {\n    onItem?.(result, item, index);\n  });\n\n  // Created once, lazily, via useState rather than a ref mutated during\n  // render — the controller itself is inert (no subscriptions, no timers)\n  // until an effect calls replace() on it, so a discarded render (double\n  // render in dev, or one React throws away) never leaks anything.\n  const [controller] = useState(() => createTaskController<ChunkScheduler<R>>());\n\n  // What getSnapshot() reports before the effect below has ever run —\n  // including during SSR, where effects never run at all.\n  const idleSnapshot = useMemo<ChunkSnapshot<R>>(\n    () => ({ status: IDLE_STATUS, processed: 0, total: items.length }),\n    [items.length],\n  );\n\n  const snapshot = useSyncExternalStore(\n    controller.subscribe,\n    () => controller.getSnapshot() ?? idleSnapshot,\n    () => idleSnapshot,\n  );\n\n  useEffect(() => {\n    const scheduler = createChunkScheduler<T, R>({\n      items,\n      processItem: stableProcessItem,\n      onItem: stableOnItem,\n      ...(timeSliceMs !== undefined ? { timeSliceMs } : {}),\n      ...(batchSize !== undefined ? { batchSize } : {}),\n      ...(collectResults !== undefined ? { collectResults } : {}),\n    });\n    controller.replace(scheduler);\n    if (autoStart) scheduler.start();\n\n    return () => {\n      // Safe even if the task already finished on its own — cancel() on a\n      // terminal scheduler is a documented no-op, not an error.\n      scheduler.cancel();\n      controller.replace(null);\n    };\n    // stableProcessItem/stableOnItem are Effect Events: stable by\n    // construction, intentionally excluded from the reactive dependency set\n    // (that's the whole point of useEffectEvent) rather than omitted by\n    // oversight.\n  }, [items, timeSliceMs, batchSize, collectResults, autoStart, controller]);\n\n  const start = useCallback(() => controller.getCurrent()?.start(), [controller]);\n  const pause = useCallback(() => controller.getCurrent()?.pause(), [controller]);\n  const resume = useCallback(() => controller.getCurrent()?.resume(), [controller]);\n  const cancel = useCallback(() => controller.getCurrent()?.cancel(), [controller]);\n\n  return {\n    status: snapshot.status,\n    processed: snapshot.processed,\n    total: snapshot.total,\n    error: snapshot.error,\n    // From the snapshot, not a direct read of the scheduler: the engine\n    // publishes results before it announces a terminal status, so the two\n    // always arrive together and a concurrent render can never tear them\n    // apart.\n    results: snapshot.results,\n    isIdle: snapshot.status === 'idle',\n    isProcessing: snapshot.status === 'processing',\n    isPaused: snapshot.status === 'paused',\n    isDone: snapshot.status === 'done',\n    isCancelled: snapshot.status === 'cancelled',\n    isError: snapshot.status === 'error',\n    start,\n    pause,\n    resume,\n    cancel,\n  };\n}\n","import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';\n\nimport type { ChunkStatus } from '../core/chunk-machine.js';\nimport { createDeferredTask } from '../core/deferred-task.js';\nimport type {\n  DeferredGenerator,\n  DeferredTask,\n  DeferredTaskSnapshot,\n} from '../core/deferred-task.js';\nimport { createTaskController } from './task-controller.js';\nimport { useEffectEvent } from './use-effect-event.js';\n\nexport interface UseDeferredTaskOptions {\n  /** Max ms of uninterrupted work before yielding. Default 5. */\n  readonly timeSliceMs?: number;\n  /**\n   * Generator segments to run between clock checks. Default 1. Raise it\n   * only for segments measured in nanoseconds; a slice can then run up to\n   * `batchSize` segments past its budget.\n   */\n  readonly batchSize?: number;\n  /** Start processing automatically when the task is (re)created. Default `true`. */\n  readonly autoStart?: boolean;\n}\n\nexport interface UseDeferredTaskState<T> {\n  readonly status: ChunkStatus;\n  readonly error: unknown;\n  /** The returned value once the task settles with `done` — `undefined` until then. */\n  readonly value: T | undefined;\n  readonly isIdle: boolean;\n  readonly isProcessing: boolean;\n  readonly isPaused: boolean;\n  readonly isDone: boolean;\n  readonly isCancelled: boolean;\n  readonly isError: boolean;\n  readonly start: () => void;\n  readonly pause: () => void;\n  readonly resume: () => void;\n  readonly cancel: () => void;\n}\n\nconst IDLE_SNAPSHOT: DeferredTaskSnapshot<never> = { status: 'idle' };\n\n/**\n * Runs an arbitrary heavy, synchronous generator function in chunks, so it\n * never produces a long task on its own. Where `useChunkedTask` chunks \"one\n * function applied to every item of an array\" automatically, this hook\n * leaves the chunk boundaries to you — put `yield` wherever your function\n * can safely pause (see `DeferredGenerator`'s doc comment for an example).\n *\n * `task` is only called when the effect (re)creates the underlying task, not\n * on every render — list whatever it closes over in `deps`, the same way\n * you would for `useMemo` or `useEffect`.\n */\nexport function useDeferredTask<T>(\n  task: () => DeferredGenerator<T>,\n  deps: readonly unknown[],\n  options?: UseDeferredTaskOptions,\n): UseDeferredTaskState<T> {\n  const { timeSliceMs, batchSize, autoStart = true } = options ?? {};\n\n  // Stable identity, always runs the latest `task` passed this render —\n  // see useChunkedTask.ts for why this is useEffectEvent rather than a ref\n  // mutated during render.\n  const stableTask = useEffectEvent(() => task());\n\n  const [controller] = useState(() => createTaskController<DeferredTask<T>>());\n\n  const snapshot = useSyncExternalStore(\n    controller.subscribe,\n    () => controller.getSnapshot() ?? IDLE_SNAPSHOT,\n    () => IDLE_SNAPSHOT,\n  );\n\n  useEffect(\n    () => {\n      const deferredTask = createDeferredTask<T>({\n        task: stableTask,\n        ...(timeSliceMs !== undefined ? { timeSliceMs } : {}),\n        ...(batchSize !== undefined ? { batchSize } : {}),\n      });\n      controller.replace(deferredTask);\n      if (autoStart) deferredTask.start();\n\n      return () => {\n        deferredTask.cancel();\n        controller.replace(null);\n      };\n    },\n    // `deps` plays the role `items` plays for useChunkedTask: it's the\n    // caller's declaration of \"this is new work\". `stableTask` is an Effect\n    // Event — stable by construction, intentionally excluded from the\n    // reactive dependency set rather than omitted by oversight. `deps` is a\n    // caller-supplied array, the same pattern (and the same reason it can't\n    // be statically verified) as useMemo/useEffect's own deps parameter.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [...deps, timeSliceMs, batchSize, autoStart, controller],\n  );\n\n  const start = useCallback(() => controller.getCurrent()?.start(), [controller]);\n  const pause = useCallback(() => controller.getCurrent()?.pause(), [controller]);\n  const resume = useCallback(() => controller.getCurrent()?.resume(), [controller]);\n  const cancel = useCallback(() => controller.getCurrent()?.cancel(), [controller]);\n\n  return {\n    status: snapshot.status,\n    error: snapshot.error,\n    // From the snapshot: the engine publishes the value before it\n    // announces `done`, so a concurrent render can never see one without\n    // the other. See useChunkedTask.ts.\n    value: snapshot.value,\n    isIdle: snapshot.status === 'idle',\n    isProcessing: snapshot.status === 'processing',\n    isPaused: snapshot.status === 'paused',\n    isDone: snapshot.status === 'done',\n    isCancelled: snapshot.status === 'cancelled',\n    isError: snapshot.status === 'error',\n    start,\n    pause,\n    resume,\n    cancel,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/react/task-controller.ts","../src/react/use-effect-event.ts","../src/react/useChunkedTask.ts","../src/react/useDeferredTask.ts"],"sourcesContent":["/**\n * The glue between a task handle (`ChunkScheduler<R>`, `DeferredTask<T>` —\n * anything with `subscribe`/`getSnapshot`) recreated from scratch whenever a\n * hook's deps change, inside an effect, and `useSyncExternalStore`, which\n * wants one stable `subscribe` function for a component's whole lifetime.\n *\n * `useSyncExternalStore` resubscribes whenever the `subscribe` function\n * identity changes — fine for correctness, but it means the naive approach\n * (pass the current task's own `.subscribe` directly) either churns\n * subscriptions every render or, worse, drifts: the component keeps\n * `subscribe`d to whichever task was current when it last resubscribed, not\n * necessarily the one `getSnapshot` is reading from after a swap.\n *\n * A controller sidesteps that: it's created once per hook instance (lazy\n * `useState` initializer in the hook, so it's stable without touching a\n * ref), hands `useSyncExternalStore` a `subscribe`/`getSnapshot` pair that\n * never change identity, and internally forwards to whichever task is\n * \"current\" — re-pointing itself via `replace()` every time the effect\n * swaps in a new one. Generic over the task shape so both `useChunkedTask`\n * and `useDeferredTask` share this one implementation.\n *\n * Every property below is an arrow function, deliberately — not method\n * shorthand — so none of them close over `this`, and `controller.subscribe`\n * can be handed to `useSyncExternalStore` directly as a plain function\n * reference without an unbound-method footgun.\n */\nexport interface SubscribableTask<Snapshot> {\n  subscribe(listener: () => void): () => void;\n  getSnapshot(): Snapshot;\n}\n\nexport interface TaskController<Task extends SubscribableTask<unknown>> {\n  subscribe: (listener: () => void) => () => void;\n  getSnapshot: () => ReturnType<Task['getSnapshot']> | undefined;\n  getCurrent: () => Task | null;\n  /** Swaps in a new task (or none), detaching from the previous one first. */\n  replace: (task: Task | null) => void;\n}\n\nexport function createTaskController<\n  Task extends SubscribableTask<unknown>,\n>(): TaskController<Task> {\n  let current: Task | null = null;\n  let detachFromCurrent: (() => void) | undefined;\n  const listeners = new Set<() => void>();\n\n  const notify = (): void => {\n    for (const listener of listeners) listener();\n  };\n\n  return {\n    subscribe: (listener) => {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    getSnapshot: () =>\n      current?.getSnapshot() as ReturnType<Task['getSnapshot']> | undefined,\n    getCurrent: () => current,\n    replace: (task) => {\n      detachFromCurrent?.();\n      current = task;\n      detachFromCurrent = task?.subscribe(notify);\n      notify();\n    },\n  };\n}\n","import * as React from 'react';\nimport { useCallback, useInsertionEffect, useRef } from 'react';\n\n/**\n * `useEffectEvent` only became a stable React export in 19.2. On React 18\n * and 19.0–19.1 it doesn't exist at all — and a named\n * `import { useEffectEvent } from 'react'` then fails outright: at module\n * link time under Node ESM (\"Named export 'useEffectEvent' not found\"), or\n * as \"useEffectEvent is not a function\" on first render in a bundler. Both\n * versions are inside this package's declared peer range, so that has to\n * work, not just type-check.\n *\n * So the native hook is read as a property of the namespace object, where a\n * missing export is plain `undefined` rather than a link error, and used\n * whenever the running React has it. Otherwise the fallback keeps the same\n * contract: a stable function identity that always calls the latest\n * callback. The latest callback is committed from an insertion effect —\n * after render, before any layout or passive effect of the same commit can\n * observe it — so effects always see the current closure, without the\n * render-time ref mutation the React Compiler rejects.\n */\ntype EffectEventHook = <Args extends readonly unknown[], Return>(\n  callback: (...args: Args) => Return,\n) => (...args: Args) => Return;\n\nexport function useEffectEventFallback<Args extends readonly unknown[], Return>(\n  callback: (...args: Args) => Return,\n): (...args: Args) => Return {\n  const latest = useRef(callback);\n  useInsertionEffect(() => {\n    latest.current = callback;\n  });\n  return useCallback((...args: Args) => latest.current(...args), []);\n}\n\n// Through `unknown` on purpose: React 18's types have no `useEffectEvent`\n// member at all, so a direct assertion wouldn't compile against them.\nconst nativeUseEffectEvent = (\n  React as unknown as { readonly useEffectEvent?: EffectEventHook }\n).useEffectEvent;\n\nexport const useEffectEvent: EffectEventHook =\n  nativeUseEffectEvent ?? useEffectEventFallback;\n","import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react';\n\nimport type { ChunkStatus } from '../core/chunk-machine.js';\nimport { createChunkScheduler } from '../core/chunk-scheduler.js';\nimport type {\n  ChunkScheduler,\n  ChunkSnapshot,\n  SkippedChunkItem,\n} from '../core/chunk-scheduler.js';\nimport { createTaskController } from './task-controller.js';\nimport { useEffectEvent } from './use-effect-event.js';\n\n/** Stable empty array so a never-skipped task doesn't hand out a fresh `[]` every render. */\nconst NO_SKIPPED: readonly SkippedChunkItem[] = [];\n\nexport interface UseChunkedTaskOptions<T, R> {\n  /** Max ms of uninterrupted work before yielding. Default 5. */\n  readonly timeSliceMs?: number;\n  /**\n   * Items to process between clock checks. Default 1. Raise it only for\n   * items measured in nanoseconds, where reading the clock costs more than\n   * the work; a slice can then run up to `batchSize` items past its budget.\n   * See the `batchSize` note on `createChunkScheduler`.\n   */\n  readonly batchSize?: number;\n  /**\n   * Keep every result in `results`. Default true. Set false when results\n   * are consumed through `onItem`, to avoid retaining one result per item;\n   * `results` is then an empty array once the task settles.\n   */\n  readonly collectResults?: boolean;\n  /** Start processing automatically when the task is (re)created. Default `true`. */\n  readonly autoStart?: boolean;\n  /**\n   * Called synchronously after each item is processed. This is the cheap\n   * way to consume results incrementally while the task is still running —\n   * write into a ref-backed buffer, a canvas, a chart, whatever you need —\n   * without paying for an array copy on every yield checkpoint.\n   */\n  readonly onItem?: (result: R, item: T, index: number) => void;\n  /**\n   * Called when `processItem` throws. Return `'skip'` to drop that item and\n   * keep going — it shows up in `skipped` — or `'abort'` to end the task as\n   * an error, carrying whatever was collected before the throw. Omitting\n   * this defaults to `'abort'`, so existing callers see no behavior change.\n   */\n  readonly onError?: (error: unknown, item: T, index: number) => 'skip' | 'abort';\n  /**\n   * Called every time a slice ends and the task is about to yield, with how\n   * long that slice ran and how many items are done so far. Ships in the\n   * production build, unlike this package's own dev-only diagnostics — wire\n   * it to your own telemetry to verify, on real traffic, that this task is\n   * actually staying under `timeSliceMs`.\n   */\n  readonly onSlice?: (durationMs: number, processed: number) => void;\n  /** Called right after each yield resolves and work is about to resume. Pairs with `onSlice`. */\n  readonly onYield?: () => void;\n  /**\n   * External cancellation source — aborting it is equivalent to calling\n   * `cancel()`, and its `reason` comes through on `reason` below, so a\n   * cancellation caused by the signal is distinguishable from a direct\n   * `cancel()` call. A new reference restarts the task the same way a new\n   * `items` array does, so memoize it (e.g. from a ref or a parent-owned\n   * `AbortController`) unless you mean to restart on every render.\n   */\n  readonly signal?: AbortSignal;\n}\n\n/** Fields every status shares, independent of the `status`/`results`/`error` narrowing below. */\ninterface UseChunkedTaskShared {\n  readonly processed: number;\n  readonly total: number;\n  /** Items `onError` has skipped so far, growing live as skips happen. Empty when unused. */\n  readonly skipped: readonly SkippedChunkItem[];\n  /**\n   * The `signal` option's `reason`, present only when cancellation came\n   * from that signal aborting rather than a direct `cancel()` call.\n   */\n  readonly reason: unknown;\n  readonly isIdle: boolean;\n  readonly isProcessing: boolean;\n  readonly isPaused: boolean;\n  readonly isDone: boolean;\n  readonly isCancelled: boolean;\n  readonly isError: boolean;\n  readonly start: () => void;\n  readonly pause: () => void;\n  readonly resume: () => void;\n  readonly cancel: () => void;\n}\n\n/**\n * Discriminated on `status`. Narrowing to `'done'` or `'cancelled'` narrows\n * `results` to a defined array, no `=== undefined` check needed alongside\n * `isDone`; narrowing to `'error'` narrows `error` to defined instead. The\n * `is*` booleans above remain the simple way to branch when you only care\n * about one status and don't need the narrowing.\n */\nexport type UseChunkedTaskState<R> = UseChunkedTaskShared &\n  (\n    | {\n        readonly status: Exclude<ChunkStatus, 'done' | 'cancelled' | 'error'>;\n        readonly results: undefined;\n        readonly error: undefined;\n      }\n    | {\n        readonly status: 'done' | 'cancelled';\n        readonly results: readonly R[];\n        readonly error: undefined;\n      }\n    | {\n        readonly status: 'error';\n        readonly results: readonly R[];\n        readonly error: unknown;\n      }\n  );\n\n// Narrowed to the literal, not widened to `ChunkStatus`, so the object\n// literal below satisfies the discriminated `ChunkSnapshot` union on its\n// own merits — no assertion needed for a status this function knows for sure.\nconst IDLE_STATUS = 'idle';\n\n/**\n * Chunks a heavy, synchronous per-item computation over `items` so it never\n * blocks the main thread for longer than a time slice — the thing that\n * costs you Interaction to Next Paint. Starts automatically by default;\n * pass `{ autoStart: false }` to wait for an explicit `start()` call (e.g.\n * behind a button).\n *\n * `processItem` and `onItem` can be fresh closures every render — the hook\n * always calls the latest version (via `useEffectEvent`) without that\n * causing the task to restart. What *does* restart the task is `items`\n * changing identity (a new array reference), or `timeSliceMs`/`autoStart`\n * changing. That's deliberate: a new `items` array means new work, and\n * memoizing it when you don't want that is the caller's call to make, the\n * same as any other React dependency.\n */\nexport function useChunkedTask<T, R>(\n  items: readonly T[],\n  processItem: (item: T, index: number) => R,\n  options?: UseChunkedTaskOptions<T, R>,\n): UseChunkedTaskState<R> {\n  const {\n    timeSliceMs,\n    batchSize,\n    collectResults,\n    autoStart = true,\n    onItem,\n    onError,\n    onSlice,\n    onYield,\n    signal,\n  } = options ?? {};\n\n  // Stable identity, always runs the latest processItem/onItem passed this\n  // render — the React-Compiler-safe replacement for a ref mutated during\n  // render. Effect Events are meant to be called from inside an effect\n  // (here: from the scheduler's async loop, which the effect below owns),\n  // never during render itself.\n  const stableProcessItem = useEffectEvent((item: T, index: number) =>\n    processItem(item, index),\n  );\n  const stableOnItem = useEffectEvent((result: R, item: T, index: number) => {\n    onItem?.(result, item, index);\n  });\n  const stableOnError = useEffectEvent(\n    (error: unknown, item: T, index: number): 'skip' | 'abort' =>\n      onError?.(error, item, index) ?? 'abort',\n  );\n  const stableOnSlice = useEffectEvent((durationMs: number, processed: number) => {\n    onSlice?.(durationMs, processed);\n  });\n  const stableOnYield = useEffectEvent(() => {\n    onYield?.();\n  });\n\n  // Created once, lazily, via useState rather than a ref mutated during\n  // render — the controller itself is inert (no subscriptions, no timers)\n  // until an effect calls replace() on it, so a discarded render (double\n  // render in dev, or one React throws away) never leaks anything.\n  const [controller] = useState(() => createTaskController<ChunkScheduler<R>>());\n\n  // What getSnapshot() reports before the effect below has ever run —\n  // including during SSR, where effects never run at all.\n  const idleSnapshot = useMemo<ChunkSnapshot<R>>(\n    () => ({ status: IDLE_STATUS, processed: 0, total: items.length }),\n    [items.length],\n  );\n\n  const snapshot = useSyncExternalStore(\n    controller.subscribe,\n    () => controller.getSnapshot() ?? idleSnapshot,\n    () => idleSnapshot,\n  );\n\n  useEffect(() => {\n    const scheduler = createChunkScheduler<T, R>({\n      items,\n      processItem: stableProcessItem,\n      onItem: stableOnItem,\n      onError: stableOnError,\n      onSlice: stableOnSlice,\n      onYield: stableOnYield,\n      ...(timeSliceMs !== undefined ? { timeSliceMs } : {}),\n      ...(batchSize !== undefined ? { batchSize } : {}),\n      ...(collectResults !== undefined ? { collectResults } : {}),\n      ...(signal !== undefined ? { signal } : {}),\n    });\n    controller.replace(scheduler);\n    if (autoStart) scheduler.start();\n\n    return () => {\n      // Safe even if the task already finished on its own — cancel() on a\n      // terminal scheduler is a documented no-op, not an error.\n      scheduler.cancel();\n      controller.replace(null);\n    };\n    // stableProcessItem/stableOnItem/stableOnError/stableOnSlice/stableOnYield\n    // are Effect Events: stable by construction, intentionally excluded\n    // from the reactive dependency set\n    // (that's the whole point of useEffectEvent) rather than omitted by\n    // oversight.\n  }, [items, timeSliceMs, batchSize, collectResults, autoStart, signal, controller]);\n\n  const start = useCallback(() => controller.getCurrent()?.start(), [controller]);\n  const pause = useCallback(() => controller.getCurrent()?.pause(), [controller]);\n  const resume = useCallback(() => controller.getCurrent()?.resume(), [controller]);\n  const cancel = useCallback(() => controller.getCurrent()?.cancel(), [controller]);\n\n  // Built from `snapshot`'s own wide-`status` fields, so — same as the core\n  // engine this wraps — it can't be checked structurally against the\n  // discriminated union above; `snapshot` already carries that invariant.\n  return {\n    status: snapshot.status,\n    processed: snapshot.processed,\n    total: snapshot.total,\n    error: snapshot.error,\n    // From the snapshot, not a direct read of the scheduler: the engine\n    // publishes results before it announces a terminal status, so the two\n    // always arrive together and a concurrent render can never tear them\n    // apart.\n    results: snapshot.results,\n    skipped: snapshot.skipped ?? NO_SKIPPED,\n    reason: snapshot.reason,\n    isIdle: snapshot.status === 'idle',\n    isProcessing: snapshot.status === 'processing',\n    isPaused: snapshot.status === 'paused',\n    isDone: snapshot.status === 'done',\n    isCancelled: snapshot.status === 'cancelled',\n    isError: snapshot.status === 'error',\n    start,\n    pause,\n    resume,\n    cancel,\n  } as UseChunkedTaskState<R>;\n}\n","import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';\n\nimport type { ChunkStatus } from '../core/chunk-machine.js';\nimport { createDeferredTask } from '../core/deferred-task.js';\nimport type {\n  DeferredGenerator,\n  DeferredTask,\n  DeferredTaskSnapshot,\n} from '../core/deferred-task.js';\nimport { createTaskController } from './task-controller.js';\nimport { useEffectEvent } from './use-effect-event.js';\n\nexport interface UseDeferredTaskOptions {\n  /** Max ms of uninterrupted work before yielding. Default 5. */\n  readonly timeSliceMs?: number;\n  /**\n   * Generator segments to run between clock checks. Default 1. Raise it\n   * only for segments measured in nanoseconds; a slice can then run up to\n   * `batchSize` segments past its budget.\n   */\n  readonly batchSize?: number;\n  /** Start processing automatically when the task is (re)created. Default `true`. */\n  readonly autoStart?: boolean;\n  /**\n   * Called every time a segment-batch ends and the task is about to yield,\n   * with how long that slice ran and how many segments are done so far.\n   * Ships in the production build — see the identical option on\n   * `useChunkedTask`/`createChunkScheduler` for why.\n   */\n  readonly onSlice?: (durationMs: number, segmentsDone: number) => void;\n  /** Called right after each yield resolves and work is about to resume. Pairs with `onSlice`. */\n  readonly onYield?: () => void;\n  /**\n   * External cancellation source — aborting it is equivalent to calling\n   * `cancel()`, and its `reason` comes through on `reason` below, so a\n   * cancellation caused by the signal is distinguishable from a direct\n   * `cancel()` call. A new reference restarts the task the same way a new\n   * entry in `deps` does, so memoize it unless you mean to restart on\n   * every render.\n   */\n  readonly signal?: AbortSignal;\n}\n\n/** Fields every status shares, independent of the `status`/`value`/`error` narrowing below. */\ninterface UseDeferredTaskShared {\n  /**\n   * The `signal` option's `reason`, present only when cancellation came\n   * from that signal aborting rather than a direct `cancel()` call.\n   */\n  readonly reason: unknown;\n  readonly isIdle: boolean;\n  readonly isProcessing: boolean;\n  readonly isPaused: boolean;\n  readonly isDone: boolean;\n  readonly isCancelled: boolean;\n  readonly isError: boolean;\n  readonly start: () => void;\n  readonly pause: () => void;\n  readonly resume: () => void;\n  readonly cancel: () => void;\n}\n\n/**\n * Discriminated on `status`. Narrowing to `'done'` narrows `value` to `T`\n * itself — no `=== undefined` check needed alongside `isDone`, even when\n * `T` allows `undefined` as a genuine return value. Narrowing to `'error'`\n * narrows `error` to defined instead.\n */\nexport type UseDeferredTaskState<T> = UseDeferredTaskShared &\n  (\n    | {\n        readonly status: Exclude<ChunkStatus, 'done' | 'error'>;\n        readonly value: undefined;\n        readonly error: undefined;\n      }\n    | { readonly status: 'done'; readonly value: T; readonly error: undefined }\n    | { readonly status: 'error'; readonly value: undefined; readonly error: unknown }\n  );\n\n// Narrowed to the literal, not widened to `ChunkStatus`, so this satisfies\n// the discriminated `DeferredTaskSnapshot` union on its own merits.\nconst IDLE_SNAPSHOT: DeferredTaskSnapshot<never> = { status: 'idle' };\n\n/**\n * Runs an arbitrary heavy, synchronous generator function in chunks, so it\n * never produces a long task on its own. Where `useChunkedTask` chunks \"one\n * function applied to every item of an array\" automatically, this hook\n * leaves the chunk boundaries to you — put `yield` wherever your function\n * can safely pause (see `DeferredGenerator`'s doc comment for an example).\n *\n * `task` is only called when the effect (re)creates the underlying task, not\n * on every render — list whatever it closes over in `deps`, the same way\n * you would for `useMemo` or `useEffect`.\n */\nexport function useDeferredTask<T>(\n  task: () => DeferredGenerator<T>,\n  deps: readonly unknown[],\n  options?: UseDeferredTaskOptions,\n): UseDeferredTaskState<T> {\n  const {\n    timeSliceMs,\n    batchSize,\n    autoStart = true,\n    onSlice,\n    onYield,\n    signal,\n  } = options ?? {};\n\n  // Stable identity, always runs the latest `task` passed this render —\n  // see useChunkedTask.ts for why this is useEffectEvent rather than a ref\n  // mutated during render.\n  const stableTask = useEffectEvent(() => task());\n  const stableOnSlice = useEffectEvent((durationMs: number, segmentsDone: number) => {\n    onSlice?.(durationMs, segmentsDone);\n  });\n  const stableOnYield = useEffectEvent(() => {\n    onYield?.();\n  });\n\n  const [controller] = useState(() => createTaskController<DeferredTask<T>>());\n\n  const snapshot = useSyncExternalStore(\n    controller.subscribe,\n    () => controller.getSnapshot() ?? IDLE_SNAPSHOT,\n    () => IDLE_SNAPSHOT,\n  );\n\n  useEffect(\n    () => {\n      const deferredTask = createDeferredTask<T>({\n        task: stableTask,\n        onSlice: stableOnSlice,\n        onYield: stableOnYield,\n        ...(timeSliceMs !== undefined ? { timeSliceMs } : {}),\n        ...(batchSize !== undefined ? { batchSize } : {}),\n        ...(signal !== undefined ? { signal } : {}),\n      });\n      controller.replace(deferredTask);\n      if (autoStart) deferredTask.start();\n\n      return () => {\n        deferredTask.cancel();\n        controller.replace(null);\n      };\n    },\n    // `deps` plays the role `items` plays for useChunkedTask: it's the\n    // caller's declaration of \"this is new work\". `stableTask` is an Effect\n    // Event — stable by construction, intentionally excluded from the\n    // reactive dependency set rather than omitted by oversight. `deps` is a\n    // caller-supplied array, the same pattern (and the same reason it can't\n    // be statically verified) as useMemo/useEffect's own deps parameter.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [...deps, timeSliceMs, batchSize, autoStart, signal, controller],\n  );\n\n  const start = useCallback(() => controller.getCurrent()?.start(), [controller]);\n  const pause = useCallback(() => controller.getCurrent()?.pause(), [controller]);\n  const resume = useCallback(() => controller.getCurrent()?.resume(), [controller]);\n  const cancel = useCallback(() => controller.getCurrent()?.cancel(), [controller]);\n\n  // Built from `snapshot`'s own wide-`status` fields — see the identical\n  // note in useChunkedTask.ts; `snapshot` already carries the invariant.\n  return {\n    status: snapshot.status,\n    error: snapshot.error,\n    // From the snapshot: the engine publishes the value before it\n    // announces `done`, so a concurrent render can never see one without\n    // the other. See useChunkedTask.ts.\n    value: snapshot.value,\n    reason: snapshot.reason,\n    isIdle: snapshot.status === 'idle',\n    isProcessing: snapshot.status === 'processing',\n    isPaused: snapshot.status === 'paused',\n    isDone: snapshot.status === 'done',\n    isCancelled: snapshot.status === 'cancelled',\n    isError: snapshot.status === 'error',\n    start,\n    pause,\n    resume,\n    cancel,\n  } as UseDeferredTaskState<T>;\n}\n"],"mappings":"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"}

package/dist/production/core/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_deferred_task = require("../deferred-task-zVnq18IN.cjs");
+const require_deferred_task = require("../deferred-task-j8KF7lk7.cjs");
 exports.DEFAULT_TIME_SLICE_MS = require_deferred_task.DEFAULT_TIME_SLICE_MS;
 exports.createChunkScheduler = require_deferred_task.createChunkScheduler;
 exports.createDeferredTask = require_deferred_task.createDeferredTask;

package/dist/production/core/index.js

@@ -1 +1 @@
-export { r as DEFAULT_TIME_SLICE_MS, n as createChunkScheduler, t as createDeferredTask, f as initialChunkState, i as isInputPending, p as isTerminal, a as now, o as resolveYieldStrategy, s as shouldYieldNow, c as supportsInputPending, l as supportsMessageChannel, u as supportsSchedulerYield, m as transition, d as yieldToMain } from "../deferred-task-BGsfee-L.js";
+export { r as DEFAULT_TIME_SLICE_MS, n as createChunkScheduler, t as createDeferredTask, f as initialChunkState, i as isInputPending, p as isTerminal, a as now, o as resolveYieldStrategy, s as shouldYieldNow, c as supportsInputPending, l as supportsMessageChannel, u as supportsSchedulerYield, m as transition, d as yieldToMain } from "../deferred-task-MsTNINAd.js";

package/dist/production/{deferred-task-BGsfee-L.js → deferred-task-MsTNINAd.js}

@@ -205,7 +205,7 @@ function at(items, index) {
 * scheduler, which is the idiomatic React data-flow anyway.
 */
 function createChunkScheduler(options) {
-	const { items, processItem, onItem, signal, yieldStrategy } = options;
+	const { items, processItem, onItem, onError, signal, yieldStrategy, onSlice, onYield } = options;
 	const timeSliceMs = normalizeTimeSliceMs(options.timeSliceMs);
 	const batchSize = normalizeBatchSize(options.batchSize);
 	const collectResults = options.collectResults ?? true;
@@ -217,6 +217,8 @@ function createChunkScheduler(options) {
 	let settledFlag = false;
 	const results = [];
 	let finalResults;
+	const skipped = [];
+	let cancelReason;
 	let snapshot = {
 		status: machineState.status,
 		processed,
@@ -252,7 +254,9 @@ function createChunkScheduler(options) {
 				processed,
 				total,
 				...machineState.error !== void 0 ? { error: machineState.error } : {},
-				...finalResults !== void 0 ? { results: finalResults } : {}
+				...finalResults !== void 0 ? { results: finalResults } : {},
+				...skipped.length > 0 ? { skipped: skipped.slice() } : {},
+				...cancelReason !== void 0 ? { reason: cancelReason } : {}
 			};
 		}
 		return snapshot;
@@ -287,13 +291,12 @@ function createChunkScheduler(options) {
 		return finalResults;
 	}
 	function settleWith(status, published, error) {
-		settle(status === "error" ? {
+		settle({
 			status,
-			error,
-			results: published
-		} : {
-			status,
-			results: published
+			results: published,
+			...error !== void 0 ? { error } : {},
+			...skipped.length > 0 ? { skipped: skipped.slice() } : {},
+			...status === "cancelled" && cancelReason !== void 0 ? { reason: cancelReason } : {}
 		});
 	}
 	/**
@@ -313,13 +316,16 @@ function createChunkScheduler(options) {
 		finishCancelled();
 	}
 	function handleAbort() {
+		cancelReason = signal?.reason;
 		cancel();
 	}
 	function detachSignal() {
 		signal?.removeEventListener("abort", handleAbort);
 	}
-	if (signal?.aborted) dispatch({ type: "CANCEL" });
-	else signal?.addEventListener("abort", handleAbort);
+	if (signal?.aborted) {
+		cancelReason = signal.reason;
+		dispatch({ type: "CANCEL" });
+	} else signal?.addEventListener("abort", handleAbort);
 	async function runLoop() {
 		let sliceStartedAt = now();
 		let index = 0;
@@ -335,17 +341,33 @@ function createChunkScheduler(options) {
 				const batchEnd = index + batchSize <= total ? index + batchSize : total;
 				while (index < batchEnd) {
 					const item = at(items, index);
-					const result = processItem(item, index);
+					let result;
+					try {
+						result = processItem(item, index);
+					} catch (caught) {
+						if ((onError?.(caught, item, index) ?? "abort") !== "skip") throw caught;
+						skipped.push({
+							index,
+							error: caught
+						});
+						processed = index + 1;
+						snapshotStale = true;
+						index += 1;
+						continue;
+					}
 					if (collectResults) results.push(result);
 					processed = index + 1;
 					onItem?.(result, item, index);
 					index += 1;
 				}
 				snapshotStale = true;
-				if (now() - sliceStartedAt >= timeSliceMs || inputPending()) {
+				const checkedAt = now();
+				if (checkedAt - sliceStartedAt >= timeSliceMs || inputPending()) {
+					onSlice?.(checkedAt - sliceStartedAt, index);
 					await yieldToMain(yieldStrategy !== void 0 ? { strategy: yieldStrategy } : void 0);
 					notify();
 					sliceStartedAt = now();
+					onYield?.();
 				}
 			}
 		} catch (error) {
@@ -410,7 +432,7 @@ function createChunkScheduler(options) {
 * here unchanged.
 */
 function createDeferredTask(options) {
-	const { task, signal, yieldStrategy } = options;
+	const { task, signal, yieldStrategy, onSlice, onYield } = options;
 	const timeSliceMs = normalizeTimeSliceMs(options.timeSliceMs);
 	const batchSize = normalizeBatchSize(options.batchSize);
 	const inputPending = resolveInputPending();
@@ -418,6 +440,8 @@ function createDeferredTask(options) {
 	let loopStarted = false;
 	let settledFlag = false;
 	let settledValue;
+	let hasSettledValue = false;
+	let cancelReason;
 	let snapshot = { status: machineState.status };
 	let snapshotStale = false;
 	const listeners = /* @__PURE__ */ new Set();
@@ -447,7 +471,8 @@ function createDeferredTask(options) {
 			snapshot = {
 				status: machineState.status,
 				...machineState.error !== void 0 ? { error: machineState.error } : {},
-				...settledValue !== void 0 ? { value: settledValue } : {}
+				...hasSettledValue ? { value: settledValue } : {},
+				...cancelReason !== void 0 ? { reason: cancelReason } : {}
 			};
 		}
 		return snapshot;
@@ -475,20 +500,28 @@ function createDeferredTask(options) {
 	*/
 	function publishValue(resolvedValue) {
 		settledValue = resolvedValue;
+		hasSettledValue = true;
 		snapshotStale = true;
 	}
 	function settleWith(status, resolvedValue, error) {
 		if (status === "done") {
 			settle({
 				status,
-				...resolvedValue !== void 0 ? { value: resolvedValue } : {}
+				value: resolvedValue
 			});
 			return;
 		}
-		settle(status === "error" ? {
+		if (status === "error") {
+			settle({
+				status,
+				error
+			});
+			return;
+		}
+		settle({
 			status,
-			error
-		} : { status });
+			...cancelReason !== void 0 ? { reason: cancelReason } : {}
+		});
 	}
 	/**
 	* Settling as cancelled, for both places that can do it. The CANCEL
@@ -506,13 +539,16 @@ function createDeferredTask(options) {
 		finishCancelled();
 	}
 	function handleAbort() {
+		cancelReason = signal?.reason;
 		cancel();
 	}
 	function detachSignal() {
 		signal?.removeEventListener("abort", handleAbort);
 	}
-	if (signal?.aborted) dispatch({ type: "CANCEL" });
-	else signal?.addEventListener("abort", handleAbort);
+	if (signal?.aborted) {
+		cancelReason = signal.reason;
+		dispatch({ type: "CANCEL" });
+	} else signal?.addEventListener("abort", handleAbort);
 	async function runLoop() {
 		let sliceStartedAt = now();
 		let segment = 0;
@@ -543,10 +579,13 @@ function createDeferredTask(options) {
 					}
 				}
 				if (done) break;
-				if (now() - sliceStartedAt >= timeSliceMs || inputPending()) {
+				const checkedAt = now();
+				if (checkedAt - sliceStartedAt >= timeSliceMs || inputPending()) {
+					onSlice?.(checkedAt - sliceStartedAt, segment);
 					await yieldToMain(yieldStrategy !== void 0 ? { strategy: yieldStrategy } : void 0);
 					notify();
 					sliceStartedAt = now();
+					onYield?.();
 				}
 			}
 		} catch (error) {
@@ -605,4 +644,4 @@ function createDeferredTask(options) {
 }
 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-BGsfee-L.js.map
+//# sourceMappingURL=deferred-task-MsTNINAd.js.map