@signaldb/core 2.0.0-beta.4 → 2.0.0-beta.5

package/dist/index.cjs17.js

@@ -1,152 +1,579 @@
 "use strict";
+const deepClone = require("./index.cjs20.js");
+const match = require("./index.cjs24.js");
+const modify = require("./index.cjs7.js");
+const queryId = require("./index.cjs21.js");
 const isEqual = require("./index.cjs6.js");
-const uniqueBy = require("./index.cjs29.js");
-class Observer {
-  previousItems = [];
-  callbacks;
-  unbindEvents;
-  /**
-   * Creates a new instance of the `Observer` class.
-   * Sets up event bindings and initializes the callbacks for tracking changes in a collection.
-   * @param bindEvents - A function to bind external events to the observer. Must return a cleanup function to unbind those events.
-   */
-  constructor(bindEvents) {
-    this.callbacks = {
-      added: [],
-      addedBefore: [],
-      changed: [],
-      changedField: [],
-      movedBefore: [],
-      removed: []
+const getIndexInfo = require("./index.cjs23.js");
+const getMatchingKeys = require("./index.cjs27.js");
+const sortItems = require("./index.cjs26.js");
+const project = require("./index.cjs25.js");
+function defaultMergeItems(a, b) {
+  return { ...a, ...b };
+}
+function selectorId(selector) {
+  return JSON.stringify(selector ?? {});
+}
+class AutoFetchDataAdapter {
+  options;
+  id;
+  onError;
+  fetchQueryItems;
+  mergeItems;
+  purgeDelay;
+  // Per-collection resources
+  storageAdapters = /* @__PURE__ */ new Map();
+  storageAdapterReady = /* @__PURE__ */ new Map();
+  collectionIndices = /* @__PURE__ */ new Map();
+  // Per-collection query registries and auto-fetch bookkeeping
+  queries = /* @__PURE__ */ new Map();
+  activeObservers = /* @__PURE__ */ new Map();
+  // per-collection: key->record
+  observerTimeouts = /* @__PURE__ */ new Map();
+  // per-collection
+  selectorIds = /* @__PURE__ */ new Map();
+  // per-collection: selectorKey -> Set<id>
+  idRefCounts = /* @__PURE__ */ new Map();
+  // per-collection: id -> refcount (for auto-fetched items)
+  autoloadIds = /* @__PURE__ */ new Map();
+  // per-collection: ids that were introduced via auto-fetch
+  constructor(options) {
+    this.options = options;
+    this.id = options.id || "autofetch-data-adapter";
+    this.onError = options.onError ?? ((error) => {
+      console.error(error);
+    });
+    this.fetchQueryItems = options.fetchQueryItems;
+    this.mergeItems = options.mergeItems ?? defaultMergeItems;
+    this.purgeDelay = options.purgeDelay ?? 1e4;
+    if (options.registerRemoteChange) {
+      void options.registerRemoteChange(async () => {
+        await this.forceRefetchAll();
+      });
+    }
+  }
+  createCollectionBackend(collection, indices) {
+    this.collectionIndices.set(collection.name, indices);
+    this.queries.set(collection.name, /* @__PURE__ */ new Map());
+    this.ensureStorageAdapter(collection.name);
+    this.activeObservers.set(collection.name, /* @__PURE__ */ new Map());
+    this.observerTimeouts.set(collection.name, /* @__PURE__ */ new Map());
+    this.selectorIds.set(collection.name, /* @__PURE__ */ new Map());
+    this.idRefCounts.set(collection.name, /* @__PURE__ */ new Map());
+    this.autoloadIds.set(collection.name, /* @__PURE__ */ new Set());
+    const ready = this.setupStorage(collection.name, indices);
+    this.storageAdapterReady.set(collection.name, ready);
+    const registerQuery = (selector, options) => {
+      const qid = queryId(selector, options);
+      const registry = this.queries.get(collection.name);
+      if (!registry)
+        throw new Error(`Collection ${collection.name} not initialized!`);
+      registry.set(qid, {
+        selector,
+        options,
+        items: [],
+        listeners: /* @__PURE__ */ new Set(),
+        ...registry.get(qid),
+        state: "active",
+        error: null
+      });
+      const key = selectorId(selector);
+      const perColObservers = this.activeObservers.get(collection.name);
+      const current = perColObservers?.get(key)?.count ?? 0;
+      perColObservers?.set(key, { selector, count: current + 1 });
+      const timeouts = this.observerTimeouts.get(collection.name);
+      const t = timeouts?.get(key);
+      if (t)
+        clearTimeout(t);
+      if (current === 0) {
+        void this.fetchAndIngest(collection.name, selector).catch(this.onError);
+      }
+      void this.fulfillQuery(collection.name, selector, options).catch(this.onError);
+    };
+    const unregisterQuery = (selector, options) => {
+      const qid = queryId(selector, options);
+      const registry = this.queries.get(collection.name);
+      registry?.delete(qid);
+      const key = selectorId(selector);
+      const perColObservers = this.activeObservers.get(collection.name);
+      const current = perColObservers?.get(key)?.count ?? 0;
+      const remaining = Math.max(0, current - 1);
+      if (remaining > 0) {
+        perColObservers?.set(key, { selector, count: remaining });
+        return;
+      }
+      const doPurge = () => {
+        perColObservers?.delete(key);
+        void this.purgeSelector(collection.name, selector).catch(this.onError);
+      };
+      if (this.purgeDelay === 0) {
+        doPurge();
+      } else {
+        const timeouts = this.observerTimeouts.get(collection.name);
+        const t = timeouts?.get(key);
+        if (t)
+          clearTimeout(t);
+        timeouts?.set(key, setTimeout(doPurge, this.purgeDelay));
+      }
+    };
+    const getQueryState = (selector, options) => {
+      const q = this.queries.get(collection.name)?.get(queryId(selector, options));
+      return q?.state ?? "active";
+    };
+    const getQueryError = (selector, options) => {
+      const q = this.queries.get(collection.name)?.get(queryId(selector, options));
+      return q?.error ?? null;
+    };
+    const getQueryResult = (selector, options) => {
+      const q = this.queries.get(collection.name)?.get(queryId(selector, options));
+      return q?.items ?? [];
+    };
+    const onQueryStateChange = (selector, options, callback) => {
+      const qid = queryId(selector, options);
+      const registry = this.queries.get(collection.name);
+      if (!registry)
+        throw new Error(`Collection ${collection.name} not initialized!`);
+      if (!registry.has(qid)) {
+        registry.set(qid, {
+          selector,
+          options,
+          state: "active",
+          error: null,
+          items: [],
+          listeners: /* @__PURE__ */ new Set()
+        });
+      }
+      registry.get(qid)?.listeners.add(callback);
+      return () => {
+        registry.get(qid)?.listeners.delete(callback);
+      };
+    };
+    return {
+      insert: async (item) => {
+        await ready;
+        const inserted = await this.insert(collection.name, item);
+        return inserted;
+      },
+      updateOne: async (selector, modifier) => {
+        await ready;
+        return this.updateOne(collection.name, selector, modifier);
+      },
+      updateMany: async (selector, modifier) => {
+        await ready;
+        return this.updateMany(collection.name, selector, modifier);
+      },
+      replaceOne: async (selector, replacement) => {
+        await ready;
+        return this.replaceOne(collection.name, selector, replacement);
+      },
+      removeOne: async (selector) => {
+        await ready;
+        return this.removeOne(collection.name, selector);
+      },
+      removeMany: async (selector) => {
+        await ready;
+        return this.removeMany(collection.name, selector);
+      },
+      registerQuery,
+      unregisterQuery,
+      getQueryState,
+      getQueryError,
+      getQueryResult,
+      onQueryStateChange,
+      executeQuery: async (selector, options) => {
+        await ready;
+        registerQuery(selector, options);
+        await new Promise((resolve) => {
+          let stop = () => {
+          };
+          stop = onQueryStateChange(selector, options, (state) => {
+            if (state === "active")
+              return;
+            resolve();
+            stop();
+          });
+        });
+        const result = getQueryResult(selector, options);
+        unregisterQuery(selector, options);
+        return result;
+      },
+      dispose: async () => {
+        this.storageAdapters.delete(collection.name);
+        this.queries.delete(collection.name);
+        this.collectionIndices.delete(collection.name);
+        this.storageAdapterReady.delete(collection.name);
+        this.activeObservers.delete(collection.name);
+        this.observerTimeouts.delete(collection.name);
+        this.selectorIds.delete(collection.name);
+        this.idRefCounts.delete(collection.name);
+        this.autoloadIds.delete(collection.name);
+      },
+      isReady: async () => {
+        await ready;
+      }
     };
-    this.unbindEvents = bindEvents();
   }
-  call(event, ...args) {
-    this.callbacks[event].forEach(({ callback, options }) => {
-      if (!options.skipInitial || !options.isInitial) {
-        callback(...args);
+  // ===== Auto-fetch mechanics =====
+  async forceRefetchAll() {
+    const tasks = [];
+    for (const [collectionName, observers] of this.activeObservers.entries()) {
+      for (const { selector, count } of observers.values()) {
+        if (count > 0)
+          tasks.push(this.fetchAndIngest(collectionName, selector));
       }
-    });
+    }
+    await Promise.all(tasks);
   }
-  hasCallbacks(events) {
-    return events.some((event) => this.callbacks[event].length > 0);
-  }
-  /**
-   * Determines if the observer has no active callbacks registered for any events.
-   * @returns A boolean indicating whether the observer is empty (i.e., no callbacks are registered).
-   */
-  isEmpty() {
-    return !this.hasCallbacks([
-      "added",
-      "addedBefore",
-      "changed",
-      "changedField",
-      "movedBefore",
-      "removed"
-    ]);
-  }
-  /**
-   * Compares the previous state of items with the new state and triggers the appropriate callbacks
-   * for events such as added, removed, changed, or moved items.
-   * @param getItems - A function that returns a promise resolving to the new items or the items themselves.
-   */
-  runChecks(getItems) {
-    const result = getItems();
-    if (result instanceof Promise) {
-      result.then((newItems) => this.checkItems(newItems)).catch((error) => {
-        console.error("Error while asynchronously querying items", error);
-      });
-    } else {
-      this.checkItems(result);
+  async fetchAndIngest(collectionName, selector) {
+    this.publishForSelector(collectionName, selector, "active", null);
+    try {
+      const items = await this.fetchQueryItems(collectionName, selector);
+      if (!items || !Array.isArray(items)) {
+        throw new Error("AutoFetchDataAdapter: fetchQueryItems must resolve to { items: T[] }");
+      }
+      const ids = items.map((i) => i.id);
+      const selectorKey = selectorId(selector);
+      const selMap = this.selectorIds.get(collectionName);
+      const previous = selMap?.get(selectorKey) ?? /* @__PURE__ */ new Set();
+      ids.forEach((id) => previous.add(id));
+      selMap?.set(selectorKey, previous);
+      await this.upsertMerged(collectionName, items);
+      await this.checkQueryUpdates(collectionName, items);
+    } catch (error) {
+      this.publishForSelector(collectionName, selector, "error", error);
+      this.onError(error);
     }
   }
-  checkItems(newItems) {
-    const oldItemsMap = new Map(this.previousItems.map((item, index) => [
-      item.id,
-      { item, index, beforeItem: this.previousItems[index + 1] || null }
-    ]));
-    const newItemsMap = new Map(newItems.map((item, index) => [
-      item.id,
-      { item, index, beforeItem: newItems[index + 1] || null }
-    ]));
-    if (this.hasCallbacks(["changed", "changedField", "movedBefore", "removed"])) {
-      oldItemsMap.forEach(({ item: oldItem, index, beforeItem: oldBeforeItem }) => {
-        const newItem = newItemsMap.get(oldItem.id);
-        if (newItem) {
-          if (this.hasCallbacks(["changed", "changedField"]) && !isEqual(newItem.item, oldItem)) {
-            this.call("changed", newItem.item);
-            if (this.hasCallbacks(["changedField"])) {
-              const keys = uniqueBy([
-                ...Object.keys(newItem.item),
-                ...Object.keys(oldItem)
-              ], (value) => value);
-              keys.forEach((key) => {
-                if (isEqual(newItem.item[key], oldItem[key]))
-                  return;
-                this.call("changedField", newItem.item, key, oldItem[key], newItem.item[key]);
-              });
-            }
-          }
-          if (newItem.index !== index && newItem.beforeItem?.id !== oldBeforeItem?.id) {
-            this.call("movedBefore", newItem.item, newItem.beforeItem);
-          }
-        } else {
-          this.call("removed", oldItem);
-        }
-      });
+  async purgeSelector(collectionName, selector) {
+    const selectorKey = selectorId(selector);
+    const selMap = this.selectorIds.get(collectionName);
+    const ids = selMap?.get(selectorKey);
+    selMap?.delete(selectorKey);
+    if (!ids || ids.size === 0)
+      return;
+    const referenceMap = this.idRefCounts.get(collectionName);
+    const autoload = this.autoloadIds.get(collectionName);
+    const toRemove = [];
+    for (const id of ids) {
+      const current = referenceMap?.get(id) ?? 0;
+      const next = Math.max(0, current - 1);
+      if (next === 0) {
+        referenceMap?.delete(id);
+        if (autoload?.has(id))
+          toRemove.push(id);
+      } else {
+        referenceMap?.set(id, next);
+      }
     }
-    if (this.hasCallbacks(["added", "addedBefore"])) {
-      newItems.forEach((newItem, index) => {
-        const oldItem = oldItemsMap.get(newItem.id);
-        if (oldItem)
-          return;
-        this.call("added", newItem);
-        this.call("addedBefore", newItem, newItems[index + 1] || null);
-      });
+    if (toRemove.length === 0)
+      return;
+    const storage = this.storageAdapters.get(collectionName);
+    if (!storage)
+      throw new Error(`No persistence adapter for collection ${collectionName}`);
+    const items = await storage.readIds(toRemove);
+    if (items.length > 0) {
+      await storage.remove(items);
+      await this.checkQueryUpdates(collectionName, items);
+    }
+    toRemove.forEach((id) => autoload?.delete(id));
+  }
+  // ===== Core query + CRUD plumbing (index-aware, same semantics as AsyncDataAdapter) =====
+  async setupStorage(collectionName, indices) {
+    const storage = this.storageAdapters.get(collectionName);
+    if (!storage)
+      throw new Error(`No persistence adapter for collection ${collectionName}`);
+    await Promise.all(indices.map((field) => storage.createIndex(field)));
+    await storage.setup();
+  }
+  ensureStorageAdapter(name) {
+    if (this.storageAdapters.has(name))
+      return;
+    const adapter = this.options.storage && this.options.storage(name);
+    if (!adapter)
+      return;
+    this.storageAdapters.set(name, adapter);
+  }
+  publishForSelector(collectionName, selector, state, error) {
+    const registry = this.queries.get(collectionName);
+    if (!registry)
+      return;
+    for (const query of registry.values()) {
+      if (!isEqual(query.selector, selector))
+        continue;
+      this.publishState(collectionName, queryId(query.selector, query.options), state, error);
+    }
+  }
+  publishState(collectionName, qid, state, error) {
+    const query = this.queries.get(collectionName)?.get(qid);
+    if (!query)
+      return;
+    query.state = state;
+    query.error = error;
+    for (const callback of query.listeners) {
+      try {
+        callback(state);
+      } catch (error_) {
+        this.onError(error_);
+      }
+    }
+  }
+  publishResult(collectionName, qid, items) {
+    const query = this.queries.get(collectionName)?.get(qid);
+    if (!query)
+      return;
+    query.items = items;
+    this.queries.get(collectionName)?.set(qid, query);
+  }
+  async fulfillQuery(collectionName, selector, options) {
+    const qid = queryId(selector, options);
+    const registry = this.queries.get(collectionName);
+    if (!registry)
+      throw new Error(`Collection ${collectionName} not initialized!`);
+    const rec = registry.get(qid);
+    if (!rec)
+      return;
+    this.publishState(collectionName, qid, "active", null);
+    try {
+      const items = await this.executeQuery(collectionName, selector, options);
+      this.publishResult(collectionName, qid, items);
+      this.publishState(collectionName, qid, "complete", null);
+    } catch (error) {
+      this.publishState(collectionName, qid, "error", error);
+    }
+  }
+  async getIndexInfo(collectionName, selector) {
+    const storage = this.storageAdapters.get(collectionName);
+    if (!storage)
+      throw new Error(`No persistence adapter for collection ${collectionName}`);
+    if (selector != null && Object.keys(selector).length === 1 && "id" in selector && typeof selector.id !== "object") {
+      return { matched: true, ids: [selector.id], optimizedSelector: {} };
+    }
+    if (selector == null) {
+      return { matched: false, ids: [], optimizedSelector: {} };
     }
-    this.previousItems = newItems;
-    Object.keys(this.callbacks).forEach((key) => {
-      const event = key;
-      const callbacks = this.callbacks[event];
-      this.callbacks[event] = callbacks.map((callback) => ({
-        ...callback,
-        options: {
-          ...callback.options,
-          isInitial: false
+    const indices = this.collectionIndices.get(collectionName) ?? [];
+    return getIndexInfo.default(indices.map((field) => async (flatSelector) => {
+      if (!Object.hasOwnProperty.call(flatSelector, field))
+        return { matched: false };
+      const index = await storage.readIndex(field);
+      const fieldSelector = flatSelector[field];
+      const filtersForNull = fieldSelector == null || fieldSelector.$exists === false;
+      const keys = filtersForNull ? { include: null, exclude: [...index.keys()].filter((key) => key != null) } : getMatchingKeys(field, flatSelector);
+      if (keys.include == null && keys.exclude == null)
+        return { matched: false };
+      let includedIds = [];
+      if (keys.include == null) {
+        for (const set of index.values())
+          for (const pos of set)
+            includedIds.push(pos);
+      } else {
+        for (const key of keys.include) {
+          const idSet = index.get(key);
+          if (idSet)
+            for (const id of idSet)
+              includedIds.push(id);
         }
-      }));
-    });
+      }
+      if (keys.exclude != null) {
+        const excludeIds = /* @__PURE__ */ new Set();
+        for (const key of keys.exclude) {
+          const idSet = index.get(key);
+          if (idSet)
+            for (const id of idSet)
+              excludeIds.add(id);
+        }
+        includedIds = includedIds.filter((pos) => !excludeIds.has(pos));
+      }
+      return {
+        matched: true,
+        ids: includedIds,
+        fields: [field],
+        keepSelector: filtersForNull
+      };
+    }), selector);
   }
-  /**
-   * Stops the observer by unbinding all events and cleaning up resources.
-   */
-  stop() {
-    this.unbindEvents();
-  }
-  /**
-   * Registers callbacks for specific events to observe changes in the collection.
-   * @param callbacks - An object containing the callbacks for various events (e.g., 'added', 'removed').
-   * @param skipInitial - A boolean indicating whether to skip invoking the callbacks for the initial state of the collection.
-   */
-  addCallbacks(callbacks, skipInitial = false) {
-    Object.keys(callbacks).forEach((key) => {
-      const typedKey = key;
-      this.callbacks[typedKey].push({
-        callback: callbacks[typedKey],
-        options: { skipInitial, isInitial: true }
-      });
-    });
+  async queryItems(collectionName, selector) {
+    const storage = this.storageAdapters.get(collectionName);
+    if (!storage)
+      throw new Error(`No persistence adapter for collection ${collectionName}`);
+    const index = await this.getIndexInfo(collectionName, selector);
+    const matchItems = (item) => {
+      if (index.optimizedSelector == null)
+        return true;
+      if (Object.keys(index.optimizedSelector).length <= 0)
+        return true;
+      return match(item, index.optimizedSelector);
+    };
+    if (index.matched) {
+      const items = await storage.readIds(index.ids);
+      if (isEqual(index.optimizedSelector, {}))
+        return items;
+      return items.filter(matchItems);
+    } else {
+      const allItems = await storage.readAll();
+      if (isEqual(selector, {}))
+        return allItems;
+      return allItems.filter(matchItems);
+    }
   }
-  /**
-   * Removes the specified callbacks for specific events, unregistering them from the observer.
-   * @param callbacks - An object containing the callbacks to be removed for various events.
-   */
-  removeCallbacks(callbacks) {
-    Object.keys(callbacks).forEach((key) => {
-      const typedKey = key;
-      const index = this.callbacks[typedKey].findIndex(({ callback }) => callback === callbacks[typedKey]);
-      this.callbacks[typedKey].splice(index, 1);
+  async executeQuery(collectionName, selector, options) {
+    const items = await this.queryItems(collectionName, selector || {});
+    const { sort, skip, limit, fields } = options || {};
+    const sorted = sort ? sortItems(items, sort) : items;
+    const skipped = skip ? sorted.slice(skip) : sorted;
+    const limited = limit ? skipped.slice(0, limit) : skipped;
+    const idExcluded = fields && fields.id === 0;
+    return limited.map((item) => {
+      if (!fields)
+        return item;
+      return { ...idExcluded ? {} : { id: item.id }, ...project(item, fields) };
     });
   }
+  async checkQueryUpdates(collectionName, changedItems) {
+    const registry = this.queries.get(collectionName);
+    if (!registry)
+      throw new Error(`Collection ${collectionName} not initialized!`);
+    if (registry.size === 0)
+      return;
+    const affected = [...registry.values()].filter(({ selector }) => changedItems.some((item) => match(item, selector)));
+    if (affected.length === 0)
+      return;
+    for (const { selector, options } of affected) {
+      const qid = queryId(selector, options);
+      this.publishState(collectionName, qid, "active", null);
+    }
+    await Promise.all(affected.map(async ({ selector, options }) => {
+      const qid = queryId(selector, options);
+      try {
+        const items = await this.executeQuery(collectionName, selector, options);
+        this.publishResult(collectionName, qid, items);
+        this.publishState(collectionName, qid, "complete", null);
+      } catch (error) {
+        this.publishState(collectionName, qid, "error", error);
+      }
+    }));
+  }
+  // ===== CRUD with push-style query updates =====
+  async insert(collectionName, newItem) {
+    const storage = this.storageAdapters.get(collectionName);
+    if (!storage)
+      throw new Error(`No persistence adapter for collection ${collectionName}`);
+    const existing = await this.executeQuery(collectionName, { id: newItem.id }, { limit: 1 });
+    if (existing.length > 0)
+      throw new Error(`Item with id ${String(newItem.id)} already exists`);
+    await storage.insert([newItem]);
+    await this.checkQueryUpdates(collectionName, [newItem]);
+    return newItem;
+  }
+  async updateOne(collectionName, selector, modifier) {
+    const storage = this.storageAdapters.get(collectionName);
+    if (!storage)
+      throw new Error(`No persistence adapter for collection ${collectionName}`);
+    const items = await this.executeQuery(collectionName, selector, { limit: 1 });
+    const [item] = items;
+    const { $setOnInsert, ...rest } = modifier;
+    if (item == null)
+      return [];
+    const modified = modify(deepClone.default(item), rest);
+    if (item.id !== modified.id) {
+      const existing = await this.executeQuery(collectionName, { id: modified.id }, { limit: 1 });
+      if (existing.length > 0)
+        throw new Error(`Item with id ${String(modified.id)} already exists`);
+    }
+    await storage.replace([modified]);
+    await this.checkQueryUpdates(collectionName, [item, modified]);
+    return [modified];
+  }
+  async updateMany(collectionName, selector, modifier) {
+    const storage = this.storageAdapters.get(collectionName);
+    if (!storage)
+      throw new Error(`No persistence adapter for collection ${collectionName}`);
+    const items = await this.executeQuery(collectionName, selector);
+    if (items.length === 0)
+      return [];
+    const { $setOnInsert, ...rest } = modifier;
+    const changed = await Promise.all(items.map(async (item) => {
+      const modified = modify(deepClone.default(item), rest);
+      if (item.id !== modified.id) {
+        const existing = await this.executeQuery(collectionName, { id: modified.id }, { limit: 1 });
+        if (existing.length > 0)
+          throw new Error(`Item with id ${String(modified.id)} already exists`);
+      }
+      return modified;
+    }));
+    await storage.replace(changed);
+    await this.checkQueryUpdates(collectionName, [...items, ...changed]);
+    return changed;
+  }
+  async replaceOne(collectionName, selector, replacement) {
+    const storage = this.storageAdapters.get(collectionName);
+    if (!storage)
+      throw new Error(`No persistence adapter for collection ${collectionName}`);
+    const items = await this.executeQuery(collectionName, selector, { limit: 1 });
+    const [item] = items;
+    if (item == null)
+      return [];
+    const modified = { ...replacement, id: replacement.id ?? item.id };
+    if (item.id !== modified.id) {
+      const existing = await this.executeQuery(collectionName, { id: modified.id }, { limit: 1 });
+      if (existing.length > 0)
+        throw new Error(`Item with id ${String(modified.id)} already exists`);
+    }
+    await storage.replace([modified]);
+    await this.checkQueryUpdates(collectionName, [item, modified]);
+    return [modified];
+  }
+  async removeOne(collectionName, selector) {
+    const storage = this.storageAdapters.get(collectionName);
+    if (!storage)
+      throw new Error(`No persistence adapter for collection ${collectionName}`);
+    const items = await this.executeQuery(collectionName, selector, { limit: 1 });
+    const [item] = items;
+    if (item == null)
+      return [];
+    await storage.remove([item]);
+    await this.checkQueryUpdates(collectionName, [item]);
+    return [item];
+  }
+  async removeMany(collectionName, selector) {
+    const storage = this.storageAdapters.get(collectionName);
+    if (!storage)
+      throw new Error(`No persistence adapter for collection ${collectionName}`);
+    const items = await this.executeQuery(collectionName, selector);
+    if (items.length === 0)
+      return [];
+    await storage.remove(items);
+    await this.checkQueryUpdates(collectionName, items);
+    return items;
+  }
+  // ===== Upsert/merge helper for ingesting fetched items =====
+  async upsertMerged(collectionName, incoming) {
+    if (incoming.length === 0)
+      return;
+    const storage = this.storageAdapters.get(collectionName);
+    if (!storage)
+      throw new Error(`No persistence adapter for collection ${collectionName}`);
+    const ids = incoming.map((i) => i.id);
+    const existing = await storage.readIds(ids);
+    const existingById = new Map(existing.map((it) => [it.id, it]));
+    const toInsert = [];
+    const toReplace = [];
+    const referenceMap = this.idRefCounts.get(collectionName);
+    const autoload = this.autoloadIds.get(collectionName);
+    for (const item of incoming) {
+      const previous = existingById.get(item.id);
+      if (previous) {
+        toReplace.push(this.mergeItems(previous, item));
+      } else {
+        toInsert.push(item);
+      }
+      autoload?.add(item.id);
+      referenceMap?.set(item.id, (referenceMap?.get(item.id) ?? 0) + 1);
+    }
+    if (toInsert.length > 0)
+      await storage.insert(toInsert);
+    if (toReplace.length > 0)
+      await storage.replace(toReplace);
+  }
 }
-module.exports = Observer;
+module.exports = AutoFetchDataAdapter;