@choksheak/react-utils 0.2.2 → 0.2.4

package/README.md

@@ -1,3 +1,5 @@
-# Chok's React Utilities
+# @choksheak/react-utils
 
 Miscellaneous React+TypeScript utilities with support for full tree-shaking.
+
+Online docs: https://choksheak.github.io/react-utils/

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@choksheak/react-utils",
   "license": "The Unlicense",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Miscellaneous React+TypeScript utilities with support for full tree-shaking.",
   "private": false,
   "main": "index.js",
@@ -10,38 +10,10 @@
   "files": [
     "**/*"
   ],
-  "exports": {
-    "./package.json": "./package.json",
-    "./fetcher": {
-      "types": "./fetcher.d.ts",
-      "import": "./fetcher.js"
-    },
-    "./sharedQuery": {
-      "types": "./sharedQuery.d.ts",
-      "import": "./sharedQuery.js"
-    },
-    "./sharedState": {
-      "types": "./sharedState.d.ts",
-      "import": "./sharedState.js"
-    }
-  },
-  "typesVersions": {
-    "*": {
-      "fetcher": [
-        "fetcher.d.ts"
-      ],
-      "sharedQuery": [
-        "sharedQuery.d.ts"
-      ],
-      "sharedState": [
-        "sharedState.d.ts"
-      ]
-    }
-  },
   "scripts": {
     "lint": "eslint .",
     "fix": "eslint . --fix",
-    "tsc": "tsc --noEmit",
+    "tsc": "tsc --noEmit --allowSyntheticDefaultImports",
     "ft": "npm run fix && npm run tsc",
     "build": "tsup src/*",
     "test": "vitest run",
@@ -50,6 +22,7 @@
     "ls": "lint-staged",
     "docs": "rm -rf docs && typedoc `find src -name '*.ts' ! -name '*.test.ts'` --out docs --name 'Chok’s React Utilities'",
     "gen-types": "tsc --emitDeclarationOnly --declaration",
+    "gen-exports": "tsx scripts/gen-exports.ts",
     "bump": "tsx scripts/bump-version.ts",
     "bump:patch": "tsx scripts/bump-version.ts --patch",
     "bump:minor": "tsx scripts/bump-version.ts --minor",
@@ -57,7 +30,7 @@
     "pkg": "scripts/package.sh",
     "pub": "npm publish dist/ --access=public",
     "commit": "scripts/commit-release.sh",
-    "release": "npm run ci && npm run bump && npm run pkg && npm run pub && npm run commit",
+    "release": "npm run ci && npm run bump && npm i && npm run pkg && npm run pub && npm run commit",
     "postinstall": "simple-git-hooks"
   },
   "simple-git-hooks": {
@@ -90,8 +63,8 @@
   "devDependencies": {
     "@eslint/compat": "^1.4.0",
     "@eslint/js": "^9.38.0",
-    "@tanstack/react-query": "^5.90.5",
     "@types/jest": "^30.0.0",
+    "@types/lodash": "^4.17.20",
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
     "@typescript-eslint/eslint-plugin": "^8.46.2",
@@ -107,6 +80,8 @@
     "globals": "^16.4.0",
     "jiti": "^2.6.1",
     "lint-staged": "^16.2.6",
+    "lodash": "^4.17.21",
+    "object-sizeof": "^2.6.5",
     "prettier": "^3.6.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
@@ -116,13 +91,44 @@
     "typedoc": "^0.28.14",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.46.2",
+    "use-deep-compare": "^1.3.0",
     "vitest": "^4.0.3",
     "wretch": "^3.0.2"
   },
   "peerDependencies": {
     "@choksheak/ts-utils": ">=0.2.9",
-    "@tanstack/react-query": ">=5",
+    "lodash": ">=4.17.21",
+    "object-sizeof": ">=2.6.5",
     "react": ">=16",
+    "use-deep-compare": ">=1.3.0",
     "wretch": ">=3"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    "./fetcher": {
+      "types": "./fetcher.d.ts",
+      "import": "./fetcher.js"
+    },
+    "./sharedQuery": {
+      "types": "./sharedQuery.d.ts",
+      "import": "./sharedQuery.js"
+    },
+    "./sharedState": {
+      "types": "./sharedState.d.ts",
+      "import": "./sharedState.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "fetcher": [
+        "./fetcher.d.ts"
+      ],
+      "sharedQuery": [
+        "./sharedQuery.d.ts"
+      ],
+      "sharedState": [
+        "./sharedState.d.ts"
+      ]
+    }
   }
 }

package/sharedQuery.d.mts

@@ -1,16 +1,37 @@
 import { SharedStateOptions, SharedState } from './sharedState.mjs';
 import './utils/storage.mjs';
 
-type FetchFn<TArgs extends unknown[], TData> = (...args: TArgs) => Promise<TData> | TData;
+type QueryFn<TArgs extends unknown[], TData> = (...args: TArgs) => Promise<TData> | TData;
 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;
