[hooks] useStores

Author: jamesgpearce

src/@types/ui-react/docs.js

@@ -397,6 +397,47 @@
  * @since v1.0.0
  */
 /// useStore
+/**
+ * The useStores hook is used to get a reference to all the Store objects named
+ * by Id within a Provider component context.
+ *
+ * A Provider component is used to wrap part of an application in a context. It
+ * can contain a default Store (or a set of Store objects named by Id) that can
+ * be easily accessed without having to be passed down as props through every
+ * component.
+ *
+ * The useStores hook lets you get a reference to the latter as an object.
+ * @returns An object containing all the Store objects named by Id.
+ * @example
+ * This example creates a Provider context into which a Store is provided, named
+ * by Id. A component within it then uses the useStores hook to get a reference
+ * to the Store again.
+ *
+ * ```jsx
+ * import {Provider, useStores} from 'tinybase/ui-react';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ *
+ * const App = ({store}) => (
+ *   <Provider storesById={{petStore: store}}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <span>{useStores()['petStore'].getListenerStats().tables}</span>
+ * );
+ *
+ * const store = createStore();
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App store={store} />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>0</span>'
+ * ```
+ * @category Store hooks
+ * @since v5.4.1
+ */
+/// useStores
 /**
  * The useStoreOrStoreById hook is used to get a reference to a Store object
  * from within a Provider component context, _or_ have it passed directly to

src/@types/ui-react/index.d.ts

@@ -130,6 +130,9 @@ export function useStoreIds(): Ids;
 /// useStore
 export function useStore(id?: Id): Store | undefined;
 
+/// useStores
+export function useStores(): {[storeId: Id]: Store};
+
 /// useStoreOrStoreById
 export function useStoreOrStoreById(
   storeOrStoreId?: StoreOrStoreId,

src/@types/ui-react/with-schemas/index.d.ts

@@ -178,6 +178,9 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
   /// useStore
   useStore: (id?: Id) => Store<Schemas> | undefined;
 
+  /// useStores
+  useStores: () => {[storeId: Id]: Store<OptionalSchemas>};
+
   /// useStoreOrStoreById
   useStoreOrStoreById: (
     storeOrStoreId?: StoreOrStoreId<Schemas>,

src/ui-react/context.ts

@@ -21,6 +21,7 @@ import type {
   useRelationshipsIds as useRelationshipsIdsDecl,
   useStore as useStoreDecl,
   useStoreIds as useStoreIdsDecl,
+  useStores as useStoresDecl,
   useSynchronizer as useSynchronizerDecl,
   useSynchronizerIds as useSynchronizerIdsDecl,
 } from '../@types/ui-react/index.d.ts';
@@ -118,6 +119,11 @@ const useThing = <UsedThing extends Thing>(
   ) as UsedThing;
 };
 
+const useThings = <UsedThing extends Thing>(
+  offset: Offsets,
+): IdObj<UsedThing> =>
+  ({...(useContext(Context)[offset * 2 + 1] ?? {})}) as IdObj<UsedThing>;
+
 const useThingOrThingById = <
   Thing extends
     | Store
@@ -159,6 +165,9 @@ export const useStoreIds: typeof useStoreIdsDecl = () =>
 export const useStore: typeof useStoreDecl = (id?: Id): Store | undefined =>
   useThing(id, Offsets.Store);
 
+export const useStores: typeof useStoresDecl = (): IdObj<Store> =>
+  useThings(Offsets.Store);
+
 export const useStoreOrStoreById = (
   storeOrStoreId?: StoreOrStoreId,
 ): Store | undefined => useThingOrThingById(storeOrStoreId, Offsets.Store);

src/ui-react/hooks.ts

@@ -302,6 +302,7 @@ export {
   useStore,
   useStoreIds,
   useStoreOrStoreById,
+  useStores,
   useSynchronizer,
   useSynchronizerIds,
   useSynchronizerOrSynchronizerById,

test/unit/core/ui-react/hooks.test.tsx

@@ -122,6 +122,7 @@ import {
   useStartTransactionListener,
   useStore,
   useStoreIds,
+  useStores,
   useTable,
   useTableCellIds,
   useTableCellIdsListener,
@@ -888,6 +889,22 @@ describe('Context Hooks', () => {
     expect(didRender).toHaveBeenCalledTimes(1);
   });
 
+  test('useStores', () => {
+    const Test = () =>
+      didRender(<>{JSON.stringify(useStores()?.['store1']?.getTables())}</>);
+    const store1 = createStore().setTables({t1: {r1: {c1: 2}}});
+    const store2 = createStore();
+    act(() => {
+      renderer = create(
+        <Provider storesById={{store1, store2}}>
+          <Test />
+        </Provider>,
+      );
+    });
+    expect(renderer.toJSON()).toEqual('{"t1":{"r1":{"c1":2}}}');
+    expect(didRender).toHaveBeenCalledTimes(1);
+  });
+
   test('useStoreIds', () => {
     const Test = () => didRender(<>{JSON.stringify(useStoreIds())}</>);
     const store1 = createStore();