@ronaldroe/micro-flow 0.0.9

package/src/classes/workflow.js

@@ -0,0 +1,383 @@
+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<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({
+    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.should_pause) {
+        this.markAsPaused();
+        this.should_pause = false;
+        return this;
+      }
+  
+      if (this.should_break) {
+        this.should_break = false;
+        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.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.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];
+
+    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;
+  }
+
+  /**
+   * 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('statuses.workflow').CREATED;
+  }
+  
+  /**
+   * Marks the workflow as paused.
+   */
+  markAsPaused() {
+    this.timing.pause_time = new Date();
+    this.status = this.getState('statuses.workflow').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('statuses.workflow').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) {
+    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/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,57 @@
+/**
+ * Enumeration of comparison operators for conditional steps.
+ * Provides both named and symbolic operator formats.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const conditional_step_comparators = {
+  EQUALS: 'equals',
+  GREATER_THAN: 'greater_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_GREATER_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

@@ -0,0 +1,31 @@
+/**
+ * Enumeration of delay types for DelayStep.
+ * 
+ * @enum {string}
+ * @readonly
+ * @example
+ * import delay_types from 'micro-flow';
+ * 
+ * const delayStep = new DelayStep({
+ *   name: 'wait-5-seconds',
+ *   delay_type: delay_types.RELATIVE,
+ *   delay_duration: 5000
+ * });
+ */
+const delay_types = {
+  /**
+   * Delay until a specific absolute timestamp or Date.
+   * Use with delay_timestamp property.
+   * @type {string}
+   */
+  ABSOLUTE: 'absolute',
+  
+  /**
+   * Delay for a relative duration in milliseconds.
+   * Use with delay_duration property.
+   * @type {string}
+   */
+  RELATIVE: 'relative',
+};
+
+export default delay_types;

package/src/enums/errors.js

@@ -0,0 +1,27 @@
+/**
+ * Error messages used in the micro-flow library.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+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',
+};
+
+/**
+ * Warning messages used in the micro-flow library.
+ * These are typically logged to the console to alert developers of potential issues.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const warnings = {
+  DO_NOT_SET_STEPS_DIRECTLY: 'Using this.setState("steps", ...) is not recommended. ' +
+    'State will not be initialized correctly. Use workflow methods to manage steps instead.',
+  BROADCAST_FAILED: 'Broadcast failed or is not supported in this environment. The error has more detail:\n',
+};
+
+export { errors, warnings };

package/src/enums/flow_control_types.js

@@ -0,0 +1,12 @@
+/**
+ * Enumeration of flow control types for breaking or continuing execution.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const flow_control_types = {
+  BREAK: 'break',
+  SKIP: 'skip'
+};
+
+export default flow_control_types;

package/src/enums/index.js

@@ -0,0 +1,14 @@
+export { default as conditional_step_comparators } from './conditional_step_comparators.js';
+export { default as delay_types } from './delay_types.js';
+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';
+export { default as sub_step_types } from './sub_step_types.js';
+export { default as workflow_event_names } from './workflow_event_names.js';
+export { default as workflow_statuses } from './workflow_statuses.js';
+export { default as base_types } from './base_types.js';

package/src/enums/logic_step_types.js

@@ -0,0 +1,16 @@
+/**
+ * Enumeration of logic step types for control flow operations.
+ * These types define different kinds of logic-based workflow steps.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const LogicStepTypes = {
+  CONDITIONAL: 'conditional',
+  LOOP: 'loop',
+  FLOW_CONTROL: 'flow_control',
+  SWITCH: 'switch',
+  SKIP: 'skip'
+};
+
+export default LogicStepTypes;

package/src/enums/loop_types.js

@@ -0,0 +1,14 @@
+/**
+ * Enumeration of loop types for LoopStep.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const loop_types = {
+  FOR: 'for',
+  FOR_EACH: 'for_each',
+  GENERATOR: 'generator',
+  WHILE: 'while',
+};
+
+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

@@ -0,0 +1,25 @@
+/**
+ * Enumeration of step lifecycle event names.
+ * Steps emit these events during their execution lifecycle.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+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',
+  STEP_COMPLETE: 'step_complete',
+  STEP_FAILED: 'step_failed',
+  STEP_RUNNING: 'step_running',
+  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_statuses.js

@@ -0,0 +1,17 @@
+/**
+ * Enumeration of possible step execution statuses.
+ * Steps transition through these statuses during their lifecycle.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const step_statuses = {
+  COMPLETE: 'complete',
+  FAILED: 'failed',
+  PENDING: 'pending',
+  QUEUED: 'queued',
+  RUNNING: 'running',
+  WAITING: 'waiting',
+};
+
+export default step_statuses;

package/src/enums/step_types.js

@@ -0,0 +1,15 @@
+/**
+ * Enumeration of step types used throughout the workflow system.
+ * These types categorize steps by their primary function.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const step_types = {
+  ACTION: 'action',
+  DELAY: 'delay',
+  LOGIC: 'logic',
+  LOOP: 'loop',
+};
+
+export default step_types;

package/src/enums/sub_step_types.js

@@ -0,0 +1,20 @@
+/**
+ * Enumeration of sub-step types used in the workflow system.
+ * @type {Object.<string, string>}
+ * @readonly
+ * @example
+ * console.log(sub_step_types.Step); // "step"
+ * console.log(sub_step_types.ConditionalStep); // "conditional"
+ */
+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

@@ -0,0 +1,27 @@
+/**
+ * Enumeration of workflow lifecycle event names.
+ * Workflows emit these events during their creation and execution lifecycle.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const workflow_event_names = {
+  WORKFLOW_BREAK_EXECUTED: 'workflow_break_executed',
+  WORKFLOW_CANCELLED: 'workflow_cancelled',
+  WORKFLOW_COMPLETE: 'workflow_complete',
+  WORKFLOW_CREATED: 'workflow_created',
+  WORKFLOW_ERRORED: 'workflow_errored',
+  WORKFLOW_FAILED: 'workflow_failed',
+  WORKFLOW_PAUSED: 'workflow_paused',
+  WORKFLOW_RESUMED: 'workflow_resumed',
+  WORKFLOW_RUNNING: 'workflow_running',
+  WORKFLOW_STEP_ADDED: 'workflow_step_added',
+  WORKFLOW_STEP_MOVED: 'workflow_step_moved',
+  WORKFLOW_STEP_REMOVED: 'workflow_step_removed',
+  WORKFLOW_STEP_SHIFTED: 'workflow_step_shifted',
+  WORKFLOW_STEP_SKIPPED: 'workflow_step_skipped',
+  WORKFLOW_STEPS_ADDED: 'workflow_steps_added',
+  WORKFLOW_STEPS_CLEARED: 'workflow_steps_cleared',
+}
+
+export default workflow_event_names;