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

package/README.md

@@ -4,337 +4,12 @@
 [![NPM monthly downloads](https://img.shields.io/npm/dm/@dr.pogodin/react-global-state)](https://www.npmjs.com/package/@dr.pogodin/react-global-state)
 [![CircleCI](https://dl.circleci.com/status-badge/img/gh/birdofpreyru/react-global-state/tree/master.svg?style=shield)](https://app.circleci.com/pipelines/github/birdofpreyru/react-global-state)
 [![GitHub Repo stars](https://img.shields.io/github/stars/birdofpreyru/react-global-state?style=social)](https://github.com/birdofpreyru/react-global-state)
+[![Dr. Pogodin Studio](https://raw.githubusercontent.com/birdofpreyru/react-global-state/master/.README/logo-dr-pogodin-studio.svg)](https://dr.pogodin.studio/docs/react-global-state)
 
 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)
+[⇒ Documentation ⇐](https://dr.pogodin.studio/docs/react-global-state/index.html)
 
-[![Sponsor](.README/sponsor.png)](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:
-
-    ```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/GlobalState.d.ts

@@ -0,0 +1,75 @@
+import SsrContext from './SsrContext';
+import { type CallbackT, type TypeLock, type ValueAtPathT, type ValueOrInitializerT } from './utils';
+type GetOptsT<T> = {
+    initialState?: boolean;
+    initialValue?: ValueOrInitializerT<T>;
+};
+export default class GlobalState<StateT> {
+    #private;
+    readonly ssrContext?: SsrContext<StateT>;
+    /**
+     * Creates a new global state object.
+     * @param initialState Intial global state content.
+     * @param ssrContext Server-side rendering context.
+     */
+    constructor(initialState: StateT, ssrContext?: SsrContext<StateT>);
+    /**
+     * Gets entire state, the same way as .get(null, opts) would do.
+     * @param opts.initialState
+     * @param opts.initialValue
+     */
+    getEntireState(opts?: GetOptsT<StateT>): StateT;
+    /**
+     * Notifies all connected state watchers that a state update has happened.
+     */
+    private notifyStateUpdate;
+    /**
+     * Sets entire state, the same way as .set(null, value) would do.
+     * @param value
+     */
+    setEntireState(value: StateT): StateT;
+    /**
+     * 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(): 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<Unlocked extends 0 | 1 = 0, ValueT = void>(path?: null | string, opts?: GetOptsT<TypeLock<Unlocked, never, ValueT>>): TypeLock<Unlocked, void, ValueT>;
+    /**
+     * 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.
+     */
+    set<PathT extends null | string | undefined, ValueArgT extends ValueAtPathT<StateT, PathT, never>, ValueResT extends ValueAtPathT<StateT, PathT, void>>(path: PathT, value: ValueArgT): ValueResT;
+    set<Unlocked extends 0 | 1 = 0, ValueT = never>(path: null | string | undefined, value: TypeLock<Unlocked, never, ValueT>): TypeLock<Unlocked, void, ValueT>;
+    /**
+     * 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): void;
+    /**
+     * 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): void;
+}
+export {};

package/build/GlobalState.js

@@ -0,0 +1,193 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _GlobalState_initialState, _GlobalState_watchers, _GlobalState_nextNotifierId, _GlobalState_currentState;
+Object.defineProperty(exports, "__esModule", { value: true });
+const lodash_1 = require("lodash");
+const utils_1 = require("./utils");
+const ERR_NO_SSR_WATCH = 'GlobalState must not be watched at server side';
+class GlobalState {
+    /**
+     * Creates a new global state object.
+     * @param initialState Intial global state content.
+     * @param ssrContext Server-side rendering context.
+     */
+    constructor(initialState, ssrContext) {
+        _GlobalState_initialState.set(this, void 0);
+        // 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.
+        _GlobalState_watchers.set(this, []);
+        _GlobalState_nextNotifierId.set(this, void 0);
+        _GlobalState_currentState.set(this, void 0);
+        __classPrivateFieldSet(this, _GlobalState_currentState, initialState, "f");
+        __classPrivateFieldSet(this, _GlobalState_initialState, initialState, "f");
+        if (ssrContext) {
+            /* eslint-disable no-param-reassign */
+            ssrContext.dirty = false;
+            ssrContext.pending = [];
+            ssrContext.state = __classPrivateFieldGet(this, _GlobalState_currentState, "f");
+            /* eslint-enable no-param-reassign */
+            this.ssrContext = ssrContext;
+        }
+        if (process.env.NODE_ENV !== 'production' && (0, utils_1.isDebugMode)()) {
+            /* eslint-disable no-console */
+            let msg = 'New ReactGlobalState created';
+            if (ssrContext)
+                msg += ' (SSR mode)';
+            console.groupCollapsed(msg);
+            console.log('Initial state:', (0, lodash_1.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 === null || opts === void 0 ? void 0 : opts.initialState) ? __classPrivateFieldGet(this, _GlobalState_initialState, "f") : __classPrivateFieldGet(this, _GlobalState_currentState, "f");
+        if (state !== undefined || (opts === null || opts === void 0 ? void 0 : opts.initialValue) === undefined)
+            return state;
+        const iv = opts.initialValue;
+        state = (0, lodash_1.isFunction)(iv) ? iv() : iv;
+        if (__classPrivateFieldGet(this, _GlobalState_currentState, "f") === 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_1.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_1.cloneDeep)(value));
+            console.log('New state:', (0, lodash_1.cloneDeep)(__classPrivateFieldGet(this, _GlobalState_currentState, "f")));
+            console.groupEnd();
+            /* eslint-enable no-console */
+        }
+        if (this.ssrContext) {
+            this.ssrContext.dirty = true;
+            this.ssrContext.state = __classPrivateFieldGet(this, _GlobalState_currentState, "f");
+        }
+        else if (!__classPrivateFieldGet(this, _GlobalState_nextNotifierId, "f")) {
+            __classPrivateFieldSet(this, _GlobalState_nextNotifierId, setTimeout(() => {
+                __classPrivateFieldSet(this, _GlobalState_nextNotifierId, undefined, "f");
+                const watchers = [...__classPrivateFieldGet(this, _GlobalState_watchers, "f")];
+                for (let i = 0; i < watchers.length; ++i) {
+                    watchers[i]();
+                }
+            }), "f");
+        }
+    }
+    /**
+     * Sets entire state, the same way as .set(null, value) would do.
+     * @param value
+     */
+    setEntireState(value) {
+        if (__classPrivateFieldGet(this, _GlobalState_currentState, "f") !== value) {
+            __classPrivateFieldSet(this, _GlobalState_currentState, value, "f");
+            this.notifyStateUpdate(null, value);
+        }
+        return value;
+    }
+    get(path, opts) {
+        if ((0, lodash_1.isNil)(path)) {
+            const res = this.getEntireState(opts);
+            return res;
+        }
+        const state = (opts === null || opts === void 0 ? void 0 : opts.initialState) ? __classPrivateFieldGet(this, _GlobalState_initialState, "f") : __classPrivateFieldGet(this, _GlobalState_currentState, "f");
+        let res = (0, lodash_1.get)(state, path);
+        if (res !== undefined || (opts === null || opts === void 0 ? void 0 : opts.initialValue) === undefined)
+            return res;
+        const iv = opts.initialValue;
+        res = (0, lodash_1.isFunction)(iv) ? iv() : iv;
+        if (!(opts === null || opts === void 0 ? void 0 : opts.initialState) || this.get(path) === undefined) {
+            this.set(path, res);
+        }
+        return res;
+    }
+    set(path, value) {
+        if ((0, lodash_1.isNil)(path))
+            return this.setEntireState(value);
+        if (value !== this.get(path)) {
+            const root = { state: __classPrivateFieldGet(this, _GlobalState_currentState, "f") };
+            let segIdx = 0;
+            let pos = root;
+            const pathSegments = (0, lodash_1.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_1.isObject)(next))
+                    pos[seg] = Object.assign({}, 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_1.set)(pos, pathSegments.slice(segIdx), value);
+                    break;
+                }
+                pos = pos[seg];
+            }
+            if (segIdx === pathSegments.length - 1) {
+                pos[pathSegments[segIdx]] = value;
+            }
+            __classPrivateFieldSet(this, _GlobalState_currentState, root.state, "f");
+            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 = __classPrivateFieldGet(this, _GlobalState_watchers, "f");
+        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 = __classPrivateFieldGet(this, _GlobalState_watchers, "f");
+        if (watchers.indexOf(callback) < 0) {
+            watchers.push(callback);
+        }
+    }
+}
+_GlobalState_initialState = new WeakMap(), _GlobalState_watchers = new WeakMap(), _GlobalState_nextNotifierId = new WeakMap(), _GlobalState_currentState = new WeakMap();
+exports.default = GlobalState;

package/build/GlobalStateProvider.d.ts

@@ -0,0 +1,55 @@
+import { type ReactNode } from 'react';
+import GlobalState from './GlobalState';
+import SsrContext from './SsrContext';
+import { type ValueOrInitializerT } from './utils';
+/**
+ * Gets {@link GlobalState} instance from the context. In most cases
+ * you should use {@link useGlobalState}, and other hooks to interact with
+ * the global state, instead of accessing it directly.
+ * @return
+ */
+export declare function getGlobalState<StateT>(): GlobalState<StateT>;
+/**
+ * @category Hooks
+ * @desc Gets SSR context.
+ * @param throwWithoutSsrContext If `true` (default),
+ * this hook will throw if no SSR context is attached to the global state;
+ * set `false` to not throw in such case. In either case the hook will throw
+ * if the {@link &lt;GlobalStateProvider&gt;} (hence the state) is missing.
+ * @returns SSR context.
+ * @throws
+ * - If current component has no parent {@link &lt;GlobalStateProvider&gt;}
+ *   in the rendered React tree.
+ * - If `throwWithoutSsrContext` is `true`, and there is no SSR context attached
+ *   to the global state provided by {@link &lt;GlobalStateProvider&gt;}.
+ */
+export declare function getSsrContext<StateT>(throwWithoutSsrContext?: boolean): SsrContext<StateT> | undefined;
+type NewStateProps<StateT> = {
+    initialState: ValueOrInitializerT<StateT>;
+    ssrContext?: SsrContext<StateT>;
+};
+type GlobalStateProviderProps<StateT> = {
+    children?: ReactNode;
+} & (NewStateProps<StateT> | {
+    stateProxy: true | GlobalState<StateT>;
+});
+/**
+ * Provides global state to its children.
+ * @param prop.children Component children, which will be provided with
+ * the global state, and rendered in place of the provider.
+ * @param prop.initialState Initial content of the global state.
+ * @param prop.ssrContext Server-side rendering (SSR) context.
+ * @param prop.stateProxy This option is useful for code
+ * splitting and SSR implementation:
+ * - If `true`, this provider instance will fetch and reuse the global state
+ *   from a parent provider.
+ * - If `GlobalState` instance, it will be used by this provider.
+ * - If not given, a new `GlobalState` instance will be created and used.
+ */
+declare function GlobalStateProvider<StateT>({ children, ...rest }: GlobalStateProviderProps<StateT>): import("react/jsx-runtime").JSX.Element;
+declare namespace GlobalStateProvider {
+    var defaultProps: {
+        children: undefined;
+    };
+}
+export default GlobalStateProvider;