-    error?: Error;
+    /**
+     * Use unknown type for error because we can't assume what type of variable
+     * will be thrown from the query function. We also don't want to add this
+     * type to QueryStateValue<TError> as it adds complexity to the type.
+     */
+    error?: unknown;
     errorUpdatedMs?: number;
 };
 type UseQueryResult<TData> = QueryStateValue<TData> & {
-    refetch: () => Promise<TData>;
+    /**
+     * Cancels the inflight query (if any). Returns true if canceled.
+     */
+    abortCurrentQuery: (reason?: unknown) => boolean;
+    /**
+     * Manually refresh the data by doing a new query.
+     */
+    refetch: () => void;
+    /**
+     * If you got the data from somewhere else (e.g. an in-memory data update),
+     * just set it directly.
+     */
     setData: (data: TData, dataUpdatedMs?: number) => void;
     deleteData: () => void;
 };
@@ -22,28 +43,49 @@ type PersistTo = "localStorage" | "indexedDb";
 type SharedQueryState<TData> = Record<string, QueryStateValue<TData>>;
 type SharedQueryOptions<TArgs extends unknown[], TData> = {
     queryName: string;
-    queryFn: FetchFn<TArgs, TData>;
+    queryFn: QueryFn<TArgs, TData>;
     staleMs?: number;
     expiryMs?: number;
     refetchOnStale?: boolean;
     persistTo?: PersistTo;
+    maxSize?: number;
+    maxBytes?: number;
+    log?: (...args: unknown[]) => void;
 } & SharedStateOptions<SharedQueryState<TData>>;
 /** Users can override these values globally. */
 declare const SharedQueryDefaults: {
     staleMs: number;
     expiryMs: number;
+    refetchOnStale: boolean;
     persistTo: PersistTo | undefined;
+    maxSize: number;
+    maxBytes: number;
+    log: (...args: unknown[]) => void;
 };
 declare class SharedQuery<TArgs extends unknown[], TData> {
-    private readonly inflightPromises;
+    private readonly inflightQueries;
     readonly queryState: SharedState<SharedQueryState<TData>>;
     readonly queryName: string;
     private readonly queryFn;
     readonly expiryMs: number;
     readonly staleMs: number;
     readonly refetchOnStale: boolean;
+    readonly maxSize: number;
+    readonly maxBytes: number;
+    readonly log: (...args: unknown[]) => void;
     constructor(options: SharedQueryOptions<TArgs, TData>);
+    /** Returns a key to identify requests based on the given args. */
     getQueryKey(args: TArgs): string;
+    /**
+     * Get the AbortController to abort the inflight query (if any).
+     *
+     * Note that once you get the controller, you can also get the signal easily
+     * using `controller.signal`. So if you need both the controller and the
+     * signal, just use this function.
+     */
+    getAbortController(queryKey: string): AbortController | null;
+    /** Get the AbortSignal to check for query abortions. */
+    getAbortSignal(queryKey: string): AbortSignal | null;
     private isStale;
     private isExpired;
     getCachedOrFetch(...args: TArgs): Promise<TData>;
@@ -54,9 +96,14 @@ declare class SharedQuery<TArgs extends unknown[], TData> {
     /** Do a new fetch even when the data is already cached. */
     updateFromSource(...args: TArgs): Promise<TData>;
     /** Delete the cached data for one set of arguments. */
-    deleteData(args: TArgs): void;
+    deleteData(queryKey: string): void;
     /** Delete all currently cached data & all inflight promises. */
     clear(): void;
+    /**
+     * Discard the oldest entries if the size exceeds the limit. The last
+     * remaining record cannot be deleted no matter what the limit is.
+     */
+    enforceSizeLimit(): void;
 }
 /**
  * Create a reusable shared query object that can be used to auto de-duplicate
@@ -64,13 +111,26 @@ declare class SharedQuery<TArgs extends unknown[], TData> {
  *
  * 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,
+ *   });
+ * ```
  */
 declare function sharedQuery<TArgs extends unknown[], TData>(options: SharedQueryOptions<TArgs, TData>): SharedQuery<TArgs, TData>;
 /**
  * React hook to make use of a shared query inside any React component.
  *
- *     const users = useSharedQuery(usersQuery, ["123"]);
+ * Example:
+ * ```
+ *   const users = useSharedQuery(usersQuery, ["123"]);
+ * ```
  */
 declare function useSharedQuery<TArgs extends unknown[], TData>(query: SharedQuery<TArgs, TData>, args?: TArgs): UseQueryResult<TData>;
 
-export { type FetchFn, type PersistTo, type QueryStateValue, SharedQuery, SharedQueryDefaults, type SharedQueryOptions, type SharedQueryState, type UseQueryResult, sharedQuery, useSharedQuery };
+export { type PersistTo, type QueryFn, type QueryStateValue, SharedQuery, SharedQueryDefaults, type SharedQueryOptions, type SharedQueryState, type UseQueryResult, sharedQuery, useSharedQuery };

package/sharedQuery.d.ts

@@ -1,14 +1,35 @@
 import { SharedState, SharedStateOptions } from "./sharedState";
-export type FetchFn<TArgs extends unknown[], TData> = (...args: TArgs) => Promise<TData> | TData;
+export type QueryFn<TArgs extends unknown[], TData> = (...args: TArgs) => 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;
-    error?: Error;
+    /**
+     * Use unknown type for error because we can't assume what type of variable
+     * will be thrown from the query function. We also don't want to add this
+     * type to QueryStateValue<TError> as it adds complexity to the type.
+     */
+    error?: unknown;
     errorUpdatedMs?: number;
 };
 export type UseQueryResult<TData> = QueryStateValue<TData> & {
-    refetch: () => Promise<TData>;
+    /**
+     * Cancels the inflight query (if any). Returns true if canceled.
+     */
+    abortCurrentQuery: (reason?: unknown) => boolean;
+    /**
+     * Manually refresh the data by doing a new query.
+     */
+    refetch: () => void;
+    /**
+     * If you got the data from somewhere else (e.g. an in-memory data update),
+     * just set it directly.
+     */
     setData: (data: TData, dataUpdatedMs?: number) => void;
     deleteData: () => void;
 };
