@ronaldroe/micro-flow 1.0.0

package/src/classes/steps/flow_control_step.js

@@ -0,0 +1,69 @@
+import { LogicStep } from './index.js';
+import flow_control_types from '../../enums/flow_control_types.js';
+
+/**
+ * FlowControlStep class for controlling workflow execution flow (break, continue, skip, pause).
+ * @class FlowControlStep
+ * @extends LogicStep
+ */
+export default class FlowControlStep extends LogicStep {
+  static step_name = 'flow_control';
+
+  /**
+   * 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 {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.
+   */
+  constructor({
+    conditional = {
+      subject: null,
+      operator: null,
+      value: null,
+    },
+    name,
+    flow_control_type = flow_control_types.BREAK,
+  }) {
+    super({
+      name,
+      conditional
+    });
+
+    if (!Object.values(flow_control_types).includes(flow_control_type)) {
+      throw new Error(`Invalid flow control type: ${flow_control_type}`);
+    }
+
+    this.flow_control_type = flow_control_type;
+    this.callable = this.shouldFlowControl.bind(this);
+  }
+
+  /**
+   * Evaluates the condition and sets the appropriate flow control flag.
+   * @async
+   * @returns {Promise<boolean>} True if the flow control should be activated.
+   */
+  async shouldFlowControl() {
+    if (this.checkCondition()) {
+      this.log(
+        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);
+
+      return true;
+    } else {
+      this.log(
+        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);
+
+      return false;
+    }
+  }
+}

package/src/classes/steps/index.js

@@ -0,0 +1,4 @@
+export { default as Step } from './step.js';
+export { default as LogicStep } from './logic_step.js';
+export { default as ConditionalStep } from './conditional_step.js';
+export { default as FlowControlStep } from './flow_control_step.js';

package/src/classes/steps/logic_step.js

@@ -0,0 +1,102 @@
+import Step from './step.js';
+import { step_types } from '../../enums/index.js';
+
+const conditional_keys = [
+  'subject',
+  'operator',
+  'value',
+];
+
+/**
+ * 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 {string} [options.conditional.operator] - Comparison operator.
+   * @param {*} [options.conditional.value] - Value to compare against.
+   * @param {Function} [options.callable=async () => {}] - Function to execute.
+   */
+  constructor({
+    name,
+    conditional = {
+      subject: null,
+      operator: null,
+      value: null,
+    },
+    callable = async () => {},
+  }) {
+    super({
+      name,
+      base_type: step_types.LOGIC_STEP,
+      callable
+    });
+
+    this.validateAndSetConditional(conditional);
+  }
+
+  /**
+   * Evaluates the conditional expression.
+   * @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;
+
+    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;
+      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.
+   */
+  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'));
+      }
+    }
+
+    this.subject = conditional.subject;
+    this.operator = conditional.operator;
+    this.value = conditional.value;
+  }
+}

package/src/classes/steps/step.js

