@oimdb/core 3.2.0 → 3.3.0

package/README.md

@@ -546,6 +546,31 @@ users.upsertOne({ id: 'user1', name: 'John' });
 users.upsertOne({ id: 'user1', email: 'john@example.com' }); // Merges with existing
 ```
 
+#### Built-in updaters
+
+Two updater strategies ship as factories — pass the result as `updateEntity`:
+
+```typescript
+import { createMergeEntityUpdater, createInPlaceEntityUpdater } from '@oimdb/core';
+
+// Default: immutable shallow merge — `{ ...prev, ...draft }`. Each update produces
+// a NEW entity object (required for React's Object.is / useSyncExternalStore).
+const a = new OIMReactiveCollection<User, string>(queue, {
+    selectPk: (u) => u.id,
+    updateEntity: createMergeEntityUpdater(),
+});
+
+// In-place: `Object.assign(prev, draft)` — mutates the existing object, no
+// per-update allocation. The entity reference is STABLE across changes, so it
+// only works with subscription-driven readers (e.g. the `*Signal` hooks in
+// @oimdb/react), not with Object.is/React.memo diffing. Fastest on the data
+// layer for update-heavy workloads.
+const b = new OIMReactiveCollection<User, string>(queue, {
+    selectPk: (u) => u.id,
+    updateEntity: createInPlaceEntityUpdater(),
+});
+```
+
 ### Event Coalescing and Update Subscriptions
 
 ```typescript
@@ -1509,7 +1534,7 @@ new OIMIndexManualOrderedArrayBased<TKey, TPk>()
 **Query:**
 - `getPksByKey(key: TKey): TPk[]` - Returns the ordered primary-key array
 - `getSlotsByKey(key: TKey): readonly TOIMAnyEntitySlot<TPk>[]` - Returns the stored ordered slots
-- `getEntitiesByKey<TEntity>(key: TKey): TEntity[]` - Returns existing entities from stored slots
+- `getEntitiesByKey<TEntity>(key: TKey): (TEntity | undefined)[]` - Returns entities from stored slots, aligned 1:1 with the pks (holes are `undefined`)
 
 #### `OIMCollectionIndexManualOrderedArrayBased<TKey, TPk, TEntity>`
 Collection-bound ordered Array-based index. Use this when ordered PK writes should resolve to canonical slots from a collection.
@@ -1518,7 +1543,7 @@ Collection-bound ordered Array-based index. Use this when ordered PK writes shou
 - `push(key: TKey, pk: TPk): number` - Append a PK as its canonical slot
 - `insertAt(key: TKey, index: number, pk: TPk): number` - Insert a PK as its canonical slot
 - `reset(key: TKey, pks: readonly TPk[]): void` - Replace the whole ordered list from PKs
-- `getEntitiesByKey(key: TKey): TEntity[]` - Returns entities from canonical slots
+- `getEntitiesByKey(key: TKey): (TEntity | undefined)[]` - Returns entities from canonical slots (holes are `undefined`)
 
 #### `OIMOrderedListCommandStream<TKey, TPk, TEntity>`
 Slot-first ordered per-key list with a command stream for imperative consumers. It stores data in an `OIMIndexManualOrderedArrayBased` and emits `TOIMOrderedListCommand` batches through `commandsEventEmitter`.