@@ -20,28 +41,49 @@ export type PersistTo = "localStorage" | "indexedDb";
 export type SharedQueryState<TData> = Record<string, QueryStateValue<TData>>;
 export type SharedQueryOptions<TArgs extends unknown[], TData> = {
     queryName: string;
-    queryFn: FetchFn<TArgs, TData>;
+    queryFn: QueryFn<TArgs, TData>;
     staleMs?: number;
     expiryMs?: number;
     refetchOnStale?: boolean;
     persistTo?: PersistTo;
+    maxSize?: number;
+    maxBytes?: number;
+    log?: (...args: unknown[]) => void;
 } & SharedStateOptions<SharedQueryState<TData>>;
 /** Users can override these values globally. */
 export declare const SharedQueryDefaults: {
     staleMs: number;
     expiryMs: number;
+    refetchOnStale: boolean;
     persistTo: PersistTo | undefined;
+    maxSize: number;
+    maxBytes: number;
+    log: (...args: unknown[]) => void;
 };
 export declare class SharedQuery<TArgs extends unknown[], TData> {
-    private readonly inflightPromises;
+    private readonly inflightQueries;
     readonly queryState: SharedState<SharedQueryState<TData>>;
     readonly queryName: string;
     private readonly queryFn;
     readonly expiryMs: number;
     readonly staleMs: number;
     readonly refetchOnStale: boolean;
+    readonly maxSize: number;
+    readonly maxBytes: number;
+    readonly log: (...args: unknown[]) => void;
     constructor(options: SharedQueryOptions<TArgs, TData>);
+    /** Returns a key to identify requests based on the given args. */
     getQueryKey(args: TArgs): string;
+    /**
+     * Get the AbortController to abort the inflight query (if any).
+     *
+     * Note that once you get the controller, you can also get the signal easily
+     * using `controller.signal`. So if you need both the controller and the
+     * signal, just use this function.
+     */
+    getAbortController(queryKey: string): AbortController | null;
+    /** Get the AbortSignal to check for query abortions. */
+    getAbortSignal(queryKey: string): AbortSignal | null;
     private isStale;
     private isExpired;
     getCachedOrFetch(...args: TArgs): Promise<TData>;
@@ -52,9 +94,14 @@ export declare class SharedQuery<TArgs extends unknown[], TData> {
     /** Do a new fetch even when the data is already cached. */
     updateFromSource(...args: TArgs): Promise<TData>;
     /** Delete the cached data for one set of arguments. */
-    deleteData(args: TArgs): void;
+    deleteData(queryKey: string): void;
     /** Delete all currently cached data & all inflight promises. */
     clear(): void;
+    /**
+     * Discard the oldest entries if the size exceeds the limit. The last
+     * remaining record cannot be deleted no matter what the limit is.
+     */
+    enforceSizeLimit(): void;
 }
 /**
  * Create a reusable shared query object that can be used to auto de-duplicate
@@ -62,11 +109,24 @@ export declare class SharedQuery<TArgs extends unknown[], TData> {
  *
  * 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 declare function sharedQuery<TArgs extends unknown[], TData>(options: SharedQueryOptions<TArgs, TData>): SharedQuery<TArgs, TData>;
 /**
  * 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 declare function useSharedQuery<TArgs extends unknown[], TData>(query: SharedQuery<TArgs, TData>, args?: TArgs): UseQueryResult<TData>;