@rethunk/react-load-hooks 0.2.0 → 0.3.1

package/README.md

@@ -39,13 +39,13 @@ A worked example and the contracts: [HUMANS.md](HUMANS.md).
 
 ## Documentation
 
-| Doc | Audience |
-| --- | --- |
-| [HUMANS.md](HUMANS.md) | Running and using the package |
-| [AGENTS.md](AGENTS.md) | Internals, invariants, and why |
+| Doc                                | Audience                       |
+| ---------------------------------- | ------------------------------ |
+| [HUMANS.md](HUMANS.md)             | Running and using the package  |
+| [AGENTS.md](AGENTS.md)             | Internals, invariants, and why |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | Process — commits, tests, docs |
-| [SECURITY.md](SECURITY.md) | Vulnerability disclosure |
-| [CHANGELOG.md](CHANGELOG.md) | Release notes |
+| [SECURITY.md](SECURITY.md)         | Vulnerability disclosure       |
+| [CHANGELOG.md](CHANGELOG.md)       | Release notes                  |
 
 ## License
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { coalescer } from './coalescer.ts';
-export { type LoadSink, loader } from './loader.ts';
+export { type Load, type LoadSink, loader } from './loader.ts';
 export { keepFields, keepUnchanged, sameValue } from './sameValue.ts';
 export { useDebouncedLoad } from './useDebouncedLoad.ts';
 export { useDebouncedValue } from './useDebouncedValue.ts';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,KAAK,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC9D,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,KAAK,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC9D,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA"}

package/dist/loader.d.ts

@@ -6,6 +6,8 @@ export interface LoadSink<T> {
     /** Shows the hook's initial value again. */
     reset: () => void;
 }
+/** `signal` aborts when a later load, new deps or stop supersedes this one: pass it to fetch to stop the abandoned work. */
+export type Load<T> = (signal: AbortSignal) => Promise<T>;
 /**
  * useLoaded's and useDebouncedLoad's logic without React. Only the newest load lands: a later load, new deps or stop
  * drops the answer, error and end of every one before it. New deps reset the value unless keepAcrossKeys, and a null
@@ -15,9 +17,9 @@ export declare function loader<T>(sink: LoadSink<T>, { keepAcrossKeys, defer, }?
     keepAcrossKeys?: boolean;
     defer?: (go: () => void) => () => void;
 }): {
-    deps(deps: DependencyList, load: (() => Promise<T>) | null): void;
+    deps(deps: DependencyList, load: Load<T> | null): void;
     /** Runs a load at once with the same deps, keeping the value shown until it answers; resolves when it has. */
-    run(load: (() => Promise<T>) | null): Promise<void>;
+    run(load: Load<T> | null): Promise<void>;
     stop(): void;
 };
 //# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAK3C,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAC/B,OAAO,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAA;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAOD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,EACE,cAAsB,EACtB,KAAW,GACZ,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;CAAO;IAuC1E,IAAI,OAAO,cAAc,QAAQ,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAoB1D,8GAA8G;IAC9G,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnD,IAAI;EAKP"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAK3C,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAC/B,OAAO,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAA;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,4HAA4H;AAC5H,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;AAOzD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,EACE,cAAsB,EACtB,KAAW,GACZ,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;CAAO;IA8C1E,IAAI,OAAO,cAAc,QAAQ,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI;IAoB/C,8GAA8G;IAC9G,GAAG,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxC,IAAI;EAKP"}

package/dist/loader.js

