react-inp-chunker 0.1.1 → 0.2.0

package/README.md

@@ -3,26 +3,42 @@
 [![npm version](https://img.shields.io/npm/v/react-inp-chunker.svg)](https://www.npmjs.com/package/react-inp-chunker)
 [![CI](https://github.com/suprabhat02/react-inp-chunker/actions/workflows/ci.yml/badge.svg)](https://github.com/suprabhat02/react-inp-chunker/actions/workflows/ci.yml)
 
-**Headless React/TypeScript hooks that chunk heavy synchronous work and yield to
-the main thread, so a long update never costs you Interaction to Next Paint (INP).**
-
-Processing a big array, running a multi-phase algorithm, or rendering a large
-canvas frame-by-frame inside a React update blocks the main thread for as long
-as it takes — every click, keypress, and tap queued behind it waits too. This
-package breaks that work into small slices and hands control back to the
-browser between them, using the best yielding primitive the current runtime
-actually has:
-
-1. [`scheduler.yield()`](https://developer.mozilla.org/en-US/docs/Web/API/Scheduler/yield) —
-   the purpose-built API, Baseline across Chromium and Firefox.
-2. `MessageChannel` — not clamped to the ~4ms floor nested `setTimeout` calls
-   get, so it yields sooner.
-3. `setTimeout(0)` — the universal fallback.
-
-No dependencies beyond React itself. Nothing here touches the DOM directly, so
-the scheduling engine (`react-inp-chunker/core`) works just as well outside
-React — a Node script, a Web Worker, anywhere a long synchronous task would
-otherwise block something else.
+**Run heavy JavaScript without freezing your React app.** React/TypeScript hooks
+that split long-running work into slices of a few milliseconds and hand the main
+thread back to the browser between them, so clicks and typing stay responsive and
+Interaction to Next Paint (INP) stays good.
+
+**[Documentation and live playground](https://suprabhat02.github.io/react-inp-chunker/)**:
+run the same work with and without chunking, type while it runs, and see the
+difference measured in your own browser.
+
+## The problem
+
+One thread runs your JavaScript, handles every click and key press, and paints the
+screen. While a function runs, everything else waits. Filter 20,000 rows, parse a
+large CSV or build a search index inside a React component, and a click in that
+window sits in a queue until the function returns. Any task over 50 ms is a _long
+task_, and an interaction that lands in one is the most common way to fail
+[INP](https://web.dev/articles/inp), the Core Web Vital for responsiveness.
+
+## What this does
+
+It doesn't make the work faster. It makes sure the work never holds the main
+thread for more than a few milliseconds at a time: process items until the time
+slice (5 ms by default) is used up, yield so the browser can handle input and
+paint, then carry on where it stopped. It yields with the best tool the browser
+has:
+
+1. [`scheduler.yield()`](https://developer.mozilla.org/en-US/docs/Web/API/Scheduler/yield)
+   in Chrome 129+, Edge 129+ and Firefox 142+. Made for exactly this: the work
+   resumes ahead of other queued tasks.
+2. `MessageChannel` in Safari and older browsers. Not clamped to the ~4 ms floor
+   that nested `setTimeout` calls get.
+3. `setTimeout(0)` as the last resort.
+
+No dependencies beyond React. The scheduling engine (`react-inp-chunker/core`)
+doesn't import React at all, so it also works in plain TypeScript, a Web Worker or
+a Node script.
 
 ## Install
 
@@ -30,47 +46,65 @@ otherwise block something else.
 npm install react-inp-chunker
 ```
 
-Requires React 18 or 19 as a peer dependency.
+Works with React 18 and 19; CI runs the full test suite on both.
 
 ## Usage
 
-### Chunking an array — `useChunkedTask`
+### Process a list: `useChunkedTask`
 
 ```tsx
 import { useChunkedTask } from 'react-inp-chunker';
 
-function RowScorer({ rows }: { rows: Row[] }) {
-  const { status, processed, total, results, isDone, pause, resume, cancel } =
-    useChunkedTask(rows, (row) => expensiveScore(row));
+function ScoredRows({ rows }: { rows: readonly Row[] }) {
+  // scoreRow runs once per row, in slices of up to 5 ms.
+  const task = useChunkedTask(rows, scoreRow);
 
-  if (!isDone) {
-    return (
-      <p>
-        Scoring… {processed}/{total}
-      </p>
-    );
+  if (task.isError) return <p role="alert">Couldn't score the rows.</p>;
+
+  if (!task.isDone || task.results === undefined) {
+    return <progress value={task.processed} max={task.total} aria-label="Scoring rows" />;
   }
 
-  return <ResultsTable rows={results} />;
+  return <ResultsTable scores={task.results} />;
 }
 ```
 
-`processItem` is called once per item, each call in its own chunk, yielding to
-the browser whenever a time slice (5ms by default) runs out or the browser
-reports pending input. Pass a fresh closure every render — it's always the
-latest one that runs, without restarting the task. What _does_ restart it is
-`rows` becoming a new array reference, or `timeSliceMs`/`autoStart` changing.
+Items are processed back to back until the time slice runs out, or until the
+browser reports pending input; then the hook yields, and resumes with the next
+item. Your component re-renders with progress once per slice, not once per item.
+
+- `scoreRow` can be a fresh closure every render: the latest one always runs,
+  without restarting the task.
+- What _does_ restart it is `rows` becoming a new array reference, or
+  `timeSliceMs`/`autoStart` changing. Memoize derived arrays.
+- Pass `{ autoStart: false }` to wait for `start()`, and `onItem` to consume
+  results while the task is still running. `pause()`, `resume()` and `cancel()`
+  work at any point, and unmounting cancels.
+- `results` is `undefined` until the task settles, and is then set in the same
+  render that first reports `done`, `cancelled` or `error` — never a render
+  later, so there is nothing to tear under concurrent React.
+
+Two options exist for work at the extremes, and most code needs neither:
+
+| Option                    | Default | Use it when                                                                                                                                                         |
+| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `batchSize: number`       | `1`     | An item takes nanoseconds, so reading the clock costs more than the work. A slice may then overrun its budget by up to `batchSize` items — that is the whole trade. |
+| `collectResults: boolean` | `true`  | You already take results through `onItem` and don't want a million-entry array retained. `results` settles as an empty array.                                       |
+
+In development, the library measures itself and says so: a single item that
+blocks for over 50 ms gets a warning naming its index, and work cheap enough that
+the clock dominates gets a concrete `batchSize` suggestion. Both are compiled out
+of production builds.
 
-### Chunking arbitrary work — `useDeferredTask`
+### Work that isn't a list: `useDeferredTask`
 
-For work that isn't "one function applied to every item of an array" — a
-multi-phase algorithm, a big canvas render — mark your own safe-to-pause
-checkpoints with a generator:
+For a long computation that isn't one function over an array, write it as a
+generator and put `yield` wherever it's safe to pause:
 
 ```tsx
-import { useDeferredTask } from 'react-inp-chunker';
+import { type DeferredGenerator, useDeferredTask } from 'react-inp-chunker';
 
-function* renderFrames(frameCount: number) {
+function* renderFrames(frameCount: number): DeferredGenerator<number> {
   for (let i = 0; i < frameCount; i++) {
     renderOneExpensiveFrame(i);
     yield; // "it's safe to pause here if we're over budget"
@@ -84,7 +118,7 @@ function FrameRenderer({ frameCount }: { frameCount: number }) {
 }
 ```
 
-### Outside React — `react-inp-chunker/core`
+### Outside React: `react-inp-chunker/core`
 
 ```ts
 import { createChunkScheduler } from 'react-inp-chunker/core';
@@ -98,17 +132,71 @@ const { status, results } = await scheduler.settled;
 ```
 
 Both engines expose `start()`, `pause()`, `resume()`, `cancel()`, a
-`subscribe()`/`getSnapshot()` pair, and a `settled` promise that always
-resolves — never rejects — with `'done' | 'cancelled' | 'error'`. An
-`AbortSignal` can drive cancellation too.
+`subscribe()`/`getSnapshot()` pair, and a `settled` promise that always resolves
+(never rejects) with `'done' | 'cancelled' | 'error'`. An `AbortSignal` can drive
+cancellation too.
+
+The [documentation](https://suprabhat02.github.io/react-inp-chunker/#api) has the
+full API, when to reach for something else (a Web Worker, `startTransition`,
+virtualization), and answers to common questions.
+
+## In production
+
+| What             | Supported                      | Proven by                                                |
+| ---------------- | ------------------------------ | -------------------------------------------------------- |
+| React            | 18 and 19                      | the whole test suite runs on both majors                 |
+| Node             | 18, 20, 22, 24                 | the packed tarball is imported and required on each      |
+| TypeScript       | 5.0 to 7                       | the published declarations compile at both ends          |
+| Module systems   | ESM and CommonJS               | separate builds and declarations, both loaded in CI      |
+| Resolution       | bundler, NodeNext, node10      | `publint` and `are-the-types-wrong` run over the tarball |
+| Browsers         | anything with `MessageChannel` | yielding measured in real Chromium and WebKit            |
+| Server rendering | yes                            | both hooks render an idle state and run nothing          |
+
+Dropping any of these is a breaking change; [SUPPORT.md](SUPPORT.md) has the
+versioning rules.
+
+**Size**, minified and brotli-compressed, with no dependencies of its own:
+`useChunkedTask` 1.83 kB, `useDeferredTask` 1.72 kB, `createChunkScheduler`
+without React 1.34 kB, everything together 2.35 kB. CI fails if a change pushes
+any of them over budget.
+
+Bundlers that set the `production` export condition — webpack, Vite, Rspack,
+Parcel — resolve to a build with the development warnings compiled out, not
+merely guarded by a flag.
+
+**What it guarantees.** A slice overruns by at most one item (or `batchSize`
+items, if you raised it), because the clock is read after every item rather than
+on an average. A settled task never reports its results a render late. Nothing
+runs after `cancel()`, no state update arrives after unmount, and `settled`
+resolves exactly once and never rejects. The loop allocates nothing per item.
+
+**Supply chain.** Published from CI through npm Trusted Publishing, so no
+long-lived token exists to leak, with signed provenance you can verify yourself:
+
+```sh
+npm audit signatures
+gh attestation verify "$(npm pack react-inp-chunker --silent)" \
+  -R suprabhat02/react-inp-chunker
+```
+
+GitHub Actions are pinned to commit SHAs, CI fails on a known vulnerability at
+any severity, and there are no runtime dependencies to audit.
+
+## Quality
 
-## Status
+An exhaustive test suite (state-machine truth table, every yield fallback path,
+slice bounds on a virtual clock, property tests, pause/resume/cancel races,
+reentrancy, SSR safety) at 100% statement, branch, function and line coverage,
+run on React 19 and React 18. On top of that, every push checks the packed
+tarball end to end: imported and required on four Node versions, compiled by two
+TypeScript majors, linted by `publint`, resolved by `are-the-types-wrong`,
+measured for real input delay in Chromium and WebKit, and diffed against a
+golden public API surface so no export changes by accident. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for how the project is organised and verified.
 
-Phase 1 — the core scheduling engine, both hooks, and an exhaustive test
-suite (state-machine truth table, every yield fallback path, pause/resume/
-cancel race conditions, reentrancy, SSR safety) at 100% statement, branch,
-function, and line coverage. See [CONTRIBUTING.md](CONTRIBUTING.md) for how
-the project is organised and verified.
+If react-inp-chunker saves you a long task, a
+[star on GitHub](https://github.com/suprabhat02/react-inp-chunker) helps other
+developers find it.
 
 ## License
 

package/core/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "react-inp-chunker-core",
+  "description": "Resolution shim for `react-inp-chunker/core` under TypeScript's classic (node10) module resolution, which predates the exports map and looks for a directory of this name. Modern resolvers read the exports map in the root package.json and never see this file. Keep the paths below in step with that map.",
+  "private": true,
+  "type": "module",
+  "main": "../dist/core/index.cjs",
+  "module": "../dist/core/index.js",
+  "types": "../dist/core/index.d.ts",
+  "sideEffects": false
+}

package/dist/core/index.cjs

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

package/dist/core/index.d.cts

@@ -1,2 +1,2 @@
-import { C as yieldToMain, D as initialChunkState, E as ChunkStatus, O as isTerminal, S as supportsSchedulerYield, T as ChunkMachineState, _ as now, a as DeferredTaskSnapshot, b as supportsInputPending, c as ChunkSchedulerOptions, d as createChunkScheduler, f as DEFAULT_TIME_SLICE_MS, g as isInputPending, h as YieldToMainOptions, i as DeferredTaskResult, k as transition, l as ChunkSchedulerResult, m as YieldStrategy, n as DeferredTask, o as createDeferredTask, p as ShouldYieldOptions, r as DeferredTaskOptions, s as ChunkScheduler, t as DeferredGenerator, u as ChunkSnapshot, v as resolveYieldStrategy, w as ChunkEvent, x as supportsMessageChannel, y as shouldYieldNow } from "../index-C6B_Nm3i.cjs";
-export { type ChunkEvent, type ChunkMachineState, type ChunkScheduler, type ChunkSchedulerOptions, type ChunkSchedulerResult, type ChunkSnapshot, type ChunkStatus, DEFAULT_TIME_SLICE_MS, type DeferredGenerator, type DeferredTask, type DeferredTaskOptions, type DeferredTaskResult, type DeferredTaskSnapshot, type ShouldYieldOptions, type YieldStrategy, type YieldToMainOptions, createChunkScheduler, createDeferredTask, initialChunkState, isInputPending, isTerminal, now, resolveYieldStrategy, shouldYieldNow, supportsInputPending, supportsMessageChannel, supportsSchedulerYield, transition, yieldToMain };
+import { A as transition, C as yieldToMain, D as TerminalChunkStatus, E as ChunkStatus, O as initialChunkState, S as supportsSchedulerYield, T as ChunkMachineState, _ as now, a as DeferredTaskSnapshot, b as supportsInputPending, c as ChunkSchedulerOptions, d as createChunkScheduler, f as DEFAULT_TIME_SLICE_MS, g as isInputPending, h as YieldToMainOptions, i as DeferredTaskResult, k as isTerminal, l as ChunkSchedulerResult, m as YieldStrategy, n as DeferredTask, o as createDeferredTask, p as ShouldYieldOptions, r as DeferredTaskOptions, s as ChunkScheduler, t as DeferredGenerator, u as ChunkSnapshot, v as resolveYieldStrategy, w as ChunkEvent, x as supportsMessageChannel, y as shouldYieldNow } from "../index-DShDP2VN.cjs";
+export { type ChunkEvent, type ChunkMachineState, type ChunkScheduler, type ChunkSchedulerOptions, type ChunkSchedulerResult, type ChunkSnapshot, type ChunkStatus, DEFAULT_TIME_SLICE_MS, type DeferredGenerator, type DeferredTask, type DeferredTaskOptions, type DeferredTaskResult, type DeferredTaskSnapshot, type ShouldYieldOptions, type TerminalChunkStatus, type YieldStrategy, type YieldToMainOptions, createChunkScheduler, createDeferredTask, initialChunkState, isInputPending, isTerminal, now, resolveYieldStrategy, shouldYieldNow, supportsInputPending, supportsMessageChannel, supportsSchedulerYield, transition, yieldToMain };

package/dist/core/index.d.ts

@@ -1,2 +1,2 @@
-import { C as yieldToMain, D as initialChunkState, E as ChunkStatus, O as isTerminal, S as supportsSchedulerYield, T as ChunkMachineState, _ as now, a as DeferredTaskSnapshot, b as supportsInputPending, c as ChunkSchedulerOptions, d as createChunkScheduler, f as DEFAULT_TIME_SLICE_MS, g as isInputPending, h as YieldToMainOptions, i as DeferredTaskResult, k as transition, l as ChunkSchedulerResult, m as YieldStrategy, n as DeferredTask, o as createDeferredTask, p as ShouldYieldOptions, r as DeferredTaskOptions, s as ChunkScheduler, t as DeferredGenerator, u as ChunkSnapshot, v as resolveYieldStrategy, w as ChunkEvent, x as supportsMessageChannel, y as shouldYieldNow } from "../index-C6B_Nm3i.js";
-export { type ChunkEvent, type ChunkMachineState, type ChunkScheduler, type ChunkSchedulerOptions, type ChunkSchedulerResult, type ChunkSnapshot, type ChunkStatus, DEFAULT_TIME_SLICE_MS, type DeferredGenerator, type DeferredTask, type DeferredTaskOptions, type DeferredTaskResult, type DeferredTaskSnapshot, type ShouldYieldOptions, type YieldStrategy, type YieldToMainOptions, createChunkScheduler, createDeferredTask, initialChunkState, isInputPending, isTerminal, now, resolveYieldStrategy, shouldYieldNow, supportsInputPending, supportsMessageChannel, supportsSchedulerYield, transition, yieldToMain };
+import { A as transition, C as yieldToMain, D as TerminalChunkStatus, E as ChunkStatus, O as initialChunkState, S as supportsSchedulerYield, T as ChunkMachineState, _ as now, a as DeferredTaskSnapshot, b as supportsInputPending, c as ChunkSchedulerOptions, d as createChunkScheduler, f as DEFAULT_TIME_SLICE_MS, g as isInputPending, h as YieldToMainOptions, i as DeferredTaskResult, k as isTerminal, l as ChunkSchedulerResult, m as YieldStrategy, n as DeferredTask, o as createDeferredTask, p as ShouldYieldOptions, r as DeferredTaskOptions, s as ChunkScheduler, t as DeferredGenerator, u as ChunkSnapshot, v as resolveYieldStrategy, w as ChunkEvent, x as supportsMessageChannel, y as shouldYieldNow } from "../index-DShDP2VN.js";
+export { type ChunkEvent, type ChunkMachineState, type ChunkScheduler, type ChunkSchedulerOptions, type ChunkSchedulerResult, type ChunkSnapshot, type ChunkStatus, DEFAULT_TIME_SLICE_MS, type DeferredGenerator, type DeferredTask, type DeferredTaskOptions, type DeferredTaskResult, type DeferredTaskSnapshot, type ShouldYieldOptions, type TerminalChunkStatus, type YieldStrategy, type YieldToMainOptions, createChunkScheduler, createDeferredTask, initialChunkState, isInputPending, isTerminal, now, resolveYieldStrategy, shouldYieldNow, supportsInputPending, supportsMessageChannel, supportsSchedulerYield, transition, yieldToMain };

package/dist/core/index.js

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