@oimdb/react 2.1.1 → 2.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 React hooks and context helpers for OIMDB reactive collections, objects, and indexes.
 
-📖 **[Full documentation](https://abaikov.github.io/oimdb/)**
+📖 **[Full documentation](https://oimdb.org/)**
 
 ## For AI Assistants
 
@@ -118,11 +118,50 @@ function TeamUsers({ teamId }: { teamId: string }) {
 - `useSelectEntitiesByIndexKeyArrayBased(collection, index, key)` watches entities referenced by one index key.
 - `useSelectEntitiesByIndexKeysArrayBased(collection, index, keys)` watches entities referenced by several index keys.
 
+### Composite (Key-Path) Indexes
+
+For indexes keyed by a composite **key path** (an array, from `indexFactory.compositeSetIndex()` / `compositeArrayIndex()`). These stabilize the key path **by content**, so passing a freshly built `['p1', 'admin']` on every render does not re-subscribe.
+
+- `useSelectPksByCompositeIndexKeySetBased(index, path)` / `…ArrayBased(index, path)` watch PKs for one key path.
+- `useSelectEntitiesByCompositeIndexKeySetBased(collection, index, path)` / `…ArrayBased(collection, index, path)` watch entities for one key path.
+
 ### Reactive Objects
 
 - `useSelectValueByObjectKey(object, key)` watches one object key.
 - `useSelectValuesByObjectKeys(object, keys)` watches several object keys.
 
+All entity/index hooks return holes as `undefined` (`(TEntity | undefined)[]`), aligned 1:1 with the requested pks/keys — render with a guard (`user ? … : null`).
+
+## Mutable mode + signal hooks (advanced)
+
+The default hooks use `useSyncExternalStore`, which detects change by **reference** (`Object.is`). That requires the store to produce a new entity object per update — the default immutable merge (`{ ...prev, ...draft }`), whose copy is the biggest per-update data-layer cost.
+
+For update-heavy, fine-grained UIs you can run a collection in **in-place / mutable** mode and bind it with the lighter **signal hooks**:
+
+```tsx
+import { OIMReactiveCollection, createInPlaceEntityUpdater } from '@oimdb/core';
+import {
+  useSelectEntityByPkSignal,
+  useSelectPksByIndexKeyArrayBasedSignal,
+  useSelectPksByIndexKeySetBasedSignal,
+} from '@oimdb/react';
+
+// Mutate entities in place — no per-update object allocation.
+const cards = new OIMReactiveCollection<Card, string>(queue, {
+  selectPk: (c) => c.id,
+  updateEntity: createInPlaceEntityUpdater(),
+});
+
+// Signal hooks re-render on the keyed notification (no Object.is), so they see
+// in-place mutations the default uSES hooks would miss.
+const card = useSelectEntityByPkSignal(cards, id);
+const ids = useSelectPksByIndexKeyArrayBasedSignal(cardsByDeck, deckId);
+```
+
+Available signal hooks (same signatures as their default counterparts): `useSelectEntityByPkSignal`, `useSelectPksByIndexKeyArrayBasedSignal`, `useSelectPksByIndexKeySetBasedSignal`. Compose the fine-grained pattern from them: a parent reads pks by index key, each row reads its own entity by pk.
+
+**Use only when every reader is subscription-driven.** Trade-offs: not Concurrent-Mode tearing-safe; the entity reference is stable across changes, so `React.memo` on entities, prev/next diffing, time-travel, and the default uSES hooks on the same collection won't see updates. Select each entity where you render it (by pk); don't pass mutable entities into `React.memo` children. See [Performance](https://oimdb.org/docs/guides/performance) for when this actually pays off (in plain React the per-component commit usually dominates).
+
 ## Context API
 
 ```typescript

package/dist/index.cjs

@@ -24,6 +24,10 @@ __export(index_exports, {
   OIMCollectionsProvider: () => OIMCollectionsProvider,
   createOIMCollectionsContext: () => createOIMCollectionsContext,
   useOIMCollectionsContext: () => useOIMCollectionsContext,
+  useSelectEntitiesByCompositeIndexKeyArrayBased: () => useSelectEntitiesByCompositeIndexKeyArrayBased,
+  useSelectEntitiesByCompositeIndexKeySetBased: () => useSelectEntitiesByCompositeIndexKeySetBased,
+  useSelectEntitiesByGlobalIndexArrayBased: () => useSelectEntitiesByGlobalIndexArrayBased,
+  useSelectEntitiesByGlobalIndexSetBased: () => useSelectEntitiesByGlobalIndexSetBased,
   useSelectEntitiesByIndexKeyArrayBased: () => useSelectEntitiesByIndexKeyArrayBased,
   useSelectEntitiesByIndexKeySetBased: () => useSelectEntitiesByIndexKeySetBased,
   useSelectEntitiesByIndexKeysArrayBased: () => useSelectEntitiesByIndexKeysArrayBased,
@@ -31,6 +35,12 @@ __export(index_exports, {
   useSelectEntitiesByPks: () => useSelectEntitiesByPks,
   useSelectEntityByPk: () => useSelectEntityByPk,
   useSelectEntityByPkSignal: () => useSelectEntityByPkSignal,
+  useSelectPksByCompositeIndexKeyArrayBased: () => useSelectPksByCompositeIndexKeyArrayBased,
+  useSelectPksByCompositeIndexKeySetBased: () => useSelectPksByCompositeIndexKeySetBased,
+  useSelectPksByGlobalIndexArrayBased: () => useSelectPksByGlobalIndexArrayBased,
+  useSelectPksByGlobalIndexArrayBasedSignal: () => useSelectPksByGlobalIndexArrayBasedSignal,
+  useSelectPksByGlobalIndexSetBased: () => useSelectPksByGlobalIndexSetBased,
+  useSelectPksByGlobalIndexSetBasedSignal: () => useSelectPksByGlobalIndexSetBasedSignal,
   useSelectPksByIndexKeyArrayBased: () => useSelectPksByIndexKeyArrayBased,
   useSelectPksByIndexKeyArrayBasedSignal: () => useSelectPksByIndexKeyArrayBasedSignal,
   useSelectPksByIndexKeySetBased: () => useSelectPksByIndexKeySetBased,
@@ -43,14 +53,121 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/hooks/index.ts
-var import_react2 = require("react");
 var import_react3 = require("react");
+var import_react4 = require("react");
 
-// src/hooks/signal.ts
+// src/hooks/global.ts
 var import_react = require("react");
-var useIsomorphicLayoutEffect = typeof window !== "undefined" ? import_react.useLayoutEffect : import_react.useEffect;
+var useSelectPksByGlobalIndexArrayBased = (reactiveIndex) => {
+  const snapshotValueRef = (0, import_react.useRef)();
+  const subscribe = (0, import_react.useMemo)(() => {
+    snapshotValueRef.current = reactiveIndex.getPks();
+    return (onStoreChange) => {
+      return reactiveIndex.subscribe(() => {
+        snapshotValueRef.current = reactiveIndex.getPks();
+        onStoreChange();
+      });
+    };
+  }, [reactiveIndex]);
+  const getSnapshot = (0, import_react.useMemo)(() => () => snapshotValueRef.current, []);
+  return (0, import_react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+};
+var useSelectPksByGlobalIndexSetBased = (reactiveIndex) => {
+  const snapshotValueRef = (0, import_react.useRef)();
+  const subscribe = (0, import_react.useMemo)(() => {
+    snapshotValueRef.current = reactiveIndex.getPks();
+    return (onStoreChange) => {
+      return reactiveIndex.subscribe(() => {
+        snapshotValueRef.current = reactiveIndex.getPks();
+        onStoreChange();
+      });
+    };
+  }, [reactiveIndex]);
+  const getSnapshot = (0, import_react.useMemo)(() => () => snapshotValueRef.current, []);
+  return (0, import_react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+};
+var useSelectEntitiesByGlobalIndexArrayBased = (reactiveCollection, reactiveIndex) => {
+  const snapshotRef = (0, import_react.useRef)();
+  const subscribe = (0, import_react.useMemo)(() => {
+    const readPks = () => reactiveIndex.getPks();
+    const readSnapshot = () => readPks().map((pk) => reactiveCollection.getOneByPk(pk));
+    snapshotRef.current = readSnapshot();
+    return (onStoreChange) => {
+      let unsubscribeFromCollection = reactiveCollection.subscribeOnKeys(
+        readPks(),
+        () => {
+          snapshotRef.current = readSnapshot();
+          onStoreChange();
+        }
+      );
+      const resubscribeCollection = () => {
+        unsubscribeFromCollection();
+        unsubscribeFromCollection = reactiveCollection.subscribeOnKeys(
+          readPks(),
+          () => {
+            snapshotRef.current = readSnapshot();
+            onStoreChange();
+          }
+        );
+      };
+      const unsubscribeFromIndex = reactiveIndex.subscribe(() => {
+        resubscribeCollection();
+        snapshotRef.current = readSnapshot();
+        onStoreChange();
+      });
+      return () => {
+        unsubscribeFromIndex();
+        unsubscribeFromCollection();
+      };
+    };
+  }, [reactiveCollection, reactiveIndex]);
+  const getSnapshot = (0, import_react.useMemo)(() => () => snapshotRef.current, []);
+  return (0, import_react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+};
+var useSelectEntitiesByGlobalIndexSetBased = (reactiveCollection, reactiveIndex) => {
+  const snapshotRef = (0, import_react.useRef)();
+  const subscribe = (0, import_react.useMemo)(() => {
+    const readPks = () => Array.from(reactiveIndex.getPks());
+    const readSnapshot = () => readPks().map((pk) => reactiveCollection.getOneByPk(pk));
+    snapshotRef.current = readSnapshot();
+    return (onStoreChange) => {
+      let unsubscribeFromCollection = reactiveCollection.subscribeOnKeys(
+        readPks(),
+        () => {
+          snapshotRef.current = readSnapshot();
+          onStoreChange();
+        }
+      );
+      const resubscribeCollection = () => {
+        unsubscribeFromCollection();
+        unsubscribeFromCollection = reactiveCollection.subscribeOnKeys(
+          readPks(),
+          () => {
+            snapshotRef.current = readSnapshot();
+            onStoreChange();
+          }
+        );
+      };
+      const unsubscribeFromIndex = reactiveIndex.subscribe(() => {
+        resubscribeCollection();
+        snapshotRef.current = readSnapshot();
+        onStoreChange();
+      });
+      return () => {
+        unsubscribeFromIndex();
+        unsubscribeFromCollection();
+      };
+    };
+  }, [reactiveCollection, reactiveIndex]);
+  const getSnapshot = (0, import_react.useMemo)(() => () => snapshotRef.current, []);
+  return (0, import_react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+};
+
+// src/hooks/signal.ts
+var import_react2 = require("react");
+var useIsomorphicLayoutEffect = typeof window !== "undefined" ? import_react2.useLayoutEffect : import_react2.useEffect;
 function useForceUpdate() {
-  const [, force] = (0, import_react.useReducer)((c) => c + 1 | 0, 0);
+  const [, force] = (0, import_react2.useReducer)((c) => c + 1 | 0, 0);
   return force;
 }
 var useSelectEntityByPkSignal = (reactiveCollection, pk) => {
@@ -77,18 +194,34 @@ var useSelectPksByIndexKeySetBasedSignal = (reactiveIndex, key) => {
   );
   return reactiveIndex.getPksByKey(key);
 };
+var useSelectPksByGlobalIndexArrayBasedSignal = (reactiveIndex) => {
+  const force = useForceUpdate();
+  useIsomorphicLayoutEffect(
+    () => reactiveIndex.subscribe(force),
+    [reactiveIndex]
+  );
+  return reactiveIndex.getPks();
+};
+var useSelectPksByGlobalIndexSetBasedSignal = (reactiveIndex) => {
+  const force = useForceUpdate();
+  useIsomorphicLayoutEffect(
+    () => reactiveIndex.subscribe(force),
+    [reactiveIndex]
+  );
+  return reactiveIndex.getPks();
+};
 
 // src/hooks/index.ts
 var EMPTY_ARRAY = [];
 var useSelectPksByIndexKeysSetBased = (reactiveIndex, keys) => {
-  const prevKeysRef = (0, import_react2.useRef)();
+  const prevKeysRef = (0, import_react3.useRef)();
   const keysAreEqual = arraysEqual(prevKeysRef.current || EMPTY_ARRAY, keys);
   if (!keysAreEqual) {
     prevKeysRef.current = keys;
   }
   const stableKeys = keysAreEqual ? prevKeysRef.current ?? keys : keys;
-  const snapshotValueRef = (0, import_react2.useRef)();
-  const subscribe = (0, import_react2.useMemo)(() => {
+  const snapshotValueRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
     snapshotValueRef.current = stableKeys.map((key) => Array.from(reactiveIndex.getPksByKey(key))).flat();
     return (onStoreChange) => {
       const updateSnapshot = () => {
@@ -104,17 +237,17 @@ var useSelectPksByIndexKeysSetBased = (reactiveIndex, keys) => {
       };
     };
   }, [reactiveIndex, stableKeys]);
-  const getSnapshot = (0, import_react2.useMemo)(() => {
+  const getSnapshot = (0, import_react3.useMemo)(() => {
     return () => {
       return snapshotValueRef.current;
     };
   }, []);
-  const snapshot = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const snapshot = (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
   return snapshot;
 };
 var useSelectPksByIndexKeySetBased = (reactiveIndex, key) => {
-  const snapshotValueRef = (0, import_react2.useRef)();
-  const subscribe = (0, import_react2.useMemo)(() => {
+  const snapshotValueRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
     snapshotValueRef.current = reactiveIndex.getPksByKey(key);
     return (onStoreChange) => {
       const updateSnapshot = () => {
@@ -124,23 +257,23 @@ var useSelectPksByIndexKeySetBased = (reactiveIndex, key) => {
       return reactiveIndex.subscribeOnKey(key, updateSnapshot);
     };
   }, [key, reactiveIndex]);
-  const getSnapshot = (0, import_react2.useMemo)(() => {
+  const getSnapshot = (0, import_react3.useMemo)(() => {
     return () => {
       return snapshotValueRef.current;
     };
   }, []);
-  const snapshot = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const snapshot = (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
   return snapshot;
 };
 var useSelectPksByIndexKeysArrayBased = (reactiveIndex, keys) => {
-  const prevKeysRef = (0, import_react2.useRef)();
+  const prevKeysRef = (0, import_react3.useRef)();
   const keysAreEqual = arraysEqual(prevKeysRef.current || EMPTY_ARRAY, keys);
   if (!keysAreEqual) {
     prevKeysRef.current = keys;
   }
   const stableKeys = keysAreEqual ? prevKeysRef.current ?? keys : keys;
-  const snapshotValueRef = (0, import_react2.useRef)();
-  const subscribe = (0, import_react2.useMemo)(() => {
+  const snapshotValueRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
     snapshotValueRef.current = stableKeys.map((key) => reactiveIndex.getPksByKey(key)).flat();
     return (onStoreChange) => {
       const updateSnapshot = () => {
@@ -156,22 +289,22 @@ var useSelectPksByIndexKeysArrayBased = (reactiveIndex, keys) => {
       };
     };
   }, [reactiveIndex, stableKeys]);
-  const getSnapshot = (0, import_react2.useMemo)(() => {
+  const getSnapshot = (0, import_react3.useMemo)(() => {
     return () => {
       return snapshotValueRef.current;
     };
   }, []);
-  const snapshot = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const snapshot = (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
   return snapshot;
 };
 var useSelectPksByIndexKeyArrayBased = (reactiveIndex, key) => {
-  const prevKeyRef = (0, import_react2.useRef)();
+  const prevKeyRef = (0, import_react3.useRef)();
   const keyAreEqual = prevKeyRef.current === key;
   if (!keyAreEqual) {
     prevKeyRef.current = key;
   }
-  const snapshotValueRef = (0, import_react2.useRef)();
-  const subscribe = (0, import_react2.useMemo)(() => {
+  const snapshotValueRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
     snapshotValueRef.current = reactiveIndex.getPksByKey(key);
     return (onStoreChange) => {
       const prevKey = prevKeyRef.current;
@@ -192,49 +325,49 @@ var useSelectPksByIndexKeyArrayBased = (reactiveIndex, key) => {
       };
     };
   }, [key, reactiveIndex]);
-  const getSnapshot = (0, import_react2.useMemo)(() => {
+  const getSnapshot = (0, import_react3.useMemo)(() => {
     return () => {
       return snapshotValueRef.current;
     };
   }, []);
-  const snapshot = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const snapshot = (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
   return snapshot;
 };
 var useSelectEntityByPk = (reactiveCollection, pk) => {
-  const getSnapshot = (0, import_react2.useMemo)(
+  const getSnapshot = (0, import_react3.useMemo)(
     () => () => reactiveCollection.getOneByPk(pk),
     [pk, reactiveCollection]
   );
-  const subscribe = (0, import_react2.useMemo)(() => {
+  const subscribe = (0, import_react3.useMemo)(() => {
     return (onStoreChange) => {
       return reactiveCollection.subscribeOnKey(pk, onStoreChange);
     };
   }, [pk, reactiveCollection]);
-  const snapshot = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const snapshot = (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
   return snapshot;
 };
 var useSelectValueByObjectKey = (reactiveObject, key) => {
-  const getSnapshot = (0, import_react2.useMemo)(
+  const getSnapshot = (0, import_react3.useMemo)(
     () => () => reactiveObject.get(key),
     [key, reactiveObject]
   );
-  const subscribe = (0, import_react2.useMemo)(() => {
+  const subscribe = (0, import_react3.useMemo)(() => {
     return (onStoreChange) => {
       return reactiveObject.subscribeOnKey(key, onStoreChange);
     };
   }, [key, reactiveObject]);
-  const snapshot = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const snapshot = (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
   return snapshot;
 };
 var useSelectValuesByObjectKeys = (reactiveObject, keys) => {
-  const prevKeysRef = (0, import_react2.useRef)();
+  const prevKeysRef = (0, import_react3.useRef)();
   const keysAreEqual = arraysEqual(prevKeysRef.current || EMPTY_ARRAY, keys);
   if (!keysAreEqual) {
     prevKeysRef.current = keys;
   }
   const stableKeys = keysAreEqual ? prevKeysRef.current ?? keys : keys;
-  const snapshotRef = (0, import_react2.useRef)();
-  const subscribe = (0, import_react2.useMemo)(() => {
+  const snapshotRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
     snapshotRef.current = stableKeys.map((key) => reactiveObject.get(key));
     return (onStoreChange) => {
       const updateSnapshot = () => {
@@ -252,12 +385,12 @@ var useSelectValuesByObjectKeys = (reactiveObject, keys) => {
       };
     };
   }, [reactiveObject, stableKeys]);
-  const getSnapshot = (0, import_react2.useMemo)(() => {
+  const getSnapshot = (0, import_react3.useMemo)(() => {
     return () => {
       return snapshotRef.current;
     };
   }, []);
-  const snapshot = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const snapshot = (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
   return snapshot;
 };
 function arraysEqual(a, b) {
@@ -269,14 +402,14 @@ function arraysEqual(a, b) {
   return true;
 }
 var useSelectEntitiesByPks = (reactiveCollection, pks) => {
-  const prevPksRef = (0, import_react2.useRef)();
+  const prevPksRef = (0, import_react3.useRef)();
   const pksAreEqual = arraysEqual(prevPksRef.current || EMPTY_ARRAY, pks);
   if (!pksAreEqual) {
     prevPksRef.current = pks;
   }
   const stablePks = pksAreEqual ? prevPksRef.current ?? pks : pks;
-  const snapshotRef = (0, import_react2.useRef)();
-  const subscribe = (0, import_react2.useMemo)(() => {
+  const snapshotRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
     snapshotRef.current = stablePks.map(
       (pk) => reactiveCollection.getOneByPk(pk)
     );
@@ -296,17 +429,17 @@ var useSelectEntitiesByPks = (reactiveCollection, pks) => {
       };
     };
   }, [reactiveCollection, stablePks]);
-  const getSnapshot = (0, import_react2.useMemo)(() => {
+  const getSnapshot = (0, import_react3.useMemo)(() => {
     return () => {
       return snapshotRef.current;
     };
   }, []);
-  const snapshot = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const snapshot = (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
   return snapshot;
 };
 var useSelectEntitiesByIndexKeySetBased = (reactiveCollection, reactiveIndex, key) => {
-  const snapshotRef = (0, import_react2.useRef)();
-  const subscribe = (0, import_react2.useMemo)(() => {
+  const snapshotRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
     const readSnapshot = () => Array.from(
       reactiveIndex.getPksByKey(key),
       (pk) => reactiveCollection.getOneByPk(pk)
@@ -339,18 +472,18 @@ var useSelectEntitiesByIndexKeySetBased = (reactiveCollection, reactiveIndex, ke
       };
     };
   }, [key, reactiveCollection, reactiveIndex]);
-  const getSnapshot = (0, import_react2.useMemo)(() => () => snapshotRef.current, []);
-  return (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const getSnapshot = (0, import_react3.useMemo)(() => () => snapshotRef.current, []);
+  return (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
 };
 var useSelectEntitiesByIndexKeysSetBased = (reactiveCollection, reactiveIndex, keys) => {
-  const prevKeysRef = (0, import_react2.useRef)();
+  const prevKeysRef = (0, import_react3.useRef)();
   const keysAreEqual = arraysEqual(prevKeysRef.current || EMPTY_ARRAY, keys);
   if (!keysAreEqual) {
     prevKeysRef.current = keys;
   }
   const stableKeys = keysAreEqual ? prevKeysRef.current ?? keys : keys;
-  const snapshotRef = (0, import_react2.useRef)();
-  const subscribe = (0, import_react2.useMemo)(() => {
+  const snapshotRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
     const readPks = () => stableKeys.flatMap(
       (key) => Array.from(reactiveIndex.getPksByKey(key))
     );
@@ -385,12 +518,12 @@ var useSelectEntitiesByIndexKeysSetBased = (reactiveCollection, reactiveIndex, k
       };
     };
   }, [reactiveCollection, reactiveIndex, stableKeys]);
-  const getSnapshot = (0, import_react2.useMemo)(() => () => snapshotRef.current, []);
-  return (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const getSnapshot = (0, import_react3.useMemo)(() => () => snapshotRef.current, []);
+  return (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
 };
 var useSelectEntitiesByIndexKeyArrayBased = (reactiveCollection, reactiveIndex, key) => {
-  const snapshotRef = (0, import_react2.useRef)();
-  const subscribe = (0, import_react2.useMemo)(() => {
+  const snapshotRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
     const readSnapshot = () => reactiveIndex.getPksByKey(key).map((pk) => reactiveCollection.getOneByPk(pk));
     const readPks = () => reactiveIndex.getPksByKey(key);
     snapshotRef.current = readSnapshot();
@@ -420,18 +553,18 @@ var useSelectEntitiesByIndexKeyArrayBased = (reactiveCollection, reactiveIndex,
       };
     };
   }, [key, reactiveCollection, reactiveIndex]);
-  const getSnapshot = (0, import_react2.useMemo)(() => () => snapshotRef.current, []);
-  return (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const getSnapshot = (0, import_react3.useMemo)(() => () => snapshotRef.current, []);
+  return (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
 };
 var useSelectEntitiesByIndexKeysArrayBased = (reactiveCollection, reactiveIndex, keys) => {
-  const prevKeysRef = (0, import_react2.useRef)();
+  const prevKeysRef = (0, import_react3.useRef)();
   const keysAreEqual = arraysEqual(prevKeysRef.current || EMPTY_ARRAY, keys);
   if (!keysAreEqual) {
     prevKeysRef.current = keys;
   }
   const stableKeys = keysAreEqual ? prevKeysRef.current ?? keys : keys;
-  const snapshotRef = (0, import_react2.useRef)();
-  const subscribe = (0, import_react2.useMemo)(() => {
+  const snapshotRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
     const readPks = () => stableKeys.flatMap((key) => reactiveIndex.getPksByKey(key));
     const readSnapshot = () => readPks().map((pk) => reactiveCollection.getOneByPk(pk));
     snapshotRef.current = readSnapshot();
@@ -464,18 +597,139 @@ var useSelectEntitiesByIndexKeysArrayBased = (reactiveCollection, reactiveIndex,
       };
     };
   }, [reactiveCollection, reactiveIndex, stableKeys]);
-  const getSnapshot = (0, import_react2.useMemo)(() => () => snapshotRef.current, []);
-  return (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const getSnapshot = (0, import_react3.useMemo)(() => () => snapshotRef.current, []);
+  return (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+};
+function useStableKeyPath(key) {
+  const prevRef = (0, import_react3.useRef)();
+  const equal = prevRef.current !== void 0 && arraysEqual(prevRef.current, key);
+  if (!equal) {
+    prevRef.current = key;
+  }
+  return equal ? prevRef.current : key;
+}
+var useSelectPksByCompositeIndexKeySetBased = (reactiveIndex, key) => {
+  const stableKey = useStableKeyPath(key);
+  const snapshotValueRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
+    snapshotValueRef.current = reactiveIndex.getPksByKey(stableKey);
+    return (onStoreChange) => {
+      const updateSnapshot = () => {
+        snapshotValueRef.current = reactiveIndex.getPksByKey(stableKey);
+        onStoreChange();
+      };
+      return reactiveIndex.subscribeOnKey(stableKey, updateSnapshot);
+    };
+  }, [stableKey, reactiveIndex]);
+  const getSnapshot = (0, import_react3.useMemo)(() => () => snapshotValueRef.current, []);
+  return (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+};
+var useSelectPksByCompositeIndexKeyArrayBased = (reactiveIndex, key) => {
+  const stableKey = useStableKeyPath(key);
+  const snapshotValueRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
+    snapshotValueRef.current = reactiveIndex.getPksByKey(stableKey);
+    return (onStoreChange) => {
+      const updateSnapshot = () => {
+        snapshotValueRef.current = reactiveIndex.getPksByKey(stableKey);
+        onStoreChange();
+      };
+      return reactiveIndex.subscribeOnKey(stableKey, updateSnapshot);
+    };
+  }, [stableKey, reactiveIndex]);
+  const getSnapshot = (0, import_react3.useMemo)(() => () => snapshotValueRef.current, []);
+  return (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+};
+var useSelectEntitiesByCompositeIndexKeySetBased = (reactiveCollection, reactiveIndex, key) => {
+  const stableKey = useStableKeyPath(key);
+  const snapshotRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
+    const readSnapshot = () => Array.from(
+      reactiveIndex.getPksByKey(stableKey),
+      (pk) => reactiveCollection.getOneByPk(pk)
+    );
+    const readPks = () => Array.from(reactiveIndex.getPksByKey(stableKey));
+    snapshotRef.current = readSnapshot();
+    return (onStoreChange) => {
+      let unsubscribeFromCollection = reactiveCollection.subscribeOnKeys(readPks(), () => {
+        snapshotRef.current = readSnapshot();
+        onStoreChange();
+      });
+      const resubscribeCollection = () => {
+        unsubscribeFromCollection();
+        unsubscribeFromCollection = reactiveCollection.subscribeOnKeys(
+          readPks(),
+          () => {
+            snapshotRef.current = readSnapshot();
+            onStoreChange();
+          }
+        );
+      };
+      const unsubscribeFromIndex = reactiveIndex.subscribeOnKey(
+        stableKey,
+        () => {
+          resubscribeCollection();
+          snapshotRef.current = readSnapshot();
+          onStoreChange();
+        }
+      );
+      return () => {
+        unsubscribeFromIndex();
+        unsubscribeFromCollection();
+      };
+    };
+  }, [stableKey, reactiveCollection, reactiveIndex]);
+  const getSnapshot = (0, import_react3.useMemo)(() => () => snapshotRef.current, []);
+  return (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+};
+var useSelectEntitiesByCompositeIndexKeyArrayBased = (reactiveCollection, reactiveIndex, key) => {
+  const stableKey = useStableKeyPath(key);
+  const snapshotRef = (0, import_react3.useRef)();
+  const subscribe = (0, import_react3.useMemo)(() => {
+    const readSnapshot = () => reactiveIndex.getPksByKey(stableKey).map((pk) => reactiveCollection.getOneByPk(pk));
+    const readPks = () => reactiveIndex.getPksByKey(stableKey);
+    snapshotRef.current = readSnapshot();
+    return (onStoreChange) => {
+      let unsubscribeFromCollection = reactiveCollection.subscribeOnKeys(readPks(), () => {
+        snapshotRef.current = readSnapshot();
+        onStoreChange();
+      });
+      const resubscribeCollection = () => {
+        unsubscribeFromCollection();
+        unsubscribeFromCollection = reactiveCollection.subscribeOnKeys(
+          readPks(),
+          () => {
+            snapshotRef.current = readSnapshot();
+            onStoreChange();
+          }
+        );
+      };
+      const unsubscribeFromIndex = reactiveIndex.subscribeOnKey(
+        stableKey,
+        () => {
+          resubscribeCollection();
+          snapshotRef.current = readSnapshot();
+          onStoreChange();
+        }
+      );
+      return () => {
+        unsubscribeFromIndex();
+        unsubscribeFromCollection();
+      };
+    };
+  }, [stableKey, reactiveCollection, reactiveIndex]);
+  const getSnapshot = (0, import_react3.useMemo)(() => () => snapshotRef.current, []);
+  return (0, import_react4.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
 };
 
 // src/context/index.tsx
-var import_react4 = require("react");
+var import_react5 = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
-var OIMCollectionsContext = (0, import_react4.createContext)(
+var OIMCollectionsContext = (0, import_react5.createContext)(
   {}
 );
 function createOIMCollectionsContext() {
-  return (0, import_react4.createContext)({});
+  return (0, import_react5.createContext)({});
 }
 function OIMCollectionsProvider({ collections, children, context }) {
   const ContextToUse = context || OIMCollectionsContext;
@@ -483,7 +737,7 @@ function OIMCollectionsProvider({ collections, children, context }) {
 }
 function useOIMCollectionsContext(context) {
   const contextToUse = context || OIMCollectionsContext;
-  const collections = (0, import_react4.useContext)(contextToUse);
+  const collections = (0, import_react5.useContext)(contextToUse);
   if (!collections || Object.keys(collections).length === 0) {
     throw new Error(
       "useOIMCollectionsContext must be used within an OIMCollectionsProvider"
@@ -497,6 +751,10 @@ function useOIMCollectionsContext(context) {
   OIMCollectionsProvider,
   createOIMCollectionsContext,
   useOIMCollectionsContext,
+  useSelectEntitiesByCompositeIndexKeyArrayBased,
+  useSelectEntitiesByCompositeIndexKeySetBased,
+  useSelectEntitiesByGlobalIndexArrayBased,
+  useSelectEntitiesByGlobalIndexSetBased,
   useSelectEntitiesByIndexKeyArrayBased,
   useSelectEntitiesByIndexKeySetBased,
   useSelectEntitiesByIndexKeysArrayBased,
@@ -504,6 +762,12 @@ function useOIMCollectionsContext(context) {
   useSelectEntitiesByPks,
   useSelectEntityByPk,
   useSelectEntityByPkSignal,
+  useSelectPksByCompositeIndexKeyArrayBased,
+  useSelectPksByCompositeIndexKeySetBased,
+  useSelectPksByGlobalIndexArrayBased,
+  useSelectPksByGlobalIndexArrayBasedSignal,
+  useSelectPksByGlobalIndexSetBased,
+  useSelectPksByGlobalIndexSetBasedSignal,
   useSelectPksByIndexKeyArrayBased,
   useSelectPksByIndexKeyArrayBasedSignal,
   useSelectPksByIndexKeySetBased,