@@ -12,16 +12,23 @@ export function loader(sink, { keepAcrossKeys = false, defer = now, } = {}) {
     let generation = 0;
     let seen = null;
     let cancel = () => undefined;
+    let controller = null;
     const drop = () => {
         generation += 1;
         cancel();
+        controller?.abort();
+        controller = null;
     };
     const start = (load) => {
         generation += 1;
+        controller?.abort();
         const mine = generation;
         const current = () => generation === mine;
+        const mineController = new AbortController();
+        controller = mineController;
         sink.loading(true);
-        return load()
+        // A load that throws before returning a promise settles through the sink like a rejection.
+        return new Promise((resolve) => resolve(load(mineController.signal)))
             .then((value) => {
             if (current()) {
                 sink.value(value);

package/dist/useDebouncedLoad.d.ts

@@ -1,11 +1,12 @@
 import { type DependencyList } from 'react';
+import { type Load } from './loader.ts';
 /**
  * useLoaded for input that changes on every key: `load` runs `delayMs` (read afresh each time a load is scheduled)
  * after `deps` last changed, and `data` keeps the last answer meanwhile. Only the newest run lands, so `onError` hears
  * only the newest failure. A null `load` resets `data` to `initial`. `run` starts another load at once, such as the
  * next page, under the same rule.
  */
-export declare function useDebouncedLoad<T>(load: (() => Promise<T>) | null, deps: DependencyList, { initial, delayMs, onError, }: {
+export declare function useDebouncedLoad<T>(load: Load<T> | null, deps: DependencyList, { initial, delayMs, onError, }: {
     initial: T;
     delayMs: number;
     onError?: (error: unknown) => void;
@@ -13,6 +14,6 @@ export declare function useDebouncedLoad<T>(load: (() => Promise<T>) | null, dep
     data: T;
     loading: boolean;
     error: unknown;
-    run: (next: () => Promise<T>) => Promise<void>;
+    run: (next: Load<T>) => Promise<void>;
 };
 //# sourceMappingURL=useDebouncedLoad.d.ts.map

package/dist/useDebouncedLoad.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDebouncedLoad.d.ts","sourceRoot":"","sources":["../src/useDebouncedLoad.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAA+B,MAAM,OAAO,CAAA;AAGxE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,IAAI,EAAE,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAC/B,IAAI,EAAE,cAAc,EACpB,EACE,OAAO,EACP,OAAO,EACP,OAAO,GACR,EAAE;IAAE,OAAO,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE;;;;gBAwCxD,MAAM,OAAO,CAAC,CAAC,CAAC;EAE/B"}
+{"version":3,"file":"useDebouncedLoad.d.ts","sourceRoot":"","sources":["../src/useDebouncedLoad.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAA+B,MAAM,OAAO,CAAA;AACxE,OAAO,EAAE,KAAK,IAAI,EAAU,MAAM,aAAa,CAAA;AAE/C;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,EACpB,IAAI,EAAE,cAAc,EACpB,EACE,OAAO,EACP,OAAO,EACP,OAAO,GACR,EAAE;IAAE,OAAO,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE;;;;gBAwCxD,IAAI,CAAC,CAAC,CAAC;EAEtB"}

package/dist/useLoaded.d.ts

@@ -1,4 +1,5 @@
 import { type DependencyList } from 'react';
+import { type Load } from './loader.ts';
 export interface LoadedOptions {
     onError?: (error: unknown) => void;
     /** Keep `data` across new deps until the new answer lands. */
@@ -11,7 +12,7 @@ export interface LoadedOptions {
  * `setData` edits the loaded value in place. The fourth argument is `onError` or `{ onError, keepAcrossKeys }`. With `keepAcrossKeys`, new deps keep `data` until the new answer lands
  * (a null load still resets it).
  */
-export declare function useLoaded<T>(load: (() => Promise<T>) | null, deps: DependencyList, initial: T, options?: ((error: unknown) => void) | LoadedOptions): {
+export declare function useLoaded<T>(load: Load<T> | null, deps: DependencyList, initial: T, options?: ((error: unknown) => void) | LoadedOptions): {
     data: T;
     setData: import("react").Dispatch<import("react").SetStateAction<T>>;
     loading: boolean;

package/dist/useLoaded.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLoaded.d.ts","sourceRoot":"","sources":["../src/useLoaded.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAA4C,MAAM,OAAO,CAAA;AAGrF,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAClC,8DAA8D;IAC9D,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,IAAI,EAAE,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAC/B,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,aAAa;;;;;;EAoCrD"}
+{"version":3,"file":"useLoaded.d.ts","sourceRoot":"","sources":["../src/useLoaded.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAA4C,MAAM,OAAO,CAAA;AACrF,OAAO,EAAE,KAAK,IAAI,EAAU,MAAM,aAAa,CAAA;AAE/C,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAClC,8DAA8D;IAC9D,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,EACpB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,aAAa;;;;;;EAoCrD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rethunk/react-load-hooks",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "React hooks for async loads that never land out of order, plus the small state hooks an app builds screens from.",
   "license": "MIT",
   "author": "Rethunk.Tech, LLC",
@@ -29,7 +29,7 @@
     "pack:check": "bun scripts/check-pack.ts"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.6.4",
+    "@biomejs/biome": "^2.6.6",
     "@happy-dom/global-registrator": "^21.0.4",
     "@testing-library/dom": "^10.4.2",
     "@testing-library/react": "^16.3.3",

package/src/index.ts

@@ -1,5 +1,5 @@
 export { coalescer } from './coalescer.ts'
-export { type LoadSink, loader } from './loader.ts'
+export { type Load, type LoadSink, loader } from './loader.ts'
 export { keepFields, keepUnchanged, sameValue } from './sameValue.ts'
 export { useDebouncedLoad } from './useDebouncedLoad.ts'
 export { useDebouncedValue } from './useDebouncedValue.ts'

package/src/loader.ts

@@ -11,6 +11,9 @@ export interface LoadSink<T> {
   reset: () => void
 }
 
+/** `signal` aborts when a later load, new deps or stop supersedes this one: pass it to fetch to stop the abandoned work. */
+export type Load<T> = (signal: AbortSignal) => Promise<T>
+
 const now = (go: () => void) => {
   go()
   return () => undefined
@@ -31,16 +34,23 @@ export function loader<T>(
   let generation = 0
   let seen: DependencyList | null = null
   let cancel: () => void = () => undefined
+  let controller: AbortController | null = null
   const drop = () => {
     generation += 1
     cancel()
+    controller?.abort()
+    controller = null
   }
-  const start = (load: () => Promise<T>): Promise<void> => {
+  const start = (load: Load<T>): Promise<void> => {
     generation += 1
+    controller?.abort()
     const mine = generation
     const current = () => generation === mine
+    const mineController = new AbortController()
+    controller = mineController
     sink.loading(true)
-    return load()
+    // A load that throws before returning a promise settles through the sink like a rejection.
+    return new Promise<T>((resolve) => resolve(load(mineController.signal)))
       .then(
         (value) => {
           if (current()) {
@@ -65,7 +75,7 @@ export function loader<T>(
     sink.loading(false)
   }
   return {
-    deps(deps: DependencyList, load: (() => Promise<T>) | null) {
+    deps(deps: DependencyList, load: Load<T> | null) {
       if (sameDeps(seen, deps)) {
         return
       }
@@ -86,7 +96,7 @@ export function loader<T>(
       })
     },
     /** Runs a load at once with the same deps, keeping the value shown until it answers; resolves when it has. */
-    run(load: (() => Promise<T>) | null): Promise<void> {
+    run(load: Load<T> | null): Promise<void> {
       if (load === null) {
         skip()
         return Promise.resolve()

package/src/useDebouncedLoad.ts

@@ -1,5 +1,5 @@
 import { type DependencyList, useEffect, useRef, useState } from 'react'
-import { loader } from './loader.ts'
+import { type Load, loader } from './loader.ts'
 
 /**
  * useLoaded for input that changes on every key: `load` runs `delayMs` (read afresh each time a load is scheduled)
@@ -8,7 +8,7 @@ import { loader } from './loader.ts'
  * next page, under the same rule.
  */
 export function useDebouncedLoad<T>(
-  load: (() => Promise<T>) | null,
+  load: Load<T> | null,
   deps: DependencyList,
   {
     initial,
@@ -54,6 +54,6 @@ export function useDebouncedLoad<T>(
     data,
     loading,
     error,
-    run: (next: () => Promise<T>) => runs.run(next),
+    run: (next: Load<T>) => runs.run(next),
   }
 }

package/src/useLoaded.ts

@@ -1,5 +1,5 @@
 import { type DependencyList, useCallback, useEffect, useRef, useState } from 'react'
-import { loader } from './loader.ts'
+import { type Load, loader } from './loader.ts'
 
 export interface LoadedOptions {
   onError?: (error: unknown) => void
@@ -15,7 +15,7 @@ export interface LoadedOptions {
  * (a null load still resets it).
  */
 export function useLoaded<T>(
-  load: (() => Promise<T>) | null,
+  load: Load<T> | null,
   deps: DependencyList,
   initial: T,
   options?: ((error: unknown) => void) | LoadedOptions,