@ronaldroe/micro-flow 1.0.0

package/src/classes/base.js

@@ -0,0 +1,143 @@
+import { v4 as uuidv4 } from 'uuid';
+import { base_types } from '../enums/index.js';
+import State from './state.js';
+
+/**
+ * Base class for workflows and steps.
+ * Provides common functionality for timing, status management, logging, and state access.
+ * @class Base
+ */
+export default class Base {
+  /**
+   * Creates a new Base instance.
+   * @param {Object} options - Configuration options.
+   * @param {string} [options.name] - Name of the instance.
+   * @param {string} [options.base_type=base_types.STEP] - Type of the base instance.
+   */
+  constructor({ name, base_type = base_types.STEP }) {
+    this.id = uuidv4();
+    this.name = name ?? `${base_type}-${this.id}`;
+
+    this.base_type = base_type;
+    this.timing = {
+      cancel_time: null,
+      complete_time: null,
+      end_time: null,
+      execution_time_ms: null,
+      start_time: null,
+    }
+  }
+
+  /**
+   * Executes the instance. Must be overridden by subclasses.
+   * @async
+   * @throws {Error} Throws if not implemented in subclass.
+   */
+  async execute() {
+    throw new Error('Execute method not implemented');
+  }
+
+  /**
+   * Logs an event and emits it to the appropriate event emitter.
+   * @param {string} event_name - Name of the event to log.
+   * @param {string} [message=null] - Optional message to log.
+   * @throws {Error} Throws if event name is invalid or event emitter not found.
+   */
+  log(event_name, message = null) {
+    if (!event_name || !State.get(`events.${this.base_type}`)) {
+      throw new Error('Invalid event name or event emitter not found');
+    }
+
+    State.get(`events.${this.base_type}`).emit(event_name, this);
+    if (State.get('log_suppress')) {
+      return;
+    }
+
+    const logMessage = message ? `\n[${this.base_type.toUpperCase()} - ${this.name}] ${message}` : `\n[${this.base_type.toUpperCase()} - ${this.name}] Event: ${event_name}`;
+    const logType = event_name.endsWith('_FAILED') ? 'error' : 'log';
+
+    console[logType](logMessage);
+  }
+
+  /**
+   * Marks the instance as complete and calculates execution time.
+   */
+  markAsComplete() {
+    this.timing.complete_time = new Date();
+    this.status = State.get('statuses')[this.base_type].COMPLETE;
+    this.timing.execution_time_ms = this.timing.complete_time - this.timing.start_time;
+
+    if (this.steps_by_id) {
+      delete this.steps_by_id;
+    }
+
+    this.log(
+      State.get(`event_names.${this.base_type}`)[`${this.base_type.toUpperCase()}_COMPLETE`],
+      `${this.base_type.charAt(0).toUpperCase() + this.base_type.slice(1)} "${this.name}" complete.`
+    );
+  }
+
+  /**
+   * Marks the instance as failed and calculates execution time.
+   */
+  markAsFailed() {
+    this.timing.complete_time = new Date();
+    this.status = State.get('statuses')[this.base_type].FAILED;
+    this.timing.execution_time_ms = this.timing.complete_time - this.timing.start_time;
+
+    this.log(
+      State.get(`event_names.${this.base_type}`)[`${this.base_type.toUpperCase()}_FAILED`],
+      `${this.base_type.charAt(0).toUpperCase() + this.base_type.slice(1)} "${this.name}" failed.`
+    );
+  }
+
+  /**
+   * Marks the instance as waiting. To be implemented by subclasses.
+   */
+  markAsWaiting() { }
+
+  /**
+   * Marks the instance as pending. To be implemented by subclasses.
+   */
+  markAsPending() { }
+
+  /**
+   * Marks the instance as running and sets the start time.
+   */
+  markAsRunning() {
+    this.timing.start_time = new Date();
+    this.status = State.get('statuses')[this.base_type].RUNNING;
+
+    this.log(
+      State.get(`event_names.${this.base_type}`)[`${this.base_type.toUpperCase()}_RUNNING`],
+      `${this.base_type.charAt(0).toUpperCase() + this.base_type.slice(1)} "${this.name}" started.`
+    );
+  }
+
+  // State management methods
+  /**
+   * Gets a value from the global state.
+   * @param {string} path - Path to the state property.
+   * @returns {*} The state value at the specified path.
+   */
+  getState(path) {
+    return State.get(path);
+  }
+
+  /**
+   * Sets a value in the global state.
+   * @param {string} path - Path to the state property.
+   * @param {*} value - Value to set.
+   */
+  setState(path, value) {
+    State.set(path, value);
+  }
+
+  /**
+   * Deletes a property from the global state.
+   * @param {string} path - Path to the state property to delete.
+   */
+  deleteState(path) {
+    State.delete(path);
+  }
+}

package/src/classes/events/broadcast.js

