@ronaldroe/micro-flow 1.0.0 → 1.2.0

package/src/classes/steps/delay_step.js

@@ -0,0 +1,103 @@
+import Step from './step.js';
+import { delay_types, step_types } from '../../enums/index.js';
+import schedule from 'node-schedule';
+import { addMilliseconds } from 'date-fns';
+
+/**
+ * DelayStep class for introducing delays in workflow execution.
+ * Supports both absolute and relative delays.
+ * @class DelayStep
+ * @extends Step
+ */
+export default class DelayStep extends Step {
+  static step_name = 'delay';
+
+  /**
+   * Creates a new DelayStep instance.
+   * @param {Object} options - Configuration options.
+   * @param {string} [options.name] - Name of the step.
+   * @param {Date|string} [options.absolute_timestamp=new Date()] - Absolute timestamp to delay until.
+   * @param {number} [options.relative_delay_ms=0] - Relative delay in milliseconds.
+   * @param {string} [options.delay_type=delay_types.RELATIVE] - Type of delay ('absolute' or 'relative').
+   */
+  constructor({
+    name,
+    absolute_timestamp = new Date(),
+    relative_delay_ms = 0,
+    delay_type = delay_types.RELATIVE
+  }) {
+    super({
+      name,
+      step_type: step_types.DELAY,
+    });
+
+    this.delay_type = delay_type;
+    this.absolute_timestamp = new Date(absolute_timestamp);
+    this.relative_delay_ms = relative_delay_ms;
+
+    this.callable = this[delay_type].bind(this);
+  }
+
+  /**
+   * Executes an absolute delay until the specified timestamp. If the timestamp is in the past, it continues immediately.
+   * @returns {Promise<Object>} Resolves with delay completion info when delay completes.
+   */
+  async absolute() {
+    const now = new Date();
+
+    if (this.absolute_timestamp.getTime() <= now.getTime()) {
+      this.log(
+        this.getState('events.step.event_names.DELAY_STEP_ABSOLUTE_COMPLETE'),
+        `No delay for step: ${this.name}. Continuing.`
+      );
+      return { delayed: false, delay_type: this.delay_type, timestamp: now.toISOString() };
+    }
+
+    return this.delay(this.absolute_timestamp);
+  }
+
+  /** Schedules a delay until the specified date and time.
+   * @param {Date} delay_until - The date and time to delay until.
+   * @returns {Promise<Object>} Resolves with delay completion info when delay completes.
+   */
+  async delay(delay_until) {
+    return new Promise((resolve) => {
+      this.log(
+        this.getState(
+          `events.step.event_names.DELAY_STEP_${this.delay_type.toUpperCase()}_SCHEDULED`
+        ),
+        `Delay scheduled for step: ${this.name} until ${delay_until.toISOString()}`
+      );
+
+      const job = schedule.scheduleJob(delay_until, () => {
+        this.log(
+          this.getState(
+            `events.step.event_names.DELAY_STEP_${this.delay_type.toUpperCase()}_COMPLETE`
+          ),
+          `Delay complete for step: ${this.name}. Continuing.`
+        );
+        resolve({ delayed: true, delay_type: this.delay_type, timestamp: new Date().toISOString() });
+      });
+
+      this.scheduled_job = job;
+    });
+  }
+
+  /**
+   * Executes a relative delay for the specified duration. If the delay duration is zero or negative, it continues immediately.
+   * @returns {Promise<Object>} Resolves with delay completion info when delay completes.
+   */
+  async relative() {
+    if (this.relative_delay_ms <= 0) {
+      this.log(
+        this.getState('events.step.event_names.DELAY_STEP_RELATIVE_COMPLETE'),
+        `No delay for step: ${this.name}. Continuing.`
+      );
+      return { delayed: false, delay_type: this.delay_type, timestamp: new Date().toISOString() };
+    }
+
+    const delay_until = addMilliseconds(new Date(), this.relative_delay_ms);
+
+    return this.delay(delay_until);
+  }
+}

package/src/classes/steps/flow_control_step.js

@@ -1,8 +1,9 @@
-import { LogicStep } from './index.js';
+import LogicStep from './logic_step.js';
 import flow_control_types from '../../enums/flow_control_types.js';
