s3db.js 13.3.1 → 13.4.0

package/README.md

@@ -137,6 +137,8 @@ console.log("🎉 Connected to S3 database!");
 
 ### 3. Create your first resource
 
+Schema validation powered by **[fastest-validator](https://github.com/icebob/fastest-validator)** ⚡
+
 ```javascript
 const users = await s3db.createResource({
   name: "users",
@@ -718,7 +720,7 @@ await users.insert({ email: 'john@example.com', password: 'secret123', age: 25 }
 
 ### Schema & Field Types
 
-Define your data structure with powerful validation:
+Define your data structure with powerful validation using **[fastest-validator](https://github.com/icebob/fastest-validator)** - a blazing-fast validation library with comprehensive type support:
 
 #### Basic Types
 
@@ -749,6 +751,9 @@ Define your data structure with powerful validation:
 
 #### Schema Examples
 
+> **📖 Validation powered by [fastest-validator](https://github.com/icebob/fastest-validator)**
+> All schemas use fastest-validator's syntax with full support for shorthand notation.
+
 ```javascript
 // Simple schema
 {
@@ -757,21 +762,40 @@ Define your data structure with powerful validation:
   age: 'number|integer|min:0|max:150'
 }
 
-// Nested objects
+// Nested objects - MAGIC AUTO-DETECT! ✨ (recommended)
+// Just write your object structure - s3db detects it automatically!
+{
+  name: 'string|required',
+  profile: {               // ← No $$type needed! Auto-detected as optional object
+    bio: 'string|max:500',
+    avatar: 'url|optional',
+    social: {              // ← Deeply nested also works!
+      twitter: 'string|optional',
+      github: 'string|optional'
+    }
+  }
+}
+
+// Need validation control? Use $$type (when you need required/optional)
+{
+  name: 'string|required',
+  profile: {
+    $$type: 'object|required',  // ← Add required validation
+    bio: 'string|max:500',
+    avatar: 'url|optional'
+  }
+}
+
+// Advanced: Full control (rare cases - strict mode, etc)
 {
   name: 'string|required',
   profile: {
     type: 'object',
+    optional: false,
+    strict: true,        // ← Enable strict validation
     props: {
       bio: 'string|max:500',
-      avatar: 'url|optional',
-      social: {
-        type: 'object',
-        props: {
-          twitter: 'string|optional',
-          github: 'string|optional'
-        }
-      }
+      avatar: 'url|optional'
     }
   }
 }

package/dist/s3db.cjs.js

@@ -26182,7 +26182,7 @@ class Database extends EventEmitter {
     })();
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => true ? "13.3.1" : "latest");
+      const [ok, err, version] = tryFn(() => true ? "13.4.0" : "latest");
       return ok ? version : "latest";
     })();
     this._resourcesMap = {};
@@ -31511,14 +31511,36 @@ 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;
+    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
+      });
+    }
     const eventHandler = async (eventData) => {
       const entities = await this._getEntitiesInState(machineId, stateName);
       for (const entity of entities) {
         try {
+          let resolvedEventName;
+          if (typeof baseEventName === "function") {
+            resolvedEventName = baseEventName(entity.context);
+          } else {
+            resolvedEventName = baseEventName;
+          }
+          if (eventSource && typeof baseEventName === "function") {
+            const eventIdMatch = eventData?.id || eventData?.entityId;
+            if (eventIdMatch && entity.entityId !== eventIdMatch) {
+              continue;
+            }
+          }
           if (trigger.condition) {
             const shouldTrigger = await trigger.condition(entity.context, entity.entityId, eventData);
             if (!shouldTrigger) continue;
@@ -31532,28 +31554,76 @@ class StateMachinePlugin extends Plugin {
               continue;
             }
           }
-          const result = await this._executeAction(
-            trigger.action,
-            { ...entity.context, eventData },
-            "TRIGGER",
-            machineId,
-            entity.entityId
-          );
-          await this._incrementTriggerCount(machineId, entity.entityId, triggerName);
-          if (trigger.sendEvent) {
-            await this.send(machineId, entity.entityId, trigger.sendEvent, {
-              ...entity.context,
-              triggerResult: result,
-              eventData
+          if (trigger.targetState) {
+            await this._transition(
+              machineId,
+              entity.entityId,
+              stateName,
+              trigger.targetState,
+              "TRIGGER",
+              { ...entity.context, eventData, triggerName }
+            );
+            const machine = this.machines.get(machineId);
+            const resourceConfig = machine.config;
+            if (resourceConfig.resource && resourceConfig.stateField) {
+              let resource;
+              if (typeof resourceConfig.resource === "string") {
+                resource = await this.database.getResource(resourceConfig.resource);
+              } else {
+                resource = resourceConfig.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}`);
+                }
+              }
+            }
+            const targetStateConfig = machine.config.states[trigger.targetState];
+            if (targetStateConfig?.entry) {
+              await this._executeAction(
+                targetStateConfig.entry,
+                { ...entity.context, eventData },
+                "TRIGGER",
+                machineId,
+                entity.entityId
+              );
+            }
+            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) {
+            const result = await this._executeAction(
+              trigger.action,
+              { ...entity.context, eventData },
+              "TRIGGER",
+              machineId,
+              entity.entityId
+            );
+            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) {
@@ -31562,16 +31632,25 @@ class StateMachinePlugin extends Plugin {
         }
       }
     };
-    if (eventName.startsWith("db:")) {
-      const dbEventName = eventName.substring(3);
-      this.database.on(dbEventName, eventHandler);
+    if (eventSource) {
+      const baseEvent = typeof baseEventName === "function" ? "updated" : baseEventName;
+      eventSource.on(baseEvent, eventHandler);
       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}'`);
       }
     } else {
-      this.on(eventName, eventHandler);
-      if (this.config.verbose) {
-        console.log(`[StateMachinePlugin] Listening to plugin event '${eventName}' for trigger '${triggerName}'`);
+      const staticEventName = typeof baseEventName === "function" ? "updated" : baseEventName;
+      if (staticEventName.startsWith("db:")) {
+        const dbEventName = staticEventName.substring(3);
+        this.database.on(dbEventName, eventHandler);
+        if (this.config.verbose) {
+          console.log(`[StateMachinePlugin] Listening to database event '${dbEventName}' for trigger '${triggerName}'`);
+        }
+      } else {
+        this.on(staticEventName, eventHandler);
+        if (this.config.verbose) {
+          console.log(`[StateMachinePlugin] Listening to plugin event '${staticEventName}' for trigger '${triggerName}'`);
+        }
       }
     }
   }