@ronaldroe/micro-flow 1.3.9 → 3.0.0

package/src/classes/steps/step.js

@@ -2,6 +2,11 @@ import Base from '../base.js';
 import Workflow from '../workflow.js';
 import { base_types, step_types } from '../../enums/index.js';
 
+// Populated by each Step subclass file registering itself (see the bottom of
+// step.js and each subclass file) - keeps this file from importing every
+// subclass directly, which would create an import cycle through the hierarchy.
+const step_class_registry = {};
+
 /**
  * Step class representing an executable unit within a workflow.
  * @class Step
@@ -10,6 +15,11 @@ import { base_types, step_types } from '../../enums/index.js';
 export default class Step extends Base {
   static step_name = 'step';
   #callable_object = null;
+  static callable_types = {
+    FUNCTION: 'function',
+    STEP: 'step',
+    WORKFLOW: 'workflow',
+  }
 
   /**
    * Creates a new Step instance.
@@ -24,6 +34,7 @@ export default class Step extends Base {
   constructor({
     name,
     callable = async () => {},
+    callable_registry_key = null,
     max_retries = 0,
     max_timeout_ms = 30000,
     step_type = step_types.ACTION,
@@ -33,6 +44,9 @@ export default class Step extends Base {
 
     this.callable = callable;
 
+    // Optional key to reference the callable to be rehydrated after serialization.
+    this.callable_registry_key = callable_registry_key;
+
     // Store off the original callable object, because if it's a Step or Workflow,
     // this.callable is set to the execute method of that object, but we may need to access its properties later.
     this.#callable_object = callable;
@@ -55,9 +69,13 @@ export default class Step extends Base {
    * @returns {Promise<Step>} The step instance with execution results.
    */
   async execute() {
-    if (!this.timeout ) {
+    if (!this.timeout) {
       this.timeout = new Promise((_, reject) =>
-        setTimeout(reject, this.max_timeout_ms, new Error(`Step "${this.name}" timed out after ${this.max_timeout_ms}ms`))
+        setTimeout(
+          reject,
+          this.max_timeout_ms,
+          new Error(`Step "${this.name}" timed out after ${this.max_timeout_ms}ms`)
+        )
       );
     }
 
@@ -81,12 +99,11 @@ export default class Step extends Base {
           throw error;
         }
       }
-
     }
 
-    const { FAILED, COMPLETE } = this.getState('statuses')[this.base_type];
+    const { FAILED, COMPLETE } = Workflow.statuses[this.base_type];
 
