@ronaldroe/micro-flow 1.3.9 → 3.0.0

package/src/classes/steps/flow_control_step.js

@@ -1,6 +1,7 @@
 import LogicStep from './logic_step.js';
 import flow_control_types from '../../enums/flow_control_types.js';
 import { conditional_step_comparators } from '../../enums/index.js';
+import { event_names } from '../instance_state.js';
 
 /**
  * FlowControlStep class for controlling workflow execution flow (break or skip).
@@ -51,20 +52,36 @@ export default class FlowControlStep extends LogicStep {
   async shouldFlowControl() {
     if (this.checkCondition()) {
       this.log(
-        this.getState('events.step.event_names.CONDITIONAL_TRUE_BRANCH_EXECUTED'),
+        event_names.step.CONDITIONAL_TRUE_BRANCH_EXECUTED,
         `Break condition met for step: ${this.name}`
       );
-      this.setParentWorkflowValue(this.parentWorkflowId, `should_${this.flow_control_type}`, true);
+      this.setParentWorkflowValue(this.parent_workflow_id, `should_${this.flow_control_type}`, true);
 
       return true;
     } else {
       this.log(
-        this.getState('events.step.event_names.CONDITIONAL_FALSE_BRANCH_EXECUTED'),
+        event_names.step.CONDITIONAL_FALSE_BRANCH_EXECUTED,
         `Break condition not met for step: ${this.name}`
       );
-      this.setParentWorkflowValue(this.parentWorkflowId, `should_${this.flow_control_type}`, false);
+      this.setParentWorkflowValue(this.parent_workflow_id, `should_${this.flow_control_type}`, false);
 
       return false;
     }
   }
+
+  /**
+   * Inserts safely serializable properties of the step into a new object for serialization.
+   * @returns {Object} An object containing the step's properties ready for serialization.
+   */
+  prepareForSerialization() {
+    return {
+      ...super.prepareForSerialization(),
+      // The base `callable` is an internal wiring detail (the bound `shouldFlowControl` method) -
+      // FlowControlStep's constructor doesn't take a callable, so it isn't real data to persist.
+      callable: null,
+      flow_control_type: this.flow_control_type,
+    };
+  }
 }
+
+FlowControlStep.registerStepClass(FlowControlStep);

package/src/classes/steps/logic_step.js

