@rethunk/react-load-hooks 0.1.1 → 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/index.d.ts

@@ -1,9 +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 { 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,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,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/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/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.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/index.ts

@@ -1,8 +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 { 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/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)
+}