@dr.pogodin/react-global-state 0.9.3 → 0.10.0-alpha.2

package/build/GlobalStateProvider.js

@@ -0,0 +1,103 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSsrContext = exports.getGlobalState = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+/* eslint-disable react/prop-types */
+const lodash_1 = require("lodash");
+const react_1 = require("react");
+const GlobalState_1 = __importDefault(require("./GlobalState"));
+const context = (0, react_1.createContext)(null);
+/**
+ * Gets {@link GlobalState} instance from the context. In most cases
+ * you should use {@link useGlobalState}, and other hooks to interact with
+ * the global state, instead of accessing it directly.
+ * @return
+ */
+function getGlobalState() {
+    // Here Rules of Hooks are violated because "getGlobalState()" does not follow
+    // convention that hook names should start with use... This is intentional in
+    // our case, as getGlobalState() hook is intended for advance scenarious,
+    // while the normal interaction with the global state should happen via
+    // another hook, useGlobalState().
+    /* eslint-disable react-hooks/rules-of-hooks */
+    const globalState = (0, react_1.useContext)(context);
+    /* eslint-enable react-hooks/rules-of-hooks */
+    if (!globalState)
+        throw new Error('Missing GlobalStateProvider');
+    return globalState;
+}
+exports.getGlobalState = getGlobalState;
+/**
+ * @category Hooks
+ * @desc Gets SSR context.
+ * @param throwWithoutSsrContext If `true` (default),
+ * this hook will throw if no SSR context is attached to the global state;
+ * set `false` to not throw in such case. In either case the hook will throw
+ * if the {@link &lt;GlobalStateProvider&gt;} (hence the state) is missing.
+ * @returns SSR context.
+ * @throws
+ * - If current component has no parent {@link &lt;GlobalStateProvider&gt;}
+ *   in the rendered React tree.
+ * - If `throwWithoutSsrContext` is `true`, and there is no SSR context attached
+ *   to the global state provided by {@link &lt;GlobalStateProvider&gt;}.
+ */
+function getSsrContext(throwWithoutSsrContext = true) {
+    const { ssrContext } = getGlobalState();
+    if (!ssrContext && throwWithoutSsrContext) {
+        throw new Error('No SSR context found');
+    }
+    return ssrContext;
+}
+exports.getSsrContext = getSsrContext;
+/**
+ * Provides global state to its children.
+ * @param prop.children Component children, which will be provided with
+ * the global state, and rendered in place of the provider.
+ * @param prop.initialState Initial content of the global state.
+ * @param prop.ssrContext Server-side rendering (SSR) context.
+ * @param prop.stateProxy This option is useful for code
+ * splitting and SSR implementation:
+ * - If `true`, this provider instance will fetch and reuse the global state
+ *   from a parent provider.
+ * - If `GlobalState` instance, it will be used by this provider.
+ * - If not given, a new `GlobalState` instance will be created and used.
+ */
+function GlobalStateProvider(_a) {
+    var { children } = _a, rest = __rest(_a, ["children"]);
+    const state = (0, react_1.useRef)();
+    if (!state.current) {
+        // NOTE: The last part of condition, "&& rest.stateProxy", is needed for
+        // graceful compatibility with JavaScript - if "undefined" stateProxy value
+        // is given, we want to follow the second branch, which creates a new
+        // GlobalState with whatever intiialState given.
+        if ('stateProxy' in rest && rest.stateProxy) {
+            if (rest.stateProxy === true)
+                state.current = getGlobalState();
+            else
+                state.current = rest.stateProxy;
+        }
+        else {
+            const { initialState, ssrContext } = rest;
+            state.current = new GlobalState_1.default((0, lodash_1.isFunction)(initialState) ? initialState() : initialState, ssrContext);
+        }
+    }
+    return ((0, jsx_runtime_1.jsx)(context.Provider, { value: state.current, children: children }));
+}
+exports.default = GlobalStateProvider;
+GlobalStateProvider.defaultProps = {
+    children: undefined,
+};

package/build/SsrContext.d.ts

@@ -0,0 +1,6 @@
+export default class SsrContext<StateT> {
+    dirty: boolean;
+    pending: Promise<void>[];
+    state?: StateT;
+    constructor(state?: StateT);
+}

package/build/SsrContext.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class SsrContext {
+    constructor(state) {
+        this.dirty = false;
+        this.pending = [];
+        this.state = state;
+    }
+}
+exports.default = SsrContext;

