@rethunk/react-load-hooks 0.1.0 → 0.2.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/coalescer.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runs one slow task per key at a time: an ask made while one runs waits for it and then runs once more, however many
+ * ask meanwhile, so a result is never older than its ask but identical slow calls do not pile up.
+ */
+export declare function coalescer(): (key: string, run: () => Promise<void>) => Promise<void>;
+//# sourceMappingURL=coalescer.d.ts.map

package/dist/coalescer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalescer.d.ts","sourceRoot":"","sources":["../src/coalescer.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,wBAAgB,SAAS,UAaV,MAAM,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,IAAI,CAAC,CAQ9D"}

package/dist/coalescer.js

@@ -0,0 +1,27 @@
+const ignore = () => undefined;
+/**
+ * Runs one slow task per key at a time: an ask made while one runs waits for it and then runs once more, however many
+ * ask meanwhile, so a result is never older than its ask but identical slow calls do not pile up.
+ */
+export function coalescer() {
+    const running = new Map();
+    const start = (key, run) => {
+        const p = run();
+        const slot = { settled: Promise.resolve(), next: null };
+        slot.settled = p.then(ignore, ignore).then(() => {
+            if (running.get(key) === slot) {
+                running.delete(key);
+            }
+        });
+        running.set(key, slot);
+        return p;
+    };
+    return (key, run) => {
+        const slot = running.get(key);
+        if (!slot) {
+            return start(key, run);
+        }
+        slot.next ??= slot.settled.then(() => start(key, run));
+        return slot.next;
+    };
+}

package/dist/index.d.ts

@@ -1,8 +1,11 @@
+export { coalescer } from './coalescer.ts';
 export { type LoadSink, loader } from './loader.ts';
+export { keepFields, keepUnchanged, sameValue } from './sameValue.ts';
 export { useDebouncedLoad } from './useDebouncedLoad.ts';
 export { useDebouncedValue } from './useDebouncedValue.ts';
-export { useLoaded } from './useLoaded.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,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,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,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,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"}

package/dist/index.js

@@ -1,7 +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/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/useLoaded.d.ts

@@ -1,11 +1,17 @@
 import { type DependencyList } from 'react';
+export interface LoadedOptions {
+    onError?: (error: unknown) => void;
+    /** Keep `data` across new deps until the new answer lands. */
+    keepAcrossKeys?: boolean;
+}
 /**
  * Runs `load` whenever `deps` change (never while `load` is null) and drops the answer of any run that has been
  * superseded or unmounted. New deps and a null load reset `data` to `initial`; a failed load keeps the last good `data`
  * and sets `error`. `reload` runs it again with the same deps and keeps the old value until the answer arrives;
- * `setData` edits the loaded value in place.
+ * `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, onError?: (error: unknown) => void): {
+export declare function useLoaded<T>(load: (() => Promise<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;;;;;GAKG;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,KAAK,EAAE,OAAO,KAAK,IAAI;;;;;;EA+BnC"}
+{"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"}

package/dist/useLoaded.js

@@ -4,9 +4,11 @@ import { loader } from './loader.js';
  * Runs `load` whenever `deps` change (never while `load` is null) and drops the answer of any run that has been
  * superseded or unmounted. New deps and a null load reset `data` to `initial`; a failed load keeps the last good `data`
  * and sets `error`. `reload` runs it again with the same deps and keeps the old value until the answer arrives;
- * `setData` edits the loaded value in place.
+ * `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 function useLoaded(load, deps, initial, onError) {
+export function useLoaded(load, deps, initial, options) {
+    const { onError, keepAcrossKeys = false } = typeof options === 'function' ? { onError: options } : (options ?? {});
     const [data, setData] = useState(initial);
     const [loading, setLoading] = useState(load !== null);
     const [error, setError] = useState(null);
@@ -25,7 +27,7 @@ export function useLoaded(load, deps, initial, onError) {
             }
         },
         reset: () => setData(() => latest.current.initial),
-    }));
+    }, { keepAcrossKeys }));
     // Runs after every render and starts a load only when the caller's deps changed: an effect cannot take a
     // caller-supplied dependency list.
     useEffect(() => {

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.0",
+  "version": "0.2.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/coalescer.ts

@@ -0,0 +1,34 @@
+interface Slot {
+  settled: Promise<void>
+  // The follow-up run asked for while this one runs, shared by every later asker.
+  next: Promise<void> | null
+}
+
+const ignore = () => undefined
+
+/**
+ * Runs one slow task per key at a time: an ask made while one runs waits for it and then runs once more, however many
+ * ask meanwhile, so a result is never older than its ask but identical slow calls do not pile up.
+ */
+export function coalescer() {
+  const running = new Map<string, Slot>()
+  const start = (key: string, run: () => Promise<void>): Promise<void> => {
+    const p = run()
+    const slot: Slot = { settled: Promise.resolve(), next: null }
+    slot.settled = p.then(ignore, ignore).then(() => {
+      if (running.get(key) === slot) {
+        running.delete(key)
+      }
+    })
+    running.set(key, slot)
+    return p
+  }
+  return (key: string, run: () => Promise<void>): Promise<void> => {
+    const slot = running.get(key)
+    if (!slot) {
+      return start(key, run)
+    }
+    slot.next ??= slot.settled.then(() => start(key, run))
+    return slot.next
+  }
+}

