@dr.pogodin/react-global-state 0.15.1 → 0.16.1

package/build/types/useAsyncCollection.d.ts

@@ -1,55 +1,38 @@
 /**
- * Loads and uses an item in an async collection.
+ * Loads and uses item(s) in an async collection.
  */
 import { type DataInEnvelopeAtPathT, type UseAsyncDataOptionsT, type UseAsyncDataResT } from './useAsyncData';
 import { type ForceT, type LockT, type TypeLock } from './utils';
-export type AsyncCollectionLoaderT<DataT> = (id: string, oldData: null | DataT) => DataT | Promise<DataT>;
+export type AsyncCollectionLoaderT<DataT, IdT extends number | string = number | string> = (id: IdT, oldData: null | DataT, meta: {
+    isAborted: () => boolean;
+    oldDataTimestamp: number;
+}) => DataT | Promise<DataT | null> | null;
+export type AsyncCollectionReloaderT<DataT, IdT extends number | string = number | string> = (loader?: AsyncCollectionLoaderT<DataT, IdT>) => Promise<void>;
+type CollectionItemT<DataT> = {
+    data: DataT | null;
+    loading: boolean;
+    timestamp: number;
+};
+export type UseAsyncCollectionResT<DataT, IdT extends number | string = number | string> = {
+    items: {
+        [id in IdT]: CollectionItemT<DataT>;
+    };
+    loading: boolean;
+    reload: AsyncCollectionReloaderT<DataT, IdT>;
+    timestamp: number;
+};
 /**
- * Resolves and stores at the given `path` of global state elements of
- * an asynchronous data collection. In other words, it is an auxiliar wrapper
- * around {@link useAsyncData}, which uses a loader which resolves to different
- * data, based on ID argument passed in, and stores data fetched for different
- * IDs in the state.
- * @param id ID of the collection item to load & use.
- * @param path The global state path where entire collection should be
- *  stored.
- * @param loader A loader function, which takes an
- * ID of data to load, and resolves to the corresponding data.
- * @param options Additional options.
- * @param options.deps An array of dependencies, which trigger
- * data reload when changed. Given dependency changes are watched shallowly
- * (similarly to the standard React's
- * [useEffect()](https://reactjs.org/docs/hooks-reference.html#useeffect)).
- * @param options.noSSR If `true`, this hook won't load data during
- * server-side rendering.
- * @param options.garbageCollectAge The maximum age of data
- * (in milliseconds), after which they are dropped from the state when the last
- * component referencing them via `useAsyncData()` hook unmounts. Defaults to
- * `maxage` option value.
- * @param options.maxage The maximum age of
- * data (in milliseconds) acceptable to the hook's caller. If loaded data are
- * older than this value, `null` is returned instead. Defaults to 5 minutes.
- * @param options.refreshAge The maximum age of data
- * (in milliseconds), after which their refreshment will be triggered when
- * any component referencing them via `useAsyncData()` hook (re-)renders.
- * Defaults to `maxage` value.
- * @return Returns an object with three fields: `data` holds the actual result of
- * last `loader` invokation, if any, and if satisfies `maxage` limit; `loading`
- * is a boolean flag, which is `true` if data are being loaded (the hook is
- * waiting for `loader` function resolution); `timestamp` (in milliseconds)
- * is Unix timestamp of related data currently loaded into the global state.
- *
- * Note that loaded data, if any, are stored at the given `path` of global state
- * along with related meta-information, using slightly different state segment
- * structure (see {@link AsyncDataEnvelope}). That segment of the global state
- * can be accessed, and even modified using other hooks,
- * _e.g._ {@link useGlobalState}, but doing so you may interfere with related
- * `useAsyncData()` hooks logic.
+ * Resolves and stores at the given `path` of the global state elements of
+ * an asynchronous data collection.
  */