package/build/index.d.ts

@@ -0,0 +1,8 @@
+export { default as GlobalState } from './GlobalState';
+export { default as GlobalStateProvider, getGlobalState, getSsrContext, } from './GlobalStateProvider';
+export { default as SsrContext } from './SsrContext';
+export { type AsyncCollectionLoaderT, default as useAsyncCollection, } from './useAsyncCollection';
+export { type AsyncDataEnvelopeT, type AsyncDataLoaderT, type UseAsyncDataOptionsT, type UseAsyncDataResT, default as useAsyncData, newAsyncDataEnvelope, } from './useAsyncData';
+export { type SetterT, type UseGlobalStateResT, default as useGlobalState, } from './useGlobalState';
+export { type ValueOrInitializerT } from './utils';
+export { default as withGlobalStateType } from './withGlobalStateType';

package/build/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withGlobalStateType = exports.useGlobalState = exports.newAsyncDataEnvelope = exports.useAsyncData = exports.useAsyncCollection = exports.SsrContext = exports.getSsrContext = exports.getGlobalState = exports.GlobalStateProvider = exports.GlobalState = void 0;
+var GlobalState_1 = require("./GlobalState");
+Object.defineProperty(exports, "GlobalState", { enumerable: true, get: function () { return __importDefault(GlobalState_1).default; } });
+var GlobalStateProvider_1 = require("./GlobalStateProvider");
+Object.defineProperty(exports, "GlobalStateProvider", { enumerable: true, get: function () { return __importDefault(GlobalStateProvider_1).default; } });
+Object.defineProperty(exports, "getGlobalState", { enumerable: true, get: function () { return GlobalStateProvider_1.getGlobalState; } });
+Object.defineProperty(exports, "getSsrContext", { enumerable: true, get: function () { return GlobalStateProvider_1.getSsrContext; } });
+var SsrContext_1 = require("./SsrContext");
+Object.defineProperty(exports, "SsrContext", { enumerable: true, get: function () { return __importDefault(SsrContext_1).default; } });
+var useAsyncCollection_1 = require("./useAsyncCollection");
+Object.defineProperty(exports, "useAsyncCollection", { enumerable: true, get: function () { return __importDefault(useAsyncCollection_1).default; } });
+var useAsyncData_1 = require("./useAsyncData");
+Object.defineProperty(exports, "useAsyncData", { enumerable: true, get: function () { return __importDefault(useAsyncData_1).default; } });
+Object.defineProperty(exports, "newAsyncDataEnvelope", { enumerable: true, get: function () { return useAsyncData_1.newAsyncDataEnvelope; } });
+var useGlobalState_1 = require("./useGlobalState");
+Object.defineProperty(exports, "useGlobalState", { enumerable: true, get: function () { return __importDefault(useGlobalState_1).default; } });
+var withGlobalStateType_1 = require("./withGlobalStateType");
+Object.defineProperty(exports, "withGlobalStateType", { enumerable: true, get: function () { return __importDefault(withGlobalStateType_1).default; } });

package/build/{module/useAsyncCollection.js → useAsyncCollection.d.ts}

@@ -1,43 +1,39 @@
 /**
  * Loads and uses an item in an async collection.
  */
-
-import useAsyncData from "./useAsyncData";
-
+import { type DataInEnvelopeAtPathT, type UseAsyncDataOptionsT, type UseAsyncDataResT } from './useAsyncData';
+import { TypeLock } from './utils';
+export type AsyncCollectionLoaderT<DataT> = (id: string, oldData: null | DataT) => DataT | Promise<DataT>;
 /**
  * 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 {string} id ID of the collection item to load & use.
- * @param {string} path The global state path where entire collection should be
+ * @param id ID of the collection item to load & use.
+ * @param path The global state path where entire collection should be
  *  stored.
- * @param {AsyncCollectionLoader} loader A loader function, which takes an
+ * @param loader A loader function, which takes an
  * ID of data to load, and resolves to the corresponding data.
- * @param {object} [options] Additional options.
- * @param {any[]} [options.deps=[]] An array of dependencies, which trigger
+ * @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 {boolean} [options.noSSR] If `true`, this hook won't load data during
+ * @param options.noSSR If `true`, this hook won't load data during
  * server-side rendering.
- * @param {number} [options.garbageCollectAge=maxage] The maximum age of data
+ * @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 {number} [options.maxage=5 x 60 x 1000] The maximum age of
+ * @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 {number} [options.refreshAge=maxage] The maximum age of data
+ * @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 {{
- *   data: any,
- *   loading: boolean,
- *   timestamp: number
- * }} Returns an object with three fields: `data` holds the actual result of
+ * @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)
@@ -50,9 +46,6 @@ import useAsyncData from "./useAsyncData";
  * _e.g._ {@link useGlobalState}, but doing so you may interfere with related
  * `useAsyncData()` hooks logic.
  */
