@ronaldroe/micro-flow 1.3.1 → 1.3.2

package/README.md

@@ -1,18 +1,24 @@
-# Micro-Flow
+# Micro-Flow: Stop fighting "Wall-of-Await" spaghetti.
 
-Micro-Flow is a simple, lightweight, cross platform (browser and runtime) logic orchestration library. Micro-Flow makes async logic flows first-class objects — named, observable, pauseable, and composable — so a multi-step process is something you can reason about, monitor, and control, not just a wall of awaits.
+Micro-Flow is a simple, lightweight, cross-platform logic orchestration library. It turns messy, imperative async chains into observable, resilient "logic flows" that run anywhere—from your React frontend to your Node.js backend.
+
+## Why Micro-Flow?
+
+We've all been there: a 100-line async function that acts as a "black box" when it fails. You have to manually hard-code retries, timeouts, state logging, and progress tracking for every single task. It’s brittle, a nightmare to unit test, and impossible to pause or resume.
+
+**Micro-Flow** makes your logic a first-class object. Instead of one giant function, you build a **Workflow** where every step is automatically tracked, timed, and controlled. It replaces "Try-Catch" boilerplate with professional orchestration.
 
 ## Features
 
-- 👀 **Observable** - Every step and logic flow emits lifecycle events (`STEP_FAILED`, `WORKFLOW_COMPLETE`, etc.) so you always know what's running, what finished, and what broke — no log-sprinkling required
-- ⏸️ **Pauseable & Resumeable** - Suspend a running logic flow mid-pipeline (e.g. waiting on user input or an external signal) and resume it without losing state
-- 🌿 **First-Class Branching** - `ConditionalStep` and `SwitchStep` keep branching logic out of your callables and in the logic flow structure where it belongs
-- 🎯 **Fine-Grained Flow Control** - Break out of or skip steps in a logic flow dynamically at runtime
-- 💾 **Shared State Singleton** - Steps communicate through a global `State` object with dot/bracket-notation path access — no threading data through function arguments
-- 📢 **Cross-Tab/Worker Communication** - Events broadcast automatically via `BroadcastChannel`, reaching other tabs and workers with no extra wiring
-- 🌐 **Universal** - Works in Node.js (≥18) and all modern browsers
-- 🎨 **Framework Friendly** - Integrates seamlessly with React, Vue, your favorite framework, and vanilla JS
-- ⚡ **Minimal Dependencies** - Lightweight and focused
+- 🔍 **Zero-Effort Observability** - Lifecycle events (`STEP_FAILED`, `WORKFLOW_COMPLETE`) emit automatically — eliminate manual log-sprinkling.
+- ⏸️ **Pause, Resume, & Rewind** - Suspend any logic flow mid-pipeline and resume it later without losing local state.
+- 🌿 **Declarative Branching** - Use `ConditionalStep` and `SwitchStep` to keep complex branching logic out of your callables and in the workflow structure.
+- 🎯 **Dynamic Flow Control** - Break out of or skip steps dynamically at runtime.
+- 💾 **Namespaced State Management** - Access global state through a namespaced singleton with dot-notation support — eliminate data-threading through arguments.
+- ✨ **Cross-Tab/Worker Sync** - Broadcast events automatically via `BroadcastChannel` to reach other tabs and workers with zero configuration.
+- 🌍 **Isomorphic by Design** - Run the same API in Node.js (≥18) and all modern browsers.
+- 🎨 **Framework Agnostic** - Integrate seamlessly with React, Vue, Svelte, or vanilla JS.
+- ⚡ **Lightweight Core** - ESM-first design with minimal production dependencies.
 
 ## Installation
 
@@ -27,12 +33,12 @@ npm install --save micro-flow
 ```javascript
 import { Workflow, Step } from 'micro-flow';
 
-// Create a simple workflow
 const workflow = new Workflow({
   name: 'data-processor',
   steps: [
     new Step({
       name: 'fetch-data',
+      max_retries: 3, // Built-in resilience for flaky APIs
       callable: async () => {
         const response = await fetch('https://api.example.com/data');
         return response.json();
@@ -40,27 +46,34 @@ const workflow = new Workflow({
     }),
     new Step({
       name: 'process-data',
-      callable: async () => {
-        console.log('Processing data...');
-        return { processed: true };
-      }
+      callable: async () => ({ processed: true })
     }),
     new Step({
       name: 'save-results',
-      callable: async () => {
-        console.log('Saving results...');
-        return { saved: true };
-      }
+      callable: async () => ({ saved: true })
     })
   ]
 });
 
-// Execute the workflow
 const result = await workflow.execute();
-console.log('Workflow complete!', result.results);
 ```
 
