s3db.js 7.3.10 → 7.4.0

package/README.md

@@ -109,6 +109,7 @@
 - [🗂️ Advanced Partitioning](#️-advanced-partitioning)
 - [🎣 Advanced Hooks System](#-advanced-hooks-system)
 - [🧩 Resource Middlewares](#-resource-middlewares)
+- [🎧 Event Listeners Configuration](#-event-listeners-configuration)
 - [📖 API Reference](#-api-reference)
 
 ---
@@ -1398,6 +1399,169 @@ await users.insert({ name: 'john', email: 'john@example.com' });
 
 #### **Best Practices**
 - Hooks are lightweight and ideal for observing or reacting to events.
+
+---
+
+### 🎧 Event Listeners Configuration
+
+s3db.js resources extend Node.js EventEmitter, providing a powerful event system for real-time monitoring and notifications. You can configure event listeners in **two ways**: programmatically using `.on()` or declaratively in the resource configuration.
+
+#### **Programmatic Event Listeners**
+Traditional EventEmitter pattern using `.on()`, `.once()`, or `.off()`:
+
+```javascript
+const users = await s3db.createResource({
+  name: "users",
+  attributes: {
+    name: "string|required",
+    email: "string|required"
+  }
+});
+
+// Single event listener
+users.on('insert', (event) => {
+  console.log('User created:', event.name);
+});
+
+// Multiple listeners for the same event
+users.on('update', (event) => {
+  console.log('Update detected:', event.id);
+});
+
+users.on('update', (event) => {
+  if (event.$before.email !== event.$after.email) {
+    console.log('Email changed!');
+  }
+});
+```
+
+#### **Declarative Event Listeners**
+Configure event listeners directly in the resource configuration for cleaner, more maintainable code:
+
+```javascript
+const users = await s3db.createResource({
+  name: "users",
+  attributes: {
+    name: "string|required",
+    email: "string|required"
+  },
+  events: {
+    // Single event listener
+    insert: (event) => {
+      console.log('📝 User created:', {
+        id: event.id,
+        name: event.name,
+        timestamp: new Date().toISOString()
+      });
+    },
+
+    // Multiple event listeners (array)
+    update: [
+      (event) => {
+        console.log('⚠️ Update detected for user:', event.id);
+      },
+      (event) => {
+        const changes = [];
+        if (event.$before.name !== event.$after.name) {
+          changes.push(`name: ${event.$before.name} → ${event.$after.name}`);
+        }
+        if (event.$before.email !== event.$after.email) {
+          changes.push(`email: ${event.$before.email} → ${event.$after.email}`);
+        }
+        if (changes.length > 0) {
+          console.log('📝 Changes:', changes.join(', '));
+        }
+      }
+    ],
+
+    // Bulk operation listeners
+    deleteMany: (count) => {
+      console.log(`🗑️ Bulk delete: ${count} users deleted`);
+    },
+
+    // Performance and monitoring
+    list: (result) => {
+      console.log(`📋 Listed ${result.count} users, ${result.errors} errors`);
+    }
+  }
+});
+```
+
+#### **Available Events**
+
+| Event | Description | Data Passed |
+|-------|-------------|-------------|
+| `insert` | Single record inserted | Complete object with all fields |
+| `update` | Single record updated | Object with `$before` and `$after` states |
+| `delete` | Single record deleted | Object data before deletion |
+| `insertMany` | Bulk insert completed | Number of records inserted |
+| `deleteMany` | Bulk delete completed | Number of records deleted |
+| `list` | List operation completed | Result object with count and errors |
+| `count` | Count operation completed | Total count number |
+| `get` | Single record retrieved | Complete object data |
+| `getMany` | Multiple records retrieved | Count of records |
+
+#### **Event Data Structure**
+
+**Insert/Get Events:**
+```javascript
+{
+  id: 'user-123',
+  name: 'John Doe',
+  email: 'john@example.com',
+  createdAt: '2023-12-01T10:00:00.000Z',
+  // ... all other fields
+}
+```
+
+**Update Events:**
+```javascript
+{
+  id: 'user-123',
+  name: 'John Updated',
+  email: 'john.new@example.com',
+  $before: {
+    name: 'John Doe',
+    email: 'john@example.com',
+    // ... previous state
+  },
+  $after: {
+    name: 'John Updated',
+    email: 'john.new@example.com',
+    // ... current state
+  }
+}
+```
+
+#### **Combining Both Approaches**
+You can use both declarative and programmatic event listeners together:
+
+```javascript
+const users = await s3db.createResource({
+  name: "users",
+  attributes: { name: "string|required" },
+  events: {
+    insert: (event) => console.log('Config listener:', event.name)
+  }
+});
+
+// Add additional programmatic listeners
+users.on('insert', (event) => {
+  console.log('Programmatic listener:', event.name);
+});
+
+await users.insert({ name: 'John' });
+// Output:
+// Config listener: John
+// Programmatic listener: John
+```
+
+#### **Best Practices for Event Listeners**
+- **Declarative for core functionality**: Use the `events` config for essential listeners
+- **Programmatic for conditional/dynamic**: Use `.on()` for listeners that might change at runtime
+- **Error handling**: Listeners should handle their own errors to avoid breaking operations
+- **Performance**: Keep listeners lightweight; use async operations sparingly
+- **Debugging**: Event listeners are excellent for debugging and monitoring
 - Middlewares are powerful and ideal for controlling or transforming operations.
 - You can safely combine both for maximum flexibility.
 

package/dist/s3db.cjs.js

@@ -11074,6 +11074,7 @@ class Resource extends EventEmitter {
    * @param {Function} [config.idGenerator] - Custom ID generator function
    * @param {number} [config.idSize=22] - Size for auto-generated IDs
    * @param {boolean} [config.versioningEnabled=false] - Enable versioning for this resource
+   * @param {Object} [config.events={}] - Event listeners to automatically add
    * @example
    * const users = new Resource({
    *   name: 'users',
@@ -11095,6 +11096,14 @@ class Resource extends EventEmitter {
    *     beforeInsert: [async (data) => {
       *       return data;
    *     }]
+   *   },
+   *   events: {
+   *     insert: (ev) => console.log('Inserted:', ev.id),
+   *     update: [
+   *       (ev) => console.warn('Update detected'),
+   *       (ev) => console.log('Updated:', ev.id)
+   *     ],
+   *     delete: (ev) => console.log('Deleted:', ev.id)
    *   }
    * });
    * 
@@ -11147,7 +11156,8 @@ class Resource extends EventEmitter {
       hooks = {},
       idGenerator: customIdGenerator,
       idSize = 22,
-      versioningEnabled = false
+      versioningEnabled = false,
+      events = {}
     } = config;
     this.name = name;
     this.client = client;
@@ -11189,6 +11199,19 @@ class Resource extends EventEmitter {
         }
       }
     }
+    if (events && Object.keys(events).length > 0) {
+      for (const [eventName, listeners] of Object.entries(events)) {
+        if (Array.isArray(listeners)) {
+          for (const listener of listeners) {
+            if (typeof listener === "function") {
+              this.on(eventName, listener);
+            }
+          }
+        } else if (typeof listeners === "function") {
+          this.on(eventName, listeners);
+        }
+      }
+    }
     this._initMiddleware();
   }
   /**
@@ -13228,6 +13251,24 @@ function validateResourceConfig(config) {
       }
     }
   }
+  if (config.events !== void 0) {
+    if (typeof config.events !== "object" || Array.isArray(config.events)) {
+      errors.push("Resource 'events' must be an object");
+    } else {
+      for (const [eventName, listeners] of Object.entries(config.events)) {
+        if (Array.isArray(listeners)) {
+          for (let i = 0; i < listeners.length; i++) {
+            const listener = listeners[i];
+            if (typeof listener !== "function") {
+              errors.push(`Resource 'events.${eventName}[${i}]' must be a function`);
+            }
+          }
+        } else if (typeof listeners !== "function") {
+          errors.push(`Resource 'events.${eventName}' must be a function or array of functions`);
+        }
+      }
+    }
+  }
   return {
     isValid: errors.length === 0,
     errors
@@ -13611,7 +13652,8 @@ class Database extends EventEmitter {
       versioningEnabled: this.versioningEnabled,
       map: config.map,
       idGenerator: config.idGenerator,
-      idSize: config.idSize
+      idSize: config.idSize,
+      events: config.events || {}
     });
     resource.database = this;
     this.resources[name] = resource;