-export default function useAsyncCollection(id, path, loader) {
-  let options = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
-  const itemPath = path ? `${path}.${id}` : id;
-  return useAsyncData(itemPath, oldData => loader(id, oldData), options);
-}
-//# sourceMappingURL=useAsyncCollection.js.map
+declare function useAsyncCollection<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}`>>;
+declare function useAsyncCollection<Unlocked extends 0 | 1 = 0, DataT = unknown>(id: string, path: null | string | undefined, loader: AsyncCollectionLoaderT<TypeLock<Unlocked, void, DataT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Unlocked, void, DataT>>;
+export default useAsyncCollection;

package/build/useAsyncCollection.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Loads and uses an item in an async collection.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const useAsyncData_1 = __importDefault(require("./useAsyncData"));
+function useAsyncCollection(id, path, loader, options = {}) {
+    const itemPath = path ? `${path}.${id}` : id;
+    return (0, useAsyncData_1.default)(itemPath, (oldData) => loader(id, oldData), options);
+}
+exports.default = useAsyncCollection;

package/build/useAsyncData.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Loads and uses async data into the GlobalState path.
+ */
+import { TypeLock } from './utils';
+import { type ValueAtPathT } from './utils';
+export type AsyncDataLoaderT<DataT> = (oldData: null | DataT) => DataT | Promise<DataT>;
+export type AsyncDataEnvelopeT<DataT> = {
+    data: null | DataT;
+    numRefs: number;
+    operationId: string;
+    timestamp: number;
+};
+export declare function newAsyncDataEnvelope<DataT>(initialData?: DataT | null): AsyncDataEnvelopeT<DataT>;
+export type UseAsyncDataOptionsT = {
+    deps?: unknown[];
+    garbageCollectAge?: number;
+    maxage?: number;
+    noSSR?: boolean;
+    refreshAge?: number;
+};
+export type UseAsyncDataResT<DataT> = {
+    data: DataT | null;
+    loading: boolean;
+    timestamp: number;
+};
+/**
+ * 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.
+ */
+export type DataInEnvelopeAtPathT<StateT, PathT extends null | string | undefined> = ValueAtPathT<StateT, PathT, never> extends AsyncDataEnvelopeT<unknown> ? Exclude<ValueAtPathT<StateT, PathT, never>['data'], null> : void;
+declare function useAsyncData<StateT, PathT extends null | string | undefined>(path: PathT, loader: AsyncDataLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;
+declare function useAsyncData<Unlocked extends 0 | 1 = 0, DataT = unknown>(path: null | string | undefined, loader: AsyncDataLoaderT<TypeLock<Unlocked, void, DataT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Unlocked, void, DataT>>;
+export default useAsyncData;

package/build/useAsyncData.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * Loads and uses async data into the GlobalState path.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newAsyncDataEnvelope = void 0;
+const lodash_1 = require("lodash");
+const react_1 = require("react");
+const uuid_1 = require("uuid");
+const js_utils_1 = require("@dr.pogodin/js-utils");
+const GlobalStateProvider_1 = require("./GlobalStateProvider");
+const useGlobalState_1 = __importDefault(require("./useGlobalState"));
+const utils_1 = require("./utils");
+const DEFAULT_MAXAGE = 5 * js_utils_1.MIN_MS; // 5 minutes.
+function newAsyncDataEnvelope(initialData = null) {
+    return {
+        data: initialData,
+        numRefs: 0,
+        operationId: '',
+        timestamp: 0,
+    };
+}
+exports.newAsyncDataEnvelope = newAsyncDataEnvelope;
+/**
+ * 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
+ */
+function load(path, loader, globalState, oldData, opIdPrefix = 'C') {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (process.env.NODE_ENV !== 'production' && (0, utils_1.isDebugMode)()) {
+            /* eslint-disable no-console */
+            console.log(`ReactGlobalState: useAsyncData data (re-)loading. Path: "${path || ''}"`);
+            /* eslint-enable no-console */
+        }
+        const operationId = opIdPrefix + (0, uuid_1.v4)();
+        const operationIdPath = path ? `${path}.operationId` : 'operationId';
+        globalState.set(operationIdPath, operationId);
+        const data = yield loader(oldData || (globalState.get(path)).data);
+        const state = globalState.get(path);
+        if (operationId === state.operationId) {
+            if (process.env.NODE_ENV !== 'production' && (0, utils_1.isDebugMode)()) {
+                /* eslint-disable no-console */
+                console.groupCollapsed(`ReactGlobalState: useAsyncData data (re-)loaded. Path: "${path || ''}"`);
+                console.log('Data:', (0, lodash_1.cloneDeep)(data));
+                /* eslint-enable no-console */
+            }
+            globalState.set(path, Object.assign(Object.assign({}, state), { data, operationId: '', timestamp: Date.now() }));
+            if (process.env.NODE_ENV !== 'production' && (0, utils_1.isDebugMode)()) {
+                /* eslint-disable no-console */
+                console.groupEnd();
+                /* eslint-enable no-console */
+            }
+        }
+    });
+}
+function useAsyncData(path, loader, options = {}) {
+    const maxage = options.maxage === undefined
+        ? DEFAULT_MAXAGE : options.maxage;
+    const refreshAge = options.refreshAge === undefined
+        ? maxage : options.refreshAge;
+    const garbageCollectAge = options.garbageCollectAge === undefined
+        ? maxage : options.garbageCollectAge;
+    // Note: here we can't depend on useGlobalState() to init the initial value,
+    // because that way we'll have issues with SSR (see details below).
+    const globalState = (0, GlobalStateProvider_1.getGlobalState)();
+    const state = globalState.get(path, {
+        initialValue: newAsyncDataEnvelope(),
+    });
+    if (globalState.ssrContext && !options.noSSR) {
+        if (!state.timestamp && !state.operationId) {
+            globalState.ssrContext.pending.push(load(path, loader, globalState, state.data, 'S'));
+        }
+    }
+    else {
+        // This takes care about the client-side reference counting, and garbage
+        // collection.
+        //
+        // Note: the Rules of Hook below are violated by conditional call to a hook,
+        // but as the condition is actually server-side or client-side environment,
+        // it is effectively non-conditional at the runtime.
+        //
+        // TODO: Though, maybe there is a way to refactor it into a cleaner code.
+        // The same applies to other useEffect() hooks below.
+        (0, react_1.useEffect)(() => {
+            const numRefsPath = path ? `${path}.numRefs` : 'numRefs';
+            const numRefs = globalState.get(numRefsPath);
+            globalState.set(numRefsPath, numRefs + 1);
+            return () => {
+                const state2 = globalState.get(path);
+                if (state2.numRefs === 1
+                    && garbageCollectAge < Date.now() - state2.timestamp) {
+                    if (process.env.NODE_ENV !== 'production' && (0, utils_1.isDebugMode)()) {
+                        /* eslint-disable no-console */
+                        console.log(`ReactGlobalState - useAsyncData garbage collected at path ${path || ''}`);
+                        /* eslint-enable no-console */
+                    }
+                    globalState.set(path, Object.assign(Object.assign({}, state2), { data: null, numRefs: 0, timestamp: 0 }));
+                }
+                else
+                    globalState.set(numRefsPath, state2.numRefs - 1);
+            };
+        }, [garbageCollectAge, globalState, path]);
+        // Note: a bunch of Rules of Hooks ignored belows because in our very
+        // special case the otherwise wrong behavior is actually what we need.
+        // Data loading and refreshing.
+        let loadTriggered = false;
+        (0, react_1.useEffect)(() => {
+            const state2 = globalState.get(path);
+            if (refreshAge < Date.now() - state2.timestamp
+                && (!state2.operationId || state2.operationId.charAt(0) === 'S')) {
+                load(path, loader, globalState, state2.data);
+                loadTriggered = true; // eslint-disable-line react-hooks/exhaustive-deps
+            }
+        });
+        const deps = options.deps || [];
+        (0, react_1.useEffect)(() => {
+            if (!loadTriggered && deps.length)
+                load(path, loader, globalState, null);
+        }, deps); // eslint-disable-line react-hooks/exhaustive-deps
+    }
+    const [localState] = (0, useGlobalState_1.default)(path, newAsyncDataEnvelope());
+    return {
+        data: maxage < Date.now() - localState.timestamp ? null : localState.data,
+        loading: Boolean(localState.operationId),
+        timestamp: localState.timestamp,
+    };
+}
+exports.default = useAsyncData;

package/build/{module/useGlobalState.js → useGlobalState.d.ts}

@@ -1,10 +1,7 @@
-// Hook for updates of global state.
-
-import { cloneDeep, isFunction } from 'lodash';
-import { useEffect, useRef, useSyncExternalStore } from 'react';
-import { getGlobalState } from "./GlobalStateProvider";
-import { isDebugMode } from "./utils";
-
+/// <reference types="react" />
+import { type TypeLock, type ValueAtPathT, type ValueOrInitializerT } from './utils';
+export type SetterT<T> = React.Dispatch<React.SetStateAction<T>>;
+export type UseGlobalStateResT<T> = [T, SetterT<T>];
 /**
  * The primary hook for interacting with the global state, modeled after
  * the standard React's
@@ -25,14 +22,14 @@ import { isDebugMode } from "./utils";
  *   state values are "fixed", and all changes becomes visible at once in the
  *   next triggered rendering pass.
  *
- * @param {string} [path] Dot-delimitered state path. It can be undefined to
+ * @param path Dot-delimitered state path. It can be undefined to
  * subscribe for entire state.
  *
  * Under-the-hood state values are read and written using `lodash`
  * [_.get()](https://lodash.com/docs/4.17.15#get) and
  * [_.set()](https://lodash.com/docs/4.17.15#set) methods, thus it is safe
  * to access state paths which have not been created before.
- * @param {any} [initialValue] Initial value to set at the `path`, or its
+ * @param initialValue Initial value to set at the `path`, or its
  * factory:
  * - If a function is given, it will act similar to
  *   [the lazy initial state of the standard React's useState()](https://reactjs.org/docs/hooks-reference.html#lazy-initial-state):
@@ -40,7 +37,7 @@ import { isDebugMode } from "./utils";
  *   and the value it returns will be written to the `path`.
  * - Otherwise, the given value itself will be written to the `path`,
  *   if the current value at `path` is `undefined`.
- * @return {Array} It returs an array with two elements: `[value, setValue]`:
+ * @return It returs an array with two elements: `[value, setValue]`:
  *
  * - The `value` is the current value at given `path`.
  *
@@ -55,55 +52,7 @@ import { isDebugMode } from "./utils";
  *   Also, similar to the standard React's state setters, `setValue()` is
  *   stable function: it does not change between component re-renders.
  */
-export default function useGlobalState(path, initialValue) {
-  const ref = useRef();
-  if (!ref.current) {
-    ref.current = {
-      callbacks: [],
-      setter: value => {
-        const rc = ref.current;
-        const newState = isFunction(value) ? value(rc.state) : value;
-        if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
-          /* eslint-disable no-console */
-          console.groupCollapsed(`ReactGlobalState - useGlobalState setter triggered for path ${rc.path || ''}`);
-          console.log('New value:', cloneDeep(newState));
-          console.groupEnd();
-          /* eslint-enable no-console */
-        }
-
-        rc.globalState.set(rc.path, newState);
-      },
-      watcher: () => {
-        const rc = ref.current;
-        const state = rc.globalState.get(rc.path);
-        if (state !== rc.state) {
-          for (let i = 0; i < rc.callbacks.length; ++i) {
-            rc.callbacks[i]();
-          }
-        }
-      }
-    };
-  }
-  const rc = ref.current;
-  const globalState = getGlobalState();
-  rc.globalState = globalState;
-  rc.path = path;
-  rc.state = useSyncExternalStore(cb => {
-    rc.callbacks.push(cb);
-  }, () => rc.globalState.get(rc.path, {
-    initialValue
-  }), () => rc.globalState.get(rc.path, {
-    initialValue,
-    initialState: true
-  }));
-  useEffect(() => {
-    globalState.watch(rc.watcher);
-    rc.watcher();
-    return () => globalState.unWatch(rc.watcher);
-  }, [globalState, rc]);
-  useEffect(() => {
-    rc.watcher();
-  }, [path, rc]);
-  return [rc.state, rc.setter];
-}
-//# sourceMappingURL=useGlobalState.js.map
+declare function useGlobalState<StateT>(): UseGlobalStateResT<StateT>;
+declare function useGlobalState<StateT, PathT extends null | string | undefined>(path: PathT, initialValue?: ValueOrInitializerT<ValueAtPathT<StateT, PathT, never>>): UseGlobalStateResT<ValueAtPathT<StateT, PathT, void>>;
+declare function useGlobalState<Unlocked extends 0 | 1 = 0, ValueT = void>(path: null | string | undefined, initialValue?: ValueOrInitializerT<TypeLock<Unlocked, never, ValueT>>): UseGlobalStateResT<TypeLock<Unlocked, void, ValueT>>;
+export default useGlobalState;

package/build/useGlobalState.js

@@ -0,0 +1,49 @@
+"use strict";
+// Hook for updates of global state.
+Object.defineProperty(exports, "__esModule", { value: true });
+const lodash_1 = require("lodash");
+const react_1 = require("react");
+const js_utils_1 = require("@dr.pogodin/js-utils");
+const GlobalStateProvider_1 = require("./GlobalStateProvider");
+const utils_1 = require("./utils");
+function useGlobalState(path, initialValue) {
+    const globalState = (0, GlobalStateProvider_1.getGlobalState)();
+    const ref = (0, react_1.useRef)();
+    const rc = ref.current || {
+        emitter: new js_utils_1.Emitter(),
+        globalState,
+        path,
+        setter: (value) => {
+            const newState = (0, lodash_1.isFunction)(value) ? value(rc.state) : value;
+            if (process.env.NODE_ENV !== 'production' && (0, utils_1.isDebugMode)()) {
+                /* eslint-disable no-console */
+                console.groupCollapsed(`ReactGlobalState - useGlobalState setter triggered for path ${rc.path || ''}`);
+                console.log('New value:', (0, lodash_1.cloneDeep)(newState));
+                console.groupEnd();
+                /* eslint-enable no-console */
+            }
+            rc.globalState.set(rc.path, newState);
+        },
+        state: (0, lodash_1.isFunction)(initialValue) ? initialValue() : initialValue,
+        watcher: () => {
+            const state = rc.globalState.get(rc.path);
+            if (state !== rc.state)
+                rc.emitter.emit();
+        },
+    };
+    ref.current = rc;
+    rc.globalState = globalState;
+    rc.path = path;
+    rc.state = (0, react_1.useSyncExternalStore)((cb) => rc.emitter.addListener(cb), () => rc.globalState.get(rc.path, { initialValue }), () => rc.globalState.get(rc.path, { initialValue, initialState: true }));
+    (0, react_1.useEffect)(() => {
+        const { watcher } = ref.current;
+        globalState.watch(watcher);
+        watcher();
+        return () => globalState.unWatch(watcher);
+    }, [globalState]);
+    (0, react_1.useEffect)(() => {
+        ref.current.watcher();
+    }, [path]);
+    return [rc.state, rc.setter];
+}
+exports.default = useGlobalState;

package/build/utils.d.ts

@@ -0,0 +1,31 @@
+import { type GetFieldType } from 'lodash';
+export type CallbackT = () => void;
+export type TypeLock<Unlocked extends 0 | 1, LockedT extends never | void, UnlockedT> = Unlocked extends 0 ? LockedT : UnlockedT;
+/**
+ * Given the type of state, `StateT`, and the type of state path, `PathT`,
+ * it evaluates the type of value at that path of the state, if it can be
+ * evaluated from the path type (it is possible when `PathT` is a string
+ * literal type, and `StateT` elements along this path have appropriate
+ * types); otherwise it falls back to the specified `UnknownT` type,
+ * which should be set either `never` (for input arguments), or `void`
+ * (for return types) - `never` and `void` in those places forbid assignments,
+ * and are not auto-inferred to more permissible types.
+ *
+ * BEWARE: When StateT is any the construct resolves to any for any string
+ * paths.
+ */
+export type ValueAtPathT<StateT, PathT extends null | string | undefined, UnknownT extends never | undefined | void> = unknown extends StateT ? UnknownT : string extends PathT ? UnknownT : PathT extends null | undefined ? StateT : GetFieldType<StateT, PathT> extends undefined ? UnknownT : GetFieldType<StateT, PathT>;
+export type ValueOrInitializerT<ValueT> = ValueT | (() => ValueT);
+/**
+ * Returns 'true' if debug logging should be performed; 'false' otherwise.
+ *
+ * BEWARE: The actual safeguards for the debug logging still should read
+ *  if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
+ *    // Some debug logging
+ *  }
+ * to ensure that debug code is stripped out by Webpack in production mode.
+ *
+ * @returns
+ * @ignore
+ */
+export declare function isDebugMode(): boolean;