+import { conditional_step_comparators } from '../../enums/index.js';
 
 /**
- * FlowControlStep class for controlling workflow execution flow (break, continue, skip, pause).
+ * FlowControlStep class for controlling workflow execution flow (break or skip).
  * @class FlowControlStep
  * @extends LogicStep
  */
@@ -13,9 +14,9 @@ export default class FlowControlStep extends LogicStep {
    * Creates a new FlowControlStep instance.
    * @param {Object} options - Configuration options.
    * @param {Object} [options.conditional] - Conditional configuration.
-   * @param {*} [options.conditional.subject] - Subject to evaluate.
-   * @param {string} [options.conditional.operator] - Comparison operator.
-   * @param {*} [options.conditional.value] - Value to compare against.
+   * @param {*|Function} [options.conditional.subject] - Subject to evaluate. Can be a function that returns the value.
+   * @param {conditional_step_comparators|string} [options.conditional.operator] - Comparison operator.
+   * @param {*|Function} [options.conditional.value] - Value to compare against. Can be a function that returns the value.
    * @param {string} [options.name] - Name of the step.
    * @param {string} [options.flow_control_type=flow_control_types.BREAK] - Type of flow control.
    * @throws {Error} Throws if flow_control_type is invalid.
@@ -53,7 +54,7 @@ export default class FlowControlStep extends LogicStep {
         this.getState('events.step.event_names.CONDITIONAL_TRUE_BRANCH_EXECUTED'),
         `Break condition met for step: ${this.name}`
       );
-      this.setState(`should_${this.flow_control_type}`, true);
+      this.setParentWorkflowValue(this.parentWorkflowId, `should_${this.flow_control_type}`, true);
 
       return true;
     } else {
@@ -61,7 +62,7 @@ export default class FlowControlStep extends LogicStep {
         this.getState('events.step.event_names.CONDITIONAL_FALSE_BRANCH_EXECUTED'),
         `Break condition not met for step: ${this.name}`
       );
-      this.setState(`should_${this.flow_control_type}`, false);
+      this.setParentWorkflowValue(this.parentWorkflowId, `should_${this.flow_control_type}`, false);
 
       return false;
     }

package/src/classes/steps/index.js

@@ -1,4 +1,8 @@
 export { default as Step } from './step.js';
 export { default as LogicStep } from './logic_step.js';
+export { default as Case } from './case.js';
 export { default as ConditionalStep } from './conditional_step.js';
+export { default as DelayStep } from './delay_step.js';
 export { default as FlowControlStep } from './flow_control_step.js';
+export { default as LoopStep } from './loop_step.js';
+export { default as SwitchStep } from './switch_step.js';

package/src/classes/steps/logic_step.js

@@ -1,11 +1,5 @@
 import Step from './step.js';
