s3db.js 13.2.2 → 13.3.0

package/src/resource.class.js

@@ -1322,7 +1322,7 @@ export class Resource extends AsyncEventEmitter {
     // Execute afterGet hooks
     data = await this.executeHooks('afterGet', data);
 
-    this._emitStandardized("get", "fetched", data, data.id);
+    this._emitStandardized("fetched", data, data.id);
     const value = data;
     return value;
   }
@@ -2201,31 +2201,6 @@ export class Resource extends AsyncEventEmitter {
     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._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) {
-      throw mapAwsError(deleteError, {
-        bucket: this.client.config.bucket,
-        key,
-        resourceName: this.name,
-        operation: 'delete',
-        id
-      });
-    }
-    
-    if (!ok2) throw mapAwsError(err2, {
-      key,
-      resourceName: this.name,
-      operation: 'delete',
-      id
-    });
-    
     // Handle partition cleanup based on strictPartitions and asyncPartitions config
     if (this.config.partitions && Object.keys(this.config.partitions).length > 0 && objectData) {
       if (this.config.strictPartitions) {
@@ -2257,19 +2232,44 @@ export class Resource extends AsyncEventEmitter {
       }
 
       // Execute other afterDelete hooks synchronously (excluding partition hook)
-      const nonPartitionHooks = this.hooks.afterDelete.filter(hook => 
+      const nonPartitionHooks = this.hooks.afterDelete.filter(hook =>
         !hook.toString().includes('deletePartitionReferences')
       );
       let afterDeleteData = objectData;
       for (const hook of nonPartitionHooks) {
         afterDeleteData = await hook(afterDeleteData);
       }
-      return response;
     } else {
       // Sync mode: execute all hooks including partition deletion
       const afterDeleteData = await this.executeHooks('afterDelete', objectData);
-      return response;
     }
+
+    // Always emit delete event after hooks execute, for audit purposes (even if delete fails)
+    this._emitStandardized("deleted", {
+      ...objectData,
+      $before: { ...objectData },
+      $after: null
+    }, id);
+
+    // If we had an error getting the object, throw it now (after emitting event and hooks)
+    if (deleteError) {
+      throw mapAwsError(deleteError, {
+        bucket: this.client.config.bucket,
+        key,
+        resourceName: this.name,
+        operation: 'delete',
+        id
+      });
+    }
+
+    if (!ok2) throw mapAwsError(err2, {
+      key,
+      resourceName: this.name,
+      operation: 'delete',
+      id
+    });
+
+    return response;
   }
 
   /**
@@ -2357,7 +2357,7 @@ export class Resource extends AsyncEventEmitter {
     // Execute afterCount hooks
     await this.executeHooks('afterCount', { count, partition, partitionValues });
 
-    this._emitStandardized("count", "counted", count);
+    this._emitStandardized("count", count);
     return count;
   }
 
@@ -2385,7 +2385,7 @@ export class Resource extends AsyncEventEmitter {
         return result;
       });
 
-    this._emitStandardized("insertMany", "inserted-many", objects.length);
+    this._emitStandardized("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._emitStandardized("deleteMany", "deleted-many", ids.length);
+    this._emitStandardized("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._emitStandardized("deleteAll", "deleted-all", {
+    this._emitStandardized("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._emitStandardized("deleteAllData", "deleted-all-data", {
+    this._emitStandardized("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._emitStandardized("listIds", "listed-ids", ids.length);
+    this._emitStandardized("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._emitStandardized("list", "listed", { count: results.length, errors: 0 });
+    this._emitStandardized("list", { count: results.length, errors: 0 });
     return results;
   }
 
   async listPartition({ partition, partitionValues, limit, offset = 0 }) {
     if (!this.config.partitions?.[partition]) {
-      this._emitStandardized("list", "listed", { partition, partitionValues, count: 0, errors: 0 });
+      this._emitStandardized("list", { 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._emitStandardized("list", "listed", { partition, partitionValues, count: results.length, errors: 0 });
+    this._emitStandardized("list", { 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._emitStandardized("list", "listed", { count: results.length, errors: 0 });
+    this._emitStandardized("list", { 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._emitStandardized("list", "listed", { partition, partitionValues, count: 0, errors: 1 });
+      this._emitStandardized("list", { partition, partitionValues, count: 0, errors: 1 });
       return [];
     }
 
-    this._emitStandardized("list", "listed", { partition, partitionValues, count: 0, errors: 1 });
+    this._emitStandardized("list", { 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._emitStandardized("getMany", "fetched-many", ids.length);
+    this._emitStandardized("fetched-many", ids.length);
     return finalResults;
   }
 
@@ -2880,7 +2880,7 @@ export class Resource extends AsyncEventEmitter {
           hasTotalItems: totalItems !== null
         }
       };
-      this._emitStandardized("page", "paginated", result);
+      this._emitStandardized("paginated", result);
       return result;
     });
     if (ok) return result;
@@ -2954,7 +2954,7 @@ export class Resource extends AsyncEventEmitter {
       contentType
     }));
     if (!ok2) throw err2;
-    this._emitStandardized("setContent", "content-set", { id, contentType, contentLength: buffer.length }, id);
+    this._emitStandardized("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._emitStandardized("content", "content-fetched", { id, contentLength: buffer.length, contentType }, id);
+    this._emitStandardized("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._emitStandardized("deleteContent", "content-deleted", id, id);
+    this._emitStandardized("content-deleted", id, id);
     return response;
   }
 
@@ -3428,7 +3428,7 @@ export class Resource extends AsyncEventEmitter {
     data._partition = partitionName;
     data._partitionValues = partitionValues;
 
-    this._emitStandardized("getFromPartition", "partition-fetched", data, data.id);
+    this._emitStandardized("partition-fetched", data, data.id);
     return data;
   }
 
@@ -3719,120 +3719,114 @@ export class Resource extends AsyncEventEmitter {
   // ============================================================================
 
   /**
-   * 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
+   * State machine accessor object
+   * Provides namespaced access to state machine operations
+   * @type {Object}
+   * @property {Function} send - Trigger state transition
+   * @property {Function} get - Get current state
+   * @property {Function} canTransition - Check if transition is valid
+   * @property {Function} getValidEvents - Get valid events for current state
+   * @property {Function} initialize - Initialize entity with initial state
+   * @property {Function} history - Get transition history
    * @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);
-  }
+   * await orders.state.send('order-123', 'CONFIRM');
+   * const state = await orders.state.get('order-123');
+   * const canShip = await orders.state.canTransition('order-123', 'SHIP');
+   */
+  get state() {
+    const resource = this;
+
+    const throwIfNoStateMachine = () => {
+      if (!resource._stateMachine) {
+        throw new Error(
+          `No state machine configured for resource '${resource.name}'. ` +
+          `Ensure StateMachinePlugin is installed and configured for this resource.`
+        );
+      }
+    };
 
-  /**
-   * 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);
-  }
+    return {
+      /**
+       * Trigger a state transition
+       * @param {string} id - Entity ID
+       * @param {string} event - Event name
+       * @param {Object} [eventData] - Event data
+       * @returns {Promise<Object>} Transition result
+       * @example
+       * await orders.state.send('order-123', 'CONFIRM', { confirmedBy: 'user-456' });
+       */
+      send: async (id, event, eventData) => {
+        throwIfNoStateMachine();
+        return resource._stateMachine.send(id, event, eventData);
+      },
 
-  /**
-   * 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 current state of an entity
+       * @param {string} id - Entity ID
+       * @returns {Promise<string>} Current state
+       * @example
+       * const currentState = await orders.state.get('order-123');
+       */
+      get: async (id) => {
+        throwIfNoStateMachine();
+        return resource._stateMachine.getState(id);
+      },
 
-  /**
-   * 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);
-  }
+      /**
+       * Check if a transition is valid
+       * @param {string} id - Entity ID
+       * @param {string} event - Event name
+       * @returns {Promise<boolean>} True if transition is valid
+       * @example
+       * const canConfirm = await orders.state.canTransition('order-123', 'CONFIRM');
+       */
+      canTransition: async (id, event) => {
+        throwIfNoStateMachine();
+        return resource._stateMachine.canTransition(id, event);
+      },
 
-  /**
-   * 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 all valid events for the current state
+       * @param {string} id - Entity ID
+       * @returns {Promise<Array<string>>} Array of valid event names
+       * @example
+       * const events = await orders.state.getValidEvents('order-123');
+       * // Returns: ['SHIP', 'CANCEL']
+       */
+      getValidEvents: async (id) => {
+        throwIfNoStateMachine();
+        return resource._stateMachine.getValidEvents(id);
+      },
 
-  /**
-   * 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);
+      /**
+       * Initialize entity with initial state
+       * @param {string} id - Entity ID
+       * @param {Object} [context] - Initial context data
+       * @returns {Promise<void>}
+       * @example
+       * await orders.state.initialize('order-456', { customerId: 'user-123' });
+       */
+      initialize: async (id, context) => {
+        throwIfNoStateMachine();
+        return resource._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
+       * @example
+       * const history = await orders.state.history('order-123', { limit: 50 });
+       */
+      history: async (id, options) => {
+        throwIfNoStateMachine();
+        return resource._stateMachine.getTransitionHistory(id, options);
+      }
+    };
   }
 
   /**