@ronaldroe/micro-flow 0.0.9

package/src/classes/steps/logic_step.js

@@ -0,0 +1,148 @@
+import Step from './step.js';
+import { conditional_step_comparators, step_types } from '../../enums/index.js';
+
+/**
+ * LogicStep class for conditional logic operations.
+ * @class LogicStep
+ * @extends Step
+ */
+export default class LogicStep extends Step {
+  static step_name = 'logic';
+
+  /**
+   * Creates a new LogicStep instance.
+   * @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 {conditional_step_comparators|string} [options.conditional.operator] - Comparison operator.
+   * @param {*} [options.conditional.value] - Value to compare against.
+   * @param {Function} [options.callable=async () => {}] - Function to execute.
+   */
+  constructor({
+    name,
+    callable = async () => {},
+    conditional = {
+      operator: null,
+      subject: null,
+      value: null,
+    },
+  }) {
+    super({
+      name,
+      base_type: step_types.LOGIC,
+      callable
+    });
+
+    this.setConditional(conditional);
+  }
+
+  /**
+   * Evaluates the conditional expression.
+   * @returns {boolean} True if the condition is met.
+   * @throws {Error} Throws if operator is unknown.
+   */
+  checkCondition() {
+    const subject = this.conditional.subject;
+    const operator = this.conditional.operator;
+    const value = this.conditional.value;
+
+    switch (operator) {
+      case this.getState('conditional_step_comparators.STRICT_EQUALS'):
+      case this.getState('conditional_step_comparators.SIGN_STRICT_EQUALS'):
+        return subject === value;
+      case this.getState('conditional_step_comparators.SIGN_EQUALS'):
+      case this.getState('conditional_step_comparators.EQUALS'):
+        return subject == value;
+      case this.getState('conditional_step_comparators.NOT_EQUALS'):
+      case this.getState('conditional_step_comparators.SIGN_NOT_EQUALS'):
+        return subject != value;
+      case this.getState('conditional_step_comparators.STRICT_NOT_EQUALS'):
+      case this.getState('conditional_step_comparators.SIGN_STRICT_NOT_EQUALS'):
+        return subject !== value;
+      case this.getState('conditional_step_comparators.GREATER_THAN'):
+      case this.getState('conditional_step_comparators.SIGN_GREATER_THAN'):
+        return subject > value;
+      case this.getState('conditional_step_comparators.LESS_THAN'):
+      case this.getState('conditional_step_comparators.SIGN_LESS_THAN'):
+        return subject < value;
+      case this.getState('conditional_step_comparators.GREATER_THAN_OR_EQUAL'):
+      case this.getState('conditional_step_comparators.SIGN_GREATER_THAN_OR_EQUAL'):
+        return subject >= value;
+      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'):
+      case this.getState('conditional_step_comparators.IN'):
+        return (Array.isArray(subject) || typeof subject === 'string') && subject.includes(value);
+      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'):
+      case this.getState('conditional_step_comparators.NOT_IN'):
+        return (Array.isArray(subject) || typeof subject === 'string') && !subject.includes(value);
+      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}`);
+    }
+  }
+
+  /**
+   * Checks if the conditional configuration is valid.
+   * @returns {boolean} True if conditional is valid.
+   */
+  conditionalIsValid() {
+    return (
+      this.conditional.subject !== null &&
+      this.conditional.subject !== undefined &&
+      this.conditional.operator !== null &&
+      this.conditional.operator !== undefined &&
+      this.conditional.value !== null &&
+      this.conditional.value !== undefined
+    );
+  }
+
+  /**
+   * Sets the conditional properties.
+   * @param {Object} conditional - Conditional configuration object.
+   * @throws {Error} Throws if conditional is invalid.
+   */
+  setConditional(conditional) {
+    this.conditional = { subject: conditional.subject, operator: conditional.operator, value: conditional.value };
+  }
+}

package/src/classes/steps/loop_step.js

@@ -0,0 +1,147 @@
+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 {*} [options.conditional.subject] - Subject to evaluate.
+   * @param {conditional_step_comparators|string} [options.conditional.operator] - Comparison operator.
+   * @param {*} [options.conditional.value] - Value to compare against.
+   * @param {string} [options.loop_type=loop_types.FOR_EACH] - Type of loop ('for', 'for_each', 'while', or 'generator').
+   * @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;
+
+    this.callable = this[`${loop_type}_loop`].bind(this);
+
+    // When this.callable is set, it binds the callable function to this instance
+    // so that it can access instance properties like current_item.
+    // Because we're using a local method instead, we bind it here.
+    this.callable_type = this.getCallableType(callable);
+    this._callable = this.callable_type === 'function'
+      ? callable.bind(this)
+      : callable.execute.bind(callable);
+  }
+
+  /**
+   * 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() {
+    if (!this._callable.constructor.name.includes('Generator')) {
+      throw new Error('Iterable must be a generator function for generator loops');
+    }
+
+    let iterations = 0;
+    for (const item of await this._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._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._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._callable());
+    }
+
+    return {
+      message: `While loop ${this.name} completed after ${iterations} iterations`,
+      result: this.results
+    };
+  }
+}

package/src/classes/steps/step.js

@@ -0,0 +1,129 @@
+import Base from '../base.js';
+import Workflow from '../workflow.js';
+import { base_types, step_types } from '../../enums/index.js';
+
+/**
+ * Step class representing an executable unit within a workflow.
+ * @class Step
+ * @extends Base
+ */
+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.
+   */
+  constructor({
+    name,
+    step_type = step_types.ACTION,
+    callable = async () => {},
+    sub_step_type = null,
+  }) {
+    super({ name, base_type: base_types.STEP });
+
+    this.callable = callable;
+
+    // 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.step_type = step_type;
+    this.sub_step_type = sub_step_type;
+
+    this.errors = [];
+    this.result = null;
+    this.retry_results = [];
+  }
+
+  /**
+   * Executes the step's callable function, Step, or Workflow.
+   * @async
+   * @returns {Promise<Step>} The step instance with execution results.
+   */
+  async execute() {
+    this.markAsRunning();
+
+    try {
+      this.result = await this._callable();
+    } 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.status !== this.getState('statuses')[this.base_type].FAILED) {
+      this.markAsComplete();
+    }
+
+    if (['step', 'workflow'].includes(this.callable_type)) {
+      return this.#callable_object;
+    }
+
+    return this;
+  }
+
+  /**
+   * Determines the type of the callable (function, step, or workflow).
+   * @param {Function|Step|Workflow} callable - The callable to check.
+   * @returns {string} The type: 'function', 'step', or 'workflow'.
+   * @throws {Error} Throws if callable type is invalid.
+   */
+  getCallableType(callable) {
+    if (callable && callable.base_type === base_types.WORKFLOW) {
+      return 'workflow';
+    } else if (callable && callable.base_type === base_types.STEP) {
+      return 'step';
+    } else if (typeof callable === 'function') {
+      return 'function';
+    } 
+
+    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.
+   */
+  set callable(callable) {
+    this.callable_type = this.getCallableType(callable);
+
+    if (['step', 'workflow'].includes(this.callable_type)) {
+      if (this.callable_type === 'step') {
+        callable.parentWorkflowId = this.parentWorkflowId ?? null;
+      }
+
+      this._callable = callable.execute.bind(callable);
+    } else {
+      this._callable = callable.bind(this);
+    }
+  }
+}

package/src/classes/steps/switch_step.js

@@ -0,0 +1,64 @@
+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 {*} [options.subject=null] - Subject value to evaluate against each case.
+   */
+  constructor({
+    name,
+    cases = [],
+    default_callable = async () => {},
+    subject = null
+  }) {
+    super({
+      name,
+      step_type: SwitchStep.step_name,
+    });
+
+    this.cases = cases;
+    const defaultCallableType = this.getCallableType(default_callable);
+    this.default_callable = defaultCallableType === '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() {
+    for (const switch_case of this.cases) {
+      switch_case.switch_subject = this.subject;
+
+      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 switch_case.execute();
+      }
+    }
+
+    return this.default_callable();
+  }
+}