@pixotope/react-context-store 0.5.0 → 0.7.0

package/src/store.tsx

@@ -10,11 +10,21 @@ import { shallowEqual } from "@pixotope/utils/comparison";
 
 const LIB_NAME = "@pixotope/react-context-store";
 
+/**
+ * A function used to compare two versions of selected state, to decide
+ * whether subscribers should be notified of a change.
+ * @param first - The previously selected state.
+ * @param second - The newly selected state.
+ * @returns `true` if the two values should be treated as equal (no update triggered), `false` otherwise.
+ */
 export type SelectorOptions<Selected> = (
   first: Selected,
   second: Selected
 ) => boolean;
 
+/**
+ * Options that configure the behavior of a store created with {@link createContextStore}.
+ */
 export type ContextOptions = {
   /**
    * If true, the store state will be preserved across mounts and un-mounts
@@ -29,8 +39,15 @@ export type ContextOptions = {
   compare?: SelectorOptions<unknown>;
 };
 
+/**
+ * The value accepted by a store's `set` function: either the next state
+ * directly, or an updater function that receives the previous state and
+ * returns the next state.
+ */
 export type SetterArgs<Store> = Store | ((prev: Store) => Store);
-type ExtractActionKeys<T> = {
+
+/** Maps an actions map (as passed to {@link createContextStore}) to the shape of the object returned by `useActions`. */
+export type ExtractActionKeys<T> = {
   [K in keyof T]: T[K] extends (
     stateProps: never,
     action: infer A
@@ -43,47 +60,105 @@ type ExtractActionKeys<T> = {
     : never;
 };
 
-type Prettify<T> = {
+/** Flattens an intersection/mapped type into a single object type, for cleaner hover tooltips. */
+export type Prettify<T> = {
   [K in keyof T]: T[K];
 } & {};
 
+/**
+ * The action argument passed to an action handler, wrapping its payload.
+ * Use this as the type of an action's second parameter to give the
+ * corresponding {@link createContextStore} action a typed payload, which is
+ * then reflected in the function returned by `useActions`.
+ * @typeParam Payload - The type of the action's payload. Defaults to `any`.
+ * @example
+ * ```tsx
+ * const store = createContextStore(initialState, {
+ *   incrementBy: ({ set, get }, action: ActionablePayload<number>) => {
+ *     set((prev) => ({ ...prev, count: get().count + action.payload }));
+ *   },
+ * });
+ * ```
+ */
 export type ActionablePayload<Payload = any> = {
   payload: Payload;
 };
 
-type StateActionProps<Store> = {
+/** The state accessors passed as the first argument to every action handler. */
+export type StateActionProps<Store> = {
+  /** Updates the store state. */
   set: (value: SetterArgs<Store>) => void;
+  /** Returns the current store state. */
   get: () => Store;
 };
 
-type Actions<Store> = {
+/**
+ * A map of action names to action handlers, as passed to {@link createContextStore}.
+ * Each handler receives {@link StateActionProps} for reading/writing the
+ * store, plus an {@link ActionablePayload} carrying any payload passed by the caller.
+ */
+export type Actions<Store> = {
   [key: string]: (
     stateProps: StateActionProps<Store>,
     action: ActionablePayload
   ) => void | Promise<void>;
 };
 
-type UseStoreReturnType<Store, SelectorOutput> = {
+/** The object returned by a store's `useStore` hook. */
+export type UseStoreReturnType<Store, SelectorOutput> = {
+  /** The currently selected state. Reading this subscribes the component to updates. */
   state: SelectorOutput;
+  /** Returns the currently selected state. Equivalent to reading `state`. */
   get: () => SelectorOutput;
+  /** Updates the store state. */
   set: (value: SetterArgs<Store>) => void;
+  /** Returns the entire store state, not just the selected slice. */
   selector: () => Store;
 };
 
-type ContextReturnType<Store, A extends Actions<Store>> = {
+/**
+ * The object returned by {@link createContextStore}: the `Provider`
+ * component plus the hooks and functions used to read, update and
+ * subscribe to the store.
+ */
+export type ContextReturnType<Store, A extends Actions<Store>> = {
+  /** Wraps the part of the component tree that should have access to the store. */
   Provider: React.FC<React.PropsWithChildren>;
+  /**
+   * Reads (a selection of) the store state from the nearest `Provider`,
+   * re-rendering the component whenever the selected state changes.
+   * @param selector - Selects the part of the store the component needs. Defaults to the entire store.
+   * @param options - A function used to compare the previous and next selected state. Defaults to the store's `compare` option, or shallow equality.
+   * @returns The selected state, plus functions to read and update the store.
+   */
   useStore: <SelectorOutput = Store>(
     selector?: (store: Store) => SelectorOutput,
     options?: SelectorOptions<SelectorOutput>
   ) => UseStoreReturnType<Store, SelectorOutput>;
+  /**
+   * Returns the actions passed to {@link createContextStore}, bound to the
+   * current store. Actions declared with an {@link ActionablePayload}
+   * parameter take a single payload argument; other actions take none.
+   */
   useActions: () => Prettify<ExtractActionKeys<A>>;
+  /**
+   * Returns a function to update the store state from the nearest
+   * `Provider`, without subscribing the component to store updates.
+   */
   useSetStore: () => (value: SetterArgs<Store>) => void;
-  useStoreSelector: () => () => Store;
+  /**
+   * Subscribes to store updates from outside the React component tree.
+   * @param selector - Selects the part of the store to watch.
+   * @param callback - Called with the selected state whenever it changes.
+   * @param options - A function used to compare the previous and next selected state. Defaults to shallow equality.
+   * @returns A function to remove the subscription.
+   */
   subscribe: <SelectorOutput = Store>(
     selector: (store: Store) => SelectorOutput,
     callback: (state: SelectorOutput) => void,
     options?: SelectorOptions<SelectorOutput>
   ) => () => void;
+  /** Removes a subscription created with `subscribe`. */
   unsubscribe: (callback: () => void) => void;
 };
 
@@ -91,6 +166,44 @@ function isFunction(value: any): value is (prev: any) => any {
   return typeof value === "function";
 }
 
+/**
+ * Creates a React context-based store: a `Provider` component plus hooks to
+ * read, update and subscribe to its state.
+ *
+ * Each call creates an independent store with its own React context, so the
+ * `Provider` and hooks returned by one call must always be used together.
+ * @typeParam Store - The shape of the store state.
+ * @typeParam A - The map of named actions available to update the store.
+ * @param args - Positional arguments: the `initialState` the store is initialized with, an
+ * optional `actions` map of named action handlers used to update the store (see
+ * {@link ActionablePayload} for actions that take a payload), and optional `options` to
+ * customize the store's behavior.
+ * @returns An object with a `Provider` component and hooks to read, update and subscribe to the store's state. See {@link ContextReturnType}.
+ * @example
+ * ```tsx
+ * const store = createContextStore(
+ *   { count: 0 },
+ *   {
+ *     increment: ({ set, get }) => set({ ...get(), count: get().count + 1 }),
+ *   }
+ * );
+ *
+ * function Counter() {
+ *   const { state: count } = store.useStore((state) => state.count);
+ *   const { increment } = store.useActions();
+ *
+ *   return <button onClick={() => increment()}>{count}</button>;
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <store.Provider>
+ *       <Counter />
+ *     </store.Provider>
+ *   );
+ * }
+ * ```
+ */
 export function createContextStore<Store, A extends Actions<Store> = Actions<Store>>(
   ...args: Extract<A, { payload: A }> extends { payload: infer Payload }
     ? [initialState: Store, actions?: A, options?: ContextOptions]
@@ -150,8 +263,12 @@ export function createContextStore<Store, A extends Actions<Store> = Actions<Sto
   const StoreContext = createContext<UseStoreDataReturnType | null>(null);
 
   /**
-   * This is the provider that will be used to wrap the react component tree
-   * to provide the store to all the components in the tree.
+   * Wraps the part of the component tree that should have access to the
+   * store. Must wrap any component using `useStore`, `useActions` or `useSetStore`.
+   * @remarks
+   * If the store was created with `{ global: true }`, state changes made
+   * while a `Provider` is mounted are preserved and restored the next time
+   * a `Provider` for this store mounts.
    */
   function Provider({ children }: React.PropsWithChildren) {
     return (
@@ -171,6 +288,13 @@ export function createContextStore<Store, A extends Actions<Store> = Actions<Sto
    */
   const observers = new Set<(state: Store) => void>();
 
+  /**
+   * Subscribes to store updates from outside the React component tree.
+   * @param selector - Selects the part of the store to watch. Defaults to the whole store.
+   * @param callback - Called with the selected state whenever it changes.
+   * @param compare - A function used to compare the previous and next selected state. Defaults to shallow equality.
+   * @returns A function to remove the subscription.
+   */
   function subscribeExternal<SelectorOutput = Store>(
     selector: (store: Store) => SelectorOutput = (store) =>
       store as unknown as SelectorOutput,
@@ -220,20 +344,24 @@ export function createContextStore<Store, A extends Actions<Store> = Actions<Sto
   } as const;
 
   /**
-   * This is the hook that will be used to access the store from any component
-   * in the react component tree.
-   * @param selector A function that will be used to select the part of the store
-   * that is needed by the component.
-   * @param options Options to customize the behavior of the hook.
-   * @returns An object with the selected state, a function to update the store
-   * and a function to get the entire store.
+   * Reads (a selection of) the store state from the nearest `Provider`,
+   * re-rendering the component whenever the selected state changes.
+   * @param selector - A function that selects the part of the store that is
+   * needed by the component. Defaults to the entire store.
+   * @param compare - A function used to compare the previous and next
+   * selected state; the component only re-renders when it returns `false`.
+   * Defaults to the store's `compare` option (see {@link ContextOptions}),
+   * or `shallowEqual` from `@pixotope/utils/comparison`.
+   * @returns An object containing the selected `state`, a `set` function to
+   * update the store, a `get` function equivalent to reading `state`, and a
+   * `selector` function to read the entire store without selecting.
    * @example
    * ```tsx
-   *  const { get, set } = useStore(store => store.user);
-   *  const { get, set } = useStore(store => store.user, { deepEqual: false });
-   *  const { get, set } = useStore(store => store.user, {
-   *      compare: (first, second) => first.id === second.id
-   *  });
+   * const { state, set } = store.useStore((store) => store.user);
+   * const { state, set } = store.useStore(
+   *   (store) => store.user,
+   *   (first, second) => first.id === second.id
+   * );
    * ```
    */
   function useStore<SelectorOutput = Store>(
@@ -275,6 +403,28 @@ export function createContextStore<Store, A extends Actions<Store> = Actions<Sto
     };
   }
 
+  /**
+   * Returns the actions passed to {@link createContextStore}, bound to the
+   * current store from the nearest `Provider`. Calling an action does not
+   * itself cause a re-render; only the state changes it makes (via `set`)
+   * do, and only for components subscribed to the affected state.
+   * @returns An object with one bound function per action. Actions declared
+   * with an {@link ActionablePayload} parameter take a single payload
+   * argument; other actions take no arguments.
+   * @example
+   * ```tsx
+   * const store = createContextStore(initialState, {
+   *   increment: ({ set, get }) => set({ ...get(), count: get().count + 1 }),
+   *   incrementBy: ({ set, get }, action: ActionablePayload<number>) =>
+   *     set({ ...get(), count: get().count + action.payload }),
+   * });
+   *
+   * function Counter() {
+   *   const { incrementBy } = store.useActions();
+   *   return <button onClick={() => incrementBy(5)}>+5</button>;
+   * }
+   * ```
+   */
   function useActions() {
     const store = useContext(StoreContext);
 
@@ -314,15 +464,24 @@ export function createContextStore<Store, A extends Actions<Store> = Actions<Sto
     return actionProxy as unknown as ExtractActionKeys<typeof actions>;
   }
 
+  /**
+   * Returns a function to update the store state from the nearest
+   * `Provider`, without subscribing the component to store updates.
+   * @returns A function that sets the store state, accepting either the
+   * next state directly or an updater function that receives the previous state.
+   * @example
+   * ```tsx
+   * const setStore = store.useSetStore();
+   * setStore((prev) => ({ ...prev, count: prev.count + 1 }));
+   * ```
+   */
   const useSetStore = () => useStore(() => false).set;
-  const useStoreSelector = () => useStore(() => false).selector;
 
   return {
     Provider,
     useStore,
     useSetStore,
     useActions,
-    useStoreSelector,
     subscribe: observable.subscribe,
     unsubscribe: observable.unsubscribe,
   };

package/typedoc.json

@@ -0,0 +1,3 @@
+{
+  "entryPoints": ["src/index.ts"]
+}