@6thbridge/utils 1.8.2-3 → 1.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@6thbridge/utils",
-  "version": "1.8.2-3",
+  "version": "1.8.3",
   "description": "simple interface for the our commonly used functions",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/readme.md

@@ -7,6 +7,7 @@ A comprehensive TypeScript utility library for Node.js applications, providing r
 - [Core Modules](#core-modules)
 - [API Reference](#api-reference)
 - [Examples](#examples)
+- [Pipelines](#pipelines)
 - [Testing](#testing)
 - [Contributing](#contributing)
 - [License](#license)
@@ -290,6 +291,93 @@ LOG_OUT=1
 # Service URLs
 USER_SERVICE_URL=http://user-service:3000
 ```
+## Pipelines
+
+`SerialPipeline` passes each executed step's result to the next step. `ParallelPipeline`
+runs independent steps concurrently with the same initial input and returns named results.
+Both accept the existing `ContextEntity` as the first argument on every invocation; the
+pipeline never stores context.
+
+Every step must provide `shouldRun(contextEntity, input): Promise<boolean>` and
+`run(contextEntity, input): Promise<Result>`. Implementers choose the result type.
+Register objects or class instances with `.pipe(name, step)`. Names must be unique.
+Registration returns a new pipeline, so retain the returned instance or chain calls.
+
+### Serial transformations and skipped steps
+
+```typescript
+import { ContextEntity, PipelineStep, SerialPipeline } from '@6thbridge/utils';
+
+class MeasureText implements PipelineStep<string, number> {
+  constructor(private minimumLength: number) {}
+
+  async shouldRun(contextEntity: ContextEntity, input: string): Promise<boolean> {
+    return input.length >= this.minimumLength;
+  }
+
+  async run(contextEntity: ContextEntity, input: string): Promise<number> {
+    return input.length;
+  }
+}
+
+const pipeline = new SerialPipeline<string>()
+  .pipe('measure', new MeasureText(3))
+  .pipe('describe', {
+    async shouldRun(contextEntity, input) {
+      return true;
+    },
+    async run(contextEntity, input) {
+      // input is string | number: skipped measurement forwards the original string.
+      return typeof input === 'number' ? `Length: ${input}` : `Unmeasured: ${input}`;
+    },
+  });
+
+const contextEntity = new ContextEntity();
+await pipeline.run(contextEntity, 'hello'); // "Length: 5"
+await pipeline.run(new ContextEntity(), 'hi'); // "Unmeasured: hi"
+```
+
+Serial execution awaits each predicate and result in registration order. A skipped step
+forwards its input unchanged, so downstream input and the final result include the types
+of values that may pass through skipped steps. Class instance methods retain their `this`.
+
+### Named parallel results
+
+```typescript
+import { ContextEntity, ParallelPipeline } from '@6thbridge/utils';
+
+const pipeline = new ParallelPipeline<string>()
+  .pipe('length', {
+    async shouldRun(contextEntity, input) {
+      return true;
+    },
+    async run(contextEntity, input) {
+      return input.length;
+    },
+  })
+  .pipe('uppercase', {
+    async shouldRun(contextEntity, input) {
+      return input.length > 0;
+    },
+    async run(contextEntity, input) {
+      return input.toUpperCase();
+    },
+  });
+
+const results = await pipeline.run(new ContextEntity(), 'hello');
+// { length: 5, uppercase: 'HELLO' }
+// Inferred properties: length?: number; uppercase?: string.
+```
+
+Parallel predicates and executions run independently. Skipped steps are omitted from the
+result object; executed steps returning `undefined` still have a result property. Result
+keys follow registration order regardless of completion order.
+
+Both pipelines reject errors from `shouldRun` or `run`. Serial execution stops before the
+next step; already started parallel work continues. Empty serial pipelines return their
+input, and empty parallel pipelines return `{}`. Pipelines can be reused concurrently
+with different contexts and inputs; callers manage any mutable state inside their steps.
+
 ## Testing
 The library includes comprehensive test suites using Jest:
 ``` bash