s3db.js 9.3.0 → 10.0.1

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

@@ -79,7 +79,7 @@ import tryFn from "../concerns/try-fn.js";
  *   },
  *   
  *   persistTransitions: true,
- *   transitionLogResource: 'state_transitions'
+ *   transitionLogResource: 'plg_state_transitions'
  * });
  *
  * === Usage ===
@@ -91,7 +91,7 @@ import tryFn from "../concerns/try-fn.js";
  * const state = await stateMachine.getState('order_processing', orderId);
  *
  * // Get valid events for current state
- * const validEvents = stateMachine.getValidEvents('order_processing', 'pending');
+ * const validEvents = await stateMachine.getValidEvents('order_processing', 'pending');
  *
  * // Get transition history
  * const history = await stateMachine.getTransitionHistory('order_processing', orderId);
@@ -105,15 +105,15 @@ export class StateMachinePlugin extends Plugin {
       actions: options.actions || {},
       guards: options.guards || {},
       persistTransitions: options.persistTransitions !== false,
-      transitionLogResource: options.transitionLogResource || 'state_transitions',
-      stateResource: options.stateResource || 'entity_states',
-      verbose: options.verbose || false,
-      ...options
+      transitionLogResource: options.transitionLogResource || 'plg_state_transitions',
+      stateResource: options.stateResource || 'plg_entity_states',
+      retryAttempts: options.retryAttempts || 3,
+      retryDelay: options.retryDelay || 100,
+      verbose: options.verbose || false
     };
-    
+
     this.database = null;
     this.machines = new Map();
-    this.stateStorage = new Map(); // In-memory cache for states
     
     this._validateConfiguration();
   }
