@rethunk/react-load-hooks 0.1.1 → 0.3.0

package/README.md

@@ -33,6 +33,8 @@ A worked example and the contracts: [HUMANS.md](HUMANS.md).
 - `loader` is the same logic without React, for a store or a class.
 - `useStoredState` persists UI state in `localStorage`.
 - `useWidth` tracks an element's width before paint; `useDebouncedValue` settles a fast-changing value.
+- `sameValue`, `keepUnchanged` and `keepFields` keep the stored value when a fresh backend answer is equal, so subscribers do not re-render.
+- `clockWhen`, `absoluteWhen` and `relativeWhen` label a time through `Intl`: "3 minutes ago" within a week, a date after.
 - `useNowValue` and `useSecondValue` share one timer per period and re-render only on a changed answer.
 
 ## Documentation

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 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';
 export { type LoadedOptions, useLoaded } from './useLoaded.ts';
 export { useNowValue, useSecondValue } from './useNow.ts';
 export { readStored, useStoredState, writeStored } from './useStoredState.ts';
 export { useWidth } from './useWidth.ts';
+export { absoluteWhen, clockWhen, relativeWhen, type WhenOptions } from './when.ts';
 //# sourceMappingURL=index.d.ts.map

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,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"}
+{"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/index.js

@@ -1,8 +1,10 @@
 export { coalescer } from './coalescer.js';
 export { loader } from './loader.js';
+export { keepFields, keepUnchanged, sameValue } from './sameValue.js';
 export { useDebouncedLoad } from './useDebouncedLoad.js';
 export { useDebouncedValue } from './useDebouncedValue.js';
 export { useLoaded } from './useLoaded.js';
 export { useNowValue, useSecondValue } from './useNow.js';
 export { readStored, useStoredState, writeStored } from './useStoredState.js';
 export { useWidth } from './useWidth.js';
+export { absoluteWhen, clockWhen, relativeWhen } from './when.js';

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;IA6C1E,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,22 @@ 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()
+        return load(mineController.signal)
             .then((value) => {
             if (current()) {
                 sink.value(value);

package/dist/sameValue.d.ts

@@ -0,0 +1,7 @@
+export declare function sameValue(a: unknown, b: unknown): boolean;
+/** next, with each item equal to the previous item of the same key replaced by that previous object. */
+export declare function keepUnchanged<T>(prev: readonly T[], next: T[], keyOf: (item: T) => string): T[];
+/** next, with each field equal to the same field of prev kept as prev's value, so a selector of an unchanged field
+ * keeps returning the same object. */
+export declare function keepFields<T extends object>(prev: T, next: T): T;
+//# sourceMappingURL=sameValue.d.ts.map

package/dist/sameValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sameValue.d.ts","sourceRoot":"","sources":["../src/sameValue.ts"],"names":[],"mappings":"AAGA,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,CAAC,EAAE,CAS/F;AAED;sCACsC;AACtC,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAQhE"}

package/dist/sameValue.js

@@ -0,0 +1,27 @@
+// Backend answers arrive as fresh objects even when nothing changed; storing one as-is re-renders every subscriber
+// and defeats memoised rows. These keep the stored value whenever the answer is equal to it.
+export function sameValue(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+/** next, with each item equal to the previous item of the same key replaced by that previous object. */
+export function keepUnchanged(prev, next, keyOf) {
+    const old = new Map(prev.map((item) => [keyOf(item), item]));
+    const kept = next.map((item) => {
+        const was = old.get(keyOf(item));
+        return was !== undefined && sameValue(was, item) ? was : item;
+    });
+    return kept.length === prev.length && kept.every((item, i) => item === prev[i])
+        ? prev
+        : kept;
+}
+/** next, with each field equal to the same field of prev kept as prev's value, so a selector of an unchanged field
+ * keeps returning the same object. */
+export function keepFields(prev, next) {
+    const out = { ...next };
+    for (const k of Object.keys(next)) {
+        if (sameValue(prev[k], next[k])) {
+            out[k] = prev[k];
+        }
+    }
+    return out;
+}

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/dist/when.d.ts

@@ -0,0 +1,11 @@
+export interface WhenOptions {
+    withTime?: boolean;
+    now?: number;
+    locale?: string;
+    fewSeconds?: string;
+    absolute?: boolean;
+}
+export declare function clockWhen(value: string | number | Date, locale?: string): string;
+export declare function absoluteWhen(value: string | number | Date, locale?: string): string;
+export declare function relativeWhen(value: string | number | Date, { withTime, now, locale, fewSeconds, absolute, }?: WhenOptions): string;
+//# sourceMappingURL=when.d.ts.map

package/dist/when.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"when.d.ts","sourceRoot":"","sources":["../src/when.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAGD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EAAE,MAAM,SAAO,GAAG,MAAM,CAG9E;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EAAE,MAAM,SAAO,GAAG,MAAM,CASjF;AAID,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EAC7B,EACE,QAAgB,EAChB,GAAgB,EAChB,MAAa,EACb,UAAgC,EAChC,QAAgB,GACjB,GAAE,WAAgB,GAClB,MAAM,CA6BR"}

package/dist/when.js

@@ -0,0 +1,60 @@
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const DAYS_PER_WEEK = 7;
+const WEEK = DAYS_PER_WEEK * DAY;
+const FIRST_YEAR = 1970;
+function parseWhen(value) {
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime()) || d.getUTCFullYear() < FIRST_YEAR) {
+        return undefined;
+    }
+    return d;
+}
+// clockWhen is the time of day as the locale writes it ("9:05 AM", "09:05"), '' for a zero or unparseable time.
+export function clockWhen(value, locale = 'en') {
+    const d = parseWhen(value);
+    return d ? new Intl.DateTimeFormat(locale, { timeStyle: 'short' }).format(d) : '';
+}
+export function absoluteWhen(value, locale = 'en') {
+    const d = parseWhen(value);
+    if (!d) {
+        return '';
+    }
+    return new Intl.DateTimeFormat(locale, {
+        dateStyle: 'medium',
+        timeStyle: 'short',
+    }).format(d);
+}
+// relativeWhen reads a moment as "3 minutes ago" or "yesterday" within the last week and as a date before that,
+// with the time too when withTime is set. A zero or unparseable time gives ''.
+export function relativeWhen(value, { withTime = false, now = Date.now(), locale = 'en', fewSeconds = 'a few seconds ago', absolute = false, } = {}) {
+    const d = parseWhen(value);
+    if (!d) {
+        return '';
+    }
+    if (absolute) {
+        return new Intl.DateTimeFormat(locale, {
+            dateStyle: 'medium',
+            ...(withTime ? { timeStyle: 'short' } : {}),
+        }).format(d);
+    }
+    const elapsed = now - d.getTime();
+    if (elapsed > -MINUTE && elapsed < MINUTE) {
+        return fewSeconds;
+    }
+    if (elapsed >= MINUTE && elapsed < WEEK) {
+        const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+        if (elapsed < HOUR) {
+            return rtf.format(-Math.floor(elapsed / MINUTE), 'minute');
+        }
+        if (elapsed < DAY) {
+            return rtf.format(-Math.floor(elapsed / HOUR), 'hour');
+        }
+        return rtf.format(-Math.floor(elapsed / DAY), 'day');
+    }
+    return new Intl.DateTimeFormat(locale, {
+        dateStyle: 'medium',
+        ...(withTime ? { timeStyle: 'short' } : {}),
+    }).format(d);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rethunk/react-load-hooks",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "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",

package/src/index.ts

@@ -1,8 +1,10 @@
 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'
 export { type LoadedOptions, useLoaded } from './useLoaded.ts'
 export { useNowValue, useSecondValue } from './useNow.ts'
 export { readStored, useStoredState, writeStored } from './useStoredState.ts'
 export { useWidth } from './useWidth.ts'
+export { absoluteWhen, clockWhen, relativeWhen, type WhenOptions } from './when.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,22 @@ 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()
+    return load(mineController.signal)
       .then(
         (value) => {
           if (current()) {
@@ -65,7 +74,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 +95,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/sameValue.ts

@@ -0,0 +1,30 @@
+// Backend answers arrive as fresh objects even when nothing changed; storing one as-is re-renders every subscriber
+// and defeats memoised rows. These keep the stored value whenever the answer is equal to it.
+
+export function sameValue(a: unknown, b: unknown): boolean {
+  return a === b || JSON.stringify(a) === JSON.stringify(b)
+}
+
+/** next, with each item equal to the previous item of the same key replaced by that previous object. */
+export function keepUnchanged<T>(prev: readonly T[], next: T[], keyOf: (item: T) => string): T[] {
+  const old = new Map(prev.map((item) => [keyOf(item), item]))
+  const kept = next.map((item) => {
+    const was = old.get(keyOf(item))
+    return was !== undefined && sameValue(was, item) ? was : item
+  })
+  return kept.length === prev.length && kept.every((item, i) => item === prev[i])
+    ? (prev as T[])
+    : kept
+}
+
+/** next, with each field equal to the same field of prev kept as prev's value, so a selector of an unchanged field
+ * keeps returning the same object. */
+export function keepFields<T extends object>(prev: T, next: T): T {
+  const out = { ...next }
+  for (const k of Object.keys(next) as (keyof T)[]) {
+    if (sameValue(prev[k], next[k])) {
+      out[k] = prev[k]
+    }
+  }
+  return out
+}

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,

package/src/when.ts

@@ -0,0 +1,82 @@
+const MINUTE = 60_000
+const HOUR = 60 * MINUTE
+const DAY = 24 * HOUR
+const DAYS_PER_WEEK = 7
+const WEEK = DAYS_PER_WEEK * DAY
+const FIRST_YEAR = 1970
+
+function parseWhen(value: string | number | Date): Date | undefined {
+  const d = new Date(value)
+  if (Number.isNaN(d.getTime()) || d.getUTCFullYear() < FIRST_YEAR) {
+    return undefined
+  }
+  return d
+}
+
+export interface WhenOptions {
+  withTime?: boolean
+  now?: number
+  locale?: string
+  // The translated text for under a minute ago, which Intl words as "now".
+  fewSeconds?: string
+  absolute?: boolean
+}
+
+// clockWhen is the time of day as the locale writes it ("9:05 AM", "09:05"), '' for a zero or unparseable time.
+export function clockWhen(value: string | number | Date, locale = 'en'): string {
+  const d = parseWhen(value)
+  return d ? new Intl.DateTimeFormat(locale, { timeStyle: 'short' }).format(d) : ''
+}
+
+export function absoluteWhen(value: string | number | Date, locale = 'en'): string {
+  const d = parseWhen(value)
+  if (!d) {
+    return ''
+  }
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: 'medium',
+    timeStyle: 'short',
+  }).format(d)
+}
+
+// relativeWhen reads a moment as "3 minutes ago" or "yesterday" within the last week and as a date before that,
+// with the time too when withTime is set. A zero or unparseable time gives ''.
+export function relativeWhen(
+  value: string | number | Date,
+  {
+    withTime = false,
+    now = Date.now(),
+    locale = 'en',
+    fewSeconds = 'a few seconds ago',
+    absolute = false,
+  }: WhenOptions = {},
+): string {
+  const d = parseWhen(value)
+  if (!d) {
+    return ''
+  }
+  if (absolute) {
+    return new Intl.DateTimeFormat(locale, {
+      dateStyle: 'medium',
+      ...(withTime ? { timeStyle: 'short' as const } : {}),
+    }).format(d)
+  }
+  const elapsed = now - d.getTime()
+  if (elapsed > -MINUTE && elapsed < MINUTE) {
+    return fewSeconds
+  }
+  if (elapsed >= MINUTE && elapsed < WEEK) {
+    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })
+    if (elapsed < HOUR) {
+      return rtf.format(-Math.floor(elapsed / MINUTE), 'minute')
+    }
+    if (elapsed < DAY) {
+      return rtf.format(-Math.floor(elapsed / HOUR), 'hour')
+    }
+    return rtf.format(-Math.floor(elapsed / DAY), 'day')
+  }
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: 'medium',
+    ...(withTime ? { timeStyle: 'short' as const } : {}),
+  }).format(d)
+}