@dr.pogodin/react-global-state 0.18.0 → 0.19.0

package/src/GlobalState.ts

@@ -1,342 +0,0 @@
-import {
-  get,
-  isFunction,
-  isObject,
-  isNil,
-  set,
-  toPath,
-} from 'lodash';
-
-import SsrContext from './SsrContext';
-
-import {
-  type CallbackT,
-  type ForceT,
-  type LockT,
-  type TypeLock,
-  type ValueAtPathT,
-  type ValueOrInitializerT,
-  cloneDeepForLog,
-  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,
-  SsrContextT extends SsrContext<StateT> = SsrContext<StateT>,
-> {
-  readonly ssrContext?: SsrContextT;
-
-  #asyncDataAbortCallbacks: Record<string, () => void> = {};
-
-  #dependencies: { [key: string]: Readonly<any[]> } = {};
-
-  #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?: SsrContextT,
-  ) {
-    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:', cloneDeepForLog(initialState));
-      console.groupEnd();
-      /* eslint-enable no-console */
-    }
-  }
-
-  /**
-   * Returns the number of currently registered async data abort callbacks,
-   * just for the sake of testing the library.
-   */
-  get numAsyncDataAbortCallbacks(): number {
-    return Object.keys(this.#asyncDataAbortCallbacks).length;
-  }
-
-  /**
-   * If `aborted` is "true" and there is an abort callback registered for
-   * the specified operation, it triggers the callback. Then, in any case,
-   * it drops the callback.
-   */
-  asyncDataLoadDone(opid: string, aborted: boolean) {
-    if (aborted) this.#asyncDataAbortCallbacks[opid]?.();
-    delete this.#asyncDataAbortCallbacks[opid];
-  }
-
-  /**
-   * Drops the record of dependencies, if any, for the given path.
-   */
-  dropDependencies(path: string) {
-    delete this.#dependencies[path];
-  }
-
-  /**
-   * Checks if given `deps` are different from previously recorded ones for
-   * the given `path`. If they are, `deps` are recorded as the new deps for
-   * the `path`, and also the array is frozen, to prevent it from being
-   * modified.
-   *
-   * TODO: This may not work as expected if path string is not normalized,
-   * and the for the same path different alternative ways to spell it down
-   * are used. We should normalize given path here, I guess, or on a higher
-   * level in the logic?
-   */
-  hasChangedDependencies(path: string, deps: any[]): boolean {
-    const prevDeps = this.#dependencies[path];
-    let changed = !prevDeps || prevDeps.length !== deps.length;
-    for (let i = 0; !changed && i < deps.length; ++i) {
-      changed = prevDeps![i] !== deps[i];
-    }
-    this.#dependencies[path] = Object.freeze(deps);
-    return changed;
-  }
-
-  /**
-   * 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:', cloneDeepForLog(value, path ?? ''));
-      console.log('New state:', cloneDeepForLog(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]!();
-        }
-      });
-    }
-  }
-
-  /**
-   * Registers an abort callback for an async data retrieval operation with
-   * the given operation ID. Throws if already registered.
-   */
-  setAsyncDataAbortCallback(opid: string, cb: () => void) {
-    this.#asyncDataAbortCallbacks[opid] = cb;
-  }
-
-  /**
-   * 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<Forced extends ForceT | LockT = LockT, ValueT = void>(
-    path?: null | string,
-    opts?: GetOptsT<TypeLock<Forced, never, ValueT>>,
-  ): TypeLock<Forced, 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<ForceT, 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<Forced extends ForceT | LockT = LockT, ValueT = never>(
-    path: null | string | undefined,
-    value: TypeLock<Forced, never, ValueT>,
-  ): TypeLock<Forced, 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

@@ -1,117 +0,0 @@
-import { isFunction } from 'lodash';
-
-import {
-  type ReactNode,
-  createContext,
-  use,
-  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 = use(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.
- */
-const GlobalStateProvider = <
-  StateT,
-  SsrContextT extends SsrContext<StateT> = SsrContext<StateT>,
->({ children, ...rest }: GlobalStateProviderProps<StateT, SsrContextT>) => {
-  const state = useRef<GlobalState<StateT, SsrContextT>>(undefined);
-  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 value={state.current}>{children}</Context>;
-};
-
-export default GlobalStateProvider;

package/src/SsrContext.ts

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

package/src/index.ts

@@ -1,84 +0,0 @@
-import GlobalState from './GlobalState';
-
-import GlobalStateProvider, {
-  getGlobalState,
-  getSsrContext,
-} from './GlobalStateProvider';
-
-import SsrContext from './SsrContext';
-
-import useAsyncCollection, {
-  type UseAsyncCollectionI,
-  type UseAsyncCollectionResT,
-} from './useAsyncCollection';
-
-import {
-  type AsyncDataEnvelopeT,
-  type AsyncDataLoaderT,
-  type AsyncDataReloaderT,
-  type UseAsyncDataI,
-  type UseAsyncDataOptionsT,
-  type UseAsyncDataResT,
-  newAsyncDataEnvelope,
-  useAsyncData,
-} from './useAsyncData';
-
-import useGlobalState, { type UseGlobalStateI } from './useGlobalState';
-
-export type { AsyncCollectionLoaderT, AsyncCollectionT } from './useAsyncCollection';
-
-export type { SetterT, UseGlobalStateResT } from './useGlobalState';
-
-export type { ForceT, ValueOrInitializerT } from './utils';
-
-export {
-  type AsyncDataEnvelopeT,
-  type AsyncDataLoaderT,
-  type AsyncDataReloaderT,
-  type UseAsyncCollectionResT,
-  type UseAsyncDataOptionsT,
-  type UseAsyncDataResT,
-  getGlobalState,
-  getSsrContext,
-  GlobalState,
-  GlobalStateProvider,
-  newAsyncDataEnvelope,
-  SsrContext,
-  useAsyncCollection,
-  useAsyncData,
-  useGlobalState,
-};
-
-interface API<
-  StateT,
-  SsrContextT extends SsrContext<StateT> = SsrContext<StateT>,
-> {
-  getGlobalState: typeof getGlobalState<StateT, SsrContextT>;
-  getSsrContext: typeof getSsrContext<SsrContextT>,
-  GlobalState: typeof GlobalState<StateT, SsrContextT>,
-  GlobalStateProvider: typeof GlobalStateProvider<StateT, SsrContextT>,
-  newAsyncDataEnvelope: typeof newAsyncDataEnvelope,
-  SsrContext: typeof SsrContext<StateT>,
-  useAsyncCollection: UseAsyncCollectionI<StateT>,
-  useAsyncData: UseAsyncDataI<StateT>,
-  useGlobalState: UseGlobalStateI<StateT>,
-}
-
-const api = {
-  getGlobalState,
-  getSsrContext,
-  GlobalState,
-  GlobalStateProvider,
-  newAsyncDataEnvelope,
-  SsrContext,
-  useAsyncCollection,
-  useAsyncData,
-  useGlobalState,
-};
-
-export function withGlobalStateType<
-  StateT,
-  SsrContextT extends SsrContext<StateT> = SsrContext<StateT>,
->() {
-  return api as API<StateT, SsrContextT>;
-}