@onlineapps/conn-orch-orchestrator 1.0.0

package/README.md

@@ -0,0 +1,585 @@
+<a name="module_@onlineapps/conn-orch-orchestrator"></a>
+
+## @onlineapps/conn-orch-orchestrator
+Workflow orchestration coordinator managing complete workflow execution.
+Provides centralized control flow handling, step routing, and workflow state management
+for OA Drive microservices.
+
+**See**: [GitHub Repository](https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-orch-orchestrator)  
+**Since**: 1.0.0  
+**Author**: OA Drive Team  
+**License**: MIT  
+
+* [@onlineapps/conn-orch-orchestrator](#module_@onlineapps/conn-orch-orchestrator)
+    * _static_
+        * [.VERSION](#module_@onlineapps/conn-orch-orchestrator.VERSION) : <code>string</code>
+    * _inner_
+        * [~OrchestratorConnector](#module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector)
+            * [new OrchestratorConnector()](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
+            * [new OrchestratorConnector(config)](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
+        * [~OrchestratorConnector](#module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector)
+            * [new OrchestratorConnector()](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
+            * [new OrchestratorConnector(config)](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
+        * [~processWorkflowMessage(message)](#module_@onlineapps/conn-orch-orchestrator..processWorkflowMessage) ⇒ <code>Promise.&lt;WorkflowResult&gt;</code> \| <code>boolean</code> \| <code>string</code> \| <code>number</code>
+        * [~processStep(message)](#module_@onlineapps/conn-orch-orchestrator..processStep) ⇒ <code>Promise.&lt;\*&gt;</code>
+        * [~handleControlFlow(step, message)](#module_@onlineapps/conn-orch-orchestrator..handleControlFlow) ⇒ <code>Promise.&lt;\*&gt;</code>
+        * [~handleIfStep(step, message)](#module_@onlineapps/conn-orch-orchestrator..handleIfStep) ⇒ <code>Promise.&lt;\*&gt;</code>
+        * [~handleForeachStep(step, message)](#module_@onlineapps/conn-orch-orchestrator..handleForeachStep) ⇒ <code>Promise.&lt;Array&gt;</code>
+        * [~handleForkJoinStep(step, message)](#module_@onlineapps/conn-orch-orchestrator..handleForkJoinStep) ⇒ <code>Promise.&lt;\*&gt;</code>
+        * [~handleSwitchStep(step, message)](#module_@onlineapps/conn-orch-orchestrator..handleSwitchStep) ⇒ <code>Promise.&lt;\*&gt;</code>
+        * [~routeToNextService(message, nextService, stepResult, nextIndex)](#module_@onlineapps/conn-orch-orchestrator..routeToNextService) ⇒ <code>Promise.&lt;void&gt;</code>
+        * [~completeWorkflow(message, finalResult)](#module_@onlineapps/conn-orch-orchestrator..completeWorkflow) ⇒ <code>Promise.&lt;void&gt;</code>
+        * [~handleWorkflowFailure(message, error)](#module_@onlineapps/conn-orch-orchestrator..handleWorkflowFailure) ⇒ <code>Promise.&lt;void&gt;</code>
+        * [~getStats()](#module_@onlineapps/conn-orch-orchestrator..getStats) ⇒ <code>OrchestratorStats</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code>
+        * [~resetStats()](#module_@onlineapps/conn-orch-orchestrator..resetStats) ⇒ <code>void</code>
+        * [~create(config)](#module_@onlineapps/conn-orch-orchestrator..create) ⇒ <code>OrchestratorConnector</code>
+        * [~WorkflowMessage](#module_@onlineapps/conn-orch-orchestrator..WorkflowMessage) : <code>Object</code>
+        * [~WorkflowResult](#module_@onlineapps/conn-orch-orchestrator..WorkflowResult) : <code>Object</code>
+        * [~ControlFlowStep](#module_@onlineapps/conn-orch-orchestrator..ControlFlowStep) : <code>Object</code>
+        * [~OrchestratorStats](#module_@onlineapps/conn-orch-orchestrator..OrchestratorStats) : <code>Object</code>
+
+<a name="module_@onlineapps/conn-orch-orchestrator.VERSION"></a>
+
+### @onlineapps/conn-orch-orchestrator.VERSION : <code>string</code>
+Current version
+
+**Kind**: static constant of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+<a name="module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector"></a>
+
+### @onlineapps/conn-orch-orchestrator~OrchestratorConnector
+**Kind**: inner class of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+
+* [~OrchestratorConnector](#module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector)
+    * [new OrchestratorConnector()](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
+    * [new OrchestratorConnector(config)](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
+
+<a name="new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new"></a>
+
+#### new OrchestratorConnector()
+Workflow orchestration connector managing complete workflow execution
+
+**Example** *(Basic Usage)*  
+```js
+const orchestrator = new OrchestratorConnector({
+  mqClient: mqConnector,
+  cookbook: cookbookConnector,
+  apiMapper: apiMapperConnector,
+  serviceName: 'invoice-service'
+});
+
+await orchestrator.processWorkflowMessage(message);
+```
+**Example** *(With Caching)*  
+```js
+const orchestrator = new OrchestratorConnector({
+  mqClient: mqConnector,
+  cookbook: cookbookConnector,
+  apiMapper: apiMapperConnector,
+  cache: cacheConnector,
+  serviceName: 'invoice-service',
+  defaultTimeout: 60000
+});
+```
+<a name="new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new"></a>
+
+#### new OrchestratorConnector(config)
+Creates a new OrchestratorConnector instance
+
+**Throws**:
+
+- <code>TypeError</code> If required dependencies are missing
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| config | <code>Object</code> |  | Configuration object |
+| config.mqClient | <code>Object</code> |  | MQ client connector for message routing |
+| config.cookbook | <code>Object</code> |  | Cookbook connector for workflow parsing |
+| [config.apiMapper] | <code>Object</code> |  | API mapper for HTTP calls |
+| [config.cache] | <code>Object</code> |  | Cache connector for step caching |
+| [config.logger] | <code>Object</code> | <code>console</code> | Logger instance |
+| [config.serviceName] | <code>string</code> | <code>&quot;&#x27;unknown&#x27;&quot;</code> | Service name for tracing |
+| [config.defaultTimeout] | <code>number</code> | <code>30000</code> | Default timeout in ms |
+| [config.maxStepRetries] | <code>number</code> | <code>3</code> | Maximum retries per step |
+
+**Example** *(Full Configuration)*  
+```js
+const orchestrator = new OrchestratorConnector({
+  mqClient: mqConnector,
+  cookbook: cookbookConnector,
+  apiMapper: apiMapperConnector,
+  cache: cacheConnector,
+  logger: loggerConnector,
+  serviceName: 'invoice-service',
+  defaultTimeout: 60000,
+  maxStepRetries: 5
+});
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector"></a>
+
+### @onlineapps/conn-orch-orchestrator~OrchestratorConnector
+**Kind**: inner class of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+
+* [~OrchestratorConnector](#module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector)
+    * [new OrchestratorConnector()](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
+    * [new OrchestratorConnector(config)](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
+
+<a name="new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new"></a>
+
+#### new OrchestratorConnector()
+Workflow orchestration connector managing complete workflow execution
+
+**Example** *(Basic Usage)*  
+```js
+const orchestrator = new OrchestratorConnector({
+  mqClient: mqConnector,
+  cookbook: cookbookConnector,
+  apiMapper: apiMapperConnector,
+  serviceName: 'invoice-service'
+});
+
+await orchestrator.processWorkflowMessage(message);
+```
+**Example** *(With Caching)*  
+```js
+const orchestrator = new OrchestratorConnector({
+  mqClient: mqConnector,
+  cookbook: cookbookConnector,
+  apiMapper: apiMapperConnector,
+  cache: cacheConnector,
+  serviceName: 'invoice-service',
+  defaultTimeout: 60000
+});
+```
+<a name="new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new"></a>
+
+#### new OrchestratorConnector(config)
+Creates a new OrchestratorConnector instance
+
+**Throws**:
+
+- <code>TypeError</code> If required dependencies are missing
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| config | <code>Object</code> |  | Configuration object |
+| config.mqClient | <code>Object</code> |  | MQ client connector for message routing |
+| config.cookbook | <code>Object</code> |  | Cookbook connector for workflow parsing |
+| [config.apiMapper] | <code>Object</code> |  | API mapper for HTTP calls |
+| [config.cache] | <code>Object</code> |  | Cache connector for step caching |
+| [config.logger] | <code>Object</code> | <code>console</code> | Logger instance |
+| [config.serviceName] | <code>string</code> | <code>&quot;&#x27;unknown&#x27;&quot;</code> | Service name for tracing |
+| [config.defaultTimeout] | <code>number</code> | <code>30000</code> | Default timeout in ms |
+| [config.maxStepRetries] | <code>number</code> | <code>3</code> | Maximum retries per step |
+
+**Example** *(Full Configuration)*  
+```js
+const orchestrator = new OrchestratorConnector({
+  mqClient: mqConnector,
+  cookbook: cookbookConnector,
+  apiMapper: apiMapperConnector,
+  cache: cacheConnector,
+  logger: loggerConnector,
+  serviceName: 'invoice-service',
+  defaultTimeout: 60000,
+  maxStepRetries: 5
+});
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..processWorkflowMessage"></a>
+
+### @onlineapps/conn-orch-orchestrator~processWorkflowMessage(message) ⇒ <code>Promise.&lt;WorkflowResult&gt;</code> \| <code>boolean</code> \| <code>string</code> \| <code>number</code>
+Process workflow message - main entry point
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Returns**: <code>Promise.&lt;WorkflowResult&gt;</code> - Processing result<code>boolean</code> - result.success - Whether processing succeeded<code>string</code> - result.workflowId - Workflow ID<code>number</code> - result.duration - Processing duration in ms  
+**Throws**:
+
+- <code>Error</code> If cookbook validation fails
+- <code>Error</code> If step processing fails
+
+**Emits**: [<code>completed</code>](#OrchestratorConnector+workflow.event_completed), [<code>failed</code>](#OrchestratorConnector+workflow.event_failed)  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| message | <code>WorkflowMessage</code> |  | Workflow message to process |
+| [message.workflow_id] | <code>string</code> |  | Unique workflow ID |
+| message.cookbook | <code>Object</code> |  | Cookbook definition |
+| [message.current_step] | <code>number</code> | <code>0</code> | Current step index |
+| [message.context] | <code>Object</code> | <code>{}</code> | Workflow context data |
+| [message.trace] | <code>Array</code> | <code>[]</code> | Execution trace |
+
+**Example** *(Process Workflow)*  
+```js
+const result = await orchestrator.processWorkflowMessage({
+  workflow_id: 'wf-123',
+  cookbook: cookbookDef,
+  current_step: 0,
+  context: { invoice_id: 'inv-456' }
+});
+
+if (result.success) {
+  console.log(`Workflow completed in ${result.duration}ms`);
+}
+```
+**Example** *(With Error Handling)*  
+```js
+try {
+  await orchestrator.processWorkflowMessage(message);
+} catch (error) {
+  console.error('Workflow failed:', error);
+  // Message sent to DLQ automatically
+}
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..processStep"></a>
+
+### @onlineapps/conn-orch-orchestrator~processStep(message) ⇒ <code>Promise.&lt;\*&gt;</code>
+Process single workflow step
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Returns**: <code>Promise.&lt;\*&gt;</code> - Step execution result  
+**Throws**:
+
+- <code>Error</code> If step not found in cookbook
+- <code>Error</code> If API call fails and onError is not 'continue'
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| message | <code>WorkflowMessage</code> | Workflow message with step info |
+
+**Example** *(Process Regular Step)*  
+```js
+const result = await orchestrator.processStep({
+  cookbook: cookbook,
+  current_step: 2,
+  context: { data: 'value' }
+});
+```
+**Example** *(Process Control Flow Step)*  
+```js
+const result = await orchestrator.processStep({
+  cookbook: { steps: [{ type: 'foreach', items: [...] }] },
+  current_step: 0
+});
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..handleControlFlow"></a>
+
+### @onlineapps/conn-orch-orchestrator~handleControlFlow(step, message) ⇒ <code>Promise.&lt;\*&gt;</code>
+Handle control flow steps (if, foreach, fork_join, switch)
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Returns**: <code>Promise.&lt;\*&gt;</code> - Control flow execution result  
+**Throws**:
+
+- <code>Error</code> If unknown control flow type
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| step | <code>ControlFlowStep</code> | Control flow step definition |
+| step.type | <code>string</code> | Type: 'if', 'foreach', 'fork_join', 'switch' |
+| message | <code>WorkflowMessage</code> | Workflow message |
+
+**Example** *(If/Else Flow)*  
+```js
+await orchestrator.handleControlFlow({
+  type: 'if',
+  condition: '${amount} > 1000',
+  then: { service: 'approval', operation: 'request' },
+  else: { service: 'payment', operation: 'process' }
+}, message);
+```
+**Example** *(Foreach Iteration)*  
+```js
+await orchestrator.handleControlFlow({
+  type: 'foreach',
+  items: '${invoices}',
+  do: { service: 'invoice', operation: 'process' }
+}, message);
+```
+**Example** *(Fork-Join Parallel)*  
+```js
+await orchestrator.handleControlFlow({
+  type: 'fork_join',
+  branches: [
+    { service: 'inventory', operation: 'check' },
+    { service: 'pricing', operation: 'calculate' }
+  ],
+  joinStrategy: 'merge'
+}, message);
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..handleIfStep"></a>
+
+### @onlineapps/conn-orch-orchestrator~handleIfStep(step, message) ⇒ <code>Promise.&lt;\*&gt;</code>
+Handle if/else control flow
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Returns**: <code>Promise.&lt;\*&gt;</code> - Branch execution result or null  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| step | <code>IfStep</code> | If step definition |
+| step.condition | <code>string</code> | Condition expression |
+| [step.then] | <code>Object</code> | Branch for true condition |
+| [step.else] | <code>Object</code> | Branch for false condition |
+| message | <code>WorkflowMessage</code> | Workflow message |
+
+**Example**  
+```js
+await orchestrator.handleIfStep({
+  condition: '${status} === "pending"',
+  then: { service: 'approval', operation: 'request' },
+  else: { service: 'notification', operation: 'send' }
+}, message);
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..handleForeachStep"></a>
+
+### @onlineapps/conn-orch-orchestrator~handleForeachStep(step, message) ⇒ <code>Promise.&lt;Array&gt;</code>
+Handle foreach iteration
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Returns**: <code>Promise.&lt;Array&gt;</code> - Array of results from each iteration  
+**Throws**:
+
+- <code>Error</code> If items is not an array
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| step | <code>ForeachStep</code> | Foreach step definition |
+| step.items | <code>string</code> \| <code>Array</code> | Items to iterate (or path to items) |
+| step.do | <code>Object</code> | Step to execute for each item |
+| message | <code>WorkflowMessage</code> | Workflow message |
+
+**Example**  
+```js
+const results = await orchestrator.handleForeachStep({
+  items: '${invoice.line_items}',
+  do: { service: 'tax', operation: 'calculate' }
+}, message);
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..handleForkJoinStep"></a>
+
+### @onlineapps/conn-orch-orchestrator~handleForkJoinStep(step, message) ⇒ <code>Promise.&lt;\*&gt;</code>
+Handle fork-join parallel execution
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Returns**: <code>Promise.&lt;\*&gt;</code> - Joined results based on strategy  
+**Throws**:
+
+- <code>Error</code> If MQ client doesn't support fork-join
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| step | <code>ForkJoinStep</code> |  | Fork-join step definition |
+| step.branches | <code>Array.&lt;Object&gt;</code> |  | Parallel branches to execute |
+| [step.joinStrategy] | <code>string</code> | <code>&quot;&#x27;merge&#x27;&quot;</code> | Join strategy: 'merge', 'array', 'first' |
+| [step.timeout] | <code>number</code> |  | Overall timeout for all branches |
+| message | <code>WorkflowMessage</code> |  | Workflow message |
+
+**Example**  
+```js
+const result = await orchestrator.handleForkJoinStep({
+  branches: [
+    { service: 'inventory', operation: 'reserve' },
+    { service: 'payment', operation: 'authorize' },
+    { service: 'shipping', operation: 'estimate' }
+  ],
+  joinStrategy: 'merge',
+  timeout: 10000
+}, message);
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..handleSwitchStep"></a>
+
+### @onlineapps/conn-orch-orchestrator~handleSwitchStep(step, message) ⇒ <code>Promise.&lt;\*&gt;</code>
+Handle switch statement
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Returns**: <code>Promise.&lt;\*&gt;</code> - Matched case execution result or null  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| step | <code>SwitchStep</code> | Switch step definition |
+| step.value | <code>string</code> | Value expression to switch on |
+| step.cases | <code>Array.&lt;Object&gt;</code> | Case definitions |
+| [step.default] | <code>Object</code> | Default case |
+| message | <code>WorkflowMessage</code> | Workflow message |
+
+**Example**  
+```js
+await orchestrator.handleSwitchStep({
+  value: '${order.type}',
+  cases: [
+    { value: 'standard', do: { service: 'shipping', operation: 'standard' } },
+    { value: 'express', do: { service: 'shipping', operation: 'express' } }
+  ],
+  default: { do: { service: 'shipping', operation: 'economy' } }
+}, message);
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..routeToNextService"></a>
+
+### @onlineapps/conn-orch-orchestrator~routeToNextService(message, nextService, stepResult, nextIndex) ⇒ <code>Promise.&lt;void&gt;</code>
+Route to next service in workflow
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Emits**: <code>MQClient#event:publish - Publishes to next service queue</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| message | <code>WorkflowMessage</code> | Current workflow message |
+| nextService | <code>string</code> | Next service name |
+| stepResult | <code>\*</code> | Current step result |
+| nextIndex | <code>number</code> | Next step index |
+
+**Example**  
+```js
+await orchestrator.routeToNextService(
+  message,
+  'invoice-service',
+  { processed: true, total: 1500 },
+  3
+);
+// Message published to 'invoice-service.workflow' queue
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..completeWorkflow"></a>
+
+### @onlineapps/conn-orch-orchestrator~completeWorkflow(message, finalResult) ⇒ <code>Promise.&lt;void&gt;</code>
+Complete workflow
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Emits**: <code>MQClient#workflow.event:completed - Workflow completion event</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| message | <code>WorkflowMessage</code> | Workflow message |
+| finalResult | <code>\*</code> | Final workflow result |
+
+**Example**  
+```js
+await orchestrator.completeWorkflow(message, {
+  status: 'success',
+  invoice_id: 'inv-789',
+  total: 1500
+});
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..handleWorkflowFailure"></a>
+
+### @onlineapps/conn-orch-orchestrator~handleWorkflowFailure(message, error) ⇒ <code>Promise.&lt;void&gt;</code>
+Handle workflow failure
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Emits**: <code>MQClient#workflow.event:dlq - Sends to dead letter queue</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| message | <code>WorkflowMessage</code> | Workflow message |
+| error | <code>Error</code> | Failure error |
+
+**Example**  
+```js
+await orchestrator.handleWorkflowFailure(message,
+  new Error('Service unavailable')
+);
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..getStats"></a>
+
+### @onlineapps/conn-orch-orchestrator~getStats() ⇒ <code>OrchestratorStats</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code>
+Get orchestrator statistics
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Returns**: <code>OrchestratorStats</code> - Current statistics<code>number</code> - stats.started - Workflows started<code>number</code> - stats.completed - Workflows completed<code>number</code> - stats.failed - Workflows failed<code>number</code> - stats.steps - Total steps processed<code>number</code> - stats.avgDuration - Average duration in ms<code>number</code> - stats.activeWorkflows - Currently active workflows  
+**Example**  
+```js
+const stats = orchestrator.getStats();
+console.log(`Success rate: ${stats.completed / stats.started * 100}%`);
+console.log(`Average duration: ${stats.avgDuration}ms`);
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..resetStats"></a>
+
+### @onlineapps/conn-orch-orchestrator~resetStats() ⇒ <code>void</code>
+Reset statistics
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Example**  
+```js
+orchestrator.resetStats();
+// All counters reset to 0
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..create"></a>
+
+### @onlineapps/conn-orch-orchestrator~create(config) ⇒ <code>OrchestratorConnector</code>
+Factory function to create orchestrator instance
+
+**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Returns**: <code>OrchestratorConnector</code> - New orchestrator instance  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| config | <code>Object</code> | Configuration object |
+
+**Example**  
+```js
+const orchestrator = OrchestratorConnector.create({
+  mqClient: mqConnector,
+  cookbook: cookbookConnector,
+  serviceName: 'invoice-service'
+});
+```
+<a name="module_@onlineapps/conn-orch-orchestrator..WorkflowMessage"></a>
+
+### @onlineapps/conn-orch-orchestrator~WorkflowMessage : <code>Object</code>
+**Kind**: inner typedef of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Properties**
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| [workflow_id] | <code>string</code> |  | Unique workflow identifier |
+| cookbook | <code>Object</code> |  | Cookbook definition |
+| [current_step] | <code>number</code> | <code>0</code> | Current step index |
+| [context] | <code>Object</code> | <code>{}</code> | Workflow context data |
+| [trace] | <code>Array</code> | <code>[]</code> | Execution trace |
+| [correlation_id] | <code>string</code> |  | Correlation ID for tracing |
+
+<a name="module_@onlineapps/conn-orch-orchestrator..WorkflowResult"></a>
+
+### @onlineapps/conn-orch-orchestrator~WorkflowResult : <code>Object</code>
+**Kind**: inner typedef of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| success | <code>boolean</code> | Whether workflow succeeded |
+| workflowId | <code>string</code> | Workflow identifier |
+| duration | <code>number</code> | Processing duration in ms |
+
+<a name="module_@onlineapps/conn-orch-orchestrator..ControlFlowStep"></a>
+
+### @onlineapps/conn-orch-orchestrator~ControlFlowStep : <code>Object</code>
+**Kind**: inner typedef of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| type | <code>string</code> | Control flow type: 'if', 'foreach', 'fork_join', 'switch' |
+| [condition] | <code>\*</code> | Condition for if steps |
+| [items] | <code>\*</code> | Items for foreach steps |
+| [branches] | <code>Array</code> | Branches for fork_join |
+| [value] | <code>string</code> | Value for switch steps |
+
+<a name="module_@onlineapps/conn-orch-orchestrator..OrchestratorStats"></a>
+
+### @onlineapps/conn-orch-orchestrator~OrchestratorStats : <code>Object</code>
+**Kind**: inner typedef of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| started | <code>number</code> | Workflows started |
+| completed | <code>number</code> | Workflows completed |
+| failed | <code>number</code> | Workflows failed |
+| steps | <code>number</code> | Total steps processed |
+| avgDuration | <code>number</code> | Average duration in ms |
+| activeWorkflows | <code>number</code> | Currently active workflows |
+

package/jest.config.js

@@ -0,0 +1,29 @@
+module.exports = {
+  testEnvironment: 'node',
+  coverageDirectory: 'coverage',
+  collectCoverageFrom: [
+    'src/**/*.js',
+    '!src/**/*.test.js'
+  ],
+  testMatch: [
+    '**/test/unit/**/*.test.js',
+    '**/test/component/**/*.test.js',
+    '**/test/integration/**/*.test.js'
+  ],
+  testPathIgnorePatterns: [
+    '/node_modules/'
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 80,
+      functions: 80,
+      lines: 80,
+      statements: 80
+    }
+  },
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1'
+  },
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
+  testTimeout: 10000
+};

package/jest.setup.js

@@ -0,0 +1,38 @@
+// Jest setup file for orchestrator tests
+
+// Increase timeout for integration tests
+if (process.env.TEST_TYPE === 'integration') {
+  jest.setTimeout(30000);
+}
+
+// Mock console methods to reduce noise during tests
+global.console = {
+  ...console,
+  error: jest.fn(),
+  warn: jest.fn(),
+  // Keep info and debug for debugging
+  info: console.info,
+  debug: console.debug,
+  log: console.log
+};
+
+// Add custom matchers if needed
+expect.extend({
+  toBeWorkflowMessage(received) {
+    const pass = received &&
+      typeof received === 'object' &&
+      'workflow_id' in received &&
+      'current_step' in received;
+
+    return {
+      pass,
+      message: () => pass
+        ? `expected ${received} not to be a workflow message`
+        : `expected ${received} to be a workflow message with workflow_id and current_step`
+    };
+  }
+});
+
+// Setup test environment variables
+process.env.NODE_ENV = 'test';
+process.env.LOG_LEVEL = 'error';