-    if (! [FAILED, COMPLETE].includes(this.status)) {
+    if (![FAILED, COMPLETE].includes(this.status)) {
       this.markAsComplete();
     }
 
@@ -94,7 +111,7 @@ export default class Step extends Base {
       return this.#callable_object;
     }
 
-    return this;
+    return this.prepareForSerialization();
   }
 
   /**
@@ -104,32 +121,185 @@ export default class Step extends Base {
    * @throws {Error} Throws if callable type is invalid.
    */
   getCallableType(callable) {
+    return Step.getCallableType(callable);
+  }
+
+  /**
+   * Determines the type of the callable (function, step, or workflow).
+   * @param {Function|Step|Workflow} callable - The callable to check.
+   * @returns {string} The type: 'function', 'step', or 'workflow'.
+   * @throws {Error} Throws if callable type is invalid.
+   */
+  static getCallableType(callable) {
     if (callable && callable.base_type === base_types.WORKFLOW) {
-      return 'workflow';
+      return Step.callable_types.WORKFLOW;
     } else if (callable && callable.base_type === base_types.STEP) {
-      return 'step';
+      return Step.callable_types.STEP;
     } else if (typeof callable === 'function') {
-      return 'function';
-    } 
+      return Step.callable_types.FUNCTION;
+    }
 
     throw new Error('Invalid callable type. Must be one of function, Step, or Workflow.');
   }
 
   /**
-   * Sets a value in the parent workflow's state.
-   * @param {string} workflowId - ID of the parent workflow.
-   * @param {string} path - Path in the workflow state to set.
+   * Registers a Step subclass so hydration can rebuild instances of the correct type.
+   * Called as a side effect at the bottom of each step subclass file.
+   * @param {typeof Step} StepClass - The Step subclass to register, keyed by its static `step_name`.
+   */
+  static registerStepClass(StepClass) {
+    step_class_registry[StepClass.step_name] = StepClass;
+  }
+
+  /**
+   * Resolves a `step_name` (as stored in `class_name` on a serialized step) to its class.
+   * Falls back to the base `Step` class if the name is unknown.
+   * @param {string} step_name - The step_name to resolve.
+   * @returns {typeof Step} The resolved Step subclass.
+   */
+  static resolveStepClass(step_name) {
+    return step_class_registry[step_name] ?? Step;
+  }
+
+  /**
+   * Serializes a callable-like value (function, Step, or Workflow) into a plain, JSON-safe descriptor.
+   * @param {Function|Step|Workflow|null} callable - The callable to serialize.
+   * @returns {Object|null} A `{ type, value }` descriptor, or null if no callable was given.
+   */
+  static serializeCallableField(callable) {
+    if (callable === null || callable === undefined) {
+      return null;
+    }
+
+    const type = Step.getCallableType(callable);
+
+    if (type === Step.callable_types.FUNCTION) {
+      return { type, value: callable.name };
+    }
+
+    return { type, value: callable.prepareForSerialization() };
+  }
+
+  /**
+   * Hydrates a callable-like descriptor (as produced by `serializeCallableField`) back into a
+   * live function, Step, or Workflow. Idempotent - passing an already-hydrated value through
+   * returns it unchanged, since subclass `hydrate` overrides may resolve a field before
+   * delegating to a superclass `hydrate` that would otherwise try to resolve it again.
+   * @param {Object|Function|Step|Workflow|null} serialized - The descriptor (or already-hydrated value) to hydrate.
+   * @param {import('../callable_registry.js').default|null} [callable_registry] - Registry used to resolve function callables.
+   * @returns {Function|Step|Workflow|undefined} The hydrated callable, or undefined if nothing was given.
+   * @throws {Error} Throws if a function callable can't be found in the registry, or the descriptor type is unknown.
+   */
+  static hydrateCallableField(serialized, callable_registry = null) {
+    if (serialized === null || serialized === undefined) {
+      return undefined;
+    }
+
+    if (typeof serialized === 'function' || serialized instanceof Step || serialized?.base_type) {
+      return serialized;
+    }
+
+    const { type, value } = serialized;
+
+    if (type === Step.callable_types.FUNCTION) {
+      if (!callable_registry || !callable_registry.has(value)) {
+        throw new Error(`Callable registry key "${value}" not found in registry or registry not provided.`);
+      }
+
+      return callable_registry.get(value);
+    }
+
+    if (type === Step.callable_types.STEP) {
+      return Step.hydrateAny(value, callable_registry);
+    }
+
+    if (type === Step.callable_types.WORKFLOW) {
+      return Workflow.hydrate(value, callable_registry);
+    }
+
+    throw new Error(`Unknown callable type "${type}" encountered during hydration.`);
+  }
+
+  /**
+   * Hydrates a parsed step object into an instance of its correct Step subclass,
+   * resolved from its serialized `class_name`.
+   * @param {Object} parsed_step - The parsed step object.
+   * @param {import('../callable_registry.js').default|null} [callable_registry] - Registry used to resolve function callables.
+   * @returns {Step} The hydrated Step (or subclass) instance.
+   */
+  static hydrateAny(parsed_step, callable_registry = null) {
+    const StepClass = Step.resolveStepClass(parsed_step.class_name);
+
+    return StepClass.hydrate(parsed_step, callable_registry);
+  }
+
+  /**
+   * 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() {
+    const serialized_step = {
+      id: this.id,
+      class_name: this.constructor.step_name,
+      name: this.name,
+      callable_type: this.callable_type,
+      step_type: this.step_type,
+      sub_step_type: this.sub_step_type,
+      max_retries: this.max_retries,
+      max_timeout_ms: this.max_timeout_ms,
+      retry_count: this.retry_count,
+      retry_results: this.retry_results,
+      errors: this.errors,
+      result: this.result,
+      timing: this.timing,
+      status: this.status,
+      parent_workflow_id: this.parent_workflow_id,
+    };
+
+    serialized_step.callable = this.callable_registry_key
+      ? { type: Step.callable_types.FUNCTION, value: this.callable_registry_key }
+      : Step.serializeCallableField(this.#callable_object);
+
+    return serialized_step;
+  }
+
+  /**
+   * Sets a value on the parent workflow instance itself. Normally this is the live object
+   * shared via this step's own state under the `workflow` key (see `initializeWorkflowState()`
+   * in `workflow.js`); when `use_state_singleton` is `true`, several unrelated workflows can
+   * share the same process-wide state, so it's looked up by id in the singleton's `workflows`
+   * registry instead.
+   * @param {string} workflow_id - ID of the parent workflow.
+   * @param {string} path - Property name to set on the workflow instance.
    * @param {*} value - Value to set at the specified path.
-   * @throws {Error} Throws if parent workflow is not found.
+   * @throws {Error} Throws if the parent workflow is not found.
    */
