@dr.pogodin/react-global-state 0.10.0-alpha.3 → 0.10.0-alpha.4

package/build/module/useAsyncData.js.map

@@ -1 +1 @@
-{"version":3,"file":"useAsyncData.js","names":["cloneDeep","useEffect","v4","uuid","MIN_MS","getGlobalState","useGlobalState","isDebugMode","DEFAULT_MAXAGE","newAsyncDataEnvelope","initialData","arguments","length","undefined","data","numRefs","operationId","timestamp","load","path","loader","globalState","oldData","opIdPrefix","process","env","NODE_ENV","console","log","operationIdPath","set","get","state","groupCollapsed","Date","now","groupEnd","useAsyncData","options","maxage","refreshAge","garbageCollectAge","initialValue","ssrContext","noSSR","pending","push","numRefsPath","state2","loadTriggered","charAt","deps","localState","loading","Boolean"],"sources":["../../src/useAsyncData.ts"],"sourcesContent":["/**\n * Loads and uses async data into the GlobalState path.\n */\n\nimport { cloneDeep } from 'lodash';\nimport { useEffect } from 'react';\nimport { v4 as uuid } from 'uuid';\n\nimport { MIN_MS } from '@dr.pogodin/js-utils';\n\nimport { getGlobalState } from './GlobalStateProvider';\nimport useGlobalState from './useGlobalState';\n\nimport {\n  type ForceT,\n  type TypeLock,\n  type ValueAtPathT,\n  isDebugMode,\n} from './utils';\n\nimport GlobalState from './GlobalState';\nimport SsrContext from './SsrContext';\n\nconst DEFAULT_MAXAGE = 5 * MIN_MS; // 5 minutes.\n\nexport type AsyncDataLoaderT<DataT>\n= (oldData: null | DataT) => DataT | Promise<DataT>;\n\nexport type AsyncDataEnvelopeT<DataT> = {\n  data: null | DataT;\n  numRefs: number;\n  operationId: string;\n  timestamp: number;\n};\n\nexport function newAsyncDataEnvelope<DataT>(\n  initialData: DataT | null = null,\n): AsyncDataEnvelopeT<DataT> {\n  return {\n    data: initialData,\n    numRefs: 0,\n    operationId: '',\n    timestamp: 0,\n  };\n}\n\nexport type UseAsyncDataOptionsT = {\n  deps?: unknown[];\n  garbageCollectAge?: number;\n  maxage?: number;\n  noSSR?: boolean;\n  refreshAge?: number;\n};\n\nexport type UseAsyncDataResT<DataT> = {\n  data: DataT | null;\n  loading: boolean;\n  timestamp: number;\n};\n\n/**\n * Executes the data loading operation.\n * @param path Data segment path inside the global state.\n * @param loader Data loader.\n * @param globalState The global state instance.\n * @param oldData Optional. Previously fetched data, currently stored in\n *  the state, if already fetched by the caller; otherwise, they will be fetched\n *  by the load() function itself.\n * @param opIdPrefix operationId prefix to use, which should be\n * 'C' at the client-side (default), or 'S' at the server-side (within SSR\n * context).\n * @return Resolves once the operation is done.\n * @ignore\n */\nasync function load<DataT>(\n  path: null | string | undefined,\n  loader: AsyncDataLoaderT<DataT>,\n  globalState: GlobalState<unknown, SsrContext<unknown>>,\n  oldData: DataT | null,\n  opIdPrefix: 'C' | 'S' = 'C',\n): Promise<void> {\n  if (process.env.NODE_ENV !== 'production' && isDebugMode()) {\n    /* eslint-disable no-console */\n    console.log(\n      `ReactGlobalState: useAsyncData data (re-)loading. Path: \"${path || ''}\"`,\n    );\n    /* eslint-enable no-console */\n  }\n  const operationId = opIdPrefix + uuid();\n  const operationIdPath = path ? `${path}.operationId` : 'operationId';\n  globalState.set<ForceT, string>(operationIdPath, operationId);\n  const data = await loader(\n    oldData || (globalState.get<ForceT, AsyncDataEnvelopeT<DataT>>(path)).data,\n  );\n  const state: AsyncDataEnvelopeT<DataT> = globalState.get<ForceT, AsyncDataEnvelopeT<DataT>>(path);\n  if (operationId === state.operationId) {\n    if (process.env.NODE_ENV !== 'production' && isDebugMode()) {\n      /* eslint-disable no-console */\n      console.groupCollapsed(\n        `ReactGlobalState: useAsyncData data (re-)loaded. Path: \"${\n          path || ''\n        }\"`,\n      );\n      console.log('Data:', cloneDeep(data));\n      /* eslint-enable no-console */\n    }\n    globalState.set<ForceT, AsyncDataEnvelopeT<DataT>>(path, {\n      ...state,\n      data,\n      operationId: '',\n      timestamp: Date.now(),\n    });\n    if (process.env.NODE_ENV !== 'production' && isDebugMode()) {\n      /* eslint-disable no-console */\n      console.groupEnd();\n      /* eslint-enable no-console */\n    }\n  }\n}\n\n/**\n * Resolves asynchronous data, and stores them at given `path` of global\n * state. When multiple components rely on asynchronous data at the same `path`,\n * the data are resolved once, and reused until their age is within specified\n * bounds. Once the data are stale, the hook allows to refresh them. It also\n * garbage-collects stale data from the global state when the last component\n * relying on them is unmounted.\n * @param path Dot-delimitered state path, where data envelop is\n * stored.\n * @param loader Asynchronous function which resolves (loads)\n * data, which should be stored at the global state `path`. When multiple\n * components\n * use `useAsyncData()` hook for the same `path`, the library assumes that all\n * hook instances are called with the same `loader` (_i.e._ whichever of these\n * loaders is used to resolve async data, the result is acceptable to be reused\n * in all related components).\n * @param options Additional options.\n * @param options.deps An array of dependencies, which trigger\n * data reload when changed. Given dependency changes are watched shallowly\n * (similarly to the standard React's\n * [useEffect()](https://reactjs.org/docs/hooks-reference.html#useeffect)).\n * @param options.noSSR If `true`, this hook won't load data during\n * server-side rendering.\n * @param options.garbageCollectAge The maximum age of data\n * (in milliseconds), after which they are dropped from the state when the last\n * component referencing them via `useAsyncData()` hook unmounts. Defaults to\n * `maxage` option value.\n * @param options.maxage The maximum age of\n * data (in milliseconds) acceptable to the hook's caller. If loaded data are\n * older than this value, `null` is returned instead. Defaults to 5 minutes.\n * @param options.refreshAge The maximum age of data\n * (in milliseconds), after which their refreshment will be triggered when\n * any component referencing them via `useAsyncData()` hook (re-)renders.\n * Defaults to `maxage` value.\n * @return Returns an object with three fields: `data` holds the actual result of\n * last `loader` invokation, if any, and if satisfies `maxage` limit; `loading`\n * is a boolean flag, which is `true` if data are being loaded (the hook is\n * waiting for `loader` function resolution); `timestamp` (in milliseconds)\n * is Unix timestamp of related data currently loaded into the global state.\n *\n * Note that loaded data, if any, are stored at the given `path` of global state\n * along with related meta-information, using slightly different state segment\n * structure (see {@link AsyncDataEnvelopeT}). That segment of the global state\n * can be accessed, and even modified using other hooks,\n * _e.g._ {@link useGlobalState}, but doing so you may interfere with related\n * `useAsyncData()` hooks logic.\n */\n\nexport type DataInEnvelopeAtPathT<StateT, PathT extends null | string | undefined>\n= ValueAtPathT<StateT, PathT, never> extends AsyncDataEnvelopeT<unknown>\n  ? Exclude<ValueAtPathT<StateT, PathT, never>['data'], null>\n  : void;\n\nfunction useAsyncData<\n  StateT,\n  PathT extends null | string | undefined,\n>(\n  path: PathT,\n  loader: AsyncDataLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>,\n  options?: UseAsyncDataOptionsT,\n): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;\n\nfunction useAsyncData<\n  Forced extends ForceT | false = false,\n  DataT = unknown,\n>(\n  path: null | string | undefined,\n  loader: AsyncDataLoaderT<TypeLock<Forced, void, DataT>>,\n  options?: UseAsyncDataOptionsT,\n): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;\n\nfunction useAsyncData<DataT>(\n  path: null | string | undefined,\n  loader: AsyncDataLoaderT<DataT>,\n  options: UseAsyncDataOptionsT = {},\n): UseAsyncDataResT<DataT> {\n  const maxage: number = options.maxage === undefined\n    ? DEFAULT_MAXAGE : options.maxage;\n\n  const refreshAge: number = options.refreshAge === undefined\n    ? maxage : options.refreshAge;\n\n  const garbageCollectAge: number = options.garbageCollectAge === undefined\n    ? maxage : options.garbageCollectAge;\n\n  // Note: here we can't depend on useGlobalState() to init the initial value,\n  // because that way we'll have issues with SSR (see details below).\n  const globalState = getGlobalState();\n  const state = globalState.get<ForceT, AsyncDataEnvelopeT<DataT>>(path, {\n    initialValue: newAsyncDataEnvelope<DataT>(),\n  });\n\n  if (globalState.ssrContext && !options.noSSR) {\n    if (!state.timestamp && !state.operationId) {\n      globalState.ssrContext.pending.push(\n        load(path, loader, globalState, state.data, 'S'),\n      );\n    }\n  } else {\n    // This takes care about the client-side reference counting, and garbage\n    // collection.\n    //\n    // Note: the Rules of Hook below are violated by conditional call to a hook,\n    // but as the condition is actually server-side or client-side environment,\n    // it is effectively non-conditional at the runtime.\n    //\n    // TODO: Though, maybe there is a way to refactor it into a cleaner code.\n    // The same applies to other useEffect() hooks below.\n    useEffect(() => { // eslint-disable-line react-hooks/rules-of-hooks\n      const numRefsPath = path ? `${path}.numRefs` : 'numRefs';\n      const numRefs = globalState.get<ForceT, number>(numRefsPath);\n      globalState.set<ForceT, number>(numRefsPath, numRefs + 1);\n      return () => {\n        const state2: AsyncDataEnvelopeT<DataT> = globalState.get<\n        ForceT, AsyncDataEnvelopeT<DataT>>(\n          path,\n        );\n        if (\n          state2.numRefs === 1\n          && garbageCollectAge < Date.now() - state2.timestamp\n        ) {\n          if (process.env.NODE_ENV !== 'production' && isDebugMode()) {\n            /* eslint-disable no-console */\n            console.log(\n              `ReactGlobalState - useAsyncData garbage collected at path ${\n                path || ''\n              }`,\n            );\n            /* eslint-enable no-console */\n          }\n          globalState.set<ForceT, AsyncDataEnvelopeT<DataT>>(path, {\n            ...state2,\n            data: null,\n            numRefs: 0,\n            timestamp: 0,\n          });\n        } else globalState.set<ForceT, number>(numRefsPath, state2.numRefs - 1);\n      };\n    }, [garbageCollectAge, globalState, path]);\n\n    // Note: a bunch of Rules of Hooks ignored belows because in our very\n    // special case the otherwise wrong behavior is actually what we need.\n\n    // Data loading and refreshing.\n    let loadTriggered = false;\n    useEffect(() => { // eslint-disable-line react-hooks/rules-of-hooks\n      const state2: AsyncDataEnvelopeT<DataT> = globalState.get<\n      ForceT, AsyncDataEnvelopeT<DataT>>(path);\n\n      if (refreshAge < Date.now() - state2.timestamp\n      && (!state2.operationId || state2.operationId.charAt(0) === 'S')) {\n        load(path, loader, globalState, state2.data);\n        loadTriggered = true; // eslint-disable-line react-hooks/exhaustive-deps\n      }\n    });\n\n    const deps = options.deps || [];\n    useEffect(() => { // eslint-disable-line react-hooks/rules-of-hooks\n      if (!loadTriggered && deps.length) load(path, loader, globalState, null);\n    }, deps); // eslint-disable-line react-hooks/exhaustive-deps\n  }\n\n  const [localState] = useGlobalState<ForceT, AsyncDataEnvelopeT<DataT>>(\n    path,\n    newAsyncDataEnvelope<DataT>(),\n  );\n\n  return {\n    data: maxage < Date.now() - localState.timestamp ? null : localState.data,\n    loading: Boolean(localState.operationId),\n    timestamp: localState.timestamp,\n  };\n}\n\nexport default useAsyncData;\n"],"mappings":"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"}
+{"version":3,"file":"useAsyncData.js","names":["cloneDeep","useEffect","v4","uuid","MIN_MS","getGlobalState","useGlobalState","isDebugMode","DEFAULT_MAXAGE","newAsyncDataEnvelope","initialData","arguments","length","undefined","data","numRefs","operationId","timestamp","load","path","loader","globalState","oldData","opIdPrefix","process","env","NODE_ENV","console","log","operationIdPath","set","get","state","groupCollapsed","Date","now","groupEnd","useAsyncData","options","maxage","refreshAge","garbageCollectAge","initialValue","ssrContext","noSSR","pending","push","numRefsPath","state2","loadTriggered","charAt","deps","localState","loading","Boolean"],"sources":["../../src/useAsyncData.ts"],"sourcesContent":["/**\n * Loads and uses async data into the GlobalState path.\n */\n\nimport { cloneDeep } from 'lodash';\nimport { useEffect } from 'react';\nimport { v4 as uuid } from 'uuid';\n\nimport { MIN_MS } from '@dr.pogodin/js-utils';\n\nimport { getGlobalState } from './GlobalStateProvider';\nimport useGlobalState from './useGlobalState';\n\nimport {\n  type ForceT,\n  type LockT,\n  type TypeLock,\n  type ValueAtPathT,\n  isDebugMode,\n} from './utils';\n\nimport GlobalState from './GlobalState';\nimport SsrContext from './SsrContext';\n\nconst DEFAULT_MAXAGE = 5 * MIN_MS; // 5 minutes.\n\nexport type AsyncDataLoaderT<DataT>\n= (oldData: null | DataT) => DataT | Promise<DataT>;\n\nexport type AsyncDataEnvelopeT<DataT> = {\n  data: null | DataT;\n  numRefs: number;\n  operationId: string;\n  timestamp: number;\n};\n\nexport function newAsyncDataEnvelope<DataT>(\n  initialData: DataT | null = null,\n): AsyncDataEnvelopeT<DataT> {\n  return {\n    data: initialData,\n    numRefs: 0,\n    operationId: '',\n    timestamp: 0,\n  };\n}\n\nexport type UseAsyncDataOptionsT = {\n  deps?: unknown[];\n  garbageCollectAge?: number;\n  maxage?: number;\n  noSSR?: boolean;\n  refreshAge?: number;\n};\n\nexport type UseAsyncDataResT<DataT> = {\n  data: DataT | null;\n  loading: boolean;\n  timestamp: number;\n};\n\n/**\n * Executes the data loading operation.\n * @param path Data segment path inside the global state.\n * @param loader Data loader.\n * @param globalState The global state instance.\n * @param oldData Optional. Previously fetched data, currently stored in\n *  the state, if already fetched by the caller; otherwise, they will be fetched\n *  by the load() function itself.\n * @param opIdPrefix operationId prefix to use, which should be\n * 'C' at the client-side (default), or 'S' at the server-side (within SSR\n * context).\n * @return Resolves once the operation is done.\n * @ignore\n */\nasync function load<DataT>(\n  path: null | string | undefined,\n  loader: AsyncDataLoaderT<DataT>,\n  globalState: GlobalState<unknown, SsrContext<unknown>>,\n  oldData: DataT | null,\n  opIdPrefix: 'C' | 'S' = 'C',\n): Promise<void> {\n  if (process.env.NODE_ENV !== 'production' && isDebugMode()) {\n    /* eslint-disable no-console */\n    console.log(\n      `ReactGlobalState: useAsyncData data (re-)loading. Path: \"${path || ''}\"`,\n    );\n    /* eslint-enable no-console */\n  }\n  const operationId = opIdPrefix + uuid();\n  const operationIdPath = path ? `${path}.operationId` : 'operationId';\n  globalState.set<ForceT, string>(operationIdPath, operationId);\n  const data = await loader(\n    oldData || (globalState.get<ForceT, AsyncDataEnvelopeT<DataT>>(path)).data,\n  );\n  const state: AsyncDataEnvelopeT<DataT> = globalState.get<ForceT, AsyncDataEnvelopeT<DataT>>(path);\n  if (operationId === state.operationId) {\n    if (process.env.NODE_ENV !== 'production' && isDebugMode()) {\n      /* eslint-disable no-console */\n      console.groupCollapsed(\n        `ReactGlobalState: useAsyncData data (re-)loaded. Path: \"${\n          path || ''\n        }\"`,\n      );\n      console.log('Data:', cloneDeep(data));\n      /* eslint-enable no-console */\n    }\n    globalState.set<ForceT, AsyncDataEnvelopeT<DataT>>(path, {\n      ...state,\n      data,\n      operationId: '',\n      timestamp: Date.now(),\n    });\n    if (process.env.NODE_ENV !== 'production' && isDebugMode()) {\n      /* eslint-disable no-console */\n      console.groupEnd();\n      /* eslint-enable no-console */\n    }\n  }\n}\n\n/**\n * Resolves asynchronous data, and stores them at given `path` of global\n * state. When multiple components rely on asynchronous data at the same `path`,\n * the data are resolved once, and reused until their age is within specified\n * bounds. Once the data are stale, the hook allows to refresh them. It also\n * garbage-collects stale data from the global state when the last component\n * relying on them is unmounted.\n * @param path Dot-delimitered state path, where data envelop is\n * stored.\n * @param loader Asynchronous function which resolves (loads)\n * data, which should be stored at the global state `path`. When multiple\n * components\n * use `useAsyncData()` hook for the same `path`, the library assumes that all\n * hook instances are called with the same `loader` (_i.e._ whichever of these\n * loaders is used to resolve async data, the result is acceptable to be reused\n * in all related components).\n * @param options Additional options.\n * @param options.deps An array of dependencies, which trigger\n * data reload when changed. Given dependency changes are watched shallowly\n * (similarly to the standard React's\n * [useEffect()](https://reactjs.org/docs/hooks-reference.html#useeffect)).\n * @param options.noSSR If `true`, this hook won't load data during\n * server-side rendering.\n * @param options.garbageCollectAge The maximum age of data\n * (in milliseconds), after which they are dropped from the state when the last\n * component referencing them via `useAsyncData()` hook unmounts. Defaults to\n * `maxage` option value.\n * @param options.maxage The maximum age of\n * data (in milliseconds) acceptable to the hook's caller. If loaded data are\n * older than this value, `null` is returned instead. Defaults to 5 minutes.\n * @param options.refreshAge The maximum age of data\n * (in milliseconds), after which their refreshment will be triggered when\n * any component referencing them via `useAsyncData()` hook (re-)renders.\n * Defaults to `maxage` value.\n * @return Returns an object with three fields: `data` holds the actual result of\n * last `loader` invokation, if any, and if satisfies `maxage` limit; `loading`\n * is a boolean flag, which is `true` if data are being loaded (the hook is\n * waiting for `loader` function resolution); `timestamp` (in milliseconds)\n * is Unix timestamp of related data currently loaded into the global state.\n *\n * Note that loaded data, if any, are stored at the given `path` of global state\n * along with related meta-information, using slightly different state segment\n * structure (see {@link AsyncDataEnvelopeT}). That segment of the global state\n * can be accessed, and even modified using other hooks,\n * _e.g._ {@link useGlobalState}, but doing so you may interfere with related\n * `useAsyncData()` hooks logic.\n */\n\nexport type DataInEnvelopeAtPathT<StateT, PathT extends null | string | undefined>\n= ValueAtPathT<StateT, PathT, never> extends AsyncDataEnvelopeT<unknown>\n  ? Exclude<ValueAtPathT<StateT, PathT, never>['data'], null>\n  : void;\n\nfunction useAsyncData<\n  StateT,\n  PathT extends null | string | undefined,\n>(\n  path: PathT,\n  loader: AsyncDataLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>,\n  options?: UseAsyncDataOptionsT,\n): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;\n\nfunction useAsyncData<\n  Forced extends ForceT | LockT = LockT,\n  DataT = void,\n>(\n  path: null | string | undefined,\n  loader: AsyncDataLoaderT<TypeLock<Forced, void, DataT>>,\n  options?: UseAsyncDataOptionsT,\n): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;\n\nfunction useAsyncData<DataT>(\n  path: null | string | undefined,\n  loader: AsyncDataLoaderT<DataT>,\n  options: UseAsyncDataOptionsT = {},\n): UseAsyncDataResT<DataT> {\n  const maxage: number = options.maxage === undefined\n    ? DEFAULT_MAXAGE : options.maxage;\n\n  const refreshAge: number = options.refreshAge === undefined\n    ? maxage : options.refreshAge;\n\n  const garbageCollectAge: number = options.garbageCollectAge === undefined\n    ? maxage : options.garbageCollectAge;\n\n  // Note: here we can't depend on useGlobalState() to init the initial value,\n  // because that way we'll have issues with SSR (see details below).\n  const globalState = getGlobalState();\n  const state = globalState.get<ForceT, AsyncDataEnvelopeT<DataT>>(path, {\n    initialValue: newAsyncDataEnvelope<DataT>(),\n  });\n\n  if (globalState.ssrContext && !options.noSSR) {\n    if (!state.timestamp && !state.operationId) {\n      globalState.ssrContext.pending.push(\n        load(path, loader, globalState, state.data, 'S'),\n      );\n    }\n  } else {\n    // This takes care about the client-side reference counting, and garbage\n    // collection.\n    //\n    // Note: the Rules of Hook below are violated by conditional call to a hook,\n    // but as the condition is actually server-side or client-side environment,\n    // it is effectively non-conditional at the runtime.\n    //\n    // TODO: Though, maybe there is a way to refactor it into a cleaner code.\n    // The same applies to other useEffect() hooks below.\n    useEffect(() => { // eslint-disable-line react-hooks/rules-of-hooks\n      const numRefsPath = path ? `${path}.numRefs` : 'numRefs';\n      const numRefs = globalState.get<ForceT, number>(numRefsPath);\n      globalState.set<ForceT, number>(numRefsPath, numRefs + 1);\n      return () => {\n        const state2: AsyncDataEnvelopeT<DataT> = globalState.get<\n        ForceT, AsyncDataEnvelopeT<DataT>>(\n          path,\n        );\n        if (\n          state2.numRefs === 1\n          && garbageCollectAge < Date.now() - state2.timestamp\n        ) {\n          if (process.env.NODE_ENV !== 'production' && isDebugMode()) {\n            /* eslint-disable no-console */\n            console.log(\n              `ReactGlobalState - useAsyncData garbage collected at path ${\n                path || ''\n              }`,\n            );\n            /* eslint-enable no-console */\n          }\n          globalState.set<ForceT, AsyncDataEnvelopeT<DataT>>(path, {\n            ...state2,\n            data: null,\n            numRefs: 0,\n            timestamp: 0,\n          });\n        } else globalState.set<ForceT, number>(numRefsPath, state2.numRefs - 1);\n      };\n    }, [garbageCollectAge, globalState, path]);\n\n    // Note: a bunch of Rules of Hooks ignored belows because in our very\n    // special case the otherwise wrong behavior is actually what we need.\n\n    // Data loading and refreshing.\n    let loadTriggered = false;\n    useEffect(() => { // eslint-disable-line react-hooks/rules-of-hooks\n      const state2: AsyncDataEnvelopeT<DataT> = globalState.get<\n      ForceT, AsyncDataEnvelopeT<DataT>>(path);\n\n      if (refreshAge < Date.now() - state2.timestamp\n      && (!state2.operationId || state2.operationId.charAt(0) === 'S')) {\n        load(path, loader, globalState, state2.data);\n        loadTriggered = true; // eslint-disable-line react-hooks/exhaustive-deps\n      }\n    });\n\n    const deps = options.deps || [];\n    useEffect(() => { // eslint-disable-line react-hooks/rules-of-hooks\n      if (!loadTriggered && deps.length) load(path, loader, globalState, null);\n    }, deps); // eslint-disable-line react-hooks/exhaustive-deps\n  }\n\n  const [localState] = useGlobalState<ForceT, AsyncDataEnvelopeT<DataT>>(\n    path,\n    newAsyncDataEnvelope<DataT>(),\n  );\n\n  return {\n    data: maxage < Date.now() - localState.timestamp ? null : localState.data,\n    loading: Boolean(localState.operationId),\n    timestamp: localState.timestamp,\n  };\n}\n\nexport default useAsyncData;\n\nexport interface UseAsyncDataI<StateT> {\n  <PathT extends null | string | undefined>(\n    path: PathT,\n    loader: AsyncDataLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>,\n    options?: UseAsyncDataOptionsT,\n  ): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;\n\n  <Forced extends ForceT | LockT = LockT, DataT = unknown>(\n    path: null | string | undefined,\n    loader: AsyncDataLoaderT<TypeLock<Forced, void, DataT>>,\n    options?: UseAsyncDataOptionsT,\n  ): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;\n}\n"],"mappings":"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"}

