@ronaldroe/micro-flow 0.0.9

package/src/classes/events/workflow_event.js

@@ -0,0 +1,28 @@
+import { Event } from './index.js';
+import { workflow_event_names } from '../../enums/index.js';
+
+/**
+ * Manages workflow-specific events by extending the base Event class.
+ * @class WorkflowEvent
+ * @extends Event
+ */
+export default class WorkflowEvent extends Event {
+  event_names = workflow_event_names;
+
+  /**
+   * Creates a new WorkflowEvent instance and registers all workflow events.
+   * @constructor
+   */
+  constructor() {
+    super();
+    this.registerWorkflowEvents();
+  }
+
+  /**
+   * Registers all workflow event names defined in the workflow_event_names enum.
+   * @returns {void}
+   */
+  registerWorkflowEvents() {
+    this.registerEvents(this.event_names);
+  }
+}

package/src/classes/index.js

@@ -0,0 +1,5 @@
+export * from './events/index.js';
+export { default as Base } from './base.js';
+export { default as State } from './state.js';
+export { default as Workflow } from './workflow.js';
+export * from './steps/index.js';

package/src/classes/state.js

@@ -0,0 +1,301 @@
+import { errors, warnings } from '../enums/errors.js';
+import { StepEvent, WorkflowEvent, StateEvent } from './events/index.js';
+import {
+  base_types,
+  conditional_step_comparators,
+  state_event_names,
+  step_event_names,
+  step_statuses,
+  step_types,
+  sub_step_types,
+  workflow_event_names,
+  workflow_statuses,
+} from '../enums/index.js';
+
+const defaultState = {
+  messages: {
+    errors,
+    warnings,
+  },
+  statuses: {
+    workflow: workflow_statuses,
+    step: step_statuses
+  },
+  event_names: {
+    workflow: workflow_event_names,
+    step: step_event_names,
+    state: state_event_names,
+  },
+  events: {
+    workflow: new WorkflowEvent(),
+    step: new StepEvent(),
+    state: new StateEvent(),
+  },
+  types: {
+    base_types,
+    step_types,
+    sub_step_types,
+  },
+  workflows: {},
+  conditional_step_comparators
+};
+
+let state = { ...defaultState };
+
+// Module-level shortcuts for events and event_names
+const events = state.events;
+const event_names = state.event_names;
+
+/**
+ * Singleton class representing the global state for workflows, steps, and processes.
+ * Provides methods for managing state with getter/setter functionality, nested path access,
+ * and immutability options. The state is shared across all workflow and step instances.
+ * 
+ * @class State
+ */
+class State {
+  /**
+   * Deletes a state property using dot-notation or bracket-notation path access.
+   * 
+   * @param {string} path - The path of the state property to delete (e.g., "user.profile.email" or "users[0].email").
+   * @returns {void}
+   * @throws {Error} Throws if path is empty or invalid.
+   */
+  static delete(path) {
+    if (!path) {
+      throw new Error(errors.INVALID_STATE_PATH);
+    }
+    
+    const parts = State.parsePath(path);
+    let current = state;
+    
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      
+      if (!Object.prototype.hasOwnProperty.call(current, part) || typeof current[part] !== 'object') {
+        return;
+      }
+      
+      current = current[part];
+    }
+    
+    delete current[parts[parts.length - 1]];
+
+    events.state.emit(event_names.state.DELETED, { state });
+  }
+
+  /**
+   * Iterates over a collection (array or object) located at the specified state path,
+   * executing a callback function for each item.
+   * 
+   * @param {string} path - The path of the state property to iterate over.
+   * @param {Function} callback - The function to execute for each item in the collection.
+   * @throws {Error} Throws if the state property at the path is not an array or object.
+   */
+  static async each(path, callback) {
+    const collection = State.get(path);
+    
+    if (Array.isArray(collection)) {
+      for (const [index, item] of collection.entries()) {
+        events.state.emit(event_names.state.EACH, { state });
+        await callback(item, index);
+      }
+    } else if (
+      typeof collection === 'object' &&
+      Object.prototype.toString.call(collection) === '[object Object]'
+    ) {
+      for (const key of Object.keys(collection)) {
+        events.state.emit(event_names.state.EACH, { state });
+        await callback(collection[key], key);
+      }
+    } else {
+      throw new Error(errors.VALUE_NOT_ITERABLE);
+    }
+  }
+
+  /**
+   * Freezes the entire state object, making it immutable.
+   * @returns {void}
+   */
+  static freeze() {
+    const frozenState = Object.freeze(state);
+    events.state.emit(event_names.state.FROZEN, { state });
+    return frozenState;
+  }
+
+  /**
+   * Gets the value of a state property using dot-notation or bracket-notation path access.
+   * 
+   * @param {string} path - The path of the state property to get. Supports both dot notation
+   * (e.g., "user.profile.name") and bracket notation (e.g., "users[0].name" or "data['key-name']").
+   * Special values:
+   * - Falsy values (null, undefined, false, ""): Returns entire state object
+   * - "*": Returns entire state object
+   * @param {*} [defaultValue=null] - Default value to return if the path doesn't exist.
+   * @param {string} [type='string'] - The output type to convert the value to.
+   * Supported types: "string", "number", "boolean".
+   * @returns {*} The value of the state property, or defaultValue if not found. null if not found
+   * and no defaultValue provided.
+   * @throws {Error} Throws if the value cannot be converted to the specified type.
+   */
+  static get(path, defaultValue = null, type = null) {
+    let gotten = state;
+    if (!path || ['*', ''].includes(path)) {
+      events.state.emit(event_names.state.GET, { state: gotten ?? defaultValue });
+      return gotten;
+    }
+
+    gotten = State.getFromPropertyPath(path, false) ?? defaultValue;
+
+    if (type) {
+      try {
+        switch (type) {
+          case 'string':
+            gotten = String(gotten);
+            break;
+          case 'number':
+            gotten = Number(gotten);
+            break;
+          case 'boolean':
+            gotten = Boolean(gotten);
+            break;
+          default:
+            break;
+        }
+      } catch (error) {
+        console.error("Error converting state value: ", error);
+      }
+    }
+
+    events.state.emit(event_names.state.GET, { state: gotten });
+
+    return gotten ?? defaultValue;
+  }
+
+  /**
+   * Resolves a nested property path within the state object.
+   * Supports both dot notation and bracket notation.
+   * 
+   * @param {string} path - The path to the property (e.g., "user.profile.name", "users[0].name", "data['key-name']").
+   * @param {boolean} [emit=true] - Whether to emit the GET_FROM_PROPERTY_PATH event.
+   * @returns {*} The value at the specified path, or undefined if not found.
+   */
+  static getFromPropertyPath(path, emit = true) {
+    const parts = State.parsePath(path);
+    let current = state;
+
+    for (const part of parts) {
+      if (current && Object.prototype.hasOwnProperty.call(current, part)) {
+        current = current[part];
+      } else {
+        return undefined;
+      }
+    }
+
+    if (emit) {
+      events.state.emit(event_names.state.GET_FROM_PROPERTY_PATH, { state });
+    }
+
+    return current;
+  }
+
+  /**
+   * Gets the entire state object.
+   * @returns {Object} The entire state object.
+   */
+  static getState() {
+    events.state.emit(event_names.state.GET_STATE, { state });
+    return state;
+  }
+
+  /**
+   * Merges an object into the current State.
+   * @param {Object} newState - The object to merge into the current State.
+   * @returns {object} The updated state object.
+   */
+  static merge(newState) {
+    state = { ...state, ...newState };
+    events.state.emit(event_names.state.MERGE, { state });
+    return state;
+  }
+
+  /**
+   * Parses a property path string into an array of keys, supporting both dot notation
+   * and bracket notation.
+   * 
+   * @param {string} path - The path to parse (e.g., "user.profile.name", "users[0].name", "data['key-name']").
+   * @returns {string[]} Array of property keys.
+   */
+  static parsePath(path) {
+    const matches = path.match(/[^.[\]]+|(?<=\[)([^\]]+)(?=\])/g);
+    
+    if (!matches) {
+      return [];
+    }
+
+    return matches.map(part => part.replace(/^['"]|['"]$/g, ''));
+  }
+
+  /**
+   * Resets the state to its default values.
+   * @returns {object} The reset state object.
+   */
+  static reset() {
+    state = { ...defaultState };
+    events.state.emit(event_names.state.RESET, { state });
+    return state;
+  }
+
+  /**
+   * Sets the value of a state property using dot-notation or bracket-notation path access.
+   * Creates intermediate objects if they don't exist.
+   * 
+   * @param {string} path - The path of the state property to set. Supports both dot notation
+   * (e.g., "user.profile.name") and bracket notation (e.g., "users[0].name" or "data['key-name']").
+   * @param {*} value - The value to set for the state property.
+   * @returns {void}
+   * @throws {Error} Throws if path is empty or invalid.
+   */
+  static set(path, value) {
+    if (!path) {
+      throw new Error(errors.INVALID_STATE_PATH);
+    }
+
+    events.state.emit(event_names.state.SET, { state });
+
+    State.setToPropertyPath(path, value, false);
+  }
+
+  /**
+   * Sets a nested property value within the state object based on a path.
+   * Supports both dot notation and bracket notation. Creates intermediate objects/arrays as needed.
+   * 
+   * @param {string} path - The path to the property (e.g., "user.profile.name", "users[0].name", "data['key-name']").
+   * @param {*} value - The value to set at the specified path.
+   * @param {boolean} [emit=true] - Whether to emit the SET_TO_PROPERTY_PATH event.
+   */
+  static setToPropertyPath(path, value, emit = true) {
+    const parts = State.parsePath(path);
+    let current = state;
+    
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      const nextPart = parts[i + 1];
+      
+      if (!Object.prototype.hasOwnProperty.call(current, part) || typeof current[part] !== 'object') {
+        // Determine if next part is an array index (numeric)
+        const isNextPartNumeric = /^\d+$/.test(nextPart);
+        current[part] = isNextPartNumeric ? [] : {};
+      }
+      current = current[part];
+    }
+    
+    if (emit) {
+      events.state.emit(event_names.state.SET_TO_PROPERTY_PATH, { state });
+    }
+
+    current[parts[parts.length - 1]] = value;
+  }
+}
+
+export default State;

