@oimdb/core 1.3.0 → 1.4.0

package/dist/index.js

@@ -28,35 +28,40 @@ var OIMEventEmitter = class {
     }
     return bucket;
   }
+  /**
+   * Compacts the handlers array by removing null entries (tombstones) left by handler removal.
+   * Rebuilds the indexByHandler map with updated indices and resets the tombstone count.
+   * This reduces array fragmentation and improves iteration performance.
+   */
   compactBucket(bucket) {
     const handlers = bucket.handlers;
     const length = handlers.length;
     const newHandlers = [];
     bucket.indexByHandler.clear();
-    if (bucket.tombstoneCount < length >> 2) {
-      newHandlers.length = length - bucket.tombstoneCount;
-    }
-    let writeIndex = 0;
     for (let i = 0; i < length; i++) {
       const handler = handlers[i];
       if (handler) {
-        newHandlers[writeIndex] = handler;
+        const writeIndex = newHandlers.length;
+        newHandlers.push(handler);
         bucket.indexByHandler.set(handler, writeIndex);
-        writeIndex++;
       }
     }
-    if (newHandlers.length !== writeIndex) {
-      newHandlers.length = writeIndex;
-    }
     bucket.handlers = newHandlers;
     bucket.tombstoneCount = 0;
   }
   on(event, handler) {
     const bucket = this.getOrCreateBucket(event);
-    if (bucket.indexByHandler.has(handler)) return;
+    if (bucket.indexByHandler.has(handler)) {
+      return () => {
+        this.off(event, handler);
+      };
+    }
     const index = bucket.handlers.length;
     bucket.handlers.push(handler);
     bucket.indexByHandler.set(handler, index);
+    return () => {
+      this.off(event, handler);
+    };
   }
   emit(event, payload) {
     const bucket = this.buckets[event];
@@ -71,10 +76,11 @@ var OIMEventEmitter = class {
     }
     bucket.isEmitting--;
     if (bucket.isEmitting === 0 && bucket.tombstoneCount > 0) {
-      if (bucket.tombstoneCount >= length >> 1) {
-        this.compactBucket(bucket);
-      } else if (length === bucket.tombstoneCount) {
+      const currentLength = bucket.handlers.length;
+      if (bucket.tombstoneCount === currentLength) {
         delete this.buckets[event];
+      } else if (bucket.tombstoneCount >= currentLength >> 1) {
+        this.compactBucket(bucket);
       }
     }
   }
@@ -88,10 +94,10 @@ var OIMEventEmitter = class {
     bucket.indexByHandler.delete(handler);
     if (bucket.isEmitting === 0) {
       const length = bucket.handlers.length;
-      if (bucket.tombstoneCount >= length >> 1) {
-        this.compactBucket(bucket);
-      } else if (length === bucket.tombstoneCount) {
+      if (bucket.tombstoneCount === length) {
         delete this.buckets[event];
+      } else if (bucket.tombstoneCount >= length >> 1) {
+        this.compactBucket(bucket);
       }
     }
   }
@@ -453,34 +459,50 @@ var EOIMUpdateEventCoalescerEventType = /* @__PURE__ */ ((EOIMUpdateEventCoalesc
 // src/core/OIMUpdateEventEmitter.ts
 var OIMUpdateEventEmitter = class {
   constructor(opts) {
+    this.keyHandlersBeforeFlush = /* @__PURE__ */ new Map();
     this.keyHandlers = /* @__PURE__ */ new Map();
+    this.isDestroyed = false;
+    this.isDispatching = false;
+    this.isInPrePhase = false;
+    this.hasPendingDuringPrePhase = false;
+    this.isFlushEnqueued = false;
     this.handleHasChanges = () => {
-      this.queue.enqueue(() => {
-        const updatedKeys = this.coalescer.getUpdatedKeys();
-        if (this.keyHandlers.size === 0) {
-          this.coalescer.clearUpdatedKeys();
-          return;
-        }
-        if (updatedKeys.size * 2 < this.keyHandlers.size) {
-          for (const key of updatedKeys.values()) {
-            const handlers = this.keyHandlers.get(key);
-            if (handlers) {
-              for (const handler of handlers) {
-                handler();
-              }
-            }
-          }
-        } else {
-          for (const [key, handlers] of this.keyHandlers) {
-            if (updatedKeys.has(key)) {
-              for (const handler of handlers) {
-                handler();
-              }
-            }
-          }
-        }
+      if (this.isDispatching && this.isInPrePhase) {
+        this.hasPendingDuringPrePhase = true;
+        return;
+      }
+      if (this.isFlushEnqueued) return;
+      this.isFlushEnqueued = true;
+      this.queue.enqueue(this.onFlush);
+    };
+    // Stable handler reference to avoid allocating a new closure on every HAS_CHANGES.
+    this.onFlush = () => {
+      this.isFlushEnqueued = false;
+      if (this.isDestroyed) {
         this.coalescer.clearUpdatedKeys();
-      });
+        this.coalescer.clearFlushingUpdatedKeys();
+        return;
+      }
+      if (this.keyHandlers.size === 0 && this.keyHandlersBeforeFlush.size === 0) {
+        this.coalescer.clearUpdatedKeys();
+        return;
+      }
+      const makeHandlerSnapshot = (handlers) => {
+        const snapshot = [];
+        handlers.forEach((h) => snapshot.push(h));
+        return snapshot;
+      };
+      try {
+        this.isDispatching = true;
+        this.isInPrePhase = true;
+        this.hasPendingDuringPrePhase = false;
+        const allKeysForNormalPhase = this.runPrePhaseDrain(makeHandlerSnapshot);
+        this.isInPrePhase = false;
+        this.runHandlersPhase(allKeysForNormalPhase, makeHandlerSnapshot);
+      } finally {
+        this.isInPrePhase = false;
+        this.isDispatching = false;
+      }
     };
     this.coalescer = opts.coalescer;
     this.coalescer.emitter.on(
@@ -489,11 +511,90 @@ var OIMUpdateEventEmitter = class {
     );
     this.queue = opts.queue;
   }
+  /**
+   * Helps to run computed values etc.
+   */
+  runPrePhaseDrain(makeHandlerSnapshot) {
+    const allKeysForNormalPhase = /* @__PURE__ */ new Set();
+    let hasMorePreWork = true;
+    while (hasMorePreWork) {
+      this.coalescer.markUpdatedKeysAsFlushing();
+      const flushingKeys = this.coalescer.getFlushingUpdatedKeys();
+      flushingKeys.forEach((key) => allKeysForNormalPhase.add(key));
+      try {
+        if (this.keyHandlersBeforeFlush.size > 0) {
+          if (flushingKeys.size * 2 < this.keyHandlersBeforeFlush.size) {
+            flushingKeys.forEach((key) => {
+              if (this.isDestroyed) return;
+              const handlers = this.keyHandlersBeforeFlush.get(key);
+              if (!handlers || handlers.size === 0) return;
+              const handlerSnapshot = makeHandlerSnapshot(handlers);
+              for (let i = 0; i < handlerSnapshot.length; i++) {
+                if (this.isDestroyed) return;
+                const handler = handlerSnapshot[i];
+                if (handlers.has(handler)) handler();
+              }
+            });
+          } else {
+            this.keyHandlersBeforeFlush.forEach((handlers, key) => {
+              if (this.isDestroyed) return;
+              if (!flushingKeys.has(key)) return;
+              if (!handlers || handlers.size === 0) return;
+              const handlerSnapshot = makeHandlerSnapshot(handlers);
+              for (let i = 0; i < handlerSnapshot.length; i++) {
+                if (this.isDestroyed) return;
+                const handler = handlerSnapshot[i];
+                if (handlers.has(handler)) handler();
+              }
+            });
+          }
+        }
+      } finally {
+        this.coalescer.clearFlushingUpdatedKeys();
+      }
+      const nextHasMorePreWork = this.hasPendingDuringPrePhase || this.coalescer.getUpdatedKeys().size > 0;
+      this.hasPendingDuringPrePhase = false;
+      hasMorePreWork = nextHasMorePreWork;
+    }
+    return allKeysForNormalPhase;
+  }
+  runHandlersPhase(allKeysForNormalPhase, makeHandlerSnapshot) {
+    if (this.keyHandlers.size === 0 || allKeysForNormalPhase.size === 0)
+      return;
+    if (allKeysForNormalPhase.size * 2 < this.keyHandlers.size) {
+      allKeysForNormalPhase.forEach((key) => {
+        if (this.isDestroyed) return;
+        const handlers = this.keyHandlers.get(key);
+        if (!handlers || handlers.size === 0) return;
+        const handlerSnapshot = makeHandlerSnapshot(handlers);
+        for (let i = 0; i < handlerSnapshot.length; i++) {
+          if (this.isDestroyed) return;
+          const handler = handlerSnapshot[i];
+          if (handlers.has(handler)) handler();
+        }
+      });
+    } else {
+      this.keyHandlers.forEach((handlers, key) => {
+        if (this.isDestroyed) return;
+        if (!allKeysForNormalPhase.has(key)) return;
+        if (!handlers || handlers.size === 0) return;
+        const handlerSnapshot = makeHandlerSnapshot(handlers);
+        for (let i = 0; i < handlerSnapshot.length; i++) {
+          if (this.isDestroyed) return;
+          const handler = handlerSnapshot[i];
+          if (handlers.has(handler)) handler();
+        }
+      });
+    }
+  }
   destroy() {
+    if (this.isDestroyed) return;
+    this.isDestroyed = true;
     this.coalescer.emitter.off(
       0 /* HAS_CHANGES */,
       this.handleHasChanges
     );
+    this.keyHandlersBeforeFlush.clear();
     this.keyHandlers.clear();
   }
   /**
@@ -501,9 +602,9 @@ var OIMUpdateEventEmitter = class {
    */
   getMetrics() {
     let totalHandlers = 0;
-    for (const handlers of this.keyHandlers.values()) {
+    this.keyHandlers.forEach((handlers) => {
       totalHandlers += handlers.size;
-    }
+    });
     return {
       totalKeys: this.keyHandlers.size,
       totalHandlers,
@@ -515,13 +616,32 @@ var OIMUpdateEventEmitter = class {
    * Check if there are any active subscriptions
    */
   hasSubscriptions() {
-    return this.keyHandlers.size > 0;
+    return this.keyHandlers.size > 0 || this.keyHandlersBeforeFlush.size > 0;
   }
   /**
    * Get the number of handlers for a specific key
    */
   getHandlerCount(key) {
-    return this.keyHandlers.get(key)?.size ?? 0;
+    return (this.keyHandlers.get(key)?.size ?? 0) + (this.keyHandlersBeforeFlush.get(key)?.size ?? 0);
+  }
+  subscribeOnKeyBeforeFlush(key, handler) {
+    let handlers = this.keyHandlersBeforeFlush.get(key);
+    if (!handlers) {
+      handlers = /* @__PURE__ */ new Set();
+      this.keyHandlersBeforeFlush.set(key, handlers);
+    }
+    handlers.add(handler);
+    return () => {
+      this.unsubscribeFromKeyBeforeFlush(key, handler);
+    };
+  }
+  unsubscribeFromKeyBeforeFlush(key, handler) {
+    const handlers = this.keyHandlersBeforeFlush.get(key);
+    if (!handlers) return;
+    handlers.delete(handler);
+    if (handlers.size === 0) {
+      this.keyHandlersBeforeFlush.delete(key);
+    }
   }
   subscribeOnKey(key, handler) {
     let handlers = this.keyHandlers.get(key);
@@ -561,6 +681,30 @@ var OIMUpdateEventEmitter = class {
       }
     };
   }
+  subscribeOnKeysBeforeFlush(keys, handler) {
+    const subscribedKeys = [];
+    for (const key of keys) {
+      let handlers = this.keyHandlersBeforeFlush.get(key);
+      if (!handlers) {
+        handlers = /* @__PURE__ */ new Set();
+        this.keyHandlersBeforeFlush.set(key, handlers);
+      }
+      if (!handlers.has(handler)) {
+        handlers.add(handler);
+        subscribedKeys.push(key);
+      }
+    }
+    return () => {
+      for (const key of subscribedKeys) {
+        this.unsubscribeFromKeyBeforeFlush(key, handler);
+      }
+    };
+  }
+  unsubscribeFromKeysBeforeFlush(keys, handler) {
+    for (const key of keys) {
+      this.unsubscribeFromKeyBeforeFlush(key, handler);
+    }
+  }
   unsubscribeFromKeys(keys, handler) {
     for (const key of keys) {
       this.unsubscribeFromKey(key, handler);
@@ -655,15 +799,19 @@ var OIMDBSettings = class {
  * This constant is exported so users can create their own indexes and pass them to coalescers.
  */
 OIMDBSettings.UPDATED_KEYS_INDEX_KEY = "__updatedKeys__";
+OIMDBSettings.FLUSHING_KEYS_INDEX_KEY = "__flushingKeys__";
 
 // src/core/OIMUpdateEventCoalescer.ts
 var OIMUpdateEventCoalescer = class {
-  constructor(index) {
+  constructor(index, flushingIndex) {
     this.emitter = new OIMEventEmitter();
     this.hasEmittedChanges = false;
     this.updatedKeysIndex = index ?? new OIMIndexManualSetBased({
       store: new OIMIndexStoreMapDrivenSetBased()
     });
+    this.flushingUpdatedKeysIndex = flushingIndex ?? new OIMIndexManualSetBased({
+      store: new OIMIndexStoreMapDrivenSetBased()
+    });
     if (!this.updatedKeysIndex.hasKey(OIMDBSettings.UPDATED_KEYS_INDEX_KEY)) {
       this.updatedKeysIndex.setPks(
         OIMDBSettings.UPDATED_KEYS_INDEX_KEY,
@@ -679,6 +827,18 @@ var OIMUpdateEventCoalescer = class {
       OIMDBSettings.UPDATED_KEYS_INDEX_KEY
     );
   }
+  getFlushingUpdatedKeys() {
+    return this.flushingUpdatedKeysIndex.getPksByKey(
+      OIMDBSettings.FLUSHING_KEYS_INDEX_KEY
+    );
+  }
+  markUpdatedKeysAsFlushing() {
+    this.flushingUpdatedKeysIndex.setPks(
+      OIMDBSettings.FLUSHING_KEYS_INDEX_KEY,
+      Array.from(this.getUpdatedKeys())
+    );
+    this.clearUpdatedKeys();
+  }
   /**
    * Clear all updated keys and reset the changed state
    */
@@ -694,6 +854,12 @@ var OIMUpdateEventCoalescer = class {
       void 0
     );
   }
+  clearFlushingUpdatedKeys() {
+    this.flushingUpdatedKeysIndex.setPks(
+      OIMDBSettings.FLUSHING_KEYS_INDEX_KEY,
+      []
+    );
+  }
   /**
    * Add keys to the updated set and emit HAS_CHANGES event if needed
    */
@@ -769,6 +935,8 @@ var OIMReactiveIndexSetBased = class {
     return this.index.getMetrics();
   }
   destroy() {
+    this.updateEventEmitter.destroy();
+    this.coalescer.destroy();
     this.index.destroy();
   }
 };
@@ -810,10 +978,16 @@ var OIMReactiveIndexArrayBased = class {
     return this.index.getMetrics();
   }
   destroy() {
+    this.updateEventEmitter.destroy();
+    this.coalescer.destroy();
     this.index.destroy();
   }
 };
 
+// src/abstract/OIMObjectStore.ts
+var OIMObjectStore = class {
+};
+
 // src/core/OIMPkSelectorFactory.ts
 var OIMPkSelectorFactory = class {
   createIdSelector() {
@@ -871,6 +1045,9 @@ var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
   getAllPks() {
     return Array.from(this.entities.keys());
   }
+  destroy() {
+    this.clear();
+  }
 };
 
 // src/core/OIMEntityUpdaterFactory.ts
@@ -968,6 +1145,10 @@ var OIMCollection = class {
       this.store.setOneByPk(pk, entity);
     }
   }
+  destroy() {
+    this.store.destroy();
+    this.emitter.offAll();
+  }
 };
 
 // src/core/OIMUpdateEventCoalescerCollection.ts
@@ -1008,6 +1189,143 @@ var OIMReactiveCollection = class extends OIMCollection {
       queue
     });
   }
+  destroy() {
+    this.updateEventEmitter.destroy();
+    this.coalescer.destroy();
+    super.destroy();
+  }
+};
+
+// src/core/OIMObjectStoreRecordDriven.ts
+var OIMObjectStoreRecordDriven = class extends OIMObjectStore {
+  constructor(initial) {
+    super();
+    this.properties = Object.assign(/* @__PURE__ */ Object.create(null), initial ?? {});
+  }
+  setProperty(key, value) {
+    this.properties[key] = value;
+  }
+  merge(draft) {
+    Object.assign(this.properties, draft);
+  }
+  delete(key) {
+    delete this.properties[key];
+  }
+  get(key) {
+    return this.properties[key];
+  }
+  getAll() {
+    return { ...this.properties };
+  }
+  clear() {
+    this.properties = /* @__PURE__ */ Object.create(null);
+  }
+  count() {
+    return Object.keys(this.properties).length;
+  }
+  keys() {
+    return Object.keys(this.properties);
+  }
+  values() {
+    return Object.values(this.properties);
+  }
+  entries() {
+    return Object.entries(this.properties);
+  }
+  destroy() {
+    this.clear();
+  }
+};
+
+// src/enum/EOIMObjectEventType.ts
+var EOIMObjectEventType = /* @__PURE__ */ ((EOIMObjectEventType2) => {
+  EOIMObjectEventType2[EOIMObjectEventType2["UPDATE"] = 0] = "UPDATE";
+  return EOIMObjectEventType2;
+})(EOIMObjectEventType || {});
+
+// src/core/OIMObject.ts
+var OIMObject = class {
+  constructor(opts) {
+    this.emitter = new OIMEventEmitter();
+    this.store = opts?.store ?? new OIMObjectStoreRecordDriven();
+  }
+  setProperty(key, value) {
+    this.store.setProperty(key, value);
+    this.emitter.emit(0 /* UPDATE */, { keys: [key] });
+  }
+  merge(draft) {
+    this.store.merge(draft);
+    this.emitter.emit(0 /* UPDATE */, {
+      keys: Object.keys(draft)
+    });
+  }
+  delete(key) {
+    this.store.delete(key);
+    this.emitter.emit(0 /* UPDATE */, { keys: [key] });
+  }
+  get(key) {
+    return this.store.get(key);
+  }
+  getAll() {
+    return this.store.getAll();
+  }
+  clear() {
+    this.store.clear();
+    this.emitter.emit(0 /* UPDATE */, { keys: [] });
+  }
+  count() {
+    return this.store.count();
+  }
+  keys() {
+    return this.store.keys();
+  }
+  values() {
+    return this.store.values();
+  }
+  entries() {
+    return this.store.entries();
+  }
+  destroy() {
+    this.store.destroy();
+    this.emitter.offAll();
+  }
+};
+
+// src/core/OIMUpdateEventCoalescerObject.ts
+var OIMUpdateEventCoalescerObject = class extends OIMUpdateEventCoalescer {
+  constructor(objectEmitter) {
+    super();
+    this.objectEmitter = objectEmitter;
+    /**
+     * When the object is updated, we keep track of the updated keys.
+     */
+    this.handleUpdate = (payload) => {
+      this.addUpdatedKeys(payload.keys);
+    };
+    this.objectEmitter.on(0 /* UPDATE */, this.handleUpdate);
+  }
+  destroy() {
+    this.objectEmitter.off(0 /* UPDATE */, this.handleUpdate);
+    this.emitter.offAll();
+    this.clearUpdatedKeys();
+  }
+};
+
+// src/core/OIMReactiveObject.ts
+var OIMReactiveObject = class extends OIMObject {
+  constructor(queue, opts) {
+    super(opts);
+    this.coalescer = new OIMUpdateEventCoalescerObject(this.emitter);
+    this.updateEventEmitter = new OIMUpdateEventEmitter({
+      coalescer: this.coalescer,
+      queue
+    });
+  }
+  destroy() {
+    this.updateEventEmitter.destroy();
+    this.coalescer.destroy();
+    super.destroy();
+  }
 };
 
 // src/core/OIMReactiveIndexManualSetBased.ts
@@ -1134,7 +1452,54 @@ var OIMReactiveIndexManualArrayBased = class extends OIMReactiveIndexArrayBased
 var OIMRICollection = class extends OIMReactiveCollection {
   constructor(queue, opts) {
     super(queue, opts.collectionOpts);
-    this.indexes = opts.indexes;
+    this.indexes = opts.indexes || {};
+  }
+};
+
+// src/core/OIMObjectStoreMapDriven.ts
+var OIMObjectStoreMapDriven = class extends OIMObjectStore {
+  constructor() {
+    super(...arguments);
+    this.properties = /* @__PURE__ */ new Map();
+  }
+  setProperty(key, value) {
+    this.properties.set(key, value);
+  }
+  merge(draft) {
+    for (const key in draft) {
+      if (!Object.prototype.hasOwnProperty.call(draft, key)) continue;
+      this.properties.set(
+        key,
+        draft[key]
+      );
+    }
+  }
+  delete(key) {
+    this.properties.delete(key);
+  }
+  get(key) {
+    return this.properties.get(key);
+  }
+  getAll() {
+    return Object.fromEntries(this.properties.entries());
+  }
+  clear() {
+    this.properties.clear();
+  }
+  count() {
+    return this.properties.size;
+  }
+  keys() {
+    return Array.from(this.properties.keys());
+  }
+  values() {
+    return Array.from(this.properties.values());
+  }
+  entries() {
+    return Array.from(this.properties.entries());
+  }
+  destroy() {
+    this.properties.clear();
   }
 };
 
@@ -1168,6 +1533,8 @@ var OIMEventQueue = class {
   constructor(options = {}) {
     this.emitter = new OIMEventEmitter();
     this.queue = [];
+    this.isFlushing = false;
+    this.pendingSchedule = false;
     this.scheduler = options.scheduler;
     if (this.scheduler) {
       this.flushBound = () => this.flush();
@@ -1183,7 +1550,12 @@ var OIMEventQueue = class {
    */
   enqueue(fn) {
     this.queue.push(fn);
-    if (this.scheduler && this.queue.length === 1) {
+    if (!this.scheduler) return;
+    if (this.isFlushing) {
+      this.pendingSchedule = true;
+      return;
+    }
+    if (this.queue.length === 1) {
       this.scheduler.schedule();
     }
   }
@@ -1193,6 +1565,8 @@ var OIMEventQueue = class {
    */
   flush() {
     if (this.queue.length === 0) return;
+    this.scheduler?.cancel();
+    this.isFlushing = true;
     this.emitter.emit(1 /* BEFORE_FLUSH */, void 0);
     const currentQueue = this.queue.slice();
     this.queue.length = 0;
@@ -1200,6 +1574,13 @@ var OIMEventQueue = class {
       currentQueue[i]();
     }
     this.emitter.emit(0 /* AFTER_FLUSH */, void 0);
+    this.isFlushing = false;
+    if (this.scheduler && this.pendingSchedule && this.queue.length > 0) {
+      this.pendingSchedule = false;
+      this.scheduler.schedule();
+    } else {
+      this.pendingSchedule = false;
+    }
   }
   /**
    * Get the current number of queued functions.
@@ -1267,7 +1648,7 @@ var OIMIndexComparatorFactory = class {
       if (existingSet.size !== newSet.size || existingSet.size !== existingPks.length) {
         return false;
       }
-      for (const pk of existingSet) {
+      for (const pk of Array.from(existingSet)) {
         if (!newSet.has(pk)) {
           return false;
         }
@@ -1333,6 +1714,270 @@ var OIMMap2Keys = class {
   }
 };
 
+// src/modules/wrapper/OIMUpdateEventCoalescerManual.ts
+var OIMUpdateEventCoalescerManual = class extends OIMUpdateEventCoalescer {
+  markUpdatedKeys(keys) {
+    if (keys.length === 0) return;
+    this.addUpdatedKeys(keys);
+  }
+  destroy() {
+    this.emitter.offAll();
+    this.updatedKeysIndex.destroy();
+    this.flushingUpdatedKeysIndex.destroy();
+  }
+};
+
+// src/modules/wrapper/collection/OIMCollectionChangedFieldsWrapper.ts
+var OIMCollectionChangedFieldsWrapper = class {
+  constructor(queue, collection, opts) {
+    this.changedFieldsByPk = /* @__PURE__ */ new Map();
+    this.changedPksByField = /* @__PURE__ */ new Map();
+    this.collection = collection;
+    this.selectPk = opts?.selectPk ?? (() => {
+      throw new Error(
+        `[OIMCollectionChangedFieldsWrapper]: selectPk was not provided. Use upsertOneByPk(...) or pass opts.selectPk.`
+      );
+    });
+    this.changedPksCoalescer = new OIMUpdateEventCoalescerManual();
+    this.changedPksEventEmitter = new OIMUpdateEventEmitter({
+      coalescer: this.changedPksCoalescer,
+      queue
+    });
+    this.changedFieldsCoalescer = new OIMUpdateEventCoalescerManual();
+    this.changedFieldsEventEmitter = new OIMUpdateEventEmitter({
+      coalescer: this.changedFieldsCoalescer,
+      queue
+    });
+  }
+  upsertOneByPk(pk, patch) {
+    this.trackPatch(pk, patch);
+    this.collection.upsertOneByPk(pk, patch);
+  }
+  upsertOne(entity) {
+    const pk = this.selectPk(entity);
+    this.trackPatch(pk, entity);
+    this.collection.upsertOne(entity);
+  }
+  upsertMany(entities) {
+    for (const entity of entities) {
+      const pk = this.selectPk(entity);
+      this.trackPatch(pk, entity);
+    }
+    this.collection.upsertMany(entities);
+  }
+  getChangedFieldsByPk(pk) {
+    return this.changedFieldsByPk.get(pk) ?? /* @__PURE__ */ new Set();
+  }
+  consumeChangedFieldsByPk(pk) {
+    const existing = this.changedFieldsByPk.get(pk);
+    if (!existing) return /* @__PURE__ */ new Set();
+    this.changedFieldsByPk.delete(pk);
+    return existing;
+  }
+  getChangedPksByField(field) {
+    return this.changedPksByField.get(field) ?? /* @__PURE__ */ new Set();
+  }
+  consumeChangedPksByField(field) {
+    const existing = this.changedPksByField.get(field);
+    if (!existing) return /* @__PURE__ */ new Set();
+    this.changedPksByField.delete(field);
+    return existing;
+  }
+  clear() {
+    this.changedFieldsByPk.clear();
+    this.changedPksByField.clear();
+  }
+  destroy() {
+    this.changedPksEventEmitter.destroy();
+    this.changedFieldsEventEmitter.destroy();
+    this.changedPksCoalescer.destroy();
+    this.changedFieldsCoalescer.destroy();
+    this.clear();
+  }
+  trackPatch(pk, patch) {
+    if (pk === void 0 || pk === null || pk === "") {
+      throw new Error(
+        `[OIMCollectionChangedFieldsWrapper]: PK is required to track changes.`
+      );
+    }
+    const keys = Object.keys(patch);
+    if (keys.length === 0) return;
+    let pkFields = this.changedFieldsByPk.get(pk);
+    if (!pkFields) {
+      pkFields = /* @__PURE__ */ new Set();
+      this.changedFieldsByPk.set(pk, pkFields);
+    }
+    for (const key of keys) {
+      pkFields.add(key);
+      let fieldPks = this.changedPksByField.get(key);
+      if (!fieldPks) {
+        fieldPks = /* @__PURE__ */ new Set();
+        this.changedPksByField.set(key, fieldPks);
+      }
+      fieldPks.add(pk);
+    }
+    this.changedPksCoalescer.markUpdatedKeys([pk]);
+    this.changedFieldsCoalescer.markUpdatedKeys(keys);
+  }
+};
+
+// src/modules/wrapper/index/OIMIndexManualOrderedArrayBased.ts
+var OIMIndexManualOrderedArrayBased = class extends OIMIndexArrayBased {
+  clear(key) {
+    if (key === void 0) {
+      const keys = this.getKeys();
+      if (keys.length > 0) {
+        this.store.clear();
+        this.emitUpdate(Array.from(keys));
+      }
+      return;
+    }
+    if (this.store.getOneByKey(key) !== void 0) {
+      this.store.removeOneByKey(key);
+      this.emitUpdate([key]);
+    }
+  }
+  push(key, itemKey) {
+    const list = this.getOrCreateList(key);
+    const index = list.length;
+    list.push(itemKey);
+    this.emitUpdate([key]);
+    return index;
+  }
+  insertAt(key, index, itemKey) {
+    const list = this.getOrCreateList(key);
+    const safeIndex = Math.max(0, Math.min(index, list.length));
+    list.splice(safeIndex, 0, itemKey);
+    this.emitUpdate([key]);
+  }
+  removeAt(key, index) {
+    const list = this.store.getOneByKey(key);
+    if (!list) return void 0;
+    if (index < 0 || index >= list.length) return void 0;
+    const [removed] = list.splice(index, 1);
+    if (list.length === 0) {
+      this.store.removeOneByKey(key);
+    }
+    this.emitUpdate([key]);
+    return removed;
+  }
+  move(key, fromIndex, toIndex) {
+    const list = this.store.getOneByKey(key);
+    if (!list) return void 0;
+    if (fromIndex < 0 || fromIndex >= list.length) return void 0;
+    if (toIndex < 0 || toIndex >= list.length) return void 0;
+    if (fromIndex === toIndex) return list[fromIndex];
+    const [itemKey] = list.splice(fromIndex, 1);
+    if (itemKey === void 0) return void 0;
+    list.splice(toIndex, 0, itemKey);
+    this.emitUpdate([key]);
+    return itemKey;
+  }
+  reset(key, itemKeys) {
+    if (itemKeys.length === 0) {
+      if (this.store.getOneByKey(key) !== void 0) {
+        this.store.removeOneByKey(key);
+        this.emitUpdate([key]);
+      }
+      return;
+    }
+    this.store.setOneByKey(key, Array.from(itemKeys));
+    this.emitUpdate([key]);
+  }
+  getOrCreateList(key) {
+    let list = this.store.getOneByKey(key);
+    if (!list) {
+      list = [];
+      this.store.setOneByKey(key, list);
+    }
+    return list;
+  }
+};
+
+// src/modules/wrapper/index/OIMOrderedListIndexCommandStreamWrapper.ts
+var OIMOrderedListIndexCommandStreamWrapper = class {
+  constructor(queue, index) {
+    this.commandsByKey = /* @__PURE__ */ new Map();
+    this.coalescer = new OIMUpdateEventCoalescerManual();
+    this.commandsEventEmitter = new OIMUpdateEventEmitter({
+      coalescer: this.coalescer,
+      queue
+    });
+    this.index = index ?? new OIMIndexManualOrderedArrayBased();
+  }
+  getPksByKey(key) {
+    return this.index.getPksByKey(key);
+  }
+  hasKey(key) {
+    return this.index.hasKey(key);
+  }
+  getKeys() {
+    return this.index.getKeys();
+  }
+  push(key, itemKey) {
+    const index = this.index.push(key, itemKey);
+    this.appendCommand(key, { type: "add", key: itemKey, index });
+  }
+  removeAt(key, index) {
+    const itemKey = this.index.removeAt(key, index);
+    if (itemKey === void 0) return;
+    this.appendCommand(key, { type: "remove", key: itemKey, index });
+  }
+  move(key, fromIndex, toIndex) {
+    const itemKey = this.index.move(key, fromIndex, toIndex);
+    if (itemKey === void 0) return;
+    this.appendCommand(key, {
+      type: "move",
+      key: itemKey,
+      fromIndex,
+      toIndex
+    });
+  }
+  reset(key, keys) {
+    this.index.reset(key, keys);
+    this.appendCommand(key, { type: "reset", keys });
+  }
+  /**
+   * Read-only peek at buffered commands without clearing them.
+   */
+  getBufferedCommands(key) {
+    return this.commandsByKey.get(key) ?? [];
+  }
+  /**
+   * Drain buffered commands for a key, preserving order.
+   * Intended usage: call inside a `commandsEventEmitter.subscribeOnKey(key, ...)` handler.
+   */
+  consumeCommands(key) {
+    const cmds = this.commandsByKey.get(key);
+    if (!cmds || cmds.length === 0) return [];
+    this.commandsByKey.delete(key);
+    return cmds;
+  }
+  clear(key) {
+    if (key === void 0) {
+      this.index.destroy();
+      this.commandsByKey.clear();
+      return;
+    }
+    this.index.clear(key);
+    this.commandsByKey.delete(key);
+  }
+  destroy() {
+    this.commandsEventEmitter.destroy();
+    this.coalescer.destroy();
+    this.clear();
+  }
+  appendCommand(key, cmd) {
+    let cmds = this.commandsByKey.get(key);
+    if (!cmds) {
+      cmds = [];
+      this.commandsByKey.set(key, cmds);
+    }
+    cmds.push(cmd);
+    this.coalescer.markUpdatedKeys([key]);
+  }
+};
+
 // src/core/event-queue-scheduler/OIMEventQueueSchedulerAnimationFrame.ts
 var OIMEventQueueSchedulerAnimationFrame = class extends OIMEventQueueScheduler {
   constructor() {
@@ -1501,17 +2146,310 @@ var OIMEventQueueSchedulerFactory = class {
     return new OIMEventQueueSchedulerImmediate();
   }
 };
+
+// src/modules/effect/core/OIMEffect.ts
+var OIMEffect = class {
+  constructor(queue, opts) {
+    this.unsubscribers = [];
+    this.isDestroyed = false;
+    this.isInFlush = false;
+    this.hasRunInThisFlush = false;
+    this.isScheduled = false;
+    this.handleQueueBeforeFlush = () => {
+      this.isInFlush = true;
+      this.hasRunInThisFlush = false;
+    };
+    this.handleQueueAfterFlush = () => {
+      this.isInFlush = false;
+      this.hasRunInThisFlush = false;
+    };
+    this.runTask = () => {
+      this.isScheduled = false;
+      if (this.isDestroyed) return;
+      this.runOnce();
+    };
+    this.invalidate = () => {
+      if (this.isDestroyed) return;
+      this.onInvalidate?.();
+      if (this.isInFlush) {
+        if (this.hasRunInThisFlush) return;
+        this.hasRunInThisFlush = true;
+        this.runOnce();
+        return;
+      }
+      if (this.isScheduled) return;
+      this.isScheduled = true;
+      this.queue.enqueue(this.runTask);
+    };
+    this.queue = queue;
+    this.phase = opts.phase;
+    this.onInvalidate = opts.onInvalidate;
+    this.run = opts.run;
+    this.deps = opts.deps ?? [];
+    this.queue.emitter.on(
+      1 /* BEFORE_FLUSH */,
+      this.handleQueueBeforeFlush
+    );
+    this.queue.emitter.on(
+      0 /* AFTER_FLUSH */,
+      this.handleQueueAfterFlush
+    );
+    for (const dep of this.deps) {
+      this.unsubscribers.push(dep.subscribe(this.phase, this.invalidate));
+    }
+  }
+  destroy() {
+    if (this.isDestroyed) return;
+    this.isDestroyed = true;
+    for (const unsubscribe of this.unsubscribers) unsubscribe();
+    this.unsubscribers = [];
+    this.queue.emitter.off(
+      1 /* BEFORE_FLUSH */,
+      this.handleQueueBeforeFlush
+    );
+    this.queue.emitter.off(
+      0 /* AFTER_FLUSH */,
+      this.handleQueueAfterFlush
+    );
+  }
+  runOnce() {
+    if (this.isDestroyed) return;
+    this.run();
+  }
+};
+
+// src/modules/effect/enum/EOIMEffectPhase.ts
+var EOIMEffectPhase = /* @__PURE__ */ ((EOIMEffectPhase2) => {
+  EOIMEffectPhase2["PRE"] = "pre";
+  EOIMEffectPhase2["HANDLERS"] = "handlers";
+  return EOIMEffectPhase2;
+})(EOIMEffectPhase || {});
+
+// src/modules/computed/enum/EOIMComputedEventType.ts
+var EOIMComputedEventType = /* @__PURE__ */ ((EOIMComputedEventType2) => {
+  EOIMComputedEventType2["UPDATE"] = "update";
+  return EOIMComputedEventType2;
+})(EOIMComputedEventType || {});
+
+// src/modules/computed/core/OIMUpdateEventCoalescerComputed.ts
+var OIMUpdateEventCoalescerComputed = class extends OIMUpdateEventCoalescer {
+  constructor(computedEmitter) {
+    super();
+    this.computedEmitter = computedEmitter;
+    this.handleUpdate = (payload) => {
+      this.addUpdatedKeys(payload.keys);
+    };
+    this.computedEmitter.on(
+      "update" /* UPDATE */,
+      this.handleUpdate
+    );
+  }
+  destroy() {
+    this.computedEmitter.off(
+      "update" /* UPDATE */,
+      this.handleUpdate
+    );
+    this.emitter.offAll();
+    this.clearUpdatedKeys();
+  }
+};
+
+// src/modules/computed/core/OIMComputed.ts
+var OIMComputed = class {
+  constructor(queue, opts) {
+    this.emitter = new OIMEventEmitter();
+    this.hasValue = false;
+    this.isDirty = true;
+    this.isInFlush = false;
+    this.hasRecomputedInThisFlush = false;
+    this.handleQueueBeforeFlush = () => {
+      this.isInFlush = true;
+      this.hasRecomputedInThisFlush = false;
+    };
+    this.handleQueueAfterFlush = () => {
+      this.isInFlush = false;
+      this.hasRecomputedInThisFlush = false;
+    };
+    this.queue = queue;
+    this.compute = opts.compute;
+    this.compare = opts.compare ?? Object.is;
+    this.deps = opts.deps ?? [];
+    this.coalescer = new OIMUpdateEventCoalescerComputed(
+      this.emitter
+    );
+    this.updateEventEmitter = new OIMUpdateEventEmitter({
+      coalescer: this.coalescer,
+      queue: this.queue
+    });
+    this.queue.emitter.on(
+      1 /* BEFORE_FLUSH */,
+      this.handleQueueBeforeFlush
+    );
+    this.queue.emitter.on(
+      0 /* AFTER_FLUSH */,
+      this.handleQueueAfterFlush
+    );
+    this.effect = new OIMEffect(this.queue, {
+      deps: this.deps,
+      phase: "pre" /* PRE */,
+      onInvalidate: () => {
+        this.isDirty = true;
+      },
+      run: () => {
+        if (this.isInFlush) {
+          if (this.hasRecomputedInThisFlush) return;
+          this.hasRecomputedInThisFlush = true;
+        }
+        this.recomputeAndEmitIfChanged();
+      }
+    });
+  }
+  get() {
+    this.recomputeAndEmitIfChanged();
+    return this.value;
+  }
+  getIfReady() {
+    return this.hasValue ? this.value : void 0;
+  }
+  destroy() {
+    this.effect.destroy();
+    this.queue.emitter.off(
+      1 /* BEFORE_FLUSH */,
+      this.handleQueueBeforeFlush
+    );
+    this.queue.emitter.off(
+      0 /* AFTER_FLUSH */,
+      this.handleQueueAfterFlush
+    );
+    this.updateEventEmitter.destroy();
+    this.coalescer.destroy();
+    this.emitter.offAll();
+  }
+  recomputeAndEmitIfChanged() {
+    if (!this.isDirty) return;
+    const prev = this.value;
+    const hadPrev = this.hasValue;
+    const next = this.compute();
+    this.value = next;
+    this.hasValue = true;
+    this.isDirty = false;
+    const changed = !hadPrev || !this.compare(prev, next);
+    if (!changed) return;
+    this.emitter.emit("update" /* UPDATE */, {
+      keys: ["value"]
+    });
+  }
+};
+
+// src/modules/effect/core/OIMEffectDependencyKeyed.ts
+function isReadonlyArray(value) {
+  return Array.isArray(value);
+}
+var OIMEffectDependencyKeyed = class {
+  constructor(updateEventEmitter, keyOrKeys) {
+    this.updateEventEmitter = updateEventEmitter;
+    if (isReadonlyArray(keyOrKeys)) {
+      this.keys = keyOrKeys;
+    } else {
+      this.key = keyOrKeys;
+    }
+  }
+  subscribe(phase, onInvalidate) {
+    const isPre = phase === "pre" /* PRE */;
+    if (this.keys !== void 0) {
+      return isPre ? this.updateEventEmitter.subscribeOnKeysBeforeFlush(
+        this.keys,
+        onInvalidate
+      ) : this.updateEventEmitter.subscribeOnKeys(
+        this.keys,
+        onInvalidate
+      );
+    }
+    if (this.key === void 0) return () => {
+    };
+    return isPre ? this.updateEventEmitter.subscribeOnKeyBeforeFlush(
+      this.key,
+      onInvalidate
+    ) : this.updateEventEmitter.subscribeOnKey(this.key, onInvalidate);
+  }
+};
+
+// src/modules/effect/core/OIMEffectDependencyKeyedObject.ts
+var OIMEffectDependencyKeyedObject = class {
+  constructor(object, keyOrKeys) {
+    this.dep = new OIMEffectDependencyKeyed(
+      object.updateEventEmitter,
+      keyOrKeys
+    );
+  }
+  subscribe(phase, onInvalidate) {
+    return this.dep.subscribe(phase, onInvalidate);
+  }
+};
+
+// src/modules/effect/core/OIMEffectDependencyKeyedCollection.ts
+var OIMEffectDependencyKeyedCollection = class {
+  constructor(collection, pkOrPks) {
+    this.dep = new OIMEffectDependencyKeyed(
+      collection.updateEventEmitter,
+      pkOrPks
+    );
+  }
+  subscribe(phase, onInvalidate) {
+    return this.dep.subscribe(phase, onInvalidate);
+  }
+};
+
+// src/modules/effect/core/OIMEffectDependencyKeyedIndex.ts
+var OIMEffectDependencyKeyedIndex = class {
+  constructor(index, keyOrKeys) {
+    this.dep = new OIMEffectDependencyKeyed(
+      index.updateEventEmitter,
+      keyOrKeys
+    );
+  }
+  subscribe(phase, onInvalidate) {
+    return this.dep.subscribe(phase, onInvalidate);
+  }
+};
+
+// src/modules/effect/core/OIMEffectDependencyComputed.ts
+var OIMEffectDependencyComputed = class {
+  constructor(computed) {
+    this.computed = computed;
+  }
+  subscribe(phase, onInvalidate) {
+    if (phase === "pre" /* PRE */) {
+      return this.computed.emitter.on("update", onInvalidate);
+    }
+    return this.computed.updateEventEmitter.subscribeOnKey(
+      "value",
+      onInvalidate
+    );
+  }
+};
 export {
   EOIMCollectionEventType,
+  EOIMComputedEventType,
+  EOIMEffectPhase,
   EOIMEventQueueEventType,
   EOIMEventQueueSchedulerEventType,
   EOIMIndexEventType,
+  EOIMObjectEventType,
   EOIMUpdateEventCoalescerEventType,
   OIMCollection,
+  OIMCollectionChangedFieldsWrapper,
   OIMCollectionStore,
   OIMCollectionStoreMapDriven,
   OIMComparatorFactory,
+  OIMComputed,
   OIMDBSettings,
+  OIMEffect,
+  OIMEffectDependencyComputed,
+  OIMEffectDependencyKeyed,
+  OIMEffectDependencyKeyedCollection,
+  OIMEffectDependencyKeyedIndex,
+  OIMEffectDependencyKeyedObject,
   OIMEntityUpdaterFactory,
   OIMEventEmitter,
   OIMEventQueue,
@@ -1524,6 +2462,7 @@ export {
   OIMIndexArrayBased,
   OIMIndexComparatorFactory,
   OIMIndexManualArrayBased,
+  OIMIndexManualOrderedArrayBased,
   OIMIndexManualSetBased,
   OIMIndexSetBased,
   OIMIndexStoreArrayBased,
@@ -1531,6 +2470,11 @@ export {
   OIMIndexStoreMapDrivenSetBased,
   OIMIndexStoreSetBased,
   OIMMap2Keys,
+  OIMObject,
+  OIMObjectStore,
+  OIMObjectStoreMapDriven,
+  OIMObjectStoreRecordDriven,
+  OIMOrderedListIndexCommandStreamWrapper,
   OIMPkSelectorFactory,
   OIMRICollection,
   OIMReactiveCollection,
@@ -1538,8 +2482,12 @@ export {
   OIMReactiveIndexManualArrayBased,
   OIMReactiveIndexManualSetBased,
   OIMReactiveIndexSetBased,
+  OIMReactiveObject,
   OIMUpdateEventCoalescer,
   OIMUpdateEventCoalescerCollection,
+  OIMUpdateEventCoalescerComputed,
   OIMUpdateEventCoalescerIndex,
+  OIMUpdateEventCoalescerManual,
+  OIMUpdateEventCoalescerObject,
   OIMUpdateEventEmitter
 };