@vinhnt-sdk/workflow 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nguyen Thanh Vinh
+
+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,71 @@
+# @vinhnt-sdk/workflow
+
+> Version: 0.4.0 | Status: BETA
+
+Workflow primitives for agent orchestration — parallel, sequential, conditional execution.
+
+## Install
+
+```bash
+# npm
+npm install @vinhnt-sdk/workflow
+
+# pnpm (monorepo)
+pnpm add @vinhnt-sdk/workflow
+```
+
+## Quick Start
+
+```typescript
+import { parallel, sequential, conditional } from '@vinhnt-sdk/workflow';
+
+// Parallel execution
+const results = await parallel([
+  { name: 'fetch-user', execute: async () => getUser() },
+  { name: 'fetch-posts', execute: async () => getPosts() },
+]);
+
+// Sequential execution
+const result = await sequential([
+  { name: 'validate', execute: async (input) => validate(input) },
+  { name: 'process', execute: async (input) => process(input) },
+  { name: 'save', execute: async (input) => save(input) },
+], initialInput);
+
+// Conditional execution
+const result = await conditional(input, [
+  {
+    condition: (input) => input.type === 'admin',
+    steps: [adminStep],
+    name: 'admin-path',
+  },
+  {
+    condition: () => true,
+    steps: [defaultStep],
+    name: 'default-path',
+  },
+]);
+```
+
+## Exports
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `WorkflowStep<TInput, TOutput>` | A single workflow step |
+| `WorkflowContext` | Context passed to each step |
+| `StepResult<T>` | Result of a workflow step |
+| `ConditionalBranch<TInput, TOutput>` | A conditional branch |
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `parallel(steps)` | Execute multiple steps in parallel |
+| `sequential(steps, input)` | Execute steps sequentially, chaining outputs |
+| `conditional(input, branches)` | Execute steps conditionally based on input |
+
+## Dependencies
+
+- `@vinhnt-sdk/schema`

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Workflow primitives for agent orchestration.
+ *
+ * Inspired by Google ADK workflow patterns.
+ * Provides parallel, sequential, and conditional execution.
+ *
+ * @module workflow
+ * @packageDocumentation
+ */
+/** Workflow step result */
+export interface StepResult<T = unknown> {
+    readonly success: boolean;
+    readonly output?: T;
+    readonly error?: Error | undefined;
+    readonly durationMs: number;
+}
+/** Workflow context passed to each step */
+export interface WorkflowContext {
+    readonly workflowId: string;
+    readonly stepIndex: number;
+    readonly metadata: Record<string, unknown>;
+    /** Abort signal for cancellation */
+    readonly signal?: AbortSignal | undefined;
+}
+/** A single workflow step */
+export interface WorkflowStep<TInput = unknown, TOutput = unknown> {
+    readonly name: string;
+    execute(input: TInput, ctx: WorkflowContext): Promise<TOutput>;
+}
+/**
+ * Execute multiple steps in parallel.
+ *
+ * @example
+ * ```ts
+ * const results = await parallel([
+ *   { name: "fetch-user", execute: async () => getUser() },
+ *   { name: "fetch-posts", execute: async () => getPosts() },
+ * ]);
+ * ```
+ */
+export declare function parallel<T>(steps: WorkflowStep<unknown, T>[], ctx?: Partial<WorkflowContext>): Promise<StepResult<T>[]>;
+/**
+ * Execute steps sequentially, passing output of one as input to the next.
+ *
+ * @example
+ * ```ts
+ * const result = await sequential([
+ *   { name: "validate", execute: async (input) => validate(input) },
+ *   { name: "process", execute: async (input) => process(input) },
+ *   { name: "save", execute: async (input) => save(input) },
+ * ], initialInput);
+ * ```
+ */
+export declare function sequential<TInput, TOutput>(steps: WorkflowStep<any, any>[], initialInput: TInput, ctx?: Partial<WorkflowContext>): Promise<StepResult<TOutput>>;
+/** A conditional branch */
+export interface ConditionalBranch<TInput = unknown, TOutput = unknown> {
+    readonly condition: (input: TInput) => boolean | Promise<boolean>;
+    readonly steps: WorkflowStep[];
+    readonly name?: string;
+}
+/**
+ * Execute steps conditionally based on input.
+ *
+ * @example
+ * ```ts
+ * const result = await conditional(input, [
+ *   {
+ *     condition: (input) => input.type === "admin",
+ *     steps: [adminStep],
+ *     name: "admin-path",
+ *   },
+ *   {
+ *     condition: () => true,
+ *     steps: [defaultStep],
+ *     name: "default-path",
+ *   },
+ * ]);
+ * ```
+ */
+export declare function conditional<TInput, TOutput>(input: TInput, branches: ConditionalBranch<TInput, TOutput>[], ctx?: Partial<WorkflowContext>): Promise<StepResult<TOutput>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,2BAA2B;AAC3B,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED,6BAA6B;AAC7B,MAAM,WAAW,YAAY,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChE;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EACjC,GAAG,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAC7B,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAc1B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,OAAO,EAC9C,KAAK,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAC/B,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAC7B,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAoC9B;AAMD,2BAA2B;AAC3B,MAAM,WAAW,iBAAiB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACpE,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,OAAO,EAC/C,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC9C,GAAG,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAC7B,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAkD9B"}