package/src/index.ts

@@ -1,7 +1,10 @@
+export { coalescer } from './coalescer.ts'
 export { type LoadSink, loader } from './loader.ts'
+export { keepFields, keepUnchanged, sameValue } from './sameValue.ts'
 export { useDebouncedLoad } from './useDebouncedLoad.ts'
 export { useDebouncedValue } from './useDebouncedValue.ts'
-export { useLoaded } from './useLoaded.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/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/useLoaded.ts

@@ -1,38 +1,50 @@
 import { type DependencyList, useCallback, useEffect, useRef, useState } from 'react'
 import { loader } from './loader.ts'
 
+export interface LoadedOptions {
+  onError?: (error: unknown) => void
+  /** Keep `data` across new deps until the new answer lands. */
+  keepAcrossKeys?: boolean
+}
+
 /**
  * Runs `load` whenever `deps` change (never while `load` is null) and drops the answer of any run that has been
  * superseded or unmounted. New deps and a null load reset `data` to `initial`; a failed load keeps the last good `data`
  * and sets `error`. `reload` runs it again with the same deps and keeps the old value until the answer arrives;
- * `setData` edits the loaded value in place.
+ * `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 function useLoaded<T>(
   load: (() => Promise<T>) | null,
   deps: DependencyList,
   initial: T,
-  onError?: (error: unknown) => void,
+  options?: ((error: unknown) => void) | LoadedOptions,
 ) {
+  const { onError, keepAcrossKeys = false } =
+    typeof options === 'function' ? { onError: options } : (options ?? {})
   const [data, setData] = useState(initial)
   const [loading, setLoading] = useState(load !== null)
   const [error, setError] = useState<unknown>(null)
   const latest = useRef({ load, initial, onError })
   latest.current = { load, initial, onError }
   const [runs] = useState(() =>
-    loader<T>({
-      value: (value) => setData(() => value),
-      error: (e) => {
-        setError(e)
-        latest.current.onError?.(e)
-      },
-      loading: (on) => {
-        setLoading(on)
-        if (on) {
-          setError(null)
-        }
+    loader<T>(
+      {
+        value: (value) => setData(() => value),
+        error: (e) => {
+          setError(e)
+          latest.current.onError?.(e)
+        },
+        loading: (on) => {
+          setLoading(on)
+          if (on) {
+            setError(null)
+          }
+        },
+        reset: () => setData(() => latest.current.initial),
       },
-      reset: () => setData(() => latest.current.initial),
-    }),
+      { keepAcrossKeys },
+    ),
   )
   // Runs after every render and starts a load only when the caller's deps changed: an effect cannot take a
   // caller-supplied dependency list.

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)
+}

package/src/loader.test.ts

@@ -1,78 +0,0 @@
-import { expect, test } from 'bun:test'
-import { loader } from './loader.ts'
-
-const flush = () => new Promise<void>((resolve) => setTimeout(resolve, 0))
-
-function harness(keepAcrossKeys: boolean) {
-  const log: string[] = []
-  const pending: (() => void)[] = []
-  const runs = loader<string>(
-    {
-      value: (v) => log.push(`value ${v}`),
-      error: (e) => log.push(`error ${String(e)}`),
-      loading: (on) => log.push(on ? 'loading' : 'idle'),
-      reset: () => log.push('reset'),
-    },
-    {
-      keepAcrossKeys,
-      // A deferred start waits in `pending` until the test runs it; cancelling empties its slot.
-      defer: (go) => {
-        const i = pending.push(go) - 1
-        return () => {
-          pending[i] = () => undefined
-        }
-      },
-    },
-  )
-  return { log, pending, runs }
-}
-
-// The branches useLoaded and useDebouncedLoad share: a superseded answer and error are dropped, new deps reset or keep
-// the value, a null load resets, a start cancelled by new deps never runs, and stop drops what is in flight.
-test('only the newest load lands', async () => {
-  for (const keep of [false, true]) {
-    const { log, pending, runs } = harness(keep)
-    const a = Promise.withResolvers<string>()
-    const b = Promise.withResolvers<string>()
-    runs.deps(['a'], () => a.promise)
-    runs.deps(['a'], () => b.promise)
-    expect(pending).toHaveLength(1)
-    pending[0]?.()
-    runs.deps(['b'], () => b.promise)
-    pending[1]?.()
-    b.resolve('b')
-    a.reject(new Error('a failed'))
-    await flush()
-    expect(log).toEqual([
-      'loading',
-      'loading',
-      ...(keep ? [] : ['reset']),
-      'loading',
-      'loading',
-      'value b',
-      'idle',
-    ])
-
-    log.length = 0
-    const c = Promise.withResolvers<string>()
-    const older = runs.run(() => c.promise)
-    const newest = runs.run(() => Promise.reject(new Error('newest')))
-    c.resolve('c')
-    await Promise.all([older, newest])
-    expect(log).toEqual(['loading', 'loading', 'error Error: newest', 'idle'])
-
-    log.length = 0
-    runs.deps(['c'], () => c.promise)
-    runs.deps(['d'], null)
-    pending.at(-1)?.()
-    await flush()
-    expect(log).toEqual([...(keep ? [] : ['reset']), 'loading', 'reset', 'idle'])
-
-    log.length = 0
-    await runs.run(null)
-    const late = runs.run(() => Promise.resolve('late'))
-    runs.stop()
-    await late
-    expect(log).toEqual(['reset', 'idle', 'loading'])
-  }
-})

package/src/useDebouncedLoad.test.ts

@@ -1,26 +0,0 @@
-import { afterAll, expect, test } from 'bun:test'
-
-const testing = await import('@testing-library/react')
-const { useDebouncedLoad } = await import('./useDebouncedLoad.ts')
-
-afterAll(() => {
-  testing.cleanup()
-})
-
-const sleep = (ms: number) => testing.act(async () => new Promise<void>((r) => setTimeout(r, ms)))
-
-test('a delayMs that changes between renders applies to the next scheduled load', async () => {
-  const view = testing.renderHook(
-    ({ key, delayMs }) =>
-      useDebouncedLoad(() => Promise.resolve(key), [key], { initial: '', delayMs }),
-    { initialProps: { key: 'a', delayMs: 1 } },
-  )
-  await sleep(20)
-  expect(view.result.current.data).toBe('a')
-
-  view.rerender({ key: 'b', delayMs: 150 })
-  await sleep(40)
-  expect(view.result.current.data).toBe('a')
-  await sleep(200)
-  expect(view.result.current.data).toBe('b')
-})

package/src/useLoaded.test.tsx

@@ -1,125 +0,0 @@
-import { afterAll, expect, test } from 'bun:test'
-
-const testing = await import('@testing-library/react')
-const { useLoaded } = await import('./useLoaded.ts')
-
-afterAll(() => {
-  testing.cleanup()
-})
-
-// Flushes pending promises inside act, so the state update they make renders before the test reads it.
-const settle = () => testing.act(async () => new Promise<void>((resolve) => setTimeout(resolve, 0)))
-
-function deferred<T>() {
-  let resolve: (v: T) => void = () => undefined
-  let reject: (e: unknown) => void = () => undefined
-  const promise = new Promise<T>((res, rej) => {
-    resolve = res
-    reject = rej
-  })
-  return { promise, resolve, reject }
-}
-
-test('loads, then reloads with the same deps', async () => {
-  let n = 0
-  const next = () => {
-    n += 1
-    return Promise.resolve(n)
-  }
-  const { result } = testing.renderHook(() => useLoaded(next, [], 0))
-  expect(result.current.loading).toBe(true)
-  await settle()
-  expect(result.current.data).toBe(1)
-  expect(result.current.loading).toBe(false)
-  await testing.act(() => result.current.reload())
-  await settle()
-  expect(result.current.data).toBe(2)
-})
-
-test('a run superseded by new deps is dropped', async () => {
-  const first = deferred<string>()
-  const second = deferred<string>()
-  const { result, rerender } = testing.renderHook(
-    ({ key }) => useLoaded(() => (key === 'a' ? first.promise : second.promise), [key], ''),
-    { initialProps: { key: 'a' } },
-  )
-  rerender({ key: 'b' })
-  second.resolve('b')
-  await settle()
-  expect(result.current.data).toBe('b')
-  first.resolve('a')
-  await testing.act(() => first.promise)
-  expect(result.current.data).toBe('b')
-})
-
-test('an answer after unmount is ignored and errors reach onError once', async () => {
-  const late = deferred<string>()
-  const seen: unknown[] = []
-  const gone = testing.renderHook(() =>
-    useLoaded(
-      () => late.promise,
-      [],
-      '',
-      (e) => seen.push(e),
-    ),
-  )
-  gone.unmount()
-  late.reject(new Error('late'))
-  await late.promise.catch(() => undefined)
-  expect(seen).toEqual([])
-
-  const boom = new Error('boom')
-  const { result } = testing.renderHook(() =>
-    useLoaded(
-      () => Promise.reject(boom),
-      [],
-      'fallback',
-      (e) => seen.push(e),
-    ),
-  )
-  await settle()
-  expect(result.current.error).toBe(boom)
-  expect(result.current.data).toBe('fallback')
-  expect(result.current.loading).toBe(false)
-  expect(seen).toEqual([boom])
-})
-
-test('new deps clear the old answer until the new one arrives', async () => {
-  const second = deferred<string>()
-  const { result, rerender } = testing.renderHook(
-    ({ key }) => useLoaded(() => (key === 'a' ? Promise.resolve('a') : second.promise), [key], ''),
-    { initialProps: { key: 'a' } },
-  )
-  await settle()
-  expect(result.current.data).toBe('a')
-  rerender({ key: 'b' })
-  await settle()
-  expect(result.current.data).toBe('')
-  second.resolve('b')
-  await settle()
-  expect(result.current.data).toBe('b')
-})
-
-test('a null loader never runs', () => {
-  const { result } = testing.renderHook(() => useLoaded<number>(null, [], 7))
-  expect(result.current).toMatchObject({ data: 7, loading: false })
-})
-
-test('a failed reload keeps the last good data', async () => {
-  let fail: boolean
-  fail = false
-  const { result } = testing.renderHook(() =>
-    useLoaded(
-      () => (fail ? Promise.reject(new Error('offline')) : Promise.resolve('good')),
-      [],
-      '',
-    ),
-  )
-  await settle()
-  expect(result.current.data).toBe('good')
-  fail = true
-  await testing.act(() => result.current.reload())
-  await settle()
-  expect(result.current.data).toBe('good')
-  expect(result.current.error).toBeInstanceOf(Error)
-})

package/src/useNow.test.ts

@@ -1,58 +0,0 @@
-import { afterAll, afterEach, beforeEach, expect, jest, setSystemTime, test } from 'bun:test'
-
-const testing = await import('@testing-library/react')
-const { useNowValue, useSecondValue } = await import('./useNow.ts')
-
-beforeEach(() => {
-  jest.useFakeTimers()
-  setSystemTime(new Date('2026-01-01T00:00:00Z'))
-})
-afterEach(() => {
-  testing.cleanup()
-  jest.useRealTimers()
-  setSystemTime()
-})
-afterAll(() => {
-  testing.cleanup()
-})
-
-test('a watcher re-renders only when its answer changes, and the clock stops with the last one', () => {
-  let renders = 0
-  const view = testing.renderHook(() => {
-    renders += 1
-    return useSecondValue((now) => Math.floor(now / 10_000), true)
-  })
-  const first = view.result.current
-  const afterMount = renders
-
-  testing.act(() => {
-    setSystemTime(new Date('2026-01-01T00:00:03Z'))
-    jest.advanceTimersByTime(3000)
-  })
-  expect(view.result.current).toBe(first)
-  expect(renders).toBe(afterMount)
-
-  testing.act(() => {
-    setSystemTime(new Date('2026-01-01T00:00:10Z'))
-    jest.advanceTimersByTime(7000)
-  })
-  expect(view.result.current).toBe(first + 1)
-
-  view.unmount()
-  expect(jest.getTimerCount()).toBe(0)
-})
-
-test('the minute clock ticks once for every watcher and is idle when none is left', () => {
-  const a = testing.renderHook(() => useNowValue((now) => Math.floor(now / 60_000)))
-  const b = testing.renderHook(() => useNowValue((now) => Math.floor(now / 60_000)))
-  expect(jest.getTimerCount()).toBe(1)
-  a.unmount()
-  expect(jest.getTimerCount()).toBe(1)
-  b.unmount()
-  expect(jest.getTimerCount()).toBe(0)
-})
-
-test('a clock switched off never ticks', () => {
-  testing.renderHook(() => useSecondValue(() => 'off', false))
-  expect(jest.getTimerCount()).toBe(0)
-})

package/src/useStoredState.test.ts

@@ -1,43 +0,0 @@
-import { afterAll, expect, test } from 'bun:test'
-
-const testing = await import('@testing-library/react')
-const { readStored, useStoredState, writeStored } = await import('./useStoredState.ts')
-
-afterAll(() => {
-  testing.cleanup()
-})
-
-const isText = (v: unknown): v is string => typeof v === 'string'
-
-test('a stored string reads back whether it was written as JSON or bare', () => {
-  localStorage.setItem('stored-test.json', JSON.stringify('run-1'))
-  localStorage.setItem('stored-test.bare', 'run-2')
-  expect(readStored('stored-test.json', '', isText)).toBe('run-1')
-  expect(readStored('stored-test.bare', '', isText)).toBe('run-2')
-  expect(readStored('stored-test.missing', 'none', isText)).toBe('none')
-  localStorage.removeItem('stored-test.json')
-  localStorage.removeItem('stored-test.bare')
-})
-
-test('the value follows the key when the key changes', () => {
-  localStorage.setItem('stored-test.a', JSON.stringify('one'))
-  localStorage.setItem('stored-test.b', JSON.stringify('two'))
-  const view = testing.renderHook(({ key }) => useStoredState(key, '', isText), {
-    initialProps: { key: 'stored-test.a' },
-  })
-  expect(view.result.current[0]).toBe('one')
-  view.rerender({ key: 'stored-test.b' })
-  expect(view.result.current[0]).toBe('two')
-  testing.act(() => view.result.current[1]('three'))
-  expect(localStorage.getItem('stored-test.b')).toBe('"three"')
-  expect(localStorage.getItem('stored-test.a')).toBe('"one"')
-  localStorage.removeItem('stored-test.a')
-  localStorage.removeItem('stored-test.b')
-})
-
-test('the caller key reaches localStorage verbatim, with no prefix', () => {
-  writeStored('stored-test.verbatim', { a: 1 })
-  expect(localStorage.getItem('stored-test.verbatim')).toBe(JSON.stringify({ a: 1 }))
-  expect(localStorage.length).toBe(1)
-  localStorage.removeItem('stored-test.verbatim')
-})