@ronaldroe/micro-flow 1.3.9 → 3.0.0

package/src/classes/instance_state.js

@@ -0,0 +1,277 @@
+import { errors, warnings } from '../enums/errors.js';
+import { StepEvent, WorkflowEvent, StateEvent } from './events/index.js';
+import {
+  base_types,
+  conditional_step_comparators,
+  state_event_names,
+  step_event_names,
+  step_statuses,
+  step_types,
+  sub_step_types,
+  workflow_event_names,
+  workflow_statuses,
+} from '../enums/index.js';
+
+/**
+ * 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.
+ */
+function parsePath(path) {
+  const matches = path.match(/[^.[\]]+|(?<=\[)([^\]]+)(?=\])/g);
+
+  if (!matches) {
+    return [];
+  }
+
+  return matches.map(part => part.replace(/^['"]|['"]$/g, ''));
+}
+
+/**
+ * Resolves a nested property path within an arbitrary object.
+ * @param {Object} target - The object to read from.
+ * @param {string} path - The path to the property.
+ * @returns {*} The value at the specified path, or undefined if not found.
+ */
+function getAtPath(target, path) {
+  const parts = parsePath(path);
+  let current = target;
+
+  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 an arbitrary object based on a path.
+ * Creates intermediate objects/arrays as needed.
+ * @param {Object} target - The object to write to.
+ * @param {string} path - The path to the property.
+ * @param {*} value - The value to set at the specified path.
+ */
+function setAtPath(target, path, value) {
+  const parts = parsePath(path);
+  let current = target;
+
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    const next_part = parts[i + 1];
+
+    if (!Object.prototype.hasOwnProperty.call(current, part) || typeof current[part] !== 'object') {
+      const is_next_part_numeric = /^\d+$/.test(next_part);
+      current[part] = is_next_part_numeric ? [] : {};
+    }
+    current = current[part];
+  }
+
+  current[parts[parts.length - 1]] = value;
+}
+
+/**
+ * Deletes a property from an arbitrary object using a path.
+ * @param {Object} target - The object to delete from.
+ * @param {string} path - The path of the property to delete.
+ */
+function deleteAtPath(target, path) {
+  const parts = parsePath(path);
+  let current = target;
+
+  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]];
+}
+
+/**
+ * Converts a resolved state value to the requested output type.
+ * @param {*} value - The value to convert.
+ * @param {string|null} type - One of "string", "number", "boolean".
+ * @returns {*} The converted value, or the original value if conversion fails or type is unrecognized.
+ */
+function convertType(value, type) {
+  if (!type) {
+    return value;
+  }
+
+  try {
+    switch (type) {
+      case 'string':
+        return String(value);
+      case 'number':
+        return Number(value);
+      case 'boolean':
+        return Boolean(value);
+      default:
+        return value;
+    }
+  } catch (error) {
+    console.error('Error converting state value: ', error);
+    return value;
+  }
+}
+
+/**
+ * Framework constants, built once here as the single canonical source. `Workflow` (see
+ * `workflow.js`) assigns these as its own static members - the public surface library
+ * consumers should reach them through - while step classes that need one directly may import
+ * the named export straight from this module instead of going through `Workflow` (avoiding an
+ * import cycle). The deprecated `State` singleton (`state.js`) also builds its `default_state`
+ * from these same values, so the `events.*` instances stay identical (by reference) regardless
+ * of whether a given `Workflow`/`Step` has opted into `use_state_singleton` - listeners
+ * registered via `State.get('events.workflow')` keep receiving events either way.
+ */
+export const messages = { errors, warnings };
+export const statuses = { workflow: workflow_statuses, step: step_statuses };
+export const event_names = { workflow: workflow_event_names, step: step_event_names, state: state_event_names };
+export const events = { workflow: new WorkflowEvent(), step: new StepEvent(), state: new StateEvent() };
+export const types = { base_types, step_types, sub_step_types };
+export { conditional_step_comparators };
+
+/**
+ * Per-instance replacement for the deprecated `State` singleton. Each `Workflow` owns one of
+ * these (created in its constructor), and shares it with every `Step` added to it, so that
+ * `getState()`/`setState()`/`deleteState()` calls made anywhere in that workflow's tree read and
+ * write the same, workflow-scoped data instead of a single process-wide object. A `Workflow`
+ * registers itself under the `workflow` key of its own `InstanceState` (see
+ * `initializeWorkflowState()` in `workflow.js`), so `getState('workflow')` resolves to the live
+ * owning `Workflow` instance; any other path is arbitrary user data set via `setState()`.
+ *
+ * Supports the same dot-notation/bracket-notation path access as `State`.
+ *
+ * @class InstanceState
+ */
+export class InstanceState {
+  /**
+   * Creates a new InstanceState.
+   * @param {Object} [initial={}] - Initial data.
+   */
+  constructor(initial = {}) {
+    this.data = initial;
+  }
+
+  /**
+   * 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. Falsy values, or "*", return the entire state.
+   * @param {*} [defaultValue=null] - Default value to return if the path doesn't exist.
+   * @param {string|null} [type=null] - The output type to convert the value to ("string", "number", "boolean").
+   * @returns {*} The value of the state property, or defaultValue if not found.
+   */
+  get(path, defaultValue = null, type = null) {
+    if (!path || ['*', ''].includes(path)) {
+      return this.data ?? defaultValue;
+    }
+
+    const gotten = getAtPath(this.data, path) ?? defaultValue;
+
+    return convertType(gotten, type) ?? defaultValue;
+  }
+
+  /**
+   * 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.
+   * @param {*} value - The value to set for the state property.
+   * @throws {Error} Throws if path is empty or invalid.
+   */
+  set(path, value) {
+    if (!path) {
+      throw new Error(errors.INVALID_STATE_PATH);
+    }
+
+    setAtPath(this.data, path, value);
+  }
+
+  /**
+   * Resolves a nested property path within this instance's data. Low-level counterpart to
+   * `get()` - unlike `get()`, a falsy/`'*'` path is not special-cased to mean "entire state".
+   * @param {string} path - The path to the property.
+   * @returns {*} The value at the specified path, or undefined if not found.
+   */
+  getStateFromPropertyPath(path) {
+    return getAtPath(this.data, path);
+  }
+
+  /**
+   * Parses a property path string into an array of keys, supporting both dot notation
+   * and bracket notation.
+   * @param {string} path - The path to parse.
+   * @returns {string[]} Array of property keys.
+   */
+  parseStatePath(path) {
+    return parsePath(path);
+  }
+
+  /**
+   * Sets a nested property value within this instance's data based on a path. Low-level
+   * counterpart to `set()` - unlike `set()`, does not throw on an empty path.
+   * @param {string} path - The path to the property.
+   * @param {*} value - The value to set at the specified path.
+   */
+  setStateToPropertyPath(path, value) {
+    setAtPath(this.data, path, value);
+  }
+
+  /**
+   * Deletes a state property using dot-notation or bracket-notation path access.
+   * @param {string} path - The path of the state property to delete.
+   * @throws {Error} Throws if path is empty or invalid.
+   */
+  delete(path) {
+    if (!path) {
+      throw new Error(errors.INVALID_STATE_PATH);
+    }
+
+    deleteAtPath(this.data, path);
+  }
+
+  /**
+   * Merges an object into the current instance state.
+   * @param {Object} newState - The object to merge in.
+   * @returns {Object} The updated state data.
+   */
+  merge(newState) {
+    this.data = { ...this.data, ...newState };
+    return this.data;
+  }
+
+  /**
+   * Iterates over a collection (array or object) located at the specified path,
+   * executing a callback function for each item.
+   * @param {string} path - The path of the property to iterate over.
+   * @param {Function} callback - The function to execute for each item in the collection.
+   * @throws {Error} Throws if the value at the path is not an array or object.
+   */
+  async each(path, callback) {
+    const collection = this.get(path);
+
+    if (Array.isArray(collection)) {
+      for (const [index, item] of collection.entries()) {
+        await callback(item, index);
+      }
+    } else if (
+      typeof collection === 'object' &&
+      Object.prototype.toString.call(collection) === '[object Object]'
+    ) {
+      for (const key of Object.keys(collection)) {
+        await callback(collection[key], key);
+      }
+    } else {
+      throw new Error(errors.VALUE_NOT_ITERABLE);
+    }
+  }
+}

