@choksheak/react-utils 0.2.2 → 0.2.3

package/sharedQuery.mjs

@@ -1,5 +1,6 @@
 // src/sharedQuery.ts
 import { MS_PER_DAY as MS_PER_DAY2 } from "@choksheak/ts-utils/timeConstants";
+import getByteSize from "object-sizeof";
 import { useCallback, useEffect, useMemo, useRef } from "react";
 
 // src/sharedState.ts
@@ -269,7 +270,11 @@ function stringifyDeterministicForKeys(params) {
 var SharedQueryDefaults = {
   staleMs: 0,
   expiryMs: 30 * MS_PER_DAY2,
-  persistTo: void 0
+  persistTo: void 0,
+  maxSize: 100,
+  // 100 is not too large, but please tweak accordingly
+  maxBytes: 1e5
+  // 100kb before GC
 };
 var SharedQuery = class {
   inflightPromises = /* @__PURE__ */ new Map();
@@ -279,6 +284,8 @@ var SharedQuery = class {
   expiryMs;
   staleMs;
   refetchOnStale;
+  maxSize;
+  maxBytes;
   constructor(options) {
     this.queryName = options.queryName;
     this.queryFn = options.queryFn;
@@ -291,6 +298,8 @@ var SharedQuery = class {
     } else if (persistTo === "indexedDb") {
       options.indexedDbKey = options.queryName;
     }
+    this.maxSize = options?.maxSize ?? SharedQueryDefaults.maxSize;
+    this.maxBytes = options?.maxBytes ?? SharedQueryDefaults.maxBytes;
     this.queryState = sharedState(
       {},
       {
@@ -359,11 +368,13 @@ var SharedQuery = class {
   /** Set the data directly if the user obtained it from somewhere else. */
   async setData(queryKey, data, dataUpdatedMs = Date.now()) {
     const entry = {
+      lastUpdatedMs: Date.now(),
       loading: false,
       data,
       dataUpdatedMs
     };
     this.queryState.setValue((prev) => ({ ...prev, [queryKey]: entry }));
+    this.enforceSizeLimit();
   }
   /** Do a new fetch even when the data is already cached. */
   async updateFromSource(...args) {
@@ -384,6 +395,78 @@ var SharedQuery = class {
     this.queryState.delete();
     this.inflightPromises.clear();
   }
+  /**
+   * Discard the oldest entries if the size exceeds the limit. The last
+   * remaining record cannot be deleted no matter what the limit is.
+   */
+  enforceSizeLimit() {
+    if (!this.maxSize && !this.maxBytes) {
+      return;
+    }
+    const oldState = this.queryState.getSnapshot();
+    const oldSize = Object.keys(oldState).length;
+    if (oldSize <= 1) {
+      return;
+    }
+    const oldByteSize = getByteSize(oldState);
+    let newState = oldState;
+    let needUpdate = false;
+    if (this.maxSize) {
+      const numToCut = oldSize - this.maxSize;
+      if (numToCut > 0) {
+        console.log(
+          `enforceSizeLimit for ${this.queryName} needed due to size ${oldSize} > ${this.maxSize}`
+        );
+        newState = { ...newState };
+        needUpdate = true;
+        Object.entries(newState).sort(
+          (entry1, entry2) => (
+            // Sort descending.
+            entry2[1].lastUpdatedMs - entry1[1].lastUpdatedMs
+          )
+        ).slice(-numToCut).forEach(([key]) => {
+          delete newState[key];
+        });
+      }
+    }
+    if (this.maxBytes && Object.keys(newState).length > 1) {
+      const currentByteSize = needUpdate ? getByteSize(newState) : oldByteSize;
+      let bytesToCut = currentByteSize - this.maxBytes;
+      if (bytesToCut > 0) {
+        console.log(
+          `enforceSizeLimit for ${this.queryName} needed due to byte size ${currentByteSize.toLocaleString()} > ${this.maxBytes.toLocaleString()}`
+        );
+        if (!needUpdate) {
+          newState = { ...newState };
+          needUpdate = true;
+        }
+        const entriesByTimeAscending = Object.entries(newState).sort(
+          (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs
+        );
+        for (
+          let i = 0;
+          // Leave the last record entriesByTimeAscending[len-1] untouched.
+          i < entriesByTimeAscending.length - 1 && bytesToCut > 0;
+          i++
+        ) {
+          const key = entriesByTimeAscending[i][0];
+          const thisSize = getByteSize(key) + getByteSize(newState[key]);
+          delete newState[key];
+          bytesToCut -= thisSize;
+        }
+      }
+    }
+    if (needUpdate) {
+      this.queryState.setValue(newState);
+      console.log(
+        `Trimmed data for ${this.queryName}: size=(${oldSize} -> ${Object.keys(newState).length}) (limit=${this.maxSize}), byteSize=(${oldByteSize.toLocaleString()} -> ${getByteSize(newState).toLocaleString()}) (limit=${this.maxBytes.toLocaleString()})`
+      );
+      return;
+    }
+    console.log(
+      `No need to trim data for ${this.queryName}: size=${oldSize} (limit=${this.maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`
+    );
+  }
 };
 var seenQueryNames = /* @__PURE__ */ new Set();
 function sharedQuery(options) {
@@ -393,7 +476,10 @@ function sharedQuery(options) {
   seenQueryNames.add(options.queryName);
   return new SharedQuery(options);
 }
-var DEFAULT_QUERY_STATE_ENTRY = { loading: true };
+var DEFAULT_QUERY_STATE_ENTRY = {
+  lastUpdatedMs: 0,
+  loading: true
+};
 function useSharedQuery(query, args = []) {
   const [queryState, setQueryState] = useSharedState(query.queryState);
   const isMounted = useRef(true);
@@ -404,6 +490,7 @@ function useSharedQuery(query, args = []) {
       const clone = { ...prev };
       clone[queryKey] = {
         ...clone[queryKey] ?? {},
+        lastUpdatedMs: Date.now(),
         loading: true
       };
       return clone;
@@ -413,11 +500,13 @@ function useSharedQuery(query, args = []) {
       if (isMounted.current) {
         setQueryState((prev) => {
           const clone = { ...prev };
+          const now = Date.now();
           clone[queryKey] = {
             // Don't keep old error.
+            lastUpdatedMs: now,
             loading: false,
             data,
-            dataUpdatedMs: Date.now()
+            dataUpdatedMs: now
           };
           return clone;
         });
@@ -427,12 +516,14 @@ function useSharedQuery(query, args = []) {
       if (isMounted.current) {
         setQueryState((prev) => {
           const clone = { ...prev };
+          const now = Date.now();
           clone[queryKey] = {
             // Keep old data.
             ...clone[queryKey] ?? {},
+            lastUpdatedMs: now,
             loading: false,
             error,
-            errorUpdatedMs: Date.now()
+            errorUpdatedMs: now
           };
           return clone;
         });

package/src/sharedQuery.ts

@@ -1,4 +1,5 @@
 import { MS_PER_DAY } from "@choksheak/ts-utils/timeConstants";
+import getByteSize from "object-sizeof";
 import { useCallback, useEffect, useMemo, useRef } from "react";
 
 import {
@@ -14,6 +15,12 @@ export type FetchFn<TArgs extends unknown[], TData> = (
 ) => Promise<TData> | TData;
 
 export type QueryStateValue<TData> = {
+  /**
+   * When this record was last updated. Used for LRU determination. If you want
+   * the data age, please use `dataUpdatedMs` instead.
+   */
+  lastUpdatedMs: number;
+
   loading: boolean;
   data?: TData;
   dataUpdatedMs?: number;
@@ -43,7 +50,7 @@ export type SharedQueryOptions<TArgs extends unknown[], TData> = {
   // Function to fetch data.
   queryFn: FetchFn<TArgs, TData>;
 
-  // ms before data considered stale; 0 means never stale.
+  // ms before data considered stale; 0 means always stale.
   staleMs?: number;
 
   // ms before data is removed from cache; 0 means never expire.
@@ -56,6 +63,14 @@ export type SharedQueryOptions<TArgs extends unknown[], TData> = {
   // queryName. This is important because it avoids requiring the user to
   // specify the same queryName twice everytime.
   persistTo?: PersistTo;
+
+  // Max number of entries to keep. The oldest entries will be discarded.
+  // The last record cannot be discarded. 0 means no limit.
+  maxSize?: number;
+
+  // Max number of bytes to keep. The oldest entries will be discarded.
+  // The last record cannot be discarded. 0 means no limit.
+  maxBytes?: number;
 } & SharedStateOptions<SharedQueryState<TData>>;
 
 /** Users can override these values globally. */
@@ -63,6 +78,8 @@ export const SharedQueryDefaults = {
   staleMs: 0,
   expiryMs: 30 * MS_PER_DAY,
   persistTo: undefined as PersistTo | undefined,
+  maxSize: 100, // 100 is not too large, but please tweak accordingly
+  maxBytes: 100_000, // 100kb before GC
 };
 
 export class SharedQuery<TArgs extends unknown[], TData> {
@@ -74,6 +91,8 @@ export class SharedQuery<TArgs extends unknown[], TData> {
   public readonly expiryMs: number;
   public readonly staleMs: number;
   public readonly refetchOnStale: boolean;
+  public readonly maxSize: number;
+  public readonly maxBytes: number;
 
   public constructor(options: SharedQueryOptions<TArgs, TData>) {
     this.queryName = options.queryName;
@@ -101,6 +120,9 @@ export class SharedQuery<TArgs extends unknown[], TData> {
       options.indexedDbKey = options.queryName;
     }
 
+    this.maxSize = options?.maxSize ?? SharedQueryDefaults.maxSize;
+    this.maxBytes = options?.maxBytes ?? SharedQueryDefaults.maxBytes;
+
     this.queryState = sharedState<SharedQueryState<TData>>(
       {},
       {
@@ -196,12 +218,15 @@ export class SharedQuery<TArgs extends unknown[], TData> {
     dataUpdatedMs = Date.now(),
   ): Promise<void> {
     const entry: QueryStateValue<TData> = {
+      lastUpdatedMs: Date.now(),
       loading: false,
       data,
       dataUpdatedMs,
     };
 
     this.queryState.setValue((prev) => ({ ...prev, [queryKey]: entry }));
+
+    this.enforceSizeLimit();
   }
 
   /** Do a new fetch even when the data is already cached. */
@@ -227,6 +252,108 @@ export class SharedQuery<TArgs extends unknown[], TData> {
     this.queryState.delete();
     this.inflightPromises.clear();
   }
+
+  /**
+   * Discard the oldest entries if the size exceeds the limit. The last
+   * remaining record cannot be deleted no matter what the limit is.
+   */
+  public enforceSizeLimit(): void {
+    // Skip if there are no limits.
+    if (!this.maxSize && !this.maxBytes) {
+      return;
+    }
+
+    const oldState = this.queryState.getSnapshot();
+    const oldSize = Object.keys(oldState).length;
+
+    // Cannot do GC if size is 1 or less.
+    if (oldSize <= 1) {
+      return;
+    }
+
+    const oldByteSize = getByteSize(oldState);
+
+    let newState = oldState;
+    let needUpdate = false;
+
+    // Limit by number of records.
+    if (this.maxSize) {
+      const numToCut = oldSize - this.maxSize;
+
+      if (numToCut > 0) {
+        console.log(
+          `enforceSizeLimit for ${this.queryName} needed due to size ${oldSize} > ${this.maxSize}`,
+        );
+
+        newState = { ...newState }; // shallow clone
+        needUpdate = true;
+
+        Object.entries(newState)
+          .sort(
+            (entry1, entry2) =>
+              // Sort descending.
+              entry2[1].lastUpdatedMs - entry1[1].lastUpdatedMs,
+          )
+          .slice(-numToCut)
+          .forEach(([key]) => {
+            delete newState[key];
+          });
+      }
+    }
+
+    // Limit by byte size.
+    if (this.maxBytes && Object.keys(newState).length > 1) {
+      // Recompute only if changed by above code.
+      const currentByteSize = needUpdate ? getByteSize(newState) : oldByteSize;
+
+      let bytesToCut = currentByteSize - this.maxBytes;
+
+      if (bytesToCut > 0) {
+        console.log(
+          `enforceSizeLimit for ${this.queryName} needed due to byte size ${currentByteSize.toLocaleString()} > ${this.maxBytes.toLocaleString()}`,
+        );
+
+        // Shallow clone only if not already cloned above.
+        if (!needUpdate) {
+          newState = { ...newState };
+          needUpdate = true;
+        }
+
+        const entriesByTimeAscending = Object.entries(newState).sort(
+          (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs,
+        );
+
+        for (
+          let i = 0;
+          // Leave the last record entriesByTimeAscending[len-1] untouched.
+          i < entriesByTimeAscending.length - 1 && bytesToCut > 0;
+          i++
+        ) {
+          const key = entriesByTimeAscending[i][0];
+          const thisSize = getByteSize(key) + getByteSize(newState[key]);
+          delete newState[key];
+          bytesToCut -= thisSize;
+        }
+      }
+    }
+
+    // Update the state.
+    if (needUpdate) {
+      this.queryState.setValue(newState);
+
+      // Log to inform user that the data was trimmed.
+      console.log(
+        `Trimmed data for ${this.queryName}: size=(${oldSize} -> ${Object.keys(newState).length}) (limit=${this.maxSize}), byteSize=(${oldByteSize.toLocaleString()} -> ${getByteSize(newState).toLocaleString()}) (limit=${this.maxBytes.toLocaleString()})`,
+      );
+
+      return;
+    }
+
+    // Log to indicate why trimming was not needed.
+    console.log(
+      `No need to trim data for ${this.queryName}: size=${oldSize} (limit=${this.maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`,
+    );
+  }
 }
 
 const seenQueryNames = new Set<string>();
@@ -237,6 +364,16 @@ const seenQueryNames = new Set<string>();
  *
  * Each `queryName` must be unique, and can only be declared once, most often
  * in the top level scope. The queryName is used for logging only.
+ *
+ * Example:
+ * ```
+ *   export const usersQuery = sharedQuery({
+ *     queryName: "users",
+ *     queryFn: listUsers,
+ *     persistTo: "indexedDb",
+ *     staleMs: MS_PER_DAY,
+ *   });
+ * ```
  */
 export function sharedQuery<TArgs extends unknown[], TData>(
   // The name could have been auto-generated, but we let the user give us a
@@ -251,12 +388,18 @@ export function sharedQuery<TArgs extends unknown[], TData>(
   return new SharedQuery(options);
 }
 
-const DEFAULT_QUERY_STATE_ENTRY: QueryStateValue<unknown> = { loading: true };
+const DEFAULT_QUERY_STATE_ENTRY: QueryStateValue<unknown> = {
+  lastUpdatedMs: 0,
+  loading: true,
+};
 
 /**
  * React hook to make use of a shared query inside any React component.
  *
- *     const users = useSharedQuery(usersQuery, ["123"]);
+ * Example:
+ * ```
+ *   const users = useSharedQuery(usersQuery, ["123"]);
+ * ```
  */
 export function useSharedQuery<TArgs extends unknown[], TData>(
   query: SharedQuery<TArgs, TData>,
@@ -278,10 +421,13 @@ export function useSharedQuery<TArgs extends unknown[], TData>(
 
     setQueryState((prev) => {
       const clone = { ...prev };
+
       clone[queryKey] = {
         ...(clone[queryKey] ?? {}),
+        lastUpdatedMs: Date.now(),
         loading: true,
       };
+
       return clone;
     });
 
@@ -291,12 +437,16 @@ export function useSharedQuery<TArgs extends unknown[], TData>(
       if (isMounted.current) {
         setQueryState((prev) => {
           const clone = { ...prev };
+          const now = Date.now();
+
           clone[queryKey] = {
             // Don't keep old error.
+            lastUpdatedMs: now,
             loading: false,
             data,
-            dataUpdatedMs: Date.now(),
+            dataUpdatedMs: now,
           };
+
           return clone;
         });
       }
@@ -309,13 +459,17 @@ export function useSharedQuery<TArgs extends unknown[], TData>(
       if (isMounted.current) {
         setQueryState((prev) => {
           const clone = { ...prev };
+          const now = Date.now();
+
           clone[queryKey] = {
             // Keep old data.
             ...(clone[queryKey] ?? {}),
+            lastUpdatedMs: now,
             loading: false,
             error,
-            errorUpdatedMs: Date.now(),
+            errorUpdatedMs: now,
           };
+
           return clone;
         });
       }

package/src/utils/stringify.test.ts

@@ -1,46 +0,0 @@
-import { stringifyDeterministicForKeys } from "./stringify";
-
-describe("stringifyDeterministicForKeys", () => {
-  test("happy", () => {
-    const expected = `{"a":1,"b":2,"c":{"e":1,"f":2}}`;
-
-    const actual1 = stringifyDeterministicForKeys({
-      a: 1,
-      b: 2,
-      c: { e: 1, f: 2 },
-    });
-    expect(actual1).toBe(expected);
-
-    const actual2 = stringifyDeterministicForKeys({
-      c: { f: 2, e: 1 },
-      b: 2,
-      a: 1,
-    });
-    expect(actual2).toBe(expected);
-  });
-
-  test("circular", () => {
-    const circular = { b: {}, a: 1 };
-    circular.b = circular;
-
-    const actual = stringifyDeterministicForKeys(circular);
-
-    expect(actual).toBe(`{"a":1,"b":"[Circular]"}`);
-  });
-
-  test("function", () => {
-    const fn = { b: {}, a: () => {} };
-
-    expect(() => stringifyDeterministicForKeys(fn)).toThrow(
-      `Functions should not be passed into query parameters`,
-    );
-  });
-
-  test("array", () => {
-    const a = [1, "a", { b: 2 }, [true]];
-
-    const actual = stringifyDeterministicForKeys(a);
-
-    expect(actual).toBe(`[1,"a",{"b":2},[true]]`);
-  });
-});

package/utils/stringify.test.d.mts

@@ -1,2 +0,0 @@
-
-export {  }

package/utils/stringify.test.d.ts

@@ -1,2 +0,0 @@
-
-export {  }

package/utils/stringify.test.js

@@ -1,69 +0,0 @@
-"use strict";
-
-// src/utils/stringify.ts
-function stringifyDeterministicForKeys(params) {
-  const cache = /* @__PURE__ */ new Set();
-  return JSON.stringify(params, (_, value) => {
-    if (typeof value === "function") {
-      throw new Error(`Functions should not be passed into query parameters`);
-    }
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-      return value;
-    }
-    if (cache.has(value)) {
-      return "[Circular]";
-    }
-    cache.add(value);
-    if (value !== params) {
-      try {
-        JSON.stringify(value);
-      } catch {
-        return "[Unserializable]";
-      }
-    }
-    return Object.keys(value).sort().reduce(
-      (result, key) => {
-        result[key] = value[key];
-        return result;
-      },
-      {}
-    );
-  });
-}
-
-// src/utils/stringify.test.ts
-describe("stringifyDeterministicForKeys", () => {
-  test("happy", () => {
-    const expected = `{"a":1,"b":2,"c":{"e":1,"f":2}}`;
-    const actual1 = stringifyDeterministicForKeys({
-      a: 1,
-      b: 2,
-      c: { e: 1, f: 2 }
-    });
-    expect(actual1).toBe(expected);
-    const actual2 = stringifyDeterministicForKeys({
-      c: { f: 2, e: 1 },
-      b: 2,
-      a: 1
-    });
-    expect(actual2).toBe(expected);
-  });
-  test("circular", () => {
-    const circular = { b: {}, a: 1 };
-    circular.b = circular;
-    const actual = stringifyDeterministicForKeys(circular);
-    expect(actual).toBe(`{"a":1,"b":"[Circular]"}`);
-  });
-  test("function", () => {
-    const fn = { b: {}, a: () => {
-    } };
-    expect(() => stringifyDeterministicForKeys(fn)).toThrow(
-      `Functions should not be passed into query parameters`
-    );
-  });
-  test("array", () => {
-    const a = [1, "a", { b: 2 }, [true]];
-    const actual = stringifyDeterministicForKeys(a);
-    expect(actual).toBe(`[1,"a",{"b":2},[true]]`);
-  });
-});

package/utils/stringify.test.mjs

@@ -1,86 +0,0 @@
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-};
-var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
-};
-
-// src/utils/stringify.ts
-function stringifyDeterministicForKeys(params) {
-  const cache = /* @__PURE__ */ new Set();
-  return JSON.stringify(params, (_, value) => {
-    if (typeof value === "function") {
-      throw new Error(`Functions should not be passed into query parameters`);
-    }
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-      return value;
-    }
-    if (cache.has(value)) {
-      return "[Circular]";
-    }
-    cache.add(value);
-    if (value !== params) {
-      try {
-        JSON.stringify(value);
-      } catch {
-        return "[Unserializable]";
-      }
-    }
-    return Object.keys(value).sort().reduce(
-      (result, key) => {
-        result[key] = value[key];
-        return result;
-      },
-      {}
-    );
-  });
-}
-var init_stringify = __esm({
-  "src/utils/stringify.ts"() {
-    "use strict";
-  }
-});
-
-// src/utils/stringify.test.ts
-var require_stringify_test = __commonJS({
-  "src/utils/stringify.test.ts"() {
-    init_stringify();
-    describe("stringifyDeterministicForKeys", () => {
-      test("happy", () => {
-        const expected = `{"a":1,"b":2,"c":{"e":1,"f":2}}`;
-        const actual1 = stringifyDeterministicForKeys({
-          a: 1,
-          b: 2,
-          c: { e: 1, f: 2 }
-        });
-        expect(actual1).toBe(expected);
-        const actual2 = stringifyDeterministicForKeys({
-          c: { f: 2, e: 1 },
-          b: 2,
-          a: 1
-        });
-        expect(actual2).toBe(expected);
-      });
-      test("circular", () => {
-        const circular = { b: {}, a: 1 };
-        circular.b = circular;
-        const actual = stringifyDeterministicForKeys(circular);
-        expect(actual).toBe(`{"a":1,"b":"[Circular]"}`);
-      });
-      test("function", () => {
-        const fn = { b: {}, a: () => {
-        } };
-        expect(() => stringifyDeterministicForKeys(fn)).toThrow(
-          `Functions should not be passed into query parameters`
-        );
-      });
-      test("array", () => {
-        const a = [1, "a", { b: 2 }, [true]];
-        const actual = stringifyDeterministicForKeys(a);
-        expect(actual).toBe(`[1,"a",{"b":2},[true]]`);
-      });
-    });
-  }
-});
-export default require_stringify_test();