@@ -1545,7 +1570,7 @@ new OIMOrderedListCommandStream(
 - `getBufferedCommands(key: TKey): readonly TOIMOrderedListCommand<TPk, TEntity>[]` - Peek at buffered commands without clearing them
 - `getPksByKey(key: TKey): readonly TPk[]` - Read the current ordered list
 - `getSlotsByKey(key: TKey): readonly TOIMEntitySlot<TEntity, TPk>[]` - Read current ordered slots
-- `getEntitiesByKey(key: TKey): TEntity[]` - Read current ordered entities
+- `getEntitiesByKey(key: TKey): (TEntity | undefined)[]` - Read current ordered entities (holes are `undefined`)
 - `clear(key?: TKey): void` - Clear all keys or a specific key
 - `destroy(): void` - Dispose subscriptions and clear state
 

package/dist/index.cjs

@@ -647,7 +647,7 @@ var OIMCarrierKeyedEmitter = class {
   }
   destroy() {
     if (this.isFlushEnqueued) {
-      this.queue.cancelTask(this.onFlush);
+      this.queue.cancel(this.onFlush);
       this.isFlushEnqueued = false;
     }
     this.subscribedCarriers.forEach((carrier) => {
@@ -671,7 +671,7 @@ var OIMCarrierKeyedEmitter = class {
   scheduleFlush() {
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.queue.enqueueTask(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   notify(carrier) {
     const subscribers = carrier.subscribers;
@@ -1236,12 +1236,12 @@ var OIMReactiveCollection = class extends OIMCollection {
   ensureAnyUpdateEnqueued() {
     if (this.isAnyUpdateScheduled) return;
     this.isAnyUpdateScheduled = true;
-    this.queue.enqueueTask(this.runAnyUpdate);
+    this.queue.enqueue(this.runAnyUpdate);
   }
   destroy() {
     this.updateEmitter.destroy();
     if (this.isAnyUpdateScheduled) {
-      this.queue.cancelTask(this.runAnyUpdate);
+      this.queue.cancel(this.runAnyUpdate);
       this.isAnyUpdateScheduled = false;
     }
     this.anyUpdateHandlers.clear();
@@ -1436,7 +1436,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.queue.enqueueTask(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   markUpdatedKey(key) {
     if (this.deliveryMode === "queue" && this.queue.isInFlush) {
@@ -1458,7 +1458,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.queue.enqueueTask(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   markAllUpdated() {
     if (this.deliveryMode === "queue" && this.queue.isInFlush) {
@@ -1480,7 +1480,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.queue.enqueueTask(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   deliverImmediate() {
     this.runSinglePass();
@@ -1529,7 +1529,7 @@ var OIMUpdateEventEmitter = class {
   }
   destroy() {
     if (this.isFlushEnqueued) {
-      this.queue.cancelTask(this.onFlush);
+      this.queue.cancel(this.onFlush);
       this.isFlushEnqueued = false;
     }
     if (this.unsubscribeAfterFlushDelivery) {
@@ -1589,7 +1589,7 @@ var OIMUpdateEventEmitter = class {
     if (this.keyHandlers.size === 0) {
       this.updatedKeys.clear();
       if (this.isFlushEnqueued) {
-        this.queue.cancelTask(this.onFlush);
+        this.queue.cancel(this.onFlush);
       }
       this.isFlushEnqueued = false;
     }
@@ -2737,48 +2737,23 @@ var OIMEventQueue = class {
     }
   }
   /**
-   * Enqueue a one-shot task to be executed on the next flush.
-   * Returns a dequeue function that can be called to cancel the task before it runs.
+   * Enqueue a one-shot task to run on the next flush. The function is stored
+   * directly (no wrapper, no returned closure) and cancelled via {@link cancel}
+   * by passing the same reference. Enqueuing the same reference twice is
+   * idempotent — it is Set-deduped and runs once per flush.
    */
   enqueue(fn) {
-    let isActive = true;
-    const task = () => {
-      if (!isActive) return;
-      fn();
-    };
-    this.tasks.add(task);
-    this.ensureScheduled();
-    return () => {
-      if (!isActive) return;
-      isActive = false;
-      this.tasks.delete(task);
-    };
-  }
-  /**
-   * Allocation-free enqueue for a **stable** function reference (e.g. a bound
-   * `onFlush` method). The function is stored directly — no wrapper, no
-   * returned closure — and cancelled via {@link cancelTask}. Enqueuing the
-   * same reference twice is idempotent (Set-deduped); callers that may run a
-   * task more than once per flush should use {@link enqueue} instead.
-   */
-  enqueueTask(fn) {
     this.tasks.add(fn);
     this.ensureScheduled();
   }
-  /** Cancel a task scheduled via {@link enqueueTask}; safe to call mid-flush. */
-  cancelTask(fn) {
+  /** Cancel a previously enqueued task by its reference; safe to call mid-flush. */
+  cancel(fn) {
     this.tasks.delete(fn);
     this.flushing?.delete(fn);
   }
   get isInFlush() {
     return this.isFlushing;
   }
-  /**
-   * Dequeue (cancel) a previously enqueued task by its dequeue function.
-   */
-  dequeue(dequeueFn) {
-    dequeueFn();
-  }
   /**
    * Execute all pending tasks.
    *

package/dist/index.d.cts

@@ -254,25 +254,15 @@ declare class OIMEventQueue {
     protected isFlushing: boolean;
     constructor(options?: TOIMEventQueueOptions);
     /**
-     * Enqueue a one-shot task to be executed on the next flush.
-     * Returns a dequeue function that can be called to cancel the task before it runs.
+     * Enqueue a one-shot task to run on the next flush. The function is stored
+     * directly (no wrapper, no returned closure) and cancelled via {@link cancel}
+     * by passing the same reference. Enqueuing the same reference twice is
+     * idempotent — it is Set-deduped and runs once per flush.
      */
-    enqueue(fn: () => void): () => void;
-    /**
-     * Allocation-free enqueue for a **stable** function reference (e.g. a bound
-     * `onFlush` method). The function is stored directly — no wrapper, no
-     * returned closure — and cancelled via {@link cancelTask}. Enqueuing the
-     * same reference twice is idempotent (Set-deduped); callers that may run a
-     * task more than once per flush should use {@link enqueue} instead.
-     */
-    enqueueTask(fn: () => void): void;
-    /** Cancel a task scheduled via {@link enqueueTask}; safe to call mid-flush. */
-    cancelTask(fn: () => void): void;
+    enqueue(fn: () => void): void;
+    /** Cancel a previously enqueued task by its reference; safe to call mid-flush. */
+    cancel(fn: () => void): void;
     get isInFlush(): boolean;
-    /**
-     * Dequeue (cancel) a previously enqueued task by its dequeue function.
-     */
-    dequeue(dequeueFn: () => void): void;
     /**
      * Execute all pending tasks.
      *

package/dist/index.d.ts

@@ -254,25 +254,15 @@ declare class OIMEventQueue {
     protected isFlushing: boolean;
     constructor(options?: TOIMEventQueueOptions);
     /**
-     * Enqueue a one-shot task to be executed on the next flush.
-     * Returns a dequeue function that can be called to cancel the task before it runs.
+     * Enqueue a one-shot task to run on the next flush. The function is stored
+     * directly (no wrapper, no returned closure) and cancelled via {@link cancel}
+     * by passing the same reference. Enqueuing the same reference twice is
+     * idempotent — it is Set-deduped and runs once per flush.
      */
-    enqueue(fn: () => void): () => void;
-    /**
-     * Allocation-free enqueue for a **stable** function reference (e.g. a bound
-     * `onFlush` method). The function is stored directly — no wrapper, no
-     * returned closure — and cancelled via {@link cancelTask}. Enqueuing the
-     * same reference twice is idempotent (Set-deduped); callers that may run a
-     * task more than once per flush should use {@link enqueue} instead.
-     */
-    enqueueTask(fn: () => void): void;
-    /** Cancel a task scheduled via {@link enqueueTask}; safe to call mid-flush. */
-    cancelTask(fn: () => void): void;
+    enqueue(fn: () => void): void;
+    /** Cancel a previously enqueued task by its reference; safe to call mid-flush. */
+    cancel(fn: () => void): void;
     get isInFlush(): boolean;
-    /**
-     * Dequeue (cancel) a previously enqueued task by its dequeue function.
-     */
-    dequeue(dequeueFn: () => void): void;
     /**
      * Execute all pending tasks.
      *

package/dist/index.js

@@ -545,7 +545,7 @@ var OIMCarrierKeyedEmitter = class {
   }
   destroy() {
     if (this.isFlushEnqueued) {
-      this.queue.cancelTask(this.onFlush);
+      this.queue.cancel(this.onFlush);
       this.isFlushEnqueued = false;
     }
     this.subscribedCarriers.forEach((carrier) => {
@@ -569,7 +569,7 @@ var OIMCarrierKeyedEmitter = class {
   scheduleFlush() {
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.queue.enqueueTask(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   notify(carrier) {
     const subscribers = carrier.subscribers;
@@ -1134,12 +1134,12 @@ var OIMReactiveCollection = class extends OIMCollection {
   ensureAnyUpdateEnqueued() {
     if (this.isAnyUpdateScheduled) return;
     this.isAnyUpdateScheduled = true;
-    this.queue.enqueueTask(this.runAnyUpdate);
+    this.queue.enqueue(this.runAnyUpdate);
   }
   destroy() {
     this.updateEmitter.destroy();
     if (this.isAnyUpdateScheduled) {
-      this.queue.cancelTask(this.runAnyUpdate);
+      this.queue.cancel(this.runAnyUpdate);
       this.isAnyUpdateScheduled = false;
     }
     this.anyUpdateHandlers.clear();
@@ -1334,7 +1334,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.queue.enqueueTask(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   markUpdatedKey(key) {
     if (this.deliveryMode === "queue" && this.queue.isInFlush) {
@@ -1356,7 +1356,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.queue.enqueueTask(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   markAllUpdated() {
     if (this.deliveryMode === "queue" && this.queue.isInFlush) {
@@ -1378,7 +1378,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.queue.enqueueTask(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   deliverImmediate() {
     this.runSinglePass();
@@ -1427,7 +1427,7 @@ var OIMUpdateEventEmitter = class {
   }
   destroy() {
     if (this.isFlushEnqueued) {
-      this.queue.cancelTask(this.onFlush);
+      this.queue.cancel(this.onFlush);
       this.isFlushEnqueued = false;
     }
     if (this.unsubscribeAfterFlushDelivery) {
@@ -1487,7 +1487,7 @@ var OIMUpdateEventEmitter = class {
     if (this.keyHandlers.size === 0) {
       this.updatedKeys.clear();
       if (this.isFlushEnqueued) {
-        this.queue.cancelTask(this.onFlush);
+        this.queue.cancel(this.onFlush);
       }
       this.isFlushEnqueued = false;
     }
@@ -2635,48 +2635,23 @@ var OIMEventQueue = class {
     }
   }
   /**
-   * Enqueue a one-shot task to be executed on the next flush.
-   * Returns a dequeue function that can be called to cancel the task before it runs.
+   * Enqueue a one-shot task to run on the next flush. The function is stored
+   * directly (no wrapper, no returned closure) and cancelled via {@link cancel}
+   * by passing the same reference. Enqueuing the same reference twice is
+   * idempotent — it is Set-deduped and runs once per flush.
    */
   enqueue(fn) {
-    let isActive = true;
-    const task = () => {
-      if (!isActive) return;
-      fn();
-    };
-    this.tasks.add(task);
-    this.ensureScheduled();
-    return () => {
-      if (!isActive) return;
-      isActive = false;
-      this.tasks.delete(task);
-    };
-  }
-  /**
-   * Allocation-free enqueue for a **stable** function reference (e.g. a bound
-   * `onFlush` method). The function is stored directly — no wrapper, no
-   * returned closure — and cancelled via {@link cancelTask}. Enqueuing the
-   * same reference twice is idempotent (Set-deduped); callers that may run a
-   * task more than once per flush should use {@link enqueue} instead.
-   */
-  enqueueTask(fn) {
     this.tasks.add(fn);
     this.ensureScheduled();
   }
-  /** Cancel a task scheduled via {@link enqueueTask}; safe to call mid-flush. */
-  cancelTask(fn) {
+  /** Cancel a previously enqueued task by its reference; safe to call mid-flush. */
+  cancel(fn) {
     this.tasks.delete(fn);
     this.flushing?.delete(fn);
   }
   get isInFlush() {
     return this.isFlushing;
   }
-  /**
-   * Dequeue (cancel) a previously enqueued task by its dequeue function.
-   */
-  dequeue(dequeueFn) {
-    dequeueFn();
-  }
   /**
    * Execute all pending tasks.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimdb/core",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Core in-memory data library with type-safe indices, reactive subscriptions, and event processing",
   "type": "module",
   "main": "./dist/index.cjs",