@@ -0,0 +1,57 @@
+/**
+ * Broadcast class provides a simplified wrapper around the BroadcastChannel API
+ * for cross-context communication (e.g., between tabs, windows, workers).
+ * 
+ * This class allows you to send and receive messages across different browsing contexts
+ * that share the same origin. It encapsulates the creation and management of a BroadcastChannel,
+ * providing a simplified API for sending and receiving messages.
+ * 
+ * @class Broadcast
+ * @extends BroadcastChannel
+ */
+export default class Broadcast extends BroadcastChannel {
+  /**
+   * Creates a new Broadcast instance for a named channel.
+   * 
+   * @constructor
+   * @param {string} channelName - The name of the broadcast channel to create or connect to.
+   * Multiple Broadcast instances with the same channel name can communicate with each other.
+   */
+  constructor(channelName) {
+    super(channelName);
+  }
+
+  /**
+   * Sends data to all other contexts listening on this channel.
+   * 
+   * @param {*} data - The data to broadcast. Can be any structured-cloneable value
+   * (primitives, objects, arrays, etc.). Functions and DOM nodes cannot be sent.
+   * @returns {void}
+   */
+  send(data) {
+    this.postMessage(data);
+  }
+
+  /**
+   * Registers a callback to handle incoming messages on this channel.
+   * 
+   * @param {Function} callback - Function to call when a message is received.
+   * Receives the message data as its only parameter.
+   * @returns {void}
+   */
+  onReceive(callback) {
+    this.onmessage = (event) => {
+      callback(event.data);
+    };
+  }
+
+  /**
+   * Closes the broadcast channel and releases its resources.
+   * After calling this method, the Broadcast instance can no longer send or receive messages.
+   * 
+   * @returns {void}
+   */
+  destroy() {
+    this.close();
+  }
+}

package/src/classes/events/event.js

@@ -0,0 +1,144 @@
+import { errors, warnings } from '../../enums/index.js';
+import Broadcast from './broadcast.js';
+
+/**
+ * Event class for micro-flow
+ * Provides a simple event emitter implementation for workflow steps and state changes.
+ *
+ * This class is used for emitting and listening to events within workflows and steps.
+ * For broadcasting events across multiple workflows or listeners, see the Broadcast class.
+ */
+class Event extends EventTarget {
+  /**
+   * Creates a new Event instance.
+   * @constructor
+   */
+  constructor() {
+    super();
+    this.events = {};
+    this._listener_map = new Map();
+  }
+
+  /**
+   * Registers multiple events by creating Event instances for each event name.
+   * @param {Object} event_names - An object containing event name constants.
+   * @returns {void}
+   */
+  registerEvents(event_names) {
+    for (const event_name of Object.values(event_names)) {
+      this.events[event_name] = new Event();
+    }
+  }
+
+  /**
+   * Emits a custom event with optional data payload.
+   * This method maintains API compatibility with EventEmitter while using CustomEvent.
+   * @param {string} event_name - The name of the event to emit.
+   * @param {*} [data] - Optional data to pass with the event in the detail property.
+   * @param {boolean} [bubbles=false] - Whether the event should bubble up through the DOM.
+   * @param {boolean} [cancelable=true] - Whether the event is cancelable.
+   * @returns {boolean} True if the event was not cancelled, false if it was cancelled.
+   */
+  emit(event_name, data, bubbles = false, cancelable = true) {
+    const workingData = JSON.parse(JSON.stringify(data));
+
+    const custom_event = new CustomEvent(event_name, {
+      detail: workingData,
+      bubbles,
+      cancelable
+    });
+    const result = this.dispatchEvent(custom_event);
+
+    try {
+      const channel = new Broadcast(event_name);
+      channel.send(workingData);
+      channel.destroy();
+    } catch (e) {
+      console.warn(warnings.BROADCAST_FAILED, e);
+    }
+    return result;
+  }
+
+  /**
+   * Listen for broadcasts on a given event name (channel).
+   * @param {string} event_name - The event name/channel to listen for.
+   * @param {Function} listener - Callback for broadcasted data.
+   * @returns {Broadcast} Returns the Broadcast instance for manual control.
+   */
+  onBroadcast(event_name, listener) {
+    const channel = new Broadcast(event_name);
+    channel.onReceive(listener);
+    return channel;
+  }
+
+  /**
+   * Listen for both local and broadcast events.
+   * @param {string} event_name - The event name/channel to listen for.
+   * @param {Function} listener - Callback for event data.
+   * @returns {Object} Returns { event: this, broadcast: Broadcast instance }
+   */
+  onAny(event_name, listener) {
+    this.on(event_name, listener);
+    const broadcast = this.onBroadcast(event_name, listener);
+    return { event: this, broadcast };
+  }
+
+  /**
+   * Adds an event listener with EventEmitter-style API.
+   * Maintains compatibility with the original API while using addEventListener.
+   * @param {string} event_name - The name of the event to listen for.
+   * @param {Function} listener - The callback function to execute when the event fires.
+   * @returns {Event} Returns this for chaining.
+   */
+  on(event_name, listener) {
+    const wrapped_listener = (event) => {
+      // Call the listener with the detail (data) from CustomEvent
+      listener(event.detail);
+    };
+    // Store the original listener reference for removeListener
+    this._listener_map.set(listener, wrapped_listener);
+    this.addEventListener(event_name, wrapped_listener);
+    return this;
+  }
+
+  /**
+   * Adds a one-time event listener with EventEmitter-style API.
+   * @param {string} event_name - The name of the event to listen for.
+   * @param {Function} listener - The callback function to execute when the event fires.
+   * @returns {Event} Returns this for chaining.
+   */
+  once(event_name, listener) {
+    const wrapped_listener = (event) => {
+      listener(event.detail);
+    };
+    this.addEventListener(event_name, wrapped_listener, { once: true });
+    return this;
+  }
+
+  /**
+   * Removes an event listener with EventEmitter-style API.
+   * @param {string} event_name - The name of the event.
+   * @param {Function} listener - The callback function to remove.
+   * @returns {Event} Returns this for chaining.
+   */
+  off(event_name, listener) {
+    if (this._listener_map && this._listener_map.has(listener)) {
+      const wrapped_listener = this._listener_map.get(listener);
+      this.removeEventListener(event_name, wrapped_listener);
+      this._listener_map.delete(listener);
+    }
+    return this;
+  }
+
+  /**
+   * Alias for off() to maintain EventEmitter API compatibility.
+   * @param {string} event_name - The name of the event.
+   * @param {Function} listener - The callback function to remove.
+   * @returns {Event} Returns this for chaining.
+   */
+  removeListener(event_name, listener) {
+    return this.off(event_name, listener);
+  }
+}
+
+export default Event;