package/build/module/useGlobalState.js

@@ -55,8 +55,9 @@ 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.
- */
-
+ */ // "Enforced type overload"
+// "Entire state overload"
+// "State evaluation overload"
 function useGlobalState(path, initialValue) {
   const globalState = getGlobalState();
   const ref = useRef();

package/build/module/useGlobalState.js.map

@@ -1 +1 @@
-{"version":3,"file":"useGlobalState.js","names":["cloneDeep","isFunction","useEffect","useRef","useSyncExternalStore","Emitter","getGlobalState","isDebugMode","useGlobalState","path","initialValue","globalState","ref","rc","current","emitter","setter","value","newState","state","process","env","NODE_ENV","console","groupCollapsed","log","groupEnd","set","watcher","get","emit","cb","addListener","initialState","watch","unWatch"],"sources":["../../src/useGlobalState.ts"],"sourcesContent":["// Hook for updates of global state.\n\nimport { cloneDeep, isFunction } from 'lodash';\nimport { useEffect, useRef, useSyncExternalStore } from 'react';\n\nimport { Emitter } from '@dr.pogodin/js-utils';\n\nimport GlobalState from './GlobalState';\nimport { getGlobalState } from './GlobalStateProvider';\n\nimport {\n  type CallbackT,\n  type ForceT,\n  type TypeLock,\n  type ValueAtPathT,\n  type ValueOrInitializerT,\n  isDebugMode,\n} from './utils';\n\nexport type SetterT<T> = React.Dispatch<React.SetStateAction<T>>;\n\ntype GlobalStateRef = {\n  emitter: Emitter<[]>;\n  globalState: GlobalState<unknown>;\n  path: null | string | undefined;\n  setter: SetterT<unknown>;\n  state: unknown;\n  watcher: CallbackT;\n};\n\nexport type UseGlobalStateResT<T> = [T, SetterT<T>];\n\n/**\n * The primary hook for interacting with the global state, modeled after\n * the standard React's\n * [useState](https://reactjs.org/docs/hooks-reference.html#usestate).\n * It subscribes a component to a given `path` of global state, and provides\n * a function to update it. Each time the value at `path` changes, the hook\n * triggers re-render of its host component.\n *\n * **Note:**\n * - For performance, the library does not copy objects written to / read from\n *   global state paths. You MUST NOT manually mutate returned state values,\n *   or change objects already written into the global state, without explicitly\n *   clonning them first yourself.\n * - State update notifications are asynchronous. When your code does multiple\n *   global state updates in the same React rendering cycle, all state update\n *   notifications are queued and dispatched together, after the current\n *   rendering cycle. In other words, in any given rendering cycle the global\n *   state values are \"fixed\", and all changes becomes visible at once in the\n *   next triggered rendering pass.\n *\n * @param path Dot-delimitered state path. It can be undefined to\n * subscribe for entire state.\n *\n * Under-the-hood state values are read and written using `lodash`\n * [_.get()](https://lodash.com/docs/4.17.15#get) and\n * [_.set()](https://lodash.com/docs/4.17.15#set) methods, thus it is safe\n * to access state paths which have not been created before.\n * @param initialValue Initial value to set at the `path`, or its\n * factory:\n * - If a function is given, it will act similar to\n *   [the lazy initial state of the standard React's useState()](https://reactjs.org/docs/hooks-reference.html#lazy-initial-state):\n *   only if the value at `path` is `undefined`, the function will be executed,\n *   and the value it returns will be written to the `path`.\n * - Otherwise, the given value itself will be written to the `path`,\n *   if the current value at `path` is `undefined`.\n * @return It returs an array with two elements: `[value, setValue]`:\n *\n * - The `value` is the current value at given `path`.\n *\n * - The `setValue()` is setter function to write a new value to the `path`.\n *\n *   Similar to the standard React's `useState()`, it supports\n *   [functional value updates](https://reactjs.org/docs/hooks-reference.html#functional-updates):\n *   if `setValue()` is called with a function as argument, that function will\n *   be called and its return value will be written to `path`. Otherwise,\n *   the argument of `setValue()` itself is written to `path`.\n *\n *   Also, similar to the standard React's state setters, `setValue()` is\n *   stable function: it does not change between component re-renders.\n */\n\nfunction useGlobalState<StateT>(): UseGlobalStateResT<StateT>;\n\nfunction useGlobalState<Forced extends ForceT | false = false, ValueT = unknown>(\n  path: null | string | undefined,\n  initialValue?: ValueOrInitializerT<TypeLock<Forced, never, ValueT>>,\n): UseGlobalStateResT<TypeLock<Forced, void, ValueT>>;\n\nfunction useGlobalState<\n  StateT,\n  PathT extends null | string | undefined,\n>(\n  path: PathT,\n  initialValue?: ValueOrInitializerT<ValueAtPathT<StateT, PathT, never>>\n): UseGlobalStateResT<ValueAtPathT<StateT, PathT, void>>;\n\nfunction useGlobalState(\n  path?: null | string,\n  initialValue?: ValueOrInitializerT<unknown>,\n): UseGlobalStateResT<any> {\n  const globalState = getGlobalState();\n\n  const ref = useRef<GlobalStateRef>();\n  const rc: GlobalStateRef = ref.current || {\n    emitter: new Emitter(),\n    globalState,\n    path,\n    setter: (value) => {\n      const newState = isFunction(value) ? value(rc.state) : value;\n      if (process.env.NODE_ENV !== 'production' && isDebugMode()) {\n        /* eslint-disable no-console */\n        console.groupCollapsed(\n          `ReactGlobalState - useGlobalState setter triggered for path ${\n            rc.path || ''\n          }`,\n        );\n        console.log('New value:', cloneDeep(newState));\n        console.groupEnd();\n        /* eslint-enable no-console */\n      }\n      rc.globalState.set<ForceT, unknown>(rc.path, newState);\n    },\n    state: isFunction(initialValue) ? initialValue() : initialValue,\n    watcher: () => {\n      const state = rc.globalState.get(rc.path);\n      if (state !== rc.state) rc.emitter.emit();\n    },\n  };\n  ref.current = rc;\n\n  rc.globalState = globalState;\n  rc.path = path;\n\n  rc.state = useSyncExternalStore(\n    (cb) => rc.emitter.addListener(cb),\n    () => rc.globalState.get<ForceT, unknown>(rc.path, { initialValue }),\n    () => rc.globalState.get<ForceT, unknown>(rc.path, { initialValue, initialState: true }),\n  );\n\n  useEffect(() => {\n    const { watcher } = ref.current!;\n    globalState.watch(watcher);\n    watcher();\n    return () => globalState.unWatch(watcher);\n  }, [globalState]);\n\n  useEffect(() => {\n    ref.current!.watcher();\n  }, [path]);\n\n  return [rc.state, rc.setter];\n}\n\nexport default useGlobalState;\n"],"mappings":"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"}
+{"version":3,"file":"useGlobalState.js","names":["cloneDeep","isFunction","useEffect","useRef","useSyncExternalStore","Emitter","getGlobalState","isDebugMode","useGlobalState","path","initialValue","globalState","ref","rc","current","emitter","setter","value","newState","state","process","env","NODE_ENV","console","groupCollapsed","log","groupEnd","set","watcher","get","emit","cb","addListener","initialState","watch","unWatch"],"sources":["../../src/useGlobalState.ts"],"sourcesContent":["// Hook for updates of global state.\n\nimport { cloneDeep, isFunction } from 'lodash';\nimport { useEffect, useRef, useSyncExternalStore } from 'react';\n\nimport { Emitter } from '@dr.pogodin/js-utils';\n\nimport GlobalState from './GlobalState';\nimport { getGlobalState } from './GlobalStateProvider';\n\nimport {\n  type CallbackT,\n  type ForceT,\n  type LockT,\n  type TypeLock,\n  type ValueAtPathT,\n  type ValueOrInitializerT,\n  isDebugMode,\n} from './utils';\n\nexport type SetterT<T> = React.Dispatch<React.SetStateAction<T>>;\n\ntype GlobalStateRef = {\n  emitter: Emitter<[]>;\n  globalState: GlobalState<unknown>;\n  path: null | string | undefined;\n  setter: SetterT<unknown>;\n  state: unknown;\n  watcher: CallbackT;\n};\n\nexport type UseGlobalStateResT<T> = [T, SetterT<T>];\n\n/**\n * The primary hook for interacting with the global state, modeled after\n * the standard React's\n * [useState](https://reactjs.org/docs/hooks-reference.html#usestate).\n * It subscribes a component to a given `path` of global state, and provides\n * a function to update it. Each time the value at `path` changes, the hook\n * triggers re-render of its host component.\n *\n * **Note:**\n * - For performance, the library does not copy objects written to / read from\n *   global state paths. You MUST NOT manually mutate returned state values,\n *   or change objects already written into the global state, without explicitly\n *   clonning them first yourself.\n * - State update notifications are asynchronous. When your code does multiple\n *   global state updates in the same React rendering cycle, all state update\n *   notifications are queued and dispatched together, after the current\n *   rendering cycle. In other words, in any given rendering cycle the global\n *   state values are \"fixed\", and all changes becomes visible at once in the\n *   next triggered rendering pass.\n *\n * @param path Dot-delimitered state path. It can be undefined to\n * subscribe for entire state.\n *\n * Under-the-hood state values are read and written using `lodash`\n * [_.get()](https://lodash.com/docs/4.17.15#get) and\n * [_.set()](https://lodash.com/docs/4.17.15#set) methods, thus it is safe\n * to access state paths which have not been created before.\n * @param initialValue Initial value to set at the `path`, or its\n * factory:\n * - If a function is given, it will act similar to\n *   [the lazy initial state of the standard React's useState()](https://reactjs.org/docs/hooks-reference.html#lazy-initial-state):\n *   only if the value at `path` is `undefined`, the function will be executed,\n *   and the value it returns will be written to the `path`.\n * - Otherwise, the given value itself will be written to the `path`,\n *   if the current value at `path` is `undefined`.\n * @return It returs an array with two elements: `[value, setValue]`:\n *\n * - The `value` is the current value at given `path`.\n *\n * - The `setValue()` is setter function to write a new value to the `path`.\n *\n *   Similar to the standard React's `useState()`, it supports\n *   [functional value updates](https://reactjs.org/docs/hooks-reference.html#functional-updates):\n *   if `setValue()` is called with a function as argument, that function will\n *   be called and its return value will be written to `path`. Otherwise,\n *   the argument of `setValue()` itself is written to `path`.\n *\n *   Also, similar to the standard React's state setters, `setValue()` is\n *   stable function: it does not change between component re-renders.\n */\n\n// \"Enforced type overload\"\nfunction useGlobalState<\n  Forced extends ForceT | LockT = LockT,\n  ValueT = void,\n>(\n  path: null | string | undefined,\n  initialValue?: ValueOrInitializerT<TypeLock<Forced, never, ValueT>>,\n): UseGlobalStateResT<TypeLock<Forced, void, ValueT>>;\n\n// \"Entire state overload\"\nfunction useGlobalState<StateT>(): UseGlobalStateResT<StateT>;\n\n// \"State evaluation overload\"\nfunction useGlobalState<\n  StateT,\n  PathT extends null | string | undefined,\n>(\n  path: PathT,\n  initialValue?: ValueOrInitializerT<ValueAtPathT<StateT, PathT, never>>\n): UseGlobalStateResT<ValueAtPathT<StateT, PathT, void>>;\n\nfunction useGlobalState(\n  path?: null | string,\n  initialValue?: ValueOrInitializerT<unknown>,\n): UseGlobalStateResT<any> {\n  const globalState = getGlobalState();\n\n  const ref = useRef<GlobalStateRef>();\n  const rc: GlobalStateRef = ref.current || {\n    emitter: new Emitter(),\n    globalState,\n    path,\n    setter: (value) => {\n      const newState = isFunction(value) ? value(rc.state) : value;\n      if (process.env.NODE_ENV !== 'production' && isDebugMode()) {\n        /* eslint-disable no-console */\n        console.groupCollapsed(\n          `ReactGlobalState - useGlobalState setter triggered for path ${\n            rc.path || ''\n          }`,\n        );\n        console.log('New value:', cloneDeep(newState));\n        console.groupEnd();\n        /* eslint-enable no-console */\n      }\n      rc.globalState.set<ForceT, unknown>(rc.path, newState);\n    },\n    state: isFunction(initialValue) ? initialValue() : initialValue,\n    watcher: () => {\n      const state = rc.globalState.get(rc.path);\n      if (state !== rc.state) rc.emitter.emit();\n    },\n  };\n  ref.current = rc;\n\n  rc.globalState = globalState;\n  rc.path = path;\n\n  rc.state = useSyncExternalStore(\n    (cb) => rc.emitter.addListener(cb),\n    () => rc.globalState.get<ForceT, unknown>(rc.path, { initialValue }),\n    () => rc.globalState.get<ForceT, unknown>(rc.path, { initialValue, initialState: true }),\n  );\n\n  useEffect(() => {\n    const { watcher } = ref.current!;\n    globalState.watch(watcher);\n    watcher();\n    return () => globalState.unWatch(watcher);\n  }, [globalState]);\n\n  useEffect(() => {\n    ref.current!.watcher();\n  }, [path]);\n\n  return [rc.state, rc.setter];\n}\n\nexport default useGlobalState;\n\nexport interface UseGlobalStateI<StateT> {\n  (): UseGlobalStateResT<StateT>;\n\n  <PathT extends null | string | undefined>(\n    path: PathT,\n    initialValue?: ValueOrInitializerT<ValueAtPathT<StateT, PathT, never>>\n  ): UseGlobalStateResT<ValueAtPathT<StateT, PathT, void>>;\n\n  <Forced extends ForceT | LockT = LockT, ValueT = unknown>(\n    path: null | string | undefined,\n    initialValue?: ValueOrInitializerT<TypeLock<Forced, never, ValueT>>,\n  ): UseGlobalStateResT<TypeLock<Forced, void, ValueT>>;\n}\n"],"mappings":"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"}

package/build/module/utils.js

@@ -1,5 +1,5 @@
-// TODO: This (ForceT & TypeLock) probably should be moved to JS Utils lib.
-// This type is used to "unlocked" special generic overrides around the library.
+// TODO: This (ForceT, LockT, and TypeLock) probably should be moved to JS Utils
+// lib.
 /**
  * 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

package/build/module/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","names":["isDebugMode","process","env","NODE_ENV","REACT_GLOBAL_STATE_DEBUG","error"],"sources":["../../src/utils.ts"],"sourcesContent":["import { type GetFieldType } from 'lodash';\n\nexport type CallbackT = () => void;\n\n// TODO: This (ForceT & TypeLock) probably should be moved to JS Utils lib.\n\n// This type is used to \"unlocked\" special generic overrides around the library.\ndeclare const force: unique symbol;\nexport type ForceT = typeof force;\n\nexport type TypeLock<\n  Unlocked extends ForceT | false,\n  LockedT extends never | void,\n  UnlockedT,\n> = Unlocked extends ForceT ? UnlockedT : LockedT;\n\n/**\n * Given the type of state, `StateT`, and the type of state path, `PathT`,\n * it evaluates the type of value at that path of the state, if it can be\n * evaluated from the path type (it is possible when `PathT` is a string\n * literal type, and `StateT` elements along this path have appropriate\n * types); otherwise it falls back to the specified `UnknownT` type,\n * which should be set either `never` (for input arguments), or `void`\n * (for return types) - `never` and `void` in those places forbid assignments,\n * and are not auto-inferred to more permissible types.\n *\n * BEWARE: When StateT is any the construct resolves to any for any string\n * paths.\n */\nexport type ValueAtPathT<\n  StateT,\n  PathT extends null | string | undefined,\n  UnknownT extends never | undefined | void,\n> = unknown extends StateT\n  ? UnknownT\n  : string extends PathT\n    ? UnknownT\n    : PathT extends null | undefined\n      ? StateT\n      : GetFieldType<StateT, PathT> extends undefined\n        ? UnknownT : GetFieldType<StateT, PathT>;\n\nexport type ValueOrInitializerT<ValueT> = ValueT | (() => ValueT);\n\n/**\n * Returns 'true' if debug logging should be performed; 'false' otherwise.\n *\n * BEWARE: The actual safeguards for the debug logging still should read\n *  if (process.env.NODE_ENV !== 'production' && isDebugMode()) {\n *    // Some debug logging\n *  }\n * to ensure that debug code is stripped out by Webpack in production mode.\n *\n * @returns\n * @ignore\n */\nexport function isDebugMode(): boolean {\n  try {\n    return process.env.NODE_ENV !== 'production'\n      && !!process.env.REACT_GLOBAL_STATE_DEBUG;\n  } catch (error) {\n    return false;\n  }\n}\n"],"mappings":"AAIA;AAEA;AAUA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AAgBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,WAAWA,CAAA,EAAY;EACrC,IAAI;IACF,OAAOC,OAAO,CAACC,GAAG,CAACC,QAAQ,KAAK,YAAY,IACvC,CAAC,CAACF,OAAO,CAACC,GAAG,CAACE,wBAAwB;EAC7C,CAAC,CAAC,OAAOC,KAAK,EAAE;IACd,OAAO,KAAK;EACd;AACF"}
+{"version":3,"file":"utils.js","names":["isDebugMode","process","env","NODE_ENV","REACT_GLOBAL_STATE_DEBUG","error"],"sources":["../../src/utils.ts"],"sourcesContent":["import { type GetFieldType } from 'lodash';\n\nexport type CallbackT = () => void;\n\n// TODO: This (ForceT, LockT, and TypeLock) probably should be moved to JS Utils\n// lib.\n\ndeclare const force: unique symbol;\ndeclare const lock: unique symbol;\n\nexport type ForceT = typeof force;\nexport type LockT = typeof lock;\n\nexport type TypeLock<\n  Unlocked extends ForceT | LockT,\n  LockedT extends never | void,\n  UnlockedT,\n> = Unlocked extends ForceT ? UnlockedT : LockedT;\n\n/**\n * Given the type of state, `StateT`, and the type of state path, `PathT`,\n * it evaluates the type of value at that path of the state, if it can be\n * evaluated from the path type (it is possible when `PathT` is a string\n * literal type, and `StateT` elements along this path have appropriate\n * types); otherwise it falls back to the specified `UnknownT` type,\n * which should be set either `never` (for input arguments), or `void`\n * (for return types) - `never` and `void` in those places forbid assignments,\n * and are not auto-inferred to more permissible types.\n *\n * BEWARE: When StateT is any the construct resolves to any for any string\n * paths.\n */\nexport type ValueAtPathT<\n  StateT,\n  PathT extends null | string | undefined,\n  UnknownT extends never | undefined | void,\n> = unknown extends StateT\n  ? UnknownT\n  : string extends PathT\n    ? UnknownT\n    : PathT extends null | undefined\n      ? StateT\n      : GetFieldType<StateT, PathT> extends undefined\n        ? UnknownT : GetFieldType<StateT, PathT>;\n\nexport type ValueOrInitializerT<ValueT> = ValueT | (() => ValueT);\n\n/**\n * Returns 'true' if debug logging should be performed; 'false' otherwise.\n *\n * BEWARE: The actual safeguards for the debug logging still should read\n *  if (process.env.NODE_ENV !== 'production' && isDebugMode()) {\n *    // Some debug logging\n *  }\n * to ensure that debug code is stripped out by Webpack in production mode.\n *\n * @returns\n * @ignore\n */\nexport function isDebugMode(): boolean {\n  try {\n    return process.env.NODE_ENV !== 'production'\n      && !!process.env.REACT_GLOBAL_STATE_DEBUG;\n  } catch (error) {\n    return false;\n  }\n}\n"],"mappings":"AAIA;AACA;AAcA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AAgBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,WAAWA,CAAA,EAAY;EACrC,IAAI;IACF,OAAOC,OAAO,CAACC,GAAG,CAACC,QAAQ,KAAK,YAAY,IACvC,CAAC,CAACF,OAAO,CAACC,GAAG,CAACE,wBAAwB;EAC7C,CAAC,CAAC,OAAOC,KAAK,EAAE;IACd,OAAO,KAAK;EACd;AACF"}

package/build/types/GlobalState.d.ts

@@ -1,5 +1,5 @@
 import SsrContext from './SsrContext';
-import { type CallbackT, type ForceT, type TypeLock, type ValueAtPathT, type ValueOrInitializerT } from './utils';
+import { type CallbackT, type ForceT, type LockT, type TypeLock, type ValueAtPathT, type ValueOrInitializerT } from './utils';
 type GetOptsT<T> = {
     initialState?: boolean;
     initialValue?: ValueOrInitializerT<T>;
@@ -42,7 +42,7 @@ export default class GlobalState<StateT, SsrContextT extends SsrContext<StateT>
      */
     get(): StateT;
     get<PathT extends null | string | undefined, ValueArgT extends ValueAtPathT<StateT, PathT, never>, ValueResT extends ValueAtPathT<StateT, PathT, void>>(path: PathT, opts?: GetOptsT<ValueArgT>): ValueResT;
-    get<Forced extends ForceT | false = false, ValueT = void>(path?: null | string, opts?: GetOptsT<TypeLock<Forced, never, ValueT>>): TypeLock<Forced, void, ValueT>;
+    get<Forced extends ForceT | LockT = LockT, ValueT = void>(path?: null | string, opts?: GetOptsT<TypeLock<Forced, never, ValueT>>): TypeLock<Forced, void, ValueT>;
     /**
      * Writes the `value` to given global state `path`.
      * @param path Dot-delimitered state path. If not given, entire
@@ -51,7 +51,7 @@ export default class GlobalState<StateT, SsrContextT extends SsrContext<StateT>
      * @return Given `value` itself.
      */
     set<PathT extends null | string | undefined, ValueArgT extends ValueAtPathT<StateT, PathT, never>, ValueResT extends ValueAtPathT<StateT, PathT, void>>(path: PathT, value: ValueArgT): ValueResT;
-    set<Forced extends ForceT | false = false, ValueT = never>(path: null | string | undefined, value: TypeLock<Forced, never, ValueT>): TypeLock<Forced, void, ValueT>;
+    set<Forced extends ForceT | LockT = LockT, ValueT = never>(path: null | string | undefined, value: TypeLock<Forced, never, ValueT>): TypeLock<Forced, void, ValueT>;
     /**
      * Unsubscribes `callback` from watching state updates; no operation if
      * `callback` is not subscribed to the state updates.

package/build/types/index.d.ts

@@ -1,8 +1,24 @@
-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 ForceT, type ValueOrInitializerT } from './utils';
-export { default as withGlobalStateType } from './withGlobalStateType';
+import GlobalState from './GlobalState';
+import GlobalStateProvider, { getGlobalState, getSsrContext } from './GlobalStateProvider';
+import SsrContext from './SsrContext';
+import useAsyncCollection, { type UseAsyncCollectionI } from './useAsyncCollection';
+import useAsyncData, { type UseAsyncDataI, newAsyncDataEnvelope } from './useAsyncData';
+import useGlobalState, { type UseGlobalStateI } from './useGlobalState';
+export type { AsyncCollectionLoaderT } from './useAsyncCollection';
+export type { AsyncDataEnvelopeT, AsyncDataLoaderT, UseAsyncDataOptionsT, UseAsyncDataResT, } from './useAsyncData';
+export type { SetterT, UseGlobalStateResT } from './useGlobalState';
+export type { ForceT, ValueOrInitializerT } from './utils';
+export { getGlobalState, getSsrContext, GlobalState, GlobalStateProvider, newAsyncDataEnvelope, SsrContext, useAsyncCollection, useAsyncData, useGlobalState, };
+export interface API<StateT, SsrContextT extends SsrContext<StateT> = SsrContext<StateT>> {
+    getGlobalState: typeof getGlobalState<StateT, SsrContextT>;
+    getSsrContext: typeof getSsrContext<SsrContextT>;
+    GlobalState: typeof GlobalState<StateT, SsrContextT>;
+    GlobalStateProvider: typeof GlobalStateProvider<StateT, SsrContextT>;
+    newAsyncDataEnvelope: typeof newAsyncDataEnvelope;
+    SsrContext: typeof SsrContext<StateT>;
+    useAsyncCollection: UseAsyncCollectionI<StateT>;
+    useAsyncData: UseAsyncDataI<StateT>;
+    useGlobalState: UseGlobalStateI<StateT>;
+}
+declare const _default: API<unknown, SsrContext<unknown>>;
+export default _default;

package/build/types/useAsyncCollection.d.ts

@@ -2,7 +2,7 @@
  * Loads and uses an item in an async collection.
  */
 import { type DataInEnvelopeAtPathT, type UseAsyncDataOptionsT, type UseAsyncDataResT } from './useAsyncData';
-import { type ForceT, type TypeLock } from './utils';
+import { type ForceT, type LockT, type 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
@@ -47,5 +47,9 @@ export type AsyncCollectionLoaderT<DataT> = (id: string, oldData: null | DataT)
  * `useAsyncData()` hooks logic.
  */
 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<Forced extends ForceT | false = false, DataT = unknown>(id: string, path: null | string | undefined, loader: AsyncCollectionLoaderT<TypeLock<Forced, void, DataT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Forced, void, 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>>;
 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>>;
+}

package/build/types/useAsyncData.d.ts

@@ -1,7 +1,7 @@
 /**
  * Loads and uses async data into the GlobalState path.
  */
-import { type ForceT, type TypeLock, type ValueAtPathT } from './utils';
+import { type ForceT, type LockT, type TypeLock, type ValueAtPathT } from './utils';
 export type AsyncDataLoaderT<DataT> = (oldData: null | DataT) => DataT | Promise<DataT>;
 export type AsyncDataEnvelopeT<DataT> = {
     data: null | DataT;
@@ -71,5 +71,9 @@ export type UseAsyncDataResT<DataT> = {
  */
 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<Forced extends ForceT | false = false, DataT = unknown>(path: null | string | undefined, loader: AsyncDataLoaderT<TypeLock<Forced, void, DataT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Forced, void, 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 default useAsyncData;
+export interface UseAsyncDataI<StateT> {
+    <PathT extends null | string | undefined>(path: PathT, loader: AsyncDataLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;
+    <Forced extends ForceT | LockT = LockT, DataT = unknown>(path: null | string | undefined, loader: AsyncDataLoaderT<TypeLock<Forced, void, DataT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;
+}

package/build/types/useGlobalState.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="react" />
-import { type ForceT, type TypeLock, type ValueAtPathT, type ValueOrInitializerT } from './utils';
+import { type ForceT, type LockT, type TypeLock, type ValueAtPathT, type ValueOrInitializerT } from './utils';
 export type SetterT<T> = React.Dispatch<React.SetStateAction<T>>;
 export type UseGlobalStateResT<T> = [T, SetterT<T>];
 /**
@@ -52,7 +52,12 @@ export type UseGlobalStateResT<T> = [T, SetterT<T>];
  *   Also, similar to the standard React's state setters, `setValue()` is
  *   stable function: it does not change between component re-renders.
  */
+declare function useGlobalState<Forced extends ForceT | LockT = LockT, ValueT = void>(path: null | string | undefined, initialValue?: ValueOrInitializerT<TypeLock<Forced, never, ValueT>>): UseGlobalStateResT<TypeLock<Forced, void, ValueT>>;
 declare function useGlobalState<StateT>(): UseGlobalStateResT<StateT>;
-declare function useGlobalState<Forced extends ForceT | false = false, ValueT = unknown>(path: null | string | undefined, initialValue?: ValueOrInitializerT<TypeLock<Forced, never, ValueT>>): UseGlobalStateResT<TypeLock<Forced, void, ValueT>>;
 declare function useGlobalState<StateT, PathT extends null | string | undefined>(path: PathT, initialValue?: ValueOrInitializerT<ValueAtPathT<StateT, PathT, never>>): UseGlobalStateResT<ValueAtPathT<StateT, PathT, void>>;
 export default useGlobalState;
+export interface UseGlobalStateI<StateT> {
+    (): UseGlobalStateResT<StateT>;
+    <PathT extends null | string | undefined>(path: PathT, initialValue?: ValueOrInitializerT<ValueAtPathT<StateT, PathT, never>>): UseGlobalStateResT<ValueAtPathT<StateT, PathT, void>>;
+    <Forced extends ForceT | LockT = LockT, ValueT = unknown>(path: null | string | undefined, initialValue?: ValueOrInitializerT<TypeLock<Forced, never, ValueT>>): UseGlobalStateResT<TypeLock<Forced, void, ValueT>>;
+}

package/build/types/utils.d.ts

@@ -1,8 +1,10 @@
 import { type GetFieldType } from 'lodash';
 export type CallbackT = () => void;
 declare const force: unique symbol;
+declare const lock: unique symbol;
 export type ForceT = typeof force;
-export type TypeLock<Unlocked extends ForceT | false, LockedT extends never | void, UnlockedT> = Unlocked extends ForceT ? UnlockedT : LockedT;
+export type LockT = typeof lock;
+export type TypeLock<Unlocked extends ForceT | LockT, LockedT extends never | void, UnlockedT> = Unlocked extends ForceT ? UnlockedT : LockedT;
 /**
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dr.pogodin/react-global-state",
-  "version": "0.10.0-alpha.3",
+  "version": "0.10.0-alpha.4",
   "description": "Hook-based global state for React",
   "main": "./build/common/index.js",
   "react-native": "src/index.ts",

package/src/GlobalState.ts

@@ -13,6 +13,7 @@ import SsrContext from './SsrContext';
 import {
   type CallbackT,
   type ForceT,
+  type LockT,
   type TypeLock,
   type ValueAtPathT,
   type ValueOrInitializerT,
@@ -162,7 +163,7 @@ export default class GlobalState<
 
   // This variant is not callable by default (without generic arguments),
   // otherwise it allows to set the correct ValueT directly.
-  get<Forced extends ForceT | false = false, ValueT = void>(
+  get<Forced extends ForceT | LockT = LockT, ValueT = void>(
     path?: null | string,
     opts?: GetOptsT<TypeLock<Forced, never, ValueT>>,
   ): TypeLock<Forced, void, ValueT>;
@@ -205,7 +206,7 @@ export default class GlobalState<
 
   // This variant is disabled by default, otherwise allows to give
   // expected value type explicitly.
-  set<Forced extends ForceT | false = false, ValueT = never>(
+  set<Forced extends ForceT | LockT = LockT, ValueT = never>(
     path: null | string | undefined,
     value: TypeLock<Forced, never, ValueT>,
   ): TypeLock<Forced, void, ValueT>;

package/src/index.ts

@@ -1,33 +1,71 @@
-export { default as GlobalState } from './GlobalState';
+import GlobalState from './GlobalState';
 
-export {
-  default as GlobalStateProvider,
+import GlobalStateProvider, {
   getGlobalState,
   getSsrContext,
 } from './GlobalStateProvider';
 
-export { default as SsrContext } from './SsrContext';
+import SsrContext from './SsrContext';
 
-export {
-  type AsyncCollectionLoaderT,
-  default as useAsyncCollection,
+import useAsyncCollection, {
+  type UseAsyncCollectionI,
 } from './useAsyncCollection';
 
-export {
-  type AsyncDataEnvelopeT,
-  type AsyncDataLoaderT,
-  type UseAsyncDataOptionsT,
-  type UseAsyncDataResT,
-  default as useAsyncData,
+import useAsyncData, {
+  type UseAsyncDataI,
   newAsyncDataEnvelope,
 } from './useAsyncData';
 
+import useGlobalState, { type UseGlobalStateI } from './useGlobalState';
+
+export type { AsyncCollectionLoaderT } from './useAsyncCollection';
+
+export type {
+  AsyncDataEnvelopeT,
+  AsyncDataLoaderT,
+  UseAsyncDataOptionsT,
+  UseAsyncDataResT,
+} from './useAsyncData';
+
+export type { SetterT, UseGlobalStateResT } from './useGlobalState';
+
+export type { ForceT, ValueOrInitializerT } from './utils';
+
 export {
-  type SetterT,
-  type UseGlobalStateResT,
-  default as useGlobalState,
-} from './useGlobalState';
+  getGlobalState,
+  getSsrContext,
+  GlobalState,
+  GlobalStateProvider,
+  newAsyncDataEnvelope,
+  SsrContext,
+  useAsyncCollection,
+  useAsyncData,
+  useGlobalState,
+};
 
-export { type ForceT, type ValueOrInitializerT } from './utils';
+export interface API<
+  StateT,
+  SsrContextT extends SsrContext<StateT> = SsrContext<StateT>,
+> {
+  getGlobalState: typeof getGlobalState<StateT, SsrContextT>;
+  getSsrContext: typeof getSsrContext<SsrContextT>,
+  GlobalState: typeof GlobalState<StateT, SsrContextT>,
+  GlobalStateProvider: typeof GlobalStateProvider<StateT, SsrContextT>,
+  newAsyncDataEnvelope: typeof newAsyncDataEnvelope,
+  SsrContext: typeof SsrContext<StateT>,
+  useAsyncCollection: UseAsyncCollectionI<StateT>,
+  useAsyncData: UseAsyncDataI<StateT>,
+  useGlobalState: UseGlobalStateI<StateT>,
+}
 
-export { default as withGlobalStateType } from './withGlobalStateType';
+export default {
+  getGlobalState,
+  getSsrContext,
+  GlobalState,
+  GlobalStateProvider,
+  newAsyncDataEnvelope,
+  SsrContext,
+  useAsyncCollection,
+  useAsyncData,
+  useGlobalState,
+} as API<unknown>;

package/src/useAsyncCollection.ts

@@ -8,7 +8,7 @@ import useAsyncData, {
   type UseAsyncDataResT,
 } from './useAsyncData';
 
-import { type ForceT, type TypeLock } from './utils';
+import { type ForceT, type LockT, type TypeLock } from './utils';
 
 export type AsyncCollectionLoaderT<DataT> =
   (id: string, oldData: null | DataT) => DataT | Promise<DataT>;
@@ -70,7 +70,7 @@ function useAsyncCollection<
 ): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`>>;
 
 function useAsyncCollection<
-  Forced extends ForceT | false = false,
+  Forced extends ForceT | LockT = LockT,
   DataT = unknown,
 >(
   id: string,
@@ -94,3 +94,19 @@ function useAsyncCollection<DataT>(
 }
 
 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>>;
+}

package/src/useAsyncData.ts

@@ -13,6 +13,7 @@ import useGlobalState from './useGlobalState';
 
 import {
   type ForceT,
+  type LockT,
   type TypeLock,
   type ValueAtPathT,
   isDebugMode,
@@ -181,8 +182,8 @@ function useAsyncData<
 ): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;
 
 function useAsyncData<
-  Forced extends ForceT | false = false,
-  DataT = unknown,
+  Forced extends ForceT | LockT = LockT,
+  DataT = void,
 >(
   path: null | string | undefined,
   loader: AsyncDataLoaderT<TypeLock<Forced, void, DataT>>,
@@ -293,3 +294,17 @@ function useAsyncData<DataT>(
 }
 
 export default useAsyncData;
+
+export interface UseAsyncDataI<StateT> {
+  <PathT extends null | string | undefined>(
+    path: PathT,
+    loader: AsyncDataLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>,
+    options?: UseAsyncDataOptionsT,
+  ): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;
+
+  <Forced extends ForceT | LockT = LockT, DataT = unknown>(
+    path: null | string | undefined,
+    loader: AsyncDataLoaderT<TypeLock<Forced, void, DataT>>,
+    options?: UseAsyncDataOptionsT,
+  ): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;
+}

package/src/useGlobalState.ts

@@ -11,6 +11,7 @@ import { getGlobalState } from './GlobalStateProvider';
 import {
   type CallbackT,
   type ForceT,
+  type LockT,
   type TypeLock,
   type ValueAtPathT,
   type ValueOrInitializerT,
@@ -81,13 +82,19 @@ export type UseGlobalStateResT<T> = [T, SetterT<T>];
  *   stable function: it does not change between component re-renders.
  */
 
-function useGlobalState<StateT>(): UseGlobalStateResT<StateT>;
-
-function useGlobalState<Forced extends ForceT | false = false, ValueT = unknown>(
+// "Enforced type overload"
+function useGlobalState<
+  Forced extends ForceT | LockT = LockT,
+  ValueT = void,
+>(
   path: null | string | undefined,
   initialValue?: ValueOrInitializerT<TypeLock<Forced, never, ValueT>>,
 ): UseGlobalStateResT<TypeLock<Forced, void, ValueT>>;
 
+// "Entire state overload"
+function useGlobalState<StateT>(): UseGlobalStateResT<StateT>;
+
+// "State evaluation overload"
 function useGlobalState<
   StateT,
   PathT extends null | string | undefined,
@@ -154,3 +161,17 @@ function useGlobalState(
 }
 
 export default useGlobalState;
+
+export interface UseGlobalStateI<StateT> {
+  (): UseGlobalStateResT<StateT>;
+
+  <PathT extends null | string | undefined>(
+    path: PathT,
+    initialValue?: ValueOrInitializerT<ValueAtPathT<StateT, PathT, never>>
+  ): UseGlobalStateResT<ValueAtPathT<StateT, PathT, void>>;
+
+  <Forced extends ForceT | LockT = LockT, ValueT = unknown>(
+    path: null | string | undefined,
+    initialValue?: ValueOrInitializerT<TypeLock<Forced, never, ValueT>>,
+  ): UseGlobalStateResT<TypeLock<Forced, void, ValueT>>;
+}

package/src/utils.ts

@@ -2,14 +2,17 @@ import { type GetFieldType } from 'lodash';
 
 export type CallbackT = () => void;
 
-// TODO: This (ForceT & TypeLock) probably should be moved to JS Utils lib.
+// TODO: This (ForceT, LockT, and TypeLock) probably should be moved to JS Utils
+// lib.
 
-// This type is used to "unlocked" special generic overrides around the library.
 declare const force: unique symbol;
+declare const lock: unique symbol;
+
 export type ForceT = typeof force;
+export type LockT = typeof lock;
 
 export type TypeLock<
-  Unlocked extends ForceT | false,
+  Unlocked extends ForceT | LockT,
   LockedT extends never | void,
   UnlockedT,
 > = Unlocked extends ForceT ? UnlockedT : LockedT;

package/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "@tsconfig/recommended",
+  "extends": "./node_modules/@tsconfig/recommended/tsconfig.json",
   "compilerOptions": {
     "declaration": true,
     "jsx": "react-jsx",