s3db.js 13.3.1 → 13.5.1

package/src/plugins/state-machine.plugin.js

@@ -133,10 +133,46 @@ export class StateMachinePlugin extends Plugin {
     this.machines = new Map();
     this.triggerIntervals = [];
     this.schedulerPlugin = null;
+    this._pendingEventHandlers = new Set();
 
     this._validateConfiguration();
   }
 
+  /**
+   * Wait for all pending event handlers to complete
+   * Useful when working with async events (asyncEvents: true)
+   * @param {number} timeout - Maximum time to wait in milliseconds (default: 5000)
+   * @returns {Promise<void>}
+   */
+  async waitForPendingEvents(timeout = 5000) {
+    if (this._pendingEventHandlers.size === 0) {
+      return; // No pending events
+    }
+
+    const startTime = Date.now();
+
+    while (this._pendingEventHandlers.size > 0) {
+      if (Date.now() - startTime > timeout) {
+        throw new StateMachineError(
+          `Timeout waiting for ${this._pendingEventHandlers.size} pending event handlers`,
+          {
+            operation: 'waitForPendingEvents',
+            pendingCount: this._pendingEventHandlers.size,
+            timeout
+          }
+        );
+      }
+
+      // Wait for at least one handler to complete
+      if (this._pendingEventHandlers.size > 0) {
+        await Promise.race(Array.from(this._pendingEventHandlers));
+      }
+
+      // Small delay before checking again
+      await new Promise(resolve => setImmediate(resolve));
+    }
+  }
+
   _validateConfiguration() {
     if (!this.config.stateMachines || Object.keys(this.config.stateMachines).length === 0) {
       throw new StateMachineError('At least one state machine must be defined', {
@@ -1170,10 +1206,22 @@ export class StateMachinePlugin extends Plugin {
 
   /**
    * Setup an event-based trigger
+   * Supports both old API (trigger.event) and new API (trigger.eventName + eventSource)
    * @private
    */
   async _setupEventTrigger(machineId, stateName, trigger, triggerName) {
-    const eventName = trigger.event;
+    // Support both old API (event) and new API (eventName)
+    const baseEventName = trigger.eventName || trigger.event;
+    const eventSource = trigger.eventSource;
+
+    if (!baseEventName) {
+      throw new StateMachineError(`Event trigger '${triggerName}' must have either 'event' or 'eventName' property`, {
+        operation: '_setupEventTrigger',
+        machineId,
+        stateName,
+        triggerName
+      });
+    }
 
     // Create event listener
     const eventHandler = async (eventData) => {
@@ -1181,6 +1229,26 @@ export class StateMachinePlugin extends Plugin {
 
       for (const entity of entities) {
         try {
+          // Resolve dynamic event name if it's a function
+          let resolvedEventName;
+          if (typeof baseEventName === 'function') {
+            resolvedEventName = baseEventName(entity.context);
+          } else {
+            resolvedEventName = baseEventName;
+          }
+
+          // Skip if event name doesn't match (for dynamic event names)
+          // This allows filtering events by entity context
+          if (eventSource && typeof baseEventName === 'function') {
+            // For resource-specific events with dynamic names, we need to check
+            // if this specific event matches this entity
+            // The eventData will contain the ID that was part of the event name
+            const eventIdMatch = eventData?.id || eventData?.entityId;
+            if (eventIdMatch && entity.entityId !== eventIdMatch) {
+              continue; // Not for this entity
+            }
+          }
+
           // Check condition if provided
           if (trigger.condition) {
             const shouldTrigger = await trigger.condition(entity.context, entity.entityId, eventData);
@@ -1198,33 +1266,92 @@ export class StateMachinePlugin extends Plugin {
             }
           }
 
-          // Execute trigger action with event data in context
-          const result = await this._executeAction(
-            trigger.action,
-            { ...entity.context, eventData },
-            'TRIGGER',
-            machineId,
-            entity.entityId
-          );
+          // NEW: Support targetState for automatic transitions
+          if (trigger.targetState) {
+            // Automatic transition to target state
+            await this._transition(
+              machineId,
+              entity.entityId,
+              stateName,
+              trigger.targetState,
+              'TRIGGER',
+              { ...entity.context, eventData, triggerName }
+            );
 
-          await this._incrementTriggerCount(machineId, entity.entityId, triggerName);
+            // Update resource's stateField if configured
+            const machine = this.machines.get(machineId);
+            const resourceConfig = machine.config;
+            if (resourceConfig.resource && resourceConfig.stateField) {
+              // Get the resource instance
+              let resource;
+              if (typeof resourceConfig.resource === 'string') {
+                resource = await this.database.getResource(resourceConfig.resource);
+              } else {
+                resource = resourceConfig.resource;
+              }
 
-          // Send success event if configured
-          if (trigger.sendEvent) {
-            await this.send(machineId, entity.entityId, trigger.sendEvent, {
-              ...entity.context,
-              triggerResult: result,
-              eventData
+              // Update the state field in the resource
+              if (resource) {
+                const [ok] = await tryFn(() =>
+                  resource.patch(entity.entityId, { [resourceConfig.stateField]: trigger.targetState })
+                );
+                if (!ok && this.config.verbose) {
+                  console.warn(`[StateMachinePlugin] Failed to update resource stateField for entity ${entity.entityId}`);
+                }
+              }
+            }
+
+            // Execute entry action of target state if exists
+            const targetStateConfig = machine.config.states[trigger.targetState];
+            if (targetStateConfig?.entry) {
+              await this._executeAction(
+                targetStateConfig.entry,
+                { ...entity.context, eventData },
+                'TRIGGER',
+                machineId,
+                entity.entityId
+              );
+            }
+
+            // Emit transition event
+            this.emit('plg:state-machine:transition', {
+              machineId,
+              entityId: entity.entityId,
+              from: stateName,
+              to: trigger.targetState,
+              event: 'TRIGGER',
+              context: { ...entity.context, eventData, triggerName }
             });
+          } else if (trigger.action) {
+            // Execute trigger action with event data in context
+            const result = await this._executeAction(
+              trigger.action,
+              { ...entity.context, eventData },
+              'TRIGGER',
+              machineId,
+              entity.entityId
+            );
+
+            // Send success event if configured
+            if (trigger.sendEvent) {
+              await this.send(machineId, entity.entityId, trigger.sendEvent, {
+                ...entity.context,
+                triggerResult: result,
+                eventData
+              });
+            }
           }
 
+          await this._incrementTriggerCount(machineId, entity.entityId, triggerName);
+
           this.emit('plg:state-machine:trigger-executed', {
             machineId,
             entityId: entity.entityId,
             state: stateName,
             trigger: triggerName,
             type: 'event',
-            eventName
+            eventName: resolvedEventName,
+            targetState: trigger.targetState
           });
         } catch (error) {
           if (this.config.verbose) {
@@ -1234,20 +1361,54 @@ export class StateMachinePlugin extends Plugin {
       }
     };
 
-    // Listen to database events if eventName starts with 'db:'
-    if (eventName.startsWith('db:')) {
-      const dbEventName = eventName.substring(3); // Remove 'db:' prefix
-      this.database.on(dbEventName, eventHandler);
+    // NEW: Support eventSource for resource-specific events
+    if (eventSource) {
+      // Listen to events from a specific resource
+      // Resource events are typically: inserted, updated, deleted
+      const baseEvent = typeof baseEventName === 'function' ? 'updated' : baseEventName;
+
+      // IMPORTANT: For resources with async events, we need to ensure the event handler
+      // completes before returning control. We wrap the handler to track pending operations.
+      const wrappedHandler = async (...args) => {
+        // Track this as a pending operation
+        const handlerPromise = eventHandler(...args);
+
+        // Store promise if state machine has event tracking
+        if (!this._pendingEventHandlers) {
+          this._pendingEventHandlers = new Set();
+        }
+        this._pendingEventHandlers.add(handlerPromise);
+
+        try {
+          await handlerPromise;
+        } finally {
+          this._pendingEventHandlers.delete(handlerPromise);
+        }
+      };
+
+      eventSource.on(baseEvent, wrappedHandler);
 
       if (this.config.verbose) {
-        console.log(`[StateMachinePlugin] Listening to database event '${dbEventName}' for trigger '${triggerName}'`);
+        console.log(`[StateMachinePlugin] Listening to resource event '${baseEvent}' from '${eventSource.name}' for trigger '${triggerName}' (async-safe)`);
       }
     } else {
-      // Listen to plugin events
-      this.on(eventName, eventHandler);
+      // Original behavior: listen to database or plugin events
+      const staticEventName = typeof baseEventName === 'function' ? 'updated' : baseEventName;
 
-      if (this.config.verbose) {
-        console.log(`[StateMachinePlugin] Listening to plugin event '${eventName}' for trigger '${triggerName}'`);
+      if (staticEventName.startsWith('db:')) {
+        const dbEventName = staticEventName.substring(3); // Remove 'db:' prefix
+        this.database.on(dbEventName, eventHandler);
+
+        if (this.config.verbose) {
+          console.log(`[StateMachinePlugin] Listening to database event '${dbEventName}' for trigger '${triggerName}'`);
+        }
+      } else {
+        // Listen to plugin events
+        this.on(staticEventName, eventHandler);
+
+        if (this.config.verbose) {
+          console.log(`[StateMachinePlugin] Listening to plugin event '${staticEventName}' for trigger '${triggerName}'`);
+        }
       }
     }
   }