@ronaldroe/micro-flow 1.3.8 → 2.0.0

package/src/classes/steps/conditional_step.js

@@ -1,3 +1,4 @@
+import Step from './step.js';
 import LogicStep from './logic_step.js';
 import { conditional_step_comparators } from '../../enums/index.js';
 
@@ -19,6 +20,8 @@ export default class ConditionalStep extends LogicStep {
    * @param {*|Function} [options.conditional.value] - Value to compare against. Can be a function that returns the value.
    * @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.
+   * @param {string|null} [options.true_callable_registry_key=null] - Optional key to reference true_callable to be rehydrated after serialization.
+   * @param {string|null} [options.false_callable_registry_key=null] - Optional key to reference false_callable to be rehydrated after serialization.
    */
   constructor({
     name,
@@ -29,12 +32,23 @@ export default class ConditionalStep extends LogicStep {
     },
     true_callable = async () => {},
     false_callable = async () => {},
+    true_callable_registry_key = null,
+    false_callable_registry_key = null,
   }) {
     super({
       name,
       conditional
     });
 
+    // Optional keys to reference true_callable/false_callable to be rehydrated after serialization.
+    this.true_callable_registry_key = true_callable_registry_key;
+    this.false_callable_registry_key = false_callable_registry_key;
+
+    // Keep the raw (unbound) originals for serialization - binding renames a function
+    // (e.g. "falseBranch" -> "bound falseBranch"), which would break registry lookups on hydrate.
+    this._true_callable_raw = true_callable;
+    this._false_callable_raw = false_callable;
+
     // Bind function callables to this step instance for state access
     if (typeof true_callable === 'function') {
       this.true_callable = true_callable.bind(this);
@@ -52,7 +66,11 @@ export default class ConditionalStep extends LogicStep {
   }
 
   /**
-   * Executes the appropriate branch based on the condition evaluation.
+   * Executes the appropriate branch based on the condition evaluation. When the executed branch
+   * is a `Step`/`Workflow` (not a plain function), it is stamped with this step's own
+   * `parent_workflow_id`/`use_state_singleton`/`state` first - true/false_callable are never
+   * added to the parent workflow via `addStep()`, so this is the only way they end up sharing
+   * its state instead of their own, independent one.
    * @async
    * @returns {Promise<*>} The result of the executed branch.
    */
@@ -71,7 +89,9 @@ export default class ConditionalStep extends LogicStep {
       if (typeof true_callable === 'function') {
         result = await true_callable();
       } else {
-        true_callable.parentWorkflowId = this.parentWorkflowId;
+        true_callable.parent_workflow_id = this.parent_workflow_id;
+        true_callable.use_state_singleton = this.use_state_singleton;
+        true_callable.state = this.state;
         result = await true_callable.execute();
       }
     } else {
@@ -83,11 +103,57 @@ export default class ConditionalStep extends LogicStep {
       if (typeof false_callable === 'function') {
         result = await false_callable();
       } else {
-        false_callable.parentWorkflowId = this.parentWorkflowId;
+        false_callable.parent_workflow_id = this.parent_workflow_id;
+        false_callable.use_state_singleton = this.use_state_singleton;
+        false_callable.state = this.state;
         result = await false_callable.execute();
       }
     }
 
     return { message: `Conditional step ${this.name} completed`, result };
   }
+
+  /**
+   * 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 `conditional` method) -
+      // ConditionalStep's constructor doesn't take a callable, so it isn't real data to persist.
+      callable: null,
+      true_callable: this.true_callable_registry_key
+        ? { type: Step.callable_types.FUNCTION, value: this.true_callable_registry_key }
+        : Step.serializeCallableField(this._true_callable_raw),
+      false_callable: this.false_callable_registry_key
+        ? { type: Step.callable_types.FUNCTION, value: this.false_callable_registry_key }
+        : Step.serializeCallableField(this._false_callable_raw),
+    };
+  }
+
+  /**
+   * Hydrates a parsed step object into a ConditionalStep instance, resolving the true/false branch callables.
+   * @param {Object} parsed_step - The parsed step object.
+   * @param {import('../callable_registry.js').default|null} [callable_registry] - Registry used to resolve function callables.
+   * @returns {ConditionalStep} The hydrated ConditionalStep instance.
+   */
+  static hydrate(parsed_step, callable_registry = null) {
+    const true_descriptor = parsed_step.true_callable;
+    const false_descriptor = parsed_step.false_callable;
+
+    return super.hydrate({
+      ...parsed_step,
+      true_callable: Step.hydrateCallableField(true_descriptor, callable_registry),
+      false_callable: Step.hydrateCallableField(false_descriptor, callable_registry),
+      true_callable_registry_key: true_descriptor?.type === Step.callable_types.FUNCTION
+        ? true_descriptor.value
+        : null,
+      false_callable_registry_key: false_descriptor?.type === Step.callable_types.FUNCTION
+        ? false_descriptor.value
+        : null,
+    }, callable_registry);
+  }
 }
+
+ConditionalStep.registerStepClass(ConditionalStep);

package/src/classes/steps/delay_step.js

@@ -100,4 +100,22 @@ export default class DelayStep extends Step {
 
     return this.delay(delay_until);
   }
+
+  /**
+   * 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 absolute/relative method) -
+      // DelayStep's constructor doesn't take a callable, so it isn't real data to persist.
+      callable: null,
+      delay_type: this.delay_type,
+      absolute_timestamp: this.absolute_timestamp,
+      relative_delay_ms: this.relative_delay_ms,
+    };
+  }
 }
+
+DelayStep.registerStepClass(DelayStep);

package/src/classes/steps/flow_control_step.js

@@ -54,7 +54,7 @@ export default class FlowControlStep extends LogicStep {
         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);
+      this.setParentWorkflowValue(this.parent_workflow_id, `should_${this.flow_control_type}`, true);
 
       return true;
     } else {
@@ -62,9 +62,25 @@ export default class FlowControlStep extends LogicStep {
         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);
+      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,16 +47,16 @@ 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 === this.getState('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'):
@@ -108,8 +111,8 @@ export default class LogicStep extends Step {
         if (typeof value !== 'string') {
           throw new Error(`Regex input must be a string.`);
         }
-        const notMatchRegex = new RegExp(value);
-        return !notMatchRegex.test(subject);
+        const not_match_regex = new RegExp(value);
+        return !not_match_regex.test(subject);
       case this.getState('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'):
@@ -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);