@signaldb/core 1.3.0 → 1.4.0

package/dist/.vite/manifest.json

@@ -163,7 +163,7 @@
     "src": "src/utils/isEqual.ts"
   },
   "src/utils/isFieldExpression.ts": {
-    "file": "index.cjs27.js",
+    "file": "index.cjs29.js",
     "name": "utils/isFieldExpression",
     "src": "src/utils/isFieldExpression.ts"
   },
@@ -197,7 +197,7 @@
     "src": "src/utils/serializeValue.ts"
   },
   "src/utils/set.ts": {
-    "file": "index.cjs28.js",
+    "file": "index.cjs27.js",
     "name": "utils/set",
     "src": "src/utils/set.ts"
   },
@@ -210,7 +210,7 @@
     ]
   },
   "src/utils/uniqueBy.ts": {
-    "file": "index.cjs29.js",
+    "file": "index.cjs28.js",
     "name": "utils/uniqueBy",
     "src": "src/utils/uniqueBy.ts"
   }

package/dist/Collection/index.d.ts

@@ -41,6 +41,7 @@ interface CollectionEvents<T extends BaseItem, U = T> {
     'insert': (item: Omit<T, 'id'> & Partial<Pick<T, 'id'>>) => void;
     'updateOne': (selector: Selector<T>, modifier: Modifier<T>) => void;
     'updateMany': (selector: Selector<T>, modifier: Modifier<T>) => void;
+    'replaceOne': (selector: Selector<T>, item: Omit<T, 'id'> & Partial<Pick<T, 'id'>>) => void;
     'removeOne': (selector: Selector<T>) => void;
     'removeMany': (selector: Selector<T>) => void;
     '_debug.getItems': (callstack: string, selector: Selector<T> | undefined, measuredTime: number) => void;
@@ -49,6 +50,7 @@ interface CollectionEvents<T extends BaseItem, U = T> {
     '_debug.insert': (callstack: string, item: Omit<T, 'id'> & Partial<Pick<T, 'id'>>) => void;
     '_debug.updateOne': (callstack: string, selector: Selector<T>, modifier: Modifier<T>) => void;
     '_debug.updateMany': (callstack: string, selector: Selector<T>, modifier: Modifier<T>) => void;
+    '_debug.replaceOne': (callstack: string, selector: Selector<T>, item: Omit<T, 'id'> & Partial<Pick<T, 'id'>>) => void;
     '_debug.removeOne': (callstack: string, selector: Selector<T>) => void;
     '_debug.removeMany': (callstack: string, selector: Selector<T>) => void;
 }
@@ -229,18 +231,38 @@ export default class Collection<T extends BaseItem<I> = BaseItem, I = any, U = T
      * Updates a single item in the collection that matches the given selector.
      * @param selector - The criteria to select the item to update.
      * @param modifier - The modifications to apply to the item.
+     * @param [options] - Optional settings for the update operation.
+     * @param [options.upsert] - If `true`, creates a new item if no item matches the selector.
      * @returns The number of items updated (0 or 1).
      * @throws {Error} If the collection is disposed or invalid arguments are provided.
      */
-    updateOne(selector: Selector<T>, modifier: Modifier<T>): 0 | 1;
+    updateOne(selector: Selector<T>, modifier: Modifier<T>, options?: {
+        upsert?: boolean;
+    }): 0 | 1;
     /**
      * Updates multiple items in the collection that match the given selector.
      * @param selector - The criteria to select the items to update.
      * @param modifier - The modifications to apply to the items.
+     * @param [options] - Optional settings for the update operation.
+     * @param [options.upsert] - If `true`, creates new items if no items match the selector.
      * @returns The number of items updated.
      * @throws {Error} If the collection is disposed or invalid arguments are provided.
      */
-    updateMany(selector: Selector<T>, modifier: Modifier<T>): number;
+    updateMany(selector: Selector<T>, modifier: Modifier<T>, options?: {
+        upsert?: boolean;
+    }): number;
+    /**
+     * Replaces a single item in the collection that matches the given selector.
+     * @param selector - The criteria to select the item to replace.
+     * @param replacement - The item to replace the selected item with.
+     * @param [options] - Optional settings for the replace operation.
+     * @param [options.upsert] - If `true`, creates a new item if no item matches the selector.
+     * @returns The number of items replaced (0 or 1).
+     * @throws {Error} If the collection is disposed or invalid arguments are provided.
+     */
+    replaceOne(selector: Selector<T>, replacement: Omit<T, 'id'> & Partial<Pick<T, 'id'>>, options?: {
+        upsert?: boolean;
+    }): 0 | 1;
     /**
      * Removes a single item from the collection that matches the given selector.
      * @param selector - The criteria to select the item to remove.

package/dist/index.cjs10.js

@@ -1,6 +1,9 @@
 "use strict";
 const mingo = require("mingo");
 function modify(item, modifier) {
+  const hasOperators = Object.keys(modifier).some((key) => key.startsWith("$"));
+  if (!hasOperators)
+    return modifier;
   const clonedItem = { ...item };
   mingo.update(clonedItem, modifier);
   return clonedItem;

package/dist/index.cjs13.js

@@ -10,14 +10,38 @@ function createExternalIndex(field, index) {
       const keys = getMatchingKeys(field, selector);
       if (keys.include == null && keys.exclude == null)
         return { matched: false };
-      const includedKeys = keys.include == null ? [...index.values()].reduce((memo, set) => [...memo, ...set], []) : keys.include.reduce((memo, key) => [...memo, ...index.get(key) || []], []);
-      const itemPositions = keys.exclude == null ? includedKeys : keys.exclude.reduce((memo, key) => memo.filter((i) => {
-        var _a;
-        return !((_a = index.get(key)) == null ? void 0 : _a.has(i));
-      }), includedKeys);
+      let includedPositions = [];
+      if (keys.include == null) {
+        for (const set of index.values()) {
+          for (const pos of set) {
+            includedPositions.push(pos);
+          }
+        }
+      } else {
+        for (const key of keys.include) {
+          const posSet = index.get(key);
+          if (posSet) {
+            for (const pos of posSet) {
+              includedPositions.push(pos);
+            }
+          }
+        }
+      }
+      if (keys.exclude != null) {
+        const excludeSet = /* @__PURE__ */ new Set();
+        for (const key of keys.exclude) {
+          const posSet = index.get(key);
+          if (posSet) {
+            for (const pos of posSet) {
+              excludeSet.add(pos);
+            }
+          }
+        }
+        includedPositions = includedPositions.filter((pos) => !excludeSet.has(pos));
+      }
       return {
         matched: true,
-        positions: itemPositions,
+        positions: includedPositions,
         fields: [field]
       };
     },