@@ -18,10 +18,12 @@ export default class LogicStep extends Step {
    * @param {conditional_step_comparators|string} [options.conditional.operator] - Comparison operator.
    * @param {*|Function, optional} [options.conditional.value] - Value to compare against. Can be a function that returns the value.
    * @param {Function} [options.callable=async () => {}] - Function to execute.
+   * @param {string|null} [options.callable_registry_key=null] - Optional key to reference the callable to be rehydrated after serialization.
    */
   constructor({
     name,
     callable = async () => {},
+    callable_registry_key = null,
     conditional = {
       operator: null,
       subject: null,
@@ -31,7 +33,8 @@ export default class LogicStep extends Step {
     super({
       name,
       step_type: step_types.LOGIC,
-      callable
+      callable,
+      callable_registry_key,
     });
 
     this.setConditional(conditional);
@@ -44,85 +47,85 @@ export default class LogicStep extends Step {
    * @throws {Error} Throws if operator is unknown.
    */
   checkCondition() {
-    const rawSubject = this.conditional_config.subject;
-    const rawValue = this.conditional_config.value;
+    const raw_subject = this.conditional_config.subject;
+    const raw_value = this.conditional_config.value;
     const operator = this.conditional_config.operator;
     
     // Resolve subject - call it if it's a function
-    const subject = typeof rawSubject === 'function' ? rawSubject() : rawSubject;
+    const subject = typeof raw_subject === 'function' ? raw_subject() : raw_subject;
     
     // Don't resolve value for CUSTOM_FUNCTION - the value IS the function to call
-    const isCustomFunction = operator === this.getState('conditional_step_comparators.CUSTOM_FUNCTION');
-    const value = (!isCustomFunction && typeof rawValue === 'function') ? rawValue() : rawValue;
+    const is_custom_function = operator === conditional_step_comparators.CUSTOM_FUNCTION;
+    const value = (!is_custom_function && typeof raw_value === 'function') ? raw_value() : raw_value;
 
     switch (operator) {
-      case this.getState('conditional_step_comparators.STRICT_EQUALS'):
-      case this.getState('conditional_step_comparators.SIGN_STRICT_EQUALS'):
+      case conditional_step_comparators.STRICT_EQUALS:
+      case conditional_step_comparators.SIGN_STRICT_EQUALS:
         return subject === value;
-      case this.getState('conditional_step_comparators.SIGN_EQUALS'):
-      case this.getState('conditional_step_comparators.EQUALS'):
+      case conditional_step_comparators.SIGN_EQUALS:
+      case conditional_step_comparators.EQUALS:
         return subject == value;
-      case this.getState('conditional_step_comparators.NOT_EQUALS'):
-      case this.getState('conditional_step_comparators.SIGN_NOT_EQUALS'):
+      case conditional_step_comparators.NOT_EQUALS:
+      case 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'):
+      case conditional_step_comparators.STRICT_NOT_EQUALS:
+      case 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'):
+      case conditional_step_comparators.GREATER_THAN:
+      case 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'):
+      case conditional_step_comparators.LESS_THAN:
+      case 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'):
+      case conditional_step_comparators.GREATER_THAN_OR_EQUAL:
+      case 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'):
+      case conditional_step_comparators.LESS_THAN_OR_EQUAL:
+      case 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 conditional_step_comparators.STRING_CONTAINS:
+      case conditional_step_comparators.STRING_INCLUDES:
+      case conditional_step_comparators.ARRAY_CONTAINS:
+      case conditional_step_comparators.ARRAY_INCLUDES:
         return (Array.isArray(subject) || typeof subject === 'string') && subject.includes(value);
-      case this.getState('conditional_step_comparators.IN'):
+      case conditional_step_comparators.IN:
         return (Array.isArray(value) || typeof value === 'string') && value.includes(subject);
-      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 conditional_step_comparators.STRING_NOT_CONTAINS:
+      case conditional_step_comparators.STRING_NOT_INCLUDES:
+      case conditional_step_comparators.ARRAY_NOT_CONTAINS:
+      case conditional_step_comparators.ARRAY_NOT_INCLUDES:
         return (Array.isArray(subject) || typeof subject === 'string') && !subject.includes(value);
-      case this.getState('conditional_step_comparators.NOT_IN'):
+      case conditional_step_comparators.NOT_IN:
         return (Array.isArray(value) || typeof value === 'string') && !value.includes(subject);
-      case this.getState('conditional_step_comparators.EMPTY'):
+      case conditional_step_comparators.EMPTY:
         return subject === '' || subject === null || subject === undefined || subject.length === 0;
-      case this.getState('conditional_step_comparators.NOT_EMPTY'):
+      case conditional_step_comparators.NOT_EMPTY:
         return subject !== '' && subject !== null && subject !== undefined && subject.length > 0;
-      case this.getState('conditional_step_comparators.REGEX_MATCH'):
+      case 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'):
+      case 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'):
+        const not_match_regex = new RegExp(value);
+        return !not_match_regex.test(subject);
+      case 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'):
+      case conditional_step_comparators.STRING_ENDS_WITH:
         return typeof subject === 'string' && typeof value === 'string' && subject.endsWith(value);
-      case this.getState('conditional_step_comparators.NULLISH'):
+      case conditional_step_comparators.NULLISH:
         return subject === null || subject === undefined;
-      case this.getState('conditional_step_comparators.NOT_NULLISH'):
+      case conditional_step_comparators.NOT_NULLISH:
         return subject !== null && subject !== undefined;
-      case this.getState('conditional_step_comparators.IS_TYPE'):
+      case conditional_step_comparators.IS_TYPE:
         return typeof subject === value;
-      case this.getState('conditional_step_comparators.IS_NOT_TYPE'):
+      case conditional_step_comparators.IS_NOT_TYPE:
         return typeof subject !== value;
-      case this.getState('conditional_step_comparators.CUSTOM_FUNCTION'):
+      case conditional_step_comparators.CUSTOM_FUNCTION:
         if (typeof value !== 'function') {
           throw new Error(`Invalid custom function: ${value}`);
         }
@@ -157,4 +160,19 @@ export default class LogicStep extends Step {
   setConditional(conditional) {
     this.conditional_config = { subject: conditional.subject, operator: conditional.operator, value: conditional.value };
   }
+
+  /**
+   * Inserts safely serializable properties of the step into a new object for serialization.
+   * Note: function-valued subject/value are not persisted - there's no registry for them,
+   * only the plain-callable field supports registry-based rehydration.
+   * @returns {Object} An object containing the step's properties ready for serialization.
+   */
+  prepareForSerialization() {
+    return {
+      ...super.prepareForSerialization(),
+      conditional: { ...this.conditional_config },
+    };
+  }
 }
+
+LogicStep.registerStepClass(LogicStep);

package/src/classes/steps/loop_step.js

@@ -1,4 +1,5 @@
 import { loop_types, step_types } from '../../enums/index.js';
+import Step from './step.js';
 import LogicStep from './logic_step.js';
 import { conditional_step_comparators } from '../../enums/index.js';
 
@@ -23,6 +24,7 @@ export default class LoopStep extends LogicStep {
    * @param {string} [options.loop_type=loop_types.FOR_EACH] - Type of loop ('for', 'for_each', 'while', or 'generator').
    * @param {number} [options.iterations=0] - Number of iterations to execute. Only used for 'for' loops.
    * @param {number} [options.max_iterations=1000] - Maximum number of iterations to prevent infinite loops.
+   * @param {string|null} [options.loop_callable_registry_key=null] - Optional key to reference the per-iteration callable to be rehydrated after serialization.
    */
   constructor({
     name,
@@ -36,6 +38,7 @@ export default class LoopStep extends LogicStep {
     loop_type = loop_types.FOR_EACH,
     iterations = 0,
     max_iterations = 1000,
+    loop_callable_registry_key = null,
   }) {
     super({ name, conditional });
     this.iterable = iterable;
@@ -45,16 +48,38 @@ export default class LoopStep extends LogicStep {
     this.results = [];
     this.current_item = null;
 
+    // Optional key to reference the per-iteration callable to be rehydrated after serialization.
+    this.loop_callable_registry_key = loop_callable_registry_key;
+
     // Store the user's callable separately so loop methods can invoke it.
     // this._callable will be set to the loop method by the setter below.
-    const userCallableType = this.getCallableType(callable);
-    this._loop_callable = userCallableType === 'function'
+    // The raw object is kept too (distinct from the bound version) so serialization
+    // can recover the original function/Step/Workflow instead of the loop-runner method.
+    this._loop_callable_type = this.getCallableType(callable);
+    this._loop_callable_object = callable;
+    this._loop_callable = this._loop_callable_type === 'function'
       ? callable.bind(this)
       : callable.execute.bind(callable);
 
     this.callable = this[`${loop_type}_loop`].bind(this);
   }
 
+  /**
+   * When the per-iteration callable is a `Step`/`Workflow` (not a plain function), stamps it with
+   * this loop step's own `parent_workflow_id`/`use_state_singleton`/`state` right before the loop
+   * runs - mirrors what `Workflow.addStep()` does for top-level steps, since a loop callable is
+   * never added to the workflow directly.
+   */
+  propagateStateToLoopCallable() {
+    if (this._loop_callable_type === 'function') {
+      return;
+    }
+
+    this._loop_callable_object.parent_workflow_id = this.parent_workflow_id;
+    this._loop_callable_object.use_state_singleton = this.use_state_singleton;
+    this._loop_callable_object.state = this.state;
+  }
+
   /**
    * Executes a generator/async generator and appends yielded values to results.
    * @throws {Error} If the callable is not a generator or async generator function.
@@ -65,6 +90,8 @@ export default class LoopStep extends LogicStep {
       throw new Error('Iterable must be a generator function for generator loops');
     }
 
+    this.propagateStateToLoopCallable();
+
     let iterations = 0;
     // Use for await...of to handle both sync and async generators
     for await (const item of this._loop_callable()) {
@@ -75,6 +102,8 @@ export default class LoopStep extends LogicStep {
       }
     }
 
+    this.iterations = iterations;
+
     return {
       message: `Generator loop ${this.name} completed after ${iterations} iterations`,
       result: this.results
@@ -86,11 +115,16 @@ export default class LoopStep extends LogicStep {
    * @returns {Object} - An object containing a message and the results of the loop.
    */
   async for_loop() {
+    this.propagateStateToLoopCallable();
+
+    const target = this.iterations;
     let i = 0;
-    for (; i < this.iterations; i++) {
+    for (; i < target; i++) {
       this.results.push(await this._loop_callable());
     }
 
+    this.iterations = i;
+
     return {
       message: `For loop ${this.name} completed after ${i} iterations`,
       result: this.results
@@ -107,6 +141,8 @@ export default class LoopStep extends LogicStep {
       throw new Error('Iterable is required for for_each loops');
     }
 
+    this.propagateStateToLoopCallable();
+
     if (typeof this.iterable === 'function') {
       this.iterable = this.iterable();
     }
@@ -118,6 +154,8 @@ export default class LoopStep extends LogicStep {
       this.results.push(await this._loop_callable());
     }
 
+    this.iterations = iterations;
+
     return {
       message: `For each loop ${this.name} completed after ${iterations} iterations`,
       result: this.results
@@ -134,15 +172,62 @@ export default class LoopStep extends LogicStep {
       throw new Error('Valid conditional is required for while loops');
     }
 
+    this.propagateStateToLoopCallable();
+
     let iterations = 0;
     while (this.checkCondition() && iterations < this.max_iterations) {
       iterations++;
       this.results.push(await this._loop_callable());
     }
 
+    this.iterations = iterations;
+
     return {
       message: `While loop ${this.name} completed after ${iterations} iterations`,
       result: this.results
     };
   }
+
+  /**
+   * Inserts safely serializable properties of the step into a new object for serialization.
+   * Note: a function-valued `iterable` is not persisted, since there's no registry for it.
+   * @returns {Object} An object containing the step's properties ready for serialization.
+   */
+  prepareForSerialization() {
+    return {
+      ...super.prepareForSerialization(),
+      callable: this.loop_callable_registry_key
+        ? { type: Step.callable_types.FUNCTION, value: this.loop_callable_registry_key }
+        : Step.serializeCallableField(this._loop_callable_object),
+      loop_type: this.loop_type,
+      iterations: this.iterations,
+      max_iterations: this.max_iterations,
+      iterable: Array.isArray(this.iterable) ? this.iterable : null,
+      results: this.results,
+    };
+  }
+
+  /**
+   * Hydrates a parsed step object into a LoopStep instance, resolving the per-iteration callable.
+   * @param {Object} parsed_step - The parsed step object.
+   * @param {import('../callable_registry.js').default|null} [callable_registry] - Registry used to resolve function callables.
+   * @returns {LoopStep} The hydrated LoopStep instance.
+   */
+  static hydrate(parsed_step, callable_registry = null) {
+    const callable_descriptor = parsed_step.callable;
+
+    const instance = super.hydrate({
+      ...parsed_step,
+      callable: Step.hydrateCallableField(callable_descriptor, callable_registry),
+      loop_callable_registry_key: callable_descriptor?.type === Step.callable_types.FUNCTION
+        ? callable_descriptor.value
+        : null,
+    }, callable_registry);
+
+    instance.results = parsed_step.results ?? [];
+
+    return instance;
+  }
 }
+
+LoopStep.registerStepClass(LoopStep);