package/src/classes/events/index.js

@@ -0,0 +1,4 @@
+export { default as Broadcast } from './broadcast.js';
+export { default as Event } from './event.js';
+export { default as StepEvent } from './step_event.js';
+export { default as WorkflowEvent } from './workflow_event.js';

package/src/classes/events/step_event.js

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

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,197 @@
+import { errors, warnings } from '../enums/errors.js';
+import { StepEvent, WorkflowEvent } from './events/index.js';
+import {
+  base_types,
+  conditional_step_comparators,
+  step_event_names,
+  step_statuses,
+  step_types,
+  sub_step_types,
+  workflow_event_names,
+  workflow_statuses,
+} from '../enums/index.js';
+
+let state = {
+  messages: {
+    errors,
+    warnings,
+  },
+  statuses: {
+    workflow: workflow_statuses,
+    step: step_statuses
+  },
+  event_names: {
+    workflow: workflow_event_names,
+    step: step_event_names
+  },
+  events: {
+    workflow: new WorkflowEvent(),
+    step: new StepEvent()
+  },
+  types: {
+    base_types,
+    step_types,
+    sub_step_types,
+  },
+  workflows: {},
+  conditional_step_comparators
+}
+
+/**
+ * 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 = this.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]];
+  }
+
+  /**
+   * 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
+   * - "*" or "": Returns entire state object
+   * @param {*} [defaultValue=null] - Default value to return if the path doesn't exist.
+   * @returns {*} The value of the state property, or defaultValue if not found. null if not found
+   * and no defaultValue provided.
+   */
+  static get(path, defaultValue = null) {
+    if (!path || ['*', ''].includes(path)) {
+      return state;
+    }
+
+    return this.getFromPropertyPath(path) ?? defaultValue;
+  }
+
+  /**
+   * Gets the entire state object.
+   * @returns {Object} The entire state object.
+   */
+  static getState() {
+    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);
+    }
+
+    this.setToPropertyPath(path, value);
+  }
+
+  /**
+   * Merges an object into the current State.
+   * @param {Object} newState - The object to merge into the current State.
+   * @returns {void}
+   */
+  static merge(newState) {
+    state = { ...state, ...newState };
+  }
+
+  /**
+   * 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, ''));
+  }
+
+  /**
+   * 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']").
+   * @returns {*} The value at the specified path, or undefined if not found.
+   */
+  static getFromPropertyPath(path) {
+    const parts = this.parsePath(path);
+    let current = state;
+
+    for (const part of parts) {
+      if (current && Object.prototype.hasOwnProperty.call(current, part)) {
+        current = current[part];
+      } else {
+        return undefined;
+      }
+    }
+
+    return current;
+  }
+
+  /**
+   * 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.
+   */
+  static setToPropertyPath(path, value) {
+    const parts = this.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];
+    }
+
+    current[parts[parts.length - 1]] = value;
+  }
+}
+
+export default State;

package/src/classes/steps/conditional_step.js

@@ -0,0 +1,80 @@
+import { LogicStep } from './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 {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;
+    const false_callable = this.false_callable;
+
+    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`
+      );
+
+      if (typeof true_callable === 'function') {
+        result = await true_callable();
+      } else {
+        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`
+      );
+
+      if (typeof false_callable === 'function') {
+        result = await false_callable();
+      } else {
+        result = await false_callable.execute();
+      }
+    }
+
+    return result;
+  }
+}