package/dist/index.cjs2.js

@@ -567,61 +567,140 @@ const _Collection = class _Collection extends EventEmitter {
    * Updates a single item in the collection that matches the given selector.
    * @param selector - The criteria to select the item to update.
    * @param modifier - The modifications to apply to the item.
+   * @param [options] - Optional settings for the update operation.
+   * @param [options.upsert] - If `true`, creates a new item if no item matches the selector.
    * @returns The number of items updated (0 or 1).
    * @throws {Error} If the collection is disposed or invalid arguments are provided.
    */
-  updateOne(selector, modifier) {
+  updateOne(selector, modifier, options) {
     if (this.isDisposed)
       throw new Error("Collection is disposed");
     if (!selector)
       throw new Error("Invalid selector");
     if (!modifier)
       throw new Error("Invalid modifier");
+    const { $setOnInsert, ...restModifier } = modifier;
     const { item, index } = this.getItemAndIndex(selector);
-    if (item == null)
-      return 0;
-    const modifiedItem = modify(deepClone.default(item), modifier);
-    const existingItem = this.findOne({ id: modifiedItem.id }, { reactive: false });
-    if (!isEqual(existingItem, { ...existingItem, id: modifiedItem.id }))
-      throw new Error("Item with same id already exists");
-    this.memory().splice(index, 1, modifiedItem);
-    this.rebuildIndices();
-    this.emit("changed", modifiedItem, modifier);
+    if (item == null) {
+      if (options == null ? void 0 : options.upsert) {
+        const newItem = modify({}, {
+          ...restModifier,
+          $set: {
+            ...$setOnInsert,
+            ...restModifier.$set
+          }
+        });
+        if (newItem.id != null && this.getItemAndIndex({ id: newItem.id }).item != null) {
+          throw new Error("Item with same id already exists");
+        }
+        this.insert(newItem);
+      }
+    } else {
+      const modifiedItem = modify(deepClone.default(item), restModifier);
+      if (item.id !== modifiedItem.id && this.getItemAndIndex({ id: modifiedItem.id }).item != null) {
+        throw new Error("Item with same id already exists");
+      }
+      this.memory().splice(index, 1, modifiedItem);
+      this.rebuildIndices();
+      this.emit("changed", modifiedItem, restModifier);
+    }
     this.emit("updateOne", selector, modifier);
     this.executeInDebugMode((callstack) => this.emit("_debug.updateOne", callstack, selector, modifier));
+    if (item == null && !(options == null ? void 0 : options.upsert))
+      return 0;
     return 1;
   }
   /**
    * Updates multiple items in the collection that match the given selector.
    * @param selector - The criteria to select the items to update.
    * @param modifier - The modifications to apply to the items.
+   * @param [options] - Optional settings for the update operation.
+   * @param [options.upsert] - If `true`, creates new items if no items match the selector.
    * @returns The number of items updated.
    * @throws {Error} If the collection is disposed or invalid arguments are provided.
    */
-  updateMany(selector, modifier) {
+  updateMany(selector, modifier, options) {
     if (this.isDisposed)
       throw new Error("Collection is disposed");
     if (!selector)
       throw new Error("Invalid selector");
     if (!modifier)
       throw new Error("Invalid modifier");
+    const { $setOnInsert, ...restModifier } = modifier;
     const items = this.getItems(selector);
-    const modifiedItems = [];
-    items.forEach((item) => {
+    if (items.length === 0 && (options == null ? void 0 : options.upsert)) {
+      const newItem = modify({}, {
+        ...restModifier,
+        $set: {
+          ...$setOnInsert,
+          ...restModifier.$set
+        }
+      });
+      if (newItem.id != null && this.getItemAndIndex({ id: newItem.id }).item != null) {
+        throw new Error("Item with same id already exists");
+      }
+      this.insert(newItem);
+    }
+    const changes = items.map((item) => {
       const { index } = this.getItemAndIndex({ id: item.id });
       if (index === -1)
-        throw new Error("Cannot resolve index for item");
-      const modifiedItem = modify(deepClone.default(item), modifier);
-      this.memory().splice(index, 1, modifiedItem);
-      modifiedItems.push(modifiedItem);
+        throw new Error(`Cannot resolve index for item with id '${item.id}'`);
+      const modifiedItem = modify(deepClone.default(item), restModifier);
+      if (item.id !== modifiedItem.id && this.getItemAndIndex({ id: modifiedItem.id }).item != null) {
+        throw new Error(`Item with same id '${modifiedItem.id}' already exists`);
+      }
+      return {
+        item: modifiedItem,
+        index
+      };
+    });
+    changes.forEach(({ item, index }) => {
+      this.memory().splice(index, 1, item);
     });
     this.rebuildIndices();
-    modifiedItems.forEach((modifiedItem) => {
-      this.emit("changed", modifiedItem, modifier);
+    changes.forEach(({ item }) => {
+      this.emit("changed", item, restModifier);
     });
     this.emit("updateMany", selector, modifier);
     this.executeInDebugMode((callstack) => this.emit("_debug.updateMany", callstack, selector, modifier));
-    return modifiedItems.length;
+    return changes.length === 0 && (options == null ? void 0 : options.upsert) ? 1 : changes.length;
+  }
+  /**
+   * Replaces a single item in the collection that matches the given selector.
+   * @param selector - The criteria to select the item to replace.
+   * @param replacement - The item to replace the selected item with.
+   * @param [options] - Optional settings for the replace operation.
+   * @param [options.upsert] - If `true`, creates a new item if no item matches the selector.
+   * @returns The number of items replaced (0 or 1).
+   * @throws {Error} If the collection is disposed or invalid arguments are provided.
+   */
+  replaceOne(selector, replacement, options) {
+    if (this.isDisposed)
+      throw new Error("Collection is disposed");
+    if (!selector)
+      throw new Error("Invalid selector");
+    const { item, index } = this.getItemAndIndex(selector);
+    if (item == null) {
+      if (options == null ? void 0 : options.upsert) {
+        if (replacement.id != null && this.getItemAndIndex({ id: replacement.id }).item != null) {
+          throw new Error("Item with same id already exists");
+        }
+        this.insert(replacement);
+      }
+    } else {
+      if (item.id !== replacement.id && this.getItemAndIndex({ id: replacement.id }).item != null) {
+        throw new Error("Item with same id already exists");
+      }
+      const modifiedItem = { id: item.id, ...replacement };
+      this.memory().splice(index, 1, modifiedItem);
+      this.rebuildIndices();
+      this.emit("changed", modifiedItem, replacement);
+    }
+    this.emit("replaceOne", selector, replacement);
+    this.executeInDebugMode((callstack) => this.emit("_debug.replaceOne", callstack, selector, replacement));
+    if (item == null && !(options == null ? void 0 : options.upsert))
+      return 0;
+    return 1;
   }
   /**
    * Removes a single item from the collection that matches the given selector.

package/dist/index.cjs22.js

@@ -1,6 +1,6 @@
 "use strict";
 const get = require("./index.cjs25.js");
-const set = require("./index.cjs28.js");
+const set = require("./index.cjs27.js");
 function project(item, fields) {
   const allFieldsDeactivated = Object.values(fields).every((value) => value === 0);
   if (allFieldsDeactivated) {

package/dist/index.cjs23.js

@@ -3,7 +3,7 @@ var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 const isEqual = require("./index.cjs9.js");
-const uniqueBy = require("./index.cjs29.js");
+const uniqueBy = require("./index.cjs28.js");
 class Observer {
   /**
    * Creates a new instance of the `Observer` class.

package/dist/index.cjs26.js

@@ -1,5 +1,5 @@
 "use strict";
-const isFieldExpression = require("./index.cjs27.js");
+const isFieldExpression = require("./index.cjs29.js");
 const serializeValue = require("./index.cjs16.js");
 function getMatchingKeys(field, selector) {
   const result = { include: null, exclude: null };

package/dist/index.cjs27.js

@@ -1,42 +1,29 @@
 "use strict";
-const expressionKeys = /* @__PURE__ */ new Set([
-  "$eq",
-  "$gt",
-  "$gte",
-  "$lt",
-  "$lte",
-  "$in",
-  "$nin",
-  "$ne",
-  "$exists",
-  "$not",
-  "$expr",
-  "$jsonSchema",
-  "$mod",
-  "$regex",
-  "$options",
-  "$text",
-  "$where",
-  "$all",
-  "$elemMatch",
-  "$size",
-  "$bitsAllClear",
-  "$bitsAllSet",
-  "$bitsAnyClear",
-  "$bitsAnySet"
-]);
-function isFieldExpression(expression) {
-  if (typeof expression !== "object" || expression == null) {
-    return false;
-  }
-  const keys = Object.keys(expression);
-  if (keys.length === 0) {
-    return false;
-  }
-  const hasInvalidKeys = keys.some((key) => !expressionKeys.has(key));
-  if (hasInvalidKeys)
-    return false;
-  const hasValidKeys = keys.every((key) => expressionKeys.has(key));
-  return hasValidKeys;
+function set(object, path, value, deleteIfUndefined = false) {
+  if (object == null)
+    return object;
+  const segments = path.split(/[.[\]]/g);
+  if (segments[0] === "")
+    segments.shift();
+  if (segments.at(-1) === "")
+    segments.pop();
+  const apply = (node) => {
+    if (segments.length > 1) {
+      const key = segments.shift();
+      const nextIsNumber = !Number.isNaN(Number.parseInt(segments[0], 10));
+      if (node[key] === void 0) {
+        node[key] = nextIsNumber ? [] : {};
+      }
+      apply(node[key]);
+    } else {
+      if (deleteIfUndefined && value === void 0) {
+        delete node[segments[0]];
+        return;
+      }
+      node[segments[0]] = value;
+    }
+  };
+  apply(object);
+  return object;
 }
-module.exports = isFieldExpression;
+module.exports = set;

package/dist/index.cjs28.js

@@ -1,29 +1,9 @@
 "use strict";
-function set(object, path, value, deleteIfUndefined = false) {
-  if (object == null)
-    return object;
-  const segments = path.split(/[.[\]]/g);
-  if (segments[0] === "")
-    segments.shift();
-  if (segments.at(-1) === "")
-    segments.pop();
-  const apply = (node) => {
-    if (segments.length > 1) {
-      const key = segments.shift();
-      const nextIsNumber = !Number.isNaN(Number.parseInt(segments[0], 10));
-      if (node[key] === void 0) {
-        node[key] = nextIsNumber ? [] : {};
-      }
-      apply(node[key]);
-    } else {
-      if (deleteIfUndefined && value === void 0) {
-        delete node[segments[0]];
-        return;
-      }
-      node[segments[0]] = value;
-    }
-  };
-  apply(object);
-  return object;
+function uniqueBy(array, fn) {
+  const set = /* @__PURE__ */ new Set();
+  return array.filter((element) => {
+    const value = typeof fn === "function" ? fn(element) : element[fn];
+    return !set.has(value) && set.add(value);
+  });
 }
-module.exports = set;
+module.exports = uniqueBy;

package/dist/index.cjs29.js

@@ -1,9 +1,42 @@
 "use strict";
-function uniqueBy(array, fn) {
-  const set = /* @__PURE__ */ new Set();
-  return array.filter((element) => {
-    const value = typeof fn === "function" ? fn(element) : element[fn];
-    return !set.has(value) && set.add(value);
-  });
+const expressionKeys = /* @__PURE__ */ new Set([
+  "$eq",
+  "$gt",
+  "$gte",
+  "$lt",
+  "$lte",
+  "$in",
+  "$nin",
+  "$ne",
+  "$exists",
+  "$not",
+  "$expr",
+  "$jsonSchema",
+  "$mod",
+  "$regex",
+  "$options",
+  "$text",
+  "$where",
+  "$all",
+  "$elemMatch",
+  "$size",
+  "$bitsAllClear",
+  "$bitsAllSet",
+  "$bitsAnyClear",
+  "$bitsAnySet"
+]);
+function isFieldExpression(expression) {
+  if (typeof expression !== "object" || expression == null) {
+    return false;
+  }
+  const keys = Object.keys(expression);
+  if (keys.length === 0) {
+    return false;
+  }
+  const hasInvalidKeys = keys.some((key) => !expressionKeys.has(key));
+  if (hasInvalidKeys)
+    return false;
+  const hasValidKeys = keys.every((key) => expressionKeys.has(key));
+  return hasValidKeys;
 }
-module.exports = uniqueBy;
+module.exports = isFieldExpression;

package/dist/index10.mjs

@@ -1,5 +1,8 @@
 import { update } from "mingo";
 function modify(item, modifier) {
+  const hasOperators = Object.keys(modifier).some((key) => key.startsWith("$"));
+  if (!hasOperators)
+    return modifier;
   const clonedItem = { ...item };
   update(clonedItem, modifier);
   return clonedItem;

package/dist/index13.mjs

@@ -8,14 +8,38 @@ function createExternalIndex(field, index) {
       const keys = getMatchingKeys(field, selector);
       if (keys.include == null && keys.exclude == null)
         return { matched: false };
-      const includedKeys = keys.include == null ? [...index.values()].reduce((memo, set) => [...memo, ...set], []) : keys.include.reduce((memo, key) => [...memo, ...index.get(key) || []], []);
-      const itemPositions = keys.exclude == null ? includedKeys : keys.exclude.reduce((memo, key) => memo.filter((i) => {
-        var _a;
-        return !((_a = index.get(key)) == null ? void 0 : _a.has(i));
-      }), includedKeys);
+      let includedPositions = [];
+      if (keys.include == null) {
+        for (const set of index.values()) {
+          for (const pos of set) {
+            includedPositions.push(pos);
+          }
+        }
+      } else {
+        for (const key of keys.include) {
+          const posSet = index.get(key);
+          if (posSet) {
+            for (const pos of posSet) {
+              includedPositions.push(pos);
+            }
+          }
+        }
+      }
+      if (keys.exclude != null) {
+        const excludeSet = /* @__PURE__ */ new Set();
+        for (const key of keys.exclude) {
+          const posSet = index.get(key);
+          if (posSet) {
+            for (const pos of posSet) {
+              excludeSet.add(pos);
+            }
+          }
+        }
+        includedPositions = includedPositions.filter((pos) => !excludeSet.has(pos));
+      }
       return {
         matched: true,
-        positions: itemPositions,
+        positions: includedPositions,
         fields: [field]
       };
     },

package/dist/index2.mjs

@@ -566,61 +566,140 @@ const _Collection = class _Collection extends EventEmitter {
    * Updates a single item in the collection that matches the given selector.
    * @param selector - The criteria to select the item to update.
    * @param modifier - The modifications to apply to the item.
+   * @param [options] - Optional settings for the update operation.
+   * @param [options.upsert] - If `true`, creates a new item if no item matches the selector.
    * @returns The number of items updated (0 or 1).
    * @throws {Error} If the collection is disposed or invalid arguments are provided.
    */
-  updateOne(selector, modifier) {
+  updateOne(selector, modifier, options) {
     if (this.isDisposed)
       throw new Error("Collection is disposed");
     if (!selector)
       throw new Error("Invalid selector");
     if (!modifier)
       throw new Error("Invalid modifier");
+    const { $setOnInsert, ...restModifier } = modifier;
     const { item, index } = this.getItemAndIndex(selector);
-    if (item == null)
-      return 0;
-    const modifiedItem = modify(deepClone(item), modifier);
-    const existingItem = this.findOne({ id: modifiedItem.id }, { reactive: false });
-    if (!isEqual(existingItem, { ...existingItem, id: modifiedItem.id }))
-      throw new Error("Item with same id already exists");
-    this.memory().splice(index, 1, modifiedItem);
-    this.rebuildIndices();
-    this.emit("changed", modifiedItem, modifier);
+    if (item == null) {
+      if (options == null ? void 0 : options.upsert) {
+        const newItem = modify({}, {
+          ...restModifier,
+          $set: {
+            ...$setOnInsert,
+            ...restModifier.$set
+          }
+        });
+        if (newItem.id != null && this.getItemAndIndex({ id: newItem.id }).item != null) {
+          throw new Error("Item with same id already exists");
+        }
+        this.insert(newItem);
+      }
+    } else {
+      const modifiedItem = modify(deepClone(item), restModifier);
+      if (item.id !== modifiedItem.id && this.getItemAndIndex({ id: modifiedItem.id }).item != null) {
+        throw new Error("Item with same id already exists");
+      }
+      this.memory().splice(index, 1, modifiedItem);
+      this.rebuildIndices();
+      this.emit("changed", modifiedItem, restModifier);
+    }
     this.emit("updateOne", selector, modifier);
     this.executeInDebugMode((callstack) => this.emit("_debug.updateOne", callstack, selector, modifier));
+    if (item == null && !(options == null ? void 0 : options.upsert))
+      return 0;
     return 1;
   }
   /**
    * Updates multiple items in the collection that match the given selector.
    * @param selector - The criteria to select the items to update.
    * @param modifier - The modifications to apply to the items.
+   * @param [options] - Optional settings for the update operation.
+   * @param [options.upsert] - If `true`, creates new items if no items match the selector.
    * @returns The number of items updated.
    * @throws {Error} If the collection is disposed or invalid arguments are provided.
    */
-  updateMany(selector, modifier) {
+  updateMany(selector, modifier, options) {
     if (this.isDisposed)
       throw new Error("Collection is disposed");
     if (!selector)
       throw new Error("Invalid selector");
     if (!modifier)
       throw new Error("Invalid modifier");
+    const { $setOnInsert, ...restModifier } = modifier;
     const items = this.getItems(selector);
-    const modifiedItems = [];
-    items.forEach((item) => {
+    if (items.length === 0 && (options == null ? void 0 : options.upsert)) {
+      const newItem = modify({}, {
+        ...restModifier,
+        $set: {
+          ...$setOnInsert,
+          ...restModifier.$set
+        }
+      });
+      if (newItem.id != null && this.getItemAndIndex({ id: newItem.id }).item != null) {
+        throw new Error("Item with same id already exists");
+      }
+      this.insert(newItem);
+    }
+    const changes = items.map((item) => {
       const { index } = this.getItemAndIndex({ id: item.id });
       if (index === -1)
-        throw new Error("Cannot resolve index for item");
-      const modifiedItem = modify(deepClone(item), modifier);
-      this.memory().splice(index, 1, modifiedItem);
-      modifiedItems.push(modifiedItem);
+        throw new Error(`Cannot resolve index for item with id '${item.id}'`);
+      const modifiedItem = modify(deepClone(item), restModifier);
+      if (item.id !== modifiedItem.id && this.getItemAndIndex({ id: modifiedItem.id }).item != null) {
+        throw new Error(`Item with same id '${modifiedItem.id}' already exists`);
+      }
+      return {
+        item: modifiedItem,
+        index
+      };
+    });
+    changes.forEach(({ item, index }) => {
+      this.memory().splice(index, 1, item);
     });
     this.rebuildIndices();
-    modifiedItems.forEach((modifiedItem) => {
-      this.emit("changed", modifiedItem, modifier);
+    changes.forEach(({ item }) => {
+      this.emit("changed", item, restModifier);
     });
     this.emit("updateMany", selector, modifier);
     this.executeInDebugMode((callstack) => this.emit("_debug.updateMany", callstack, selector, modifier));
-    return modifiedItems.length;
+    return changes.length === 0 && (options == null ? void 0 : options.upsert) ? 1 : changes.length;
+  }
+  /**
+   * Replaces a single item in the collection that matches the given selector.
+   * @param selector - The criteria to select the item to replace.
+   * @param replacement - The item to replace the selected item with.
+   * @param [options] - Optional settings for the replace operation.
+   * @param [options.upsert] - If `true`, creates a new item if no item matches the selector.
+   * @returns The number of items replaced (0 or 1).
+   * @throws {Error} If the collection is disposed or invalid arguments are provided.
+   */
+  replaceOne(selector, replacement, options) {
+    if (this.isDisposed)
+      throw new Error("Collection is disposed");
+    if (!selector)
+      throw new Error("Invalid selector");
+    const { item, index } = this.getItemAndIndex(selector);
+    if (item == null) {
+      if (options == null ? void 0 : options.upsert) {
+        if (replacement.id != null && this.getItemAndIndex({ id: replacement.id }).item != null) {
+          throw new Error("Item with same id already exists");
+        }
+        this.insert(replacement);
+      }
+    } else {
+      if (item.id !== replacement.id && this.getItemAndIndex({ id: replacement.id }).item != null) {
+        throw new Error("Item with same id already exists");
+      }
+      const modifiedItem = { id: item.id, ...replacement };
+      this.memory().splice(index, 1, modifiedItem);
+      this.rebuildIndices();
+      this.emit("changed", modifiedItem, replacement);
+    }
+    this.emit("replaceOne", selector, replacement);
+    this.executeInDebugMode((callstack) => this.emit("_debug.replaceOne", callstack, selector, replacement));
+    if (item == null && !(options == null ? void 0 : options.upsert))
+      return 0;
+    return 1;
   }
   /**
    * Removes a single item from the collection that matches the given selector.

package/dist/index22.mjs

@@ -1,5 +1,5 @@
 import get from "./index25.mjs";
-import set from "./index28.mjs";
+import set from "./index27.mjs";
 function project(item, fields) {
   const allFieldsDeactivated = Object.values(fields).every((value) => value === 0);
   if (allFieldsDeactivated) {

package/dist/index23.mjs

@@ -2,7 +2,7 @@ var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 import isEqual from "./index9.mjs";
-import uniqueBy from "./index29.mjs";
+import uniqueBy from "./index28.mjs";
 class Observer {
   /**
    * Creates a new instance of the `Observer` class.

package/dist/index26.mjs

@@ -1,4 +1,4 @@
-import isFieldExpression from "./index27.mjs";
+import isFieldExpression from "./index29.mjs";
 import serializeValue from "./index16.mjs";
 function getMatchingKeys(field, selector) {
   const result = { include: null, exclude: null };

package/dist/index27.mjs

@@ -1,43 +1,30 @@
-const expressionKeys = /* @__PURE__ */ new Set([
-  "$eq",
-  "$gt",
-  "$gte",
-  "$lt",
-  "$lte",
-  "$in",
-  "$nin",
-  "$ne",
-  "$exists",
-  "$not",
-  "$expr",
-  "$jsonSchema",
-  "$mod",
-  "$regex",
-  "$options",
-  "$text",
-  "$where",
-  "$all",
-  "$elemMatch",
-  "$size",
-  "$bitsAllClear",
-  "$bitsAllSet",
-  "$bitsAnyClear",
-  "$bitsAnySet"
-]);
-function isFieldExpression(expression) {
-  if (typeof expression !== "object" || expression == null) {
-    return false;
-  }
-  const keys = Object.keys(expression);
-  if (keys.length === 0) {
-    return false;
-  }
-  const hasInvalidKeys = keys.some((key) => !expressionKeys.has(key));
-  if (hasInvalidKeys)
-    return false;
-  const hasValidKeys = keys.every((key) => expressionKeys.has(key));
-  return hasValidKeys;
+function set(object, path, value, deleteIfUndefined = false) {
+  if (object == null)
+    return object;
+  const segments = path.split(/[.[\]]/g);
+  if (segments[0] === "")
+    segments.shift();
+  if (segments.at(-1) === "")
+    segments.pop();
+  const apply = (node) => {
+    if (segments.length > 1) {
+      const key = segments.shift();
+      const nextIsNumber = !Number.isNaN(Number.parseInt(segments[0], 10));
+      if (node[key] === void 0) {
+        node[key] = nextIsNumber ? [] : {};
+      }
+      apply(node[key]);
+    } else {
+      if (deleteIfUndefined && value === void 0) {
+        delete node[segments[0]];
+        return;
+      }
+      node[segments[0]] = value;
+    }
+  };
+  apply(object);
+  return object;
 }
 export {
-  isFieldExpression as default
+  set as default
 };

package/dist/index28.mjs

@@ -1,30 +1,10 @@
-function set(object, path, value, deleteIfUndefined = false) {
-  if (object == null)
-    return object;
-  const segments = path.split(/[.[\]]/g);
-  if (segments[0] === "")
-    segments.shift();
-  if (segments.at(-1) === "")
-    segments.pop();
-  const apply = (node) => {
-    if (segments.length > 1) {
-      const key = segments.shift();
-      const nextIsNumber = !Number.isNaN(Number.parseInt(segments[0], 10));
-      if (node[key] === void 0) {
-        node[key] = nextIsNumber ? [] : {};
-      }
-      apply(node[key]);
-    } else {
-      if (deleteIfUndefined && value === void 0) {
-        delete node[segments[0]];
-        return;
-      }
-      node[segments[0]] = value;
-    }
-  };
-  apply(object);
-  return object;
+function uniqueBy(array, fn) {
+  const set = /* @__PURE__ */ new Set();
+  return array.filter((element) => {
+    const value = typeof fn === "function" ? fn(element) : element[fn];
+    return !set.has(value) && set.add(value);
+  });
 }
 export {
-  set as default
+  uniqueBy as default
 };

package/dist/index29.mjs

@@ -1,10 +1,43 @@
-function uniqueBy(array, fn) {
-  const set = /* @__PURE__ */ new Set();
-  return array.filter((element) => {
-    const value = typeof fn === "function" ? fn(element) : element[fn];
-    return !set.has(value) && set.add(value);
-  });
+const expressionKeys = /* @__PURE__ */ new Set([
+  "$eq",
+  "$gt",
+  "$gte",
+  "$lt",
+  "$lte",
+  "$in",
+  "$nin",
+  "$ne",
+  "$exists",
+  "$not",
+  "$expr",
+  "$jsonSchema",
+  "$mod",
+  "$regex",
+  "$options",
+  "$text",
+  "$where",
+  "$all",
+  "$elemMatch",
+  "$size",
+  "$bitsAllClear",
+  "$bitsAllSet",
+  "$bitsAnyClear",
+  "$bitsAnySet"
+]);
+function isFieldExpression(expression) {
+  if (typeof expression !== "object" || expression == null) {
+    return false;
+  }
+  const keys = Object.keys(expression);
+  if (keys.length === 0) {
+    return false;
+  }
+  const hasInvalidKeys = keys.some((key) => !expressionKeys.has(key));
+  if (hasInvalidKeys)
+    return false;
+  const hasValidKeys = keys.every((key) => expressionKeys.has(key));
+  return hasValidKeys;
 }
 export {
-  uniqueBy as default
+  isFieldExpression as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaldb/core",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "SignalDB is a client-side database that provides a simple MongoDB-like interface to the data with first-class typescript support to achieve an optimistic UI. Data persistence can be achieved by using storage providers that store the data through a JSON interface to places such as localStorage.",
   "scripts": {
     "build": "rimraf dist && vite build"