@ronaldroe/micro-flow 1.3.9 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ronaldroe/micro-flow",
-  "version": "1.3.9",
+  "version": "2.0.0",
   "description": "A lightweight, flexible workflow orchestration library for Node.js and browser environments. Build complex, sequential processes with ease using an intuitive API that supports conditional logic, flow control, event handling, and state management.",
   "main": "dist/index.js",
   "exports": {

package/src/classes/base.js

@@ -1,6 +1,6 @@
 import crypto from 'crypto';
 import { base_types } from '../enums/index.js';
-import State from './state.js';
+import State, { InstanceState } from './state.js';
 
 /**
  * Base class for workflows and steps.
@@ -13,12 +13,20 @@ export default class Base {
    * @param {Object} options - Configuration options.
    * @param {string} [options.name] - Name of the instance.
    * @param {string} [options.base_type=base_types.STEP] - Type of the base instance.
+   * @param {boolean} [options.use_state_singleton=false] - Deprecated. When true, `getState`/`setState`/`deleteState`
+   * fall back to the process-wide `State` singleton instead of this instance's own state. `Workflow` passes this
+   * value down to every `Step` it owns, so it only needs to be set once, on the workflow.
+   * @param {InstanceState|null} [options.state=null] - The `InstanceState` this instance's `getState`/`setState`/
+   * `deleteState` calls should read and write. `Workflow` creates its own on construction and shares it with its
+   * `Step`s; a `Step` created standalone (not yet added to a workflow) gets its own until it's added to one.
    */
-  constructor({ name, base_type = base_types.STEP }) {
+  constructor({ name, base_type = base_types.STEP, use_state_singleton = false, state = null }) {
     this.id = crypto.randomUUID();
     this.name = name ?? `${base_type}-${this.id}`;
 
     this.base_type = base_type;
+    this.use_state_singleton = use_state_singleton;
+    this.state = use_state_singleton ? null : (state ?? new InstanceState());
     this.timing = {
       cancel_time: null,
       complete_time: null,
@@ -52,10 +60,10 @@ export default class Base {
       return;
     }
 
-    const logMessage = message ? `\n[${this.base_type.toUpperCase()} - ${this.name}] ${message}` : `\n[${this.base_type.toUpperCase()} - ${this.name}] Event: ${event_name}`;
-    const logType = event_name.endsWith('_failed') ? 'error' : 'log';
+    const log_message = message ? `\n[${this.base_type.toUpperCase()} - ${this.name}] ${message}` : `\n[${this.base_type.toUpperCase()} - ${this.name}] Event: ${event_name}`;
+    const log_type = event_name.endsWith('_failed') ? 'error' : 'log';
 
-    console[logType](logMessage);
+    console[log_type](log_message);
   }
 
   /**
@@ -115,28 +123,51 @@ export default class Base {
 
   // State management methods
   /**
-   * Gets a value from the global state.
+   * Gets a value from this instance's own state (the `Workflow`'s state, shared with its `Step`s).
+   * Set `use_state_singleton: true` (on the owning `Workflow`) to instead read from the
+   * deprecated, process-wide `State` singleton.
    * @param {string} path - Path to the state property.
    * @returns {*} The state value at the specified path.
    */
   getState(path) {
-    return State.get(path);
+    if (this.use_state_singleton) {
+      console.warn('The state singleton has been deprecated. Use the .prepareForSerialization() method on the workflow instance instead.');
+      return State.get(path);
+    }
+
+    return this.state.get(path);
   }
 
   /**
-   * Sets a value in the global state.
+   * Sets a value in this instance's own state (the `Workflow`'s state, shared with its `Step`s).
+   * Set `use_state_singleton: true` (on the owning `Workflow`) to instead write to the
+   * deprecated, process-wide `State` singleton.
    * @param {string} path - Path to the state property.
    * @param {*} value - Value to set.
    */
   setState(path, value) {
-    State.set(path, value);
+    if (this.use_state_singleton) {
+      console.warn('The state singleton has been deprecated. Use the .prepareForSerialization() method on the workflow instance instead.');
+      State.set(path, value);
+      return;
+    }
+
+    this.state.set(path, value);
   }
 
   /**
-   * Deletes a property from the global state.
+   * Deletes a property from this instance's own state (the `Workflow`'s state, shared with its `Step`s).
+   * Set `use_state_singleton: true` (on the owning `Workflow`) to instead delete from the
+   * deprecated, process-wide `State` singleton.
    * @param {string} path - Path to the state property to delete.
    */
   deleteState(path) {
-    State.delete(path);
+    if (this.use_state_singleton) {
+      console.warn('The state singleton has been deprecated. Use the .prepareForSerialization() method on the workflow instance instead.');
+      State.delete(path);
+      return;
+    }
+
+    this.state.delete(path);
   }
 }

package/src/classes/callable_registry.js

@@ -0,0 +1,82 @@
+/**
+ * Provides a registry for callable functions to be used with persistence mode.
+ * This class allows you to register, retrieve, check for, and deregister callable functions by name.
+ */
+export default class CallableRegistry {
+  #registry;
+
+  /**
+   * Registry for callable functions to be used with persistence mode.
+   */
+  constructor() {
+    this.clear();
+  }
+
+  /**
+   * Clears all callable entries from the registry.
+   */
+  clear() {
+    this.#registry = {};
+  }
+
+  /**
+   * Removes a callable from the registry.
+   * @param {string} name - The name of the callable to remove.
+   * @throws Will throw an error if no callable is registered under the given name.
+   */
+  deregister(name) {
+    if (!this.has(name)) {
+      throw new Error(`No callable registered under the name "${name}".`);
+    }
+
+    delete this.#registry[name];
+  }
+
+  /**
+   * Retrieves a callable from the registry.
+   * @param {string} name - The name of the callable to retrieve.
+   * @returns {Function} The callable function registered under the given name.
+   * @throws Will throw an error if no callable is registered under the given name.
+   */
+  get(name) {
+    if (!this.has(name)) {
+      throw new Error(`No callable registered under the name "${name}".`);
+    }
+
+    return this.#registry[name];
+  }
+
+  /**
+   * Checks if a callable is registered under the given name.
+   * @param {string} name - The name of the callable to check.
+   * @returns {boolean} True if a callable is registered under the given name, false otherwise.
+   */
+  has(name) {
+    return Object.hasOwn(this.#registry, name);
+  }
+
+  /**
+   * Registers a callable function under a given name.
+   * @param {string} name - The name to register the callable under.
+   * @param {Function} callable - The function to register as a callable.
+   * @throws Will throw an error if the provided callable is not a function.
+   */
+  register(name, callable) {
+    if (typeof callable !== 'function') {
+      throw new Error('Only functions can be registered as callables.');
+    }
+
+    this.#registry[name] = callable;
+  }
+
+  /**
+   * Registers multiple callables from an object mapping names to functions.
+   * @param {Object} callables - An object where keys are names and values are functions to register.
+   * @throws Will throw an error if any of the provided callables is not a function.
+   */
+  registerMany(callables) {
+    for (const [name, callable] of Object.entries(callables)) {
+      this.register(name, callable);
+    }
+  }
+}

package/src/classes/events/event.js

@@ -40,7 +40,7 @@ class Event extends EventTarget {
    */
   emit(event_name, data, bubbles = false, cancelable = true) {
     const seen = new WeakSet();
-    const workingData = JSON.parse(JSON.stringify(data, (key, value) => {
+    const working_data = JSON.parse(JSON.stringify(data, (key, value) => {
       if (typeof value === 'object' && value !== null) {
         if (seen.has(value)) return undefined;
         seen.add(value);
@@ -49,7 +49,7 @@ class Event extends EventTarget {
     }));
 
     const custom_event = new CustomEvent(event_name, {
-      detail: workingData,
+      detail: working_data,
       bubbles,
       cancelable
     });
@@ -57,7 +57,7 @@ class Event extends EventTarget {
 
     try {
       const channel = new BroadcastChannel(event_name);
-      channel.postMessage(workingData);
+      channel.postMessage(working_data);
       channel.close();
     } catch (e) {
       console.warn(warnings.BROADCAST_FAILED, e);

package/src/classes/index.js

@@ -1,5 +1,6 @@
 export * from './events/index.js';
 export { default as Base } from './base.js';
-export { default as State } from './state.js';
+export { default as CallableRegistry } from './callable_registry.js';
+export { default as State, InstanceState } from './state.js';
 export { default as Workflow } from './workflow.js';
 export * from './steps/index.js';

package/src/classes/state.js

@@ -12,7 +12,7 @@ import {
   workflow_statuses,
 } from '../enums/index.js';
 
-const defaultState = {
+const default_state = {
   messages: {
     errors,
     warnings,
@@ -40,12 +40,282 @@ const defaultState = {
   conditional_step_comparators
 };
 
-let state = { ...defaultState };
+let state = { ...default_state };
 
 // Module-level shortcuts for events and event_names
 const events = state.events;
 const event_names = state.event_names;
 
+/**
+ * Parses a property path string into an array of keys, supporting both dot notation
+ * and bracket notation. Shared by both the deprecated singleton `State` and per-instance
+ * `InstanceState`.
+ *
+ * @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;
+  }
+}
+
+/**
+ * Builds a fresh data object for a `Workflow`/`Step` instance's own state, seeded with the
+ * same framework constants (statuses, event enums, event emitters, comparators) the deprecated
+ * `State` singleton used to provide - but with its own independent, empty `workflows` registry
+ * rather than sharing the process-wide one.
+ *
+ * The event emitters (and other constant objects) are shared by reference with the singleton's
+ * defaults so that `on()`/`off()` listeners registered via `State.get('events.workflow')` keep
+ * receiving events regardless of whether a given `Workflow`/`Step` has opted back into
+ * `use_state_singleton`.
+ *
+ * @returns {Object} A fresh instance-state data object.
+ */
+export function createInstanceStateData() {
+  return {
+    messages: default_state.messages,
+    statuses: default_state.statuses,
+    event_names: default_state.event_names,
+    events: default_state.events,
+    types: default_state.types,
+    conditional_step_comparators: default_state.conditional_step_comparators,
+    workflows: {},
+  };
+}
+
+/**
+ * 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.
+ *
+ * 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, defaults to a fresh `createInstanceStateData()` result.
+   */
+  constructor(initial = createInstanceStateData()) {
+    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);
+    }
+  }
+}
+
 /**
  * Singleton class representing the global state for workflows, steps, and processes.
  * Provides methods for managing state with getter/setter functionality, nested path access,
@@ -118,9 +388,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 +512,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 +553,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);