-### Browser Example
+### ✨ Feature Spotlight: Cross-Tab Sync
+Trigger logic in one tab and react to it in another. Events sync across workers and browser windows automatically:
+
+```javascript
+import { State } from 'micro-flow';
+
+// Listen for updates from other tabs/workers
+State.get('events.workflow').on('sync-event', (data) => {
+  updateUI(data);
+});
+
+// Broadcast to all other contexts
+State.get('events.workflow').emit('sync-event', { status: 'updated' });
+```
+
+### Browser: Coordinating UI Logic
 
 ```javascript
 import { Workflow, Step } from './micro-flow.js';
@@ -96,7 +109,7 @@ document.getElementById('loadBtn').addEventListener('click', () => {
 });
 ```
 
-### React Example
+### React: Decoupling Logic from Components
 
 ```javascript
 import { Workflow, Step, State } from './micro-flow.js';
@@ -110,12 +123,7 @@ function DataFetcher() {
     const workflow = new Workflow({
       name: 'fetch-workflow',
       steps: [
-        new Step({
-          name: 'start',
-          callable: async () => {
-            setLoading(true);
-          }
-        }),
+        new Step({ name: 'start', callable: async () => setLoading(true) }),
         new Step({
           name: 'fetch',
           callable: async () => {
@@ -124,12 +132,7 @@ function DataFetcher() {
             setData(json);
           }
         }),
-        new Step({
-          name: 'complete',
-          callable: async () => {
-            setLoading(false);
-          }
-        })
+        new Step({ name: 'complete', callable: async () => setLoading(false) })
       ]
     });
 
@@ -147,16 +150,13 @@ function DataFetcher() {
 }
 ```
 
-### Vue Example
+### Vue: Clean Reactive Lifecycle
 
 ```vue
 <template>
-  <div>
-    <button @click="runWorkflow" :disabled="isRunning">
-      {{ isRunning ? 'Processing...' : 'Run Workflow' }}
-    </button>
-    <p>{{ result }}</p>
-  </div>
+  <button @click="runWorkflow" :disabled="isRunning">
+    {{ isRunning ? 'Processing...' : 'Run Workflow' }}
+  </button>
 </template>
 
 <script setup>
@@ -164,33 +164,26 @@ import { ref } from 'vue';
 import { Workflow, Step } from './micro-flow.js';
 
 const isRunning = ref(false);
-const result = ref('');
 
 const runWorkflow = async () => {
   const workflow = new Workflow({
     name: 'vue-workflow',
     steps: [
       new Step({
-        name: 'step-1',
+        name: 'process',
         callable: async () => {
           isRunning.value = true;
-          await new Promise(resolve => setTimeout(resolve, 1000));
-          return 'Step 1 complete';
+          await doAsyncWork();
         }
       }),
       new Step({
-        name: 'step-2',
-        callable: async () => {
-          await new Promise(resolve => setTimeout(resolve, 1000));
-          return 'Step 2 complete';
-        }
+        name: 'finalize',
+        callable: async () => { isRunning.value = false; }
       })
     ]
   });
 
-  const workflowResult = await workflow.execute();
-  result.value = 'Workflow complete!';
-  isRunning.value = false;
+  await workflow.execute();
 };
 </script>
 ```
