react-inp-chunker 0.0.0-stage → 0.1.0

package/dist/index.cjs

@@ -0,0 +1,160 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_deferred_task = require("./deferred-task-BXVzapQg.cjs");
+let react = require("react");
+// src/react/task-controller.ts
+function createTaskController() {
+	let current = null;
+	let detachFromCurrent;
+	const listeners = /* @__PURE__ */ new Set();
+	const notify = () => {
+		for (const listener of listeners) listener();
+	};
+	return {
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		getSnapshot: () => current?.getSnapshot(),
+		getCurrent: () => current,
+		replace: (task) => {
+			detachFromCurrent?.();
+			current = task;
+			detachFromCurrent = task?.subscribe(notify);
+			notify();
+		}
+	};
+}
+// src/react/useChunkedTask.ts
+const IDLE_STATUS = "idle";
+/**
+* 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
+* costs you Interaction to Next Paint. Starts automatically by default;
+* pass `{ autoStart: false }` to wait for an explicit `start()` call (e.g.
+* behind a button).
+*
+* `processItem` and `onItem` can be fresh closures every render — the hook
+* always calls the latest version (via `useEffectEvent`) without that
+* causing the task to restart. What *does* restart the task is `items`
+* changing identity (a new array reference), or `timeSliceMs`/`autoStart`
+* changing. That's deliberate: a new `items` array means new work, and
+* memoizing it when you don't want that is the caller's call to make, the
+* same as any other React dependency.
+*/
+function useChunkedTask(items, processItem, options) {
+	const { timeSliceMs, autoStart = true, onItem } = options ?? {};
+	const stableProcessItem = (0, react.useEffectEvent)((item, index) => processItem(item, index));
+	const stableOnItem = (0, react.useEffectEvent)((result, item, index) => {
+		onItem?.(result, item, index);
+	});
+	const [controller] = (0, react.useState)(() => createTaskController());
+	const idleSnapshot = (0, react.useMemo)(() => ({
+		status: IDLE_STATUS,
+		processed: 0,
+		total: items.length
+	}), [items.length]);
+	const snapshot = (0, react.useSyncExternalStore)(controller.subscribe, () => controller.getSnapshot() ?? idleSnapshot, () => idleSnapshot);
+	(0, react.useEffect)(() => {
+		const scheduler = require_deferred_task.createChunkScheduler({
+			items,
+			processItem: stableProcessItem,
+			onItem: stableOnItem,
+			...timeSliceMs !== void 0 ? { timeSliceMs } : {}
+		});
+		controller.replace(scheduler);
+		if (autoStart) scheduler.start();
+		return () => {
+			scheduler.cancel();
+			controller.replace(null);
+		};
+	}, [
+		items,
+		timeSliceMs,
+		autoStart,
+		controller
+	]);
+	const start = (0, react.useCallback)(() => controller.getCurrent()?.start(), [controller]);
+	const pause = (0, react.useCallback)(() => controller.getCurrent()?.pause(), [controller]);
+	const resume = (0, react.useCallback)(() => controller.getCurrent()?.resume(), [controller]);
+	const cancel = (0, react.useCallback)(() => controller.getCurrent()?.cancel(), [controller]);
+	const results = controller.getCurrent()?.getResults();
+	return {
+		status: snapshot.status,
+		processed: snapshot.processed,
+		total: snapshot.total,
+		error: snapshot.error,
+		results,
+		isIdle: snapshot.status === "idle",
+		isProcessing: snapshot.status === "processing",
+		isPaused: snapshot.status === "paused",
+		isDone: snapshot.status === "done",
+		isCancelled: snapshot.status === "cancelled",
+		isError: snapshot.status === "error",
+		start,
+		pause,
+		resume,
+		cancel
+	};
+}
+// src/react/useDeferredTask.ts
+const IDLE_SNAPSHOT = { status: "idle" };
+/**
+* Runs an arbitrary heavy, synchronous generator function in chunks, so it
+* never produces a long task on its own. Where `useChunkedTask` chunks "one
+* function applied to every item of an array" automatically, this hook
+* leaves the chunk boundaries to you — put `yield` wherever your function
+* can safely pause (see `DeferredGenerator`'s doc comment for an example).
+*
+* `task` is only called when the effect (re)creates the underlying task, not
+* on every render — list whatever it closes over in `deps`, the same way
+* you would for `useMemo` or `useEffect`.
+*/
+function useDeferredTask(task, deps, options) {
+	const { timeSliceMs, autoStart = true } = options ?? {};
+	const stableTask = (0, react.useEffectEvent)(() => task());
+	const [controller] = (0, react.useState)(() => createTaskController());
+	const snapshot = (0, react.useSyncExternalStore)(controller.subscribe, () => controller.getSnapshot() ?? IDLE_SNAPSHOT, () => IDLE_SNAPSHOT);
+	(0, react.useEffect)(() => {
+		const deferredTask = require_deferred_task.createDeferredTask({
+			task: stableTask,
+			...timeSliceMs !== void 0 ? { timeSliceMs } : {}
+		});
+		controller.replace(deferredTask);
+		if (autoStart) deferredTask.start();
+		return () => {
+			deferredTask.cancel();
+			controller.replace(null);
+		};
+	}, [
+		...deps,
+		timeSliceMs,
+		autoStart,
+		controller
+	]);
+	const start = (0, react.useCallback)(() => controller.getCurrent()?.start(), [controller]);
+	const pause = (0, react.useCallback)(() => controller.getCurrent()?.pause(), [controller]);
+	const resume = (0, react.useCallback)(() => controller.getCurrent()?.resume(), [controller]);
+	const cancel = (0, react.useCallback)(() => controller.getCurrent()?.cancel(), [controller]);
+	const value = controller.getCurrent()?.getValue();
+	return {
+		status: snapshot.status,
+		error: snapshot.error,
+		value,
+		isIdle: snapshot.status === "idle",
+		isProcessing: snapshot.status === "processing",
+		isPaused: snapshot.status === "paused",
+		isDone: snapshot.status === "done",
+		isCancelled: snapshot.status === "cancelled",
+		isError: snapshot.status === "error",
+		start,
+		pause,
+		resume,
+		cancel
+	};
+}
+exports.useChunkedTask = useChunkedTask;
+exports.useDeferredTask = useDeferredTask;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["useEffectEvent","useState","useMemo","useSyncExternalStore","createChunkScheduler","useCallback","useEffectEvent","useState","useSyncExternalStore","createDeferredTask","useCallback"],"sources":["../src/react/task-controller.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 {\n  useCallback,\n  useEffect,\n  useEffectEvent,\n  useMemo,\n  useState,\n  useSyncExternalStore,\n} 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';\n\nexport interface UseChunkedTaskOptions<T, R> {\n  /** Max ms of uninterrupted work before yielding. Default 5. */\n  readonly timeSliceMs?: number;\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 { timeSliceMs, autoStart = true, onItem } = 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>(\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    });\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, 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  // Safe to read outside useSyncExternalStore's own getSnapshot: a\n  // scheduler only ever finishes synchronously (dispatch-then-finish, no\n  // await between them — see chunk-scheduler.ts), so by the time React\n  // re-renders in response to the status-change notification, getResults()\n  // already agrees with that status. They can never be observed out of sync.\n  const results = controller.getCurrent()?.getResults();\n\n  return {\n    status: snapshot.status,\n    processed: snapshot.processed,\n    total: snapshot.total,\n    error: snapshot.error,\n    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 {\n  useCallback,\n  useEffect,\n  useEffectEvent,\n  useState,\n  useSyncExternalStore,\n} 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';\n\nexport interface UseDeferredTaskOptions {\n  /** Max ms of uninterrupted work before yielding. Default 5. */\n  readonly timeSliceMs?: 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 = { 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, 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      });\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, 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  // See useChunkedTask.ts for why reading this outside useSyncExternalStore\n  // is safe: status and value are always settled in the same synchronous\n  // turn, with no await between them.\n  const value = controller.getCurrent()?.getValue();\n\n  return {\n    status: snapshot.status,\n    error: snapshot.error,\n    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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"}