-  setParentWorkflowValue(workflowId, path, value) {
-    const parentWorkflow = this.getState('workflows')[workflowId];
+  setParentWorkflowValue(workflow_id, path, value) {
+    const parent_workflow = this.use_state_singleton
+      ? this.getState('workflows')[workflow_id]
+      : this.getState('workflow');
 
-    if (!parentWorkflow) {
-      throw new Error(`Parent workflow with ID ${workflowId} not found.`);
+    if (!parent_workflow || parent_workflow.id !== workflow_id) {
+      throw new Error(`Parent workflow with ID ${workflow_id} not found.`);
     }
 
-    parentWorkflow[path] = value;
+    parent_workflow[path] = value;
+  }
+
+  /**
+   * Serializes the step into a JSON string.
+   * @returns {string} The JSON string representation of the step.
+   */
+  serialize() {
+    return JSON.stringify(this.prepareForSerialization());
+  }
+
+  /**
+   * Custom JSON serializer
+   * @returns {Object} The JSON representation of the step.
+   */
+  toJSON() {
+    return this.prepareForSerialization();
   }
 
   /**
@@ -141,7 +311,7 @@ export default class Step extends Base {
 
     if (['step', 'workflow'].includes(this.callable_type)) {
       if (this.callable_type === 'step') {
-        callable.parentWorkflowId = this.parentWorkflowId ?? null;
+        callable.parent_workflow_id = this.parent_workflow_id ?? null;
       }
 
       this._callable = callable.execute.bind(callable);
@@ -149,4 +319,52 @@ export default class Step extends Base {
       this._callable = callable.bind(this);
     }
   }
+
+  /**
+   * Deserializes a JSON string into a Step instance and hydrates it, dispatching to the correct subclass.
+   * @param {string} serialized_step - The JSON string representation of the step.
+   * @param {import('../callable_registry.js').default|null} [callable_registry] - Registry used to resolve function callables.
+   * @returns {Step} The hydrated Step (or subclass) instance.
+   * @throws {Error} Throws if the serialized step is not a string.
+   */
+  static hydrateSerialized(serialized_step, callable_registry = null) {
+    if (typeof serialized_step !== 'string') {
+      throw new Error('Invalid serialized step. Must be a string.');
+    }
+
+    return Step.hydrateAny(JSON.parse(serialized_step), callable_registry);
+  }
+
+  /**
+   * Hydrates a parsed step object into an instance of `this` class, resolving its callable
+   * (and restoring execution metadata) from the serialized data.
+   * Subclasses with extra callable-like fields (e.g. ConditionalStep's true_callable/false_callable)
+   * should resolve those fields with `Step.hydrateCallableField` and delegate to `super.hydrate()`.
+   * @param {Object} parsed_step - The parsed step object.
+   * @param {import('../callable_registry.js').default|null} [callable_registry] - Registry used to resolve function callables.
+   * @returns {Step} The hydrated Step instance.
+   * @throws {Error} Throws if a callable registry key is specified but not found in the registry.
+   */
+  static hydrate(parsed_step, callable_registry = null) {
+    const callable_descriptor = parsed_step.callable;
+    const callable = Step.hydrateCallableField(callable_descriptor, callable_registry);
+    const callable_registry_key = callable_descriptor?.type === Step.callable_types.FUNCTION
+      ? callable_descriptor.value
+      : null;
+
+    const instance = new this({ ...parsed_step, callable, callable_registry_key });
+
+    instance.id = parsed_step.id;
+    instance.retry_count = parsed_step.retry_count ?? 0;
+    instance.retry_results = parsed_step.retry_results ?? [];
+    instance.errors = parsed_step.errors ?? [];
+    instance.result = parsed_step.result ?? null;
+    instance.timing = parsed_step.timing;
+    instance.status = parsed_step.status;
+    instance.parent_workflow_id = parsed_step.parent_workflow_id ?? null;
+
+    return instance;
+  }
 }
+
+Step.registerStepClass(Step);

package/src/classes/steps/switch_step.js

@@ -1,4 +1,5 @@
 import Step from './step.js';
+import { event_names } from '../instance_state.js';
 
 /**
  * SwitchStep class for implementing switch/case logic in workflows.
@@ -16,12 +17,14 @@ export default class SwitchStep extends Step {
    * @param {Array<Case|LogicStep>} [options.cases=[]] - Array of Case or LogicStep instances to evaluate. LogicStep instances MUST have conditional.subject set.
    * @param {Function|Step|Workflow} [options.default_callable=async () => {}] - Function, Step, or Workflow to execute if no cases match.
    * @param {*|Function} [options.subject=null] - Subject value to evaluate against each case. Can be a function that returns the value.
+   * @param {string|null} [options.default_callable_registry_key=null] - Optional key to reference default_callable to be rehydrated after serialization.
    */
   constructor({
     name,
     cases = [],
     default_callable = async () => {},
-    subject = null
+    subject = null,
+    default_callable_registry_key = null,
   }) {
     super({
       name,
@@ -29,6 +32,7 @@ export default class SwitchStep extends Step {
     });
 
     this.cases = cases;
+    this.default_callable_registry_key = default_callable_registry_key;
     this._default_callable_type = this.getCallableType(default_callable);
     this._default_callable_raw = default_callable;
     this.default_callable = this._default_callable_type === 'function'
@@ -42,36 +46,91 @@ export default class SwitchStep extends Step {
   /**
    * Executes the switch logic by evaluating each case in order.
    * Returns the result of the first matching case, or the default callable if no match.
+   * Every `Case` (and, if it's a `Step`/`Workflow`, `default_callable`) is stamped with this
+   * step's own `parent_workflow_id`/`use_state_singleton`/`state` before it runs, since `cases`
+   * lives on this step rather than the parent workflow's `_steps`, so it never goes through
+   * `Workflow.addStep()` to pick those up on its own.
    * @returns {Promise<*>} The result of the matched case or default callable.
    */
   async switch() {
     // Resolve subject once - call it if it's a function
-    const resolvedSubject = typeof this.subject === 'function' ? this.subject() : this.subject;
+    const resolved_subject = typeof this.subject === 'function' ? this.subject() : this.subject;
     
     for (const switch_case of this.cases) {
-      switch_case.switch_subject = resolvedSubject;
+      switch_case.switch_subject = resolved_subject;
+      // Cases live in `this.cases`, not the workflow's `_steps` array, so they never go through
+      // Workflow.addStep() - stamp them here instead, mirroring what addStep() does.
+      switch_case.parent_workflow_id = this.parent_workflow_id;
+      switch_case.use_state_singleton = this.use_state_singleton;
+      switch_case.state = this.state;
 
       const is_matched = await switch_case.checkCondition();
 
       if (is_matched) {
         this.log(
-          this.getState('events.step.event_names.SWITCH_CASE_MATCHED'),
+          event_names.step.SWITCH_CASE_MATCHED,
           `Case matched for step: ${this.name}, executing case callable`
         );
 
         // Return the case's result value directly, not the Case object.
         // This keeps result structure consistent: switchStep.result contains the
         // callable's return value, matching how Step.result works.
-        const caseResult = await switch_case.execute();
-        return caseResult.result;
+        const case_result = await switch_case.execute();
+        return case_result.result;
       }
     }
 
     // Unwrap Step/Workflow results for consistency with case results
-    const defaultResult = await this.default_callable();
     if (this._default_callable_type !== 'function') {
-      return defaultResult.result;
+      this._default_callable_raw.parent_workflow_id = this.parent_workflow_id;
+      this._default_callable_raw.use_state_singleton = this.use_state_singleton;
+      this._default_callable_raw.state = this.state;
     }
-    return defaultResult;
+
+    const default_result = await this.default_callable();
+    if (this._default_callable_type !== 'function') {
+      return default_result.result;
+    }
+    return default_result;
+  }
+
+  /**
+   * Inserts safely serializable properties of the step into a new object for serialization.
+   * Note: a function-valued `subject` 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(),
+      // The base `callable` is an internal wiring detail (the bound `switch` method) -
+      // SwitchStep's constructor doesn't take a callable, so it isn't real data to persist.
+      callable: null,
+      cases: this.cases.map(switch_case => switch_case.prepareForSerialization()),
+      default_callable: this.default_callable_registry_key
+        ? { type: Step.callable_types.FUNCTION, value: this.default_callable_registry_key }
+        : Step.serializeCallableField(this._default_callable_raw),
+      subject: typeof this.subject === 'function' ? null : this.subject,
+    };
+  }
+
+  /**
+   * Hydrates a parsed step object into a SwitchStep instance, resolving its cases and default 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 {SwitchStep} The hydrated SwitchStep instance.
+   */
+  static hydrate(parsed_step, callable_registry = null) {
+    const default_descriptor = parsed_step.default_callable;
+
+    return super.hydrate({
+      ...parsed_step,
+      cases: (parsed_step.cases ?? []).map(switch_case => Step.hydrateAny(switch_case, callable_registry)),
+      default_callable: Step.hydrateCallableField(default_descriptor, callable_registry),
+      default_callable_registry_key: default_descriptor?.type === Step.callable_types.FUNCTION
+        ? default_descriptor.value
+        : null,
+    }, callable_registry);
   }
 }
+
+SwitchStep.registerStepClass(SwitchStep);