@oimdb/core 3.7.0 → 3.9.0

package/README.md

@@ -185,6 +185,25 @@ const multipleUsers = users.getManyByPks(['user1', 'user2']);
 const userSlot = users.getSlotByPk('user1');
 ```
 
+#### Composite primary key
+
+Instead of a primitive PK, a collection can be keyed by a **composite key path** — an arbitrary-length tuple of primitive segments. Pass a trie-backed store:
+
+```typescript
+import { OIMReactiveCollection, OIMCollectionStoreTrieDriven, TOIMKeyPath } from '@oimdb/core';
+
+const memberships = new OIMReactiveCollection<Membership, TOIMKeyPath>(queue, {
+    selectPk: (m) => [m.userId, m.projectId],
+    store: new OIMCollectionStoreTrieDriven<Membership>(),
+});
+
+memberships.getOneByPk([1, 10]);        // matched by content — a fresh array works
+memberships.subscribeOnKey([1, 10], render);
+memberships.removeOneByPk([1, 10]);
+```
+
+Key paths match **by content** (the store interns each logical PK to one canonical `slot.pk`). Indexes work over such a collection too (`indexFactory.setBasedIndex()` indexes composite PKs). Primitive-PK collections keep the native-`Map` store untouched. At serialization boundaries a composite PK needs an `IOIMPkCodec` (`OIMPkCodecKeyPath`) — `@oimdb/persist`/`@oimdb/snapshot-manager` need none; `@oimdb/redux-adapter` takes it.
+
 ### Creating a Reactive Index
 
 OIMDB provides two types of indexes optimized for different use cases:
@@ -634,6 +653,24 @@ users.upsertOne({ id: 'user1', role: 'admin' });
 // This prevents unnecessary re-renders and improves performance
 ```
 
+### Disposing everything at once — `OIMDisposeScope`
+
+Teardown is LIFO: dispose dependents before what they depend on (indexes / streams / selectors → collection → queue). Instead of tracking that order by hand, register into an `OIMDisposeScope` as you build and tear it all down in one call:
+
+```typescript
+import { OIMDisposeScope, OIMEventQueue, OIMReactiveCollection } from '@oimdb/core';
+
+const scope = new OIMDisposeScope();
+const queue = scope.add(new OIMEventQueue());
+const users = scope.add(new OIMReactiveCollection(queue, { selectPk: u => u.id }));
+const byTeam = scope.add(usersIndexFactory.setBasedIndex());
+scope.add(selector.watch(render)); // bare unsubscribe fn works too
+
+scope.destroy(); // disposes byTeam → users → queue (reverse order), no bookkeeping
+```
+
+`add(x)` returns `x` for inline capture. Accepts both `{ destroy(): void }` objects and bare `() => void` unsubscribe functions (selectors, per-key subscriptions and scheduler tasks expose only the latter). Idempotent; every item is disposed even if one throws (first error rethrown after); `child()` nests a sub-scope. Factory: `createOIMDisposeScope()`. Related exports: `IOIMDisposable`, `TOIMDisposable`.
+
 ### Effects, Computed, and the Event Lifecycle
 
 OIMDB uses a single-pass flush boundary: `queue.flush()` executes the current batch of pending work.
@@ -1361,6 +1398,8 @@ createOIMCollectionIndexFactory(queue, collection)
 
 **Methods:**
 - `setBasedIndex<TKey>()` - Create `OIMReactiveCollectionIndexManualSetBased<TKey, TPk, TEntity>`
+- `compositeSetIndex()` - Create `OIMReactiveCollectionIndexCompositeTrieSetBased<TPk, TEntity>` — set-based index keyed by a composite **key path** (`TOIMKeyPath`, an arbitrary-length tuple of primitive segments, e.g. `setPks([projectId, role], pks)`). Matched by content in O(arity), no string concatenation. Primitive-keyed indexes keep their native-`Map` fast path.
+- `compositeArrayIndex()` - Create `OIMReactiveCollectionIndexCompositeTrieArrayBased<TPk, TEntity>` — ordered counterpart of `compositeSetIndex`, buckets are ordered slot arrays per key path.
 - `derivedSetIndex<TKey>(selectIndexKeys)` - Create `OIMDerivedCollectionIndexSetBased<TKey, TPk, TEntity>`
 - `arrayBasedIndex<TKey>()` - Create `OIMReactiveCollectionIndexManualArrayBased<TKey, TPk, TEntity>`
 - `derivedArrayIndex<TKey>(selectIndexKeys, { orderBy?, compareEntities? })` - Create `OIMDerivedCollectionIndexArrayBased<TKey, TPk, TEntity>`
@@ -1404,7 +1443,7 @@ new OIMReactiveCollectionIndexManualSetBased(queue: OIMEventQueue, opts: {
         store?: OIMIndexStoreSetBased<TKey, TPk>;
     };
 } | {
-    resolveSlot: TOIMEntitySlotResolver<TPk>;
+    getSlot: TOIMEntitySlotGetter<TPk>;
     indexOptions?: {
         comparePks?: TOIMIndexComparator<TPk>;
         store?: OIMIndexStoreSetBased<TKey, TPk>;
@@ -1412,7 +1451,7 @@ new OIMReactiveCollectionIndexManualSetBased(queue: OIMEventQueue, opts: {
 })
 ```
 
-Pass exactly one binding: `collection` for normal collection-bound indexes, or `resolveSlot` for custom slot resolution.
+Pass exactly one binding: `collection` for normal collection-bound indexes, or `getSlot` for custom slot lookup.
 
 **Methods:**
 - `setPks(key: TKey, pks: readonly TPk[]): void` - Set primary keys for index key
@@ -1502,7 +1541,7 @@ new OIMReactiveCollectionIndexManualArrayBased(queue: OIMEventQueue, opts: {
         store?: OIMIndexStoreArrayBased<TKey, TPk>;
     };
 } | {
-    resolveSlot: TOIMEntitySlotResolver<TPk>;
+    getSlot: TOIMEntitySlotGetter<TPk>;
     indexOptions?: {
         comparePks?: TOIMIndexComparator<TPk>;
         store?: OIMIndexStoreArrayBased<TKey, TPk>;
@@ -1510,7 +1549,7 @@ new OIMReactiveCollectionIndexManualArrayBased(queue: OIMEventQueue, opts: {
 })
 ```
 
-Pass exactly one binding: `collection` for normal collection-bound indexes, or `resolveSlot` for custom slot resolution.
+Pass exactly one binding: `collection` for normal collection-bound indexes, or `getSlot` for custom slot lookup.
 
 **Methods:**
 - `setPks(key: TKey, pks: readonly TPk[]): void` - Set primary keys for index key