react-inp-chunker 0.1.2 → 0.3.0

package/dist/index.js.map

@@ -1 +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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"}
+{"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\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  /** Items `onError` has skipped so far, growing live as skips happen. Empty when unused. */\n  readonly skipped: readonly SkippedChunkItem[];\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    onError,\n    onSlice,\n    onYield,\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    });\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, 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    skipped: snapshot.skipped ?? NO_SKIPPED,\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   * 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\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, onSlice, onYield } = 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      });\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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"}

package/dist/production/core/index.cjs

@@ -0,0 +1,16 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_deferred_task = require("../deferred-task-yh5pWlSj.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;
+exports.initialChunkState = require_deferred_task.initialChunkState;
+exports.isInputPending = require_deferred_task.isInputPending;
+exports.isTerminal = require_deferred_task.isTerminal;
+exports.now = require_deferred_task.now;
+exports.resolveYieldStrategy = require_deferred_task.resolveYieldStrategy;
+exports.shouldYieldNow = require_deferred_task.shouldYieldNow;
+exports.supportsInputPending = require_deferred_task.supportsInputPending;
+exports.supportsMessageChannel = require_deferred_task.supportsMessageChannel;
+exports.supportsSchedulerYield = require_deferred_task.supportsSchedulerYield;
+exports.transition = require_deferred_task.transition;
+exports.yieldToMain = require_deferred_task.yieldToMain;

package/dist/production/core/index.js

@@ -0,0 +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-DkHdsliy.js";

package/dist/{deferred-task-5kfztF2G.js → production/deferred-task-DkHdsliy.js}

@@ -71,6 +71,19 @@ function supportsInputPending() {
 	return typeof globalThis.navigator?.scheduling?.isInputPending === "function";
 }
 /**
+* Resolves the input-pending probe once, for callers that would otherwise
+* run the feature detection on every item of a long task: walking
+* `navigator.scheduling.isInputPending` through optional calls is wasted
+* work a million times over. Returns a function that always answers
+* `false` where the API is missing, so callers need no second branch.
+*/
+function resolveInputPending() {
+	return supportsInputPending() ? isInputPending : returnsFalse;
+}
+function returnsFalse() {
+	return false;
+}
+/**
 * Best-effort read of whether the browser has pending input right now.
 * Returns `false` — never throws — when the API is unavailable or errors,
 * since the caller's fallback (a plain time budget) is always safe.
@@ -92,6 +105,7 @@ function yieldViaMessageChannel() {
 	return new Promise((resolve) => {
 		const channel = new MessageChannel();
 		channel.port1.onmessage = () => {
+			channel.port1.close();
 			resolve();
 		};
 		channel.port2.postMessage(null);
@@ -139,6 +153,23 @@ function now() {
 	return Date.now();
 }
 /**
+* A time slice of zero, a negative number or NaN is meaningless, so those
+* fall back to the default rather than producing a task that yields after
+* every item (or never).
+*/
+function normalizeTimeSliceMs(value) {
+	if (typeof value !== "number" || Number.isNaN(value) || value <= 0) return 5;
+	return value;
+}
+/**
+* Batch sizes are whole items, at least one. Anything else — a fraction,
+* zero, a negative, NaN — falls back to 1, the safe default.
+*/
+function normalizeBatchSize(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return 1;
+	return Math.floor(value);
+}
+/**
 * Whether the caller should yield right now: either the time slice has run
 * out, or the browser is reporting pending input (a stronger, earlier
 * signal than the clock — used only when the runtime exposes it).
@@ -149,9 +180,17 @@ function shouldYieldNow(options) {
 	return isInputPending();
 }
 // src/core/chunk-scheduler.ts
-function normalizeTimeSliceMs$1(value) {
-	if (typeof value !== "number" || Number.isNaN(value) || value <= 0) return 5;
-	return value;
+/**
+* `items[index]` for an index the caller has already bounds-checked.
+*
+* The loop below only ever indexes below `items.length`, but
+* `noUncheckedIndexedAccess` widens every index read to `T | undefined`,
+* and `T` may itself include `undefined` — so no runtime check can narrow
+* it. This states the invariant in one place instead of asserting at each
+* use, and compiles to a plain index read.
+*/
+function at(items, index) {
+	return items[index];
 }
 /**
 * Builds a one-shot, controllable scheduler that processes `items` through
@@ -166,20 +205,26 @@ function normalizeTimeSliceMs$1(value) {
 * scheduler, which is the idiomatic React data-flow anyway.
 */
 function createChunkScheduler(options) {
-	const { items, processItem, onItem, signal, yieldStrategy } = options;
-	const timeSliceMs = normalizeTimeSliceMs$1(options.timeSliceMs);
+	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;
 	const total = items.length;
+	const inputPending = resolveInputPending();
 	let machineState = initialChunkState;
 	let processed = 0;
 	let loopStarted = false;
 	let settledFlag = false;
 	const results = [];
 	let finalResults;
+	const skipped = [];
+	let cancelReason;
 	let snapshot = {
 		status: machineState.status,
 		processed,
 		total
 	};
+	let snapshotStale = false;
 	const listeners = /* @__PURE__ */ new Set();
 	let settleFn;
 	const settledPromise = new Promise((resolve) => {
@@ -201,20 +246,27 @@ function createChunkScheduler(options) {
 	function notify() {
 		for (const listener of listeners) listener();
 	}
-	function refreshSnapshot() {
-		snapshot = {
-			status: machineState.status,
-			processed,
-			total,
-			...machineState.error !== void 0 ? { error: machineState.error } : {}
-		};
+	function getSnapshot() {
+		if (snapshotStale) {
+			snapshotStale = false;
+			snapshot = {
+				status: machineState.status,
+				processed,
+				total,
+				...machineState.error !== void 0 ? { error: machineState.error } : {},
+				...finalResults !== void 0 ? { results: finalResults } : {},
+				...skipped.length > 0 ? { skipped: skipped.slice() } : {},
+				...cancelReason !== void 0 ? { reason: cancelReason } : {}
+			};
+		}
+		return snapshot;
 	}
 	function dispatch(event) {
 		const next = transition(machineState, event);
 		const changed = next !== machineState;
 		if (changed) {
 			machineState = next;
-			refreshSnapshot();
+			snapshotStale = true;
 			notify();
 		}
 		return { changed };
@@ -227,78 +279,113 @@ function createChunkScheduler(options) {
 		settleFn(result);
 	}
 	/**
-	* The single path every terminal transition goes through: snapshots the
-	* results array exactly once (not per item), publishes it via
-	* getResults(), and settles the public promise with the same reference —
-	* no redundant second copy.
+	* Publishes the accumulated results exactly once, at the moment the task
+	* settles — not per item, and never as a second copy. Always called
+	* *before* the terminal status is announced, so the notification that
+	* reports `done` already carries the results: a subscriber can never
+	* observe one without the other.
 	*/
-	function finish(status, error) {
-		const resultsCopy = [...results];
-		finalResults = resultsCopy;
-		settle(status === "error" ? {
-			status,
-			error,
-			results: resultsCopy
-		} : {
+	function publishResults() {
+		finalResults = results;
+		snapshotStale = true;
+		return finalResults;
+	}
+	function settleWith(status, published, error) {
+		settle({
 			status,
-			results: resultsCopy
+			results: published,
+			...error !== void 0 ? { error } : {},
+			...skipped.length > 0 ? { skipped: skipped.slice() } : {},
+			...status === "cancelled" && cancelReason !== void 0 ? { reason: cancelReason } : {}
 		});
 	}
+	/**
+	* Settling as cancelled, for both places that can do it: the loop
+	* noticing, and cancel() on a task whose loop never ran. The CANCEL
+	* transition was announced earlier, before there were any results to
+	* carry, so this notifies again now that there are.
+	*/
+	function finishCancelled() {
+		settleWith("cancelled", publishResults());
+		notify();
+	}
 	function settleIfNeverStarted() {
-		const { status, error } = machineState;
+		const { status } = machineState;
 		if (loopStarted || !isTerminal(status)) return;
 		loopStarted = true;
-		/* v8 ignore next */
-		if (status === "error") finish("error", error);
-		else finish(status);
+		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();
-		itemLoop: for (const [index, item] of items.entries()) {
-			for (;;) {
+		let index = 0;
+		try {
+			while (index < total) {
 				const status = machineState.status;
-				if (status === "cancelled") break itemLoop;
-				if (status !== "paused") break;
-				await waitForWake();
-				sliceStartedAt = now();
-			}
-			try {
-				const result = processItem(item, index);
-				results.push(result);
-				processed = index + 1;
-				refreshSnapshot();
-				onItem?.(result, item, index);
-			} catch (error) {
-				dispatch({
-					type: "ERROR",
-					error
-				});
-				finish("error", error);
-				return;
-			}
-			if (shouldYieldNow({
-				sliceStartedAt,
-				timeSliceMs
-			})) {
-				await yieldToMain(yieldStrategy !== void 0 ? { strategy: yieldStrategy } : void 0);
-				notify();
-				sliceStartedAt = now();
+				if (status === "cancelled") break;
+				if (status === "paused") {
+					await waitForWake();
+					sliceStartedAt = now();
+					continue;
+				}
+				const batchEnd = index + batchSize <= total ? index + batchSize : total;
+				while (index < batchEnd) {
+					const item = at(items, 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;
+				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) {
+			const published = publishResults();
+			dispatch({
+				type: "ERROR",
+				error
+			});
+			settleWith("error", published, error);
+			return;
 		}
 		if (machineState.status === "cancelled") {
-			finish("cancelled");
+			finishCancelled();
 			return;
 		}
+		const published = publishResults();
 		dispatch({ type: "COMPLETE" });
-		finish("done");
+		settleWith("done", published);
 	}
 	function start() {
 		dispatch({ type: "START" });
@@ -325,7 +412,7 @@ function createChunkScheduler(options) {
 		pause,
 		resume,
 		cancel,
-		getSnapshot: () => snapshot,
+		getSnapshot,
 		getResults: () => finalResults,
 		subscribe(listener) {
 			listeners.add(listener);
@@ -337,10 +424,6 @@ function createChunkScheduler(options) {
 	};
 }
 // src/core/deferred-task.ts
-function normalizeTimeSliceMs(value) {
-	if (typeof value !== "number" || Number.isNaN(value) || value <= 0) return 5;
-	return value;
-}
 /**
 * The generator-driven sibling of `createChunkScheduler`, for heavy work
 * that isn't shaped like "one function applied to each item of an array".
@@ -349,13 +432,17 @@ function normalizeTimeSliceMs(value) {
 * 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();
 	let machineState = initialChunkState;
 	let loopStarted = false;
 	let settledFlag = false;
-	let value;
+	let settledValue;
+	let cancelReason;
 	let snapshot = { status: machineState.status };
+	let snapshotStale = false;
 	const listeners = /* @__PURE__ */ new Set();
 	let settleFn;
 	const settledPromise = new Promise((resolve) => {
@@ -377,18 +464,24 @@ function createDeferredTask(options) {
 	function notify() {
 		for (const listener of listeners) listener();
 	}
-	function refreshSnapshot() {
-		snapshot = {
-			status: machineState.status,
-			...machineState.error !== void 0 ? { error: machineState.error } : {}
-		};
+	function getSnapshot() {
+		if (snapshotStale) {
+			snapshotStale = false;
+			snapshot = {
+				status: machineState.status,
+				...machineState.error !== void 0 ? { error: machineState.error } : {},
+				...settledValue !== void 0 ? { value: settledValue } : {},
+				...cancelReason !== void 0 ? { reason: cancelReason } : {}
+			};
+		}
+		return snapshot;
 	}
 	function dispatch(event) {
 		const next = transition(machineState, event);
 		const changed = next !== machineState;
 		if (changed) {
 			machineState = next;
-			refreshSnapshot();
+			snapshotStale = true;
 			notify();
 		}
 		return { changed };
@@ -400,38 +493,63 @@ function createDeferredTask(options) {
 		detachSignal();
 		settleFn(result);
 	}
-	function finish(status, resolvedValue, error) {
+	/**
+	* Publishes the returned value before the terminal status is announced,
+	* so the notification that reports `done` already carries it.
+	*/
+	function publishValue(resolvedValue) {
+		settledValue = resolvedValue;
+		snapshotStale = true;
+	}
+	function settleWith(status, resolvedValue, error) {
 		if (status === "done") {
-			value = resolvedValue;
 			settle({
 				status,
 				...resolvedValue !== void 0 ? { 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
+	* transition was announced earlier, so this notifies again now that the
+	* task has actually settled.
+	*/
+	function finishCancelled() {
+		settleWith("cancelled");
+		notify();
 	}
 	function settleIfNeverStarted() {
-		const { status, error } = machineState;
+		const { status } = machineState;
 		if (loopStarted || !isTerminal(status)) return;
 		loopStarted = true;
-		/* v8 ignore next */
-		if (status === "error") finish("error", void 0, error);
-		else finish(status);
+		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;
 		const generator = task();
 		let step = {
 			done: false,
@@ -449,15 +567,23 @@ function createDeferredTask(options) {
 					sliceStartedAt = now();
 					continue;
 				}
-				step = generator.next();
-				if (step.done) break;
-				if (shouldYieldNow({
-					sliceStartedAt,
-					timeSliceMs
-				})) {
+				let done = false;
+				for (let inBatch = 0; inBatch < batchSize; inBatch++) {
+					step = generator.next();
+					segment += 1;
+					if (step.done) {
+						done = true;
+						break;
+					}
+				}
+				if (done) break;
+				const checkedAt = now();
+				if (checkedAt - sliceStartedAt >= timeSliceMs || inputPending()) {
+					onSlice?.(checkedAt - sliceStartedAt, segment);
 					await yieldToMain(yieldStrategy !== void 0 ? { strategy: yieldStrategy } : void 0);
 					notify();
 					sliceStartedAt = now();
+					onYield?.();
 				}
 			}
 		} catch (error) {
@@ -465,16 +591,18 @@ function createDeferredTask(options) {
 				type: "ERROR",
 				error
 			});
-			finish("error", void 0, error);
+			settleWith("error", void 0, error);
 			return;
 		}
 		if (machineState.status === "cancelled") {
-			finish("cancelled");
+			finishCancelled();
 			return;
 		}
-		dispatch({ type: "COMPLETE" });
 		/* v8 ignore next */
-		finish("done", step.done ? step.value : void 0);
+		const returned = step.done ? step.value : void 0;
+		publishValue(returned);
+		dispatch({ type: "COMPLETE" });
+		settleWith("done", returned);
 	}
 	function start() {
 		dispatch({ type: "START" });
@@ -501,8 +629,8 @@ function createDeferredTask(options) {
 		pause,
 		resume,
 		cancel,
-		getSnapshot: () => snapshot,
-		getValue: () => value,
+		getSnapshot,
+		getValue: () => settledValue,
 		subscribe(listener) {
 			listeners.add(listener);
 			return () => {
@@ -514,4 +642,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-5kfztF2G.js.map
+//# sourceMappingURL=deferred-task-DkHdsliy.js.map