-import { step_types } from '../../enums/index.js';
-
-const conditional_keys = [
-  'subject',
-  'operator',
-  'value',
-];
+import { conditional_step_comparators, step_types } from '../../enums/index.js';
 
 /**
  * LogicStep class for conditional logic operations.
@@ -20,38 +14,46 @@ export default class LogicStep extends Step {
    * @param {Object} options - Configuration options.
    * @param {string} [options.name] - Name of the step.
    * @param {Object} [options.conditional] - Conditional configuration.
-   * @param {*} [options.conditional.subject] - Subject to evaluate.
-   * @param {string} [options.conditional.operator] - Comparison operator.
-   * @param {*} [options.conditional.value] - Value to compare against.
+   * @param {*|Function} [options.conditional.subject] - Subject to evaluate. Can be a function that returns the value.
+   * @param {conditional_step_comparators|string} [options.conditional.operator] - Comparison operator.
+   * @param {*|Function} [options.conditional.value] - Value to compare against. Can be a function that returns the value.
    * @param {Function} [options.callable=async () => {}] - Function to execute.
    */
   constructor({
     name,
+    callable = async () => {},
     conditional = {
-      subject: null,
       operator: null,
+      subject: null,
       value: null,
     },
-    callable = async () => {},
   }) {
     super({
       name,
-      base_type: step_types.LOGIC_STEP,
+      step_type: step_types.LOGIC,
       callable
     });
 
-    this.validateAndSetConditional(conditional);
+    this.setConditional(conditional);
   }
 
   /**
    * Evaluates the conditional expression.
+   * Supports function subjects and values - they are called to get the actual value.
    * @returns {boolean} True if the condition is met.
    * @throws {Error} Throws if operator is unknown.
    */
   checkCondition() {
-    const subject = this.subject;
-    const operator = this.operator;
-    const value = this.value;
+    const rawSubject = this.conditional_config.subject;
+    const rawValue = this.conditional_config.value;
+    const operator = this.conditional_config.operator;
+    
+    // Resolve subject - call it if it's a function
+    const subject = typeof rawSubject === 'function' ? rawSubject() : rawSubject;
+    
+    // Don't resolve value for CUSTOM_FUNCTION - the value IS the function to call
+    const isCustomFunction = operator === this.getState('conditional_step_comparators.CUSTOM_FUNCTION');
+    const value = (!isCustomFunction && typeof rawValue === 'function') ? rawValue() : rawValue;
 
     switch (operator) {
       case this.getState('conditional_step_comparators.STRICT_EQUALS'):
@@ -78,25 +80,83 @@ export default class LogicStep extends Step {
       case this.getState('conditional_step_comparators.LESS_THAN_OR_EQUAL'):
       case this.getState('conditional_step_comparators.SIGN_LESS_THAN_OR_EQUAL'):
         return subject <= value;
+      case this.getState('conditional_step_comparators.STRING_CONTAINS'):
+      case this.getState('conditional_step_comparators.STRING_INCLUDES'):
+      case this.getState('conditional_step_comparators.ARRAY_CONTAINS'):
+      case this.getState('conditional_step_comparators.ARRAY_INCLUDES'):
+        return (Array.isArray(subject) || typeof subject === 'string') && subject.includes(value);
+      case this.getState('conditional_step_comparators.IN'):
+        return (Array.isArray(value) || typeof value === 'string') && value.includes(subject);
+      case this.getState('conditional_step_comparators.STRING_NOT_CONTAINS'):
+      case this.getState('conditional_step_comparators.STRING_NOT_INCLUDES'):
+      case this.getState('conditional_step_comparators.ARRAY_NOT_CONTAINS'):
+      case this.getState('conditional_step_comparators.ARRAY_NOT_INCLUDES'):
+        return (Array.isArray(subject) || typeof subject === 'string') && !subject.includes(value);
+      case this.getState('conditional_step_comparators.NOT_IN'):
+        return (Array.isArray(value) || typeof value === 'string') && !value.includes(subject);
+      case this.getState('conditional_step_comparators.EMPTY'):
+        return subject === '' || subject === null || subject === undefined || subject.length === 0;
+      case this.getState('conditional_step_comparators.NOT_EMPTY'):
+        return subject !== '' && subject !== null && subject !== undefined && subject.length > 0;
+      case this.getState('conditional_step_comparators.REGEX_MATCH'):
+        if (typeof value !== 'string') {
+          throw new Error(`Regex input must be a string.`);
+        }
+        const regex = new RegExp(value);
+        return regex.test(subject);
+      case this.getState('conditional_step_comparators.REGEX_NOT_MATCH'):
+        if (typeof value !== 'string') {
+          throw new Error(`Regex input must be a string.`);
+        }
+        const notMatchRegex = new RegExp(value);
+        return !notMatchRegex.test(subject);
+      case this.getState('conditional_step_comparators.STRING_STARTS_WITH'):
+        return typeof subject === 'string' && typeof value === 'string' && subject.startsWith(value);
+      case this.getState('conditional_step_comparators.STRING_ENDS_WITH'):
+        return typeof subject === 'string' && typeof value === 'string' && subject.endsWith(value);
+      case this.getState('conditional_step_comparators.NULLISH'):
+        return subject === null || subject === undefined;
+      case this.getState('conditional_step_comparators.NOT_NULLISH'):
+        return subject !== null && subject !== undefined;
+      case this.getState('conditional_step_comparators.IS_TYPE'):
+        return typeof subject === value;
+      case this.getState('conditional_step_comparators.IS_NOT_TYPE'):
+        return typeof subject !== value;
+      case this.getState('conditional_step_comparators.CUSTOM_FUNCTION'):
+        if (typeof value !== 'function') {
+          throw new Error(`Invalid custom function: ${value}`);
+        }
+        return value(subject);
       default:
         throw new Error(`Unknown operator: ${operator}`);
     }
   }
 
   /**
-   * Validates and sets the conditional properties.
-   * @param {Object} conditional - Conditional configuration object.
-   * @throws {Error} Throws if conditional is invalid.
+   * Checks if the conditional configuration is valid.
+   * A valid conditional has subject, operator, and value all set (not null/undefined).
+   * Functions are valid as subject or value - they will be called during checkCondition().
+   * @returns {boolean} True if conditional is valid.
    */
-  validateAndSetConditional(conditional) {
-    for (const [key, value] of Object.entries(conditional)) {
-      if (!value || !Object.values(conditional_keys).includes(key)) {
-        throw new Error(this.getState('messages.errors.INVALID_CONDITIONAL'));
-      }
-    }
+  conditionalIsValid() {
+    // Check if all conditional properties are set (not null or undefined)
+    // Can't use falsy check here because valid values could be falsy (e.g. empty string, 0, false)
+    // Functions are valid - they'll be called to get the actual value
+    return (
+      this.conditional_config.subject !== null &&
+      this.conditional_config.subject !== undefined &&
+      this.conditional_config.operator !== null &&
+      this.conditional_config.operator !== undefined &&
+      this.conditional_config.value !== null &&
+      this.conditional_config.value !== undefined
+    );
+  }
 
-    this.subject = conditional.subject;
-    this.operator = conditional.operator;
-    this.value = conditional.value;
+  /**
+   * Sets the conditional properties.
+   * @param {Object} conditional - Conditional configuration object.
+   */
+  setConditional(conditional) {
+    this.conditional_config = { subject: conditional.subject, operator: conditional.operator, value: conditional.value };
   }
 }

package/src/classes/steps/loop_step.js

@@ -0,0 +1,148 @@
+import { loop_types, step_types } from '../../enums/index.js';
+import LogicStep from './logic_step.js';
+import { conditional_step_comparators } from '../../enums/index.js';
+
+/**
+ * LoopStep class for executing loops within a workflow.
+ * @class LoopStep
+ * @extends LogicStep
+ */
+export default class LoopStep extends LogicStep {
+  static step_name = step_types.LOOP;
+
+  /**
+   * Creates a new LoopStep instance.
+   * @param {Object} options - Configuration options.
+   * @param {string} [options.name] - Name of the step.
+   * @param {Array|Iterable|Function} options.iterable - Iterable to loop over or function returning an iterable. Required for 'for_each' and 'generator' loops.
+   * @param {Function} [options.callable=async () => {}] - Function to execute for each iteration.
+   * @param {Object} [options.conditional] - Conditional configuration for while loops. Required for 'while' loops.
+   * @param {*|Function} [options.conditional.subject] - Subject to evaluate. Can be a function that returns the value.
+   * @param {conditional_step_comparators|string} [options.conditional.operator] - Comparison operator.
+   * @param {*|Function} [options.conditional.value] - Value to compare against. Can be a function that returns the value.
+   * @param {string} [options.loop_type=loop_types.FOR_EACH] - Type of loop ('for', 'for_each', 'while', or 'generator').
+   * @param {number} [options.iterations=0] - Number of iterations to execute. Only used for 'for' loops.
+   * @param {number} [options.max_iterations=1000] - Maximum number of iterations to prevent infinite loops.
+   */
+  constructor({
+    name,
+    iterable,
+    callable = async () => {},
+    conditional = {
+      operator: null,
+      subject: null,
+      value: null,
+    },
+    loop_type = loop_types.FOR_EACH,
+    iterations = 0,
+    max_iterations = 1000,
+  }) {
+    super({ name, conditional });
+    this.iterable = iterable;
+    this.loop_type = loop_type;
+    this.iterations = iterations > max_iterations ? max_iterations : iterations;
+    this.max_iterations = max_iterations;
+    this.results = [];
+    this.current_item = null;
+
+    // Store the user's callable separately so loop methods can invoke it.
+    // this._callable will be set to the loop method by the setter below.
+    const userCallableType = this.getCallableType(callable);
+    this._loop_callable = userCallableType === 'function'
+      ? callable.bind(this)
+      : callable.execute.bind(callable);
+
+    this.callable = this[`${loop_type}_loop`].bind(this);
+  }
+
+  /**
+   * Executes a generator/async generator and appends yielded values to results.
+   * @throws {Error} If the callable is not a generator or async generator function.
+   * @returns {Object} - An object containing a message and the results of the loop.
+   */
+  async generator_loop() {
+    if (!this._loop_callable.constructor.name.includes('Generator')) {
+      throw new Error('Iterable must be a generator function for generator loops');
+    }
+
+    let iterations = 0;
+    // Use for await...of to handle both sync and async generators
+    for await (const item of this._loop_callable()) {
+      this.results.push(item);
+
+      if (++iterations >= this.max_iterations) {
+        break;
+      }
+    }
+
+    return {
+      message: `Generator loop ${this.name} completed after ${iterations} iterations`,
+      result: this.results
+    };
+  }
+
+  /**
+   * Executes a for loop calling the callable for a set number of iterations
+   * @returns {Object} - An object containing a message and the results of the loop.
+   */
+  async for_loop() {
+    let i = 0;
+    for (; i < this.iterations; i++) {
+      this.results.push(await this._loop_callable());
+    }
+
+    return {
+      message: `For loop ${this.name} completed after ${i} iterations`,
+      result: this.results
+    };
+  }
+
+  /**
+   * Executes the callable for each item in the iterable.
+   * @throws {Error} If the iterable is not provided.
+   * @returns {Object} - An object containing a message and the results of the loop.
+   */
+  async for_each_loop() {
+    if (!this.iterable) {
+      throw new Error('Iterable is required for for_each loops');
+    }
+
+    if (typeof this.iterable === 'function') {
+      this.iterable = this.iterable();
+    }
+
+    let iterations = 0;
+    for (const item of this.iterable) {
+      iterations++;
+      this.current_item = item;
+      this.results.push(await this._loop_callable());
+    }
+
+    return {
+      message: `For each loop ${this.name} completed after ${iterations} iterations`,
+      result: this.results
+    };
+  }
+
+  /**
+   * Executes the callable while the condition is true.
+   * @throws {Error} If the conditional is not valid.
+   * @returns {Object} - An object containing a message and the results of the loop.
+   */
+  async while_loop() {
+    if (!this.conditionalIsValid()) {
+      throw new Error('Valid conditional is required for while loops');
+    }
+
+    let iterations = 0;
+    while (this.checkCondition() && iterations < this.max_iterations) {
+      iterations++;
+      this.results.push(await this._loop_callable());
+    }
+
+    return {
+      message: `While loop ${this.name} completed after ${iterations} iterations`,
+      result: this.results
+    };
+  }
+}

package/src/classes/steps/step.js

@@ -9,19 +9,24 @@ import { base_types, step_types } from '../../enums/index.js';
  */
 export default class Step extends Base {
   static step_name = 'step';
+  #callable_object = null;
 
   /**
    * Creates a new Step instance.
    * @param {Object} options - Configuration options.
    * @param {string} [options.name] - Name of the step.
-   * @param {string} [options.step_type=step_types.ACTION] - Type of the step.
    * @param {Function|Step|Workflow} [options.callable=async () => {}] - Function, Step, or Workflow to execute.
-   * @param {string} [options.sub_step_type=null] - Sub-type of the step.
+   * @param {number} [options.max_retries=0] - Maximum number of retries on failure.
+   * @param {number} [options.max_timeout_ms=30000] - Maximum execution time in milliseconds before timing out.
+   * @param {string} [options.step_type=step_types.ACTION] - Type of the step.
+   * @param {sub_step_types|null} [options.sub_step_type=null] - Sub-type of the step (use values from the sub_step_types enum).
    */
   constructor({
     name,
-    step_type = step_types.ACTION,
     callable = async () => {},
+    max_retries = 0,
+    max_timeout_ms = 30000,
+    step_type = step_types.ACTION,
     sub_step_type = null,
   }) {
     super({ name, base_type: base_types.STEP });
@@ -30,14 +35,18 @@ export default class Step extends Base {
 
     // Store off the original callable object, because if it's a Step or Workflow,
     // this.callable is set to the execute method of that object, but we may need to access its properties later.
-    this.callable_object = callable;
+    this.#callable_object = callable;
 
+    this.max_retries = max_retries;
+    this.retry_count = 0;
+    this.max_timeout_ms = max_timeout_ms;
     this.step_type = step_type;
     this.sub_step_type = sub_step_type;
 
     this.errors = [];
     this.result = null;
     this.retry_results = [];
+    this.timeout = null;
   }
 
   /**
@@ -46,28 +55,43 @@ export default class Step extends Base {
    * @returns {Promise<Step>} The step instance with execution results.
    */
   async execute() {
+    if (!this.timeout ) {
+      this.timeout = new Promise((_, reject) =>
+        setTimeout(reject, this.max_timeout_ms, new Error(`Step "${this.name}" timed out after ${this.max_timeout_ms}ms`))
+      );
+    }
+
     this.markAsRunning();
 
     try {
-      this.result = await this._callable();
+      this.result = await Promise.race([this._callable(), this.timeout]);
     } catch (error) {
-      this.errors.push(error);
-      this.markAsFailed();
-
-      this.timing.end_time = new Date();
-      this.timing.execution_time_ms = this.timing.end_time - this.timing.start_time;
-
-      if (this.getState('exit_on_error')) {
-        throw error;
+      if (this.max_retries && this.retry_count < this.max_retries) {
+        this.retry_count++;
+        this.retry_results.push({
+          retry_count: this.retry_count,
+          result: await this.execute(),
+        });
+      } else {
+        this.errors.push(error);
+
+        this.markAsFailed();
+
+        if (this.getState('exit_on_error')) {
+          throw error;
+        }
       }
+
     }
 
-    if (this.status !== this.getState('statuses')[this.base_type].FAILED) {
+    const { FAILED, COMPLETE } = this.getState('statuses')[this.base_type];
+
+    if (! [FAILED, COMPLETE].includes(this.status)) {
       this.markAsComplete();
     }
 
     if (['step', 'workflow'].includes(this.callable_type)) {
-      this.callable_object.prepareReturnData();
+      return this.#callable_object;
     }
 
     return this;
@@ -80,9 +104,9 @@ export default class Step extends Base {
    * @throws {Error} Throws if callable type is invalid.
    */
   getCallableType(callable) {
-    if (callable instanceof Workflow) {
+    if (callable && callable.base_type === base_types.WORKFLOW) {
       return 'workflow';
-    } else if (callable instanceof Step) {
+    } else if (callable && callable.base_type === base_types.STEP) {
       return 'step';
     } else if (typeof callable === 'function') {
       return 'function';
@@ -91,6 +115,23 @@ export default class Step extends Base {
     throw new Error('Invalid callable type. Must be one of function, Step, or Workflow.');
   }
 
+  /**
+   * Sets a value in the parent workflow's state.
+   * @param {string} workflowId - ID of the parent workflow.
+   * @param {string} path - Path in the workflow state to set.
+   * @param {*} value - Value to set at the specified path.
+   * @throws {Error} Throws if parent workflow is not found.
+   */
+  setParentWorkflowValue(workflowId, path, value) {
+    const parentWorkflow = this.getState('workflows')[workflowId];
+
+    if (!parentWorkflow) {
+      throw new Error(`Parent workflow with ID ${workflowId} not found.`);
+    }
+
+    parentWorkflow[path] = value;
+  }
+
   /**
    * Sets the callable for the step and determines its type.
    * @param {Function|Step|Workflow} callable - The callable to set.
@@ -105,7 +146,7 @@ export default class Step extends Base {
 
       this._callable = callable.execute.bind(callable);
     } else {
-      this._callable = callable;
+      this._callable = callable.bind(this);
     }
   }
 }