@ronaldroe/micro-flow 1.3.9 → 2.0.0

package/src/classes/workflow.js

@@ -1,5 +1,8 @@
 import crypto from 'crypto';
 import Base from './base.js';
+import CallableRegistry from './callable_registry.js';
+import Step from './steps/step.js';
+import State from './state.js';
 import { base_types } from '../enums/index.js';
 
 /**
@@ -12,30 +15,48 @@ export default class Workflow extends Base {
    * Creates a new Workflow instance.
    * @param {Object} options - Configuration options.
    * @param {string} [options.name] - Name of the workflow.
+   * @param {CallableRegistry|null} [options.callable_registry=null] - Registry for callable objects.
    * @param {boolean} [options.exit_on_error=false] - Whether to exit on error.
    * @param {Array<Step>} [options.steps=[]] - Array of steps to add to the workflow.
    * @param {boolean} [options.throw_on_empty=false] - Whether to throw error if workflow is empty.
+   * @param {boolean} [options.use_state_singleton=false] - Deprecated. When true, this workflow (and every
+   * `Step` it owns) reads/writes `getState`/`setState`/`deleteState` calls through the process-wide `State`
+   * singleton instead of this workflow's own state.
    */
   constructor({
     name,
+    callable_registry = null,
     exit_on_error = false,
+    result_per_step = false,
+    result_per_step_function = null,
     steps = [],
-    throw_on_empty = false
+    throw_on_empty = false,
+    use_state_singleton = false,
   }) {
-    super({ name, base_type: base_types.WORKFLOW });
-
-    this.initializeWorkflowState();
-
-    this.addSteps(steps);
+    super({ name, base_type: base_types.WORKFLOW, use_state_singleton });
 
+    this.callable_registry = callable_registry ?? new CallableRegistry();
+    this.current_session_id = null;
     this.exit_on_error = exit_on_error;
-    this.throw_on_empty = throw_on_empty;
+    this.result_per_step = result_per_step;
     this.sessions = {};
-    this.current_session_id = null;
+    this.throw_on_empty = throw_on_empty;
+    this.result_per_step_function = result_per_step_function;
+
+    // _steps/steps_by_id must exist before initializeWorkflowState(): it reads this._steps
+    // (to set current_step) and logs, which serializes `this` - both need this._steps to
+    // already be an array, even when no steps are passed (addSteps([]) never calls addStep,
+    // so it wouldn't otherwise get initialized).
+    this._steps = [];
+    this.steps_by_id = {};
+    this.addSteps(steps);
+    this.initializeWorkflowState();
   }
 
   /**
    * Executes the workflow by running all steps in sequence.
+   * If the workflow is currently `paused`, resumes from the step after the one
+   * that was running when it paused, rather than starting over from the beginning.
    * @async
    * @returns {Promise<Workflow>} The workflow instance with execution results.
    * @throws {Error} Throws if workflow is empty and throw_on_empty is true.
@@ -51,13 +72,17 @@ export default class Workflow extends Base {
       }
 
       this.markAsComplete();
-      this.prepareResult('Workflow is empty', null);
+      await this.prepareResult('Workflow is empty', null);
       return this;
     }
-  
+
+    const is_resuming = this.status === this.getState('statuses.workflow').PAUSED;
+    const paused_at_index = this._steps.findIndex(step => step.id === this.current_step);
+    const start_index = is_resuming ? paused_at_index + 1 : 0;
+
     this.markAsRunning();
 
-    for (let i = 0; i < this._steps.length; i++) {
+    for (let i = start_index; i < this._steps.length; i++) {
       if (this.should_break) {
         this.log(this.getState('event_names.workflow').WORKFLOW_BREAK_EXECUTED, `Workflow "${this.name}" execution broken at step ${this._steps[i].name} - ${this._steps[i].id}.`);
         break;
@@ -76,10 +101,10 @@ export default class Workflow extends Base {
 
       try {
         const step_result = await this.step();
-        this.prepareResult('Success', step_result);
+        await this.prepareResult('Success', step_result);
       } catch (error) {
         this.markAsFailed();
-        this.prepareResult(`Workflow execution failed at step ${this.steps_by_id[this.current_step].name} - ${this.current_step}`, { error });
+        await this.prepareResult(`Workflow execution failed at step ${this.steps_by_id[this.current_step].name} - ${this.current_step}`, { error });
   
         if (this.exit_on_error) {
           return this;
@@ -94,7 +119,7 @@ export default class Workflow extends Base {
     }
 
     this.markAsComplete();
-    return this;
+    return this.prepareForSerialization();
   }
 
   /**
@@ -121,7 +146,6 @@ export default class Workflow extends Base {
   async step() {
     const step = this.steps_by_id[this.current_step];
 
-    step.parentWorkflowId = this.id;
     const result = await step.execute();
 
     if (step.status === this.getState('statuses.step.FAILED')) {
@@ -137,8 +161,10 @@ export default class Workflow extends Base {
    * @throws {Error} Throws if step is not a valid Step instance.
    */
   addStep(step) {
+    // This check only ensures that the getCallableType method exists,
+    // which is a characteristic of Step instances
     if (typeof step.getCallableType !== 'function') {
-      throw new Error('Invalid step type. Must be an instance of Step.');
+      throw new Error('Invalid input. Must be an instance of Step.');
     }
 
     if (!Array.isArray(this._steps)) {
@@ -151,7 +177,10 @@ export default class Workflow extends Base {
 
     this.steps_by_id[step.id] = step;
 
-    step.parentWorkflowId = this.id;
+    step.parent_workflow_id = this.id;
+    step.parent_workflow = this.prepareForSerialization();
+    step.use_state_singleton = this.use_state_singleton;
+    step.state = this.state;
     this._steps.push(step);
   }
 
@@ -166,7 +195,10 @@ export default class Workflow extends Base {
     }
 
     this.steps_by_id[step.id] = step;
-    step.parentWorkflowId = this.id;
+    step.parent_workflow_id = this.id;
+    step.parent_workflow = this.prepareForSerialization();
+    step.use_state_singleton = this.use_state_singleton;
+    step.state = this.state;
     this._steps.splice(index, 0, step);
   }
 
@@ -175,6 +207,10 @@ export default class Workflow extends Base {
    * @param {Step[]} steps - Array of steps to add.
    */
   addSteps(steps) {
+    if (!Array.isArray(steps)) {
+      throw new Error('Invalid input. Must be an array of Step instances.');
+    }
+
     steps.forEach(step => this.addStep(step));
   }
 
@@ -183,6 +219,7 @@ export default class Workflow extends Base {
    */
   clearSteps() {
     this._steps = [];
+    this.steps_by_id = {};
   }
 
   /**
@@ -207,6 +244,10 @@ export default class Workflow extends Base {
    * @param {string} stepId - The ID of the step to delete.
    */
   deleteStep(stepId) {
+    if (!Array.isArray(this._steps)) {
+      this._steps = [];
+    }
+
     this._steps = this._steps.filter(step => step.id !== stepId);
   }
 
@@ -215,28 +256,48 @@ export default class Workflow extends Base {
    * @param {number} index - The index of the step to delete.
    */
   deleteStepByIndex(index) {
+    if (!Array.isArray(this._steps)) {
+      this._steps = [];
+    }
+
     this._steps.splice(index, 1);
   }
 
+  /**
+   * Resolves a nested property path within this workflow's own state - the low-level counterpart
+   * to `getState()`. Falls back to the deprecated `State` singleton's resolver when
+   * `use_state_singleton` is `true`.
+   * @param {string} path - Path to the state property.
+   * @param {boolean} [emit=true] - Only meaningful when `use_state_singleton` is `true`; whether
+   * to emit the singleton's `GET_FROM_PROPERTY_PATH` state event.
+   * @returns {*} The value at the specified path, or undefined if not found.
+   */
+  getStateFromPropertyPath(path, emit = true) {
+    if (this.use_state_singleton) {
+      console.warn('The state singleton has been deprecated. Use the .prepareForSerialization() method on the workflow instance instead.');
+      return State.getFromPropertyPath(path, emit);
+    }
+
+    return this.state.getStateFromPropertyPath(path);
+  }
+
   /**
    * Initializes the workflow state with default values.
    */
   initializeWorkflowState() {
-    this.results = [];
-    this.exit_on_error = false;
-    this.current_step = null;
-    this.should_break = false;
-    this.should_continue = false;
-    this.should_pause = false;
-    this.should_skip = false;
-    this.status = this.getState('statuses.workflow').CREATED;
-    this._steps = [];
-    this.throw_on_empty = this.throw_on_empty;
+    this.current_step = ! this.isEmpty() ? this._steps[0].id : null;
+    this.results = this.results ?? [];
+    this.sessions = this.sessions ?? {};
+    this.should_break = this.should_break ?? false;
+    this.should_continue = this.should_continue ?? false;
+    this.should_pause = this.should_pause ?? false;
+    this.should_skip = this.should_skip ?? false;
+    this.status = this.status ?? this.getState('statuses.workflow').CREATED;
     this.timing = {
       ...this.timing,
-      create_time: new Date(),
-      pause_time: null,
-      resume_time: null,
+      create_time: this.timing?.create_time ?? new Date(),
+      pause_time: this.timing?.pause_time ?? null,
+      resume_time: this.timing?.resume_time ?? null,
     }
 
     const workflows = this.getState('workflows');
@@ -254,7 +315,7 @@ export default class Workflow extends Base {
    * @returns {boolean} True if the workflow is empty.
    */
   isEmpty() {
-    return !this._steps || !this._steps.length
+    return !Array.isArray(this._steps) || !this._steps.length;
   }
 
   /**
@@ -329,6 +390,16 @@ export default class Workflow extends Base {
     );
   }
 
+  /**
+   * Parses a property path string into an array of keys, supporting both dot notation and
+   * bracket notation (e.g. `"users[0].name"`). Pure utility - not affected by `use_state_singleton`.
+   * @param {string} path - The path to parse.
+   * @returns {string[]} Array of property keys.
+   */
+  parseStatePath(path) {
+    return this.use_state_singleton ? State.parsePath(path) : this.state.parseStatePath(path);
+  }
+
   /**
    * Pauses the workflow execution.
    */
@@ -350,13 +421,41 @@ export default class Workflow extends Base {
     return this._steps.pop();
   }
 
+  /**
+   * Inserts safely serializable properties of the workflow into a new object for serialization.
+   * @returns {Object} An object containing the workflow's properties ready for serialization.
+  */
+  prepareForSerialization() {
+    const serialized_workflow = {
+      id: this.id,
+      current_session_id: this.current_session_id,
+      current_step: this.current_step,
+      exit_on_error: this.exit_on_error,
+      name: this.name,
+      sessions: this.sessions,
+      status: this.status,
+      steps: this._steps.map(step => step.prepareForSerialization()),
+      throw_on_empty: this.throw_on_empty,
+      timing: this.timing,
+      results: this.results,
+      use_state_singleton: this.use_state_singleton,
+    };
+
+    return serialized_workflow;
+  }
+
   /**
    * Prepares a result object and adds it to the results array.
    * @param {string} message - Result message.
    * @param {*} data - Result data.
    */
-  prepareResult(message, data) {
-    this.results.push({ message, data });
+  async prepareResult(message, data) {
+    if (this.result_per_step && typeof this.result_per_step_function === 'function') {
+      await this.result_per_step_function(this.prepareForSerialization());
+    }
+
+    const result = { message, data };
+    this.results.push(result);
   }
 
   /**
@@ -375,6 +474,33 @@ export default class Workflow extends Base {
     steps.forEach(step => this.addStep(step));
   }
 
+  /**
+   * Serializes the workflow into a JSON string.
+   * @returns {string} The JSON string representation of the workflow.
+   */
+  serialize() {
+    return JSON.stringify(this.prepareForSerialization());
+  }
+
+  /**
+   * Sets a nested property value within this workflow's own state, creating intermediate
+   * objects/arrays as needed - the low-level counterpart to `setState()`. Falls back to the
+   * deprecated `State` singleton's setter when `use_state_singleton` is `true`.
+   * @param {string} path - Path to the state property.
+   * @param {*} value - The value to set at the specified path.
+   * @param {boolean} [emit=true] - Only meaningful when `use_state_singleton` is `true`; whether
+   * to emit the singleton's `SET_TO_PROPERTY_PATH` state event.
+   */
+  setStateToPropertyPath(path, value, emit = true) {
+    if (this.use_state_singleton) {
+      console.warn('The state singleton has been deprecated. Use the .prepareForSerialization() method on the workflow instance instead.');
+      State.setToPropertyPath(path, value, emit);
+      return;
+    }
+
+    this.state.setStateToPropertyPath(path, value);
+  }
+
   /**
    * Removes and returns the first step from the workflow.
    * @returns {Step} The first step.
@@ -399,10 +525,20 @@ export default class Workflow extends Base {
 
     this.steps_by_id[step.id] = step;
 
-    step.parentWorkflowId = this.id;
+    step.parent_workflow_id = this.id;
+    step.use_state_singleton = this.use_state_singleton;
+    step.state = this.state;
     this._steps.unshift(step);
   }
 
+  /**
+   * Custom JSON serializer
+   * @returns {Object} The JSON representation of the workflow.
+   */
+  toJSON() {
+    return this.prepareForSerialization();
+  }
+
   /**
    * Gets the array of steps in the workflow.
    * @returns {Step[]} Array of steps.
@@ -416,12 +552,73 @@ export default class Workflow extends Base {
    * @param {Step[]} steps - Array of steps to add.
    */
   set steps(steps) {
-    steps.forEach((step, index) => {
-      if (typeof step.getCallableType !== 'function') {
-        throw new Error(`Invalid step type. Step at index ${index} is not an instance of Step.`);
-      }
+    this.addSteps(steps);
+  }
+
+  /**
+   * Deserializes a JSON string into a Workflow instance and hydrates it.
+   * @param {string} serialized_workflow - The JSON string representation of the workflow.
+   * @param {CallableRegistry|null} [callable_registry] - Registry used to resolve function callables in the workflow's steps.
+   * @returns {Workflow} The hydrated Workflow instance.
+   * @throws {Error} Throws if the serialized workflow is not a string.
+   */
+  static hydrateSerialized(serialized_workflow, callable_registry = null) {
+    // TODO: Validate structure of serialized workflow
+    if (typeof serialized_workflow !== 'string') {
+      throw new Error('Invalid serialized workflow. Must be a string.');
+    }
+
+    const parsed = JSON.parse(serialized_workflow);
+
+    return Workflow.hydrate(parsed, callable_registry);
+  }
+
+  /**
+   * Hydrates a parsed workflow object into a Workflow instance.
+   * @param {Object} parsed_workflow - The parsed workflow object.
+   * @param {CallableRegistry|null} [callable_registry] - Registry used to resolve function callables in the workflow's steps.
+   * @returns {Workflow} The hydrated Workflow instance.
+   * @throws {Error} Throws if the parsed workflow is not a valid object.
+   */
+  static hydrate(parsed_workflow, callable_registry = null) {
+    // TODO: Validate structure of serialized workflow
+    // TODO: Use event system to handle errors?
+    if (typeof parsed_workflow !== 'object' || parsed_workflow === null) {
+      throw new Error('Invalid parsed workflow. Must be a valid object.');
+    }
+
+    const hydrated_workflow = new Workflow({
+      name: parsed_workflow.name,
+      callable_registry,
+      exit_on_error: parsed_workflow.exit_on_error,
+      steps: parsed_workflow.steps.map(step => Step.hydrateAny(step, callable_registry)),
+      throw_on_empty: parsed_workflow.throw_on_empty,
+      use_state_singleton: parsed_workflow.use_state_singleton ?? false,
     });
 
-    this.addSteps(steps);
+    // The constructor above (via Base) always generates a fresh id, and addStep() has
+    // already stamped that fresh id onto each step's parent_workflow_id and registered
+    // the workflow under it in its own state's `workflows` registry. Restoring the real id
+    // below would otherwise leave both of those referencing a discarded id, so fix them up here too.
+    const stale_id = hydrated_workflow.id;
+    hydrated_workflow.id = parsed_workflow.id;
+
+    const workflows = hydrated_workflow.getState('workflows');
+    delete workflows[stale_id];
+    workflows[hydrated_workflow.id] = hydrated_workflow;
+    hydrated_workflow.setState('workflows', workflows);
+
+    hydrated_workflow.steps.forEach(step => {
+      step.parent_workflow_id = hydrated_workflow.id;
+    });
+
+    hydrated_workflow.current_session_id = parsed_workflow.current_session_id;
+    hydrated_workflow.current_step = parsed_workflow.current_step ?? hydrated_workflow.current_step;
+    hydrated_workflow.sessions = parsed_workflow.sessions ?? {};
+    hydrated_workflow.status = parsed_workflow.status;
+    hydrated_workflow.timing = parsed_workflow.timing;
+    hydrated_workflow.results = parsed_workflow.results;
+
+    return hydrated_workflow;
   }
 }

package/src/enums/delay_types.js

@@ -6,7 +6,7 @@
  * @example
  * import delay_types from 'micro-flow';
  * 
- * const delayStep = new DelayStep({
+ * const delay_step = new DelayStep({
  *   name: 'wait-5-seconds',
  *   delay_type: delay_types.RELATIVE,
  *   delay_duration: 5000

package/src/enums/logic_step_types.js

@@ -5,7 +5,7 @@
  * @enum {string}
  * @readonly
  */
-const LogicStepTypes = {
+const logic_step_types = {
   CONDITIONAL: 'conditional',
   LOOP: 'loop',
   FLOW_CONTROL: 'flow_control',
@@ -13,4 +13,4 @@ const LogicStepTypes = {
   SKIP: 'skip'
 };
 
-export default LogicStepTypes;
+export default logic_step_types;

package/src/enums/sub_step_types.js

@@ -3,18 +3,18 @@
  * @type {Object.<string, string>}
  * @readonly
  * @example
- * console.log(sub_step_types.Step); // "step"
- * console.log(sub_step_types.ConditionalStep); // "conditional"
+ * console.log(sub_step_types.step); // "step"
+ * console.log(sub_step_types.conditional_step); // "conditional"
  */
 const sub_step_types = {
-  Step: 'step',
-  LogicStep: 'logic',
-  ConditionalStep: 'conditional',
-  FlowControlStep: 'flow_control',
-  LoopStep: 'loop',
-  SwitchStep: 'switch',
-  Case: 'case',
-  DelayStep: 'delay',
+  step: 'step',
+  logic_step: 'logic',
+  conditional_step: 'conditional',
+  flow_control_step: 'flow_control',
+  loop_step: 'loop',
+  switch_step: 'switch',
+  case: 'case',
+  delay_step: 'delay',
 };
 
 export default sub_step_types;