@ronaldroe/micro-flow 1.0.0

package/src/enums/delay_types.js

@@ -0,0 +1,38 @@
+/**
+ * Enumeration of delay types for DelayStep.
+ * 
+ * @enum {string}
+ * @readonly
+ * @example
+ * import delay_types from 'micro-flow';
+ * 
+ * const delayStep = new DelayStep({
+ *   name: 'wait-5-seconds',
+ *   delay_type: delay_types.RELATIVE,
+ *   delay_duration: 5000
+ * });
+ */
+const delay_types = {
+  /**
+   * Delay until a specific absolute timestamp or Date.
+   * Use with delay_timestamp property.
+   * @type {string}
+   */
+  ABSOLUTE: 'absolute',
+  
+  /**
+   * Delay using a cron expression for scheduled execution.
+   * Use with cron_expression property.
+   * @type {string}
+   */
+  CRON: 'cron',
+  
+  /**
+   * Delay for a relative duration in milliseconds.
+   * Use with delay_duration property.
+   * @type {string}
+   */
+  RELATIVE: 'relative',
+};
+
+export default delay_types;

package/src/enums/errors.js

@@ -0,0 +1,25 @@
+/**
+ * Error messages used in the micro-flow library.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const errors = {
+  INVALID_STATE_PATH: 'The provided state path is invalid.\n',
+  INVALID_CONDITIONAL: 'Conditional properties are required for LogicStep.',
+};
+
+/**
+ * Warning messages used in the micro-flow library.
+ * These are typically logged to the console to alert developers of potential issues.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const warnings = {
+  DO_NOT_SET_STEPS_DIRECTLY: 'Using this.setState("steps", ...) is not recommended. ' +
+    'State will not be initialized correctly. Use workflow methods to manage steps instead.',
+  BROADCAST_FAILED: 'Broadcast failed or is not supported in this environment. The error has more detail:\n',
+};
+
+export { errors, warnings };

package/src/enums/flow_control_types.js

@@ -0,0 +1,12 @@
+/**
+ * Enumeration of flow control types for breaking or continuing execution.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const flow_control_types = {
+  BREAK: 'break',
+  SKIP: 'skip'
+};
+
+export default flow_control_types;

package/src/enums/index.js

@@ -0,0 +1,13 @@
+export { default as conditional_step_comparators } from './conditional_step_comparators.js';
+export { default as delay_types } from './delay_types.js';
+export * from './errors.js';
+export { default as flow_control_types } from './flow_control_types.js';
+export { default as logic_step_types } from './logic_step_types.js';
+export { default as loop_types } from './loop_types.js';
+export { default as step_event_names } from './step_event_names.js';
+export { default as step_statuses } from './step_statuses.js';
+export { default as step_types } from './step_types.js';
+export { default as sub_step_types } from './sub_step_types.js';
+export { default as workflow_event_names } from './workflow_event_names.js';
+export { default as workflow_statuses } from './workflow_statuses.js';
+export { default as base_types } from './base_types.js';

package/src/enums/logic_step_types.js

@@ -0,0 +1,16 @@
+/**
+ * Enumeration of logic step types for control flow operations.
+ * These types define different kinds of logic-based workflow steps.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const LogicStepTypes = {
+  CONDITIONAL: 'conditional',
+  LOOP: 'loop',
+  FLOW_CONTROL: 'flow_control',
+  SWITCH: 'switch',
+  SKIP: 'skip'
+};
+
+export default LogicStepTypes;

package/src/enums/loop_types.js

@@ -0,0 +1,12 @@
+/**
+ * Enumeration of loop types for LoopStep.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const loop_types = {
+  WHILE: 'while',
+  FOR_EACH: 'for_each'
+};
+
+export default loop_types;

package/src/enums/step_event_names.js

@@ -0,0 +1,22 @@
+/**
+ * Enumeration of step lifecycle event names.
+ * Steps emit these events during their execution lifecycle.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const step_event_names = {
+  CONDITIONAL_FALSE_BRANCH_EXECUTED: 'conditional_false_branch_executed',
+  CONDITIONAL_TRUE_BRANCH_EXECUTED: 'conditional_true_branch_executed',
+  DELAY_STEP_ABSOLUTE_COMPLETE: 'delay_step_absolute_complete',
+  DELAY_STEP_RELATIVE_COMPLETE: 'delay_step_relative_complete',
+  LOOP_ITERATION_COMPLETE: 'loop_iteration_complete',
+  STEP_COMPLETE: 'step_complete',
+  STEP_FAILED: 'step_failed',
+  STEP_RUNNING: 'step_running',
+  STEP_PENDING: 'step_pending',
+  STEP_WAITING: 'step_waiting',
+  STEP_RETRYING: 'step_retrying',
+}
+
+export default step_event_names;

package/src/enums/step_statuses.js

@@ -0,0 +1,17 @@
+/**
+ * Enumeration of possible step execution statuses.
+ * Steps transition through these statuses during their lifecycle.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const step_statuses = {
+  COMPLETE: 'complete',
+  FAILED: 'failed',
+  PENDING: 'pending',
+  QUEUED: 'queued',
+  RUNNING: 'running',
+  WAITING: 'waiting',
+};
+
+export default step_statuses;

package/src/enums/step_types.js

@@ -0,0 +1,14 @@
+/**
+ * Enumeration of step types used throughout the workflow system.
+ * These types categorize steps by their primary function.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const step_types = {
+  ACTION: 'action',
+  LOGIC: 'logic',
+  DELAY: 'delay',
+};
+
+export default step_types;

package/src/enums/sub_step_types.js

@@ -0,0 +1,130 @@
+import { readdirSync, readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import logic_step_types from './logic_step_types.js';
+import step_types from './step_types.js';
+import { sub } from 'date-fns';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Generates a mapping of Step class names to their step_name identifiers by reading
+ * class files from the filesystem. This approach avoids circular dependencies that would
+ * occur if we imported the Step classes directly.
+ * 
+ * The function parses each class file to extract:
+ * - The class name from the export statement
+ * - The static step_name property value
+ * 
+ * When step_name references an enum (e.g., logic_step_types.CONDITIONAL), the function
+ * resolves the actual string value from the imported enum objects.
+ * 
+ * The built-in classes directory is always scanned. Additional directories can be provided
+ * to scan for custom step classes. This is typically used via the workflow's sub_step_type_paths
+ * configuration option.
+ * 
+ * @function generate_sub_step_types
+ * @param {string[]} [directories=[]] - An array of additional directory paths to scan for class files. 
+ *   The built-in classes directory is always included. Defaults to an empty array.
+ * @returns {Object.<string, string|null>} An object mapping class names to their step_name values.
+ *   Classes without a step_name property are mapped to null.
+ * @example
+ * // Default usage (scans built-in classes only)
+ * const types = generate_sub_step_types();
+ * // Returns:
+ * // {
+ * //   "Step": null,
+ * //   "ConditionalStep": "conditional",
+ * //   "LogicStep": "logic",
+ * //   "DelayStep": "delay",
+ * //   ...
+ * // }
+ * 
+ * // With custom directories
+ * const types = generate_sub_step_types(['/path/to/custom/steps']);
+ */
+const generate_sub_step_types = (directories = []) => {
+  const types = {};
+  
+  // Always include the classes directory, then append any additional directories
+  directories.push(join(__dirname, '../classes'));
+  
+  // Combine all enums into one lookup object
+  const allEnums = {
+    logic_step_types,
+    step_types
+  };
+  
+  // Scan each directory in the array
+  for (const dir of directories) {
+    // Read all files in the current directory
+    const files = readdirSync(dir).filter(file => file.endsWith('.js') && file !== 'index.js');
+    
+    for (const file of files) {
+      const filePath = join(dir, file);
+      const content = readFileSync(filePath, 'utf-8');
+      
+      // Extract class name from the file content
+      const classNameMatch = content.match(/export default class (\w+)/);
+      if (!classNameMatch) continue;
+      
+      const className = classNameMatch[1];
+      
+      // Extract static step_name value
+      const stepNameMatch = content.match(/static step_name\s*=\s*['"`]?([^'"`;\n]+)['"`]?/);
+      
+      if (stepNameMatch) {
+        let stepName = stepNameMatch[1].trim();
+        
+        // Handle cases where step_name references an enum
+        // e.g., logic_step_types.CONDITIONAL or step_types.ACTION
+        if (stepName.includes('.')) {
+          const [enumName, enumKey] = stepName.split('.');
+          
+          // Look up the actual value from the imported enums
+          if (allEnums[enumName] && allEnums[enumName][enumKey]) {
+            stepName = allEnums[enumName][enumKey];
+          } else {
+            stepName = null;
+          }
+        }
+        
+        types[className] = stepName;
+      } else {
+        types[className] = null;
+      }
+    }
+  }
+  
+  return types;
+}
+
+/**
+ * Pre-generated mapping of all built-in Step class names to their step_name identifiers.
+ * This is a singleton object exported as the default export.
+ * 
+ * **Changed in recent version:** Previously exported as a function, now exported as a
+ * pre-generated object for improved performance and consistency.
+ * 
+ * @constant {Object.<string, string|null>}
+ * @example
+ * import sub_step_types from 'micro-flow';
+ * 
+ * console.log(sub_step_types);
+ * // {
+ * //   "Step": null,
+ * //   "ConditionalStep": "conditional",
+ * //   "DelayStep": "delay",
+ * //   "LoopStep": "loop",
+ * //   ...
+ * // }
+ * 
+ * // Check if a class name is a registered step type
+ * if (sub_step_types['ConditionalStep']) {
+ *   console.log('ConditionalStep is a registered step type');
+ * }
+ */
+const sub_step_types = generate_sub_step_types();
+
+export default sub_step_types;

package/src/enums/workflow_event_names.js

@@ -0,0 +1,26 @@
+/**
+ * Enumeration of workflow lifecycle event names.
+ * Workflows emit these events during their creation and execution lifecycle.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const workflow_event_names = {
+  WORKFLOW_CANCELLED: 'workflow_cancelled',
+  WORKFLOW_COMPLETE: 'workflow_complete',
+  WORKFLOW_CREATED: 'workflow_created',
+  WORKFLOW_ERRORED: 'workflow_errored',
+  WORKFLOW_FAILED: 'workflow_failed',
+  WORKFLOW_PAUSED: 'workflow_paused',
+  WORKFLOW_RESUMED: 'workflow_resumed',
+  WORKFLOW_RUNNING: 'workflow_running',
+  WORKFLOW_STEP_ADDED: 'workflow_step_added',
+  WORKFLOW_STEP_MOVED: 'workflow_step_moved',
+  WORKFLOW_STEP_REMOVED: 'workflow_step_removed',
+  WORKFLOW_STEP_SHIFTED: 'workflow_step_shifted',
+  WORKFLOW_STEP_SKIPPED: 'workflow_step_skipped',
+  WORKFLOW_STEPS_ADDED: 'workflow_steps_added',
+  WORKFLOW_STEPS_CLEARED: 'workflow_steps_cleared',
+}
+
+export default workflow_event_names;

package/src/enums/workflow_statuses.js

@@ -0,0 +1,21 @@
+/**
+ * Enumeration of possible workflow execution statuses.
+ * Workflows transition through these statuses during their lifecycle.
+ * 
+ * @enum {string}
+ * @readonly
+ */
+const workflow_statuses = {
+  CANCELLED: 'cancelled',
+  COMPLETE: 'complete',
+  CREATED: 'created',
+  ERRORED: 'errored',
+  FROZEN: 'frozen',
+  FAILED: 'failed',
+  PAUSED: 'paused',
+  PENDING: 'pending',
+  RUNNING: 'running',
+  SKIPPED: 'skipped'
+};
+
+export default workflow_statuses;

package/src/index.js

@@ -0,0 +1,2 @@
+export * from './classes/index.js';
+export * from './enums/index.js';