package/src/classes/state.js

@@ -1,50 +1,21 @@
-import { errors, warnings } from '../enums/errors.js';
-import { StepEvent, WorkflowEvent, StateEvent } from './events/index.js';
-import {
-  base_types,
-  conditional_step_comparators,
-  state_event_names,
-  step_event_names,
-  step_statuses,
-  step_types,
-  sub_step_types,
-  workflow_event_names,
-  workflow_statuses,
-} from '../enums/index.js';
+import { errors } from '../enums/errors.js';
+import { messages, statuses, event_names, events, types, conditional_step_comparators } from './instance_state.js';
 
-const defaultState = {
-  messages: {
-    errors,
-    warnings,
-  },
-  statuses: {
-    workflow: workflow_statuses,
-    step: step_statuses
-  },
-  event_names: {
-    workflow: workflow_event_names,
-    step: step_event_names,
-    state: state_event_names,
-  },
-  events: {
-    workflow: new WorkflowEvent(),
-    step: new StepEvent(),
-    state: new StateEvent(),
-  },
-  types: {
-    base_types,
-    step_types,
-    sub_step_types,
-  },
+// Built from the same constants `Workflow` exposes as static members (see instance_state.js),
+// so `events.*` stays the same instance regardless of whether a given Workflow/Step has opted
+// into `use_state_singleton`. Only `workflows` is singleton-only - it was never meant to be
+// copied into per-instance state.
+export const default_state = {
+  messages,
+  statuses,
+  event_names,
+  events,
+  types,
   workflows: {},
-  conditional_step_comparators
+  conditional_step_comparators,
 };
 
-let state = { ...defaultState };
-
-// Module-level shortcuts for events and event_names
-const events = state.events;
-const event_names = state.event_names;
+let state = { ...default_state };
 
 /**
  * Singleton class representing the global state for workflows, steps, and processes.
@@ -118,9 +89,9 @@ class State {
    * @returns {void}
    */
   static freeze() {
-    const frozenState = Object.freeze(state);
+    const frozen_state = Object.freeze(state);
     events.state.emit(event_names.state.FROZEN, { state });
-    return frozenState;
+    return frozen_state;
   }
 
   /**
@@ -242,7 +213,7 @@ class State {
    */
   static reset() {
     state = { 
-      ...defaultState,
+      ...default_state,
       workflows: {},  // Always create fresh to avoid shared reference mutation
     };
     events.state.emit(event_names.state.RESET, { state });
@@ -283,12 +254,12 @@ class State {
     
     for (let i = 0; i < parts.length - 1; i++) {
       const part = parts[i];
-      const nextPart = parts[i + 1];
+      const next_part = 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 ? [] : {};
+        const is_next_part_numeric = /^\d+$/.test(next_part);
+        current[part] = is_next_part_numeric ? [] : {};
       }
       current = current[part];
     }

package/src/classes/steps/case.js

@@ -20,6 +20,7 @@ export default class Case extends LogicStep {
    * @param {conditional_step_comparators|string} [options.conditional.operator=null] - Comparison operator.
    * @param {*|Function} [options.conditional.value=null] - Value to compare against. Can be a function that returns the value.
    * @param {Function|Step|Workflow} [options.callable=async () => {}] - Function, Step, or Workflow to execute when case matches.
+   * @param {string|null} [options.callable_registry_key=null] - Optional key to reference the callable to be rehydrated after serialization.
    * @param {boolean} [options.force_subject_override=false] - Force override of subject even if already set.
    */
   constructor({
@@ -30,12 +31,14 @@ export default class Case extends LogicStep {
       value: null,
     },
     callable = async () => {},
+    callable_registry_key = null,
     force_subject_override = false,
   }) {
     super({
       name,
       step_type: Case.step_name,
       callable,
+      callable_registry_key,
     });
 
     this.conditional_config = conditional;
@@ -52,14 +55,14 @@ export default class Case extends LogicStep {
    * @throws {Error} If the resulting conditional configuration is invalid.
    */
   set switch_subject(subject) {
-    const subjectProvided = subject !== null && subject !== undefined;
-    const hasExistingSubject = this.conditional_config.subject !== null && this.conditional_config.subject !== undefined;
+    const subject_provided = subject !== null && subject !== undefined;
+    const has_existing_subject = this.conditional_config.subject !== null && this.conditional_config.subject !== undefined;
 
-    if (!subjectProvided && !hasExistingSubject) {
+    if (!subject_provided && !has_existing_subject) {
       throw new Error(`No subject set for case step: ${this.name}, using default equality check`);
     }
 
-    if (subjectProvided && (!hasExistingSubject || this.force_subject_override)) {
+    if (subject_provided && (!has_existing_subject || this.force_subject_override)) {
       this.conditional_config.subject = subject;
     }
 
@@ -67,4 +70,31 @@ export default class Case extends LogicStep {
       throw new Error(`Invalid conditional configuration for case step: ${this.name}`);
     }
   }
+
+  /**
+   * 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(),
+      force_subject_override: this.force_subject_override,
+      is_matched: this.is_matched,
+    };
+  }
+
+  /**
+   * Hydrates a parsed step object into a Case instance, restoring match state.
+   * @param {Object} parsed_step - The parsed step object.
+   * @param {import('../callable_registry.js').default|null} [callable_registry] - Registry used to resolve function callables.
+   * @returns {Case} The hydrated Case instance.
+   */
+  static hydrate(parsed_step, callable_registry = null) {
+    const instance = super.hydrate(parsed_step, callable_registry);
+    instance.is_matched = parsed_step.is_matched ?? false;
+
+    return instance;
+  }
 }
+
+Case.registerStepClass(Case);

package/src/classes/steps/conditional_step.js

@@ -1,5 +1,7 @@
+import Step from './step.js';
 import LogicStep from './logic_step.js';
 import { conditional_step_comparators } from '../../enums/index.js';
+import { event_names } from '../instance_state.js';
 
 /**
  * ConditionalStep class for branching logic based on conditions.
@@ -19,6 +21,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 +33,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 +67,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.
    */
@@ -64,30 +83,78 @@ export default class ConditionalStep extends LogicStep {
 
     if (this.checkCondition()) {
       this.log(
-        this.getState('events.step.event_names.CONDITIONAL_TRUE_BRANCH_EXECUTED'),
+        event_names.step.CONDITIONAL_TRUE_BRANCH_EXECUTED,
         `Condition met for step: ${this.name}, executing true branch`
       );
 
       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 {
       this.log(
-        this.getState('events.step.event_names.CONDITIONAL_FALSE_BRANCH_EXECUTED'),
+        event_names.step.CONDITIONAL_FALSE_BRANCH_EXECUTED,
         `Condition not met for step: ${this.name}, executing false branch`
       );
 
       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

@@ -1,5 +1,6 @@
 import Step from './step.js';
 import { delay_types, step_types } from '../../enums/index.js';
+import { event_names } from '../instance_state.js';
 import schedule from 'node-schedule';
 import { addMilliseconds } from 'date-fns';
 
@@ -47,7 +48,7 @@ export default class DelayStep extends Step {
 
     if (this.absolute_timestamp.getTime() <= now.getTime()) {
       this.log(
-        this.getState('events.step.event_names.DELAY_STEP_ABSOLUTE_COMPLETE'),
+        event_names.step.DELAY_STEP_ABSOLUTE_COMPLETE,
         `No delay for step: ${this.name}. Continuing.`
       );
       return { delayed: false, delay_type: this.delay_type, timestamp: now.toISOString() };
@@ -63,17 +64,13 @@ export default class DelayStep extends Step {
   async delay(delay_until) {
     return new Promise((resolve) => {
       this.log(
-        this.getState(
-          `events.step.event_names.DELAY_STEP_${this.delay_type.toUpperCase()}_SCHEDULED`
-        ),
+        event_names.step[`DELAY_STEP_${this.delay_type.toUpperCase()}_SCHEDULED`],
         `Delay scheduled for step: ${this.name} until ${delay_until.toISOString()}`
       );
 
       const job = schedule.scheduleJob(delay_until, () => {
         this.log(
-          this.getState(
-            `events.step.event_names.DELAY_STEP_${this.delay_type.toUpperCase()}_COMPLETE`
-          ),
+          event_names.step[`DELAY_STEP_${this.delay_type.toUpperCase()}_COMPLETE`],
           `Delay complete for step: ${this.name}. Continuing.`
         );
         resolve({ delayed: true, delay_type: this.delay_type, timestamp: new Date().toISOString() });
@@ -90,7 +87,7 @@ export default class DelayStep extends Step {
   async relative() {
     if (this.relative_delay_ms <= 0) {
       this.log(
-        this.getState('events.step.event_names.DELAY_STEP_RELATIVE_COMPLETE'),
+        event_names.step.DELAY_STEP_RELATIVE_COMPLETE,
         `No delay for step: ${this.name}. Continuing.`
       );
       return { delayed: false, delay_type: this.delay_type, timestamp: new Date().toISOString() };
@@ -100,4 +97,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);