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

package/src/GlobalStateProvider.tsx

@@ -0,0 +1,127 @@
+/* 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,
+  SsrContextT extends SsrContext<StateT> = SsrContext<StateT>,
+>(): GlobalState<StateT, SsrContextT> {
+  // 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, SsrContextT>;
+}
+
+/**
+ * @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<
+  SsrContextT extends SsrContext<unknown>,
+>(
+  throwWithoutSsrContext = true,
+): SsrContextT | undefined {
+  const { ssrContext } = getGlobalState<SsrContextT['state'], SsrContextT>();
+  if (!ssrContext && throwWithoutSsrContext) {
+    throw new Error('No SSR context found');
+  }
+  return ssrContext;
+}
+
+type NewStateProps<StateT, SsrContextT extends SsrContext<StateT>> = {
+  initialState: ValueOrInitializerT<StateT>,
+  ssrContext?: SsrContextT;
+};
+
+type GlobalStateProviderProps<
+  StateT,
+  SsrContextT extends SsrContext<StateT>,
+> = {
+  children?: ReactNode;
+} & (NewStateProps<StateT, SsrContextT> | {
+  stateProxy: true | GlobalState<StateT, SsrContextT>;
+});
+
+/**
+ * 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,
+  SsrContextT extends SsrContext<StateT> = SsrContext<StateT>,
+>(
+  { children, ...rest }: GlobalStateProviderProps<StateT, SsrContextT>,
+) {
+  const state = useRef<GlobalState<StateT, SsrContextT>>();
+  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, SsrContextT>;
+
+      state.current = new GlobalState<StateT, SsrContextT>(
+        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;
+  }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+export { default as GlobalState } from './GlobalState';
+
+export {
+  default as GlobalStateProvider,
+  getGlobalState,
+  getSsrContext,
+} from './GlobalStateProvider';
+
+export { default as SsrContext } from './SsrContext';
+
+export {
+  type AsyncCollectionLoaderT,
+  default as useAsyncCollection,
+} from './useAsyncCollection';
+
+export {
+  type AsyncDataEnvelopeT,
+  type AsyncDataLoaderT,
+  type UseAsyncDataOptionsT,
+  type UseAsyncDataResT,
+  default as useAsyncData,
+  newAsyncDataEnvelope,
+} from './useAsyncData';
+
+export {
+  type SetterT,
+  type UseGlobalStateResT,
+  default as useGlobalState,
+} from './useGlobalState';
+
+export { type ForceT, type ValueOrInitializerT } from './utils';
+
+export { default as withGlobalStateType } from './withGlobalStateType';

package/src/useAsyncCollection.ts

@@ -0,0 +1,96 @@
+/**
+ * Loads and uses an item in an async collection.
+ */
+
+import useAsyncData, {
+  type DataInEnvelopeAtPathT,
+  type UseAsyncDataOptionsT,
+  type UseAsyncDataResT,
+} from './useAsyncData';
+
+import { type ForceT, type TypeLock } from './utils';
+
+export type AsyncCollectionLoaderT<DataT> =
+  (id: string, oldData: null | DataT) => DataT | Promise<DataT>;
+
+/**
+ * Resolves and stores at the given `path` of global state elements of
+ * an asynchronous data collection. In other words, it is an auxiliar wrapper
+ * around {@link useAsyncData}, which uses a loader which resolves to different
+ * data, based on ID argument passed in, and stores data fetched for different
+ * IDs in the state.
+ * @param id ID of the collection item to load & use.
+ * @param path The global state path where entire collection should be
+ *  stored.
+ * @param loader A loader function, which takes an
+ * ID of data to load, and resolves to the corresponding data.
+ * @param options Additional options.
+ * @param options.deps An array of dependencies, which trigger
+ * data reload when changed. Given dependency changes are watched shallowly
+ * (similarly to the standard React's
+ * [useEffect()](https://reactjs.org/docs/hooks-reference.html#useeffect)).
+ * @param options.noSSR If `true`, this hook won't load data during
+ * server-side rendering.
+ * @param options.garbageCollectAge The maximum age of data
+ * (in milliseconds), after which they are dropped from the state when the last
+ * component referencing them via `useAsyncData()` hook unmounts. Defaults to
+ * `maxage` option value.
+ * @param options.maxage The maximum age of
+ * data (in milliseconds) acceptable to the hook's caller. If loaded data are
+ * older than this value, `null` is returned instead. Defaults to 5 minutes.
+ * @param options.refreshAge The maximum age of data
+ * (in milliseconds), after which their refreshment will be triggered when
+ * any component referencing them via `useAsyncData()` hook (re-)renders.
+ * Defaults to `maxage` value.
+ * @return Returns an object with three fields: `data` holds the actual result of
+ * last `loader` invokation, if any, and if satisfies `maxage` limit; `loading`
+ * is a boolean flag, which is `true` if data are being loaded (the hook is
+ * waiting for `loader` function resolution); `timestamp` (in milliseconds)
+ * is Unix timestamp of related data currently loaded into the global state.
+ *
+ * Note that loaded data, if any, are stored at the given `path` of global state
+ * along with related meta-information, using slightly different state segment
+ * structure (see {@link AsyncDataEnvelope}). That segment of the global state
+ * can be accessed, and even modified using other hooks,
+ * _e.g._ {@link useGlobalState}, but doing so you may interfere with related
+ * `useAsyncData()` hooks logic.
+ */
+
+function useAsyncCollection<
+  StateT,
+  PathT extends null | string | undefined,
+  IdT extends string,
+>(
+  id: IdT,
+  path: PathT,
+  loader: AsyncCollectionLoaderT<
+  DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`>
+  >,
+  options?: UseAsyncDataOptionsT,
+): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, `${PathT}.${IdT}`>>;
+
+function useAsyncCollection<
+  Forced extends ForceT | false = false,
+  DataT = unknown,
+>(
+  id: string,
+  path: null | string | undefined,
+  loader: AsyncCollectionLoaderT<TypeLock<Forced, void, DataT>>,
+  options?: UseAsyncDataOptionsT,
+): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;
+
+function useAsyncCollection<DataT>(
+  id: string,
+  path: null | string | undefined,
+  loader: AsyncCollectionLoaderT<DataT>,
+  options: UseAsyncDataOptionsT = {},
+): UseAsyncDataResT<DataT> {
+  const itemPath = path ? `${path}.${id}` : id;
+  return useAsyncData<ForceT, DataT>(
+    itemPath,
+    (oldData: null | DataT) => loader(id, oldData),
+    options,
+  );
+}
+
+export default useAsyncCollection;

package/src/useAsyncData.ts

@@ -0,0 +1,295 @@
+/**
+ * Loads and uses async data into the GlobalState path.
+ */
+
+import { cloneDeep } from 'lodash';
+import { useEffect } from 'react';
+import { v4 as uuid } from 'uuid';
+
+import { MIN_MS } from '@dr.pogodin/js-utils';
+
+import { getGlobalState } from './GlobalStateProvider';
+import useGlobalState from './useGlobalState';
+
+import {
+  type ForceT,
+  type TypeLock,
+  type ValueAtPathT,
+  isDebugMode,
+} from './utils';
+
+import GlobalState from './GlobalState';
+import SsrContext from './SsrContext';
+
+const DEFAULT_MAXAGE = 5 * MIN_MS; // 5 minutes.
+
+export type AsyncDataLoaderT<DataT>
+= (oldData: null | DataT) => DataT | Promise<DataT>;
+
+export type AsyncDataEnvelopeT<DataT> = {
+  data: null | DataT;
+  numRefs: number;
+  operationId: string;
+  timestamp: number;
+};
+
+export function newAsyncDataEnvelope<DataT>(
+  initialData: DataT | null = null,
+): AsyncDataEnvelopeT<DataT> {
+  return {
+    data: initialData,
+    numRefs: 0,
+    operationId: '',
+    timestamp: 0,
+  };
+}
+
+export type UseAsyncDataOptionsT = {
+  deps?: unknown[];
+  garbageCollectAge?: number;
+  maxage?: number;
+  noSSR?: boolean;
+  refreshAge?: number;
+};
+
+export type UseAsyncDataResT<DataT> = {
+  data: DataT | null;
+  loading: boolean;
+  timestamp: number;
+};
+
+/**
+ * Executes the data loading operation.
+ * @param path Data segment path inside the global state.
+ * @param loader Data loader.
+ * @param globalState The global state instance.
+ * @param oldData Optional. Previously fetched data, currently stored in
+ *  the state, if already fetched by the caller; otherwise, they will be fetched
+ *  by the load() function itself.
+ * @param opIdPrefix operationId prefix to use, which should be
+ * 'C' at the client-side (default), or 'S' at the server-side (within SSR
+ * context).
+ * @return Resolves once the operation is done.
+ * @ignore
+ */
+async function load<DataT>(
+  path: null | string | undefined,
+  loader: AsyncDataLoaderT<DataT>,
+  globalState: GlobalState<unknown, SsrContext<unknown>>,
+  oldData: DataT | null,
+  opIdPrefix: 'C' | 'S' = 'C',
+): Promise<void> {
+  if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
+    /* eslint-disable no-console */
+    console.log(
+      `ReactGlobalState: useAsyncData data (re-)loading. Path: "${path || ''}"`,
+    );
+    /* eslint-enable no-console */
+  }
+  const operationId = opIdPrefix + uuid();
+  const operationIdPath = path ? `${path}.operationId` : 'operationId';
+  globalState.set<ForceT, string>(operationIdPath, operationId);
+  const data = await loader(
+    oldData || (globalState.get<ForceT, AsyncDataEnvelopeT<DataT>>(path)).data,
+  );
+  const state: AsyncDataEnvelopeT<DataT> = globalState.get<ForceT, AsyncDataEnvelopeT<DataT>>(path);
+  if (operationId === state.operationId) {
+    if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
+      /* eslint-disable no-console */
+      console.groupCollapsed(
+        `ReactGlobalState: useAsyncData data (re-)loaded. Path: "${
+          path || ''
+        }"`,
+      );
+      console.log('Data:', cloneDeep(data));
+      /* eslint-enable no-console */
+    }
+    globalState.set<ForceT, AsyncDataEnvelopeT<DataT>>(path, {
+      ...state,
+      data,
+      operationId: '',
+      timestamp: Date.now(),
+    });
+    if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
+      /* eslint-disable no-console */
+      console.groupEnd();
+      /* eslint-enable no-console */
+    }
+  }
+}
+
+/**
+ * Resolves asynchronous data, and stores them at given `path` of global
+ * state. When multiple components rely on asynchronous data at the same `path`,
+ * the data are resolved once, and reused until their age is within specified
+ * bounds. Once the data are stale, the hook allows to refresh them. It also
+ * garbage-collects stale data from the global state when the last component
+ * relying on them is unmounted.
+ * @param path Dot-delimitered state path, where data envelop is
+ * stored.
+ * @param loader Asynchronous function which resolves (loads)
+ * data, which should be stored at the global state `path`. When multiple
+ * components
+ * use `useAsyncData()` hook for the same `path`, the library assumes that all
+ * hook instances are called with the same `loader` (_i.e._ whichever of these
+ * loaders is used to resolve async data, the result is acceptable to be reused
+ * in all related components).
+ * @param options Additional options.
+ * @param options.deps An array of dependencies, which trigger
+ * data reload when changed. Given dependency changes are watched shallowly
+ * (similarly to the standard React's
+ * [useEffect()](https://reactjs.org/docs/hooks-reference.html#useeffect)).
+ * @param options.noSSR If `true`, this hook won't load data during
+ * server-side rendering.
+ * @param options.garbageCollectAge The maximum age of data
+ * (in milliseconds), after which they are dropped from the state when the last
+ * component referencing them via `useAsyncData()` hook unmounts. Defaults to
+ * `maxage` option value.
+ * @param options.maxage The maximum age of
+ * data (in milliseconds) acceptable to the hook's caller. If loaded data are
+ * older than this value, `null` is returned instead. Defaults to 5 minutes.
+ * @param options.refreshAge The maximum age of data
+ * (in milliseconds), after which their refreshment will be triggered when
+ * any component referencing them via `useAsyncData()` hook (re-)renders.
+ * Defaults to `maxage` value.
+ * @return Returns an object with three fields: `data` holds the actual result of
+ * last `loader` invokation, if any, and if satisfies `maxage` limit; `loading`
+ * is a boolean flag, which is `true` if data are being loaded (the hook is
+ * waiting for `loader` function resolution); `timestamp` (in milliseconds)
+ * is Unix timestamp of related data currently loaded into the global state.
+ *
+ * Note that loaded data, if any, are stored at the given `path` of global state
+ * along with related meta-information, using slightly different state segment
+ * structure (see {@link AsyncDataEnvelopeT}). That segment of the global state
+ * can be accessed, and even modified using other hooks,
+ * _e.g._ {@link useGlobalState}, but doing so you may interfere with related
+ * `useAsyncData()` hooks logic.
+ */
+
+export type DataInEnvelopeAtPathT<StateT, PathT extends null | string | undefined>
+= ValueAtPathT<StateT, PathT, never> extends AsyncDataEnvelopeT<unknown>
+  ? Exclude<ValueAtPathT<StateT, PathT, never>['data'], null>
+  : void;
+
+function useAsyncData<
+  StateT,
+  PathT extends null | string | undefined,
+>(
+  path: PathT,
+  loader: AsyncDataLoaderT<DataInEnvelopeAtPathT<StateT, PathT>>,
+  options?: UseAsyncDataOptionsT,
+): UseAsyncDataResT<DataInEnvelopeAtPathT<StateT, PathT>>;
+
+function useAsyncData<
+  Forced extends ForceT | false = false,
+  DataT = unknown,
+>(
+  path: null | string | undefined,
+  loader: AsyncDataLoaderT<TypeLock<Forced, void, DataT>>,
+  options?: UseAsyncDataOptionsT,
+): UseAsyncDataResT<TypeLock<Forced, void, DataT>>;
+
+function useAsyncData<DataT>(
+  path: null | string | undefined,
+  loader: AsyncDataLoaderT<DataT>,
+  options: UseAsyncDataOptionsT = {},
+): UseAsyncDataResT<DataT> {
+  const maxage: number = options.maxage === undefined
+    ? DEFAULT_MAXAGE : options.maxage;
+
+  const refreshAge: number = options.refreshAge === undefined
+    ? maxage : options.refreshAge;
+
+  const garbageCollectAge: number = options.garbageCollectAge === undefined
+    ? maxage : options.garbageCollectAge;
+
+  // Note: here we can't depend on useGlobalState() to init the initial value,
+  // because that way we'll have issues with SSR (see details below).
+  const globalState = getGlobalState();
+  const state = globalState.get<ForceT, AsyncDataEnvelopeT<DataT>>(path, {
+    initialValue: newAsyncDataEnvelope<DataT>(),
+  });
+
+  if (globalState.ssrContext && !options.noSSR) {
+    if (!state.timestamp && !state.operationId) {
+      globalState.ssrContext.pending.push(
+        load(path, loader, globalState, state.data, 'S'),
+      );
+    }
+  } else {
+    // This takes care about the client-side reference counting, and garbage
+    // collection.
+    //
+    // Note: the Rules of Hook below are violated by conditional call to a hook,
+    // but as the condition is actually server-side or client-side environment,
+    // it is effectively non-conditional at the runtime.
+    //
+    // TODO: Though, maybe there is a way to refactor it into a cleaner code.
+    // The same applies to other useEffect() hooks below.
+    useEffect(() => { // eslint-disable-line react-hooks/rules-of-hooks
+      const numRefsPath = path ? `${path}.numRefs` : 'numRefs';
+      const numRefs = globalState.get<ForceT, number>(numRefsPath);
+      globalState.set<ForceT, number>(numRefsPath, numRefs + 1);
+      return () => {
+        const state2: AsyncDataEnvelopeT<DataT> = globalState.get<
+        ForceT, AsyncDataEnvelopeT<DataT>>(
+          path,
+        );
+        if (
+          state2.numRefs === 1
+          && garbageCollectAge < Date.now() - state2.timestamp
+        ) {
+          if (process.env.NODE_ENV !== 'production' && isDebugMode()) {
+            /* eslint-disable no-console */
+            console.log(
+              `ReactGlobalState - useAsyncData garbage collected at path ${
+                path || ''
+              }`,
+            );
+            /* eslint-enable no-console */
+          }
+          globalState.set<ForceT, AsyncDataEnvelopeT<DataT>>(path, {
+            ...state2,
+            data: null,
+            numRefs: 0,
+            timestamp: 0,
+          });
+        } else globalState.set<ForceT, number>(numRefsPath, state2.numRefs - 1);
+      };
+    }, [garbageCollectAge, globalState, path]);
+
+    // Note: a bunch of Rules of Hooks ignored belows because in our very
+    // special case the otherwise wrong behavior is actually what we need.
+
+    // Data loading and refreshing.
+    let loadTriggered = false;
+    useEffect(() => { // eslint-disable-line react-hooks/rules-of-hooks
+      const state2: AsyncDataEnvelopeT<DataT> = globalState.get<
+      ForceT, AsyncDataEnvelopeT<DataT>>(path);
+
+      if (refreshAge < Date.now() - state2.timestamp
+      && (!state2.operationId || state2.operationId.charAt(0) === 'S')) {
+        load(path, loader, globalState, state2.data);
+        loadTriggered = true; // eslint-disable-line react-hooks/exhaustive-deps
+      }
+    });
+
+    const deps = options.deps || [];
+    useEffect(() => { // eslint-disable-line react-hooks/rules-of-hooks
+      if (!loadTriggered && deps.length) load(path, loader, globalState, null);
+    }, deps); // eslint-disable-line react-hooks/exhaustive-deps
+  }
+
+  const [localState] = useGlobalState<ForceT, AsyncDataEnvelopeT<DataT>>(
+    path,
+    newAsyncDataEnvelope<DataT>(),
+  );
+
+  return {
+    data: maxage < Date.now() - localState.timestamp ? null : localState.data,
+    loading: Boolean(localState.operationId),
+    timestamp: localState.timestamp,
+  };
+}
+
+export default useAsyncData;