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

package/src/index.ts

@@ -0,0 +1,33 @@
+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/node/useAsyncCollection.js → src/useAsyncCollection.ts}

@@ -1,49 +1,48 @@
-"use strict";
-
-var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = useAsyncCollection;
-var _useAsyncData = _interopRequireDefault(require("./useAsyncData"));
 /**
  * Loads and uses an item in an async collection.
  */
 
+import useAsyncData, {
+  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)
@@ -56,8 +55,42 @@ var _useAsyncData = _interopRequireDefault(require("./useAsyncData"));
  * _e.g._ {@link useGlobalState}, but doing so you may interfere with related
  * `useAsyncData()` hooks logic.
  */
-function useAsyncCollection(id, path, loader, options = {}) {
+
+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}`>>;
+
+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>>;
+
+function useAsyncCollection<DataT>(
+  id: string,
+  path: null | string | undefined,
+  loader: AsyncCollectionLoaderT<DataT>,
+  options: UseAsyncDataOptionsT = {},
+): UseAsyncDataResT<DataT> {
   const itemPath = path ? `${path}.${id}` : id;
-  return (0, _useAsyncData.default)(itemPath, oldData => loader(id, oldData), options);
+  return useAsyncData<1, DataT>(
+    itemPath,
+    (oldData: null | DataT) => loader(id, oldData),
+    options,
+  );
 }
-//# sourceMappingURL=useAsyncCollection.js.map
+
+export default useAsyncCollection;

package/src/useAsyncData.ts

@@ -0,0 +1,287 @@
+/**
+ * Loads and uses async data into the GlobalState path.
+ */
+
+import { cloneDeep } from 'lodash';
+import { useEffect } from 'react';
+import { v4 as uuid } from 'uuid';
+
+import { MIN_MS } from '@dr.pogodin/js-utils';
+
+import { getGlobalState } from './GlobalStateProvider';
+import useGlobalState from './useGlobalState';
+import { TypeLock, isDebugMode } from './utils';
+
+import GlobalState from './GlobalState';
+
+import { type ValueAtPathT } from './utils';
+
+const DEFAULT_MAXAGE = 5 * MIN_MS; // 5 minutes.
+
+export type AsyncDataLoaderT<DataT>
+= (oldData: null | DataT) => DataT | Promise<DataT>;
+
+export type AsyncDataEnvelopeT<DataT> = {
+  data: null | DataT;
+  numRefs: number;
+  operationId: string;
+  timestamp: number;
+};
+
+export function newAsyncDataEnvelope<DataT>(
+  initialData: DataT | null = null,
+): AsyncDataEnvelopeT<DataT> {
+  return {
+    data: initialData,
+    numRefs: 0,
+    operationId: '',
+    timestamp: 0,
+  };
+}
+
+export type UseAsyncDataOptionsT = {
+  deps?: unknown[];
+  garbageCollectAge?: number;
+  maxage?: number;
+  noSSR?: boolean;
+  refreshAge?: number;
+};
+
+export type UseAsyncDataResT<DataT> = {
+  data: DataT | null;
+  loading: boolean;
+  timestamp: number;
+};
+
+/**
+ * Executes the data loading operation.
+ * @param path Data segment path inside the global state.
+ * @param loader Data loader.
+ * @param globalState The global state instance.
+ * @param oldData Optional. Previously fetched data, currently stored in
+ *  the state, if already fetched by the caller; otherwise, they will be fetched
+ *  by the load() function itself.
+ * @param opIdPrefix operationId prefix to use, which should be
+ * 'C' at the client-side (default), or 'S' at the server-side (within SSR
+ * context).
+ * @return Resolves once the operation is done.
+ * @ignore
+ */
+async function load<DataT>(
+  path: null | string | undefined,
+  loader: AsyncDataLoaderT<DataT>,
+  globalState: GlobalState<unknown>,
+  oldData: DataT | null,
+  opIdPrefix: 'C' | 'S' = 'C',
+): Promise<void> {
+  if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
+    /* eslint-disable no-console */
+    console.log(
+      `ReactGlobalState: useAsyncData data (re-)loading. Path: "${path || ''}"`,
+    );
+    /* eslint-enable no-console */
+  }
+  const operationId = opIdPrefix + uuid();
+  const operationIdPath = path ? `${path}.operationId` : 'operationId';
+  globalState.set<1, string>(operationIdPath, operationId);
+  const data = await loader(
+    oldData || (globalState.get<1, AsyncDataEnvelopeT<DataT>>(path)).data,
+  );
+  const state: AsyncDataEnvelopeT<DataT> = globalState.get<1, AsyncDataEnvelopeT<DataT>>(path);
+  if (operationId === state.operationId) {
+    if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
+      /* eslint-disable no-console */
+      console.groupCollapsed(
+        `ReactGlobalState: useAsyncData data (re-)loaded. Path: "${
+          path || ''
+        }"`,
+      );
+      console.log('Data:', cloneDeep(data));
+      /* eslint-enable no-console */
+    }
+    globalState.set<1, AsyncDataEnvelopeT<DataT>>(path, {
+      ...state,
+      data,
+      operationId: '',
+      timestamp: Date.now(),
+    });
+    if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
+      /* eslint-disable no-console */
+      console.groupEnd();
+      /* eslint-enable no-console */
+    }
+  }
+}
+
+/**
+ * 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;
+
+function useAsyncData<
+  StateT,
+  PathT extends null | string | undefined,
+>(
+  path: PathT,
+  loader: AsyncDataLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>,
+  options?: UseAsyncDataOptionsT,
+): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;
+
+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>>;
+
+function useAsyncData<DataT>(
+  path: null | string | undefined,
+  loader: AsyncDataLoaderT<DataT>,
+  options: UseAsyncDataOptionsT = {},
+): UseAsyncDataResT<DataT> {
+  const maxage: number = options.maxage === undefined
+    ? DEFAULT_MAXAGE : options.maxage;
+
+  const refreshAge: number = options.refreshAge === undefined
+    ? maxage : options.refreshAge;
+
+  const garbageCollectAge: number = 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 = getGlobalState();
+  const state = globalState.get<1, AsyncDataEnvelopeT<DataT>>(path, {
+    initialValue: newAsyncDataEnvelope<DataT>(),
+  });
+
+  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.
+    useEffect(() => { // eslint-disable-line react-hooks/rules-of-hooks
+      const numRefsPath = path ? `${path}.numRefs` : 'numRefs';
+      const numRefs = globalState.get<1, number>(numRefsPath);
+      globalState.set<1, number>(numRefsPath, numRefs + 1);
+      return () => {
+        const state2: AsyncDataEnvelopeT<DataT> = globalState.get<1, AsyncDataEnvelopeT<DataT>>(
+          path,
+        );
+        if (
+          state2.numRefs === 1
+          && garbageCollectAge < Date.now() - state2.timestamp
+        ) {
+          if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
+            /* eslint-disable no-console */
+            console.log(
+              `ReactGlobalState - useAsyncData garbage collected at path ${
+                path || ''
+              }`,
+            );
+            /* eslint-enable no-console */
+          }
+          globalState.set<1, AsyncDataEnvelopeT<DataT>>(path, {
+            ...state2,
+            data: null,
+            numRefs: 0,
+            timestamp: 0,
+          });
+        } else globalState.set<1, number>(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;
+    useEffect(() => { // eslint-disable-line react-hooks/rules-of-hooks
+      const state2: AsyncDataEnvelopeT<DataT> = globalState.get<1, AsyncDataEnvelopeT<DataT>>(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 || [];
+    useEffect(() => { // eslint-disable-line react-hooks/rules-of-hooks
+      if (!loadTriggered && deps.length) load(path, loader, globalState, null);
+    }, deps); // eslint-disable-line react-hooks/exhaustive-deps
+  }
+
+  const [localState] = useGlobalState<1, AsyncDataEnvelopeT<DataT>>(
+    path,
+    newAsyncDataEnvelope<DataT>(),
+  );
+
+  return {
+    data: maxage < Date.now() - localState.timestamp ? null : localState.data,
+    loading: Boolean(localState.operationId),
+    timestamp: localState.timestamp,
+  };
+}
+
+export default useAsyncData;

package/src/useGlobalState.ts

@@ -0,0 +1,158 @@
+// Hook for updates of global state.
+
+import { cloneDeep, isFunction } from 'lodash';
+import { useEffect, useRef, useSyncExternalStore } from 'react';
+
+import { Emitter } from '@dr.pogodin/js-utils';
+
+import GlobalState from './GlobalState';
+import { getGlobalState } from './GlobalStateProvider';
+
+import {
+  type CallbackT,
+  type TypeLock,
+  type ValueAtPathT,
+  type ValueOrInitializerT,
+  isDebugMode,
+} from './utils';
+
+export type SetterT<T> = React.Dispatch<React.SetStateAction<T>>;
+
+type GlobalStateRef = {
+  emitter: Emitter<[]>;
+  globalState: GlobalState<unknown>;
+  path: null | string | undefined;
+  setter: SetterT<unknown>;
+  state: unknown;
+  watcher: CallbackT;
+};
+
+export type UseGlobalStateResT<T> = [T, SetterT<T>];
+
+/**
+ * The primary hook for interacting with the global state, modeled after
+ * the standard React's
+ * [useState](https://reactjs.org/docs/hooks-reference.html#usestate).
+ * It subscribes a component to a given `path` of global state, and provides
+ * a function to update it. Each time the value at `path` changes, the hook
+ * triggers re-render of its host component.
+ *
+ * **Note:**
+ * - For performance, the library does not copy objects written to / read from
+ *   global state paths. You MUST NOT manually mutate returned state values,
+ *   or change objects already written into the global state, without explicitly
+ *   clonning them first yourself.
+ * - State update notifications are asynchronous. When your code does multiple
+ *   global state updates in the same React rendering cycle, all state update
+ *   notifications are queued and dispatched together, after the current
+ *   rendering cycle. In other words, in any given rendering cycle the global
+ *   state values are "fixed", and all changes becomes visible at once in the
+ *   next triggered rendering pass.
+ *
+ * @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 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):
+ *   only if the value at `path` is `undefined`, the function will be executed,
+ *   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 It returs an array with two elements: `[value, setValue]`:
+ *
+ * - The `value` is the current value at given `path`.
+ *
+ * - The `setValue()` is setter function to write a new value to the `path`.
+ *
+ *   Similar to the standard React's `useState()`, it supports
+ *   [functional value updates](https://reactjs.org/docs/hooks-reference.html#functional-updates):
+ *   if `setValue()` is called with a function as argument, that function will
+ *   be called and its return value will be written to `path`. Otherwise,
+ *   the argument of `setValue()` itself is written to `path`.
+ *
+ *   Also, similar to the standard React's state setters, `setValue()` is
+ *   stable function: it does not change between component re-renders.
+ */
+
+function useGlobalState<StateT>(): UseGlobalStateResT<StateT>;
+
+function useGlobalState<
+  StateT,
+  PathT extends null | string | undefined,
+>(
+  path: PathT,
+  initialValue?: ValueOrInitializerT<ValueAtPathT<StateT, PathT, never>>
+): UseGlobalStateResT<ValueAtPathT<StateT, PathT, void>>;
+
+function useGlobalState<
+  Unlocked extends 0 | 1 = 0,
+  ValueT = void,
+>(
+  path: null | string | undefined,
+  initialValue?: ValueOrInitializerT<TypeLock<Unlocked, never, ValueT>>,
+): UseGlobalStateResT<TypeLock<Unlocked, void, ValueT>>;
+
+function useGlobalState(
+  path?: null | string,
+  initialValue?: ValueOrInitializerT<unknown>,
+): UseGlobalStateResT<any> {
+  const globalState = getGlobalState();
+
+  const ref = useRef<GlobalStateRef>();
+  const rc: GlobalStateRef = ref.current || {
+    emitter: new Emitter(),
+    globalState,
+    path,
+    setter: (value) => {
+      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<1, unknown>(rc.path, newState);
+    },
+    state: 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 = useSyncExternalStore(
+    (cb) => rc.emitter.addListener(cb),
+    () => rc.globalState.get<1, unknown>(rc.path, { initialValue }),
+    () => rc.globalState.get<1, unknown>(rc.path, { initialValue, initialState: true }),
+  );
+
+  useEffect(() => {
+    const { watcher } = ref.current!;
+    globalState.watch(watcher);
+    watcher();
+    return () => globalState.unWatch(watcher);
+  }, [globalState]);
+
+  useEffect(() => {
+    ref.current!.watcher();
+  }, [path]);
+
+  return [rc.state, rc.setter];
+}
+
+export default useGlobalState;

package/src/utils.ts

@@ -0,0 +1,59 @@
+import { type GetFieldType } from 'lodash';
+
+export type CallbackT = () => void;
+
+// TODO: This probably should be moved to JS Utils lib.
+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 function isDebugMode(): boolean {
+  try {
+    return process.env.NODE_ENV !== 'production'
+      && !!process.env.REACT_GLOBAL_STATE_DEBUG;
+  } catch (error) {
+    return false;
+  }
+}