package/dist/index.js

@@ -0,0 +1,164 @@
+/**
+ * Workflow primitives for agent orchestration.
+ *
+ * Inspired by Google ADK workflow patterns.
+ * Provides parallel, sequential, and conditional execution.
+ *
+ * @module workflow
+ * @packageDocumentation
+ */
+// ---------------------------------------------------------------------------
+// Parallel Execution
+// ---------------------------------------------------------------------------
+/**
+ * Execute multiple steps in parallel.
+ *
+ * @example
+ * ```ts
+ * const results = await parallel([
+ *   { name: "fetch-user", execute: async () => getUser() },
+ *   { name: "fetch-posts", execute: async () => getPosts() },
+ * ]);
+ * ```
+ */
+export async function parallel(steps, ctx) {
+    const workflowId = ctx?.workflowId ?? `parallel-${Date.now()}`;
+    const metadata = ctx?.metadata ?? {};
+    return Promise.all(steps.map((step, i) => executeStep(step, undefined, {
+        workflowId,
+        stepIndex: i,
+        metadata,
+        signal: ctx?.signal,
+    })));
+}
+// ---------------------------------------------------------------------------
+// Sequential Execution
+// ---------------------------------------------------------------------------
+/**
+ * Execute steps sequentially, passing output of one as input to the next.
+ *
+ * @example
+ * ```ts
+ * const result = await sequential([
+ *   { name: "validate", execute: async (input) => validate(input) },
+ *   { name: "process", execute: async (input) => process(input) },
+ *   { name: "save", execute: async (input) => save(input) },
+ * ], initialInput);
+ * ```
+ */
+export async function sequential(steps, initialInput, ctx) {
+    const workflowId = ctx?.workflowId ?? `sequential-${Date.now()}`;
+    const metadata = ctx?.metadata ?? {};
+    let currentInput = initialInput;
+    let totalDuration = 0;
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        if (!step)
+            continue;
+        const result = await executeStep(step, currentInput, {
+            workflowId,
+            stepIndex: i,
+            metadata,
+            signal: ctx?.signal,
+        });
+        totalDuration += result.durationMs;
+        if (!result.success) {
+            return {
+                success: false,
+                error: result.error,
+                durationMs: totalDuration,
+            };
+        }
+        currentInput = result.output;
+    }
+    return {
+        success: true,
+        output: currentInput,
+        durationMs: totalDuration,
+    };
+}
+/**
+ * Execute steps conditionally based on input.
+ *
+ * @example
+ * ```ts
+ * const result = await conditional(input, [
+ *   {
+ *     condition: (input) => input.type === "admin",
+ *     steps: [adminStep],
+ *     name: "admin-path",
+ *   },
+ *   {
+ *     condition: () => true,
+ *     steps: [defaultStep],
+ *     name: "default-path",
+ *   },
+ * ]);
+ * ```
+ */
+export async function conditional(input, branches, ctx) {
+    const workflowId = ctx?.workflowId ?? `conditional-${Date.now()}`;
+    const metadata = ctx?.metadata ?? {};
+    for (let i = 0; i < branches.length; i++) {
+        const branch = branches[i];
+        if (!branch)
+            continue;
+        const shouldRun = await branch.condition(input);
+        if (shouldRun) {
+            let currentInput = input;
+            let totalDuration = 0;
+            for (let j = 0; j < branch.steps.length; j++) {
+                const step = branch.steps[j];
+                if (!step)
+                    continue;
+                const result = await executeStep(step, currentInput, {
+                    workflowId,
+                    stepIndex: j,
+                    metadata: { ...metadata, branch: branch.name ?? i },
+                    signal: ctx?.signal,
+                });
+                totalDuration += result.durationMs;
+                if (!result.success) {
+                    return {
+                        success: false,
+                        error: result.error,
+                        durationMs: totalDuration,
+                    };
+                }
+                currentInput = result.output;
+            }
+            return {
+                success: true,
+                output: currentInput,
+                durationMs: totalDuration,
+            };
+        }
+    }
+    return {
+        success: false,
+        error: new Error("No matching branch"),
+        durationMs: 0,
+    };
+}
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+async function executeStep(step, input, ctx) {
+    const start = Date.now();
+    try {
+        const output = await step.execute(input, ctx);
+        return {
+            success: true,
+            output,
+            durationMs: Date.now() - start,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error : new Error(String(error)),
+            durationMs: Date.now() - start,
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@vinhnt-sdk/workflow",
+  "version": "0.4.0",
+  "description": "Workflow primitives for agent orchestration - parallel, sequential, conditional",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vinhnt-develop/vinhnt-sdk.git",
+    "directory": "packages/workflow"
+  },
+  "homepage": "https://github.com/vinhnt-develop/vinhnt-sdk/tree/main/packages/workflow",
+  "bugs": {
+    "url": "https://github.com/vinhnt-develop/vinhnt-sdk/issues"
+  },
+  "keywords": [
+    "vnt",
+    "workflow",
+    "orchestration",
+    "parallel",
+    "sequential"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@vinhnt-sdk/schema": "0.4.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.7"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}