@@ -292,49 +292,68 @@ export class StateMachinePlugin extends Plugin {
     // Persist transition log
     if (this.config.persistTransitions) {
       const transitionId = `${machineId}_${entityId}_${timestamp}`;
-      
-      const [logOk, logErr] = await tryFn(() => 
-        this.database.resource(this.config.transitionLogResource).insert({
-          id: transitionId,
-          machineId,
-          entityId,
-          fromState,
-          toState,
-          event,
-          context,
-          timestamp,
-          createdAt: now.slice(0, 10) // YYYY-MM-DD for partitioning
-        })
-      );
-      
+
+      // Retry transition logging (critical for audit trail)
+      let logOk = false;
+      let lastLogErr;
+
+      for (let attempt = 0; attempt < this.config.retryAttempts; attempt++) {
+        const [ok, err] = await tryFn(() =>
+          this.database.resource(this.config.transitionLogResource).insert({
+            id: transitionId,
+            machineId,
+            entityId,
+            fromState,
+            toState,
+            event,
+            context,
+            timestamp,
+            createdAt: now.slice(0, 10) // YYYY-MM-DD for partitioning
+          })
+        );
+
+        if (ok) {
+          logOk = true;
+          break;
+        }
+
+        lastLogErr = err;
+
+        if (attempt < this.config.retryAttempts - 1) {
+          const delay = this.config.retryDelay * Math.pow(2, attempt);
+          await new Promise(resolve => setTimeout(resolve, delay));
+        }
+      }
+
       if (!logOk && this.config.verbose) {
-        console.warn(`[StateMachinePlugin] Failed to log transition:`, logErr.message);
+        console.warn(`[StateMachinePlugin] Failed to log transition after ${this.config.retryAttempts} attempts:`, lastLogErr.message);
       }
-      
-      // Update current state
+
+      // Update current state with upsert pattern
       const stateId = `${machineId}_${entityId}`;
-      const [stateOk, stateErr] = await tryFn(async () => {
-        const exists = await this.database.resource(this.config.stateResource).exists(stateId);
-        
-        const stateData = {
-          id: stateId,
-          machineId,
-          entityId,
-          currentState: toState,
-          context,
-          lastTransition: transitionId,
-          updatedAt: now
-        };
-        
-        if (exists) {
-          await this.database.resource(this.config.stateResource).update(stateId, stateData);
-        } else {
-          await this.database.resource(this.config.stateResource).insert(stateData);
+      const stateData = {
+        machineId,
+        entityId,
+        currentState: toState,
+        context,
+        lastTransition: transitionId,
+        updatedAt: now
+      };
+
+      // Try update first (most common case), fallback to insert if doesn't exist
+      const [updateOk] = await tryFn(() =>
+        this.database.resource(this.config.stateResource).update(stateId, stateData)
+      );
+
+      if (!updateOk) {
+        // Record doesn't exist, insert it
+        const [insertOk, insertErr] = await tryFn(() =>
+          this.database.resource(this.config.stateResource).insert({ id: stateId, ...stateData })
+        );
+
+        if (!insertOk && this.config.verbose) {
+          console.warn(`[StateMachinePlugin] Failed to upsert state:`, insertErr.message);
         }
-      });
-      
-      if (!stateOk && this.config.verbose) {
-        console.warn(`[StateMachinePlugin] Failed to update state:`, stateErr.message);
       }
     }
   }
@@ -374,22 +393,23 @@ export class StateMachinePlugin extends Plugin {
 
   /**
    * Get valid events for current state
+   * Can accept either a state name (sync) or entityId (async to fetch latest state)
    */
-  getValidEvents(machineId, stateOrEntityId) {
+  async getValidEvents(machineId, stateOrEntityId) {
     const machine = this.machines.get(machineId);
     if (!machine) {
       throw new Error(`State machine '${machineId}' not found`);
     }
-    
+
     let state;
     if (machine.config.states[stateOrEntityId]) {
-      // stateOrEntityId is a state name
+      // stateOrEntityId is a state name - direct lookup
       state = stateOrEntityId;
     } else {
-      // stateOrEntityId is an entityId, get current state
-      state = machine.currentStates.get(stateOrEntityId) || machine.config.initialState;
+      // stateOrEntityId is an entityId - fetch latest state from storage
+      state = await this.getState(machineId, stateOrEntityId);
     }
-    
+
     const stateConfig = machine.config.states[state];
     return stateConfig && stateConfig.on ? Object.keys(stateConfig.on) : [];
   }
@@ -401,29 +421,30 @@ export class StateMachinePlugin extends Plugin {
     if (!this.config.persistTransitions) {
       return [];
     }
-    
+
     const { limit = 50, offset = 0 } = options;
-    
-    const [ok, err, transitions] = await tryFn(() => 
-      this.database.resource(this.config.transitionLogResource).list({
-        where: { machineId, entityId },
-        orderBy: { timestamp: 'desc' },
+
+    const [ok, err, transitions] = await tryFn(() =>
+      this.database.resource(this.config.transitionLogResource).query({
+        machineId,
+        entityId
+      }, {
         limit,
         offset
       })
     );
-    
+
     if (!ok) {
       if (this.config.verbose) {
         console.warn(`[StateMachinePlugin] Failed to get transition history:`, err.message);
       }
       return [];
     }
-    
-    // Sort by timestamp descending to ensure newest first
-    const sortedTransitions = transitions.sort((a, b) => b.timestamp - a.timestamp);
-    
-    return sortedTransitions.map(t => ({
+
+    // Sort by timestamp descending (newest first)
+    const sorted = (transitions || []).sort((a, b) => b.timestamp - a.timestamp);
+
+    return sorted.map(t => ({
       from: t.fromState,
       to: t.toState,
       event: t.event,
@@ -440,33 +461,41 @@ export class StateMachinePlugin extends Plugin {
     if (!machine) {
       throw new Error(`State machine '${machineId}' not found`);
     }
-    
+
     const initialState = machine.config.initialState;
     machine.currentStates.set(entityId, initialState);
-    
+
     if (this.config.persistTransitions) {
       const now = new Date().toISOString();
       const stateId = `${machineId}_${entityId}`;
-      
-      await this.database.resource(this.config.stateResource).insert({
-        id: stateId,
-        machineId,
-        entityId,
-        currentState: initialState,
-        context,
-        lastTransition: null,
-        updatedAt: now
-      });
+
+      // Try to insert, ignore if already exists (idempotent)
+      const [ok, err] = await tryFn(() =>
+        this.database.resource(this.config.stateResource).insert({
+          id: stateId,
+          machineId,
+          entityId,
+          currentState: initialState,
+          context,
+          lastTransition: null,
+          updatedAt: now
+        })
+      );
+
+      // Only throw if error is NOT "already exists"
+      if (!ok && err && !err.message?.includes('already exists')) {
+        throw new Error(`Failed to initialize entity state: ${err.message}`);
+      }
     }
-    
+
     // Execute entry action for initial state
     const initialStateConfig = machine.config.states[initialState];
     if (initialStateConfig && initialStateConfig.entry) {
       await this._executeAction(initialStateConfig.entry, context, 'INIT', machineId, entityId);
     }
-    
+
     this.emit('entity_initialized', { machineId, entityId, initialState });
-    
+
     return initialState;
   }
 
@@ -531,7 +560,6 @@ export class StateMachinePlugin extends Plugin {
 
   async stop() {
     this.machines.clear();
-    this.stateStorage.clear();
   }
 
   async cleanup() {

package/src/resource.class.js

@@ -926,6 +926,7 @@ export class Resource extends AsyncEventEmitter {
     data._lastModified = request.LastModified;
     data._hasContent = request.ContentLength > 0;
     data._mimeType = request.ContentType || null;
+    data._etag = request.ETag;
     data._v = objectVersion;
 
     // Add version info to returned data
@@ -1159,6 +1160,210 @@ export class Resource extends AsyncEventEmitter {
     }
   }
 
+  /**
+   * Update with conditional check (If-Match ETag)
+   * @param {string} id - Resource ID
+   * @param {Object} attributes - Attributes to update
+   * @param {Object} options - Options including ifMatch (ETag)
+   * @returns {Promise<Object>} { success: boolean, data?: Object, etag?: string, error?: string }
+   * @example
+   * const msg = await resource.get('msg-123');
+   * const result = await resource.updateConditional('msg-123', { status: 'processing' }, { ifMatch: msg._etag });
+   * if (!result.success) {
+   *   console.log('Update failed - object was modified by another process');
+   * }
+   */
+  async updateConditional(id, attributes, options = {}) {
+    if (isEmpty(id)) {
+      throw new Error('id cannot be empty');
+    }
+
+    const { ifMatch } = options;
+    if (!ifMatch) {
+      throw new Error('updateConditional requires ifMatch option with ETag value');
+    }
+
+    // Check if resource exists
+    const exists = await this.exists(id);
+    if (!exists) {
+      return {
+        success: false,
+        error: `Resource with id '${id}' does not exist`
+      };
+    }
+
+    // Get original data
+    const originalData = await this.get(id);
+    const attributesClone = cloneDeep(attributes);
+    let mergedData = cloneDeep(originalData);
+
+    // Merge attributes (same logic as update)
+    for (const [key, value] of Object.entries(attributesClone)) {
+      if (key.includes('.')) {
+        let ref = mergedData;
+        const parts = key.split('.');
+        for (let i = 0; i < parts.length - 1; i++) {
+          if (typeof ref[parts[i]] !== 'object' || ref[parts[i]] === null) {
+            ref[parts[i]] = {};
+          }
+          ref = ref[parts[i]];
+        }
+        ref[parts[parts.length - 1]] = cloneDeep(value);
+      } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        mergedData[key] = merge({}, mergedData[key], value);
+      } else {
+        mergedData[key] = cloneDeep(value);
+      }
+    }
+
+    // Update timestamps if enabled
+    if (this.config.timestamps) {
+      const now = new Date().toISOString();
+      mergedData.updatedAt = now;
+      if (!mergedData.metadata) mergedData.metadata = {};
+      mergedData.metadata.updatedAt = now;
+    }
+
+    // Execute beforeUpdate hooks
+    const preProcessedData = await this.executeHooks('beforeUpdate', cloneDeep(mergedData));
+    const completeData = { ...originalData, ...preProcessedData, id };
+
+    // Validate
+    const { isValid, errors, data } = await this.validate(cloneDeep(completeData));
+    if (!isValid) {
+      return {
+        success: false,
+        error: 'Validation failed: ' + ((errors && errors.length) ? JSON.stringify(errors) : 'unknown'),
+        validationErrors: errors
+      };
+    }
+
+    // Prepare data for storage
+    const { id: validatedId, ...validatedAttributes } = data;
+    const mappedData = await this.schema.mapper(validatedAttributes);
+    mappedData._v = String(this.version);
+
+    const behaviorImpl = getBehavior(this.behavior);
+    const { mappedData: processedMetadata, body } = await behaviorImpl.handleUpdate({
+      resource: this,
+      id,
+      data: validatedAttributes,
+      mappedData,
+      originalData: { ...attributesClone, id }
+    });
+
+    const key = this.getResourceKey(id);
+    let existingContentType = undefined;
+    let finalBody = body;
+
+    if (body === "" && this.behavior !== 'body-overflow') {
+      const [ok, err, existingObject] = await tryFn(() => this.client.getObject(key));
+      if (ok && existingObject.ContentLength > 0) {
+        const existingBodyBuffer = Buffer.from(await existingObject.Body.transformToByteArray());
+        const existingBodyString = existingBodyBuffer.toString();
+        const [okParse, errParse] = await tryFn(() => Promise.resolve(JSON.parse(existingBodyString)));
+        if (!okParse) {
+          finalBody = existingBodyBuffer;
+          existingContentType = existingObject.ContentType;
+        }
+      }
+    }
+
+    let finalContentType = existingContentType;
+    if (finalBody && finalBody !== "" && !finalContentType) {
+      const [okParse, errParse] = await tryFn(() => Promise.resolve(JSON.parse(finalBody)));
+      if (okParse) finalContentType = 'application/json';
+    }
+
+    // Attempt conditional write with IfMatch
+    const [ok, err, response] = await tryFn(() => this.client.putObject({
+      key,
+      body: finalBody,
+      contentType: finalContentType,
+      metadata: processedMetadata,
+      ifMatch  // ← Conditional write with ETag
+    }));
+
+    if (!ok) {
+      // Check if it's a PreconditionFailed error (412)
+      if (err.name === 'PreconditionFailed' || err.$metadata?.httpStatusCode === 412) {
+        return {
+          success: false,
+          error: 'ETag mismatch - object was modified by another process'
+        };
+      }
+
+      // Other errors
+      return {
+        success: false,
+        error: err.message || 'Update failed'
+      };
+    }
+
+    // Success - compose updated data
+    const updatedData = await this.composeFullObjectFromWrite({
+      id,
+      metadata: processedMetadata,
+      body: finalBody,
+      behavior: this.behavior
+    });
+
+    // Handle partition updates (async if configured)
+    const oldData = { ...originalData, id };
+    const newData = { ...validatedAttributes, id };
+
+    if (this.config.asyncPartitions && this.config.partitions && Object.keys(this.config.partitions).length > 0) {
+      // Async mode
+      setImmediate(() => {
+        this.handlePartitionReferenceUpdates(oldData, newData).catch(err => {
+          this.emit('partitionIndexError', {
+            operation: 'updateConditional',
+            id,
+            error: err,
+            message: err.message
+          });
+        });
+      });
+
+      // Execute non-partition hooks
+      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', {
+        ...updatedData,
+        $before: { ...originalData },
+        $after: { ...finalResult }
+      });
+
+      return {
+        success: true,
+        data: finalResult,
+        etag: response.ETag
+      };
+    } else {
+      // Sync mode
+      await this.handlePartitionReferenceUpdates(oldData, newData);
+      const finalResult = await this.executeHooks('afterUpdate', updatedData);
+
+      this.emit('update', {
+        ...updatedData,
+        $before: { ...originalData },
+        $after: { ...finalResult }
+      });
+
+      return {
+        success: true,
+        data: finalResult,
+        etag: response.ETag
+      };
+    }
+  }
+
   /**
    * Delete a resource object by ID
    * @param {string} id - Resource ID