@@ -0,0 +1,111 @@
+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';
+
+  /**
+   * 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)) {
+      this.callable_object.prepareReturnData();
+    }
+
+    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 instanceof Workflow) {
+      return 'workflow';
+    } else if (callable instanceof 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 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;
+    }
+  }
+}

package/src/classes/workflow.js

@@ -0,0 +1,379 @@
+import { Base } from './index.js';
+import { base_types } from '../enums/index.js';
+
+/**
+ * Workflow class for managing and executing a sequence of steps.
+ * @class Workflow
+ * @extends Base
+ */
+export default class Workflow extends Base {
+  /**
+   * Creates a new Workflow instance.
+   * @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 {boolean} [options.throw_on_empty=false] - Whether to throw error if workflow is empty.
+   */
+  constructor({
+    name,
+    exit_on_error = false,
+    steps = [],
+    throw_on_empty = false
+  }) {
+    super({ name, base_type: base_types.WORKFLOW });
+
+    this.initializeWorkflowState();
+
+    this.addSteps(steps);
+
+    this.exit_on_error = exit_on_error;
+    this.throw_on_empty = throw_on_empty;
+  }
+
+  /**
+   * Executes the workflow by running all steps in sequence.
+   * @async
+   * @returns {Promise<Workflow>} The workflow instance with execution results.
+   * @throws {Error} Throws if workflow is empty and throw_on_empty is true.
+   */
+  async execute() {
+    if (this.isEmpty()) {
+      if (this.throw_on_empty) {
+        throw new Error('Cannot execute an empty workflow');
+      }
+
+      this.markAsComplete();
+      this.prepareResult('Workflow is empty', null);
+      return this;
+    }
+  
+    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}.`);
+        break;
+      }
+
+      if (this.getState('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);
+        continue;
+      }
+
+      this.current_step = this._steps[i].id;
+
+      try {
+        const step_result = await this.step();
+        this.prepareResult('Success', step_result);
+      } catch (error) {
+        this.markAsFailed();
+        this.prepareResult(`Workflow execution failed at step ${this.steps_by_id[this.current_step].name} - ${this.current_step}`, { error });
+  
+        if (this.exit_on_error) {
+          return this;
+        }
+      }
+    }
+
+    this.markAsComplete();
+    return this;
+  }
+
+  /**
+   * Resumes a paused workflow.
+   * @async
+   * @returns {Promise<Workflow>} The workflow instance.
+   */
+  async resume() {
+    this.should_pause = false;
+    this.timing.resume_time = new Date();
+
+    this.getState('events.workflow').emit(
+      this.getState('event_names.workflow').WORKFLOW_RESUMED,
+      this.getState()
+    );
+    return this.execute();
+  }
+
+  /**
+   * Executes a single step in the workflow.
+   * @async
+   * @returns {Promise<*>} The result of the step execution.
+   */
+  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;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Adds a step to the workflow.
+   * @param {Step} step - The step to add.
+   * @throws {Error} Throws if step is not a valid Step instance.
+   */
+  addStep(step) {
+    if (typeof step.getCallableType !== 'function') {
+      throw new Error('Invalid step type. Must be an instance of Step.');
+    }
+
+    if (!Array.isArray(this._steps)) {
+      this._steps = [];
+    }
+
+    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.push(step);
+  }
+
+  /**
+   * Adds a step at a specific index in the workflow.
+   * @param {Step} step - The step to add.
+   * @param {number} index - The index at which to insert the step.
+   */
+  addStepAtIndex(step, index) {
+    step.parentWorkflowId = this.id;
+    this._steps.splice(index, 0, step);
+  }
+
+  /**
+   * Adds multiple steps to the workflow.
+   * @param {Step[]} steps - Array of steps to add.
+   */
+  addSteps(steps) {
+    steps.forEach(step => this.addStep(step));
+  }
+
+  /**
+   * Clears all steps from the workflow.
+   */
+  clearSteps() {
+    this._steps = [];
+  }
+
+  /**
+   * Deletes a step from the workflow by its ID.
+   * @param {string} stepId - The ID of the step to delete.
+   */
+  deleteStep(stepId) {
+    this._steps = this._steps.filter(step => step.id !== stepId);
+  }
+
+  /**
+   * Deletes a step from the workflow by its index.
+   * @param {number} index - The index of the step to delete.
+   */
+  deleteStepByIndex(index) {
+    this._steps.splice(index, 1);
+  }
+
+  /**
+   * Initializes the workflow state with default values.
+   */
+  initializeWorkflowState() {
+    this.results = [];
+    this.exit_on_error = false;
+    this.current_step = null;
+    this.should_break = false;
+    this.should_continue = false;
+    this.should_pause = false;
+    this.should_skip = false;
+    this.status = this.getState('statuses.workflow').CREATED;
+    this._steps = [];
+    this.throw_on_empty = this.throw_on_empty;
+    this.timing = {
+      ...this.timing,
+      create_time: new Date(),
+      pause_time: null,
+      resume_time: null,
+    }
+
+    const workflows = this.getState('workflows');
+    workflows[this.id] = this;
+    this.setState('workflows', workflows);
+
+    this.log(
+      this.getState('event_names.workflow').WORKFLOW_CREATED,
+      `Workflow "${this.name}" initialized.`
+    );
+  }
+
+  /**
+   * Checks if the workflow has no steps.
+   * @returns {boolean} True if the workflow is empty.
+   */
+  isEmpty() {
+    return !this._steps && !this._steps.length
+  }
+  
+  /**
+   * Marks the workflow as created.
+   * @returns {string} The CREATED status.
+   */
+  markAsCreated() {
+    this.timing.create_time = new Date();
+    
+    this.log(
+      this.getState('event_names.workflow').WORKFLOW_CREATED,
+      `Workflow "${this.name}" created.`
+    );
+
+    return this.getState('workflow.statuses').CREATED;
+  }
+  
+  /**
+   * Marks the workflow as paused.
+   */
+  markAsPaused() {
+    this.timing.pause_time = new Date();
+    this.status = this.getState('workflow.statuses').PAUSED;
+
+    this.getState('events.workflow').emit(
+      this.getState('event_names.workflow').WORKFLOW_PAUSED,
+      this.getState()
+    );
+  }
+  
+  /**
+   * Marks the workflow as resumed.
+   */
+  markAsResumed() {
+    this.timing.resume_time = new Date();
+    this.status = this.getState('workflow.statuses').RUNNING;
+
+    this.getState('events.workflow').emit(
+      this.getState('event_names.workflow').WORKFLOW_RESUMED,
+      this.getState()
+    );
+  }
+
+  /**
+   * Moves a step from one index to another.
+   * @param {number} fromIndex - The current index of the step.
+   * @param {number} toIndex - The target index for the step.
+   */
+  moveStep(fromIndex, toIndex) {
+    const [step] = this._steps.splice(fromIndex, 1);
+    this._steps.splice(toIndex, 0, step);
+
+    this.getState('events.workflow').emit(
+      this.getState('event_names.workflow').WORKFLOW_STEP_MOVED,
+      this.getState()
+    );
+  }
+
+  /**
+   * Pauses the workflow execution.
+   */
+  pause() {
+    this.should_pause = true;
+    this.timing.pause_time = new Date();
+
+    this.getState('events.workflow').emit(
+      this.getState('event_names.workflow').WORKFLOW_PAUSED,
+      this.getState()
+    );
+  }
+
+  /**
+   * Removes and returns the last step from the workflow.
+   * @returns {Step} The last step.
+   */
+  popStep() {
+    return this._steps.pop();
+  }
+
+  /**
+   * Prepares a result object and adds it to the results array.
+   * @param {string} message - Result message.
+   * @param {*} data - Result data.
+   */
+  prepareResult(message, data) {
+    this.results.push({ message, data });
+  }
+
+  /**
+   * Adds a step to the end of the workflow.
+   * @param {Step} step - The step to add.
+   */
+  pushStep(step) {
+    this.addStep(step);
+  }
+
+  /**
+   * Adds multiple steps to the end of the workflow.
+   * @param {Step[]} steps - Array of steps to add.
+   */
+  pushSteps(steps) {
+    steps.forEach(step => this.addStep(step));
+  }
+
+  /**
+   * Removes and returns the first step from the workflow.
+   * @returns {Step} The first step.
+   */
+  shiftStep() {
+    return this._steps.shift();
+  }
+
+  /**
+   * Adds a step to the beginning of the workflow.
+   * @param {Step} step - The step to add.
+   * @throws {Error} Throws if step is not a valid Step instance.
+   */
+  unshiftStep(step) {
+    if (typeof step.getCallableType !== 'function') {
+      throw new Error('Invalid step type. Must be an instance of Step.');
+    }
+
+    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.unshift(step);
+  }
+
+  /**
+   * Gets the array of steps in the workflow.
+   * @returns {Step[]} Array of steps.
+   */
+  get steps() {
+    return this._steps;
+  }
+
+  /**
+   * Sets the steps array by adding multiple steps.
+   * @param {Step[]} steps - Array of steps to add.
+   */
+  set steps(steps) {
+    this.addSteps(steps);
+  }
+}

package/src/enums/base_types.js

@@ -0,0 +1,6 @@
+const base_types = {
+  STEP: 'step',
+  WORKFLOW: 'workflow'
+};
+
+export default base_types;

package/src/enums/conditional_step_comparators.js

@@ -0,0 +1,27 @@
+/**
+ * Enumeration of comparison operators for conditional steps.
+ * Provides both named and symbolic operator formats.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+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_OR_EQUAL: 'less_than_or_equal',
+  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_OR_EQUAL: '<=',
+};
+
+export default conditional_step_comparators;