s3db.js 13.2.1 → 13.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3db.js",
-  "version": "13.2.1",
+  "version": "13.2.2",
   "description": "Use AWS S3, the world's most reliable document storage, as a database with this ORM.",
   "main": "dist/s3db.cjs.js",
   "module": "dist/s3db.es.js",

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

@@ -191,6 +191,9 @@ export class StateMachinePlugin extends Plugin {
       });
     }
 
+    // Attach state machines to resources for direct API access
+    await this._attachStateMachinesToResources();
+
     // Setup trigger system if enabled
     await this._setupTriggers();
 
@@ -1249,6 +1252,71 @@ export class StateMachinePlugin extends Plugin {
     }
   }
 
+  /**
+   * Attach state machine instances to their associated resources
+   * This enables the resource API: resource.state(id, event)
+   * @private
+   */
+  async _attachStateMachinesToResources() {
+    for (const [machineName, machineConfig] of Object.entries(this.config.stateMachines)) {
+      const resourceConfig = machineConfig.config || machineConfig;
+
+      // Skip if no resource is specified
+      if (!resourceConfig.resource) {
+        if (this.config.verbose) {
+          console.log(`[StateMachinePlugin] Machine '${machineName}' has no resource configured, skipping attachment`);
+        }
+        continue;
+      }
+
+      // Get the resource instance
+      let resource;
+      if (typeof resourceConfig.resource === 'string') {
+        // Resource specified as name
+        resource = this.database.resources[resourceConfig.resource];
+        if (!resource) {
+          console.warn(
+            `[StateMachinePlugin] Resource '${resourceConfig.resource}' not found for machine '${machineName}'. ` +
+            `Resource API will not be available.`
+          );
+          continue;
+        }
+      } else {
+        // Resource specified as instance
+        resource = resourceConfig.resource;
+      }
+
+      // Create a machine proxy that delegates to this plugin
+      const machineProxy = {
+        send: async (id, event, eventData) => {
+          return this.send(machineName, id, event, eventData);
+        },
+        getState: async (id) => {
+          return this.getState(machineName, id);
+        },
+        canTransition: async (id, event) => {
+          return this.canTransition(machineName, id, event);
+        },
+        getValidEvents: async (id) => {
+          return this.getValidEvents(machineName, id);
+        },
+        initializeEntity: async (id, context) => {
+          return this.initializeEntity(machineName, id, context);
+        },
+        getTransitionHistory: async (id, options) => {
+          return this.getTransitionHistory(machineName, id, options);
+        }
+      };
+
+      // Attach the proxy to the resource
+      resource._attachStateMachine(machineProxy);
+
+      if (this.config.verbose) {
+        console.log(`[StateMachinePlugin] Attached machine '${machineName}' to resource '${resource.name}'`);
+      }
+    }
+  }
+
   async start() {
     if (this.config.verbose) {
       console.log(`[StateMachinePlugin] Started with ${this.machines.size} state machines`);

package/src/resource.class.js

@@ -1322,7 +1322,7 @@ export class Resource extends AsyncEventEmitter {
     // Execute afterGet hooks
     data = await this.executeHooks('afterGet', data);
 
-    this._emitWithDeprecation("get", "fetched", data, data.id);
+    this._emitStandardized("get", "fetched", data, data.id);
     const value = data;
     return value;
   }
@@ -2202,7 +2202,7 @@ export class Resource extends AsyncEventEmitter {
     const [ok2, err2, response] = await tryFn(() => this.client.deleteObject(key));
 
     // Always emit delete event for audit purposes, even if delete fails
-    this._emitWithDeprecation("delete", "deleted", {
+    this._emitStandardized("delete", "deleted", {
       ...objectData,
       $before: { ...objectData },
       $after: null
@@ -2357,7 +2357,7 @@ export class Resource extends AsyncEventEmitter {
     // Execute afterCount hooks
     await this.executeHooks('afterCount', { count, partition, partitionValues });
 
-    this._emitWithDeprecation("count", "counted", count);
+    this._emitStandardized("count", "counted", count);
     return count;
   }
 
@@ -2385,7 +2385,7 @@ export class Resource extends AsyncEventEmitter {
         return result;
       });
 
-    this._emitWithDeprecation("insertMany", "inserted-many", objects.length);
+    this._emitStandardized("insertMany", "inserted-many", objects.length);
     return results;
   }
 
@@ -2435,7 +2435,7 @@ export class Resource extends AsyncEventEmitter {
     // Execute afterDeleteMany hooks
     await this.executeHooks('afterDeleteMany', { ids, results });
 
-    this._emitWithDeprecation("deleteMany", "deleted-many", ids.length);
+    this._emitStandardized("deleteMany", "deleted-many", ids.length);
     return results;
   }
 
@@ -2449,7 +2449,7 @@ export class Resource extends AsyncEventEmitter {
     const prefix = `resource=${this.name}/data`;
     const deletedCount = await this.client.deleteAll({ prefix });
 
-    this._emitWithDeprecation("deleteAll", "deleted-all", {
+    this._emitStandardized("deleteAll", "deleted-all", {
       version: this.version,
       prefix,
       deletedCount
@@ -2472,7 +2472,7 @@ export class Resource extends AsyncEventEmitter {
     const prefix = `resource=${this.name}`;
     const deletedCount = await this.client.deleteAll({ prefix });
 
-    this._emitWithDeprecation("deleteAllData", "deleted-all-data", {
+    this._emitStandardized("deleteAllData", "deleted-all-data", {
       resource: this.name,
       prefix,
       deletedCount
@@ -2550,7 +2550,7 @@ export class Resource extends AsyncEventEmitter {
       const idPart = parts.find(part => part.startsWith('id='));
       return idPart ? idPart.replace('id=', '') : null;
     }).filter(Boolean);
-    this._emitWithDeprecation("listIds", "listed-ids", ids.length);
+    this._emitStandardized("listIds", "listed-ids", ids.length);
     return ids;
   }
 
@@ -2598,13 +2598,13 @@ export class Resource extends AsyncEventEmitter {
     const [ok, err, ids] = await tryFn(() => this.listIds({ limit, offset }));
     if (!ok) throw err;
     const results = await this.processListResults(ids, 'main');
-    this._emitWithDeprecation("list", "listed", { count: results.length, errors: 0 });
+    this._emitStandardized("list", "listed", { count: results.length, errors: 0 });
     return results;
   }
 
   async listPartition({ partition, partitionValues, limit, offset = 0 }) {
     if (!this.config.partitions?.[partition]) {
-      this._emitWithDeprecation("list", "listed", { partition, partitionValues, count: 0, errors: 0 });
+      this._emitStandardized("list", "listed", { partition, partitionValues, count: 0, errors: 0 });
       return [];
     }
     const partitionDef = this.config.partitions[partition];
@@ -2614,7 +2614,7 @@ export class Resource extends AsyncEventEmitter {
     const ids = this.extractIdsFromKeys(keys).slice(offset);
     const filteredIds = limit ? ids.slice(0, limit) : ids;
     const results = await this.processPartitionResults(filteredIds, partition, partitionDef, keys);
-    this._emitWithDeprecation("list", "listed", { partition, partitionValues, count: results.length, errors: 0 });
+    this._emitStandardized("list", "listed", { partition, partitionValues, count: results.length, errors: 0 });
     return results;
   }
 
@@ -2670,7 +2670,7 @@ export class Resource extends AsyncEventEmitter {
         }
         return this.handleResourceError(err, id, context);
       });
-    this._emitWithDeprecation("list", "listed", { count: results.length, errors: 0 });
+    this._emitStandardized("list", "listed", { count: results.length, errors: 0 });
     return results;
   }
 
@@ -2743,11 +2743,11 @@ export class Resource extends AsyncEventEmitter {
    */
   handleListError(error, { partition, partitionValues }) {
     if (error.message.includes("Partition '") && error.message.includes("' not found")) {
-      this._emitWithDeprecation("list", "listed", { partition, partitionValues, count: 0, errors: 1 });
+      this._emitStandardized("list", "listed", { partition, partitionValues, count: 0, errors: 1 });
       return [];
     }
 
-    this._emitWithDeprecation("list", "listed", { partition, partitionValues, count: 0, errors: 1 });
+    this._emitStandardized("list", "listed", { partition, partitionValues, count: 0, errors: 1 });
     return [];
   }
 
@@ -2789,7 +2789,7 @@ export class Resource extends AsyncEventEmitter {
     // Execute afterGetMany hooks
     const finalResults = await this.executeHooks('afterGetMany', results);
 
-    this._emitWithDeprecation("getMany", "fetched-many", ids.length);
+    this._emitStandardized("getMany", "fetched-many", ids.length);
     return finalResults;
   }
 
@@ -2880,7 +2880,7 @@ export class Resource extends AsyncEventEmitter {
           hasTotalItems: totalItems !== null
         }
       };
-      this._emitWithDeprecation("page", "paginated", result);
+      this._emitStandardized("page", "paginated", result);
       return result;
     });
     if (ok) return result;
@@ -2954,7 +2954,7 @@ export class Resource extends AsyncEventEmitter {
       contentType
     }));
     if (!ok2) throw err2;
-    this._emitWithDeprecation("setContent", "content-set", { id, contentType, contentLength: buffer.length }, id);
+    this._emitStandardized("setContent", "content-set", { id, contentType, contentLength: buffer.length }, id);
     return updatedData;
   }
 
@@ -2984,7 +2984,7 @@ export class Resource extends AsyncEventEmitter {
     }
     const buffer = Buffer.from(await response.Body.transformToByteArray());
     const contentType = response.ContentType || null;
-    this._emitWithDeprecation("content", "content-fetched", { id, contentLength: buffer.length, contentType }, id);
+    this._emitStandardized("content", "content-fetched", { id, contentLength: buffer.length, contentType }, id);
     return {
       buffer,
       contentType
@@ -3018,7 +3018,7 @@ export class Resource extends AsyncEventEmitter {
       metadata: existingMetadata,
     }));
     if (!ok2) throw err2;
-    this._emitWithDeprecation("deleteContent", "content-deleted", id, id);
+    this._emitStandardized("deleteContent", "content-deleted", id, id);
     return response;
   }
 
@@ -3428,7 +3428,7 @@ export class Resource extends AsyncEventEmitter {
     data._partition = partitionName;
     data._partitionValues = partitionValues;
 
-    this._emitWithDeprecation("getFromPartition", "partition-fetched", data, data.id);
+    this._emitStandardized("getFromPartition", "partition-fetched", data, data.id);
     return data;
   }
 
@@ -3714,6 +3714,137 @@ export class Resource extends AsyncEventEmitter {
     return out;
   }
 
+  // ============================================================================
+  // STATE MACHINE METHODS
+  // ============================================================================
+
+  /**
+   * Send an event to trigger a state transition
+   * @param {string} id - Entity ID
+   * @param {string} event - Event name
+   * @param {Object} [eventData] - Event data
+   * @returns {Promise<Object>} Transition result
+   * @throws {Error} If no state machine is configured for this resource
+   * @example
+   * await orders.state('order-123', 'CONFIRM', { confirmedBy: 'user-456' });
+   */
+  async state(id, event, eventData) {
+    if (!this._stateMachine) {
+      throw new Error(
+        `No state machine configured for resource '${this.name}'. ` +
+        `Ensure StateMachinePlugin is installed and configured for this resource.`
+      );
+    }
+    return this._stateMachine.send(id, event, eventData);
+  }
+
+  /**
+   * Get current state of an entity
+   * @param {string} id - Entity ID
+   * @returns {Promise<string>} Current state
+   * @throws {Error} If no state machine is configured for this resource
+   * @example
+   * const currentState = await orders.getState('order-123');
+   */
+  async getState(id) {
+    if (!this._stateMachine) {
+      throw new Error(
+        `No state machine configured for resource '${this.name}'. ` +
+        `Ensure StateMachinePlugin is installed and configured for this resource.`
+      );
+    }
+    return this._stateMachine.getState(id);
+  }
+
+  /**
+   * Check if a transition is valid
+   * @param {string} id - Entity ID
+   * @param {string} event - Event name
+   * @returns {Promise<boolean>} True if transition is valid
+   * @throws {Error} If no state machine is configured for this resource
+   * @example
+   * const canConfirm = await orders.canTransition('order-123', 'CONFIRM');
+   */
+  async canTransition(id, event) {
+    if (!this._stateMachine) {
+      throw new Error(
+        `No state machine configured for resource '${this.name}'. ` +
+        `Ensure StateMachinePlugin is installed and configured for this resource.`
+      );
+    }
+    return this._stateMachine.canTransition(id, event);
+  }
+
+  /**
+   * Get all valid events for the current state
+   * @param {string} id - Entity ID
+   * @returns {Promise<Array<string>>} Array of valid event names
+   * @throws {Error} If no state machine is configured for this resource
+   * @example
+   * const events = await orders.getValidEvents('order-123');
+   * // Returns: ['SHIP', 'CANCEL']
+   */
+  async getValidEvents(id) {
+    if (!this._stateMachine) {
+      throw new Error(
+        `No state machine configured for resource '${this.name}'. ` +
+        `Ensure StateMachinePlugin is installed and configured for this resource.`
+      );
+    }
+    return this._stateMachine.getValidEvents(id);
+  }
+
+  /**
+   * Initialize entity with initial state
+   * @param {string} id - Entity ID
+   * @param {Object} [context] - Initial context data
+   * @returns {Promise<void>}
+   * @throws {Error} If no state machine is configured for this resource
+   * @example
+   * await orders.initializeState('order-456', { customerId: 'user-123' });
+   */
+  async initializeState(id, context) {
+    if (!this._stateMachine) {
+      throw new Error(
+        `No state machine configured for resource '${this.name}'. ` +
+        `Ensure StateMachinePlugin is installed and configured for this resource.`
+      );
+    }
+    return this._stateMachine.initializeEntity(id, context);
+  }
+
+  /**
+   * Get transition history for an entity
+   * @param {string} id - Entity ID
+   * @param {Object} [options] - Query options
+   * @param {number} [options.limit=100] - Maximum number of transitions
+   * @param {Date} [options.fromDate] - Filter from date
+   * @param {Date} [options.toDate] - Filter to date
+   * @returns {Promise<Array<Object>>} Transition history
+   * @throws {Error} If no state machine is configured for this resource
+   * @example
+   * const history = await orders.getStateHistory('order-123', { limit: 50 });
+   */
+  async getStateHistory(id, options) {
+    if (!this._stateMachine) {
+      throw new Error(
+        `No state machine configured for resource '${this.name}'. ` +
+        `Ensure StateMachinePlugin is installed and configured for this resource.`
+      );
+    }
+    return this._stateMachine.getTransitionHistory(id, options);
+  }
+
+  /**
+   * Internal method to attach state machine instance
+   * This is called by StateMachinePlugin during initialization
+   * @private
+   * @param {Object} stateMachine - State machine instance
+   */
+  _attachStateMachine(stateMachine) {
+    this._stateMachine = stateMachine;
+  }
+
 }
 
 /**