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

package/src/useGlobalState.ts

@@ -0,0 +1,156 @@
+// Hook for updates of global state.
+
+import { cloneDeep, isFunction } from 'lodash';
+import { useEffect, useRef, useSyncExternalStore } from 'react';
+
+import { Emitter } from '@dr.pogodin/js-utils';
+
+import GlobalState from './GlobalState';
+import { getGlobalState } from './GlobalStateProvider';
+
+import {
+  type CallbackT,
+  type ForceT,
+  type TypeLock,
+  type ValueAtPathT,
+  type ValueOrInitializerT,
+  isDebugMode,
+} from './utils';
+
+export type SetterT<T> = React.Dispatch<React.SetStateAction<T>>;
+
+type GlobalStateRef = {
+  emitter: Emitter<[]>;
+  globalState: GlobalState<unknown>;
+  path: null | string | undefined;
+  setter: SetterT<unknown>;
+  state: unknown;
+  watcher: CallbackT;
+};
+
+export type UseGlobalStateResT<T> = [T, SetterT<T>];
+
+/**
+ * The primary hook for interacting with the global state, modeled after
+ * the standard React's
+ * [useState](https://reactjs.org/docs/hooks-reference.html#usestate).
+ * It subscribes a component to a given `path` of global state, and provides
+ * a function to update it. Each time the value at `path` changes, the hook
+ * triggers re-render of its host component.
+ *
+ * **Note:**
+ * - For performance, the library does not copy objects written to / read from
+ *   global state paths. You MUST NOT manually mutate returned state values,
+ *   or change objects already written into the global state, without explicitly
+ *   clonning them first yourself.
+ * - State update notifications are asynchronous. When your code does multiple
+ *   global state updates in the same React rendering cycle, all state update
+ *   notifications are queued and dispatched together, after the current
+ *   rendering cycle. In other words, in any given rendering cycle the global
+ *   state values are "fixed", and all changes becomes visible at once in the
+ *   next triggered rendering pass.
+ *
+ * @param path Dot-delimitered state path. It can be undefined to
+ * subscribe for entire state.
+ *
+ * Under-the-hood state values are read and written using `lodash`
+ * [_.get()](https://lodash.com/docs/4.17.15#get) and
+ * [_.set()](https://lodash.com/docs/4.17.15#set) methods, thus it is safe
+ * to access state paths which have not been created before.
+ * @param initialValue Initial value to set at the `path`, or its
+ * factory:
+ * - If a function is given, it will act similar to
+ *   [the lazy initial state of the standard React's useState()](https://reactjs.org/docs/hooks-reference.html#lazy-initial-state):
+ *   only if the value at `path` is `undefined`, the function will be executed,
+ *   and the value it returns will be written to the `path`.
+ * - Otherwise, the given value itself will be written to the `path`,
+ *   if the current value at `path` is `undefined`.
+ * @return It returs an array with two elements: `[value, setValue]`:
+ *
+ * - The `value` is the current value at given `path`.
+ *
+ * - The `setValue()` is setter function to write a new value to the `path`.
+ *
+ *   Similar to the standard React's `useState()`, it supports
+ *   [functional value updates](https://reactjs.org/docs/hooks-reference.html#functional-updates):
+ *   if `setValue()` is called with a function as argument, that function will
+ *   be called and its return value will be written to `path`. Otherwise,
+ *   the argument of `setValue()` itself is written to `path`.
+ *
+ *   Also, similar to the standard React's state setters, `setValue()` is
+ *   stable function: it does not change between component re-renders.
+ */
+
+function useGlobalState<StateT>(): UseGlobalStateResT<StateT>;
+
+function useGlobalState<Forced extends ForceT | false = false, ValueT = unknown>(
+  path: null | string | undefined,
+  initialValue?: ValueOrInitializerT<TypeLock<Forced, never, ValueT>>,
+): UseGlobalStateResT<TypeLock<Forced, void, ValueT>>;
+
+function useGlobalState<
+  StateT,
+  PathT extends null | string | undefined,
+>(
+  path: PathT,
+  initialValue?: ValueOrInitializerT<ValueAtPathT<StateT, PathT, never>>
+): UseGlobalStateResT<ValueAtPathT<StateT, PathT, void>>;
+
+function useGlobalState(
+  path?: null | string,
+  initialValue?: ValueOrInitializerT<unknown>,
+): UseGlobalStateResT<any> {
+  const globalState = getGlobalState();
+
+  const ref = useRef<GlobalStateRef>();
+  const rc: GlobalStateRef = ref.current || {
+    emitter: new Emitter(),
+    globalState,
+    path,
+    setter: (value) => {
+      const newState = isFunction(value) ? value(rc.state) : value;
+      if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
+        /* eslint-disable no-console */
+        console.groupCollapsed(
+          `ReactGlobalState - useGlobalState setter triggered for path ${
+            rc.path || ''
+          }`,
+        );
+        console.log('New value:', cloneDeep(newState));
+        console.groupEnd();
+        /* eslint-enable no-console */
+      }
+      rc.globalState.set<ForceT, unknown>(rc.path, newState);
+    },
+    state: isFunction(initialValue) ? initialValue() : initialValue,
+    watcher: () => {
+      const state = rc.globalState.get(rc.path);
+      if (state !== rc.state) rc.emitter.emit();
+    },
+  };
+  ref.current = rc;
+
+  rc.globalState = globalState;
+  rc.path = path;
+
+  rc.state = useSyncExternalStore(
+    (cb) => rc.emitter.addListener(cb),
+    () => rc.globalState.get<ForceT, unknown>(rc.path, { initialValue }),
+    () => rc.globalState.get<ForceT, unknown>(rc.path, { initialValue, initialState: true }),
+  );
+
+  useEffect(() => {
+    const { watcher } = ref.current!;
+    globalState.watch(watcher);
+    watcher();
+    return () => globalState.unWatch(watcher);
+  }, [globalState]);
+
+  useEffect(() => {
+    ref.current!.watcher();
+  }, [path]);
+
+  return [rc.state, rc.setter];
+}
+
+export default useGlobalState;

