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

package/build/types/useAsyncCollection.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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';
+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 id ID of the collection item to load & use.
+ * @param path The global state path where entire collection should be
+ *  stored.
+ * @param loader A loader function, which takes an
+ * ID of data to load, and resolves to the corresponding data.
+ * @param options Additional options.
+ * @param options.deps An array of dependencies, which trigger
+ * data reload when changed. Given dependency changes are watched shallowly
+ * (similarly to the standard React's
+ * [useEffect()](https://reactjs.org/docs/hooks-reference.html#useeffect)).
+ * @param options.noSSR If `true`, this hook won't load data during
+ * server-side rendering.
+ * @param options.garbageCollectAge The maximum age of data
+ * (in milliseconds), after which they are dropped from the state when the last
+ * component referencing them via `useAsyncData()` hook unmounts. Defaults to
+ * `maxage` option value.
+ * @param options.maxage The maximum age of
+ * data (in milliseconds) acceptable to the hook's caller. If loaded data are
+ * older than this value, `null` is returned instead. Defaults to 5 minutes.
+ * @param options.refreshAge The maximum age of data
+ * (in milliseconds), after which their refreshment will be triggered when
+ * any component referencing them via `useAsyncData()` hook (re-)renders.
+ * Defaults to `maxage` value.
+ * @return Returns an object with three fields: `data` holds the actual result of
+ * last `loader` invokation, if any, and if satisfies `maxage` limit; `loading`
+ * is a boolean flag, which is `true` if data are being loaded (the hook is
+ * waiting for `loader` function resolution); `timestamp` (in milliseconds)
+ * is Unix timestamp of related data currently loaded into the global state.
+ *
+ * Note that loaded data, if any, are stored at the given `path` of global state
+ * along with related meta-information, using slightly different state segment
+ * structure (see {@link AsyncDataEnvelope}). That segment of the global state
+ * can be accessed, and even modified using other hooks,
+ * _e.g._ {@link useGlobalState}, but doing so you may interfere with related
+ * `useAsyncData()` hooks logic.
+ */
+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>>;
+export default useAsyncCollection;

package/build/types/useAsyncData.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Loads and uses async data into the GlobalState path.
+ */
+import { type ForceT, type TypeLock, 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<Forced extends ForceT | false = false, DataT = unknown>(path: null | string | undefined, loader: AsyncDataLoaderT<TypeLock<Forced, void, DataT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;
+export default useAsyncData;

package/build/types/useGlobalState.d.ts

@@ -0,0 +1,58 @@
+/// <reference types="react" />
+import { type ForceT, 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
+ * [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.
+ */
+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;

package/build/types/utils.d.ts

@@ -0,0 +1,34 @@
+import { type GetFieldType } from 'lodash';
+export type CallbackT = () => void;
+declare const force: unique symbol;
+export type ForceT = typeof force;
+export type TypeLock<Unlocked extends ForceT | false, 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
+ * 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;
+export {};

package/build/types/withGlobalStateType.d.ts

@@ -0,0 +1,29 @@
+import { type ForceT, type TypeLock, type ValueAtPathT, type ValueOrInitializerT } from './utils';
+import GlobalStateProvider, { getGlobalState, getSsrContext } from './GlobalStateProvider';
+import SsrContext from './SsrContext';
+import { type UseGlobalStateResT } from './useGlobalState';
+import { type AsyncCollectionLoaderT } from './useAsyncCollection';
+import { type AsyncDataLoaderT, type DataInEnvelopeAtPathT, type UseAsyncDataOptionsT, type UseAsyncDataResT } from './useAsyncData';
+interface NarrowedUseGlobalStateI<StateT> {
+    (): UseGlobalStateResT<StateT>;
+    <PathT extends null | string | undefined>(path: PathT, initialValue?: ValueOrInitializerT<ValueAtPathT<StateT, PathT, never>>): UseGlobalStateResT<ValueAtPathT<StateT, PathT, void>>;
+    <Forced extends ForceT | false = false, ValueT = unknown>(path: null | string | undefined, initialValue?: ValueOrInitializerT<TypeLock<Forced, never, ValueT>>): UseGlobalStateResT<TypeLock<Forced, void, ValueT>>;
+}
+interface NarrowedUseAsyncDataI<StateT> {
+    <PathT extends null | string | undefined>(path: PathT, loader: AsyncDataLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;
+    <Forced extends ForceT | false = false, DataT = unknown>(path: null | string | undefined, loader: AsyncDataLoaderT<TypeLock<Forced, void, DataT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Forced, never, DataT>>;
+}
+interface NarrowedUseAsyncCollectionI<StateT> {
+    <PathT extends null | string | undefined>(id: string, path: PathT, loader: AsyncCollectionLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;
+    <Forced extends ForceT | false = false, DataT = unknown>(id: string, path: null | string | undefined, loader: AsyncCollectionLoaderT<TypeLock<Forced, void, DataT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataT>;
+}
+type WithGlobalStateTypeResT<StateT, SsrContextT extends SsrContext<StateT> = SsrContext<StateT>> = {
+    getGlobalState: typeof getGlobalState<StateT, SsrContextT>;
+    getSsrContext: typeof getSsrContext<SsrContextT>;
+    GlobalStateProvider: typeof GlobalStateProvider<StateT, SsrContextT>;
+    useAsyncCollection: NarrowedUseAsyncCollectionI<StateT>;
+    useAsyncData: NarrowedUseAsyncDataI<StateT>;
+    useGlobalState: NarrowedUseGlobalStateI<StateT>;
+};
+export default function withGlobalStateType<StateT, SsrContextT extends SsrContext<StateT> = SsrContext<StateT>>(): WithGlobalStateTypeResT<StateT, SsrContextT>;
+export {};

package/package.json

@@ -1,26 +1,27 @@
 {
   "name": "@dr.pogodin/react-global-state",
-  "version": "0.10.0-alpha.1",
+  "version": "0.10.0-alpha.3",
   "description": "Hook-based global state for React",
-  "main": "./build/node/index.js",
+  "main": "./build/common/index.js",
   "react-native": "src/index.ts",
   "source": "src/index.ts",
+  "types": "./build/types/index.d.ts",
   "exports": {
     "module": "./build/module/index.js",
-    "node": "./build/node/index.js",
-    "types": "./index.d.ts",
-    "default": "./build/node/index.js"
+    "node": "./build/common/index.js",
+    "default": "./build/common/index.js"
   },
   "scripts": {
-    "build": "rimraf build && npm run build:module && npm run build:node",
-    "build:module": "rimraf build/web && babel src --out-dir build/module --source-maps --config-file ./babel.module.config.js",
-    "build:node": "rimraf build/node && babel src --out-dir build/node --source-maps",
+    "build": "rimraf build && npm run build:types && npm run build:common && npm run build:module",
+    "build:common": "rimraf build/common && babel src -x .ts,.tsx --out-dir build/common --source-maps",
+    "build:module": "rimraf build/module && babel src -x .ts,.tsx --out-dir build/module --source-maps --config-file ./babel.module.config.js",
+    "build:types": "rimraf build/types && tsc --project tsconfig.types.json",
     "jest": "npm run jest:types && npm run jest:logic",
-    "jest:types": "jest --config jest/config-types.json",
     "jest:logic": "jest --config jest/config.json -w 1",
+    "jest:types": "jest --config jest/config-types.json",
     "lint": "eslint --ext .js,.jsx,.ts,.tsx .",
     "test": "npm run lint && npm run typecheck && npm run jest",
-    "typecheck": "tsc --noEmit && tsc --project __tests__/tsconfig.typecheck.json"
+    "typecheck": "tsc --project __tests__/tsconfig.json"
   },
   "repository": "github:birdofpreyru/react-global-state",
   "keywords": [
@@ -39,53 +40,53 @@
   },
   "homepage": "https://dr.pogodin.studio/docs/react-global-state/index.html",
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "dependencies": {
-    "@babel/runtime": "^7.22.6",
+    "@babel/runtime": "^7.23.2",
     "@dr.pogodin/js-utils": "^0.0.6",
     "lodash": "^4.17.21",
-    "uuid": "^9.0.0"
+    "uuid": "^9.0.1"
   },
   "devDependencies": {
-    "@babel/cli": "^7.22.6",
-    "@babel/core": "^7.22.8",
-    "@babel/eslint-parser": "^7.22.7",
-    "@babel/eslint-plugin": "^7.22.5",
-    "@babel/node": "^7.22.6",
-    "@babel/plugin-transform-runtime": "^7.22.7",
-    "@babel/preset-env": "^7.22.7",
-    "@babel/preset-react": "^7.22.5",
-    "@babel/preset-typescript": "^7.22.5",
-    "@tsconfig/recommended": "^1.0.2",
-    "@tsd/typescript": "^5.1.6",
-    "@types/jest": "^29.5.3",
-    "@types/lodash": "^4.14.195",
-    "@types/pretty": "^2.0.1",
-    "@types/react": "^18.2.14",
-    "@types/react-dom": "^18.2.6",
-    "@types/uuid": "^9.0.2",
-    "@typescript-eslint/eslint-plugin": "^5.61.0",
-    "@typescript-eslint/parser": "^5.61.0",
-    "babel-jest": "^29.6.1",
+    "@babel/cli": "^7.23.0",
+    "@babel/core": "^7.23.2",
+    "@babel/eslint-parser": "^7.22.15",
+    "@babel/eslint-plugin": "^7.22.10",
+    "@babel/node": "^7.22.19",
+    "@babel/plugin-transform-runtime": "^7.23.2",
+    "@babel/preset-env": "^7.23.2",
+    "@babel/preset-react": "^7.22.15",
+    "@babel/preset-typescript": "^7.23.2",
+    "@tsconfig/recommended": "^1.0.3",
+    "@tsd/typescript": "^5.2.2",
+    "@types/jest": "^29.5.6",
+    "@types/lodash": "^4.14.200",
+    "@types/pretty": "^2.0.2",
+    "@types/react": "^18.2.31",
+    "@types/react-dom": "^18.2.14",
+    "@types/uuid": "^9.0.6",
+    "@typescript-eslint/eslint-plugin": "^6.8.0",
+    "@typescript-eslint/parser": "^6.8.0",
+    "babel-jest": "^29.7.0",
     "babel-plugin-module-resolver": "^5.0.0",
-    "eslint": "^8.44.0",
+    "eslint": "^8.52.0",
     "eslint-config-airbnb": "^19.0.4",
-    "eslint-config-airbnb-typescript": "^17.0.0",
+    "eslint-config-airbnb-typescript": "^17.1.0",
     "eslint-import-resolver-babel-module": "^5.3.2",
-    "eslint-plugin-import": "^2.27.5",
-    "eslint-plugin-jest": "^27.2.2",
+    "eslint-plugin-import": "^2.28.1",
+    "eslint-plugin-jest": "^27.4.3",
     "eslint-plugin-jsx-a11y": "^6.7.1",
-    "eslint-plugin-react": "^7.32.2",
+    "eslint-plugin-react": "^7.33.2",
     "eslint-plugin-react-hooks": "^4.6.0",
-    "jest": "^29.6.1",
-    "jest-environment-jsdom": "^29.6.1",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
     "jest-runner-tsd": "^6.0.0",
     "mockdate": "^3.0.5",
     "pretty": "^2.0.0",
     "rimraf": "^5.0.1",
     "tsd-lite": "^0.8.0",
-    "typescript": "^5.1.6"
+    "typescript": "^5.2.2"
   },
   "peerDependencies": {
     "react": "^18.2.0",

package/src/GlobalState.ts

@@ -0,0 +1,283 @@
+import {
+  cloneDeep,
+  get,
+  isFunction,
+  isObject,
+  isNil,
+  set,
+  toPath,
+} from 'lodash';
+
+import SsrContext from './SsrContext';
+
+import {
+  type CallbackT,
+  type ForceT,
+  type TypeLock,
+  type ValueAtPathT,
+  type ValueOrInitializerT,
+  isDebugMode,
+} from './utils';
+
+const ERR_NO_SSR_WATCH = 'GlobalState must not be watched at server side';
+
+type GetOptsT<T> = {
+  initialState?: boolean;
+  initialValue?: ValueOrInitializerT<T>;
+};
+
+export default class GlobalState<
+  StateT,
+  SsrContextT extends SsrContext<StateT> = SsrContext<StateT>,
+> {
+  readonly ssrContext?: SsrContextT;
+
+  #initialState: StateT;
+
+  // TODO: It is tempting to replace watchers here by
+  // Emitter from @dr.pogodin/js-utils, but we need to clone
+  // current watchers for emitting later, and this is not something
+  // Emitter supports right now.
+  #watchers: CallbackT[] = [];
+
+  #nextNotifierId?: NodeJS.Timeout;
+
+  #currentState: StateT;
+
+  /**
+   * Creates a new global state object.
+   * @param initialState Intial global state content.
+   * @param ssrContext Server-side rendering context.
+   */
+  constructor(
+    initialState: StateT,
+    ssrContext?: SsrContextT,
+  ) {
+    this.#currentState = initialState;
+    this.#initialState = initialState;
+
+    if (ssrContext) {
+      /* eslint-disable no-param-reassign */
+      ssrContext.dirty = false;
+      ssrContext.pending = [];
+      ssrContext.state = this.#currentState;
+      /* eslint-enable no-param-reassign */
+
+      this.ssrContext = ssrContext;
+    }
+
+    if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
+      /* eslint-disable no-console */
+      let msg = 'New ReactGlobalState created';
+      if (ssrContext) msg += ' (SSR mode)';
+      console.groupCollapsed(msg);
+      console.log('Initial state:', cloneDeep(initialState));
+      console.groupEnd();
+      /* eslint-enable no-console */
+    }
+  }
+
+  /**
+   * Gets entire state, the same way as .get(null, opts) would do.
+   * @param opts.initialState
+   * @param opts.initialValue
+   */
+  getEntireState(opts?: GetOptsT<StateT>): StateT {
+    let state = opts?.initialState ? this.#initialState : this.#currentState;
+    if (state !== undefined || opts?.initialValue === undefined) return state;
+
+    const iv = opts.initialValue;
+    state = isFunction(iv) ? iv() : iv;
+    if (this.#currentState === undefined) this.setEntireState(state);
+    return state;
+  }
+
+  /**
+   * Notifies all connected state watchers that a state update has happened.
+   */
+  private notifyStateUpdate(path: null | string | undefined, value: unknown) {
+    if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
+      /* eslint-disable no-console */
+      const p = typeof path === 'string'
+        ? `"${path}"` : 'none (entire state update)';
+      console.groupCollapsed(`ReactGlobalState update. Path: ${p}`);
+      console.log('New value:', cloneDeep(value));
+      console.log('New state:', cloneDeep(this.#currentState));
+      console.groupEnd();
+      /* eslint-enable no-console */
+    }
+
+    if (this.ssrContext) {
+      this.ssrContext.dirty = true;
+      this.ssrContext.state = this.#currentState;
+    } else if (!this.#nextNotifierId) {
+      this.#nextNotifierId = setTimeout(() => {
+        this.#nextNotifierId = undefined;
+        const watchers = [...this.#watchers];
+        for (let i = 0; i < watchers.length; ++i) {
+          watchers[i]();
+        }
+      });
+    }
+  }
+
+  /**
+   * Sets entire state, the same way as .set(null, value) would do.
+   * @param value
+   */
+  setEntireState(value: StateT): StateT {
+    if (this.#currentState !== value) {
+      this.#currentState = value;
+      this.notifyStateUpdate(null, value);
+    }
+    return value;
+  }
+
+  /**
+   * Gets current or initial value at the specified "path" of the global state.
+   * @param path Dot-delimitered state path.
+   * @param options Additional options.
+   * @param options.initialState If "true" the value will be read
+   *  from the initial state instead of the current one.
+   * @param options.initialValue If the value read from the "path" is
+   *  "undefined", this "initialValue" will be returned instead. In such case
+   *  "initialValue" will also be written to the "path" of the current global
+   *  state (no matter "initialState" flag), if "undefined" is stored there.
+   * @return Retrieved value.
+   */
+
+  // .get() without arguments just falls back to .getEntireState().
+  get(): StateT;
+
+  // This variant attempts to automatically resolve and check the type of value
+  // at the given path, as precise as the actual state and path types permit.
+  // If the automatic path resolution is not possible, the ValueT fallsback
+  // to `never` (or to `undefined` in some cases), effectively forbidding
+  // to use this .get() variant.
+  get<
+    PathT extends null | string | undefined,
+    ValueArgT extends ValueAtPathT<StateT, PathT, never>,
+    ValueResT extends ValueAtPathT<StateT, PathT, void>,
+  >(path: PathT, opts?: GetOptsT<ValueArgT>): ValueResT;
+
+  // 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>(
+    path?: null | string,
+    opts?: GetOptsT<TypeLock<Forced, never, ValueT>>,
+  ): TypeLock<Forced, void, ValueT>;
+
+  get<ValueT>(path?: null | string, opts?: GetOptsT<ValueT>): ValueT {
+    if (isNil(path)) {
+      const res = this.getEntireState((opts as unknown) as GetOptsT<StateT>);
+      return (res as unknown) as ValueT;
+    }
+
+    const state = opts?.initialState ? this.#initialState : this.#currentState;
+
+    let res = get(state, path);
+    if (res !== undefined || opts?.initialValue === undefined) return res;
+
+    const iv = opts.initialValue;
+    res = isFunction(iv) ? iv() : iv;
+
+    if (!opts?.initialState || this.get(path) === undefined) {
+      this.set<ForceT, unknown>(path, res);
+    }
+
+    return res;
+  }
+
+  /**
+   * Writes the `value` to given global state `path`.
+   * @param path Dot-delimitered state path. If not given, entire
+   * global state content is replaced by the `value`.
+   * @param value The value.
+   * @return Given `value` itself.
+   */
+
+  // This variant attempts automatic value type resolution & checking.
+  set<
+    PathT extends null | string | undefined,
+    ValueArgT extends ValueAtPathT<StateT, PathT, never>,
+    ValueResT extends ValueAtPathT<StateT, PathT, void>,
+  >(path: PathT, value: ValueArgT): ValueResT;
+
+  // This variant is disabled by default, otherwise allows to give
+  // expected value type explicitly.
+  set<Forced extends ForceT | false = false, ValueT = never>(
+    path: null | string | undefined,
+    value: TypeLock<Forced, never, ValueT>,
+  ): TypeLock<Forced, void, ValueT>;
+
+  set(path: null | string | undefined, value: unknown): unknown {
+    if (isNil(path)) return this.setEntireState(value as StateT);
+
+    if (value !== this.get(path)) {
+      const root = { state: this.#currentState };
+      let segIdx = 0;
+      let pos: any = root;
+      const pathSegments = toPath(`state.${path}`);
+      for (; segIdx < pathSegments.length - 1; segIdx += 1) {
+        const seg = pathSegments[segIdx];
+        const next = pos[seg];
+        if (Array.isArray(next)) pos[seg] = [...next];
+        else if (isObject(next)) pos[seg] = { ...next };
+        else {
+          // We arrived to a state sub-segment, where the remaining part of
+          // the update path does not exist yet. We rely on lodash's set()
+          // function to create the remaining path, and set the value.
+          set(pos, pathSegments.slice(segIdx), value);
+          break;
+        }
+        pos = pos[seg];
+      }
+
+      if (segIdx === pathSegments.length - 1) {
+        pos[pathSegments[segIdx]] = value;
+      }
+
+      this.#currentState = root.state;
+
+      this.notifyStateUpdate(path, value);
+    }
+    return value;
+  }
+
+  /**
+   * Unsubscribes `callback` from watching state updates; no operation if
+   * `callback` is not subscribed to the state updates.
+   * @param callback
+   * @throws if {@link SsrContext} is attached to the state instance: the state
+   * watching functionality is intended for client-side (non-SSR) only.
+   */
+  unWatch(callback: CallbackT) {
+    if (this.ssrContext) throw new Error(ERR_NO_SSR_WATCH);
+
+    const watchers = this.#watchers;
+    const pos = watchers.indexOf(callback);
+    if (pos >= 0) {
+      watchers[pos] = watchers[watchers.length - 1];
+      watchers.pop();
+    }
+  }
+
+  /**
+   * Subscribes `callback` to watch state updates; no operation if
+   * `callback` is already subscribed to this state instance.
+   * @param callback It will be called without any arguments every
+   * time the state content changes (note, howhever, separate state updates can
+   * be applied to the state at once, and watching callbacks will be called once
+   * after such bulk update).
+   * @throws if {@link SsrContext} is attached to the state instance: the state
+   * watching functionality is intended for client-side (non-SSR) only.
+   */
+  watch(callback: CallbackT) {
+    if (this.ssrContext) throw new Error(ERR_NO_SSR_WATCH);
+
+    const watchers = this.#watchers;
+    if (watchers.indexOf(callback) < 0) {
+      watchers.push(callback);
+    }
+  }
+}