package/dist/index.d.cts

@@ -0,0 +1,84 @@
+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-C6B_Nm3i.cjs";
+interface UseChunkedTaskOptions<T, R> {
+  /** Max ms of uninterrupted work before yielding. Default 5. */
+  readonly timeSliceMs?: number;
+  /** Start processing automatically when the task is (re)created. Default `true`. */
+  readonly autoStart?: boolean;
+  /**
+   * Called synchronously after each item is processed. This is the cheap
+   * way to consume results incrementally while the task is still running —
+   * write into a ref-backed buffer, a canvas, a chart, whatever you need —
+   * without paying for an array copy on every yield checkpoint.
+   */
+  readonly onItem?: (result: R, item: T, index: number) => void;
+}
+interface UseChunkedTaskState<R> {
+  readonly status: ChunkStatus;
+  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;
+  readonly isIdle: boolean;
+  readonly isProcessing: boolean;
+  readonly isPaused: boolean;
+  readonly isDone: boolean;
+  readonly isCancelled: boolean;
+  readonly isError: boolean;
+  readonly start: () => void;
+  readonly pause: () => void;
+  readonly resume: () => void;
+  readonly cancel: () => void;
+}
+/**
+ * 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
+ * costs you Interaction to Next Paint. Starts automatically by default;
+ * pass `{ autoStart: false }` to wait for an explicit `start()` call (e.g.
+ * behind a button).
+ *
+ * `processItem` and `onItem` can be fresh closures every render — the hook
+ * always calls the latest version (via `useEffectEvent`) without that
+ * causing the task to restart. What *does* restart the task is `items`
+ * changing identity (a new array reference), or `timeSliceMs`/`autoStart`
+ * changing. That's deliberate: a new `items` array means new work, and
+ * memoizing it when you don't want that is the caller's call to make, the
+ * same as any other React dependency.
+ */
+export declare function useChunkedTask<T, R>(items: readonly T[], processItem: (item: T, index: number) => R, options?: UseChunkedTaskOptions<T, R>): UseChunkedTaskState<R>;
+interface UseDeferredTaskOptions {
+  /** Max ms of uninterrupted work before yielding. Default 5. */
+  readonly timeSliceMs?: number;
+  /** Start processing automatically when the task is (re)created. Default `true`. */
+  readonly autoStart?: boolean;
+}
+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;
+  readonly isIdle: boolean;
+  readonly isProcessing: boolean;
+  readonly isPaused: boolean;
+  readonly isDone: boolean;
+  readonly isCancelled: boolean;
+  readonly isError: boolean;
+  readonly start: () => void;
+  readonly pause: () => void;
+  readonly resume: () => void;
+  readonly cancel: () => void;
+}
+/**
+ * Runs an arbitrary heavy, synchronous generator function in chunks, so it
+ * never produces a long task on its own. Where `useChunkedTask` chunks "one
+ * function applied to every item of an array" automatically, this hook
+ * leaves the chunk boundaries to you — put `yield` wherever your function
+ * can safely pause (see `DeferredGenerator`'s doc comment for an example).
+ *
+ * `task` is only called when the effect (re)creates the underlying task, not
+ * on every render — list whatever it closes over in `deps`, the same way
+ * 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 };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/react/useChunkedTask.ts","../src/react/useDeferredTask.ts"],"mappings":";UAciB,sBAAsB,GAAG;;WAE/B;;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;UCnDN;;WAEN;;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"}

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+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-C6B_Nm3i.js";
+interface UseChunkedTaskOptions<T, R> {
+  /** Max ms of uninterrupted work before yielding. Default 5. */
+  readonly timeSliceMs?: number;
+  /** Start processing automatically when the task is (re)created. Default `true`. */
+  readonly autoStart?: boolean;
+  /**
+   * Called synchronously after each item is processed. This is the cheap
+   * way to consume results incrementally while the task is still running —
+   * write into a ref-backed buffer, a canvas, a chart, whatever you need —
+   * without paying for an array copy on every yield checkpoint.
+   */
+  readonly onItem?: (result: R, item: T, index: number) => void;
+}
+interface UseChunkedTaskState<R> {
+  readonly status: ChunkStatus;
+  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;
+  readonly isIdle: boolean;
+  readonly isProcessing: boolean;
+  readonly isPaused: boolean;
+  readonly isDone: boolean;
+  readonly isCancelled: boolean;
+  readonly isError: boolean;
+  readonly start: () => void;
+  readonly pause: () => void;
+  readonly resume: () => void;
+  readonly cancel: () => void;
+}
+/**
+ * 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
+ * costs you Interaction to Next Paint. Starts automatically by default;
+ * pass `{ autoStart: false }` to wait for an explicit `start()` call (e.g.
+ * behind a button).
+ *
+ * `processItem` and `onItem` can be fresh closures every render — the hook
+ * always calls the latest version (via `useEffectEvent`) without that
+ * causing the task to restart. What *does* restart the task is `items`
+ * changing identity (a new array reference), or `timeSliceMs`/`autoStart`
+ * changing. That's deliberate: a new `items` array means new work, and
+ * memoizing it when you don't want that is the caller's call to make, the
+ * same as any other React dependency.
+ */
+export declare function useChunkedTask<T, R>(items: readonly T[], processItem: (item: T, index: number) => R, options?: UseChunkedTaskOptions<T, R>): UseChunkedTaskState<R>;
+interface UseDeferredTaskOptions {
+  /** Max ms of uninterrupted work before yielding. Default 5. */
+  readonly timeSliceMs?: number;
+  /** Start processing automatically when the task is (re)created. Default `true`. */
+  readonly autoStart?: boolean;
+}
+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;
+  readonly isIdle: boolean;
+  readonly isProcessing: boolean;
+  readonly isPaused: boolean;
+  readonly isDone: boolean;
+  readonly isCancelled: boolean;
+  readonly isError: boolean;
+  readonly start: () => void;
+  readonly pause: () => void;
+  readonly resume: () => void;
+  readonly cancel: () => void;
+}
+/**
+ * Runs an arbitrary heavy, synchronous generator function in chunks, so it
+ * never produces a long task on its own. Where `useChunkedTask` chunks "one
+ * function applied to every item of an array" automatically, this hook
+ * leaves the chunk boundaries to you — put `yield` wherever your function
+ * can safely pause (see `DeferredGenerator`'s doc comment for an example).
+ *
+ * `task` is only called when the effect (re)creates the underlying task, not
+ * on every render — list whatever it closes over in `deps`, the same way
+ * 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 };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/react/useChunkedTask.ts","../src/react/useDeferredTask.ts"],"mappings":";UAciB,sBAAsB,GAAG;;WAE/B;;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;UCnDN;;WAEN;;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"}

package/dist/index.js

@@ -0,0 +1,158 @@
+import { n as createChunkScheduler, t as createDeferredTask } from "./deferred-task-5kfztF2G.js";
+import { useCallback, useEffect, useEffectEvent, useMemo, useState, useSyncExternalStore } from "react";
+// src/react/task-controller.ts
+function createTaskController() {
+	let current = null;
+	let detachFromCurrent;
+	const listeners = /* @__PURE__ */ new Set();
+	const notify = () => {
+		for (const listener of listeners) listener();
+	};
+	return {
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		getSnapshot: () => current?.getSnapshot(),
+		getCurrent: () => current,
+		replace: (task) => {
+			detachFromCurrent?.();
+			current = task;
+			detachFromCurrent = task?.subscribe(notify);
+			notify();
+		}
+	};
+}
+// src/react/useChunkedTask.ts
+const IDLE_STATUS = "idle";
+/**
+* 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
+* costs you Interaction to Next Paint. Starts automatically by default;
+* pass `{ autoStart: false }` to wait for an explicit `start()` call (e.g.
+* behind a button).
+*
+* `processItem` and `onItem` can be fresh closures every render — the hook
+* always calls the latest version (via `useEffectEvent`) without that
+* causing the task to restart. What *does* restart the task is `items`
+* changing identity (a new array reference), or `timeSliceMs`/`autoStart`
+* changing. That's deliberate: a new `items` array means new work, and
+* memoizing it when you don't want that is the caller's call to make, the
+* same as any other React dependency.
+*/
+function useChunkedTask(items, processItem, options) {
+	const { timeSliceMs, autoStart = true, onItem } = options ?? {};
+	const stableProcessItem = useEffectEvent((item, index) => processItem(item, index));
+	const stableOnItem = useEffectEvent((result, item, index) => {
+		onItem?.(result, item, index);
+	});
+	const [controller] = useState(() => createTaskController());
+	const idleSnapshot = useMemo(() => ({
+		status: IDLE_STATUS,
+		processed: 0,
+		total: items.length
+	}), [items.length]);
+	const snapshot = useSyncExternalStore(controller.subscribe, () => controller.getSnapshot() ?? idleSnapshot, () => idleSnapshot);
+	useEffect(() => {
+		const scheduler = createChunkScheduler({
+			items,
+			processItem: stableProcessItem,
+			onItem: stableOnItem,
+			...timeSliceMs !== void 0 ? { timeSliceMs } : {}
+		});
+		controller.replace(scheduler);
+		if (autoStart) scheduler.start();
+		return () => {
+			scheduler.cancel();
+			controller.replace(null);
+		};
+	}, [
+		items,
+		timeSliceMs,
+		autoStart,
+		controller
+	]);
+	const start = useCallback(() => controller.getCurrent()?.start(), [controller]);
+	const pause = useCallback(() => controller.getCurrent()?.pause(), [controller]);
+	const resume = useCallback(() => controller.getCurrent()?.resume(), [controller]);
+	const cancel = useCallback(() => controller.getCurrent()?.cancel(), [controller]);
+	const results = controller.getCurrent()?.getResults();
+	return {
+		status: snapshot.status,
+		processed: snapshot.processed,
+		total: snapshot.total,
+		error: snapshot.error,
+		results,
+		isIdle: snapshot.status === "idle",
+		isProcessing: snapshot.status === "processing",
+		isPaused: snapshot.status === "paused",
+		isDone: snapshot.status === "done",
+		isCancelled: snapshot.status === "cancelled",
+		isError: snapshot.status === "error",
+		start,
+		pause,
+		resume,
+		cancel
+	};
+}
+// src/react/useDeferredTask.ts
+const IDLE_SNAPSHOT = { status: "idle" };
+/**
+* Runs an arbitrary heavy, synchronous generator function in chunks, so it
+* never produces a long task on its own. Where `useChunkedTask` chunks "one
+* function applied to every item of an array" automatically, this hook
+* leaves the chunk boundaries to you — put `yield` wherever your function
+* can safely pause (see `DeferredGenerator`'s doc comment for an example).
+*
+* `task` is only called when the effect (re)creates the underlying task, not
+* on every render — list whatever it closes over in `deps`, the same way
+* you would for `useMemo` or `useEffect`.
+*/
+function useDeferredTask(task, deps, options) {
+	const { timeSliceMs, autoStart = true } = options ?? {};
+	const stableTask = useEffectEvent(() => task());
+	const [controller] = useState(() => createTaskController());
+	const snapshot = useSyncExternalStore(controller.subscribe, () => controller.getSnapshot() ?? IDLE_SNAPSHOT, () => IDLE_SNAPSHOT);
+	useEffect(() => {
+		const deferredTask = createDeferredTask({
+			task: stableTask,
+			...timeSliceMs !== void 0 ? { timeSliceMs } : {}
+		});
+		controller.replace(deferredTask);
+		if (autoStart) deferredTask.start();
+		return () => {
+			deferredTask.cancel();
+			controller.replace(null);
+		};
+	}, [
+		...deps,
+		timeSliceMs,
+		autoStart,
+		controller
+	]);
+	const start = useCallback(() => controller.getCurrent()?.start(), [controller]);
+	const pause = useCallback(() => controller.getCurrent()?.pause(), [controller]);
+	const resume = useCallback(() => controller.getCurrent()?.resume(), [controller]);
+	const cancel = useCallback(() => controller.getCurrent()?.cancel(), [controller]);
+	const value = controller.getCurrent()?.getValue();
+	return {
+		status: snapshot.status,
+		error: snapshot.error,
+		value,
+		isIdle: snapshot.status === "idle",
+		isProcessing: snapshot.status === "processing",
+		isPaused: snapshot.status === "paused",
+		isDone: snapshot.status === "done",
+		isCancelled: snapshot.status === "cancelled",
+		isError: snapshot.status === "error",
+		start,
+		pause,
+		resume,
+		cancel
+	};
+}
+export { useChunkedTask, useDeferredTask };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/react/task-controller.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 {\n  useCallback,\n  useEffect,\n  useEffectEvent,\n  useMemo,\n  useState,\n  useSyncExternalStore,\n} 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';\n\nexport interface UseChunkedTaskOptions<T, R> {\n  /** Max ms of uninterrupted work before yielding. Default 5. */\n  readonly timeSliceMs?: number;\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 { timeSliceMs, autoStart = true, onItem } = 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>(\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    });\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, 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  // Safe to read outside useSyncExternalStore's own getSnapshot: a\n  // scheduler only ever finishes synchronously (dispatch-then-finish, no\n  // await between them — see chunk-scheduler.ts), so by the time React\n  // re-renders in response to the status-change notification, getResults()\n  // already agrees with that status. They can never be observed out of sync.\n  const results = controller.getCurrent()?.getResults();\n\n  return {\n    status: snapshot.status,\n    processed: snapshot.processed,\n    total: snapshot.total,\n    error: snapshot.error,\n    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 {\n  useCallback,\n  useEffect,\n  useEffectEvent,\n  useState,\n  useSyncExternalStore,\n} 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';\n\nexport interface UseDeferredTaskOptions {\n  /** Max ms of uninterrupted work before yielding. Default 5. */\n  readonly timeSliceMs?: 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 = { 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, 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      });\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, 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  // See useChunkedTask.ts for why reading this outside useSyncExternalStore\n  // is safe: status and value are always settled in the same synchronous\n  // turn, with no await between them.\n  const value = controller.getCurrent()?.getValue();\n\n  return {\n    status: snapshot.status,\n    error: snapshot.error,\n    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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"}