@signaldb/core 1.3.1 → 1.5.0

package/dist/Collection/index.d.ts

@@ -41,14 +41,17 @@ 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;
+    'validate': (item: T) => void;
     '_debug.getItems': (callstack: string, selector: Selector<T> | undefined, measuredTime: number) => void;
     '_debug.find': <O extends FindOptions<T>>(callstack: string, selector: Selector<T> | undefined, options: O | undefined, cursor: Cursor<T, U>) => void;
     '_debug.findOne': <O extends FindOptions<T>>(callstack: string, selector: Selector<T>, options: O | undefined, item: U | undefined) => void;
     '_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 +232,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.cjs2.js

@@ -530,6 +530,7 @@ const _Collection = class _Collection extends EventEmitter {
     if (!item)
       throw new Error("Invalid item");
     const newItem = { id: randomId(), ...item };
+    this.emit("validate", newItem);
     if (this.idIndex.has(serializeValue(newItem.id)))
       throw new Error("Item with same id already exists");
     this.memory().push(newItem);
@@ -567,61 +568,143 @@ 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.emit("validate", modifiedItem);
+      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`);
+      }
+      this.emit("validate", modifiedItem);
+      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.emit("validate", modifiedItem);
+      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.d.ts

@@ -3,7 +3,7 @@ export type { default as MemoryAdapter } from './types/MemoryAdapter';
 export type { default as PersistenceAdapter, Changeset, LoadResponse, } from './types/PersistenceAdapter';
 export type { default as Selector } from './types/Selector';
 export type { default as Modifier } from './types/Modifier';
-export type { BaseItem, ObserveCallbacks, CursorOptions, Transform, SortSpecifier, FieldSpecifier, FindOptions, } from './Collection';
+export type { BaseItem, ObserveCallbacks, CursorOptions, Transform, SortSpecifier, FieldSpecifier, FindOptions, CollectionOptions, } from './Collection';
 export { default as Collection, createIndex } from './Collection';
 export { default as AutoFetchCollection } from './AutoFetchCollection';
 export { default as combinePersistenceAdapters } from './persistence/combinePersistenceAdapters';

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/index2.mjs

@@ -529,6 +529,7 @@ const _Collection = class _Collection extends EventEmitter {
     if (!item)
       throw new Error("Invalid item");
     const newItem = { id: randomId(), ...item };
+    this.emit("validate", newItem);
     if (this.idIndex.has(serializeValue(newItem.id)))
       throw new Error("Item with same id already exists");
     this.memory().push(newItem);
@@ -566,61 +567,143 @@ 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.emit("validate", modifiedItem);
+      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`);
+      }
+      this.emit("validate", modifiedItem);
+      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.emit("validate", modifiedItem);
+      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/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@signaldb/core",
-  "version": "1.3.1",
+  "version": "1.5.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"
+    "build": "rimraf dist && vite build",
+    "test": "vitest"
   },
   "repository": {
     "type": "git",
@@ -54,5 +55,8 @@
   "dependencies": {
     "fast-sort": "^3.4.1",
     "mingo": "^6.5.1"
+  },
+  "devDependencies": {
+    "zod": "^3.24.2"
   }
 }