package/src/classes/steps/case.js

@@ -0,0 +1,70 @@
+import LogicStep from './logic_step.js';
+import { conditional_step_comparators } from '../../enums/index.js';
+
+/**
+ * Case class representing a single case in a switch statement.
+ * Used in conjunction with SwitchStep to create switch/case logic.
+ * @class Case
+ * @extends LogicStep
+ */
+export default class Case extends LogicStep {
+  static step_name = 'case';
+
+  /**
+   * Creates a new Case instance.
+   * Note: Plain LogicStep instances can be used in place of Case, but they MUST have conditional.subject set.
+   * @param {Object} options - Configuration options.
+   * @param {string} [options.name] - Name of the case.
+   * @param {Object} [options.conditional] - Conditional configuration.
+   * @param {*} [options.conditional.subject=null] - Subject to evaluate (typically set by SwitchStep).
+   * @param {conditional_step_comparators|string} [options.conditional.operator=null] - Comparison operator.
+   * @param {*} [options.conditional.value=null] - Value to compare against.
+   * @param {Function|Step|Workflow} [options.callable=async () => {}] - Function, Step, or Workflow to execute when case matches.
+   * @param {boolean} [options.force_subject_override=false] - Force override of subject even if already set.
+   */
+  constructor({
+    name,
+    conditional = {
+      subject: null,
+      operator: null,
+      value: null,
+    },
+    callable = async () => {},
+    force_subject_override = false,
+  }) {
+    super({
+      name,
+      step_type: Case.step_name,
+      callable,
+    });
+
+    this.conditional = conditional;
+    this.force_subject_override = force_subject_override;
+
+    this.is_matched = false;
+  }
+
+  /**
+   * Sets the switch subject from the parent SwitchStep.
+   * Automatically sets the conditional subject if not already set or if force_subject_override is true.
+   * @param {*} subject - The subject value from the SwitchStep.
+   * @throws {Error} If no subject is provided and conditional.subject is not set.
+   * @throws {Error} If the resulting conditional configuration is invalid.
+   */
+  set switch_subject(subject) {
+    const subjectProvided = subject !== null && subject !== undefined;
+    const hasExistingSubject = this.conditional.subject !== null && this.conditional.subject !== undefined;
+
+    if (!subjectProvided && !hasExistingSubject) {
+      throw new Error(`No subject set for case step: ${this.name}, using default equality check`);
+    }
+
+    if (subjectProvided && (!hasExistingSubject || this.force_subject_override)) {
+      this.conditional.subject = subject;
+    }
+
+    if (!this.conditionalIsValid()) {
+      throw new Error(`Invalid conditional configuration for case step: ${this.name}`);
+    }
+  }
+}

