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

package/build/{node/utils.js → utils.js}

@@ -1,12 +1,6 @@
 "use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-exports.isDebugMode = isDebugMode;
-// Auxiliary stuff.
-
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDebugMode = void 0;
 /**
  * Returns 'true' if debug logging should be performed; 'false' otherwise.
  *
@@ -16,16 +10,16 @@ exports.isDebugMode = isDebugMode;
  *  }
  * to ensure that debug code is stripped out by Webpack in production mode.
  *
- * @returns {boolean}
+ * @returns
  * @ignore
  */
 function isDebugMode() {
-  try {
-    return process.env.NODE_ENV !== 'production' && !!process.env.REACT_GLOBAL_STATE_DEBUG;
-  } catch (error) {
-    return false;
-  }
+    try {
+        return process.env.NODE_ENV !== 'production'
+            && !!process.env.REACT_GLOBAL_STATE_DEBUG;
+    }
+    catch (error) {
+        return false;
+    }
 }
-var _default = null;
-exports.default = _default;
-//# sourceMappingURL=utils.js.map
+exports.isDebugMode = isDebugMode;

package/build/withGlobalStateType.d.ts

@@ -0,0 +1,39 @@
+/// <reference types="react" />
+import { type TypeLock, type ValueAtPathT, type ValueOrInitializerT } from './utils';
+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';
+export default function withGlobalStateType<StateT>(): {
+    getGlobalState: () => import("./GlobalState").default<StateT>;
+    getSsrContext: (throwWithoutSsrContext?: boolean) => SsrContext<StateT> | undefined;
+    GlobalStateProvider: {
+        ({ children, ...rest }: {
+            children?: import("react").ReactNode;
+        } & ({
+            initialState: ValueOrInitializerT<StateT>;
+            ssrContext?: SsrContext<StateT> | undefined;
+        } | {
+            stateProxy: true | import("./GlobalState").default<StateT>;
+        })): import("react/jsx-runtime").JSX.Element;
+        defaultProps: {
+            children: undefined;
+        };
+    };
+    SsrContext: {
+        new (state?: StateT | undefined): SsrContext<StateT>;
+    };
+    useAsyncCollection: {
+        <PathT extends string | null | undefined>(id: string, path: PathT, loader: AsyncCollectionLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;
+        <Unlocked extends 0 | 1 = 0, DataT = unknown>(id: string, path: null | string | undefined, loader: AsyncCollectionLoaderT<TypeLock<Unlocked, void, DataT>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataT>;
+    };
+    useAsyncData: {
+        <PathT_1 extends string | null | undefined>(path: PathT_1, loader: AsyncDataLoaderT<DataInEnvelopeAtPathT<StateT, PathT_1>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT_1>>;
+        <Unlocked_1 extends 0 | 1 = 0, DataT_1 = unknown>(path: null | string | undefined, loader: AsyncDataLoaderT<TypeLock<Unlocked_1, void, DataT_1>>, options?: UseAsyncDataOptionsT): UseAsyncDataResT<TypeLock<Unlocked_1, never, DataT_1>>;
+    };
+    useGlobalState: {
+        (): UseGlobalStateResT<StateT>;
+        <PathT_2 extends string | null | undefined>(path: PathT_2, initialValue?: ValueOrInitializerT<ValueAtPathT<StateT, PathT_2, never>> | undefined): UseGlobalStateResT<ValueAtPathT<StateT, PathT_2, void>>;
+        <Unlocked_2 extends 0 | 1 = 0, ValueT = void>(path: null | string | undefined, initialValue?: ValueOrInitializerT<TypeLock<Unlocked_2, never, ValueT>> | undefined): UseGlobalStateResT<TypeLock<Unlocked_2, void, ValueT>>;
+    };
+};

package/build/withGlobalStateType.js

@@ -0,0 +1,55 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const GlobalStateProvider_1 = __importStar(require("./GlobalStateProvider"));
+const SsrContext_1 = __importDefault(require("./SsrContext"));
+const useGlobalState_1 = __importDefault(require("./useGlobalState"));
+const useAsyncCollection_1 = __importDefault(require("./useAsyncCollection"));
+const useAsyncData_1 = __importDefault(require("./useAsyncData"));
+function withGlobalStateType() {
+    // These wrap useGlobalState() with locked-in StateT type.
+    function useGlobalStateWrap(path, initialValue) {
+        return (0, useGlobalState_1.default)(path, initialValue);
+    }
+    function useAsyncDataWrap(path, loader, options = {}) {
+        return (0, useAsyncData_1.default)(path, loader, options);
+    }
+    function useAsyncCollectionWrap(id, path, loader, options = {}) {
+        return (0, useAsyncCollection_1.default)(id, path, loader, options);
+    }
+    return {
+        getGlobalState: (GlobalStateProvider_1.getGlobalState),
+        getSsrContext: (GlobalStateProvider_1.getSsrContext),
+        GlobalStateProvider: (GlobalStateProvider_1.default),
+        SsrContext: (SsrContext_1.default),
+        useAsyncCollection: useAsyncCollectionWrap,
+        useAsyncData: useAsyncDataWrap,
+        useGlobalState: useGlobalStateWrap,
+    };
+}
+exports.default = withGlobalStateType;

package/package.json

@@ -1,21 +1,22 @@
 {
   "name": "@dr.pogodin/react-global-state",
-  "version": "0.9.3",
+  "version": "0.10.0-alpha.2",
   "description": "Hook-based global state for React",
-  "main": "./build/node/index.js",
+  "main": "./build/index.js",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
   "exports": {
-    "module": "./build/module/index.js",
-    "node": "./build/node/index.js",
     "types": "./index.d.ts",
-    "default": "./build/node/index.js"
+    "default": "./build/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",
-    "jest": "jest --config jest/config.json",
-    "lint": "eslint --ext .js,.jsx .",
-    "test": "npm run lint && npm run jest"
+    "build": "rimraf build && tsc",
+    "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",
+    "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"
   },
   "repository": "github:birdofpreyru/react-global-state",
   "keywords": [
@@ -24,7 +25,8 @@
     "state",
     "hooks",
     "hook",
-    "global"
+    "global",
+    "typescript"
   ],
   "author": "Dr. Sergey Pogodin <doc@pogodin.studio> (https://dr.pogodin.studio)",
   "license": "MIT",
@@ -32,35 +34,54 @@
     "url": "https://github.com/birdofpreyru/react-global-state.git/issues"
   },
   "homepage": "https://dr.pogodin.studio/docs/react-global-state/index.html",
+  "engines": {
+    "node": ">=16"
+  },
   "dependencies": {
-    "@babel/runtime": "^7.21.0",
+    "@babel/runtime": "^7.22.6",
+    "@dr.pogodin/js-utils": "^0.0.6",
     "lodash": "^4.17.21",
     "uuid": "^9.0.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.21.0",
-    "@babel/core": "^7.21.4",
-    "@babel/eslint-parser": "^7.21.3",
-    "@babel/eslint-plugin": "^7.19.1",
-    "@babel/node": "^7.20.7",
-    "@babel/plugin-transform-runtime": "^7.21.4",
-    "@babel/preset-env": "^7.21.4",
-    "@babel/preset-react": "^7.18.6",
-    "babel-jest": "^29.5.0",
+    "@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-plugin-module-resolver": "^5.0.0",
-    "eslint": "^8.37.0",
+    "eslint": "^8.44.0",
     "eslint-config-airbnb": "^19.0.4",
+    "eslint-config-airbnb-typescript": "^17.0.0",
     "eslint-import-resolver-babel-module": "^5.3.2",
     "eslint-plugin-import": "^2.27.5",
-    "eslint-plugin-jest": "^27.2.1",
+    "eslint-plugin-jest": "^27.2.2",
     "eslint-plugin-jsx-a11y": "^6.7.1",
     "eslint-plugin-react": "^7.32.2",
     "eslint-plugin-react-hooks": "^4.6.0",
-    "jest": "^29.5.0",
-    "jest-environment-jsdom": "^29.5.0",
+    "jest": "^29.6.1",
+    "jest-environment-jsdom": "^29.6.1",
+    "jest-runner-tsd": "^6.0.0",
     "mockdate": "^3.0.5",
     "pretty": "^2.0.0",
-    "rimraf": "^4.4.1"
+    "rimraf": "^5.0.1",
+    "tsd-lite": "^0.8.0",
+    "typescript": "^5.1.6"
   },
   "peerDependencies": {
     "react": "^18.2.0",

package/src/GlobalState.ts

@@ -0,0 +1,279 @@
+import {
+  cloneDeep,
+  get,
+  isFunction,
+  isObject,
+  isNil,
+  set,
+  toPath,
+} from 'lodash';
+
+import SsrContext from './SsrContext';
+
+import {
+  type CallbackT,
+  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> {
+  readonly ssrContext?: SsrContext<StateT>;
+
+  #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?: SsrContext<StateT>,
+  ) {
+    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<Unlocked extends 0 | 1 = 0, ValueT = void>(
+    path?: null | string,
+    opts?: GetOptsT<TypeLock<Unlocked, never, ValueT>>,
+  ): TypeLock<Unlocked, 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<1, 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<Unlocked extends 0 | 1 = 0, ValueT = never>(
+    path: null | string | undefined,
+    value: TypeLock<Unlocked, never, ValueT>,
+  ): TypeLock<Unlocked, 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);
+    }
+  }
+}

package/src/GlobalStateProvider.tsx

@@ -0,0 +1,116 @@
+/* eslint-disable react/prop-types */
+
+import { isFunction } from 'lodash';
+
+import {
+  type ReactNode,
+  createContext,
+  useContext,
+  useRef,
+} from 'react';
+
+import GlobalState from './GlobalState';
+import SsrContext from './SsrContext';
+
+import { type ValueOrInitializerT } from './utils';
+
+const context = createContext<GlobalState<unknown> | null>(null);
+
+/**
+ * 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 function getGlobalState<StateT>(): GlobalState<StateT> {
+  // Here Rules of Hooks are violated because "getGlobalState()" does not follow
+  // convention that hook names should start with use... This is intentional in
+  // our case, as getGlobalState() hook is intended for advance scenarious,
+  // while the normal interaction with the global state should happen via
+  // another hook, useGlobalState().
+  /* eslint-disable react-hooks/rules-of-hooks */
+  const globalState = useContext(context);
+  /* eslint-enable react-hooks/rules-of-hooks */
+  if (!globalState) throw new Error('Missing GlobalStateProvider');
+  return globalState as 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 function getSsrContext<StateT>(
+  throwWithoutSsrContext = true,
+): SsrContext<StateT> | undefined {
+  const { ssrContext } = getGlobalState<StateT>();
+  if (!ssrContext && throwWithoutSsrContext) {
+    throw new Error('No SSR context found');
+  }
+  return ssrContext;
+}
+
+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.
+ */
+export default function GlobalStateProvider<StateT>(
+  { children, ...rest }: GlobalStateProviderProps<StateT>,
+) {
+  const state = useRef<GlobalState<StateT>>();
+  if (!state.current) {
+    // NOTE: The last part of condition, "&& rest.stateProxy", is needed for
+    // graceful compatibility with JavaScript - if "undefined" stateProxy value
+    // is given, we want to follow the second branch, which creates a new
+    // GlobalState with whatever intiialState given.
+    if ('stateProxy' in rest && rest.stateProxy) {
+      if (rest.stateProxy === true) state.current = getGlobalState();
+      else state.current = rest.stateProxy;
+    } else {
+      const { initialState, ssrContext } = rest as NewStateProps<StateT>;
+
+      state.current = new GlobalState<StateT>(
+        isFunction(initialState) ? initialState() : initialState,
+        ssrContext,
+      );
+    }
+  }
+  return (
+    <context.Provider value={state.current}>
+      {children}
+    </context.Provider>
+  );
+}
+
+GlobalStateProvider.defaultProps = {
+  children: undefined,
+};

package/src/SsrContext.ts

@@ -0,0 +1,11 @@
+export default class SsrContext<StateT> {
+  dirty: boolean = false;
+
+  pending: Promise<void>[] = [];
+
+  state?: StateT;
+
+  constructor(state?: StateT) {
+    this.state = state;
+  }
+}