s3db.js 13.1.0 → 13.2.2

package/src/plugins/ttl.plugin.js

@@ -200,7 +200,7 @@ export class TTLPlugin extends Plugin {
       console.log(`[TTLPlugin] Installed with ${Object.keys(this.resources).length} resources`);
     }
 
-    this.emit('installed', {
+    this.emit('db:plugin:installed', {
       plugin: 'TTLPlugin',
       resources: Object.keys(this.resources)
     });
@@ -512,7 +512,7 @@ export class TTLPlugin extends Plugin {
       this.stats.lastScanAt = new Date().toISOString();
       this.stats.lastScanDuration = Date.now() - startTime;
 
-      this.emit('scanCompleted', {
+      this.emit('plg:ttl:scan-completed', {
         granularity,
         duration: this.stats.lastScanDuration,
         cohorts
@@ -520,7 +520,7 @@ export class TTLPlugin extends Plugin {
     } catch (error) {
       console.error(`[TTLPlugin] Error in ${granularity} cleanup:`, error);
       this.stats.totalErrors++;
-      this.emit('cleanupError', { granularity, error });
+      this.emit('plg:ttl:cleanup-error', { granularity, error });
     }
   }
 
@@ -585,7 +585,7 @@ export class TTLPlugin extends Plugin {
       await this.expirationIndex.delete(entry.id);
 
       this.stats.totalExpired++;
-      this.emit('recordExpired', { resource: entry.resourceName, record });
+      this.emit('plg:ttl:record-expired', { resource: entry.resourceName, record });
     } catch (error) {
       console.error(`[TTLPlugin] Error processing expired entry:`, error);
       this.stats.totalErrors++;

package/src/plugins/vector.plugin.js

@@ -47,7 +47,7 @@ export class VectorPlugin extends Plugin {
   }
 
   async onInstall() {
-    this.emit('installed', { plugin: 'VectorPlugin' });
+    this.emit('db:plugin:installed', { plugin: 'VectorPlugin' });
 
     // Validate vector storage for all resources
     this.validateVectorStorage();
@@ -57,11 +57,11 @@ export class VectorPlugin extends Plugin {
   }
 
   async onStart() {
-    this.emit('started', { plugin: 'VectorPlugin' });
+    this.emit('db:plugin:started', { plugin: 'VectorPlugin' });
   }
 
   async onStop() {
-    this.emit('stopped', { plugin: 'VectorPlugin' });
+    this.emit('db:plugin:stopped', { plugin: 'VectorPlugin' });
   }
 
   async onUninstall(options) {
@@ -78,7 +78,7 @@ export class VectorPlugin extends Plugin {
       delete resource.distance;
     }
 
-    this.emit('uninstalled', { plugin: 'VectorPlugin' });
+    this.emit('db:plugin:uninstalled', { plugin: 'VectorPlugin' });
   }
 
   /**
@@ -114,12 +114,12 @@ export class VectorPlugin extends Plugin {
             recommendation: 'body-overflow'
           };
 
-          this.emit('vector:storage-warning', warning);
+          this.emit('plg:vector:storage-warning', warning);
 
           // Auto-fix if configured
           if (this.config.autoFixBehavior) {
             resource.behavior = 'body-overflow';
-            this.emit('vector:behavior-fixed', {
+            this.emit('plg:vector:behavior-fixed', {
               resource: resource.name,
               newBehavior: 'body-overflow'
             });
@@ -163,7 +163,7 @@ export class VectorPlugin extends Plugin {
 
       // Check if partition already exists
       if (resource.config.partitions && resource.config.partitions[partitionName]) {
-        this.emit('vector:partition-exists', {
+        this.emit('plg:vector:partition-exists', {
           resource: resource.name,
           vectorField: vectorField.name,
           partition: partitionName,
@@ -193,7 +193,7 @@ export class VectorPlugin extends Plugin {
       }
 
       // Emit event
-      this.emit('vector:partition-created', {
+      this.emit('plg:vector:partition-created', {
         resource: resource.name,
         vectorField: vectorField.name,
         partition: partitionName,
@@ -296,7 +296,7 @@ export class VectorPlugin extends Plugin {
       return updates;
     });
 
-    this.emit('vector:hooks-installed', {
+    this.emit('plg:vector:hooks-installed', {
       resource: resource.name,
       vectorField,
       trackingField,
@@ -429,7 +429,7 @@ export class VectorPlugin extends Plugin {
 
     // Emit event if field detected
     if (vectorField && this.config.emitEvents) {
-      this.emit('vector:field-detected', {
+      this.emit('plg:vector:field-detected', {
         resource: resource.name,
         vectorField,
         timestamp: Date.now()

package/src/resource.class.js

@@ -1021,6 +1021,24 @@ export class Resource extends AsyncEventEmitter {
     return Buffer.byteLength(String(body), 'utf8');
   }
 
+  /**
+   * Emit standardized events with optional ID-specific variant
+   *
+   * @private
+   * @param {string} event - Event name
+   * @param {Object} payload - Event payload
+   * @param {string} [id] - Optional ID for ID-specific events
+   */
+  _emitStandardized(event, payload, id = null) {
+    // Emit standardized event
+    this.emit(event, payload);
+
+    // Emit ID-specific event if ID provided
+    if (id) {
+      this.emit(`${event}:${id}`, payload);
+    }
+  }
+
   /**
    * Insert a new resource object
    * @param {Object} attributes - Resource attributes
@@ -1191,24 +1209,24 @@ export class Resource extends AsyncEventEmitter {
       }
 
       // Execute other afterInsert hooks synchronously (excluding partition hook)
-      const nonPartitionHooks = this.hooks.afterInsert.filter(hook => 
+      const nonPartitionHooks = this.hooks.afterInsert.filter(hook =>
         !hook.toString().includes('createPartitionReferences')
       );
       let finalResult = insertedObject;
       for (const hook of nonPartitionHooks) {
         finalResult = await hook(finalResult);
       }
-      
-      // Emit insert event
-      this.emit('insert', finalResult);
+
+      // Emit insert event with standardized naming
+      this._emitStandardized('inserted', finalResult, finalResult?.id || insertedObject?.id);
       return finalResult;
     } else {
       // Sync mode: execute all hooks including partition creation
       const finalResult = await this.executeHooks('afterInsert', insertedObject);
-      
-      // Emit insert event
-      this.emit('insert', finalResult);
-      
+
+      // Emit insert event with standardized naming
+      this._emitStandardized('inserted', finalResult, finalResult?.id || insertedObject?.id);
+
       // Return the final object
       return finalResult;
     }
@@ -1304,7 +1322,7 @@ export class Resource extends AsyncEventEmitter {
     // Execute afterGet hooks
     data = await this.executeHooks('afterGet', data);
 
-    this.emit("get", data);
+    this._emitStandardized("get", "fetched", data, data.id);
     const value = data;
     return value;
   }
@@ -1579,28 +1597,28 @@ export class Resource extends AsyncEventEmitter {
       }
 
       // Execute other afterUpdate hooks synchronously (excluding partition hook)
-      const nonPartitionHooks = this.hooks.afterUpdate.filter(hook => 
+      const nonPartitionHooks = this.hooks.afterUpdate.filter(hook =>
         !hook.toString().includes('handlePartitionReferenceUpdates')
       );
       let finalResult = updatedData;
       for (const hook of nonPartitionHooks) {
         finalResult = await hook(finalResult);
       }
-      
-      this.emit('update', {
+
+      this._emitStandardized('updated', {
         ...updatedData,
         $before: { ...originalData },
         $after: { ...finalResult }
-      });
+      }, updatedData.id);
       return finalResult;
     } else {
       // Sync mode: execute all hooks including partition updates
       const finalResult = await this.executeHooks('afterUpdate', updatedData);
-      this.emit('update', {
+      this._emitStandardized('updated', {
         ...updatedData,
         $before: { ...originalData },
         $after: { ...finalResult }
-      });
+      }, updatedData.id);
       return finalResult;
     }
   }
@@ -2125,11 +2143,11 @@ export class Resource extends AsyncEventEmitter {
         finalResult = await hook(finalResult);
       }
 
-      this.emit('update', {
+      this._emitStandardized('updated', {
         ...updatedData,
         $before: { ...originalData },
         $after: { ...finalResult }
-      });
+      }, updatedData.id);
 
       return {
         success: true,
@@ -2141,11 +2159,11 @@ export class Resource extends AsyncEventEmitter {
       await this.handlePartitionReferenceUpdates(oldData, newData);
       const finalResult = await this.executeHooks('afterUpdate', updatedData);
 
-      this.emit('update', {
+      this._emitStandardized('updated', {
         ...updatedData,
         $before: { ...originalData },
         $after: { ...finalResult }
-      });
+      }, updatedData.id);
 
       return {
         success: true,
@@ -2182,13 +2200,13 @@ export class Resource extends AsyncEventEmitter {
     await this.executeHooks('beforeDelete', objectData);
     const key = this.getResourceKey(id);
     const [ok2, err2, response] = await tryFn(() => this.client.deleteObject(key));
-    
+
     // Always emit delete event for audit purposes, even if delete fails
-    this.emit("delete", {
+    this._emitStandardized("delete", "deleted", {
       ...objectData,
       $before: { ...objectData },
       $after: null
-    });
+    }, id);
     
     // If we had an error getting the object, throw it now (after emitting the event)
     if (deleteError) {
@@ -2339,7 +2357,7 @@ export class Resource extends AsyncEventEmitter {
     // Execute afterCount hooks
     await this.executeHooks('afterCount', { count, partition, partitionValues });
 
-    this.emit("count", count);
+    this._emitStandardized("count", "counted", count);
     return count;
   }
 
@@ -2367,7 +2385,7 @@ export class Resource extends AsyncEventEmitter {
         return result;
       });
 
-    this.emit("insertMany", objects.length);
+    this._emitStandardized("insertMany", "inserted-many", objects.length);
     return results;
   }
 
@@ -2417,7 +2435,7 @@ export class Resource extends AsyncEventEmitter {
     // Execute afterDeleteMany hooks
     await this.executeHooks('afterDeleteMany', { ids, results });
 
-    this.emit("deleteMany", ids.length);
+    this._emitStandardized("deleteMany", "deleted-many", ids.length);
     return results;
   }
 
@@ -2431,7 +2449,7 @@ export class Resource extends AsyncEventEmitter {
     const prefix = `resource=${this.name}/data`;
     const deletedCount = await this.client.deleteAll({ prefix });
 
-    this.emit("deleteAll", {
+    this._emitStandardized("deleteAll", "deleted-all", {
       version: this.version,
       prefix,
       deletedCount
@@ -2454,7 +2472,7 @@ export class Resource extends AsyncEventEmitter {
     const prefix = `resource=${this.name}`;
     const deletedCount = await this.client.deleteAll({ prefix });
 
-    this.emit("deleteAllData", {
+    this._emitStandardized("deleteAllData", "deleted-all-data", {
       resource: this.name,
       prefix,
       deletedCount
@@ -2532,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.emit("listIds", ids.length);
+    this._emitStandardized("listIds", "listed-ids", ids.length);
     return ids;
   }
 
@@ -2580,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.emit("list", { 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.emit("list", { partition, partitionValues, count: 0, errors: 0 });
+      this._emitStandardized("list", "listed", { partition, partitionValues, count: 0, errors: 0 });
       return [];
     }
     const partitionDef = this.config.partitions[partition];
@@ -2596,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.emit("list", { partition, partitionValues, count: results.length, errors: 0 });
+    this._emitStandardized("list", "listed", { partition, partitionValues, count: results.length, errors: 0 });
     return results;
   }
 
@@ -2652,7 +2670,7 @@ export class Resource extends AsyncEventEmitter {
         }
         return this.handleResourceError(err, id, context);
       });
-    this.emit("list", { count: results.length, errors: 0 });
+    this._emitStandardized("list", "listed", { count: results.length, errors: 0 });
     return results;
   }
 
@@ -2725,11 +2743,11 @@ export class Resource extends AsyncEventEmitter {
    */
   handleListError(error, { partition, partitionValues }) {
     if (error.message.includes("Partition '") && error.message.includes("' not found")) {
-      this.emit("list", { partition, partitionValues, count: 0, errors: 1 });
+      this._emitStandardized("list", "listed", { partition, partitionValues, count: 0, errors: 1 });
       return [];
     }
 
-    this.emit("list", { partition, partitionValues, count: 0, errors: 1 });
+    this._emitStandardized("list", "listed", { partition, partitionValues, count: 0, errors: 1 });
     return [];
   }
 
@@ -2771,7 +2789,7 @@ export class Resource extends AsyncEventEmitter {
     // Execute afterGetMany hooks
     const finalResults = await this.executeHooks('afterGetMany', results);
 
-    this.emit("getMany", ids.length);
+    this._emitStandardized("getMany", "fetched-many", ids.length);
     return finalResults;
   }
 
@@ -2862,7 +2880,7 @@ export class Resource extends AsyncEventEmitter {
           hasTotalItems: totalItems !== null
         }
       };
-      this.emit("page", result);
+      this._emitStandardized("page", "paginated", result);
       return result;
     });
     if (ok) return result;
@@ -2936,7 +2954,7 @@ export class Resource extends AsyncEventEmitter {
       contentType
     }));
     if (!ok2) throw err2;
-    this.emit("setContent", { id, contentType, contentLength: buffer.length });
+    this._emitStandardized("setContent", "content-set", { id, contentType, contentLength: buffer.length }, id);
     return updatedData;
   }
 
@@ -2966,7 +2984,7 @@ export class Resource extends AsyncEventEmitter {
     }
     const buffer = Buffer.from(await response.Body.transformToByteArray());
     const contentType = response.ContentType || null;
-    this.emit("content", id, buffer.length, contentType);
+    this._emitStandardized("content", "content-fetched", { id, contentLength: buffer.length, contentType }, id);
     return {
       buffer,
       contentType
@@ -3000,7 +3018,7 @@ export class Resource extends AsyncEventEmitter {
       metadata: existingMetadata,
     }));
     if (!ok2) throw err2;
-    this.emit("deleteContent", id);
+    this._emitStandardized("deleteContent", "content-deleted", id, id);
     return response;
   }
 
@@ -3410,7 +3428,7 @@ export class Resource extends AsyncEventEmitter {
     data._partition = partitionName;
     data._partitionValues = partitionValues;
 
-    this.emit("getFromPartition", data);
+    this._emitStandardized("getFromPartition", "partition-fetched", data, data.id);
     return data;
   }
 
@@ -3696,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;
+  }
+
 }
 
 /**