@ronaldroe/micro-flow 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Starkey Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,581 @@
+# Micro-Flow
+
+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.
+
+## Features
+
+- 🚀 **Simple & Intuitive** - Easy-to-understand API for building workflows
+- 🔄 **Sequential Execution** - Run steps in order with automatic error handling
+- 🌿 **Conditional Logic** - Branch execution based on conditions
+- 🎯 **Flow Control** - Break, skip, or pause workflow execution
+- 📡 **Event-Driven** - Listen to workflow and step lifecycle events
+- 💾 **State Management** - Built-in global state with nested path access
+- 📢 **Cross-Tab/Worker Communication** - Broadcast messages between browser tabs/windows or between workers in your favorite JS runtime
+- 🌐 **Universal** - Works in Node.js and all modern browsers
+- ⚡ **Minimal Dependencies** - Lightweight and simple
+- 🎨 **Framework Friendly** - Integrates seamlessly with React, Vue, your favorite framework and vanilla JS
+
+## Installation
+
+```bash
+npm install --save micro-flow
+```
+
+## Quick Start
+
+### Node.js Example
+
+```javascript
+import { Workflow, Step } from 'micro-flow';
+
+// Create a simple workflow
+const workflow = new Workflow({
+  name: 'data-processor',
+  steps: [
+    new Step({
+      name: 'fetch-data',
+      callable: async () => {
+        const response = await fetch('https://api.example.com/data');
+        return response.json();
+      }
+    }),
+    new Step({
+      name: 'process-data',
+      callable: async () => {
+        console.log('Processing data...');
+        return { processed: true };
+      }
+    }),
+    new Step({
+      name: 'save-results',
+      callable: async () => {
+        console.log('Saving results...');
+        return { saved: true };
+      }
+    })
+  ]
+});
+
+// Execute the workflow
+const result = await workflow.execute();
+console.log('Workflow complete!', result.results);
+```
+
+### Browser Example
+
+```javascript
+import { Workflow, Step } from './micro-flow.js';
+
+const workflow = new Workflow({
+  name: 'ui-update',
+  steps: [
+    new Step({
+      name: 'show-loading',
+      callable: async () => {
+        document.getElementById('loader').style.display = 'block';
+      }
+    }),
+    new Step({
+      name: 'fetch-data',
+      callable: async () => {
+        const response = await fetch('/api/data');
+        return response.json();
+      }
+    }),
+    new Step({
+      name: 'update-ui',
+      callable: async () => {
+        document.getElementById('content').textContent = 'Data loaded!';
+        document.getElementById('loader').style.display = 'none';
+      }
+    })
+  ]
+});
+
+document.getElementById('loadBtn').addEventListener('click', () => {
+  workflow.execute();
+});
+```
+
+### React Example
+
+```javascript
+import { Workflow, Step, State } from './micro-flow.js';
+import { useState } from 'react';
+
+function DataFetcher() {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(false);
+
+  const fetchData = async () => {
+    const workflow = new Workflow({
+      name: 'fetch-workflow',
+      steps: [
+        new Step({
+          name: 'start',
+          callable: async () => {
+            setLoading(true);
+          }
+        }),
+        new Step({
+          name: 'fetch',
+          callable: async () => {
+            const res = await fetch('/api/data');
+            const json = await res.json();
+            setData(json);
+          }
+        }),
+        new Step({
+          name: 'complete',
+          callable: async () => {
+            setLoading(false);
+          }
+        })
+      ]
+    });
+
+    await workflow.execute();
+  };
+
+  return (
+    <div>
+      <button onClick={fetchData} disabled={loading}>
+        {loading ? 'Loading...' : 'Fetch Data'}
+      </button>
+      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+    </div>
+  );
+}
+```
+
+### Vue Example
+
+```vue
+<template>
+  <div>
+    <button @click="runWorkflow" :disabled="isRunning">
+      {{ isRunning ? 'Processing...' : 'Run Workflow' }}
+    </button>
+    <p>{{ result }}</p>
+  </div>
+</template>
+
+<script setup>
+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',
+        callable: async () => {
+          isRunning.value = true;
+          await new Promise(resolve => setTimeout(resolve, 1000));
+          return 'Step 1 complete';
+        }
+      }),
+      new Step({
+        name: 'step-2',
+        callable: async () => {
+          await new Promise(resolve => setTimeout(resolve, 1000));
+          return 'Step 2 complete';
+        }
+      })
+    ]
+  });
+
+  const workflowResult = await workflow.execute();
+  result.value = 'Workflow complete!';
+  isRunning.value = false;
+};
+</script>
+```
+
+## 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 */]
+});
+```
+
+### Steps
+
+Steps are individual units of work that execute functions, other steps, or even entire workflows:
+
+```javascript
+import { Step } from 'micro-flow';
+
+const step = new Step({
+  name: 'my-step',
+  callable: async () => {
+    // Your async code here
+    return result;
+  }
+});
+```
+
+### Conditional Steps
+
+Execute different code paths based on conditions:
+
+```javascript
+import { ConditionalStep } from 'micro-flow';
+
+const conditionalStep = new ConditionalStep({
+  name: 'environment-check',
+  conditional: {
+    subject: process.env.NODE_ENV,
+    operator: '===',
+    value: 'production'
+  },
+  true_callable: async () => {
+    return loadProductionConfig();
+  },
+  false_callable: async () => {
+    return loadDevelopmentConfig();
+  }
+});
+```
+
+### Loop Steps
+
+Iterate over collections or repeat while conditions are met:
+
+```javascript
+import { LoopStep, loop_types } from 'micro-flow';
+
+// For-each loop
+const forEachLoop = new LoopStep({
+  name: 'process-items',
+  loop_type: loop_types.FOR_EACH,
+  items: [1, 2, 3, 4, 5],
+  callable: async (item) => {
+    console.log('Processing:', item);
+  }
+});
+
+// While loop
+const whileLoop = new LoopStep({
+  name: 'retry-until-success',
+  loop_type: loop_types.WHILE,
+  condition: () => retryCount < maxRetries,
+  callable: async () => {
+    await attemptOperation();
+  }
+});
+```
+
+### Delay Steps
+
+Delay workflow execution with various timing strategies:
+
+```javascript
+import { DelayStep, delay_types } from 'micro-flow';
+
+// Relative delay (milliseconds)
+const relativeDelay = new DelayStep({
+  name: 'wait-5-seconds',
+  delay_type: delay_types.RELATIVE,
+  delay_duration: 5000
+});
+
+// Absolute delay (specific time)
+const absoluteDelay = new DelayStep({
+  name: 'wait-until-midnight',
+  delay_type: delay_types.ABSOLUTE,
+  delay_timestamp: new Date('2025-12-31T23:59:59')
+});
+
+// Cron-based delay (scheduled)
+const cronDelay = new DelayStep({
+  name: 'daily-task',
+  delay_type: delay_types.CRON,
+  cron_expression: '0 9 * * *'  // Every day at 9 AM
+});
+```
+
+### Flow Control
+
+Control workflow execution with break and skip logic:
+
+```javascript
+import { FlowControlStep, flow_control_types } from 'micro-flow';
+
+const breakStep = new FlowControlStep({
+  name: 'error-check',
+  conditional: {
+    subject: errorCount,
+    operator: '>',
+    value: 0
+  },
+  flow_control_type: flow_control_types.BREAK
+});
+```
+
+### State Management
+
+Access global state across all workflows and steps:
+
+```javascript
+import { State } from 'micro-flow';
+
+// Set values
+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');
+```
+
+### Events
+
+Listen to workflow and step lifecycle events. You can do this using Node's EventEmitter syntax or the browser's CustomEvent syntax:
+
+```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);
+});
+```
+
+### Cross-Tab/Worker Communication
+
+Broadcast messages between browser tabs and windows:
+
+```javascript
+import { Broadcast } from './micro-flow.js';
+
+const broadcast = new Broadcast('my-channel');
+
+// Send messages to other tabs
+broadcast.send({ type: 'update', data: { userId: 123 } });
+
+// Receive messages from other tabs
+broadcast.onReceive((data) => {
+  console.log('Message from another tab:', data);
+  if (data.type === 'update') {
+    updateUI(data.data);
+  }
+});
+
+// Clean up when done
+broadcast.destroy();
+```
+
+## 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
+
+```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!';
+        }
+      })
+    ]
+  });
+}
+```
+
+## 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:**
+- [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)
+
+**Events:**
+- [Event System](docs/classes/events/event.md)
+- [WorkflowEvent API](docs/classes/events/workflow_event.md)
+- [StepEvent API](docs/classes/events/step_event.md)
+- [Broadcast API](docs/classes/events/broadcast.md)
+
+**Enumerations:**
+- [Step Types](docs/enums/step_types.md)
+- [Step Statuses](docs/enums/step_statuses.md)
+- [Workflow Statuses](docs/enums/workflow_statuses.md)
+- [Delay Types](docs/enums/delay_types.md)
+- [Loop Types](docs/enums/loop_types.md)
+
+## Browser Compatibility
+
+Micro-flow works in all modern browsers that support:
+- ES6 Modules
+- Async/await
+- CustomEvent API
+- EventTarget API
+
+Supported browsers:
+- Chrome/Edge 63+
+- Firefox 60+
+- Safari 11.1+
+- Opera 50+
+
+## Node.js Compatibility
+
+Requires Node.js 14+ for full ES6 module support.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Why Micro-Flow?
+
+Micro-flow is designed to be:
+
+- **Lightweight** - Small footprint, zero dependencies
+- **Simple** - Easy to learn and use
+- **Flexible** - Works in Node.js and browsers
+- **Powerful** - Handles complex workflows with ease
+- **Type-Safe Ready** - Can be extended with TypeScript definitions
+
+Perfect for projects that need workflow orchestration without the complexity of enterprise solutions.

package/index.js

@@ -0,0 +1 @@
+export * from './src/index.js';

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@ronaldroe/micro-flow",
+  "version": "1.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": "index.js",
+  "scripts": {
+    "build": "node build.js",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "workflow",
+    "orchestration",
+    "state-machine",
+    "flow-control",
+    "event-driven",
+    "browser",
+    "nodejs",
+    "state-management",
+    "sequential",
+    "process-automation"
+  ],
+  "author": "Starkey Software",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/starkeysoft/micro-flow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/starkeysoft/micro-flow/issues"
+  },
+  "homepage": "https://github.com/starkeysoft/micro-flow#readme",
+  "files": [
+    "index.js",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "date-fns": "^4.1.0",
+    "node-schedule": "^2.1.1",
+    "uuid": "^13.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.14",
+    "esbuild": "^0.27.0",
+    "vitest": "^4.0.14"
+  }
+}