package/src/classes/steps/conditional_step.js

@@ -0,0 +1,90 @@
+import LogicStep from './logic_step.js';
+import { conditional_step_comparators } from '../../enums/index.js';
+
+/**
+ * ConditionalStep class for branching logic based on conditions.
+ * @class ConditionalStep
+ * @extends LogicStep
+ */
+export default class ConditionalStep extends LogicStep {
+  static step_name = 'conditional';
+
+  /**
+   * Creates a new ConditionalStep 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|Step|Workflow} [options.true_callable=async () => {}] - Callable to execute if condition is true.
+   * @param {Function|Step|Workflow} [options.false_callable=async () => {}] - Callable to execute if condition is false.
+   */
+  constructor({
+    name,
+    conditional = {
+      subject: null,
+      operator: null,
+      value: null,
+    },
+    true_callable = async () => {},
+    false_callable = async () => {},
+  }) {
+    super({
+      name,
+      conditional
+    });
+
+    this.true_callable = true_callable;
+    this.false_callable = false_callable;
+
+    this.callable = this.conditional.bind(this);
+  }
+
+  /**
+   * Executes the appropriate branch based on the condition evaluation.
+   * @async
+   * @returns {Promise<*>} The result of the executed branch.
+   */
+  async conditional() {
+    const true_callable = this.true_callable;
+    true_callable.parentWorkflowId = this.parentWorkflowId;
+
+    const false_callable = this.false_callable;
+    false_callable.parentWorkflowId = this.parentWorkflowId;
+
+    let result = null;
+
+    if (this.checkCondition()) {
+      this.log(
+        this.getState('events.step.event_names.CONDITIONAL_TRUE_BRANCH_EXECUTED'),
+        `Condition met for step: ${this.name}, executing true branch`
+      );
+
+      // Normally, the callable is automatically set according to its type
+      // Here, they are set separately, so we need to account for types
+      if (typeof true_callable === 'function') {
+        result = await true_callable();
+      } else {
+        true_callable.parentWorkflowId = this.parentWorkflowId;
+        result = await true_callable.execute();
+      }
+    } else {
+      this.log(
+        this.getState('events.step.event_names.CONDITIONAL_FALSE_BRANCH_EXECUTED'),
+        `Condition not met for step: ${this.name}, executing false branch`
+      );
+
+      // Normally, the callable is automatically set according to its type
+      // Here, they are set separately, so we need to account for types
+      if (typeof false_callable === 'function') {
+        result = await false_callable();
+      } else {
+        false_callable.parentWorkflowId = this.parentWorkflowId;
+        result = await false_callable.execute();
+      }
+    }
+
+    return { message: `Conditional step ${this.name} completed`, result };
+  }
+}

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 a message object 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 this;
+    }
+
+    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<DelayStep>} Resolves with the DelayStep instance 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(this);
+      });
+
+      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 a message object 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 this;
+    }
+
+    const delay_until = addMilliseconds(new Date(), this.relative_delay_ms);
+
+    return this.delay(delay_until);
+  }
+}

package/src/classes/steps/flow_control_step.js

@@ -0,0 +1,70 @@
+import { LogicStep } from './index.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).
+ * @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 {conditional_step_comparators|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.setParentWorkflowValue(this.parentWorkflowId, `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.setParentWorkflowValue(this.parentWorkflowId, `should_${this.flow_control_type}`, false);
+
+      return false;
+    }
+  }
+}

package/src/classes/steps/index.js

@@ -0,0 +1,8 @@
+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 LogicStep } from './logic_step.js';
+export { default as LoopStep } from './loop_step.js';
+export { default as Step } from './step.js';
+export { default as SwitchStep } from './switch_step.js';