@ronaldroe/micro-flow 1.0.0 → 1.2.1

package/src/classes/steps/switch_step.js

@@ -0,0 +1,77 @@
+import Step from './step.js';
+
+/**
+ * SwitchStep class for implementing switch/case logic in workflows.
+ * Evaluates cases in order and executes the first matching case, or a default callable if no cases match.
+ * @class SwitchStep
+ * @extends Step
+ */
+export default class SwitchStep extends Step {
+  static step_name = 'switch';
+
+  /**
+   * Creates a new SwitchStep instance.
+   * @param {Object} options - Configuration options.
+   * @param {string} [options.name] - Name of the step.
+   * @param {Array<Case|LogicStep>} [options.cases=[]] - Array of Case or LogicStep instances to evaluate. LogicStep instances MUST have conditional.subject set.
+   * @param {Function|Step|Workflow} [options.default_callable=async () => {}] - Function, Step, or Workflow to execute if no cases match.
+   * @param {*|Function} [options.subject=null] - Subject value to evaluate against each case. Can be a function that returns the value.
+   */
+  constructor({
+    name,
+    cases = [],
+    default_callable = async () => {},
+    subject = null
+  }) {
+    super({
+      name,
+      step_type: SwitchStep.step_name,
+    });
+
+    this.cases = cases;
+    this._default_callable_type = this.getCallableType(default_callable);
+    this._default_callable_raw = default_callable;
+    this.default_callable = this._default_callable_type === 'function'
+      ? default_callable.bind(this)
+      : default_callable.execute.bind(default_callable);
+    this.subject = subject;
+
+    this.callable = this.switch.bind(this);
+  }
+
+  /**
+   * Executes the switch logic by evaluating each case in order.
+   * Returns the result of the first matching case, or the default callable if no match.
+   * @returns {Promise<*>} The result of the matched case or default callable.
+   */
+  async switch() {
+    // Resolve subject once - call it if it's a function
+    const resolvedSubject = typeof this.subject === 'function' ? this.subject() : this.subject;
+    
+    for (const switch_case of this.cases) {
+      switch_case.switch_subject = resolvedSubject;
+
+      const is_matched = await switch_case.checkCondition();
+
+      if (is_matched) {
+        this.log(
+          this.getState('events.step.event_names.SWITCH_CASE_MATCHED'),
+          `Case matched for step: ${this.name}, executing case callable`
+        );
+
+        // Return the case's result value directly, not the Case object.
+        // This keeps result structure consistent: switchStep.result contains the
+        // callable's return value, matching how Step.result works.
+        const caseResult = await switch_case.execute();
+        return caseResult.result;
+      }
+    }
+
+    // Unwrap Step/Workflow results for consistency with case results
+    const defaultResult = await this.default_callable();
+    if (this._default_callable_type !== 'function') {
+      return defaultResult.result;
+    }
+    return defaultResult;
+  }
+}

package/src/classes/workflow.js

