flongo 1.4.0 → 1.6.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/dist/flongoQuery.d.ts

@@ -214,6 +214,15 @@ export declare class FlongoQuery implements ICollectionQuery {
      * @returns This query instance for chaining
      */
     geoWithin(bounds?: Bounds): FlongoQuery;
+    /**
+     * Performs a proximity query using MongoDB's $near operator
+     * Requires a 2dsphere index on the target field
+     * Results are automatically sorted by distance (nearest first)
+     * @param center - Center point coordinates
+     * @param maxDistanceMeters - Maximum distance in meters
+     * @returns This query instance for chaining
+     */
+    near(center: Coordinates, maxDistanceMeters: number): FlongoQuery;
     /**
      * Sets the field and direction for sorting results
      * @param field - Field name to sort by

package/dist/flongoQuery.js

@@ -330,6 +330,24 @@ class FlongoQuery {
         }
         return this;
     }
+    /**
+     * Performs a proximity query using MongoDB's $near operator
+     * Requires a 2dsphere index on the target field
+     * Results are automatically sorted by distance (nearest first)
+     * @param center - Center point coordinates
+     * @param maxDistanceMeters - Maximum distance in meters
+     * @returns This query instance for chaining
+     */
+    near(center, maxDistanceMeters) {
+        this.set("$near", {
+            $geometry: {
+                type: "Point",
+                coordinates: [center.longitude, center.latitude]
+            },
+            $maxDistance: maxDistanceMeters
+        });
+        return this;
+    }
     // ===========================================
     // SORTING
     // ===========================================

package/package.json

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