@@ -198,294 +191,53 @@ const runWorkflow = async () => {
 ## Core Concepts
 
 ### Workflows
-
-Workflows are primary structures that execute a series of steps in sequence. They provide:
-
-- Sequential step execution
-- Error handling with `exit_on_error` option
-- Pause and resume capabilities
-- Event emission for monitoring
-- Result collection
-
-```javascript
-import { Workflow } from 'micro-flow';
-
-const workflow = new Workflow({
-  name: 'my-workflow',
-  exit_on_error: true,  // Stop on first error
-  steps: [/* array of steps */]
-});
-```
+Workflows execute a series of steps in sequence. Use them to manage:
+- Sequential execution and error handling.
+- Fine-grained pause and resume control.
+- Event emission for real-time monitoring.
+- Result aggregation and session tracking.
 
 ### Steps
-
-Steps are individual units of work that execute functions, other steps, or even entire workflows. Steps have retry and timeout mechanisms.
-
-```javascript
-import { Step } from 'micro-flow';
-
-const step = new Step({
-  name: 'my-step',
-  callable: async () => {
-    // Your async code here
-    return result;
-  }
-});
-```
+Orchestrate functions, other steps, or entire workflows as individual units of work. Every step includes built-in retry and timeout policies.
 
 ### Callables
-
-Most step types accept a `callable` parameter. Callables are the individual actions a step can take.
-
-A callable can be any async function, another step, or even a whole workflow. That flexibility allows for everything from very simple logic flows to large, modularized flows broken down into logical units for execution.
+Define logic using callables. Assign any async function, step, or workflow to a step's `callable` parameter. This flexibility enables everything from simple logic chains to modularized, enterprise-scale flows.
 
 ### State Management
-
-Access global state across all workflows and steps:
+Manage namespaced global state across all workflows and steps:
 
 ```javascript
 import { State } from 'micro-flow';
 
-// Set values
+// Set and get values with dot-notation
 State.set('user.name', 'John Doe');
-State.set('config.timeout', 5000);
-
-// Get values
-const userName = State.get('user.name');
-const timeout = State.get('config.timeout', 3000); // with default
-
-// Delete values
-State.delete('user.name');
-
-// Merge objects into state
-State.merge({ settings: { theme: 'dark', lang: 'en' } });
-
-// Iterate over collections
-State.set('users', [{ name: 'Alice' }, { name: 'Bob' }]);
-State.each('users', (user, index) => {
-  console.log(`User ${index}: ${user.name}`);
-});
-
-// Freeze state (make immutable)
-State.freeze();
+const timeout = State.get('config.timeout', 3000);
 
-// Reset state to defaults
-State.reset();
+// Merge or iterate over collections
+State.merge({ settings: { theme: 'dark' } });
+State.each('users', (user) => console.log(user.name));
 ```
 
 ### Events
-
-Listen to workflow, step, and state lifecycle events. You can do this using Node's EventEmitter syntax or the browser's CustomEvent syntax. Both work in any environment:
-
-```javascript
-import { State } from 'micro-flow';
-
-const workflowEvents = State.get('events.workflow');
-
-workflowEvents.on('workflow_complete', (data) => {
-  console.log(`Workflow ${data.name} completed in ${data.timing.execution_time_ms}ms`);
-});
-
-const stepEvents = State.get('events.step');
-
-stepEvents.on('step_failed', (data) => {
-  console.error(`Step ${data.name} failed:`, data.errors);
-});
-
-const stateEvents = State.get('events.state');
-
-stateEvents.on('set', (data) => {
-  console.log('State modified:', data.state);
-});
-
-stateEvents.on('deleted', (data) => {
-  console.log('State property deleted');
-});
-```
-
-### Cross-Tab/Worker Communication
-
-Events broadcast automatically between browser tabs and windows or across workers when emitted, with no extra wiring needed:
-
-```javascript
-import { State } from './micro-flow.js';
-
-// All events broadcast automatically via BroadcastChannel
-const event = State.get('events.workflow');
-
-// Send event to other tabs
-event.emit('my-event', { type: 'update', data: { userId: 123 } });
-
-// Receive events from other tabs
-event.on('my-event', (data) => {
-  console.log('Message from another tab:', data);
-  if (data.type === 'update') {
-    updateUI(data.data);
-  }
-});
-```
+Monitor lifecycle events for workflows, steps, and state. Use Node's EventEmitter syntax or the browser's CustomEvent syntax—both support all environments.
 
 ## Use Cases
 
-### Backend (Node.js)
-
-- **Data Processing Pipelines** - ETL workflows, data transformation
-- **API Integrations** - Multi-step API calls with retry logic
-- **Task Automation** - Scheduled jobs, batch processing
-- **Microservices Orchestration** - Coordinate service calls
-- **Testing Workflows** - Integration test sequences
-
-### Frontend (Browser)
-
-- **Multi-Step Forms** - Registration, checkout, surveys
-- **Data Fetching** - Sequential API calls with caching
-- **Animation Sequences** - Complex UI animations
-- **User Onboarding** - Step-by-step tutorials
-- **State Machines** - UI state management
-- **Cross-Tab Synchronization** - Auth state, shopping cart, notifications
-- **Real-Time Collaboration** - Multi-tab editing, shared state
-
-## Advanced Examples
-
-### Node.js - Data Pipeline with Error Handling
-
-```javascript
-import { Workflow, Step, ConditionalStep, State } from 'micro-flow';
-
-const pipeline = new Workflow({
-  name: 'data-pipeline',
-  exit_on_error: false,
-  steps: [
-    new Step({
-      name: 'extract',
-      callable: async () => {
-        const data = await fetchFromDatabase();
-        State.set('pipeline.raw', data);
-        return data;
-      }
-    }),
-    new ConditionalStep({
-      name: 'validate',
-      conditional: {
-        subject: State.get('pipeline.raw')?.length,
-        operator: '>',
-        value: 0
-      },
-      true_callable: async () => ({ valid: true }),
-      false_callable: async () => {
-        throw new Error('No data to process');
-      }
-    }),
-    new Step({
-      name: 'transform',
-      callable: async () => {
-        const raw = State.get('pipeline.raw');
-        const transformed = raw.map(transform);
-        State.set('pipeline.transformed', transformed);
-        return transformed;
-      }
-    }),
-    new Step({
-      name: 'load',
-      callable: async () => {
-        const data = State.get('pipeline.transformed');
-        await saveToDatabase(data);
-        return { saved: data.length };
-      }
-    })
-  ]
-});
-
-await pipeline.execute();
-```
-
-### Browser - Multi-Step Form with Validation
+### Power Backend Processes (Node.js)
+- **Data Pipelines** - Build ETL and transformation workflows.
+- **API Integrations** - Orchestrate multi-step API calls with built-in retries.
+- **Automation** - Automate scheduled jobs and batch processing.
+- **Microservices** - Coordinate complex service calls.
 
-```javascript
-import { Workflow, ConditionalStep } from './micro-flow.js';
-
-function createFormWorkflow(formData) {
-  return new Workflow({
-    name: 'form-submission',
-    steps: [
-      new ConditionalStep({
-        name: 'validate-email',
-        conditional: {
-          subject: /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(formData.email),
-          operator: '===',
-          value: true
-        },
-        true_callable: async () => ({ valid: true }),
-        false_callable: async () => {
-          throw new Error('Invalid email');
-        }
-      }),
-      new Step({
-        name: 'submit',
-        callable: async () => {
-          const response = await fetch('/api/submit', {
-            method: 'POST',
-            body: JSON.stringify(formData)
-          });
-          return response.json();
-        }
-      }),
-      new Step({
-        name: 'show-success',
-        callable: async () => {
-          document.getElementById('message').textContent = 'Success!';
-        }
-      })
-    ]
-  });
-}
-```
+### Enhance Frontend Logic (Browser)
+- **Multi-Step UI** - Build registration flows and checkout wizards.
+- **Data Fetching** - Coordinate sequential API calls with caching.
+- **Animations** - Sequence complex UI animations.
+- **State Sync** - Sync auth state and shopping carts across tabs instantly.
 
 ## Documentation
-
-Full documentation is available in the [docs](docs/) directory:
-
-- [API Documentation](docs/index.md) - Complete API reference
-- [Classes](docs/classes/) - Workflow, Step, State, and more
-- [Events](docs/classes/events/) - Event system documentation
-- [Enums](docs/enums/) - Status codes and constants
-- [Examples](docs/examples/) - Comprehensive examples
-
-### Quick Links
-
-**Core Classes:**
+Explore the full documentation in the [docs](docs/) directory:
+- [API Reference](docs/index.md)
 - [Workflow API](docs/classes/workflow.md)
 - [Step API](docs/classes/steps/step.md)
 - [State Management](docs/classes/state.md)
-
-**Logic Steps:**
-- [LogicStep API](docs/classes/steps/logic_step.md)
-- [ConditionalStep API](docs/classes/steps/conditional_step.md)
-- [FlowControlStep API](docs/classes/steps/flow_control_step.md)
-- [CaseStep API](docs/classes/steps/case.md)
-- [SwitchStep API](docs/classes/steps/switch_step.md)
-- [LoopStep API](docs/classes/steps/loop_step.md)
-- [DelayStep API](docs/classes/steps/delay_step.md)
-
-**Events:**
-- [Event System](docs/classes/events/event.md)
-- [WorkflowEvent API](docs/classes/events/workflow_event.md)
-- [StepEvent API](docs/classes/events/step_event.md)
-- [StateEvent API](docs/classes/events/state_event.md)
-
-
-**Enumerations:**
-- [Base Types](docs/enums/base_types.md)
-- [Step Types](docs/enums/step_types.md)
-- [Sub Step Types](docs/enums/sub_step_types.md)
-- [Logic Step Types](docs/enums/logic_step_types.md)
-- [Conditional Step Comparators](docs/enums/conditional_step_comparators.md)
-- [Flow Control Types](docs/enums/flow_control_types.md)
-- [Step Statuses](docs/enums/step_statuses.md)
-- [Workflow Statuses](docs/enums/workflow_statuses.md)
-- [Step Event Names](docs/enums/step_event_names.md)
-- [Workflow Event Names](docs/enums/workflow_event_names.md)
-- [State Event Names](docs/enums/state_event_names.md)
-- [Delay Types](docs/enums/delay_types.md)
-- [Loop Types](docs/enums/loop_types.md)
-- [Errors and Warnings](docs/enums/errors.md)

package/dist/src/classes/registry.js

@@ -0,0 +1,2 @@
+var o=Object.defineProperty;var e=(s,t)=>o(s,"name",{value:t,configurable:!0});import"./steps/index.js";const r=Symbol.for("@ronaldroe/micro-flow/registry");globalThis[r]||(globalThis[r]=new Map);class g{static{e(this,"Registry")}static get registry(){return globalThis[r]}static register(t,i){this.registry.set(t,i)}static get(t){return this.registry.get(t)}}export{g as default};
+//# sourceMappingURL=registry.js.map

package/dist/src/classes/registry.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/classes/registry.js"],
+  "sourcesContent": ["import * as Steps from './steps/index.js';\n\nconst _REGISTRY_KEY = Symbol.for('@ronaldroe/micro-flow/registry');\n\nif (!globalThis[_REGISTRY_KEY]) {\n  globalThis[_REGISTRY_KEY] = new Map();\n}\n\nexport default class Registry {\n  static get registry() {\n    return globalThis[_REGISTRY_KEY];\n  }\n\n  static register(name, stepClass) {\n    this.registry.set(name, stepClass);\n  }\n\n  static get(name) {\n    return this.registry.get(name);\n  }\n}\n"],
+  "mappings": "+EAAA,MAAuB,mBAEvB,MAAMA,EAAgB,OAAO,IAAI,gCAAgC,EAE5D,WAAWA,CAAa,IAC3B,WAAWA,CAAa,EAAI,IAAI,KAGlC,MAAOC,CAAuB,CAR9B,MAQ8B,CAAAC,EAAA,iBAC5B,WAAW,UAAW,CACpB,OAAO,WAAWF,CAAa,CACjC,CAEA,OAAO,SAASG,EAAMC,EAAW,CAC/B,KAAK,SAAS,IAAID,EAAMC,CAAS,CACnC,CAEA,OAAO,IAAID,EAAM,CACf,OAAO,KAAK,SAAS,IAAIA,CAAI,CAC/B,CACF",
+  "names": ["_REGISTRY_KEY", "Registry", "__name", "name", "stepClass"]
+}

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export*from"./classes/index.js";export*from"./enums/index.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/index.js"],
+  "sourcesContent": ["export * from './classes/index.js';\nexport * from './enums/index.js';\n"],
+  "mappings": "AAAA,WAAc,qBACd,WAAc",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ronaldroe/micro-flow",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "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/registry.js

@@ -0,0 +1,21 @@
+import * as Steps from './steps/index.js';
+
+const _REGISTRY_KEY = Symbol.for('@ronaldroe/micro-flow/registry');
+
+if (!globalThis[_REGISTRY_KEY]) {
+  globalThis[_REGISTRY_KEY] = new Map();
+}
+
+export default class Registry {
+  static get registry() {
+    return globalThis[_REGISTRY_KEY];
+  }
+
+  static register(name, stepClass) {
+    this.registry.set(name, stepClass);
+  }
+
+  static get(name) {
+    return this.registry.get(name);
+  }
+}