@oimdb/react 2.1.1 → 2.1.2

package/README.md

@@ -123,6 +123,38 @@ function TeamUsers({ teamId }: { teamId: string }) {
 - `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://abaikov.github.io/oimdb/docs/guides/performance) for when this actually pays off (in plain React the per-component commit usually dominates).
+
 ## Context API
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimdb/react",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "React integration for OIMDB - Hooks for selection and subscription with external storage",
   "type": "module",
   "main": "./dist/index.cjs",