flongo 1.4.0 → 1.5.0

package/dist/flongoCollection.d.ts

@@ -131,6 +131,26 @@ export declare class FlongoCollection<T> {
      * @param clientId - Optional client ID for audit trail
      */
     batchCreate(attributes: T[], clientId?: string): Promise<string[]>;
+    /**
+     * Inserts a document if no document with the same _id exists; otherwise does nothing.
+     * Race-safe "first writer wins" semantics — ideal for cache-through writes.
+     * @param attributes - Document data including _id
+     * @param clientId - Optional client ID for audit trail
+     * @returns Promise resolving to the document (newly created or existing)
+     */
+    createIfNotExists(attributes: T & {
+        _id: string;
+    }, clientId?: string): Promise<Entity & T>;
+    /**
+     * Inserts a document if no document with the same _id exists; otherwise overwrites it.
+     * Race-safe "last writer wins" semantics.
+     * @param attributes - Document data including _id
+     * @param clientId - Optional client ID for audit trail
+     * @returns Promise resolving to the document (newly created or updated)
+     */
+    createOrUpdate(attributes: T & {
+        _id: string;
+    }, clientId?: string): Promise<Entity & T>;
     /**
      * Updates multiple documents matching the query
      * @param attributes - Fields to update

package/dist/flongoCollection.js

@@ -256,6 +256,35 @@ class FlongoCollection {
         });
         return Object.values(result.insertedIds).map((id) => id.toString());
     }
+    /**
+     * Inserts a document if no document with the same _id exists; otherwise does nothing.
+     * Race-safe "first writer wins" semantics — ideal for cache-through writes.
+     * @param attributes - Document data including _id
+     * @param clientId - Optional client ID for audit trail
+     * @returns Promise resolving to the document (newly created or existing)
+     */
+    async createIfNotExists(attributes, clientId) {
+        const { _id, ...rest } = attributes;
+        const now = Date.now();
+        const result = await this.collection.findOneAndUpdate({ _id }, { $setOnInsert: { ...rest, createdBy: clientId, createdAt: now, updatedAt: now } }, { upsert: true, returnDocument: 'after' });
+        return this.toEntity(result);
+    }
+    /**
+     * Inserts a document if no document with the same _id exists; otherwise overwrites it.
+     * Race-safe "last writer wins" semantics.
+     * @param attributes - Document data including _id
+     * @param clientId - Optional client ID for audit trail
+     * @returns Promise resolving to the document (newly created or updated)
+     */
+    async createOrUpdate(attributes, clientId) {
+        const { _id, createdAt, createdBy, updatedAt, updatedBy, ...rest } = attributes;
+        const now = Date.now();
+        const result = await this.collection.findOneAndUpdate({ _id }, {
+            $set: { ...rest, updatedAt: now, updatedBy: clientId },
+            $setOnInsert: { createdAt: now, createdBy: clientId }
+        }, { upsert: true, returnDocument: 'after' });
+        return this.toEntity(result);
+    }
     // ===========================================
     // UPDATE OPERATIONS
     // ===========================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flongo",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Firestore-like fluent query API for MongoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",