package/src/utils.ts

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

package/src/withGlobalStateType.ts

@@ -0,0 +1,170 @@
+import {
+  type ForceT,
+  type TypeLock,
+  type ValueAtPathT,
+  type ValueOrInitializerT,
+} from './utils';
+
+import GlobalStateProvider, {
+  getGlobalState,
+  getSsrContext,
+} from './GlobalStateProvider';
+
+import SsrContext from './SsrContext';
+
+import useGlobalState, {
+  type UseGlobalStateResT,
+} from './useGlobalState';
+
+import useAsyncCollection, {
+  type AsyncCollectionLoaderT,
+} from './useAsyncCollection';
+
+import useAsyncData, {
+  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>,
+  // SsrContext: SsrContext<StateT>,
+  useAsyncCollection: NarrowedUseAsyncCollectionI<StateT>,
+  useAsyncData: NarrowedUseAsyncDataI<StateT>,
+  useGlobalState: NarrowedUseGlobalStateI<StateT>,
+};
+
+export default function withGlobalStateType<
+  StateT,
+  SsrContextT extends SsrContext<StateT> = SsrContext<StateT>,
+>(): WithGlobalStateTypeResT<StateT, SsrContextT> {
+  // These wrap useGlobalState() with locked-in StateT type.
+
+  function useGlobalStateWrap(): UseGlobalStateResT<StateT>;
+
+  function useGlobalStateWrap<PathT extends null | string | undefined>(
+    path: PathT,
+    initialValue?: ValueOrInitializerT<ValueAtPathT<StateT, PathT, never>>,
+  ): UseGlobalStateResT<ValueAtPathT<StateT, PathT, void>>;
+
+  function useGlobalStateWrap<Forced extends ForceT | false = false, ValueT = unknown>(
+    path: null | string | undefined,
+    initialValue?: ValueOrInitializerT<TypeLock<Forced, never, ValueT>>,
+  ): UseGlobalStateResT<TypeLock<Forced, void, ValueT>>;
+
+  function useGlobalStateWrap(
+    path?: null | string,
+    initialValue?: ValueOrInitializerT<unknown>,
+  ): UseGlobalStateResT<any> {
+    return useGlobalState<ForceT, unknown>(path, initialValue);
+  }
+
+  // These overloads & implementation wrap useAsyncData() hook to lock-in its
+  // underlying StateT.
+
+  function useAsyncDataWrap<PathT extends null | string | undefined>(
+    path: PathT,
+    loader: AsyncDataLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>,
+    options?: UseAsyncDataOptionsT,
+  ): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;
+
+  function useAsyncDataWrap<Forced extends ForceT | false = false, DataT = unknown>(
+    path: null | string | undefined,
+    loader: AsyncDataLoaderT<TypeLock<Forced, void, DataT>>,
+    options?: UseAsyncDataOptionsT,
+  ): UseAsyncDataResT<TypeLock<Forced, never, DataT>>;
+
+  function useAsyncDataWrap<DataT>(
+    path: null | string | undefined,
+    loader: AsyncDataLoaderT<DataT>,
+    options: UseAsyncDataOptionsT = {},
+  ): UseAsyncDataResT<DataT> {
+    return useAsyncData<ForceT, DataT>(path, loader, options);
+  }
+
+  // These overloads & implementation wrap useAsyncCollection() hook to lock-in
+  // its underlying StateT.
+
+  function useAsyncCollectionWrap<PathT extends null | string | undefined>(
+    id: string,
+    path: PathT,
+    loader: AsyncCollectionLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>,
+    options?: UseAsyncDataOptionsT,
+  ): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;
+
+  function useAsyncCollectionWrap<Forced extends ForceT | false = false, DataT = unknown>(
+    id: string,
+    path: null | string | undefined,
+    loader: AsyncCollectionLoaderT<TypeLock<Forced, void, DataT>>,
+    options?: UseAsyncDataOptionsT,
+  ): UseAsyncDataResT<DataT>;
+
+  function useAsyncCollectionWrap<DataT>(
+    id: string,
+    path: null | string | undefined,
+    loader: AsyncCollectionLoaderT<DataT>,
+    options: UseAsyncDataOptionsT = {},
+  ): UseAsyncDataResT<DataT> {
+    return useAsyncCollection<ForceT, DataT>(id, path, loader, options);
+  }
+
+  return {
+    getGlobalState: getGlobalState<StateT, SsrContextT>,
+    getSsrContext: getSsrContext<SsrContextT>,
+    GlobalStateProvider: GlobalStateProvider<StateT, SsrContextT>,
+    // SsrContext, /* CustomSsrContext || SsrContext, */
+    useAsyncCollection: useAsyncCollectionWrap,
+    useAsyncData: useAsyncDataWrap,
+    useGlobalState: useGlobalStateWrap,
+  };
+}

package/tsconfig.json

@@ -1,9 +1,15 @@
 {
   "extends": "@tsconfig/recommended",
-  "include": ["src/**/*"],
   "compilerOptions": {
     "declaration": true,
     "jsx": "react-jsx",
-    "outDir": "build"
-  }
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "outDir": "build",
+    "paths": {
+      "*": ["./*"],
+    },
+    "strict": true,
+    "verbatimModuleSyntax": true,
+  },
 }

package/tsconfig.types.json

@@ -0,0 +1,14 @@
+{
+  "extends": "@tsconfig/recommended",
+  "include": ["src"],
+  "compilerOptions": {
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "outDir": "build/types",
+    "strict": true,
+    "verbatimModuleSyntax": true,
+  }
+}