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

package/README.md

@@ -10,332 +10,8 @@ State of the art approach to the global state and asynchronous data management
 in React applications, powered by hooks and Context API. Simple, efficient, with
 full server-side rendering (SSR) support.
 
-[Library Reference](https://dr.pogodin.studio/docs/react-global-state/index.html) •
-[Blog Article](https://dr.pogodin.studio/dev-blog/the-global-state-in-react-designed-right)
+TypeScript support since v0.10.0.
 
-[![Sponsor](https://raw.githubusercontent.com/birdofpreyru/react-global-state/master/.README/sponsor.svg)](https://github.com/sponsors/birdofpreyru)
-
-### Motivation
-
-The motivation and vision is to bring to the table all useful features
-of Redux, without related development overheads, like the amount of required
-boilerplate code, and the efforts needed to design and maintain actions
-and reducers.
-
-With this library, the introduction of a datum (data piece), shared across
-different application components, is as easy as using the local React state:
-
-```jsx
-function SampleReactComponent() {
-  const [data, setData] = useGlobalState('data.storage.path', initialValue);
-
-  /* `data` value can be updating by calling `setData(newData)` anywhere inside
-   * the component code, including inside hooks like `useEffect(..)` or some
-   * event handlers. */
-
-  return /* Some JSX markup. */;
-}
-```
-
-Relying on async data, e.g. loading into the state data from a 3-rd party API,
-is the same easy:
-
-```jsx
-async function loader() {
-
-  /* Some async operation to get data, like a call to a 3-rd party API. */
-
-  return data;
-}
-
-function SampleReactComponent() {
-  const { data, loading, timestamp } = useAsyncData('data.envelope.path', loader);
-
-  /* `data` holds the data loaded into the global state, if they are fresh enough;
-   * `loading` signals that data loading (or silent re-loading) is in-progress;
-   * `timestamp` is the timestamp of currently loaded `data`. */
-
-  return /* Some JSX markup. */
-}
-```
-⇑ Behind the scene, the library takes care about updating the component
-when the data loading starts and ends, also about the timestamps, automatic
-reloading, and garbage collection of aged data.
-
-Related closely to async data is the server-side rendering (SSR). This library
-takes it into account, and provides a flexible way to implement SSR with loading
-of some, or all async data at the server side.
-
-### Setup
-
-1.  <a name="base-setup"></a> The base setup is simple: just wrap your app into
-    the `<GlobalStateProvider>` component, provided by this library, and you'll
-    be able to use any library hooks within its child hierarchy.
-
-    ```jsx
-    /* The minimal example of the library setup and usage. */
-
-    import React from 'react';
-    import {
-      GlobalStateProvider,
-      useAsyncData,
-      useGlobalState,
-    } from '@dr.pogodin/react-global-state';
-
-    /* Example of component relying on the global state. */
-
-    function SampleComponent() {
-      const [value, setValue] = useGlobalState('sample.component', 0);
-      return (
-        <button onClick={() => setValue(1 + value)}>
-          {value}
-        </button>
-      );
-    }
-
-    /* Example of component relying on async data in the global state. */
-
-    async function sampleDataLoader() {
-      return new Promise((resolve) => {
-        setTimeout(() => resolve('Sample Data'), 500);
-      });
-    }
-
-    function SampleAsyncComponent() {
-      const { data, loading } = useAsyncData('sample.async-component', sampleDataLoader);
-      return data;
-    }
-
-    /* Example of the root app component, providing the state.  */
-
-    export default function SampleApp() {
-      return (
-        <GlobalStateProvider>
-          <SampleComponent />
-          <SampleAsyncComponent />
-        </GlobalStateProvider>
-      );
-    }
-    ```
-
-    Multiple, or nested `<GlobalStateProvider>` instances are allowed, and they
-    will provide independent global states to its children (shadowing parent ones,
-    in the case of nesting). However, the current SSR implementation assumes
-    a single `<GlobalStateProvider>` at the app root. Multiple providers won't
-    break it, but won't be a part of SSR data loading either.
-
-    This setup is fine to run both at the client, and at the server-side, but
-    in the case of server-side rendering, the library won't run any async data
-    fetching, thus rendering pages with the initial global state; e.g. in
-    the example above the `<SampleAsyncComponent>` will be rendered as an empty
-    node, as `data` will be `undefined`, and `loading` will be `false`.
-    To handle SSR better, and to have `<SampleAsyncComponent>` rendered as
-    `Sample Data` even at the server-side, you need the following, a bit more
-    complex, setup.
-
-2.  Advanced setup with the server-side rendering support is demonstrated below,
-    assuming that `<SampleComponent>`, `sampleDataLoader(..)`,
-    and `<SampleAsyncComponent>` are defined the same way as in the previous
-    example, and `<SampleApp>` component itself does not include
-    the `<GlobalStateProvider>`, i.e.
-
-    ```jsx
-    export default function SampleApp() {
-      return (
-        <React.Fragment>
-          <SampleComponent />
-          <SampleAsyncComponent />
-        </React.Fragment>
-      );
-    }
-    ```
-
-    The server-side rendering code becomes:
+[&rArr; Documentation &lArr;](https://dr.pogodin.studio/docs/react-global-state/index.html)
 
-    ```jsx
-    /* Server-sider rendering. */
-
-    import React from 'react';
-    import ReactDOM from 'react-dom/server';
-
-    import { GlobalStateProvider } from '@dr.pogodin/react-global-state';
-
-    import SampleApp from 'path/to/app';
-
-    // As you want to keep server latency within a reason, it is a good idea
-    // to limit the maximum number of SSR rounds, or the maximum SSR time, or
-    // both, and perform any async operations which took too long at the client
-    // side.
-    const MAX_SSR_ROUNDS = 3;
-    const SSR_TIMEOUT = 1000; // 1 second (in milliseconds).
-
-    async function renderServerSide() {
-      let render;
-      const start = Date.now();
-      const ssrContext = { state: {} };
-      for (let round = 0; round < MAX_SSR_ROUNDS; round += 1) {
-        // SSR round.
-        render = ReactDOM.renderToString((
-          <GlobalStateProvider
-            initialState={ssrContext.state}
-            ssrContext={ssrContext}
-          >
-            <SampleApp />
-          </GlobalStateProvider>
-        ));
-
-        // SSR round did not altered the global state: we are done.
-        if (!ssrContext.dirty) break;
-
-        // Waiting for pending async operations to complete.
-        const timeout = SSR_TIMEOUT + start - Date.now();
-        const ok = timeout > 0 && await Promise.race([
-          Promise.allSettled(ssrContext.pending),
-          new Promise((x) => setTimeout(() => x(false), timeout)),
-        ]);
-        if (!ok) break; // SSR timeout.
-      }
-      return { render, state: ssrContext.state };
-    }
-    ```
-    &uArr; When `ssrContext` property is passed into the `<GlobalStateProvider>`,
-    the corresponding global state object switches into the SSR mode. In this mode,
-    if the app rendering modifies the state, the `ssrContext.dirty` flag is set
-    `true`, and for any async operations, triggered by the library hooks,
-    corresponding promises are added into the `ssrContext.pending` array.
-    Thus, the block of code
-    ```js
-    if (!ssrContext.dirty) break;
-
-    const timeout = SSR_TIMEOUT + start - Date.now();
-    const ok = timeout > 0 && await Promise.race([
-      Promise.allSettled(ssrContext.pending),
-      new Promise((x) => setTimeout(() => x(false), timeout)),
-    ]);
-    if (!ok) break;
-    ```
-    in the case when last rendering pass triggered async operations, it waits
-    for them to complete, and allows the rendering pass to be redone
-    with the new initial value of the global state, which is written to
-    `ssrContext.state` in this case. If no updates to the state happened
-    in the last rendering pass, this block breaks out of the loop, leaving
-    to you in the `render` variable the HTML markup to send to the client,
-    and in the `ssrContext.state` the initial value of the global state to use
-    for app initialization at the client side.
-
-    The outer `for` loop serves to protect against possible long re-rendering
-    loops: if after several re-renders the state has not become stable, it is
-    fine to send to the client side the latest render and state results, and
-    finalize the rest of rendering at the client side. Similarly, the timeout
-    condition interrupts SSR and cause the code to serve the current render
-    and state, if any pending async operation takes too long, thus compromising
-    server latency.
-
-    In case when some async operations are too long to wait for them during SSR,
-    the async hooks accept `noSSR` option, to be ignored during SSR. Additional
-    option is to wrap the rendering cycle into a timeout race codition, and if
-    the desired rendering time has bit hit, the rendering loop can be interrupted,
-    and the latest render and state can be sent to the client side.
-
-    The corresponding client-side rendering is simple, just pass the state
-    calculated during the server-side rendering into the `initialState` prop
-    of `<GlobalStateProvider>` at the client side:
-
-    ```jsx
-    /* Client-side rendering. */
-
-    import React from 'react';
-    import ReactDOM from 'react-dom';
-
-    import { GlobalStateProvider } from '@dr.pogodin/react-global-state';
-
-    import SampleApp from 'path/to/app';
-
-    function renderClientSide(stateFromServerSide) {
-      ReactDOM.hydrate((
-        <GlobalStateProvider initialState={stateFromServerSide}>
-          <SampleApp />
-        </GlobalStateProvider>
-      ), document.getElementById('your-react-view'));
-    }
-    ```
-
-### Frequently Asked Questions
-
-- _Does React Global State library avoid unnecessary component re-renders when values updated in the global state are irrelevant to those components?_
-
-  Yes, it does avoid unnecessary re-renders of the component tree. A component
-  relying on `some.path` in the global state is re-rendered only when the value
-  at this path, or its sub-path has changed; _i.e._ it will be re-rendered if
-  the value at `some.path` has changed, and it will be re-rendered if the value
-  at `some.path.sub.path` has changed.
-
-- _How would you describe your use case compared to another React global state library, e.g. [Valtio](https://www.npmjs.com/package/valtio)?_
-
-  1.  React Global State is designed to follow the standard React API as close
-      as possible. _E.g._ if some component relies on the local state:
-      ```jsx
-      const [value, setValue] = useState(initialState);
-      ```
-      to move that value to the global state (or _vice versa_) one only needs to
-      replace the hook with
-      ```jsx
-      const [value, setValue] = useGlobalState(path, initialState);
-      ```
-      The [useGlobalState()] hook takes care to follow all edge cases of the
-      standard [useState()]: `setValue` setter identity is stable (does not
-      change on re-renders), functional updates and lazy initial state are
-      supported.
-
-      Other libraries tend to re-invent the wheel, introducing their own APIs,
-      which (i) should be learned and understood; (ii) do complicate migration
-      of components between the local and global state, should it be needed in
-      a course of app development / prototyping.
-
-  2.  When it comes to async data in the global state other libraries tend to
-      offer only a very basic supported, often relying on experimental or internal
-      React mechanics.
-
-      React Global State, [useAsyncData()] and [useAsyncCollection()] hooks in
-      particular, implements async data fetching and management features: when
-      multiple components use these hooks to load async data to the same global
-      state path the library takes care to do the actual loading just once, and
-      then keep the data without reloading until their age reaches (configurable)
-      max age. There is an automated garbage collection of expired, non-used
-      async data from the global state; there is server-side rendering (SSR)
-      support, with suggested high-level setup taking care that all async data
-      loaded using [useAsyncData()] and [useAsyncCollection()] hooks will be
-      automatically loaded and used in server-side renders (still allowing to
-      opt-out of that for individual hooks, and timeout server-side fetching of
-      data that take too long to arrive, in which case the library will fetch
-      such data client-side). It does not rely on experimental React APIs to
-      achieve its functionality, it only uses current public APIs.
-
-      For me the support of async data fetching into the global state and their
-      further management with out-of-the-box SSR support was the primary
-      motivation to create React Global State. There are many other global state
-      React libraries, but I was not able to find any that would cover the async
-      data handling with that ease I believed was possible. The secondary
-      motivation was that existing global state libraries either had
-      the shortcoming of unnecessary component re-renders when data irrelevant
-      to them where updated in the global state, or introduced their
-      own APIs, where following the standard React APIs for local state looks
-      to me a way more convenient approach.
-
-- _Is React Global State library production ready (considering the current version number 0.y.z)?_
-
-  Yes. I personally use it in production for all my commercial and personal
-  React projects for over an year. I just don't feel like to call it v1 until
-  a reasonable adoption by 3rd party developers, and any API improvements that
-  may come out of community experience.
-
-[Library Reference](https://dr.pogodin.studio/docs/react-global-state/index.html) &bull;
-[Blog Article](https://dr.pogodin.studio/dev-blog/the-global-state-in-react-designed-right)
-
-[useAsyncCollection()]: https://dr.pogodin.studio/docs/react-global-state/docs/api/hooks/useasynccollection
-[useAsyncData()]: https://dr.pogodin.studio/docs/react-global-state/docs/api/hooks/useasyncdata
-[useGlobalState()]: https://dr.pogodin.studio/docs/react-global-state/docs/api/hooks/useglobalstate
-[useState()]: https://reactjs.org/docs/hooks-reference.html#usestate
-
-[functional updates]: https://reactjs.org/docs/hooks-reference.html#functional-updates
-[lazy initial state]: https://reactjs.org/docs/hooks-reference.html#functional-updates
+[![Sponsor](https://raw.githubusercontent.com/birdofpreyru/react-global-state/master/.README/sponsor.svg)](https://github.com/sponsors/birdofpreyru)

package/build/common/GlobalState.js

@@ -0,0 +1,219 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _lodash = require("lodash");
+var _utils = require("./utils");
+const ERR_NO_SSR_WATCH = 'GlobalState must not be watched at server side';
+class GlobalState {
+  #initialState;
+
+  // 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 = [];
+  #nextNotifierId;
+  #currentState;
+
+  /**
+   * Creates a new global state object.
+   * @param initialState Intial global state content.
+   * @param ssrContext Server-side rendering context.
+   */
+  constructor(initialState, ssrContext) {
+    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' && (0, _utils.isDebugMode)()) {
+      /* eslint-disable no-console */
+      let msg = 'New ReactGlobalState created';
+      if (ssrContext) msg += ' (SSR mode)';
+      console.groupCollapsed(msg);
+      console.log('Initial state:', (0, _lodash.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) {
+    let state = opts?.initialState ? this.#initialState : this.#currentState;
+    if (state !== undefined || opts?.initialValue === undefined) return state;
+    const iv = opts.initialValue;
+    state = (0, _lodash.isFunction)(iv) ? iv() : iv;
+    if (this.#currentState === undefined) this.setEntireState(state);
+    return state;
+  }
+
+  /**
+   * Notifies all connected state watchers that a state update has happened.
+   */
+  notifyStateUpdate(path, value) {
+    if (process.env.NODE_ENV !== 'production' && (0, _utils.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:', (0, _lodash.cloneDeep)(value));
+      console.log('New state:', (0, _lodash.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) {
+    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().
+  // 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.
+  // This variant is not callable by default (without generic arguments),
+  // otherwise it allows to set the correct ValueT directly.
+  get(path, opts) {
+    if ((0, _lodash.isNil)(path)) {
+      const res = this.getEntireState(opts);
+      return res;
+    }
+    const state = opts?.initialState ? this.#initialState : this.#currentState;
+    let res = (0, _lodash.get)(state, path);
+    if (res !== undefined || opts?.initialValue === undefined) return res;
+    const iv = opts.initialValue;
+    res = (0, _lodash.isFunction)(iv) ? iv() : iv;
+    if (!opts?.initialState || this.get(path) === undefined) {
+      this.set(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.
+  // This variant is disabled by default, otherwise allows to give
+  // expected value type explicitly.
+  set(path, value) {
+    if ((0, _lodash.isNil)(path)) return this.setEntireState(value);
+    if (value !== this.get(path)) {
+      const root = {
+        state: this.#currentState
+      };
+      let segIdx = 0;
+      let pos = root;
+      const pathSegments = (0, _lodash.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 ((0, _lodash.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.
+          (0, _lodash.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) {
+    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) {
+    if (this.ssrContext) throw new Error(ERR_NO_SSR_WATCH);
+    const watchers = this.#watchers;
+    if (watchers.indexOf(callback) < 0) {
+      watchers.push(callback);
+    }
+  }
+}
+exports.default = GlobalState;
+//# sourceMappingURL=GlobalState.js.map

package/build/common/GlobalState.js.map

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