@flowerforce/flowerbase 1.8.2 → 1.8.3

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 1.8.3 (2026-04-02)
+
+
+### 🩹 Fixes
+
+- updateOne options ([5b16467](https://github.com/flowerforce/flowerbase/commit/5b16467))
+
 ## 1.8.2 (2026-03-31)
 
 

package/README.md

@@ -616,35 +616,80 @@ Once deployed, you'll receive a public URL (e.g. https://your-app-name.up.exampl
 
 >This URL should be used as the base URL in your frontend application, as explained in the next section.
 
-## 🌐 Frontend Setup – Realm SDK in React (Example)
+## 🌐 Frontend Setup – `@flowerforce/flowerbase-client` (Recommended)
 
-You can use the official `realm-web` SDK to integrate MongoDB Realm into a React application.
-This serves as a sample setup — similar logic can be applied using other official Realm SDKs **(e.g. React Native, Node, or Flutter)**.
-
-### 📦 Install Realm SDK
+For frontend and mobile projects, you can use the dedicated Flowerbase client:
 
 ```bash
-npm install realm-web
+npm install @flowerforce/flowerbase-client
 ```
 
-### ⚙️ Configure Realm in React
-
-Create a file to initialize and export the Realm App instance:
+### ⚙️ Configure client app
 
 ```ts
-// src/realm/realmApp.ts
+import { App, Credentials } from '@flowerforce/flowerbase-client'
 
-import * as Realm from "realm-web";
+const app = new App({
+  id: 'your-app-id',
+  baseUrl: 'https://your-deployed-backend-url.com',
+  timeout: 10000
+})
 
-// Replace with your actual Realm App ID and your deployed backend URL
-const app = new Realm.App({
-  id: "your-realm-app-id", // e.g., my-app-abcde
-  baseUrl: "https://your-deployed-backend-url.com" // e.g., https://your-app-name.up.example.app
-});
+await app.logIn(Credentials.emailPassword('user@example.com', 'secret'))
+```
+
+### 📦 Common client operations
+
+```ts
+const user = app.currentUser
+if (!user) throw new Error('User not logged in')
+
+const profile = await user.functions.getProfile()
 
-export default app;
+const todos = user.mongoClient('mongodb-atlas')
+  .db('my-db')
+  .collection('todos')
 
+await todos.insertOne({ title: 'Ship docs update', done: false })
+const openTodos = await todos.find({ done: false })
 ```
 
->🔗 The baseUrl should point to the backend URL you deployed earlier using Flowerbase.
-This tells the frontend SDK where to send authentication and data requests.
+`@flowerforce/flowerbase-client` supports:
+- local-userpass / anon-user / custom-function authentication
+- function calls (`user.functions.<name>(...)`)
+- MongoDB operations via `user.mongoClient('mongodb-atlas')`
+- change streams with `watch()` async iterator
+- BSON/EJSON interoperability (`ObjectId`, `Date`, etc.)
+
+## 💡 Use Cases by Feature
+
+### 🔐 Authentication
+- Registration and login flows for SaaS dashboards using `local-userpass`.
+- Guest sessions for trial users with `anon-user`, then account upgrade with full registration.
+- Delegated enterprise login with `custom-function` auth when credentials must be validated by external identity logic.
+
+### 🔒 Rules
+- Multi-tenant isolation where each user can only read/write documents of their own workspace.
+- Field-level protection to hide private fields (for example billing or internal notes) from non-admin users.
+
+### ⚙️ Functions
+- Centralized business logic (pricing, counters, workflows) called from web and mobile clients.
+- Privileged server-side tasks invoked with `run_as_system` to perform safe internal operations.
+
+### 🔔 Triggers
+- Audit logging on insert/update/delete events into an activity collection.
+- Scheduled jobs (for example nightly cleanup, reminder generation, data aggregation).
+- Auth lifecycle reactions (welcome email on user creation, cleanup on user deletion).
+
+### 🌐 HTTP Endpoints
+- Public webhook ingestion from third-party systems.
+- Protected custom APIs for backoffice actions not exposed as direct database operations.
+
+### 📡 `flowerbase-client`
+- Real-time UI updates in task boards using `collection.watch()` change streams.
+- Frontend data access with Realm-style API surface to minimize integration complexity.
+- Shared client usage across web and React Native projects with consistent auth/session behavior.
+
+### 🖥 Monitoring UI
+- Live inspection of function invocations, endpoint calls, and trigger executions in staging/production.
+- Fast troubleshooting with event stream filters and user/session search tools.

package/dist/features/functions/utils.d.ts

@@ -18,7 +18,7 @@ export declare const executeQuery: ({ currentMethod, query, update, filter, proj
     countDocuments: () => Promise<number>;
     deleteOne: () => Promise<import("mongodb").DeleteResult>;
     insertOne: () => Promise<import("mongodb").InsertOneResult<Document>>;
-    updateOne: () => Promise<unknown> | import("mongodb").FindCursor<any> | import("mongodb").ChangeStream<Document, Document> | import("mongodb").AggregationCursor<Document>;
+    updateOne: () => Promise<import("mongodb").UpdateResult<Document>>;
     findOneAndUpdate: () => Promise<Document | null>;
     aggregate: () => Promise<Document[]>;
     insertMany: () => Promise<import("mongodb").InsertManyResult<Document>>;

package/dist/features/functions/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/features/functions/utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAGlC,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE3D;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAU,gBAAuB,KAAG,OAAO,CAAC,SAAS,CAwB9E,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAU,2HAYhC,kBAAkB;;;;;;;;;;;;;EAiGpB,CAAA"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/features/functions/utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAGlC,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE3D;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAU,gBAAuB,KAAG,OAAO,CAAC,SAAS,CAwB9E,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAU,2HAYhC,kBAAkB;;;;;;;;;;;;;EAsGpB,CAAA"}

package/dist/features/functions/utils.js

@@ -100,7 +100,7 @@ const executeQuery = (_a) => __awaiter(void 0, [_a], void 0, function* ({ curren
         countDocuments: () => currentMethod(bson_1.EJSON.deserialize(resolvedQuery), parsedOptions),
         deleteOne: () => currentMethod(bson_1.EJSON.deserialize(resolvedQuery), parsedOptions),
         insertOne: () => currentMethod(bson_1.EJSON.deserialize(document)),
-        updateOne: () => currentMethod(bson_1.EJSON.deserialize(resolvedQuery), bson_1.EJSON.deserialize(resolvedUpdate)),
+        updateOne: () => currentMethod(bson_1.EJSON.deserialize(resolvedQuery), bson_1.EJSON.deserialize(resolvedUpdate), parsedOptions),
         findOneAndUpdate: () => currentMethod(bson_1.EJSON.deserialize(resolvedQuery), bson_1.EJSON.deserialize(resolvedUpdate), parsedOptions),
         aggregate: () => __awaiter(void 0, void 0, void 0, function* () {
             return (yield currentMethod(bson_1.EJSON.deserialize(pipeline), {}, // TODO -> ADD OPTIONS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowerforce/flowerbase",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/features/functions/__tests__/utils.test.ts

@@ -0,0 +1,33 @@
+import { executeQuery } from '../utils'
+
+describe('executeQuery', () => {
+  it('passes parsed options to updateOne', async () => {
+    const currentMethod = jest.fn().mockResolvedValue({
+      acknowledged: true,
+      matchedCount: 0,
+      modifiedCount: 0,
+      upsertedCount: 1
+    })
+
+    const operators = await executeQuery({
+      currentMethod,
+      query: { ownerUserId: 'user-1' },
+      update: {
+        $set: { locale: 'it-IT' },
+        $setOnInsert: { scope: 'workspace' }
+      },
+      options: { upsert: true }
+    } as any)
+
+    await operators.updateOne()
+
+    expect(currentMethod).toHaveBeenCalledWith(
+      { ownerUserId: 'user-1' },
+      {
+        $set: { locale: 'it-IT' },
+        $setOnInsert: { scope: 'workspace' }
+      },
+      { upsert: true }
+    )
+  })
+})

package/src/features/functions/utils.ts

@@ -122,7 +122,12 @@ export const executeQuery = async ({
       (currentMethod as ReturnType<GetOperatorsFunction>['insertOne'])(
         EJSON.deserialize(document)
       ),
-    updateOne: () => currentMethod(EJSON.deserialize(resolvedQuery), EJSON.deserialize(resolvedUpdate)),
+    updateOne: () =>
+      (currentMethod as ReturnType<GetOperatorsFunction>['updateOne'])(
+        EJSON.deserialize(resolvedQuery),
+        EJSON.deserialize(resolvedUpdate),
+        parsedOptions
+      ),
     findOneAndUpdate: () =>
       (currentMethod as ReturnType<GetOperatorsFunction>['findOneAndUpdate'])(
         EJSON.deserialize(resolvedQuery),