@@ -1,4 +1,5 @@
-import { Base } from './index.js';
+import crypto from 'crypto';
+import Base from './base.js';
 import { base_types } from '../enums/index.js';
 
 /**
@@ -12,7 +13,7 @@ export default class Workflow extends Base {
    * @param {Object} options - Configuration options.
    * @param {string} [options.name] - Name of the workflow.
    * @param {boolean} [options.exit_on_error=false] - Whether to exit on error.
-   * @param {Array} [options.steps=[]] - Array of steps to add to the workflow.
+   * @param {Array<Step>} [options.steps=[]] - Array of steps to add to the workflow.
    * @param {boolean} [options.throw_on_empty=false] - Whether to throw error if workflow is empty.
    */
   constructor({
@@ -29,6 +30,8 @@ export default class Workflow extends Base {
 
     this.exit_on_error = exit_on_error;
     this.throw_on_empty = throw_on_empty;
+    this.sessions = {};
+    this.current_session_id = null;
   }
 
   /**
@@ -38,6 +41,10 @@ export default class Workflow extends Base {
    * @throws {Error} Throws if workflow is empty and throw_on_empty is true.
    */
   async execute() {
+    if (!this.current_session_id) {
+      this.current_session_id = crypto.randomUUID();
+    }
+
     if (this.isEmpty()) {
       if (this.throw_on_empty) {
         throw new Error('Cannot execute an empty workflow');
@@ -51,23 +58,17 @@ export default class Workflow extends Base {
     this.markAsRunning();
 
     for (let i = 0; i < this._steps.length; i++) {
-      if (this.getState('should_pause')) {
-        this.markAsPaused();
-        this.setState('should_pause', false);
-        break;
-      }
-  
-      if (this.getState('should_break')) {
-        this.log('workflow_break_executed', `Workflow "${this.name}" execution broken at step ${this._steps[i].name} - ${this._steps[i].id}.`);
+      if (this.should_break) {
+        this.log(this.getState('event_names.workflow').WORKFLOW_BREAK_EXECUTED, `Workflow "${this.name}" execution broken at step ${this._steps[i].name} - ${this._steps[i].id}.`);
         break;
       }
 
-      if (this.getState('should_skip')) {
+      if (this.should_skip) {
         this.log(
           this.getState('events.workflow.event_names.WORKFLOW_STEP_SKIPPED'),
           `Workflow "${this.name}" skipping step ${this._steps[i].name} - ${this._steps[i].id}.`
         );
-        this.setState('should_skip', false);
+        this.should_skip = false;
         continue;
       }
 
@@ -84,6 +85,12 @@ export default class Workflow extends Base {
           return this;
         }
       }
+
+      if (this.should_pause) {
+        this.markAsPaused();
+        this.should_pause = false;
+        return this;
+      }
     }
 
     this.markAsComplete();
@@ -114,14 +121,11 @@ export default class Workflow extends Base {
   async step() {
     const step = this.steps_by_id[this.current_step];
 
-    let result;
-    try {
-      result = await step.execute();
-      this.results.push(result);
-    } catch (error) {
-      if (this.exit_on_error) {
-        throw error;
-      }
+    step.parentWorkflowId = this.id;
+    const result = await step.execute();
+
+    if (step.status === this.getState('statuses.step.FAILED')) {
+      throw step.errors[step.errors.length - 1] ?? new Error(`Step "${step.name}" failed`);
     }
 
     return result;
@@ -157,6 +161,11 @@ export default class Workflow extends Base {
    * @param {number} index - The index at which to insert the step.
    */
   addStepAtIndex(step, index) {
+    if (!this.steps_by_id || typeof this.steps_by_id !== 'object') {
+      this.steps_by_id = {};
+    }
+
+    this.steps_by_id[step.id] = step;
     step.parentWorkflowId = this.id;
     this._steps.splice(index, 0, step);
   }
@@ -176,6 +185,23 @@ export default class Workflow extends Base {
     this._steps = [];
   }
 
+  /**
+   * Closes the current session and stores a snapshot of the workflow state.
+   */
+  closeCurrentSession() {
+    if (!this.current_session_id) {
+      return;
+    }
+
+    this.sessions[this.current_session_id] = {
+      results: [...this.results],
+      status: this.status,
+      timing: { ...this.timing },
+      closed_at: new Date()
+    };
+    this.current_session_id = null;
+  }
+
   /**
    * Deletes a step from the workflow by its ID.
    * @param {string} stepId - The ID of the step to delete.
@@ -228,9 +254,17 @@ export default class Workflow extends Base {
    * @returns {boolean} True if the workflow is empty.
    */
   isEmpty() {
-    return !this._steps && !this._steps.length
+    return !this._steps || !this._steps.length
   }
-  
+
+  /**
+   * Marks the workflow as complete and closes the current session.
+   */
+  markAsComplete() {
+    super.markAsComplete();
+    this.closeCurrentSession();
+  }
+
   /**
    * Marks the workflow as created.
    * @returns {string} The CREATED status.
@@ -243,15 +277,23 @@ export default class Workflow extends Base {
       `Workflow "${this.name}" created.`
     );
 
-    return this.getState('workflow.statuses').CREATED;
+    return this.getState('statuses.workflow').CREATED;
   }
-  
+
+  /**
+   * Marks the workflow as failed and closes the current session.
+   */
+  markAsFailed() {
+    super.markAsFailed();
+    this.closeCurrentSession();
+  }
+
   /**
    * Marks the workflow as paused.
    */
   markAsPaused() {
     this.timing.pause_time = new Date();
-    this.status = this.getState('workflow.statuses').PAUSED;
+    this.status = this.getState('statuses.workflow').PAUSED;
 
     this.getState('events.workflow').emit(
       this.getState('event_names.workflow').WORKFLOW_PAUSED,
@@ -264,7 +306,7 @@ export default class Workflow extends Base {
    */
   markAsResumed() {
     this.timing.resume_time = new Date();
-    this.status = this.getState('workflow.statuses').RUNNING;
+    this.status = this.getState('statuses.workflow').RUNNING;
 
     this.getState('events.workflow').emit(
       this.getState('event_names.workflow').WORKFLOW_RESUMED,
@@ -374,6 +416,12 @@ export default class Workflow extends Base {
    * @param {Step[]} steps - Array of steps to add.
    */
   set steps(steps) {
+    steps.forEach((step, index) => {
+      if (typeof step.getCallableType !== 'function') {
+        throw new Error(`Invalid step type. Step at index ${index} is not an instance of Step.`);
+      }
+    });
+
     this.addSteps(steps);
   }
 }

package/src/enums/conditional_step_comparators.js

@@ -7,21 +7,51 @@
  */
 const conditional_step_comparators = {
   EQUALS: 'equals',
-  STRICT_EQUALS: 'strict_equals',
-  NOT_EQUALS: 'not_equals',
-  STRICT_NOT_EQUALS: 'strict_not_equals',
   GREATER_THAN: 'greater_than',
-  LESS_THAN: 'less_than',
   GREATER_THAN_OR_EQUAL: 'greater_than_or_equal',
+  LESS_THAN: 'less_than',
   LESS_THAN_OR_EQUAL: 'less_than_or_equal',
+  NOT_EQUALS: 'not_equals',
+  STRICT_EQUALS: 'strict_equals',
+  STRICT_NOT_EQUALS: 'strict_not_equals',
+
   SIGN_EQUALS: '==',
-  SIGN_STRICT_EQUALS: '===',
-  SIGN_NOT_EQUALS: '!=',
-  SIGN_STRICT_NOT_EQUALS: '!==',
   SIGN_GREATER_THAN: '>',
-  SIGN_LESS_THAN: '<',
   SIGN_GREATER_THAN_OR_EQUAL: '>=',
+  SIGN_LESS_THAN: '<',
   SIGN_LESS_THAN_OR_EQUAL: '<=',
+  SIGN_NOT_EQUALS: '!=',
+  SIGN_STRICT_EQUALS: '===',
+  SIGN_STRICT_NOT_EQUALS: '!==',
+
+  STRING_CONTAINS: 'string_contains',
+  STRING_INCLUDES: 'string_includes',
+  STRING_NOT_CONTAINS: 'string_not_contains',
+  STRING_NOT_INCLUDES: 'string_not_includes',
+  STRING_STARTS_WITH: 'string_starts_with',
+  STRING_ENDS_WITH: 'string_ends_with',
+
+  ARRAY_CONTAINS: 'array_contains',
+  ARRAY_INCLUDES: 'array_includes',
+  ARRAY_NOT_CONTAINS: 'array_not_contains',
+  ARRAY_NOT_INCLUDES: 'array_not_includes',
+
+  EMPTY: 'empty',
+  NOT_EMPTY: 'not_empty',
+
+  REGEX_MATCH: 'regex_match',
+  REGEX_NOT_MATCH: 'regex_not_match',
+
+  IN: 'in',
+  NOT_IN: 'not_in',
+
+  NULLISH: 'nullish',
+  NOT_NULLISH: 'not_nullish',
+
+  IS_TYPE: 'is_type',
+  IS_NOT_TYPE: 'is_not_type',
+
+  CUSTOM_FUNCTION: 'custom_function'
 };
 
 export default conditional_step_comparators;

package/src/enums/delay_types.js

@@ -20,13 +20,6 @@ const delay_types = {
    */
   ABSOLUTE: 'absolute',
   
-  /**
-   * Delay using a cron expression for scheduled execution.
-   * Use with cron_expression property.
-   * @type {string}
-   */
-  CRON: 'cron',
-  
   /**
    * Delay for a relative duration in milliseconds.
    * Use with delay_duration property.

package/src/enums/errors.js

@@ -7,6 +7,8 @@
 const errors = {
   INVALID_STATE_PATH: 'The provided state path is invalid.\n',
   INVALID_CONDITIONAL: 'Conditional properties are required for LogicStep.',
+  OBJECT_NOT_PARSEABLE: 'The provided object could not be parsed.\n',
+  VALUE_NOT_ITERABLE: 'The provided value is not iterable.\n',
 };
 
 /**

package/src/enums/index.js

@@ -4,6 +4,7 @@ export * from './errors.js';
 export { default as flow_control_types } from './flow_control_types.js';
 export { default as logic_step_types } from './logic_step_types.js';
 export { default as loop_types } from './loop_types.js';
+export { default as state_event_names } from './state_event_names.js';
 export { default as step_event_names } from './step_event_names.js';
 export { default as step_statuses } from './step_statuses.js';
 export { default as step_types } from './step_types.js';

package/src/enums/loop_types.js

@@ -5,8 +5,10 @@
  * @readonly
  */
 const loop_types = {
+  FOR: 'for',
+  FOR_EACH: 'for_each',
+  GENERATOR: 'generator',
   WHILE: 'while',
-  FOR_EACH: 'for_each'
 };
 
 export default loop_types;

package/src/enums/state_event_names.js

@@ -0,0 +1,17 @@
+/**
+ * Enumeration of state event names.
+ */
+const state_event_names = {
+  DELETED: 'deleted',
+  EACH: 'each',
+  FROZEN: 'frozen',
+  GET: 'get',
+  GET_FROM_PROPERTY_PATH: 'get_from_property_path',
+  GET_STATE: 'get_state',
+  MERGE: 'merge',
+  RESET: 'reset',
+  SET: 'set',
+  SET_TO_PROPERTY_PATH: 'set_to_property_path',
+}
+
+export default state_event_names;

package/src/enums/step_event_names.js

@@ -8,6 +8,8 @@
 const step_event_names = {
   CONDITIONAL_FALSE_BRANCH_EXECUTED: 'conditional_false_branch_executed',
   CONDITIONAL_TRUE_BRANCH_EXECUTED: 'conditional_true_branch_executed',
+  DELAY_STEP_ABSOLUTE_SCHEDULED: 'delay_step_absolute_scheduled',
+  DELAY_STEP_RELATIVE_SCHEDULED: 'delay_step_relative_scheduled',
   DELAY_STEP_ABSOLUTE_COMPLETE: 'delay_step_absolute_complete',
   DELAY_STEP_RELATIVE_COMPLETE: 'delay_step_relative_complete',
   LOOP_ITERATION_COMPLETE: 'loop_iteration_complete',
@@ -17,6 +19,7 @@ const step_event_names = {
   STEP_PENDING: 'step_pending',
   STEP_WAITING: 'step_waiting',
   STEP_RETRYING: 'step_retrying',
+  SWITCH_CASE_MATCHED: 'switch_case_matched',
 }
 
 export default step_event_names;

package/src/enums/step_types.js

@@ -7,8 +7,9 @@
  */
 const step_types = {
   ACTION: 'action',
-  LOGIC: 'logic',
   DELAY: 'delay',
+  LOGIC: 'logic',
+  LOOP: 'loop',
 };
 
 export default step_types;

package/src/enums/sub_step_types.js

@@ -1,130 +1,20 @@
-import { readdirSync, readFileSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import logic_step_types from './logic_step_types.js';
-import step_types from './step_types.js';
-import { sub } from 'date-fns';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-/**
- * Generates a mapping of Step class names to their step_name identifiers by reading
- * class files from the filesystem. This approach avoids circular dependencies that would
- * occur if we imported the Step classes directly.
- * 
- * The function parses each class file to extract:
- * - The class name from the export statement
- * - The static step_name property value
- * 
- * When step_name references an enum (e.g., logic_step_types.CONDITIONAL), the function
- * resolves the actual string value from the imported enum objects.
- * 
- * The built-in classes directory is always scanned. Additional directories can be provided
- * to scan for custom step classes. This is typically used via the workflow's sub_step_type_paths
- * configuration option.
- * 
- * @function generate_sub_step_types
- * @param {string[]} [directories=[]] - An array of additional directory paths to scan for class files. 
- *   The built-in classes directory is always included. Defaults to an empty array.
- * @returns {Object.<string, string|null>} An object mapping class names to their step_name values.
- *   Classes without a step_name property are mapped to null.
- * @example
- * // Default usage (scans built-in classes only)
- * const types = generate_sub_step_types();
- * // Returns:
- * // {
- * //   "Step": null,
- * //   "ConditionalStep": "conditional",
- * //   "LogicStep": "logic",
- * //   "DelayStep": "delay",
- * //   ...
- * // }
- * 
- * // With custom directories
- * const types = generate_sub_step_types(['/path/to/custom/steps']);
- */
-const generate_sub_step_types = (directories = []) => {
-  const types = {};
-  
-  // Always include the classes directory, then append any additional directories
-  directories.push(join(__dirname, '../classes'));
-  
-  // Combine all enums into one lookup object
-  const allEnums = {
-    logic_step_types,
-    step_types
-  };
-  
-  // Scan each directory in the array
-  for (const dir of directories) {
-    // Read all files in the current directory
-    const files = readdirSync(dir).filter(file => file.endsWith('.js') && file !== 'index.js');
-    
-    for (const file of files) {
-      const filePath = join(dir, file);
-      const content = readFileSync(filePath, 'utf-8');
-      
-      // Extract class name from the file content
-      const classNameMatch = content.match(/export default class (\w+)/);
-      if (!classNameMatch) continue;
-      
-      const className = classNameMatch[1];
-      
-      // Extract static step_name value
-      const stepNameMatch = content.match(/static step_name\s*=\s*['"`]?([^'"`;\n]+)['"`]?/);
-      
-      if (stepNameMatch) {
-        let stepName = stepNameMatch[1].trim();
-        
-        // Handle cases where step_name references an enum
-        // e.g., logic_step_types.CONDITIONAL or step_types.ACTION
-        if (stepName.includes('.')) {
-          const [enumName, enumKey] = stepName.split('.');
-          
-          // Look up the actual value from the imported enums
-          if (allEnums[enumName] && allEnums[enumName][enumKey]) {
-            stepName = allEnums[enumName][enumKey];
-          } else {
-            stepName = null;
-          }
-        }
-        
-        types[className] = stepName;
-      } else {
-        types[className] = null;
-      }
-    }
-  }
-  
-  return types;
-}
-
 /**
- * Pre-generated mapping of all built-in Step class names to their step_name identifiers.
- * This is a singleton object exported as the default export.
- * 
- * **Changed in recent version:** Previously exported as a function, now exported as a
- * pre-generated object for improved performance and consistency.
- * 
- * @constant {Object.<string, string|null>}
+ * Enumeration of sub-step types used in the workflow system.
+ * @type {Object.<string, string>}
+ * @readonly
  * @example
- * import sub_step_types from 'micro-flow';
- * 
- * console.log(sub_step_types);
- * // {
- * //   "Step": null,
- * //   "ConditionalStep": "conditional",
- * //   "DelayStep": "delay",
- * //   "LoopStep": "loop",
- * //   ...
- * // }
- * 
- * // Check if a class name is a registered step type
- * if (sub_step_types['ConditionalStep']) {
- *   console.log('ConditionalStep is a registered step type');
- * }
+ * console.log(sub_step_types.Step); // "step"
+ * console.log(sub_step_types.ConditionalStep); // "conditional"
  */
-const sub_step_types = generate_sub_step_types();
+const sub_step_types = {
+  Step: 'step',
+  LogicStep: 'logic',
+  ConditionalStep: 'conditional',
+  FlowControlStep: 'flow_control',
+  LoopStep: 'loop',
+  SwitchStep: 'switch',
+  Case: 'case',
+  DelayStep: 'delay',
+};
 
 export default sub_step_types;

package/src/enums/workflow_event_names.js

@@ -6,6 +6,7 @@
  * @readonly
  */
 const workflow_event_names = {
+  WORKFLOW_BREAK_EXECUTED: 'workflow_break_executed',
   WORKFLOW_CANCELLED: 'workflow_cancelled',
   WORKFLOW_COMPLETE: 'workflow_complete',
   WORKFLOW_CREATED: 'workflow_created',

package/index.js

@@ -1 +0,0 @@
-export * from './src/index.js';

package/src/classes/events/broadcast.js

@@ -1,57 +0,0 @@
-/**
- * Broadcast class provides a simplified wrapper around the BroadcastChannel API
- * for cross-context communication (e.g., between tabs, windows, workers).
- * 
- * This class allows you to send and receive messages across different browsing contexts
- * that share the same origin. It encapsulates the creation and management of a BroadcastChannel,
- * providing a simplified API for sending and receiving messages.
- * 
- * @class Broadcast
- * @extends BroadcastChannel
- */
-export default class Broadcast extends BroadcastChannel {
-  /**
-   * Creates a new Broadcast instance for a named channel.
-   * 
-   * @constructor
-   * @param {string} channelName - The name of the broadcast channel to create or connect to.
-   * Multiple Broadcast instances with the same channel name can communicate with each other.
-   */
-  constructor(channelName) {
-    super(channelName);
-  }
-
-  /**
-   * Sends data to all other contexts listening on this channel.
-   * 
-   * @param {*} data - The data to broadcast. Can be any structured-cloneable value
-   * (primitives, objects, arrays, etc.). Functions and DOM nodes cannot be sent.
-   * @returns {void}
-   */
-  send(data) {
-    this.postMessage(data);
-  }
-
-  /**
-   * Registers a callback to handle incoming messages on this channel.
-   * 
-   * @param {Function} callback - Function to call when a message is received.
-   * Receives the message data as its only parameter.
-   * @returns {void}
-   */
-  onReceive(callback) {
-    this.onmessage = (event) => {
-      callback(event.data);
-    };
-  }
-
-  /**
-   * Closes the broadcast channel and releases its resources.
-   * After calling this method, the Broadcast instance can no longer send or receive messages.
-   * 
-   * @returns {void}
-   */
-  destroy() {
-    this.close();
-  }
-}