npm - @choksheak/react-utils - Versions diffs - 0.3.1 → 0.3.2 - Mend

@choksheak/react-utils 0.3.1 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/sharedQuery.min.mjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/sharedQuery.ts","../src/sharedState.ts","../src/storage.ts","../src/stringify.ts","../src/useDeepMemo.ts"],"sourcesContent":["/*\n @packageDocumentation\n \n The \"shared query\" is a data fetching convenience library that helps users\n * to load data, check for staleness and expiration, cache in memory, local\n * storage or indexed db, and be able to manipulate the data anytime.\n \n Each shared query creates a new private shared state that handles the data\n * storage. This shared state contains the records for all queries, where each\n * query is a unique set of arguments used to make the query. The number of\n * records and the total byte size of data can be limited so as to ensure the\n * query does not take up too much memory.\n \n Example:\n * ```\n * import { sharedQuery, useSharedQuery } from \"@choksheak/react-utils/sharedQuery\";\n \n // Create a new shared query in the top level scope.\n * // The query function `queryFn` here does not take any arguments.\n * //\n * // Only the queryName and queryFn are required and everything else is\n * // optional.\n * //\n * // The queryName must be unique, otherwise we will throw an\n * // error. This is because defining the same queryName for two different\n * // queries implies that the queries are the same, thus violating the idea\n * // of a \"shared\" query, and almost certainly points to a bug in the code.\n * export const usersQuery = sharedQuery({\n * queryName: \"users\",\n * queryFn: listUsers,\n * persistTo: \"indexedDb\",\n * staleMs: MS_PER_DAY,\n * });\n \n // Note that the query will only start fetching on mount in React.\n * // But you can do `usersQuery.getCachedOrFetch()` here to prefetch the\n * // data if necessary.\n * usersQuery.getCachedOrFetch();\n \n // Example of using a query function with arguments.\n * export const getUserQuery = sharedQuery({\n * queryName: \"getUser\",\n * queryFn: getUser, // getUser(userId: string) => User\n * persistTo: \"indexedDb\",\n * staleMs: MS_PER_DAY,\n * });\n \n export const UsersComponent: React.FC = () => {\n * // Second argument is optional, and is an array of arguments to be\n * // passed to the `queryFn`.\n * const users = useSharedQuery(usersQuery);\n \n return (\n * <>\n * <h1>List of Users</h1>\n \n <button onclick={users.refetch}>Refresh</button>\n \n {users.loading && <Loader />}\n \n {users.error && !users.data && <p>Error: {String(users.error)}</p>}\n \n <p>Data: {users.data ? JSON.stringify(users.data) : \"-\"}</p>\n * </>\n * );\n * };\n \n export const AnotherComponent: React.FC = () => {\n * // This query will be deduped with the one above, sharing the same\n * // data and the same fetches.\n * const users = useSharedQuery(usersQuery);\n * ...\n * };\n \n export const DisplayOneUser: React.FC<{userId: string}> = ({userId}) => {\n * // Example of using the query with an argument. Whenever the argument\n * // changes, the data will be fetched and updated automatically.\n * const user = useSharedQuery(getUserQuery, [userId]);\n \n return <>User: {user.data ? JSON.stringify(user.data) : \"-\"}</>;\n * };\n * ```\n /\n\nimport { MS_PER_DAY } from \"@choksheak/ts-utils/timeConstants\";\nimport getByteSize from \"object-sizeof\";\nimport {\n SetStateAction,\n useCallback,\n useEffect,\n useMemo,\n useRef,\n useState,\n} from \"react\";\n\nimport {\n SharedState,\n sharedState,\n SharedStateOptions,\n useSharedState,\n} from \"./sharedState\";\nimport { PersistTo } from \"./storage\";\nimport { stringifyDeterministicForKeys } from \"./stringify\";\nimport { useDeepMemo } from \"./useDeepMemo\";\n\n/* Type of the queryFn used to fetch the data from source. /\nexport type QueryFn<TArgs extends unknown[], TData> = (\n ...args: TArgs\n) => Promise<TData> \| TData;\n\n/* An entry for a persisted state corresponding to one query key. /\nexport type QueryStateValue<TData> = Readonly<{\n /\n When this record was last updated. Used for LRU determination. If you want\n * the data age, please use `dataUpdatedMs` instead.\n /\n lastUpdatedMs: number;\n\n loading: boolean;\n data?: TData;\n dataUpdatedMs?: number;\n\n /\n Use unknown type for error because we can't assume what type of variable\n * will be thrown from the query function. We also don't want to add this\n * type to QueryStateValue<TError> as it adds complexity to the type.\n /\n error?: unknown;\n\n errorUpdatedMs?: number;\n}>;\n\n/* Return type for useSharedQuery(). /\nexport type UseQueryResult<TData> = QueryStateValue<TData> &\n Readonly<{\n /\n Return the last non-empty data if you want to display the last loaded data\n * while waiting for the new data to load.\n /\n lastNonEmptyData: TData \| undefined;\n\n /\n Cancels the inflight query (if any). Returns true if canceled.\n /\n abortCurrentQuery: (reason?: unknown) => boolean;\n\n /\n Manually refresh the data by doing a new query.\n /\n refetch: () => void;\n\n /\n If you got the data from somewhere else (e.g. an in-memory data update),\n * just set it directly.\n /\n setData: (data: TData, dataUpdatedMs?: number) => void;\n\n deleteData: () => void;\n }>;\n\n/\n The full query state is a record of all the fetch states mapped by\n * query key to the state entry.\n /\nexport type SharedQueryState<TData> = Record<string, QueryStateValue<TData>>;\n\n/* Options to configure a shared query. /\nexport type SharedQueryOptions<TArgs extends unknown[], TData> = {\n /\n The name could have been auto-generated, but we let the user give us a\n * human-readable name that can be identified quickly in the logs.\n * Note that the queryKey is a string formed by the queryName plus the query\n * arguments.\n /\n queryName: string;\n\n /\n Function to fetch data.\n /\n queryFn: QueryFn<TArgs, TData>;\n\n /\n ms before data considered stale; 0 means always stale.\n /\n staleMs?: number;\n\n /\n ms before data is removed from cache; 0 means never expire.\n /\n expiryMs?: number;\n\n /\n Trigger background re-fetch if stale.\n /\n refetchOnStale?: boolean;\n\n /\n Shortcut to set the localStorageKey or indexedDbKey automatically from\n * queryName. This is important because it avoids requiring the user to\n * specify the same queryName twice everytime.\n /\n persistTo?: PersistTo;\n\n /\n Max number of entries to keep. The oldest entries will be discarded.\n * The last record cannot be discarded. 0 means no limit.\n /\n maxSize?: number;\n\n /\n Max number of bytes to keep. The oldest entries will be discarded.\n * The last record cannot be discarded. 0 means no limit.\n /\n maxBytes?: number;\n\n /\n Keep a copy of the last non-empty data so that when you change the\n * query arguments, you can still display the old data while waiting for the\n * new data to load.\n /\n keepLastNonEmptyData?: boolean;\n\n /\n Customize the logger.\n /\n log?: (...args: unknown[]) => void;\n} & SharedStateOptions<SharedQueryState<TData>>;\n\n/* Users can override these values globally. /\nexport const SharedQueryConfig = {\n /* Refetch on every page load. /\n staleMs: 0,\n\n /* Keep in cache for a long time. /\n expiryMs: 30 MS_PER_DAY,\n\n /** Always refetch automatically if the data is stale. /\n refetchOnStale: true,\n\n /* No default persistence configured. /\n persistTo: undefined as PersistTo \| undefined,\n\n /* 100 is not too large, but please tweak accordingly. /\n maxSize: 100,\n\n /* 100kb limit before discarding old records. /\n maxBytes: 100_000,\n\n /* Default to log to console. /\n log: (...args: unknown[]) => console.log(\"[sharedQuery]\", ...args),\n};\n\nexport type SharedQueryConfig = typeof SharedQueryConfig;\n\n/* Convenience function to update global defaults. /\nexport function configureSharedQuery(config: Partial<SharedQueryConfig>) {\n Object.assign(SharedQueryConfig, config);\n}\n\n/* Please use sharedQuery() instead. /\nexport class SharedQuery<TArgs extends unknown[], TData> {\n private readonly inflightQueries = new Map<\n string,\n { promise: Promise<TData>; abortController: AbortController }\n >();\n\n public readonly queryState: SharedState<SharedQueryState<TData>>;\n\n /\n Keep track of the mounted query keys. This handles the case where an\n * earlier-started query returns later, and when it returns, it was already\n * unmounted, thus making it eligible for clean up right after fetch.\n /\n private readonly mountedKeys = new Map<string, number>();\n\n public readonly queryName: string;\n private readonly queryFn: QueryFn<TArgs, TData>;\n public readonly expiryMs: number;\n public readonly staleMs: number;\n public readonly refetchOnStale: boolean;\n public readonly maxSize: number;\n public readonly maxBytes: number;\n public readonly keepLastNonEmptyData: boolean;\n public readonly log: (...args: unknown[]) => void;\n\n public constructor(options: SharedQueryOptions<TArgs, TData>) {\n this.queryName = options.queryName;\n this.queryFn = options.queryFn;\n\n this.staleMs = options?.staleMs ?? SharedQueryConfig.staleMs;\n this.expiryMs = options?.expiryMs ?? SharedQueryConfig.expiryMs;\n\n this.refetchOnStale =\n options?.refetchOnStale ?? SharedQueryConfig.refetchOnStale;\n\n // Apply shortcut when using `persistTo`.\n // Specifying the `store` will take precedence over `persistTo`.\n if (!options.store) {\n const persistTo = options.persistTo ?? SharedQueryConfig.persistTo;\n\n if (persistTo) {\n options.store = {\n persistTo,\n key: options.queryName,\n expiryMs: this.expiryMs,\n };\n }\n }\n\n this.maxSize = options?.maxSize ?? SharedQueryConfig.maxSize;\n this.maxBytes = options?.maxBytes ?? SharedQueryConfig.maxBytes;\n\n this.keepLastNonEmptyData = Boolean(options?.keepLastNonEmptyData);\n\n this.log = options?.log ?? SharedQueryConfig.log;\n\n this.queryState = sharedState<SharedQueryState<TData>>(\n {}, // defaultValue\n options,\n );\n }\n\n /* Returns a key to identify requests based on the given args. /\n public getQueryKey(args: TArgs): string {\n return this.queryName + \":\" + stringifyDeterministicForKeys(args);\n }\n\n /\n Get the AbortController to abort the inflight query (if any).\n \n Note that once you get the controller, you can also get the signal easily\n * using `controller.signal`. So if you need both the controller and the\n * signal, just use this function.\n /\n public getAbortController(args: TArgs): AbortController \| null {\n const queryKey = this.getQueryKey(args);\n return this.getAbortControllerByKey(queryKey);\n }\n\n public getAbortControllerByKey(queryKey: string): AbortController \| null {\n return this.inflightQueries.get(queryKey)?.abortController ?? null;\n }\n\n /\n Get the AbortSignal to check for query abortions.\n \n Example:\n * ```\n * const getUserQuery = sharedQuery({\n * queryName: \"getUser\",\n * queryFn: (userId: string) => {\n * // Get the signal for this current execution.\n * const signal = getUserQuery.getAbortSignal([userId]);\n \n // Pass the signal to fetch so that it can be aborted.\n * const response = await fetch(`/users/${userId}`, { signal });\n \n // Check for errors.\n * if (!response.ok) {\n * throw new Error(response.statusText);\n * }\n \n // Return the data.\n * return await response.json();\n * },\n * });\n * ```\n /\n public getAbortSignal(args: TArgs): AbortSignal \| null {\n const queryKey = this.getQueryKey(args);\n return this.getAbortSignalByKey(queryKey);\n }\n\n public getAbortSignalByKey(queryKey: string): AbortSignal \| null {\n return this.getAbortControllerByKey(queryKey)?.signal ?? null;\n }\n\n private isStale(dataUpdatedMs: number): boolean {\n if (this.staleMs === 0) return true; // always stale\n\n const ageMs = Date.now() - dataUpdatedMs;\n return ageMs > this.staleMs;\n }\n\n private isExpired(dataUpdatedMs: number): boolean {\n if (this.expiryMs === 0) return false; // never expire\n\n const ageMs = Date.now() - dataUpdatedMs;\n return ageMs > this.expiryMs;\n }\n\n public async getCachedOrFetch(...args: TArgs): Promise<TData> {\n const queryKey = this.getQueryKey(args);\n const cached = this.queryState.getSnapshot()?.[queryKey];\n\n if (cached?.data && !this.isExpired(cached.dataUpdatedMs ?? 0)) {\n // Return cached value if not stale.\n if (!this.isStale(cached.dataUpdatedMs ?? 0)) {\n this.log(`Return fresh data ${queryKey} from cache without fetching`);\n return cached.data;\n }\n\n // If stale, optionally update the data in the background.\n if (this.refetchOnStale) {\n this.log(`refetchOnStale for ${queryKey}`);\n void this.dedupedFetch(queryKey, ...args);\n }\n\n // Still return stale data immediately.\n this.log(`Returning stale data for ${queryKey}`);\n return cached.data;\n }\n\n return await this.dedupedFetch(queryKey, ...args);\n }\n\n private dedupedFetch(queryKey: string, ...args: TArgs): Promise<TData> {\n const inflightQuery = this.inflightQueries.get(queryKey);\n\n // De-duplicate in-flight requests\n if (inflightQuery) {\n this.log(`Deduplicating inflight fetch for ${queryKey}`);\n return inflightQuery.promise;\n }\n\n // Fetch new data\n const promise = this.startFetching(queryKey, args);\n const abortController = new AbortController();\n\n this.inflightQueries.set(queryKey, { promise, abortController });\n\n return promise;\n }\n\n private async startFetching(queryKey: string, args: TArgs) {\n this.log(`Start fetching ${queryKey}`);\n\n try {\n const data = await this.queryFn(...args);\n\n this.log(`Successfully fetched ${queryKey}`);\n this.setData(queryKey, data, Date.now());\n return data;\n } catch (e) {\n this.log(`Failed to fetch ${queryKey}: ${e}`);\n throw e;\n } finally {\n this.inflightQueries.delete(queryKey);\n }\n }\n\n /* Get the entire stored entry for a query key. /\n public getQueryValue(queryKey: string): QueryStateValue<TData> \| undefined {\n return this.queryState.getSnapshot()?.[queryKey];\n }\n\n /* Get the current stored data for a query key. /\n public getData(queryKey: string): TData \| undefined {\n const stateValue: QueryStateValue<TData> \| undefined =\n this.queryState.getSnapshot()?.[queryKey];\n\n // Check for expiration.\n if (stateValue?.lastUpdatedMs) {\n if (this.isExpired(stateValue.lastUpdatedMs)) {\n this.deleteData(queryKey);\n return undefined;\n }\n }\n\n return stateValue?.data;\n }\n\n /* Set the data directly if the user obtained it from somewhere else. /\n public setData(\n queryKey: string,\n data: TData,\n dataUpdatedMs = Date.now(),\n ): void {\n const entry: QueryStateValue<TData> = {\n lastUpdatedMs: Date.now(),\n loading: false,\n data,\n dataUpdatedMs,\n };\n\n this.queryState.setValue((prev) => ({ ...prev, [queryKey]: entry }));\n\n this.enforceSizeLimit();\n }\n\n /\n Do a new fetch even when the data is already cached, but don't fetch if\n * another fetch is already inflight.\n /\n public async updateFromSource(...args: TArgs): Promise<TData> {\n const key = this.getQueryKey(args);\n return await this.dedupedFetch(key, ...args);\n }\n\n /* Delete the cached data for one set of arguments. /\n public deleteData(queryKey: string): void {\n const record = this.queryState.getSnapshot();\n const clone = { ...record };\n delete clone[queryKey];\n this.queryState.setValue(clone);\n\n const inflight = this.inflightQueries.get(queryKey);\n if (inflight) {\n this.inflightQueries.delete(queryKey);\n inflight.abortController.abort(\"Deleted\");\n }\n }\n\n /* Delete all currently cached data & all inflight promises. /\n public clear(): void {\n this.queryState.delete();\n\n for (const { abortController } of Array.from(\n this.inflightQueries.values(),\n )) {\n abortController.abort(\"Cleared\");\n }\n\n this.inflightQueries.clear();\n }\n\n /* Keep track of mounted keys. /\n public mount(queryKey: string): void {\n this.mountedKeys.set(queryKey, (this.mountedKeys.get(queryKey) ?? 0) + 1);\n }\n\n /* Clean up mounted keys. /\n public unmount(queryKey: string): void {\n const count = this.mountedKeys.get(queryKey);\n if (count === 1) {\n this.mountedKeys.delete(queryKey);\n } else {\n this.mountedKeys.set(queryKey, (count ?? 0) - 1);\n }\n }\n\n /\n Discard the oldest entries if the size exceeds the limit. The last\n * remaining record cannot be deleted no matter what the limit is.\n /\n public enforceSizeLimit(): void {\n // Skip if there are no limits.\n if (!this.maxSize && !this.maxBytes) {\n return;\n }\n\n const oldState = this.queryState.getSnapshot();\n const oldSize = Object.keys(oldState).length;\n\n // Cannot do GC if size is 1 or less.\n if (oldSize <= 1) {\n return;\n }\n\n const oldByteSize = getByteSize(oldState);\n\n let numToCut = this.maxSize ? oldSize - this.maxSize : 0;\n let bytesToCut = this.maxBytes ? oldByteSize - this.maxBytes : 0;\n\n // Log to indicate why trimming was not needed.\n if (numToCut <= 0 && bytesToCut <= 0) {\n this.log(\n `No need to trim data for ${this.queryName}: size=${oldSize} (limit=${this.maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`,\n );\n return;\n }\n\n // Log to inform user that trimming is needed.\n this.log(\n `Need to trim ${this.queryName}: numToCut=${numToCut}, bytesToCut=${bytesToCut}`,\n );\n\n const newState = { ...oldState }; // shallow clone\n let needUpdate = false;\n\n const deleteKeyIfNotMounted = (key: string, expired: boolean) => {\n // Mounted keys cannot be cleaned up as they are visible in the UI.\n if (this.mountedKeys.has(key)) {\n this.log(`Cannot clean up ${key} as it is mounted`);\n return;\n }\n\n const byteSize = getByteSize(key) + getByteSize(newState[key]);\n this.log(\n `Cleaning up unmounted${expired ? \", expired\" : \"\"} ${key} (byteSize=${byteSize.toLocaleString()})`,\n );\n\n numToCut--;\n bytesToCut -= byteSize;\n\n delete newState[key];\n needUpdate = true;\n };\n\n let entriesByTimeAscending = Object.entries(newState).sort(\n (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs,\n );\n\n // Clean up all expired entries. Note that the auto-expiration in the\n // storage adapter only applies to the entire state, which contains all\n // the different query keys and their values. Each query key has its own\n // timestamp and we need to apply our own expiration here.\n for (const [key] of entriesByTimeAscending) {\n // Anything after this is not expired yet.\n if (!this.isExpired(newState[key].lastUpdatedMs)) {\n break;\n }\n\n deleteKeyIfNotMounted(key, true);\n }\n\n if (numToCut > 0 \|\| bytesToCut > 0) {\n if (needUpdate) {\n entriesByTimeAscending = Object.entries(newState).sort(\n (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs,\n );\n }\n\n // Clean up starting from oldest entry first.\n for (const [key] of entriesByTimeAscending) {\n deleteKeyIfNotMounted(key, false);\n\n if (numToCut <= 0 && bytesToCut <= 0) {\n break;\n }\n }\n }\n\n // Log to indicate why trimming was not needed.\n if (!needUpdate) {\n this.log(\n `No trimmable entries found for ${this.queryName}: size=${oldSize} (limit=${this.maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`,\n );\n return;\n }\n\n // Update the state.\n this.queryState.setValue(newState);\n\n // Log to inform user that the data was trimmed.\n this.log(\n `Trimmed data for ${this.queryName}: size=[${oldSize} -> ${Object.keys(newState).length}] (limit=${this.maxSize}), byteSize=[${oldByteSize.toLocaleString()} -> ${getByteSize(newState).toLocaleString()}] (limit=${this.maxBytes.toLocaleString()})`,\n );\n }\n}\n\n// Disallow duplicate query names.\nconst seenQueryNames = new Set<string>();\n\n/\n Create a reusable shared query object that can be used to auto de-duplicate\n * and cache all data fetches, with auto-expiration and staleness checks.\n \n Each `queryName` must be unique, and can only be declared once, most often\n * in the top level scope. The queryName is used for logging only.\n \n Example:\n * ```\n * export const usersQuery = sharedQuery({\n * queryName: \"users\",\n * queryFn: listUsers,\n * persistTo: \"indexedDb\",\n * staleMs: MS_PER_DAY,\n * });\n * ```\n /\nexport function sharedQuery<TArgs extends unknown[], TData>(\n // The name could have been auto-generated, but we let the user give us a\n // human-readable name that can be identified quickly in the logs.\n options: SharedQueryOptions<TArgs, TData>,\n): SharedQuery<TArgs, TData> {\n if (seenQueryNames.has(options.queryName)) {\n throw new Error(`Duplicate shared query \"${options.queryName}\"`);\n }\n seenQueryNames.add(options.queryName);\n\n return new SharedQuery(options);\n}\n\n// Using any so that we don't need to typecast later.\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst DEFAULT_QUERY_STATE_ENTRY: Readonly<QueryStateValue<any>> = {\n lastUpdatedMs: 0,\n loading: true,\n};\n\n/\n React hook to make use of a shared query inside any React component. The\n * args do not need to be specified if no args are needed, i.e. this would work\n * ```\n * const allUsers = useSharedQuery(listUsersQuery);\n * ```\n \n Example:\n * ```\n * const users = useSharedQuery(usersQuery, \"userid123\");\n * ```\n /\nexport function useSharedQuery<TArgs extends unknown[], TData>(\n query: SharedQuery<TArgs, TData>,\n // Optional: Default to use no arguments.\n ...args: TArgs\n): UseQueryResult<TData> {\n // We don't expect users to provide a stable `args`, so stabilize it here.\n const stableArgs = useDeepMemo(args);\n\n const [queryState, setQueryState] = useSharedState(query.queryState);\n\n const isMounted = useRef(true);\n\n const queryKey = useMemo(\n () => query.getQueryKey(stableArgs),\n [query, stableArgs],\n );\n\n // Init with empty object.\n const queryStateValue: QueryStateValue<TData> =\n queryState[queryKey] ?? DEFAULT_QUERY_STATE_ENTRY;\n\n const setQueryStateValue = useCallback(\n (next: SetStateAction<QueryStateValue<TData>>) => {\n setQueryState((prev) => {\n const clone = { ...prev };\n clone[queryKey] =\n typeof next === \"function\"\n ? next(clone[queryKey] ?? DEFAULT_QUERY_STATE_ENTRY)\n : next;\n return clone;\n });\n },\n [queryKey, setQueryState],\n );\n\n // Keep the last non-empty data loaded in case you want to show a placeholder\n // during new loads.\n const [lastNonEmptyData, setLastNonEmptyData] = useState<TData \| undefined>();\n\n useEffect(() => {\n if (query.keepLastNonEmptyData && queryStateValue.data !== undefined) {\n setLastNonEmptyData(queryStateValue.data);\n }\n }, [query.keepLastNonEmptyData, queryStateValue.data]);\n\n // The fetch logic wrapped in useCallback to be stable for useEffect\n const execute = useCallback(\n async (forceRefresh: boolean) => {\n query.log(`Begin executing shared query ${queryKey}`);\n\n setQueryStateValue((prev) => ({\n // Keep old data and error.\n ...prev,\n lastUpdatedMs: Date.now(),\n loading: true,\n }));\n\n try {\n const data = await (forceRefresh\n ? query.updateFromSource(...stableArgs)\n : query.getCachedOrFetch(...stableArgs));\n\n if (isMounted.current) {\n const now = Date.now();\n\n setQueryStateValue({\n // Don't keep old error.\n lastUpdatedMs: now,\n loading: false,\n data,\n dataUpdatedMs: now,\n });\n }\n } catch (e) {\n if (isMounted.current) {\n const now = Date.now();\n\n setQueryStateValue((prev) => ({\n // Keep old data.\n ...prev,\n lastUpdatedMs: now,\n loading: false,\n error: e,\n errorUpdatedMs: now,\n }));\n }\n }\n },\n [query, queryKey, setQueryStateValue, stableArgs],\n );\n\n useEffect(() => {\n isMounted.current = true;\n query.mount(queryKey);\n\n void execute(false);\n\n return () => {\n isMounted.current = false;\n query.unmount(queryKey);\n };\n }, [execute, query, queryKey]);\n\n return useMemo(() => {\n return {\n ...queryStateValue,\n lastNonEmptyData,\n // This works only if the user-given queryFn supports abort. If not,\n // this function doesn't do anything, since we don't have any means to\n // abort the running queryFn.\n abortCurrentQuery: (reason?: unknown) => {\n const controller = query.getAbortControllerByKey(queryKey);\n controller?.abort(reason);\n return Boolean(controller);\n },\n refetch: () => {\n void execute(true);\n },\n setData: (data: TData, dataUpdatedMs?: number) => {\n const now = Date.now();\n setQueryStateValue((prev) => ({\n ...prev,\n data,\n dataUpdatedMs: dataUpdatedMs ?? now,\n lastUpdatedMs: now,\n loading: false,\n }));\n },\n deleteData: () => {\n setQueryState((prev) => {\n const clone = { ...prev };\n delete clone[queryKey];\n return clone;\n });\n },\n } satisfies UseQueryResult<TData>;\n }, [\n execute,\n lastNonEmptyData,\n query,\n queryKey,\n queryStateValue,\n setQueryState,\n setQueryStateValue,\n ]);\n}\n","/\n @packageDocumentation\n \n The \"shared state\" is a React state that shares the same value across the\n * entire app. It is largely similar to the jotai library, but is much smaller\n * and much easier to work with when used for persisting in local storage or\n * indexed db, with an automatic expiration for persisted values.\n \n This library aims to be the shortest, simplest, easiest to use, and most\n * efficient implementation of shared global React states with seamless support\n * for client persistence.\n \n Example:\n * ```\n * import { sharedState, useSharedState } from \"@choksheak/react-utils/sharedState\";\n \n // Create a new shared state in the top level scope.\n * // The first argument is the default value, which is required.\n * // The second argument is an options object, and is optional (defaults\n * // to storing in memory only without any persistence).\n * const usersState = sharedState([], { indexedDbKey: \"users\" });\n \n export const UsersComponent: React.FC = () => {\n * // Get both the value and the setter.\n * const [users, setUsers] = useSharedState(usersState);\n * ...\n * };\n \n export const ReadOnlyComponent: React.FC = () => {\n * // Get the value only.\n * const users = useSharedStateValue(usersState);\n * ...\n * };\n \n export const WriteOnlyComponent: React.FC = () => {\n * // Get the setter only.\n * const setUsers = useSharedStateSetter(usersState);\n * ...\n * };\n * ```\n /\n\nimport { StorageAdapter } from \"@choksheak/ts-utils/storageAdapter\";\nimport { MS_PER_DAY } from \"@choksheak/ts-utils/timeConstants\";\nimport { Dispatch, SetStateAction, useSyncExternalStore } from \"react\";\n\nimport { getStorageAdapter, StorageOptions } from \"./storage\";\n\n/**********************************************************************/\n/ Global config /\n/*********************************************************************/\n\n/\n * These values are configurable by the user at any time.\n /\nexport const SharedStateConfig = {\n /\n Default duration for storage expiration in milliseconds. Initial value\n * is 30 days, but can be changed to anything.\n /\n storeExpiryMs: 30 MS_PER_DAY,\n\n /*\n True to load from storage only on mount, false (default) to load in\n * the top level scope when the shared state is defined.\n /\n lazyLoad: false,\n};\n\nexport type SharedStateConfig = typeof SharedStateConfig;\n\n/* Convenience function to update global defaults. /\nexport function configureSharedState(config: Partial<SharedStateConfig>) {\n Object.assign(SharedStateConfig, config);\n}\n\n/**********************************************************************/\n/ Shared state implementation /\n/*********************************************************************/\n\ntype Subscriber<T> = (next: T, prev: T) => void;\n\nclass PubSubStore {\n private dataByKey = new Map<string, unknown>();\n private subscribersByKey = new Map<string, Set<Subscriber<unknown>>>();\n\n // This could be undefined if T includes undefined, else it should never\n // return undefined because the user has to always specify the default value.\n public get<T>(key: string): T {\n return this.dataByKey.get(key) as T;\n }\n\n public set<T>(key: string, value: T): void {\n const prev = this.dataByKey.get(key) as T;\n\n // Do nothing if no change.\n if (prev === value) return;\n\n this.dataByKey.set(key, value);\n this.notify(key, value, prev);\n }\n\n public delete(key: string): void {\n this.dataByKey.delete(key);\n }\n\n public setNoNotify<T>(key: string, value: T): void {\n this.dataByKey.set(key, value);\n }\n\n // Subscribe to changes of a specific key\n public subscribe<T>(key: string, subscriber: Subscriber<T>): () => void {\n let subscribers = this.subscribersByKey.get(key);\n if (!subscribers) {\n subscribers = new Set();\n this.subscribersByKey.set(key, subscribers);\n }\n\n // Type coercion: we store Subscriber<unknown>\n subscribers.add(subscriber as Subscriber<unknown>);\n\n // Return unsubscribe function\n return () => {\n subscribers.delete(subscriber as Subscriber<unknown>);\n if (subscribers.size === 0) this.subscribersByKey.delete(key);\n };\n }\n\n private notify<T>(key: string, next: T, prev: T): void {\n const subscribers = this.subscribersByKey.get(key);\n if (!subscribers) return;\n\n // Make copy to protect against mutation during iteration.\n const copy = Array.from(subscribers.values());\n for (const subscriber of copy) {\n try {\n subscriber(next, prev);\n } catch (e) {\n console.error(`Error invoking subscriber:`, e);\n }\n }\n }\n}\n\nconst pubSubStore = new PubSubStore();\n\nconst STORAGE_KEY = \"state\";\n\n/ Options to configure a shared state. /\nexport type SharedStateOptions<T> = {\n lazyLoad?: boolean;\n} & StorageOptions<T>;\n\nlet stateKey = 0;\n\n/* Please use sharedState() instead. /\nexport class SharedState<T> {\n private readonly pubSubKey: string;\n private readonly storageAdapter: StorageAdapter<T> \| null;\n public readonly setValueBounded: Dispatch<SetStateAction<T>>;\n public initStarted = false;\n public initDone = false;\n\n public constructor(\n private readonly defaultValue: T,\n options?: SharedStateOptions<T>,\n ) {\n this.pubSubKey = String(stateKey++);\n\n // Use max of 1 storage adapter per shared state.\n this.storageAdapter = getStorageAdapter(\n options,\n SharedStateConfig.storeExpiryMs,\n );\n\n // Same as this.setValue, but binding the `this` reference.\n this.setValueBounded = (next: SetStateAction<T>) => {\n this.setValue(next);\n };\n\n // Always set the default value first to avoid returning undefineds if that\n // is not part of T.\n pubSubStore.setNoNotify(this.pubSubKey, defaultValue);\n\n const lazyLoad = options?.lazyLoad;\n const lazy = lazyLoad !== undefined ? lazyLoad : SharedStateConfig.lazyLoad;\n\n if (!lazy) {\n void this.initDefaultValueOnce();\n }\n }\n\n // `subscribe` function required by useSyncExternalStore\n public subscribe(subscriber: () => void): () => void {\n return pubSubStore.subscribe(this.pubSubKey, () => subscriber());\n }\n\n // Get the value of the shared state.\n // `getSnapshot` function — must return same ref if value unchanged\n public getSnapshot(): T {\n return pubSubStore.get(this.pubSubKey);\n }\n\n // Set the value of the shared state.\n public setValue(next: SetStateAction<T>): void {\n if (typeof next === \"function\") {\n const prev = pubSubStore.get<T>(this.pubSubKey);\n next = (next as (p: T) => T)(prev);\n }\n\n pubSubStore.set(this.pubSubKey, next);\n void this.storageAdapter?.set(STORAGE_KEY, next);\n }\n\n // Remove the value of the shared state. Actually this just sets the value\n // back to the given default value.\n public delete() {\n pubSubStore.set(this.pubSubKey, this.defaultValue);\n void this.storageAdapter?.set(STORAGE_KEY, this.defaultValue);\n }\n\n // Initial default handling\n public async initDefaultValueOnce() {\n if (this.initDone \|\| this.initStarted) return;\n this.initStarted = true;\n\n const v = await this.storageAdapter?.get(STORAGE_KEY);\n const value = v !== undefined ? v : this.defaultValue;\n pubSubStore.set(this.pubSubKey, value);\n this.initDone = true;\n\n // Make sure React rerenders with the new initDone=true set.\n pubSubStore.set(this.pubSubKey, value);\n }\n}\n\n/\n Create a new shared state object. Put this code at the top level scope:\n \n Example:\n * ```\n * const counterState = sharedState<number>(0);\n * ```\n /\nexport function sharedState<T>(\n defaultValue: T,\n options?: SharedStateOptions<T>,\n): SharedState<T> {\n return new SharedState(defaultValue, options);\n}\n\n/\n React hook for subscribing to a key in the global store.\n \n Example:\n * ```\n * const [counter, setCounter] = useSharedState(counterState);\n * ```\n /\nexport function useSharedState<T>(\n state: SharedState<T>,\n): [T, Dispatch<SetStateAction<T>>] {\n state.initDefaultValueOnce();\n\n const value = useSyncExternalStore(\n (onStoreChange) => state.subscribe(onStoreChange),\n () => state.getSnapshot(),\n // getServerSnapshot is needed to prevent SSR dev errors in nextjs.\n () => state.getSnapshot(),\n );\n\n return [value, state.setValueBounded];\n}\n\n/\n Same as useSharedState(), but returns the value only.\n \n Example:\n * ```\n * const counter = useSharedStateValue(counterState);\n * ```\n /\nexport function useSharedStateValue<T>(state: SharedState<T>) {\n return useSharedState(state)[0];\n}\n\n/\n Same as useSharedState(), but returns the setter only.\n \n Example:\n * ```\n * const setCounter = useSharedStateSetter(counterState);\n * ```\n /\nexport function useSharedStateSetter<T>(state: SharedState<T>) {\n return useSharedState(state)[1];\n}\n","import { kvStore } from \"@choksheak/ts-utils/kvStore\";\nimport { LocalStore } from \"@choksheak/ts-utils/localStore\";\nimport { StorageAdapter } from \"@choksheak/ts-utils/storageAdapter\";\n\n/* List of all available pre-built persistence options. /\nexport type PersistTo = \"localStorage\" \| \"indexedDb\";\n\nexport type StoreOptions = {\n persistTo: PersistTo;\n\n // Storage key to act as a namespace to store the data.\n key: string;\n\n // How long to wait before the value is considered expired.\n expiryMs?: number;\n};\n\nexport type StorageOptions<T> = {\n /\n You can either specify the storage adapter directly to use a custom\n * store, or specify the properties to use the pre-built ones.\n /\n store?: StorageAdapter<T> \| StoreOptions;\n};\n\nexport function getStorageAdapter<T>(\n options: StorageOptions<T> \| undefined,\n defaultStoreExpiryMs: number,\n): StorageAdapter<T> \| null {\n const { store } = options ?? {};\n\n if (!store) {\n return null;\n }\n\n if (\n \"persistTo\" in store &&\n typeof store.persistTo === \"string\" &&\n \"key\" in store &&\n typeof store.key === \"string\"\n ) {\n const expiryMs = store.expiryMs \|\| defaultStoreExpiryMs;\n\n switch (store.persistTo) {\n case \"localStorage\": {\n const adapter = new LocalStore(store.key, {\n defaultExpiryMs: expiryMs,\n });\n\n // Handle SSR.\n return {\n set: (key: string, value: T): void => {\n if (typeof window === \"undefined\") return; // handle SSR\n\n // Also apply the custom expiryMs on every item in this store.\n adapter.set(key, value);\n },\n get: (key: string): T \| undefined => {\n if (typeof window === \"undefined\") return undefined; // handle SSR\n\n return adapter.get(key);\n },\n delete: (key: string): void => {\n if (typeof window === \"undefined\") return; // handle SSR\n\n adapter.delete(key);\n },\n clear: (): void => {\n if (typeof window === \"undefined\") return; // handle SSR\n\n adapter.clear();\n },\n };\n }\n\n case \"indexedDb\": {\n // Use the key prefix as a unique namespace for this store.\n const keyPrefix = store.key + \":\";\n\n // Prefix all keys using `keyPrefix` so that we can keep all data in\n // the same store in the same DB. If we keep the data in different\n // DB stores, then GC will not be able to clean up abandoned stores.\n return {\n set: async (key: string, value: T): Promise<void> => {\n if (typeof window === \"undefined\") return; // handle SSR\n\n // Also apply the custom expiryMs on every item in this store.\n await kvStore.set(keyPrefix + key, value, expiryMs);\n },\n get: async (key: string): Promise<T \| undefined> => {\n if (typeof window === \"undefined\") return undefined; // handle SSR\n\n return await kvStore.get(keyPrefix + key);\n },\n delete: async (key: string): Promise<void> => {\n if (typeof window === \"undefined\") return; // handle SSR\n\n await kvStore.delete(keyPrefix + key);\n },\n clear: async (): Promise<void> => {\n if (typeof window === \"undefined\") return; // handle SSR\n\n await kvStore.clear();\n },\n };\n }\n\n default:\n store.persistTo satisfies never;\n throw new Error(`Unknown store.adapter ${store.persistTo}`);\n }\n }\n\n return store as StorageAdapter<T>;\n}\n","/\n JSON stringify a value of any type, and returns an unsafe string. The string\n * is \"unsafe\" because you might not be able to restore the original object\n * using the serialized JSON. This is specifically used for query key generation\n * and is not suitable for more general uses.\n \n Note: The given value should not contain any functions because functions\n * cannot be serialized and deserialized properly.\n /\nexport function stringifyDeterministicForKeys(params: unknown): string {\n const cache = new Set();\n\n return JSON.stringify(params, (_, value) => {\n if (typeof value === \"function\") {\n throw new Error(`Functions should not be passed into query parameters`);\n }\n\n if (!value \|\| typeof value !== \"object\" \|\| Array.isArray(value)) {\n return value;\n }\n\n if (cache.has(value)) {\n // Circular reference detected! Return a placeholder string.\n return \"[Circular]\";\n }\n\n cache.add(value);\n\n // Don't crash on circular references, but don't mark the top level object\n // as circular because we want to return as much string as possible.\n if (value !== params) {\n try {\n JSON.stringify(value);\n } catch {\n return \"[Unserializable]\";\n }\n }\n\n return Object.keys(value)\n .sort()\n .reduce(\n (result: Record<string, unknown>, key: string) => {\n result[key] = value[key];\n return result;\n },\n {} as Record<string, unknown>,\n );\n });\n}\n","import isEqual from \"lodash/isEqual\";\nimport { useMemo, useState } from \"react\";\n\n/\n Provides a stable value for T based on deep equality. The deep equality is\n * determined by the `isEqual()` function in lodash.\n */\nexport function useDeepMemo<T>(value: T): T {\n const [state, setState] = useState<T>(value);\n\n return useMemo(() => {\n if (state === value \|\| isEqual(state, value)) {\n return state;\n }\n\n // We check equality, so this should be safe.\n // eslint-disable-next-line react-hooks/set-state-in-render\n setState(value);\n\n return value;\n }, [state, value]);\n}\n"],"mappings":"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","names":["MS_PER_DAY","getByteSize","useCallback","useEffect","useMemo","useRef","useState","MS_PER_DAY","useSyncExternalStore","kvStore","LocalStore","getStorageAdapter","options","defaultStoreExpiryMs","store","expiryMs","adapter","key","value","keyPrefix","SharedStateConfig","MS_PER_DAY","PubSubStore","key","value","prev","subscriber","subscribers","next","copy","e","pubSubStore","STORAGE_KEY","stateKey","SharedState","defaultValue","options","getStorageAdapter","SharedStateConfig","lazyLoad","v","sharedState","useSharedState","state","useSyncExternalStore","onStoreChange","stringifyDeterministicForKeys","params","cache","_","value","result","key","isEqual","useMemo","useState","useDeepMemo","value","state","setState","SharedQueryConfig","MS_PER_DAY","args","configureSharedQuery","config","SharedQuery","options","persistTo","sharedState","stringifyDeterministicForKeys","queryKey","dataUpdatedMs","cached","inflightQuery","promise","abortController","data","e","stateValue","entry","prev","key","clone","inflight","count","oldState","oldSize","oldByteSize","getByteSize","numToCut","bytesToCut","newState","needUpdate","deleteKeyIfNotMounted","expired","byteSize","entriesByTimeAscending","entry1","entry2","seenQueryNames","sharedQuery","DEFAULT_QUERY_STATE_ENTRY","useSharedQuery","query","stableArgs","useDeepMemo","queryState","setQueryState","useSharedState","isMounted","useRef","useMemo","queryStateValue","setQueryStateValue","useCallback","next","lastNonEmptyData","setLastNonEmptyData","useState","useEffect","execute","forceRefresh","now","reason","controller"]}
1	+ {"version":3,"sources":["../src/sharedQuery.ts","../src/sharedState.ts","../src/storage.ts","../src/stringify.ts","../src/useDeepMemo.ts"],"sourcesContent":["/*\n @packageDocumentation\n \n The \"shared query\" is a data fetching convenience library that helps users\n * to load data, check for staleness and expiration, cache in memory, local\n * storage or indexed db, and be able to manipulate the data anytime.\n \n Each shared query creates a new private shared state that handles the data\n * storage. This shared state contains the records for all queries, where each\n * query is a unique set of arguments used to make the query. The number of\n * records and the total byte size of data can be limited so as to ensure the\n * query does not take up too much memory.\n \n Example:\n * ```\n * import { sharedQuery, useSharedQuery } from \"@choksheak/react-utils/sharedQuery\";\n \n // Create a new shared query in the top level scope.\n * // The query function `queryFn` here does not take any arguments.\n * //\n * // Only the queryName and queryFn are required and everything else is\n * // optional.\n * //\n * // The queryName must be unique, otherwise we will throw an\n * // error. This is because defining the same queryName for two different\n * // queries implies that the queries are the same, thus violating the idea\n * // of a \"shared\" query, and almost certainly points to a bug in the code.\n * export const usersQuery = sharedQuery({\n * queryName: \"users\",\n * queryFn: listUsers,\n * persistTo: \"indexedDb\",\n * staleMs: MS_PER_DAY,\n * });\n \n // Note that the query will only start fetching on mount in React.\n * // But you can do `usersQuery.getCachedOrFetch()` here to prefetch the\n * // data if necessary.\n * usersQuery.getCachedOrFetch();\n \n // Example of using a query function with arguments.\n * export const getUserQuery = sharedQuery({\n * queryName: \"getUser\",\n * queryFn: getUser, // getUser(userId: string) => User\n * persistTo: \"indexedDb\",\n * staleMs: MS_PER_DAY,\n * });\n \n export const UsersComponent: React.FC = () => {\n * // Second argument is optional, and is an array of arguments to be\n * // passed to the `queryFn`.\n * const users = useSharedQuery(usersQuery);\n \n return (\n * <>\n * <h1>List of Users</h1>\n \n <button onclick={users.refetch}>Refresh</button>\n \n {users.loading && <Loader />}\n \n {users.error && !users.data && <p>Error: {String(users.error)}</p>}\n \n <p>Data: {users.data ? JSON.stringify(users.data) : \"-\"}</p>\n * </>\n * );\n * };\n \n export const AnotherComponent: React.FC = () => {\n * // This query will be deduped with the one above, sharing the same\n * // data and the same fetches.\n * const users = useSharedQuery(usersQuery);\n * ...\n * };\n \n export const DisplayOneUser: React.FC<{userId: string}> = ({userId}) => {\n * // Example of using the query with an argument. Whenever the argument\n * // changes, the data will be fetched and updated automatically.\n * const user = useSharedQuery(getUserQuery, [userId]);\n \n return <>User: {user.data ? JSON.stringify(user.data) : \"-\"}</>;\n * };\n * ```\n /\n\nimport { MS_PER_DAY } from \"@choksheak/ts-utils/timeConstants\";\nimport getByteSize from \"object-sizeof\";\nimport {\n SetStateAction,\n useCallback,\n useEffect,\n useMemo,\n useRef,\n useState,\n} from \"react\";\n\nimport {\n SharedState,\n sharedState,\n SharedStateOptions,\n useSharedState,\n} from \"./sharedState\";\nimport { PersistTo } from \"./storage\";\nimport { stringifyDeterministicForKeys } from \"./stringify\";\nimport { useDeepMemo } from \"./useDeepMemo\";\n\n/* Type of the queryFn used to fetch the data from source. /\nexport type QueryFn<TArgs extends unknown[], TData> = (\n ...args: TArgs\n) => Promise<TData> \| TData;\n\n/* An entry for a persisted state corresponding to one query key. /\nexport type QueryStateValue<TData> = Readonly<{\n /\n When this record was last updated. Used for LRU determination. If you want\n * the data age, please use `dataUpdatedMs` instead.\n /\n lastUpdatedMs: number;\n\n loading: boolean;\n data?: TData;\n dataUpdatedMs?: number;\n\n /\n Use unknown type for error because we can't assume what type of variable\n * will be thrown from the query function. We also don't want to add this\n * type to QueryStateValue<TError> as it adds complexity to the type.\n /\n error?: unknown;\n\n errorUpdatedMs?: number;\n}>;\n\n/* Return type for useSharedQuery(). /\nexport type UseQueryResult<TData> = QueryStateValue<TData> &\n Readonly<{\n /\n Return the last non-empty data if you want to display the last loaded data\n * while waiting for the new data to load.\n /\n lastNonEmptyData: TData \| undefined;\n\n /\n Cancels the inflight query (if any). Returns true if canceled.\n /\n abortCurrentQuery: (reason?: unknown) => boolean;\n\n /\n Manually refresh the data by doing a new query.\n /\n refetch: () => void;\n\n /\n If you got the data from somewhere else (e.g. an in-memory data update),\n * just set it directly.\n /\n setData: (data: TData, dataUpdatedMs?: number) => void;\n\n deleteData: () => void;\n }>;\n\n/\n The full query state is a record of all the fetch states mapped by\n * query key to the state entry.\n /\nexport type SharedQueryState<TData> = Record<string, QueryStateValue<TData>>;\n\n/* Options to configure a shared query. /\nexport type SharedQueryOptions<TArgs extends unknown[], TData> = {\n /\n The name could have been auto-generated, but we let the user give us a\n * human-readable name that can be identified quickly in the logs.\n * Note that the queryKey is a string formed by the queryName plus the query\n * arguments.\n /\n queryName: string;\n\n /\n Function to fetch data.\n /\n queryFn: QueryFn<TArgs, TData>;\n\n /\n ms before data considered stale; 0 means always stale.\n /\n staleMs?: number;\n\n /\n ms before data is removed from cache; 0 means never expire.\n /\n expiryMs?: number;\n\n /\n Trigger background re-fetch if stale.\n /\n refetchOnStale?: boolean;\n\n /\n Shortcut to set the localStorageKey or indexedDbKey automatically from\n * queryName. This is important because it avoids requiring the user to\n * specify the same queryName twice everytime.\n /\n persistTo?: PersistTo;\n\n /\n Max number of entries to keep. The oldest entries will be discarded.\n * The last record cannot be discarded. 0 means no limit.\n /\n maxSize?: number;\n\n /\n Max number of bytes to keep. The oldest entries will be discarded.\n * The last record cannot be discarded. 0 means no limit.\n /\n maxBytes?: number;\n\n /\n Keep a copy of the last non-empty data so that when you change the\n * query arguments, you can still display the old data while waiting for the\n * new data to load.\n /\n keepLastNonEmptyData?: boolean;\n\n /\n Customize the logger.\n /\n log?: (...args: unknown[]) => void;\n} & SharedStateOptions<SharedQueryState<TData>>;\n\n/* Users can override these values globally. /\nexport const SharedQueryConfig = {\n /* Refetch on every page load. /\n staleMs: 0,\n\n /* Keep in cache for a long time. /\n expiryMs: 30 MS_PER_DAY,\n\n /** Always refetch automatically if the data is stale. /\n refetchOnStale: true,\n\n /* No default persistence configured. /\n persistTo: undefined as PersistTo \| undefined,\n\n /* 100 is not too large, but please tweak accordingly. /\n maxSize: 100,\n\n /* 100kb limit before discarding old records. /\n maxBytes: 100_000,\n\n /* Default to log to console. /\n log: (...args: unknown[]) => console.log(\"[sharedQuery]\", ...args),\n};\n\nexport type SharedQueryConfig = typeof SharedQueryConfig;\n\n/* Convenience function to update global defaults. /\nexport function configureSharedQuery(config: Partial<SharedQueryConfig>) {\n Object.assign(SharedQueryConfig, config);\n}\n\n/* Please use sharedQuery() instead. /\nexport class SharedQuery<TArgs extends unknown[], TData> {\n private readonly inflightQueries = new Map<\n string,\n { promise: Promise<TData>; abortController: AbortController }\n >();\n\n public readonly queryState: SharedState<SharedQueryState<TData>>;\n\n /\n Keep track of the mounted query keys. This handles the case where an\n * earlier-started query returns later, and when it returns, it was already\n * unmounted, thus making it eligible for clean up right after fetch.\n /\n private readonly mountedKeys = new Map<string, number>();\n\n public readonly queryName: string;\n private readonly queryFn: QueryFn<TArgs, TData>;\n public readonly expiryMs: number;\n public readonly staleMs: number;\n public readonly refetchOnStale: boolean;\n public readonly maxSize: number;\n public readonly maxBytes: number;\n public readonly keepLastNonEmptyData: boolean;\n public readonly log: (...args: unknown[]) => void;\n\n public constructor(options: SharedQueryOptions<TArgs, TData>) {\n this.queryName = options.queryName;\n this.queryFn = options.queryFn;\n\n this.staleMs = options?.staleMs ?? SharedQueryConfig.staleMs;\n this.expiryMs = options?.expiryMs ?? SharedQueryConfig.expiryMs;\n\n this.refetchOnStale =\n options?.refetchOnStale ?? SharedQueryConfig.refetchOnStale;\n\n // Apply shortcut when using `persistTo`.\n // Specifying the `store` will take precedence over `persistTo`.\n if (!options.store) {\n const persistTo = options.persistTo ?? SharedQueryConfig.persistTo;\n\n if (persistTo) {\n options.store = {\n persistTo,\n key: options.queryName,\n expiryMs: this.expiryMs,\n };\n }\n }\n\n this.maxSize = options?.maxSize ?? SharedQueryConfig.maxSize;\n this.maxBytes = options?.maxBytes ?? SharedQueryConfig.maxBytes;\n\n this.keepLastNonEmptyData = Boolean(options?.keepLastNonEmptyData);\n\n this.log = options?.log ?? SharedQueryConfig.log;\n\n this.queryState = sharedState<SharedQueryState<TData>>(\n {}, // defaultValue\n options,\n );\n }\n\n /* Returns a key to identify requests based on the given args. /\n public getQueryKey(args: TArgs): string {\n return this.queryName + \":\" + stringifyDeterministicForKeys(args);\n }\n\n /\n Get the AbortController to abort the inflight query (if any).\n \n Note that once you get the controller, you can also get the signal easily\n * using `controller.signal`. So if you need both the controller and the\n * signal, just use this function.\n /\n public getAbortController(args: TArgs): AbortController \| null {\n const queryKey = this.getQueryKey(args);\n return this.getAbortControllerByKey(queryKey);\n }\n\n public getAbortControllerByKey(queryKey: string): AbortController \| null {\n return this.inflightQueries.get(queryKey)?.abortController ?? null;\n }\n\n /\n Get the AbortSignal to check for query abortions.\n \n Example:\n * ```\n * const getUserQuery = sharedQuery({\n * queryName: \"getUser\",\n * queryFn: (userId: string) => {\n * // Get the signal for this current execution.\n * const signal = getUserQuery.getAbortSignal([userId]);\n \n // Pass the signal to fetch so that it can be aborted.\n * const response = await fetch(`/users/${userId}`, { signal });\n \n // Check for errors.\n * if (!response.ok) {\n * throw new Error(response.statusText);\n * }\n \n // Return the data.\n * return await response.json();\n * },\n * });\n * ```\n /\n public getAbortSignal(args: TArgs): AbortSignal \| null {\n const queryKey = this.getQueryKey(args);\n return this.getAbortSignalByKey(queryKey);\n }\n\n public getAbortSignalByKey(queryKey: string): AbortSignal \| null {\n return this.getAbortControllerByKey(queryKey)?.signal ?? null;\n }\n\n private isStale(dataUpdatedMs: number): boolean {\n if (this.staleMs === 0) return true; // always stale\n\n const ageMs = Date.now() - dataUpdatedMs;\n return ageMs > this.staleMs;\n }\n\n private isExpired(dataUpdatedMs: number): boolean {\n if (this.expiryMs === 0) return false; // never expire\n\n const ageMs = Date.now() - dataUpdatedMs;\n return ageMs > this.expiryMs;\n }\n\n public async getCachedOrFetch(...args: TArgs): Promise<TData> {\n const queryKey = this.getQueryKey(args);\n const cached = this.queryState.getSnapshot()?.[queryKey];\n\n if (cached?.data && !this.isExpired(cached.dataUpdatedMs ?? 0)) {\n // Return cached value if not stale.\n if (!this.isStale(cached.dataUpdatedMs ?? 0)) {\n this.log(`Return fresh data ${queryKey} from cache without fetching`);\n return cached.data;\n }\n\n // If stale, optionally update the data in the background.\n if (this.refetchOnStale) {\n this.log(`refetchOnStale for ${queryKey}`);\n void this.dedupedFetch(queryKey, ...args);\n }\n\n // Still return stale data immediately.\n this.log(`Returning stale data for ${queryKey}`);\n return cached.data;\n }\n\n return await this.dedupedFetch(queryKey, ...args);\n }\n\n private dedupedFetch(queryKey: string, ...args: TArgs): Promise<TData> {\n const inflightQuery = this.inflightQueries.get(queryKey);\n\n // De-duplicate in-flight requests\n if (inflightQuery) {\n this.log(`Deduplicating inflight fetch for ${queryKey}`);\n return inflightQuery.promise;\n }\n\n // Fetch new data\n const promise = this.startFetching(queryKey, args);\n const abortController = new AbortController();\n\n this.inflightQueries.set(queryKey, { promise, abortController });\n\n return promise;\n }\n\n private async startFetching(queryKey: string, args: TArgs) {\n this.log(`Start fetching ${queryKey}`);\n\n try {\n const data = await this.queryFn(...args);\n\n this.log(`Successfully fetched ${queryKey}`);\n this.setData(queryKey, data, Date.now());\n return data;\n } catch (e) {\n this.log(`Failed to fetch ${queryKey}: ${e}`);\n throw e;\n } finally {\n this.inflightQueries.delete(queryKey);\n }\n }\n\n /* Get the entire stored entry for a query key. /\n public getQueryValue(queryKey: string): QueryStateValue<TData> \| undefined {\n return this.queryState.getSnapshot()?.[queryKey];\n }\n\n /* Get the current stored data for a query key. /\n public getData(queryKey: string): TData \| undefined {\n const stateValue: QueryStateValue<TData> \| undefined =\n this.queryState.getSnapshot()?.[queryKey];\n\n // Check for expiration.\n if (stateValue?.lastUpdatedMs) {\n if (this.isExpired(stateValue.lastUpdatedMs)) {\n this.deleteData(queryKey);\n return undefined;\n }\n }\n\n return stateValue?.data;\n }\n\n /* Set the data directly if the user obtained it from somewhere else. /\n public setData(\n queryKey: string,\n data: TData,\n dataUpdatedMs = Date.now(),\n ): void {\n const entry: QueryStateValue<TData> = {\n lastUpdatedMs: Date.now(),\n loading: false,\n data,\n dataUpdatedMs,\n };\n\n this.queryState.setValue((prev) => ({ ...prev, [queryKey]: entry }));\n\n this.enforceSizeLimit();\n }\n\n /\n Do a new fetch even when the data is already cached, but don't fetch if\n * another fetch is already inflight.\n /\n public async updateFromSource(...args: TArgs): Promise<TData> {\n const key = this.getQueryKey(args);\n return await this.dedupedFetch(key, ...args);\n }\n\n /* Delete the cached data for one set of arguments. /\n public deleteData(queryKey: string): void {\n const record = this.queryState.getSnapshot();\n const clone = { ...record };\n delete clone[queryKey];\n this.queryState.setValue(clone);\n\n const inflight = this.inflightQueries.get(queryKey);\n if (inflight) {\n this.inflightQueries.delete(queryKey);\n inflight.abortController.abort(\"Deleted\");\n }\n }\n\n /* Delete all currently cached data & all inflight promises. /\n public clear(): void {\n this.queryState.delete();\n\n for (const { abortController } of Array.from(\n this.inflightQueries.values(),\n )) {\n abortController.abort(\"Cleared\");\n }\n\n this.inflightQueries.clear();\n }\n\n /* Keep track of mounted keys. /\n public mount(queryKey: string): void {\n this.mountedKeys.set(queryKey, (this.mountedKeys.get(queryKey) ?? 0) + 1);\n }\n\n /* Clean up mounted keys. /\n public unmount(queryKey: string): void {\n const count = this.mountedKeys.get(queryKey);\n if (count === 1) {\n this.mountedKeys.delete(queryKey);\n } else {\n this.mountedKeys.set(queryKey, (count ?? 0) - 1);\n }\n }\n\n /\n Discard the oldest entries if the size exceeds the limit. The last\n * remaining record cannot be deleted no matter what the limit is.\n /\n public enforceSizeLimit(): void {\n // Skip if there are no limits.\n if (!this.maxSize && !this.maxBytes) {\n return;\n }\n\n const oldState = this.queryState.getSnapshot();\n const oldSize = Object.keys(oldState).length;\n\n // Cannot do GC if size is 1 or less.\n if (oldSize <= 1) {\n return;\n }\n\n const oldByteSize = getByteSize(oldState);\n\n let numToCut = this.maxSize ? oldSize - this.maxSize : 0;\n let bytesToCut = this.maxBytes ? oldByteSize - this.maxBytes : 0;\n\n // Log to indicate why trimming was not needed.\n if (numToCut <= 0 && bytesToCut <= 0) {\n this.log(\n `No need to trim data for ${this.queryName}: size=${oldSize} (limit=${this.maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`,\n );\n return;\n }\n\n // Log to inform user that trimming is needed.\n this.log(\n `Need to trim ${this.queryName}: numToCut=${numToCut}, bytesToCut=${bytesToCut}`,\n );\n\n const newState = { ...oldState }; // shallow clone\n let needUpdate = false;\n\n const deleteKeyIfNotMounted = (key: string, expired: boolean) => {\n // Mounted keys cannot be cleaned up as they are visible in the UI.\n if (this.mountedKeys.has(key)) {\n this.log(`Cannot clean up ${key} as it is mounted`);\n return;\n }\n\n const byteSize = getByteSize(key) + getByteSize(newState[key]);\n this.log(\n `Cleaning up unmounted${expired ? \", expired\" : \"\"} ${key} (byteSize=${byteSize.toLocaleString()})`,\n );\n\n numToCut--;\n bytesToCut -= byteSize;\n\n delete newState[key];\n needUpdate = true;\n };\n\n let entriesByTimeAscending = Object.entries(newState).sort(\n (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs,\n );\n\n // Clean up all expired entries. Note that the auto-expiration in the\n // storage adapter only applies to the entire state, which contains all\n // the different query keys and their values. Each query key has its own\n // timestamp and we need to apply our own expiration here.\n for (const [key] of entriesByTimeAscending) {\n // Anything after this is not expired yet.\n if (!this.isExpired(newState[key].lastUpdatedMs)) {\n break;\n }\n\n deleteKeyIfNotMounted(key, true);\n }\n\n if (numToCut > 0 \|\| bytesToCut > 0) {\n if (needUpdate) {\n entriesByTimeAscending = Object.entries(newState).sort(\n (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs,\n );\n }\n\n // Clean up starting from oldest entry first.\n for (const [key] of entriesByTimeAscending) {\n deleteKeyIfNotMounted(key, false);\n\n if (numToCut <= 0 && bytesToCut <= 0) {\n break;\n }\n }\n }\n\n // Log to indicate why trimming was not needed.\n if (!needUpdate) {\n this.log(\n `No trimmable entries found for ${this.queryName}: size=${oldSize} (limit=${this.maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`,\n );\n return;\n }\n\n // Update the state.\n this.queryState.setValue(newState);\n\n // Log to inform user that the data was trimmed.\n this.log(\n `Trimmed data for ${this.queryName}: size=[${oldSize} -> ${Object.keys(newState).length}] (limit=${this.maxSize}), byteSize=[${oldByteSize.toLocaleString()} -> ${getByteSize(newState).toLocaleString()}] (limit=${this.maxBytes.toLocaleString()})`,\n );\n }\n}\n\n// Disallow duplicate query names.\nconst seenQueryNames = new Set<string>();\n\n/\n Create a reusable shared query object that can be used to auto de-duplicate\n * and cache all data fetches, with auto-expiration and staleness checks.\n \n Each `queryName` must be unique, and can only be declared once, most often\n * in the top level scope. The queryName is used for logging only.\n \n Example:\n * ```\n * export const usersQuery = sharedQuery({\n * queryName: \"users\",\n * queryFn: listUsers,\n * persistTo: \"indexedDb\",\n * staleMs: MS_PER_DAY,\n * });\n * ```\n /\nexport function sharedQuery<TArgs extends unknown[], TData>(\n // The name could have been auto-generated, but we let the user give us a\n // human-readable name that can be identified quickly in the logs.\n options: SharedQueryOptions<TArgs, TData>,\n): SharedQuery<TArgs, TData> {\n if (seenQueryNames.has(options.queryName)) {\n throw new Error(`Duplicate shared query \"${options.queryName}\"`);\n }\n seenQueryNames.add(options.queryName);\n\n return new SharedQuery(options);\n}\n\n// Using any so that we don't need to typecast later.\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst DEFAULT_QUERY_STATE_ENTRY: Readonly<QueryStateValue<any>> = {\n lastUpdatedMs: 0,\n loading: true,\n};\n\n/\n React hook to make use of a shared query inside any React component. The\n * args do not need to be specified if no args are needed, i.e. this would work\n * ```\n * const allUsers = useSharedQuery(listUsersQuery);\n * ```\n \n Example:\n * ```\n * const users = useSharedQuery(usersQuery, \"userid123\");\n * ```\n /\nexport function useSharedQuery<TArgs extends unknown[], TData>(\n query: SharedQuery<TArgs, TData>,\n // Optional: Default to use no arguments.\n ...args: TArgs\n): UseQueryResult<TData> {\n // We don't expect users to provide a stable `args`, so stabilize it here.\n const stableArgs = useDeepMemo(args);\n\n const [queryState, setQueryState] = useSharedState(query.queryState);\n\n const isMounted = useRef(true);\n\n const queryKey = useMemo(\n () => query.getQueryKey(stableArgs),\n [query, stableArgs],\n );\n\n // Init with empty object.\n const queryStateValue: QueryStateValue<TData> =\n queryState[queryKey] ?? DEFAULT_QUERY_STATE_ENTRY;\n\n const setQueryStateValue = useCallback(\n (next: SetStateAction<QueryStateValue<TData>>) => {\n setQueryState((prev) => {\n const clone = { ...prev };\n clone[queryKey] =\n typeof next === \"function\"\n ? next(clone[queryKey] ?? DEFAULT_QUERY_STATE_ENTRY)\n : next;\n return clone;\n });\n },\n [queryKey, setQueryState],\n );\n\n // Keep the last non-empty data loaded in case you want to show a placeholder\n // during new loads.\n const [lastNonEmptyData, setLastNonEmptyData] = useState<TData \| undefined>();\n\n useEffect(() => {\n if (query.keepLastNonEmptyData && queryStateValue.data !== undefined) {\n setLastNonEmptyData(queryStateValue.data);\n }\n }, [query.keepLastNonEmptyData, queryStateValue.data]);\n\n // The fetch logic wrapped in useCallback to be stable for useEffect\n const execute = useCallback(\n async (forceRefresh: boolean) => {\n query.log(`Begin executing shared query ${queryKey}`);\n\n setQueryStateValue((prev) => ({\n // Keep old data and error.\n ...prev,\n lastUpdatedMs: Date.now(),\n loading: true,\n }));\n\n try {\n const data = await (forceRefresh\n ? query.updateFromSource(...stableArgs)\n : query.getCachedOrFetch(...stableArgs));\n\n if (isMounted.current) {\n const now = Date.now();\n\n setQueryStateValue({\n // Don't keep old error.\n lastUpdatedMs: now,\n loading: false,\n data,\n dataUpdatedMs: now,\n });\n }\n } catch (e) {\n if (isMounted.current) {\n const now = Date.now();\n\n setQueryStateValue((prev) => ({\n // Keep old data.\n ...prev,\n lastUpdatedMs: now,\n loading: false,\n error: e,\n errorUpdatedMs: now,\n }));\n }\n }\n },\n [query, queryKey, setQueryStateValue, stableArgs],\n );\n\n useEffect(() => {\n isMounted.current = true;\n query.mount(queryKey);\n\n void execute(false);\n\n return () => {\n isMounted.current = false;\n query.unmount(queryKey);\n };\n }, [execute, query, queryKey]);\n\n return useMemo(() => {\n return {\n ...queryStateValue,\n lastNonEmptyData,\n // This works only if the user-given queryFn supports abort. If not,\n // this function doesn't do anything, since we don't have any means to\n // abort the running queryFn.\n abortCurrentQuery: (reason?: unknown) => {\n const controller = query.getAbortControllerByKey(queryKey);\n controller?.abort(reason);\n return Boolean(controller);\n },\n refetch: () => {\n void execute(true);\n },\n setData: (data: TData, dataUpdatedMs?: number) => {\n const now = Date.now();\n setQueryStateValue((prev) => ({\n ...prev,\n data,\n dataUpdatedMs: dataUpdatedMs ?? now,\n lastUpdatedMs: now,\n loading: false,\n }));\n },\n deleteData: () => {\n setQueryState((prev) => {\n const clone = { ...prev };\n delete clone[queryKey];\n return clone;\n });\n },\n } satisfies UseQueryResult<TData>;\n }, [\n execute,\n lastNonEmptyData,\n query,\n queryKey,\n queryStateValue,\n setQueryState,\n setQueryStateValue,\n ]);\n}\n","/\n @packageDocumentation\n \n The \"shared state\" is a React state that shares the same value across the\n * entire app. It is largely similar to the jotai library, but is much smaller\n * and much easier to work with when used for persisting in local storage or\n * indexed db, with an automatic expiration for persisted values.\n \n This library aims to be the shortest, simplest, easiest to use, and most\n * efficient implementation of shared global React states with seamless support\n * for client persistence.\n \n Example:\n * ```\n * import { sharedState, useSharedState } from \"@choksheak/react-utils/sharedState\";\n \n // Create a new shared state in the top level scope.\n * // The first argument is the default value, which is required.\n * // The second argument is an options object, and is optional (defaults\n * // to storing in memory only without any persistence).\n * const usersState = sharedState([], { indexedDbKey: \"users\" });\n \n export const UsersComponent: React.FC = () => {\n * // Get both the value and the setter.\n * const [users, setUsers] = useSharedState(usersState);\n * ...\n * };\n \n export const ReadOnlyComponent: React.FC = () => {\n * // Get the value only.\n * const users = useSharedStateValue(usersState);\n * ...\n * };\n \n export const WriteOnlyComponent: React.FC = () => {\n * // Get the setter only.\n * const setUsers = useSharedStateSetter(usersState);\n * ...\n * };\n * ```\n /\n\nimport { StorageAdapter } from \"@choksheak/ts-utils/storageAdapter\";\nimport { MS_PER_DAY } from \"@choksheak/ts-utils/timeConstants\";\nimport { Dispatch, SetStateAction, useSyncExternalStore } from \"react\";\n\nimport { getStorageAdapter, StorageOptions } from \"./storage\";\n\n/**********************************************************************/\n/ Global config /\n/*********************************************************************/\n\n/\n * These values are configurable by the user at any time.\n /\nexport const SharedStateConfig = {\n /\n Default duration for storage expiration in milliseconds. Initial value\n * is 30 days, but can be changed to anything.\n /\n storeExpiryMs: 30 MS_PER_DAY,\n\n /*\n True to load from storage only on mount, false (default) to load in\n * the top level scope when the shared state is defined.\n /\n lazyLoad: false,\n};\n\nexport type SharedStateConfig = typeof SharedStateConfig;\n\n/* Convenience function to update global defaults. /\nexport function configureSharedState(config: Partial<SharedStateConfig>) {\n Object.assign(SharedStateConfig, config);\n}\n\n/**********************************************************************/\n/ Shared state implementation /\n/*********************************************************************/\n\ntype Subscriber<T> = (next: T, prev: T) => void;\n\nclass PubSubStore {\n private dataByKey = new Map<string, unknown>();\n private subscribersByKey = new Map<string, Set<Subscriber<unknown>>>();\n\n // This could be undefined if T includes undefined, else it should never\n // return undefined because the user has to always specify the default value.\n public get<T>(key: string): T {\n return this.dataByKey.get(key) as T;\n }\n\n public set<T>(key: string, value: T): void {\n const prev = this.dataByKey.get(key) as T;\n\n // Do nothing if no change.\n if (prev === value) return;\n\n this.dataByKey.set(key, value);\n this.notify(key, value, prev);\n }\n\n public delete(key: string): void {\n this.dataByKey.delete(key);\n }\n\n public setNoNotify<T>(key: string, value: T): void {\n this.dataByKey.set(key, value);\n }\n\n // Subscribe to changes of a specific key\n public subscribe<T>(key: string, subscriber: Subscriber<T>): () => void {\n let subscribers = this.subscribersByKey.get(key);\n if (!subscribers) {\n subscribers = new Set();\n this.subscribersByKey.set(key, subscribers);\n }\n\n // Type coercion: we store Subscriber<unknown>\n subscribers.add(subscriber as Subscriber<unknown>);\n\n // Return unsubscribe function\n return () => {\n subscribers.delete(subscriber as Subscriber<unknown>);\n if (subscribers.size === 0) this.subscribersByKey.delete(key);\n };\n }\n\n private notify<T>(key: string, next: T, prev: T): void {\n const subscribers = this.subscribersByKey.get(key);\n if (!subscribers) return;\n\n // Make copy to protect against mutation during iteration.\n const copy = Array.from(subscribers.values());\n for (const subscriber of copy) {\n try {\n subscriber(next, prev);\n } catch (e) {\n console.error(`Error invoking subscriber:`, e);\n }\n }\n }\n}\n\nconst pubSubStore = new PubSubStore();\n\nconst STORAGE_KEY = \"state\";\n\n/ Options to configure a shared state. /\nexport type SharedStateOptions<T> = {\n lazyLoad?: boolean;\n} & StorageOptions<T>;\n\nlet stateKey = 0;\n\n/* Please use sharedState() instead. /\nexport class SharedState<T> {\n private readonly pubSubKey: string;\n private readonly storageAdapter: StorageAdapter<T> \| null;\n public readonly setValueBounded: Dispatch<SetStateAction<T>>;\n public initStarted = false;\n public initDone = false;\n\n public constructor(\n private readonly defaultValue: T,\n options?: SharedStateOptions<T>,\n ) {\n this.pubSubKey = String(stateKey++);\n\n // Use max of 1 storage adapter per shared state.\n this.storageAdapter = getStorageAdapter(\n options,\n SharedStateConfig.storeExpiryMs,\n );\n\n // Same as this.setValue, but binding the `this` reference.\n this.setValueBounded = (next: SetStateAction<T>) => {\n this.setValue(next);\n };\n\n // Always set the default value first to avoid returning undefineds if that\n // is not part of T.\n pubSubStore.setNoNotify(this.pubSubKey, defaultValue);\n\n const lazyLoad = options?.lazyLoad;\n const lazy = lazyLoad !== undefined ? lazyLoad : SharedStateConfig.lazyLoad;\n\n if (!lazy) {\n void this.initDefaultValueOnce();\n }\n }\n\n /* `subscribe` function required by useSyncExternalStore. /\n public subscribe(subscriber: () => void): () => void {\n return pubSubStore.subscribe(this.pubSubKey, () => subscriber());\n }\n\n /* Returns true if there is a backing store. /\n public hasStore(): boolean {\n return Boolean(this.storageAdapter);\n }\n\n /\n Set a value directly into the store. Does nothing if there is no\n * backing store.\n \n Warning: If you want to set the value properly, you should use\n * `setValue()` instead which also updates the in-memory copy.\n /\n public async setInStore(value: T): Promise<void> {\n return await this.storageAdapter?.set(STORAGE_KEY, value);\n }\n\n /\n Get a value directly from the store. Returns undefined if there is no\n * backing store.\n /\n public async getFromStore(): Promise<T \| undefined> {\n return await this.storageAdapter?.get(STORAGE_KEY);\n }\n\n /\n Get the value of the shared state.\n * `getSnapshot` function — must return same ref if value unchanged.\n * Note that this would return the default value if data init from store is\n * not completed yet.\n /\n public getSnapshot(): T {\n return pubSubStore.get(this.pubSubKey);\n }\n\n /* Set the value of the shared state. /\n public setValue(next: SetStateAction<T>): void {\n if (typeof next === \"function\") {\n const prev = pubSubStore.get<T>(this.pubSubKey);\n next = (next as (p: T) => T)(prev);\n }\n\n pubSubStore.set(this.pubSubKey, next);\n void this.setInStore(next);\n }\n\n /\n Remove the value of the shared state. Actually this just sets the value\n * back to the given default value.\n /\n public delete() {\n pubSubStore.set(this.pubSubKey, this.defaultValue);\n void this.storageAdapter?.set(STORAGE_KEY, this.defaultValue);\n }\n\n /* Initial default handling. /\n public async initDefaultValueOnce() {\n if (this.initDone \|\| this.initStarted) return;\n this.initStarted = true;\n\n const stored = await this.getFromStore();\n const value = stored !== undefined ? stored : this.defaultValue;\n\n pubSubStore.set(this.pubSubKey, value);\n\n this.initDone = true;\n }\n}\n\n/\n Create a new shared state object. Put this code at the top level scope:\n \n Example:\n * ```\n * const counterState = sharedState<number>(0);\n * ```\n /\nexport function sharedState<T>(\n defaultValue: T,\n options?: SharedStateOptions<T>,\n): SharedState<T> {\n return new SharedState(defaultValue, options);\n}\n\n/\n React hook for subscribing to a key in the global store.\n \n Example:\n * ```\n * const [counter, setCounter] = useSharedState(counterState);\n * ```\n /\nexport function useSharedState<T>(\n state: SharedState<T>,\n): [T, Dispatch<SetStateAction<T>>] {\n state.initDefaultValueOnce();\n\n const value = useSyncExternalStore(\n (onStoreChange) => state.subscribe(onStoreChange),\n () => state.getSnapshot(),\n // getServerSnapshot is needed to prevent SSR dev errors in nextjs.\n () => state.getSnapshot(),\n );\n\n return [value, state.setValueBounded];\n}\n\n/\n Same as useSharedState(), but returns the value only.\n \n Example:\n * ```\n * const counter = useSharedStateValue(counterState);\n * ```\n /\nexport function useSharedStateValue<T>(state: SharedState<T>) {\n return useSharedState(state)[0];\n}\n\n/\n Same as useSharedState(), but returns the setter only.\n \n Example:\n * ```\n * const setCounter = useSharedStateSetter(counterState);\n * ```\n /\nexport function useSharedStateSetter<T>(state: SharedState<T>) {\n return useSharedState(state)[1];\n}\n","import { kvStore } from \"@choksheak/ts-utils/kvStore\";\nimport { LocalStore } from \"@choksheak/ts-utils/localStore\";\nimport { StorageAdapter } from \"@choksheak/ts-utils/storageAdapter\";\n\n/* List of all available pre-built persistence options. /\nexport type PersistTo = \"localStorage\" \| \"indexedDb\";\n\n/* Options to configure a pre-built store adapter. /\nexport type StoreOptions = {\n /* Choose which pre-built store adapter to use. /\n persistTo: PersistTo;\n\n /* Storage key to act as a namespace to store the data. /\n key: string;\n\n /* How long to wait before the value is considered expired. /\n expiryMs?: number;\n\n /* Returns true if the given value supposed to be of type T is valid. /\n isValid?: (u: unknown) => boolean;\n};\n\n/* Either use a pre-built store, or a custom one you provide. /\nexport type StorageOptions<T> = {\n /\n You can either specify the storage adapter directly to use a custom\n * store, or specify the properties to use the pre-built ones.\n /\n store?: StorageAdapter<T> \| StoreOptions;\n};\n\n// In SSR (Server-Side Rendering) mode, we never want to use our storage\n// adapters for anything.\nconst IS_NOT_BROWSER = typeof window === \"undefined\";\n\nexport function getStorageAdapter<T>(\n options: StorageOptions<T> \| undefined,\n defaultStoreExpiryMs: number,\n): StorageAdapter<T> \| null {\n const { store } = options ?? {};\n\n if (!store) {\n return null;\n }\n\n if (\n \"persistTo\" in store &&\n typeof store.persistTo === \"string\" &&\n \"key\" in store &&\n typeof store.key === \"string\"\n ) {\n const expiryMs = store.expiryMs \|\| defaultStoreExpiryMs;\n const isValid = store.isValid;\n\n switch (store.persistTo) {\n case \"localStorage\": {\n const adapter = new LocalStore(store.key, {\n defaultExpiryMs: expiryMs,\n });\n\n // Handle SSR.\n return {\n set: (key: string, value: T): void => {\n if (IS_NOT_BROWSER) return; // handle SSR\n\n // Also apply the custom expiryMs on every item in this store.\n adapter.set(key, value);\n },\n get: (key: string): T \| undefined => {\n if (IS_NOT_BROWSER) return undefined; // handle SSR\n\n const value = adapter.get<T>(key);\n\n if (isValid && !isValid(value)) {\n console.warn(\n `localStorage adapter: Auto-discard invalid value for ${key}: ${JSON.stringify(value)}`,\n );\n adapter.delete(key);\n return undefined;\n }\n\n return value;\n },\n delete: (key: string): void => {\n if (IS_NOT_BROWSER) return; // handle SSR\n\n adapter.delete(key);\n },\n clear: (): void => {\n if (IS_NOT_BROWSER) return; // handle SSR\n\n adapter.clear();\n },\n };\n }\n\n case \"indexedDb\": {\n // Use the key prefix as a unique namespace for this store.\n const keyPrefix = store.key + \":\";\n const isValid = store.isValid;\n\n // Prefix all keys using `keyPrefix` so that we can keep all data in\n // the same store in the same DB. If we keep the data in different\n // DB stores, then GC will not be able to clean up abandoned stores.\n return {\n set: async (key: string, value: T): Promise<void> => {\n if (IS_NOT_BROWSER) return; // handle SSR\n\n // Also apply the custom expiryMs on every item in this store.\n await kvStore.set(keyPrefix + key, value, expiryMs);\n },\n get: async (key: string): Promise<T \| undefined> => {\n if (IS_NOT_BROWSER) return undefined; // handle SSR\n\n const fullKey = keyPrefix + key;\n const value = await kvStore.get<T>(fullKey);\n\n if (isValid && !isValid(value)) {\n console.warn(\n `indexedDb adapter: Auto-discard invalid value for ${key}: ${JSON.stringify(value)}`,\n );\n await kvStore.delete(fullKey);\n return undefined;\n }\n\n return value;\n },\n delete: async (key: string): Promise<void> => {\n if (IS_NOT_BROWSER) return; // handle SSR\n\n await kvStore.delete(keyPrefix + key);\n },\n clear: async (): Promise<void> => {\n if (IS_NOT_BROWSER) return; // handle SSR\n\n await kvStore.clear();\n },\n };\n }\n\n default:\n store.persistTo satisfies never;\n throw new Error(`Unknown store.adapter ${store.persistTo}`);\n }\n }\n\n return store as StorageAdapter<T>;\n}\n","/\n JSON stringify a value of any type, and returns an unsafe string. The string\n * is \"unsafe\" because you might not be able to restore the original object\n * using the serialized JSON. This is specifically used for query key generation\n * and is not suitable for more general uses.\n \n Note: The given value should not contain any functions because functions\n * cannot be serialized and deserialized properly.\n /\nexport function stringifyDeterministicForKeys(params: unknown): string {\n const cache = new Set();\n\n return JSON.stringify(params, (_, value) => {\n if (typeof value === \"function\") {\n throw new Error(`Functions should not be passed into query parameters`);\n }\n\n if (!value \|\| typeof value !== \"object\" \|\| Array.isArray(value)) {\n return value;\n }\n\n if (cache.has(value)) {\n // Circular reference detected! Return a placeholder string.\n return \"[Circular]\";\n }\n\n cache.add(value);\n\n // Don't crash on circular references, but don't mark the top level object\n // as circular because we want to return as much string as possible.\n if (value !== params) {\n try {\n JSON.stringify(value);\n } catch {\n return \"[Unserializable]\";\n }\n }\n\n return Object.keys(value)\n .sort()\n .reduce(\n (result: Record<string, unknown>, key: string) => {\n result[key] = value[key];\n return result;\n },\n {} as Record<string, unknown>,\n );\n });\n}\n","import isEqual from \"lodash/isEqual\";\nimport { useMemo, useState } from \"react\";\n\n/\n Provides a stable value for T based on deep equality. The deep equality is\n * determined by the `isEqual()` function in lodash.\n */\nexport function useDeepMemo<T>(value: T): T {\n const [state, setState] = useState<T>(value);\n\n return useMemo(() => {\n if (state === value \|\| isEqual(state, value)) {\n return state;\n }\n\n // We check equality, so this should be safe.\n // eslint-disable-next-line react-hooks/set-state-in-render\n setState(value);\n\n return value;\n }, [state, value]);\n}\n"],"mappings":"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","names":["MS_PER_DAY","getByteSize","useCallback","useEffect","useMemo","useRef","useState","MS_PER_DAY","useSyncExternalStore","kvStore","LocalStore","IS_NOT_BROWSER","getStorageAdapter","options","defaultStoreExpiryMs","store","expiryMs","isValid","adapter","key","value","keyPrefix","fullKey","SharedStateConfig","MS_PER_DAY","PubSubStore","key","value","prev","subscriber","subscribers","next","copy","e","pubSubStore","STORAGE_KEY","stateKey","SharedState","defaultValue","options","getStorageAdapter","SharedStateConfig","lazyLoad","stored","sharedState","useSharedState","state","useSyncExternalStore","onStoreChange","stringifyDeterministicForKeys","params","cache","_","value","result","key","isEqual","useMemo","useState","useDeepMemo","value","state","setState","SharedQueryConfig","MS_PER_DAY","args","configureSharedQuery","config","SharedQuery","options","persistTo","sharedState","stringifyDeterministicForKeys","queryKey","dataUpdatedMs","cached","inflightQuery","promise","abortController","data","e","stateValue","entry","prev","key","clone","inflight","count","oldState","oldSize","oldByteSize","getByteSize","numToCut","bytesToCut","newState","needUpdate","deleteKeyIfNotMounted","expired","byteSize","entriesByTimeAscending","entry1","entry2","seenQueryNames","sharedQuery","DEFAULT_QUERY_STATE_ENTRY","useSharedQuery","query","stableArgs","useDeepMemo","queryState","setQueryState","useSharedState","isMounted","useRef","useMemo","queryStateValue","setQueryStateValue","useCallback","next","lastNonEmptyData","setLastNonEmptyData","useState","useEffect","execute","forceRefresh","now","reason","controller"]}

package/sharedQuery.mjs CHANGED Viewed

@@ -16,6 +16,7 @@ import { useSyncExternalStore } from "react";
 // src/storage.ts
 import { kvStore } from "@choksheak/ts-utils/kvStore";
 import { LocalStore } from "@choksheak/ts-utils/localStore";
+var IS_NOT_BROWSER = typeof window === "undefined";
 function getStorageAdapter(options, defaultStoreExpiryMs) {
   const { store } = options ?? {};
   if (!store) {
@@ -23,6 +24,7 @@ function getStorageAdapter(options, defaultStoreExpiryMs) {
   }
   if ("persistTo" in store && typeof store.persistTo === "string" && "key" in store && typeof store.key === "string") {
     const expiryMs = store.expiryMs || defaultStoreExpiryMs;
+    const isValid = store.isValid;
     switch (store.persistTo) {
       case "localStorage": {
         const adapter = new LocalStore(store.key, {
@@ -30,40 +32,58 @@ function getStorageAdapter(options, defaultStoreExpiryMs) {
         });
         return {
           set: (key, value) => {
-            if (typeof window === "undefined") return;
+            if (IS_NOT_BROWSER) return;
             adapter.set(key, value);
           },
           get: (key) => {
-            if (typeof window === "undefined") return void 0;
-            return adapter.get(key);
+            if (IS_NOT_BROWSER) return void 0;
+            const value = adapter.get(key);
+            if (isValid && !isValid(value)) {
+              console.warn(
+                `localStorage adapter: Auto-discard invalid value for ${key}: ${JSON.stringify(value)}`
+              );
+              adapter.delete(key);
+              return void 0;
+            }
+            return value;
           },
           delete: (key) => {
-            if (typeof window === "undefined") return;
+            if (IS_NOT_BROWSER) return;
             adapter.delete(key);
           },
           clear: () => {
-            if (typeof window === "undefined") return;
+            if (IS_NOT_BROWSER) return;
             adapter.clear();
           }
         };
       }
       case "indexedDb": {
         const keyPrefix = store.key + ":";
+        const isValid2 = store.isValid;
         return {
           set: async (key, value) => {
-            if (typeof window === "undefined") return;
+            if (IS_NOT_BROWSER) return;
             await kvStore.set(keyPrefix + key, value, expiryMs);
           },
           get: async (key) => {
-            if (typeof window === "undefined") return void 0;
-            return await kvStore.get(keyPrefix + key);
+            if (IS_NOT_BROWSER) return void 0;
+            const fullKey = keyPrefix + key;
+            const value = await kvStore.get(fullKey);
+            if (isValid2 && !isValid2(value)) {
+              console.warn(
+                `indexedDb adapter: Auto-discard invalid value for ${key}: ${JSON.stringify(value)}`
+              );
+              await kvStore.delete(fullKey);
+              return void 0;
+            }
+            return value;
           },
           delete: async (key) => {
-            if (typeof window === "undefined") return;
+            if (IS_NOT_BROWSER) return;
             await kvStore.delete(keyPrefix + key);
           },
           clear: async () => {
-            if (typeof window === "undefined") return;
+            if (IS_NOT_BROWSER) return;
             await kvStore.clear();
           }
         };
@@ -161,39 +181,65 @@ var SharedState = class {
   setValueBounded;
   initStarted = false;
   initDone = false;
-  // `subscribe` function required by useSyncExternalStore
+  /** `subscribe` function required by useSyncExternalStore. */
   subscribe(subscriber) {
     return pubSubStore.subscribe(this.pubSubKey, () => subscriber());
   }
-  // Get the value of the shared state.
-  // `getSnapshot` function — must return same ref if value unchanged
+  /** Returns true if there is a backing store. */
+  hasStore() {
+    return Boolean(this.storageAdapter);
+  }
+  /**
+   * Set a value directly into the store. Does nothing if there is no
+   * backing store.
+   *
+   * Warning: If you want to set the value properly, you should use
+   * `setValue()` instead which also updates the in-memory copy.
+   */
+  async setInStore(value) {
+    return await this.storageAdapter?.set(STORAGE_KEY, value);
+  }
+  /**
+   * Get a value directly from the store. Returns undefined if there is no
+   * backing store.
+   */
+  async getFromStore() {
+    return await this.storageAdapter?.get(STORAGE_KEY);
+  }
+  /**
+   * Get the value of the shared state.
+   *  `getSnapshot` function — must return same ref if value unchanged.
+   * Note that this would return the default value if data init from store is
+   * not completed yet.
+   */
   getSnapshot() {
     return pubSubStore.get(this.pubSubKey);
   }
-  // Set the value of the shared state.
+  /** Set the value of the shared state. */
   setValue(next) {
     if (typeof next === "function") {
       const prev = pubSubStore.get(this.pubSubKey);
       next = next(prev);
     }
     pubSubStore.set(this.pubSubKey, next);
-    void this.storageAdapter?.set(STORAGE_KEY, next);
+    void this.setInStore(next);
   }
-  // Remove the value of the shared state. Actually this just sets the value
-  // back to the given default value.
+  /**
+   * Remove the value of the shared state. Actually this just sets the value
+   * back to the given default value.
+   */
   delete() {
     pubSubStore.set(this.pubSubKey, this.defaultValue);
     void this.storageAdapter?.set(STORAGE_KEY, this.defaultValue);
   }
-  // Initial default handling
+  /** Initial default handling. */
   async initDefaultValueOnce() {
     if (this.initDone || this.initStarted) return;
     this.initStarted = true;
-    const v = await this.storageAdapter?.get(STORAGE_KEY);
-    const value = v !== void 0 ? v : this.defaultValue;
+    const stored = await this.getFromStore();
+    const value = stored !== void 0 ? stored : this.defaultValue;
     pubSubStore.set(this.pubSubKey, value);
     this.initDone = true;
-    pubSubStore.set(this.pubSubKey, value);
   }
 };
 function sharedState(defaultValue, options) {

package/sharedState.cjs CHANGED Viewed

@@ -35,6 +35,7 @@ var import_react = require("react");
 // src/storage.ts
 var import_kvStore = require("@choksheak/ts-utils/kvStore");
 var import_localStore = require("@choksheak/ts-utils/localStore");
+var IS_NOT_BROWSER = typeof window === "undefined";
 function getStorageAdapter(options, defaultStoreExpiryMs) {
   const { store } = options ?? {};
   if (!store) {
@@ -42,6 +43,7 @@ function getStorageAdapter(options, defaultStoreExpiryMs) {
   }
   if ("persistTo" in store && typeof store.persistTo === "string" && "key" in store && typeof store.key === "string") {
     const expiryMs = store.expiryMs || defaultStoreExpiryMs;
+    const isValid = store.isValid;
     switch (store.persistTo) {
       case "localStorage": {
         const adapter = new import_localStore.LocalStore(store.key, {
@@ -49,40 +51,58 @@ function getStorageAdapter(options, defaultStoreExpiryMs) {
         });
         return {
           set: (key, value) => {
-            if (typeof window === "undefined") return;
+            if (IS_NOT_BROWSER) return;
             adapter.set(key, value);
           },
           get: (key) => {
-            if (typeof window === "undefined") return void 0;
-            return adapter.get(key);
+            if (IS_NOT_BROWSER) return void 0;
+            const value = adapter.get(key);
+            if (isValid && !isValid(value)) {
+              console.warn(
+                `localStorage adapter: Auto-discard invalid value for ${key}: ${JSON.stringify(value)}`
+              );
+              adapter.delete(key);
+              return void 0;
+            }
+            return value;
           },
           delete: (key) => {
-            if (typeof window === "undefined") return;
+            if (IS_NOT_BROWSER) return;
             adapter.delete(key);
           },
           clear: () => {
-            if (typeof window === "undefined") return;
+            if (IS_NOT_BROWSER) return;
             adapter.clear();
           }
         };
       }
       case "indexedDb": {
         const keyPrefix = store.key + ":";
+        const isValid2 = store.isValid;
         return {
           set: async (key, value) => {
-            if (typeof window === "undefined") return;
+            if (IS_NOT_BROWSER) return;
             await import_kvStore.kvStore.set(keyPrefix + key, value, expiryMs);
           },
           get: async (key) => {
-            if (typeof window === "undefined") return void 0;
-            return await import_kvStore.kvStore.get(keyPrefix + key);
+            if (IS_NOT_BROWSER) return void 0;
+            const fullKey = keyPrefix + key;
+            const value = await import_kvStore.kvStore.get(fullKey);
+            if (isValid2 && !isValid2(value)) {
+              console.warn(
+                `indexedDb adapter: Auto-discard invalid value for ${key}: ${JSON.stringify(value)}`
+              );
+              await import_kvStore.kvStore.delete(fullKey);
+              return void 0;
+            }
+            return value;
           },
           delete: async (key) => {
-            if (typeof window === "undefined") return;
+            if (IS_NOT_BROWSER) return;
             await import_kvStore.kvStore.delete(keyPrefix + key);
           },
           clear: async () => {
-            if (typeof window === "undefined") return;
+            if (IS_NOT_BROWSER) return;
             await import_kvStore.kvStore.clear();
           }
         };
@@ -183,39 +203,65 @@ var SharedState = class {
   setValueBounded;
   initStarted = false;
   initDone = false;
-  // `subscribe` function required by useSyncExternalStore
+  /** `subscribe` function required by useSyncExternalStore. */
   subscribe(subscriber) {
     return pubSubStore.subscribe(this.pubSubKey, () => subscriber());
   }
-  // Get the value of the shared state.
-  // `getSnapshot` function — must return same ref if value unchanged
+  /** Returns true if there is a backing store. */
+  hasStore() {
+    return Boolean(this.storageAdapter);
+  }
+  /**
+   * Set a value directly into the store. Does nothing if there is no
+   * backing store.
+   *
+   * Warning: If you want to set the value properly, you should use
+   * `setValue()` instead which also updates the in-memory copy.
+   */
+  async setInStore(value) {
+    return await this.storageAdapter?.set(STORAGE_KEY, value);
+  }
+  /**
+   * Get a value directly from the store. Returns undefined if there is no
+   * backing store.
+   */
+  async getFromStore() {
+    return await this.storageAdapter?.get(STORAGE_KEY);
+  }
+  /**
+   * Get the value of the shared state.
+   *  `getSnapshot` function — must return same ref if value unchanged.
+   * Note that this would return the default value if data init from store is
+   * not completed yet.
+   */
   getSnapshot() {
     return pubSubStore.get(this.pubSubKey);
   }
-  // Set the value of the shared state.
+  /** Set the value of the shared state. */
   setValue(next) {
     if (typeof next === "function") {
       const prev = pubSubStore.get(this.pubSubKey);
       next = next(prev);
     }
     pubSubStore.set(this.pubSubKey, next);
-    void this.storageAdapter?.set(STORAGE_KEY, next);
+    void this.setInStore(next);
   }
-  // Remove the value of the shared state. Actually this just sets the value
-  // back to the given default value.
+  /**
+   * Remove the value of the shared state. Actually this just sets the value
+   * back to the given default value.
+   */
   delete() {
     pubSubStore.set(this.pubSubKey, this.defaultValue);
     void this.storageAdapter?.set(STORAGE_KEY, this.defaultValue);
   }
-  // Initial default handling
+  /** Initial default handling. */
   async initDefaultValueOnce() {
     if (this.initDone || this.initStarted) return;
     this.initStarted = true;
-    const v = await this.storageAdapter?.get(STORAGE_KEY);
-    const value = v !== void 0 ? v : this.defaultValue;
+    const stored = await this.getFromStore();
+    const value = stored !== void 0 ? stored : this.defaultValue;
     pubSubStore.set(this.pubSubKey, value);
     this.initDone = true;
-    pubSubStore.set(this.pubSubKey, value);
   }
 };
 function sharedState(defaultValue, options) {