-declare function useAsyncCollection<StateT, PathT extends null | string | undefined, IdT extends string, DataT extends DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`> = DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`>>(id: IdT, path: PathT, loader: AsyncCollectionLoaderT<DataT>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataT>;
-declare function useAsyncCollection<Forced extends ForceT | LockT = LockT, DataT = unknown>(id: string, path: null | string | undefined, loader: AsyncCollectionLoaderT<TypeLock<Forced, void, DataT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;
+declare function useAsyncCollection<StateT, PathT extends null | string | undefined, IdT extends number | string, DataT extends DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`> = DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`>>(id: IdT, path: PathT, loader: AsyncCollectionLoaderT<DataT, IdT>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataT>;
+declare function useAsyncCollection<Forced extends ForceT | LockT = LockT, DataT = unknown, IdT extends number | string = number | string>(id: IdT, path: null | string | undefined, loader: AsyncCollectionLoaderT<TypeLock<Forced, void, DataT>, IdT>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;
+declare function useAsyncCollection<StateT, PathT extends null | string | undefined, IdT extends number | string, DataT extends DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`> = DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`>>(id: IdT[], path: PathT, loader: AsyncCollectionLoaderT<DataT, IdT>, options?: UseAsyncDataOptionsT): UseAsyncCollectionResT<DataT, IdT>;
+declare function useAsyncCollection<Forced extends ForceT | LockT = LockT, DataT = unknown, IdT extends number | string = number | string>(id: IdT[], path: null | string | undefined, loader: AsyncCollectionLoaderT<TypeLock<Forced, void, DataT>, IdT>, options?: UseAsyncDataOptionsT): UseAsyncCollectionResT<DataT, IdT>;
 export default useAsyncCollection;
 export interface UseAsyncCollectionI<StateT> {
-    <PathT extends null | string | undefined, IdT extends string>(id: IdT, path: PathT, loader: AsyncCollectionLoaderT<DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`>>;
-    <Forced extends ForceT | LockT = LockT, DataT = unknown>(id: string, path: null | string | undefined, loader: AsyncCollectionLoaderT<TypeLock<Forced, void, DataT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;
+    <PathT extends null | string | undefined, IdT extends number | string>(id: IdT, path: PathT, loader: AsyncCollectionLoaderT<DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`>, IdT>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`>>;
+    <Forced extends ForceT | LockT = LockT, DataT = unknown, IdT extends number | string = number | string>(id: IdT, path: null | string | undefined, loader: AsyncCollectionLoaderT<TypeLock<Forced, void, DataT>, IdT>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;
+    <PathT extends null | string | undefined, IdT extends number | string>(id: IdT[], path: PathT, loader: AsyncCollectionLoaderT<DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`>, IdT>, options?: UseAsyncDataOptionsT): UseAsyncCollectionResT<DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`>, IdT>;
+    <Forced extends ForceT | LockT = LockT, DataT = unknown, IdT extends number | string = number | string>(id: IdT[], path: null | string | undefined, loader: AsyncCollectionLoaderT<TypeLock<Forced, void, DataT>, IdT>, options?: UseAsyncDataOptionsT): UseAsyncCollectionResT<DataT, IdT>;
 }

package/build/types/useAsyncData.d.ts

@@ -2,7 +2,13 @@
  * Loads and uses async data into the GlobalState path.
  */
 import { type ForceT, type LockT, type TypeLock, type ValueAtPathT } from './utils';
-export type AsyncDataLoaderT<DataT> = (oldData: null | DataT) => DataT | Promise<DataT>;
+import GlobalState from './GlobalState';
+import SsrContext from './SsrContext';
+export declare const DEFAULT_MAXAGE: number;
+export type AsyncDataLoaderT<DataT> = (oldData: null | DataT, meta: {
+    isAborted: () => boolean;
+    oldDataTimestamp: number;
+}) => DataT | Promise<DataT | null> | null;
 export type AsyncDataReloaderT<DataT> = (loader?: AsyncDataLoaderT<DataT>) => Promise<void>;
 export type AsyncDataEnvelopeT<DataT> = {
     data: null | DataT;
@@ -10,6 +16,7 @@ export type AsyncDataEnvelopeT<DataT> = {
     operationId: string;
     timestamp: number;
 };
+export type OperationIdT = `${'C' | 'S'}${string}`;
 export declare function newAsyncDataEnvelope<DataT>(initialData?: DataT | null, { numRefs, timestamp }?: {
     numRefs?: number | undefined;
     timestamp?: number | undefined;
@@ -27,54 +34,29 @@ export type UseAsyncDataResT<DataT> = {
     reload: AsyncDataReloaderT<DataT>;
     timestamp: number;
 };
+/**
+ * Executes the data loading operation.
+ * @param path Data segment path inside the global state.
+ * @param loader Data loader.
+ * @param globalState The global state instance.
+ * @param oldData Optional. Previously fetched data, currently stored in
+ *  the state, if already fetched by the caller; otherwise, they will be fetched
+ *  by the load() function itself.
+ * @param opIdPrefix operationId prefix to use, which should be
+ * 'C' at the client-side (default), or 'S' at the server-side (within SSR
+ * context).
+ * @return Resolves once the operation is done.
+ * @ignore
+ */
+export declare function load<DataT>(path: null | string | undefined, loader: AsyncDataLoaderT<DataT>, globalState: GlobalState<unknown, SsrContext<unknown>>, old?: {
+    data: DataT | null;
+    timestamp: number;
+}, operationId?: OperationIdT): Promise<void>;
 /**
  * Resolves asynchronous data, and stores them at given `path` of global
- * state. When multiple components rely on asynchronous data at the same `path`,
- * the data are resolved once, and reused until their age is within specified
- * bounds. Once the data are stale, the hook allows to refresh them. It also
- * garbage-collects stale data from the global state when the last component
- * relying on them is unmounted.
- * @param path Dot-delimitered state path, where data envelop is
- * stored.
- * @param loader Asynchronous function which resolves (loads)
- * data, which should be stored at the global state `path`. When multiple
- * components
- * use `useAsyncData()` hook for the same `path`, the library assumes that all
- * hook instances are called with the same `loader` (_i.e._ whichever of these
- * loaders is used to resolve async data, the result is acceptable to be reused
- * in all related components).
- * @param options Additional options.
- * @param options.deps An array of dependencies, which trigger
- * data reload when changed. Given dependency changes are watched shallowly
- * (similarly to the standard React's
- * [useEffect()](https://reactjs.org/docs/hooks-reference.html#useeffect)).
- * @param options.noSSR If `true`, this hook won't load data during
- * server-side rendering.
- * @param options.garbageCollectAge The maximum age of data
- * (in milliseconds), after which they are dropped from the state when the last
- * component referencing them via `useAsyncData()` hook unmounts. Defaults to
- * `maxage` option value.
- * @param options.maxage The maximum age of
- * data (in milliseconds) acceptable to the hook's caller. If loaded data are
- * older than this value, `null` is returned instead. Defaults to 5 minutes.
- * @param options.refreshAge The maximum age of data
- * (in milliseconds), after which their refreshment will be triggered when
- * any component referencing them via `useAsyncData()` hook (re-)renders.
- * Defaults to `maxage` value.
- * @return Returns an object with three fields: `data` holds the actual result of
- * last `loader` invokation, if any, and if satisfies `maxage` limit; `loading`
- * is a boolean flag, which is `true` if data are being loaded (the hook is
- * waiting for `loader` function resolution); `timestamp` (in milliseconds)
- * is Unix timestamp of related data currently loaded into the global state.
- *
- * Note that loaded data, if any, are stored at the given `path` of global state
- * along with related meta-information, using slightly different state segment
- * structure (see {@link AsyncDataEnvelopeT}). That segment of the global state
- * can be accessed, and even modified using other hooks,
- * _e.g._ {@link useGlobalState}, but doing so you may interfere with related
- * `useAsyncData()` hooks logic.
+ * state.
  */
-export type DataInEnvelopeAtPathT<StateT, PathT extends null | string | undefined> = ValueAtPathT<StateT, PathT, never> extends AsyncDataEnvelopeT<unknown> ? Exclude<ValueAtPathT<StateT, PathT, never>['data'], null> : void;
+export type DataInEnvelopeAtPathT<StateT, PathT extends null | string | undefined> = Exclude<Extract<ValueAtPathT<StateT, PathT, void>, AsyncDataEnvelopeT<unknown>>['data'], null>;
 declare function useAsyncData<StateT, PathT extends null | string | undefined, DataT extends DataInEnvelopeAtPathT<StateT, PathT> = DataInEnvelopeAtPathT<StateT, PathT>>(path: PathT, loader: AsyncDataLoaderT<DataT>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataT>;
 declare function useAsyncData<Forced extends ForceT | LockT = LockT, DataT = void>(path: null | string | undefined, loader: AsyncDataLoaderT<TypeLock<Forced, void, DataT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;
 export { useAsyncData };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dr.pogodin/react-global-state",
-  "version": "0.15.1",
+  "version": "0.16.1",
   "description": "Hook-based global state for React",
   "main": "./build/common/index.js",
   "react-native": "src/index.ts",
@@ -43,7 +43,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@babel/runtime": "^7.24.8",
+    "@babel/runtime": "^7.25.0",
     "@dr.pogodin/js-utils": "^0.0.12",
     "@types/lodash": "^4.17.7",
     "lodash": "^4.17.21",
@@ -51,15 +51,15 @@
   },
   "devDependencies": {
     "@babel/cli": "^7.24.8",
-    "@babel/core": "^7.24.9",
-    "@babel/eslint-parser": "^7.24.8",
-    "@babel/eslint-plugin": "^7.24.7",
-    "@babel/node": "^7.24.8",
+    "@babel/core": "^7.25.2",
+    "@babel/eslint-parser": "^7.25.1",
+    "@babel/eslint-plugin": "^7.25.1",
+    "@babel/node": "^7.25.0",
     "@babel/plugin-transform-runtime": "^7.24.7",
-    "@babel/preset-env": "^7.24.8",
+    "@babel/preset-env": "^7.25.3",
     "@babel/preset-react": "^7.24.7",
     "@babel/preset-typescript": "^7.24.7",
-    "@testing-library/dom": "^10.3.2",
+    "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.0.0",
     "@tsconfig/recommended": "^1.0.7",
     "@types/jest": "^29.5.12",
@@ -82,9 +82,9 @@
     "jest-environment-jsdom": "^29.7.0",
     "mockdate": "^3.0.5",
     "rimraf": "^6.0.1",
-    "tstyche": "^2.1.0",
-    "typescript": "^5.5.3",
-    "typescript-eslint": "^7.16.1"
+    "tstyche": "^2.1.1",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.0.0"
   },
   "peerDependencies": {
     "react": "^18.3.1",

package/src/GlobalState.ts

@@ -97,7 +97,7 @@ export default class GlobalState<
     const prevDeps = this.#dependencies[path];
     let changed = !prevDeps || prevDeps.length !== deps.length;
     for (let i = 0; !changed && i < deps.length; ++i) {
-      changed = prevDeps[i] !== deps[i];
+      changed = prevDeps![i] !== deps[i];
     }
     this.#dependencies[path] = Object.freeze(deps);
     return changed;
@@ -141,7 +141,7 @@ export default class GlobalState<
         this.#nextNotifierId = undefined;
         const watchers = [...this.#watchers];
         for (let i = 0; i < watchers.length; ++i) {
-          watchers[i]();
+          watchers[i]!();
         }
       });
     }
@@ -245,7 +245,7 @@ export default class GlobalState<
       let pos: any = root;
       const pathSegments = toPath(`state.${path}`);
       for (; segIdx < pathSegments.length - 1; segIdx += 1) {
-        const seg = pathSegments[segIdx];
+        const seg = pathSegments[segIdx]!;
         const next = pos[seg];
         if (Array.isArray(next)) pos[seg] = [...next];
         else if (isObject(next)) pos[seg] = { ...next };
@@ -260,7 +260,7 @@ export default class GlobalState<
       }
 
       if (segIdx === pathSegments.length - 1) {
-        pos[pathSegments[segIdx]] = value;
+        pos[pathSegments[segIdx]!] = value;
       }
 
       this.#currentState = root.state;
@@ -283,7 +283,7 @@ export default class GlobalState<
     const watchers = this.#watchers;
     const pos = watchers.indexOf(callback);
     if (pos >= 0) {
-      watchers[pos] = watchers[watchers.length - 1];
+      watchers[pos] = watchers[watchers.length - 1]!;
       watchers.pop();
     }
   }

package/src/index.ts

@@ -9,10 +9,16 @@ import SsrContext from './SsrContext';
 
 import useAsyncCollection, {
   type UseAsyncCollectionI,
+  type UseAsyncCollectionResT,
 } from './useAsyncCollection';
 
 import {
+  type AsyncDataEnvelopeT,
+  type AsyncDataLoaderT,
+  type AsyncDataReloaderT,
   type UseAsyncDataI,
+  type UseAsyncDataOptionsT,
+  type UseAsyncDataResT,
   newAsyncDataEnvelope,
   useAsyncData,
 } from './useAsyncData';
@@ -21,19 +27,25 @@ import useGlobalState, { type UseGlobalStateI } from './useGlobalState';
 
 export type { AsyncCollectionLoaderT } from './useAsyncCollection';
 
-export * from './useAsyncData';
-
 export type { SetterT, UseGlobalStateResT } from './useGlobalState';
 
 export type { ForceT, ValueOrInitializerT } from './utils';
 
 export {
+  type AsyncDataEnvelopeT,
+  type AsyncDataLoaderT,
+  type AsyncDataReloaderT,
+  type UseAsyncCollectionResT,
+  type UseAsyncDataOptionsT,
+  type UseAsyncDataResT,
   getGlobalState,
   getSsrContext,
   GlobalState,
   GlobalStateProvider,
+  newAsyncDataEnvelope,
   SsrContext,
   useAsyncCollection,
+  useAsyncData,
   useGlobalState,
 };