@ronaldroe/micro-flow 2.0.0 → 3.0.0

package/src/classes/steps/flow_control_step.js

@@ -1,6 +1,7 @@
 import LogicStep from './logic_step.js';
 import flow_control_types from '../../enums/flow_control_types.js';
 import { conditional_step_comparators } from '../../enums/index.js';
+import { event_names } from '../instance_state.js';
 
 /**
  * FlowControlStep class for controlling workflow execution flow (break or skip).
@@ -51,7 +52,7 @@ export default class FlowControlStep extends LogicStep {
   async shouldFlowControl() {
     if (this.checkCondition()) {
       this.log(
-        this.getState('events.step.event_names.CONDITIONAL_TRUE_BRANCH_EXECUTED'),
+        event_names.step.CONDITIONAL_TRUE_BRANCH_EXECUTED,
         `Break condition met for step: ${this.name}`
       );
       this.setParentWorkflowValue(this.parent_workflow_id, `should_${this.flow_control_type}`, true);
@@ -59,7 +60,7 @@ export default class FlowControlStep extends LogicStep {
       return true;
     } else {
       this.log(
-        this.getState('events.step.event_names.CONDITIONAL_FALSE_BRANCH_EXECUTED'),
+        event_names.step.CONDITIONAL_FALSE_BRANCH_EXECUTED,
         `Break condition not met for step: ${this.name}`
       );
       this.setParentWorkflowValue(this.parent_workflow_id, `should_${this.flow_control_type}`, false);

package/src/classes/steps/logic_step.js

@@ -55,77 +55,77 @@ export default class LogicStep extends Step {
     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 is_custom_function = operator === this.getState('conditional_step_comparators.CUSTOM_FUNCTION');
+    const is_custom_function = operator === 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'):
-      case this.getState('conditional_step_comparators.SIGN_STRICT_EQUALS'):
+      case conditional_step_comparators.STRICT_EQUALS:
+      case conditional_step_comparators.SIGN_STRICT_EQUALS:
         return subject === value;
-      case this.getState('conditional_step_comparators.SIGN_EQUALS'):
-      case this.getState('conditional_step_comparators.EQUALS'):
+      case conditional_step_comparators.SIGN_EQUALS:
+      case conditional_step_comparators.EQUALS:
         return subject == value;
-      case this.getState('conditional_step_comparators.NOT_EQUALS'):
-      case this.getState('conditional_step_comparators.SIGN_NOT_EQUALS'):
+      case conditional_step_comparators.NOT_EQUALS:
+      case conditional_step_comparators.SIGN_NOT_EQUALS:
         return subject != value;
-      case this.getState('conditional_step_comparators.STRICT_NOT_EQUALS'):
-      case this.getState('conditional_step_comparators.SIGN_STRICT_NOT_EQUALS'):
+      case conditional_step_comparators.STRICT_NOT_EQUALS:
+      case conditional_step_comparators.SIGN_STRICT_NOT_EQUALS:
         return subject !== value;
-      case this.getState('conditional_step_comparators.GREATER_THAN'):
-      case this.getState('conditional_step_comparators.SIGN_GREATER_THAN'):
+      case conditional_step_comparators.GREATER_THAN:
+      case conditional_step_comparators.SIGN_GREATER_THAN:
         return subject > value;
-      case this.getState('conditional_step_comparators.LESS_THAN'):
-      case this.getState('conditional_step_comparators.SIGN_LESS_THAN'):
+      case conditional_step_comparators.LESS_THAN:
+      case conditional_step_comparators.SIGN_LESS_THAN:
         return subject < value;
-      case this.getState('conditional_step_comparators.GREATER_THAN_OR_EQUAL'):
-      case this.getState('conditional_step_comparators.SIGN_GREATER_THAN_OR_EQUAL'):
+      case conditional_step_comparators.GREATER_THAN_OR_EQUAL:
+      case conditional_step_comparators.SIGN_GREATER_THAN_OR_EQUAL:
         return subject >= value;
-      case this.getState('conditional_step_comparators.LESS_THAN_OR_EQUAL'):
-      case this.getState('conditional_step_comparators.SIGN_LESS_THAN_OR_EQUAL'):
+      case conditional_step_comparators.LESS_THAN_OR_EQUAL:
+      case conditional_step_comparators.SIGN_LESS_THAN_OR_EQUAL:
         return subject <= value;
-      case this.getState('conditional_step_comparators.STRING_CONTAINS'):
-      case this.getState('conditional_step_comparators.STRING_INCLUDES'):
-      case this.getState('conditional_step_comparators.ARRAY_CONTAINS'):
-      case this.getState('conditional_step_comparators.ARRAY_INCLUDES'):
+      case conditional_step_comparators.STRING_CONTAINS:
+      case conditional_step_comparators.STRING_INCLUDES:
+      case conditional_step_comparators.ARRAY_CONTAINS:
+      case conditional_step_comparators.ARRAY_INCLUDES:
         return (Array.isArray(subject) || typeof subject === 'string') && subject.includes(value);
-      case this.getState('conditional_step_comparators.IN'):
+      case conditional_step_comparators.IN:
         return (Array.isArray(value) || typeof value === 'string') && value.includes(subject);
-      case this.getState('conditional_step_comparators.STRING_NOT_CONTAINS'):
-      case this.getState('conditional_step_comparators.STRING_NOT_INCLUDES'):
-      case this.getState('conditional_step_comparators.ARRAY_NOT_CONTAINS'):
-      case this.getState('conditional_step_comparators.ARRAY_NOT_INCLUDES'):
+      case conditional_step_comparators.STRING_NOT_CONTAINS:
+      case conditional_step_comparators.STRING_NOT_INCLUDES:
+      case conditional_step_comparators.ARRAY_NOT_CONTAINS:
+      case conditional_step_comparators.ARRAY_NOT_INCLUDES:
         return (Array.isArray(subject) || typeof subject === 'string') && !subject.includes(value);
-      case this.getState('conditional_step_comparators.NOT_IN'):
+      case conditional_step_comparators.NOT_IN:
         return (Array.isArray(value) || typeof value === 'string') && !value.includes(subject);
-      case this.getState('conditional_step_comparators.EMPTY'):
+      case conditional_step_comparators.EMPTY:
         return subject === '' || subject === null || subject === undefined || subject.length === 0;
-      case this.getState('conditional_step_comparators.NOT_EMPTY'):
+      case conditional_step_comparators.NOT_EMPTY:
         return subject !== '' && subject !== null && subject !== undefined && subject.length > 0;
-      case this.getState('conditional_step_comparators.REGEX_MATCH'):
+      case conditional_step_comparators.REGEX_MATCH:
         if (typeof value !== 'string') {
           throw new Error(`Regex input must be a string.`);
         }
         const regex = new RegExp(value);
         return regex.test(subject);
-      case this.getState('conditional_step_comparators.REGEX_NOT_MATCH'):
+      case conditional_step_comparators.REGEX_NOT_MATCH:
         if (typeof value !== 'string') {
           throw new Error(`Regex input must be a string.`);
         }
         const not_match_regex = new RegExp(value);
         return !not_match_regex.test(subject);
-      case this.getState('conditional_step_comparators.STRING_STARTS_WITH'):
+      case 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'):
+      case conditional_step_comparators.STRING_ENDS_WITH:
         return typeof subject === 'string' && typeof value === 'string' && subject.endsWith(value);
-      case this.getState('conditional_step_comparators.NULLISH'):
+      case conditional_step_comparators.NULLISH:
         return subject === null || subject === undefined;
-      case this.getState('conditional_step_comparators.NOT_NULLISH'):
+      case conditional_step_comparators.NOT_NULLISH:
         return subject !== null && subject !== undefined;
-      case this.getState('conditional_step_comparators.IS_TYPE'):
+      case conditional_step_comparators.IS_TYPE:
         return typeof subject === value;
-      case this.getState('conditional_step_comparators.IS_NOT_TYPE'):
+      case conditional_step_comparators.IS_NOT_TYPE:
         return typeof subject !== value;
-      case this.getState('conditional_step_comparators.CUSTOM_FUNCTION'):
+      case conditional_step_comparators.CUSTOM_FUNCTION:
         if (typeof value !== 'function') {
           throw new Error(`Invalid custom function: ${value}`);
         }

package/src/classes/steps/step.js

@@ -101,7 +101,7 @@ export default class Step extends Base {
       }
     }
 
-    const { FAILED, COMPLETE } = this.getState('statuses')[this.base_type];
+    const { FAILED, COMPLETE } = Workflow.statuses[this.base_type];
 
     if (![FAILED, COMPLETE].includes(this.status)) {
       this.markAsComplete();
@@ -264,16 +264,22 @@ export default class Step extends Base {
   }
 
   /**
-   * Sets a value in the parent workflow's state.
+   * 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 - Path in the workflow state to set.
+   * @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(workflow_id, path, value) {
-    const parent_workflow = this.getState('workflows')[workflow_id];
+    const parent_workflow = this.use_state_singleton
+      ? this.getState('workflows')[workflow_id]
+      : this.getState('workflow');
 
-    if (!parent_workflow) {
+    if (!parent_workflow || parent_workflow.id !== workflow_id) {
       throw new Error(`Parent workflow with ID ${workflow_id} not found.`);
     }
 

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.
@@ -67,7 +68,7 @@ export default class SwitchStep extends Step {
 
       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`
         );
 

package/src/classes/workflow.js

@@ -3,6 +3,7 @@ import Base from './base.js';
 import CallableRegistry from './callable_registry.js';
 import Step from './steps/step.js';
 import State from './state.js';
+import { statuses, event_names, events, types, conditional_step_comparators, messages } from './instance_state.js';
 import { base_types } from '../enums/index.js';
 
 /**
@@ -76,7 +77,7 @@ export default class Workflow extends Base {
       return this;
     }
 
-    const is_resuming = this.status === this.getState('statuses.workflow').PAUSED;
+    const is_resuming = this.status === 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;
 
@@ -84,13 +85,13 @@ export default class Workflow extends Base {
 
     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}.`);
+        this.log(event_names.workflow.WORKFLOW_BREAK_EXECUTED, `Workflow "${this.name}" execution broken at step ${this._steps[i].name} - ${this._steps[i].id}.`);
         break;
       }
 
       if (this.should_skip) {
         this.log(
-          this.getState('events.workflow.event_names.WORKFLOW_STEP_SKIPPED'),
+          event_names.workflow.WORKFLOW_STEP_SKIPPED,
           `Workflow "${this.name}" skipping step ${this._steps[i].name} - ${this._steps[i].id}.`
         );
         this.should_skip = false;
@@ -131,8 +132,8 @@ export default class Workflow extends Base {
     this.should_pause = false;
     this.timing.resume_time = new Date();
 
-    this.getState('events.workflow').emit(
-      this.getState('event_names.workflow').WORKFLOW_RESUMED,
+    events.workflow.emit(
+      event_names.workflow.WORKFLOW_RESUMED,
       this.getState()
     );
     return this.execute();
@@ -148,7 +149,7 @@ export default class Workflow extends Base {
 
     const result = await step.execute();
 
-    if (step.status === this.getState('statuses.step.FAILED')) {
+    if (step.status === statuses.step.FAILED) {
       throw step.errors[step.errors.length - 1] ?? new Error(`Step "${step.name}" failed`);
     }
 
@@ -292,7 +293,7 @@ export default class Workflow extends Base {
     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.status = this.status ?? statuses.workflow.CREATED;
     this.timing = {
       ...this.timing,
       create_time: this.timing?.create_time ?? new Date(),
@@ -300,12 +301,19 @@ export default class Workflow extends Base {
       resume_time: this.timing?.resume_time ?? null,
     }
 
-    const workflows = this.getState('workflows');
-    workflows[this.id] = this;
-    this.setState('workflows', workflows);
+    if (this.use_state_singleton) {
+      // The deprecated `State` singleton is shared by every workflow that opts into it, so it
+      // still needs an id-keyed registry (unlike per-instance state, which only ever has one
+      // workflow to represent and can just reference it directly - see the else branch).
+      const workflows = this.getState('workflows');
+      workflows[this.id] = this;
+      this.setState('workflows', workflows);
+    } else {
+      this.setState('workflow', this);
+    }
 
     this.log(
-      this.getState('event_names.workflow').WORKFLOW_CREATED,
+      event_names.workflow.WORKFLOW_CREATED,
       `Workflow "${this.name}" initialized.`
     );
   }
@@ -334,11 +342,11 @@ export default class Workflow extends Base {
     this.timing.create_time = new Date();
     
     this.log(
-      this.getState('event_names.workflow').WORKFLOW_CREATED,
+      event_names.workflow.WORKFLOW_CREATED,
       `Workflow "${this.name}" created.`
     );
 
-    return this.getState('statuses.workflow').CREATED;
+    return statuses.workflow.CREATED;
   }
 
   /**
@@ -354,23 +362,23 @@ export default class Workflow extends Base {
    */
   markAsPaused() {
     this.timing.pause_time = new Date();
-    this.status = this.getState('statuses.workflow').PAUSED;
+    this.status = statuses.workflow.PAUSED;
 
-    this.getState('events.workflow').emit(
-      this.getState('event_names.workflow').WORKFLOW_PAUSED,
+    events.workflow.emit(
+      event_names.workflow.WORKFLOW_PAUSED,
       this.getState()
     );
   }
-  
+
   /**
    * Marks the workflow as resumed.
    */
   markAsResumed() {
     this.timing.resume_time = new Date();
-    this.status = this.getState('statuses.workflow').RUNNING;
+    this.status = statuses.workflow.RUNNING;
 
-    this.getState('events.workflow').emit(
-      this.getState('event_names.workflow').WORKFLOW_RESUMED,
+    events.workflow.emit(
+      event_names.workflow.WORKFLOW_RESUMED,
       this.getState()
     );
   }
@@ -384,8 +392,8 @@ export default class Workflow extends Base {
     const [step] = this._steps.splice(fromIndex, 1);
     this._steps.splice(toIndex, 0, step);
 
-    this.getState('events.workflow').emit(
-      this.getState('event_names.workflow').WORKFLOW_STEP_MOVED,
+    events.workflow.emit(
+      event_names.workflow.WORKFLOW_STEP_MOVED,
       this.getState()
     );
   }
@@ -407,8 +415,8 @@ export default class Workflow extends Base {
     this.should_pause = true;
     this.timing.pause_time = new Date();
 
-    this.getState('events.workflow').emit(
-      this.getState('event_names.workflow').WORKFLOW_PAUSED,
+    events.workflow.emit(
+      event_names.workflow.WORKFLOW_PAUSED,
       this.getState()
     );
   }
@@ -597,16 +605,20 @@ export default class Workflow extends Base {
     });
 
     // 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.
+    // already stamped that fresh id onto each step's parent_workflow_id and (in singleton mode)
+    // registered the workflow under it in the singleton's `workflows` registry. Restoring the
+    // real id below would otherwise leave both referencing a discarded id, so fix them up here
+    // too. Per-instance state needs no such fixup for its `workflow` key - it's the same live
+    // object, so the id mutation below is reflected automatically.
     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);
+    if (hydrated_workflow.use_state_singleton) {
+      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;
@@ -622,3 +634,12 @@ export default class Workflow extends Base {
     return hydrated_workflow;
   }
 }
+
+// Framework constants, exposed as static members rather than duplicated into every
+// Workflow's own state (see instance_state.js, the canonical source for these values).
+Workflow.statuses = statuses;
+Workflow.event_names = event_names;
+Workflow.events = events;
+Workflow.types = types;
+Workflow.conditional_step_comparators = conditional_step_comparators;
+Workflow.messages = messages;