@uploadista/core 0.0.2

package/dist/utils/once.d.ts

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+import { UploadistaError } from "../errors/uploadista-error";
+export declare function once<T, A extends unknown[], Return>(fn: (this: T, ...args: A) => Return): (this: T, ...args: A) => Return;
+/**
+ * Effect-based once utilities
+ */
+export declare const OnceEffect: {
+    /**
+     * Creates an Effect-based once function that only executes once
+     * @param effect - The effect to execute only once
+     * @returns Effect that caches the result after first execution
+     */
+    make: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | UploadistaError, R>;
+    /**
+     * Creates a legacy once function wrapper
+     * @param fn - Function to wrap
+     * @returns Once-wrapped function
+     */
+    legacy: typeof once;
+};
+//# sourceMappingURL=once.d.ts.map

package/dist/utils/once.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"once.d.ts","sourceRoot":"","sources":["../../src/utils/once.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAG7D,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EAAE,EAAE,MAAM,EACjD,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,MAAM,UAIT,CAAC,WAAW,CAAC,KAAG,MAAM,CAYjD;AAED;;GAEG;AACH,eAAO,MAAM,UAAU;IACrB;;;;OAIG;WACI,CAAC,EAAE,CAAC,EAAE,CAAC,UACJ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,eAAe,EAAE,CAAC,CAAC;IAsB3C;;;;OAIG;;CAEJ,CAAC"}

package/dist/utils/once.js

@@ -0,0 +1,54 @@
+import { Effect } from "effect";
+import { UploadistaError } from "../errors/uploadista-error";
+// only call a function once
+export function once(fn) {
+    let called = false;
+    let value;
+    const f = function (...args) {
+        if (called) {
+            if (value) {
+                return value;
+            }
+            throw new Error("Function called more than once");
+        }
+        called = true;
+        value = fn.apply(this, args);
+        return value;
+    };
+    return f;
+}
+/**
+ * Effect-based once utilities
+ */
+export const OnceEffect = {
+    /**
+     * Creates an Effect-based once function that only executes once
+     * @param effect - The effect to execute only once
+     * @returns Effect that caches the result after first execution
+     */
+    make: (effect) => {
+        let cached;
+        let called = false;
+        return Effect.gen(function* () {
+            if (called) {
+                if (cached !== undefined) {
+                    return cached;
+                }
+                yield* new UploadistaError({
+                    code: "UNKNOWN_ERROR",
+                    status: 500,
+                    body: "Effect called more than once with undefined result",
+                }).toEffect();
+            }
+            called = true;
+            cached = yield* effect;
+            return cached;
+        });
+    },
+    /**
+     * Creates a legacy once function wrapper
+     * @param fn - Function to wrap
+     * @returns Once-wrapped function
+     */
+    legacy: once,
+};

package/dist/utils/once.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"once.js","names":["value: Return | undefined","cached: A | undefined"],"sources":["../../src/utils/once.ts"],"sourcesContent":["import { Effect } from \"effect\";\nimport { UploadistaError } from \"../errors/uploadista-error\";\n\n// only call a function once\nexport function once<T, A extends unknown[], Return>(\n  fn: (this: T, ...args: A) => Return,\n) {\n  let called = false;\n  let value: Return | undefined;\n  const f = function (this: T, ...args: A): Return {\n    if (called) {\n      if (value) {\n        return value;\n      }\n      throw new Error(\"Function called more than once\");\n    }\n    called = true;\n    value = fn.apply(this, args);\n    return value;\n  };\n  return f;\n}\n\n/**\n * Effect-based once utilities\n */\nexport const OnceEffect = {\n  /**\n   * Creates an Effect-based once function that only executes once\n   * @param effect - The effect to execute only once\n   * @returns Effect that caches the result after first execution\n   */\n  make: <A, E, R>(\n    effect: Effect.Effect<A, E, R>,\n  ): Effect.Effect<A, E | UploadistaError, R> => {\n    let cached: A | undefined;\n    let called = false;\n\n    return Effect.gen(function* () {\n      if (called) {\n        if (cached !== undefined) {\n          return cached;\n        }\n        yield* new UploadistaError({\n          code: \"UNKNOWN_ERROR\",\n          status: 500,\n          body: \"Effect called more than once with undefined result\",\n        }).toEffect();\n      }\n\n      called = true;\n      cached = yield* effect;\n      return cached;\n    });\n  },\n\n  /**\n   * Creates a legacy once function wrapper\n   * @param fn - Function to wrap\n   * @returns Once-wrapped function\n   */\n  legacy: once,\n};\n"],"mappings":"kGAIA,SAAgB,EACd,EACA,CACA,IAAI,EAAS,GACTA,EAYJ,OAXU,SAAmB,GAAG,EAAiB,CAC/C,GAAI,EAAQ,CACV,GAAI,EACF,OAAO,EAET,MAAU,MAAM,iCAAiC,CAInD,MAFA,GAAS,GACT,EAAQ,EAAG,MAAM,KAAM,EAAK,CACrB,GAQX,MAAa,EAAa,CAMxB,KACE,GAC6C,CAC7C,IAAIC,EACA,EAAS,GAEb,OAAO,EAAO,IAAI,WAAa,CAC7B,GAAI,EAAQ,CACV,GAAI,IAAW,IAAA,GACb,OAAO,EAET,MAAO,IAAI,EAAgB,CACzB,KAAM,gBACN,OAAQ,IACR,KAAM,qDACP,CAAC,CAAC,UAAU,CAKf,MAFA,GAAS,GACT,EAAS,MAAO,EACT,GACP,EAQJ,OAAQ,EACT"}

package/dist/utils/semaphore.cjs

@@ -0,0 +1 @@
+const e=require(`../semaphore-DVrONiAV.cjs`);exports.SemaphoreEffect=e.SemaphoreEffect,exports.permit=e.permit,exports.semaphore=e.semaphore;

package/dist/utils/semaphore.d.cts

@@ -0,0 +1,3 @@
+import "../uploadista-error-kKlhLRhY.cjs";
+import { Permit, Semaphore, SemaphoreEffect, permit, semaphore } from "../semaphore-BHprIjFI.cjs";
+export { Permit, Semaphore, SemaphoreEffect, permit, semaphore };

package/dist/utils/semaphore.d.ts

@@ -0,0 +1,78 @@
+import { Effect, type Scope } from "effect";
+import type { UploadistaError } from "../errors/uploadista-error";
+type ReleaseCallback = () => Promise<void>;
+/**
+ * Creates a permit that must be explicitly released to free up a semaphore slot.
+ *
+ * Permits are used internally by semaphores to track resource acquisition and release.
+ * Each permit represents one available slot in the semaphore's concurrency limit.
+ *
+ * @param onRelease - Callback function to execute when the permit is released
+ * @returns A permit object with a release method
+ * @internal
+ */
+export declare function permit(onRelease: ReleaseCallback): {
+    release: () => Promise<void>;
+};
+export type Permit = ReturnType<typeof permit>;
+/**
+ * Creates a semaphore for controlling concurrent access to resources.
+ *
+ * A semaphore limits the number of concurrent operations that can access a shared
+ * resource. This is useful for:
+ * - Limiting parallel file uploads
+ * - Controlling database connection pool size
+ * - Throttling API requests
+ * - Managing concurrent flow node execution
+ *
+ * When all permits are in use, new acquire() calls will wait until a permit
+ * becomes available.
+ *
+ * @param count - Maximum number of concurrent operations allowed
+ * @returns A semaphore object with an acquire method
+ *
+ * @example
+ * ```typescript
+ * const uploadSemaphore = semaphore(3); // Max 3 concurrent uploads
+ *
+ * async function uploadFile(file: File) {
+ *   const permit = await uploadSemaphore.acquire();
+ *   try {
+ *     // Upload file (max 3 concurrent)
+ *     await uploadToServer(file);
+ *   } finally {
+ *     await permit.release();
+ *   }
+ * }
+ *
+ * // Process files with concurrency limit
+ * await Promise.all(files.map(uploadFile));
+ * ```
+ */
+export declare function semaphore(count: number): {
+    acquire: () => Promise<Permit>;
+};
+export type Semaphore = ReturnType<typeof semaphore>;
+/**
+ * Effect-based semaphore utilities
+ */
+export declare const SemaphoreEffect: {
+    /**
+     * Creates an Effect-based semaphore with resource management
+     * @param count - Number of permits available
+     * @returns Effect semaphore with automatic resource cleanup
+     */
+    make: (count: number) => Effect.Effect<{
+        acquire: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | UploadistaError, R>;
+    }, never, Scope.Scope>;
+    /**
+     * Creates a legacy semaphore wrapper
+     * @param count - Number of permits
+     * @returns Legacy semaphore instance
+     */
+    legacy: (count: number) => {
+        acquire: () => Promise<Permit>;
+    };
+};
+export {};
+//# sourceMappingURL=semaphore.d.ts.map

package/dist/utils/semaphore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore.d.ts","sourceRoot":"","sources":["../../src/utils/semaphore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,KAAK,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,KAAK,eAAe,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3C;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,eAAe;;EAahD;AAED,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC;AAO/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM;mBAIjB,OAAO,CAAC,MAAM,CAAC;EAgCpC;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,eAAe;IAC1B;;;;OAIG;kBAEM,MAAM,KACZ,MAAM,CAAC,MAAM,CACd;QACE,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,eAAe,EAAE,CAAC,CAAC,CAAC;KAC/C,EACD,KAAK,EACL,KAAK,CAAC,KAAK,CACZ;IAyCD;;;;OAIG;oBACa,MAAM;uBArGF,OAAO,CAAC,MAAM,CAAC;;CAsGpC,CAAC"}

package/dist/utils/semaphore.js

@@ -0,0 +1,134 @@
+import { Effect } from "effect";
+/**
+ * Creates a permit that must be explicitly released to free up a semaphore slot.
+ *
+ * Permits are used internally by semaphores to track resource acquisition and release.
+ * Each permit represents one available slot in the semaphore's concurrency limit.
+ *
+ * @param onRelease - Callback function to execute when the permit is released
+ * @returns A permit object with a release method
+ * @internal
+ */
+export function permit(onRelease) {
+    let isReleased = false;
+    async function release() {
+        if (!isReleased) {
+            isReleased = true;
+            await onRelease();
+        }
+    }
+    return {
+        release,
+    };
+}
+/**
+ * Creates a semaphore for controlling concurrent access to resources.
+ *
+ * A semaphore limits the number of concurrent operations that can access a shared
+ * resource. This is useful for:
+ * - Limiting parallel file uploads
+ * - Controlling database connection pool size
+ * - Throttling API requests
+ * - Managing concurrent flow node execution
+ *
+ * When all permits are in use, new acquire() calls will wait until a permit
+ * becomes available.
+ *
+ * @param count - Maximum number of concurrent operations allowed
+ * @returns A semaphore object with an acquire method
+ *
+ * @example
+ * ```typescript
+ * const uploadSemaphore = semaphore(3); // Max 3 concurrent uploads
+ *
+ * async function uploadFile(file: File) {
+ *   const permit = await uploadSemaphore.acquire();
+ *   try {
+ *     // Upload file (max 3 concurrent)
+ *     await uploadToServer(file);
+ *   } finally {
+ *     await permit.release();
+ *   }
+ * }
+ *
+ * // Process files with concurrency limit
+ * await Promise.all(files.map(uploadFile));
+ * ```
+ */
+export function semaphore(count) {
+    let availablePermits = count;
+    const deferreds = [];
+    function acquire() {
+        if (availablePermits > 0) {
+            return Promise.resolve(createPermit());
+        }
+        const deferred = {};
+        deferred.promise = new Promise((resolve) => {
+            deferred.resolve = resolve;
+        });
+        deferreds.push(deferred);
+        return deferred.promise;
+    }
+    function createPermit() {
+        availablePermits--;
+        return permit(async () => {
+            availablePermits++;
+            if (deferreds.length > 0) {
+                const deferred = deferreds.shift();
+                if (deferred) {
+                    deferred.resolve?.(createPermit());
+                    await deferred.promise;
+                }
+            }
+        });
+    }
+    return {
+        acquire,
+    };
+}
+/**
+ * Effect-based semaphore utilities
+ */
+export const SemaphoreEffect = {
+    /**
+     * Creates an Effect-based semaphore with resource management
+     * @param count - Number of permits available
+     * @returns Effect semaphore with automatic resource cleanup
+     */
+    make: (count) => Effect.acquireRelease(Effect.sync(() => {
+        let availablePermits = count;
+        const queue = [];
+        const acquire = (effect) => Effect.gen(function* () {
+            // Wait for a permit
+            yield* Effect.async((resume) => {
+                if (availablePermits > 0) {
+                    availablePermits--;
+                    resume(Effect.void);
+                }
+                else {
+                    queue.push((releasePermit) => {
+                        availablePermits--;
+                        resume(Effect.void);
+                    });
+                }
+            });
+            // Execute the effect with cleanup
+            return yield* Effect.ensuring(effect, Effect.sync(() => {
+                availablePermits++;
+                if (queue.length > 0) {
+                    const nextWaiting = queue.shift();
+                    if (nextWaiting) {
+                        nextWaiting(() => { });
+                    }
+                }
+            }));
+        });
+        return { acquire };
+    }), () => Effect.void),
+    /**
+     * Creates a legacy semaphore wrapper
+     * @param count - Number of permits
+     * @returns Legacy semaphore instance
+     */
+    legacy: (count) => semaphore(count),
+};

package/dist/utils/throttle.cjs

@@ -0,0 +1 @@
+const e=require(`../debounce-LZK7yS7Z.cjs`);function t(t,n,{leading:r=!0,trailing:i=!0}={}){return e.debounce(t,n,{leading:r,trailing:i})}const n={legacy:t};exports.ThrottleEffect=n,exports.throttle=t;

package/dist/utils/throttle.d.cts

@@ -0,0 +1,24 @@
+//#region src/utils/throttle.d.ts
+declare function throttle<T, A extends unknown[], Return>(fn: (this: T, ...args: A) => Return, wait: number, {
+  leading,
+  trailing
+}?: {
+  leading?: boolean;
+  trailing?: boolean;
+}): (this: T, ...args: A) => void;
+/**
+ * Effect-based throttle utilities
+ */
+declare const ThrottleEffect: {
+  /**
+   * Creates a legacy throttle function wrapper
+   * @param fn - Function to throttle
+   * @param wait - Wait time in milliseconds
+   * @param options - Throttle options
+   * @returns Throttled function
+   */
+  legacy: typeof throttle;
+};
+//#endregion
+export { ThrottleEffect, throttle };
+//# sourceMappingURL=throttle.d.cts.map

package/dist/utils/throttle.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.cts","names":[],"sources":["../../src/utils/throttle.ts"],"sourcesContent":[],"mappings":";iBAEgB,oDACH,YAAY,MAAM;;;;EADf,OAAA,CAAA,EAAA,OAAQ;EAAA,QAAA,CAAA,EAAA,OAAA;SACX,EAKsC,CALtC,EAAA,GAAA,IAAA,EAKsC,CALtC,EAAA,GAAA,IAAA;;;;AAIT,cAYS,cAZT,EAAA;;;;AAYJ;;;;iBASC"}

package/dist/utils/throttle.d.ts

@@ -0,0 +1,18 @@
+export declare function throttle<T, A extends unknown[], Return>(fn: (this: T, ...args: A) => Return, wait: number, { leading, trailing, }?: {
+    leading?: boolean;
+    trailing?: boolean;
+}): (this: T, ...args: A) => void;
+/**
+ * Effect-based throttle utilities
+ */
+export declare const ThrottleEffect: {
+    /**
+     * Creates a legacy throttle function wrapper
+     * @param fn - Function to throttle
+     * @param wait - Wait time in milliseconds
+     * @param options - Throttle options
+     * @returns Throttled function
+     */
+    legacy: typeof throttle;
+};
+//# sourceMappingURL=throttle.d.ts.map

package/dist/utils/throttle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.ts","sourceRoot":"","sources":["../../src/utils/throttle.ts"],"names":[],"mappings":"AAEA,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EAAE,EAAE,MAAM,EACrD,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,MAAM,EACnC,IAAI,EAAE,MAAM,EACZ,EACE,OAAc,EACd,QAAe,GAChB,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,iCAMlD;AAED;;GAEG;AACH,eAAO,MAAM,cAAc;IACzB;;;;;;OAMG;;CAEJ,CAAC"}

package/dist/utils/throttle.js

@@ -0,0 +1,20 @@
+import { debounce } from "./debounce.js";
+export function throttle(fn, wait, { leading = true, trailing = true, } = {}) {
+    return debounce(fn, wait, {
+        leading,
+        trailing,
+    });
+}
+/**
+ * Effect-based throttle utilities
+ */
+export const ThrottleEffect = {
+    /**
+     * Creates a legacy throttle function wrapper
+     * @param fn - Function to throttle
+     * @param wait - Wait time in milliseconds
+     * @param options - Throttle options
+     * @returns Throttled function
+     */
+    legacy: throttle,
+};

package/dist/utils/throttle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.js","names":[],"sources":["../../src/utils/throttle.ts"],"sourcesContent":["import { debounce } from \"./debounce.js\";\n\nexport function throttle<T, A extends unknown[], Return>(\n  fn: (this: T, ...args: A) => Return,\n  wait: number,\n  {\n    leading = true,\n    trailing = true,\n  }: { leading?: boolean; trailing?: boolean } = {},\n) {\n  return debounce(fn, wait, {\n    leading,\n    trailing,\n  });\n}\n\n/**\n * Effect-based throttle utilities\n */\nexport const ThrottleEffect = {\n  /**\n   * Creates a legacy throttle function wrapper\n   * @param fn - Function to throttle\n   * @param wait - Wait time in milliseconds\n   * @param options - Throttle options\n   * @returns Throttled function\n   */\n  legacy: throttle,\n};\n"],"mappings":"mDAEA,SAAgB,EACd,EACA,EACA,CACE,UAAU,GACV,WAAW,IACkC,EAAE,CACjD,CACA,OAAO,EAAS,EAAI,EAAM,CACxB,UACA,WACD,CAAC,CAMJ,MAAa,EAAiB,CAQ5B,OAAQ,EACT"}

package/docs/PARALLEL_EXECUTION.md

@@ -0,0 +1,206 @@
+# Parallel Flow Execution
+
+The uploadista flow engine now supports parallel execution of independent nodes using Effect's native concurrency primitives, significantly improving performance for complex flows with multiple processing branches.
+
+## Overview
+
+The parallel execution feature automatically identifies nodes that can run concurrently (nodes that don't depend on each other) and groups them into execution levels. Nodes within the same level are executed in parallel with controlled concurrency, while different levels are executed sequentially to maintain dependencies.
+
+## Key Features
+
+- **Automatic Dependency Analysis**: The scheduler analyzes the flow graph and groups independent nodes into parallel execution levels using Kahn's algorithm
+- **Effect-Based Concurrency**: Uses Effect's `Effect.all()` with concurrency limits to manage parallel execution safely
+- **Backward Compatibility**: Falls back to sequential execution when parallel execution is disabled (default behavior)
+- **Error Handling**: Proper error propagation and failure handling across parallel branches
+- **Type-Safe**: Full TypeScript support with proper Effect typing
+
+## Usage
+
+To enable parallel execution, set the `parallelExecution` option when creating a flow:
+
+```typescript
+import { createFlowWithSchema } from '@uploadista/core/flow';
+
+const flow = yield* createFlowWithSchema({
+  flowId: 'my-parallel-flow',
+  name: 'Parallel Processing Flow',
+  nodes: [inputNode, processA, processB, processC, mergeNode, outputNode],
+  edges: [
+    { source: 'input', target: 'processA' },
+    { source: 'input', target: 'processB' },
+    { source: 'input', target: 'processC' },
+    { source: 'processA', target: 'merge' },
+    { source: 'processB', target: 'merge' },
+    { source: 'processC', target: 'merge' },
+    { source: 'merge', target: 'output' }
+  ],
+  inputSchema: myInputSchema,
+  outputSchema: myOutputSchema,
+  parallelExecution: {
+    enabled: true,
+    maxConcurrency: 4, // Maximum number of concurrent nodes per level
+  },
+});
+```
+
+## Configuration Options
+
+- `enabled`: Boolean flag to enable/disable parallel execution (default: `false`)
+- `maxConcurrency`: Maximum number of nodes to execute concurrently within a level (default: `4`)
+
+## How It Works
+
+### 1. Dependency Analysis
+The scheduler analyzes the flow graph using Kahn's algorithm to build a dependency graph and calculate the in-degree (number of dependencies) for each node.
+
+### 2. Level Grouping
+Nodes are grouped into execution levels based on their dependencies:
+- **Level 0**: Input nodes (no dependencies)
+- **Level 1**: Nodes that depend only on Level 0 nodes
+- **Level N**: Nodes that depend on Level N-1 nodes
+
+### 3. Parallel Execution with Effect
+Within each level, nodes are executed in parallel using Effect's `Effect.all()` with concurrency control. This ensures:
+- No more than `maxConcurrency` nodes execute simultaneously
+- Resource exhaustion is prevented
+- Proper error handling and cleanup
+
+### 4. Sequential Level Processing
+Levels are processed sequentially in a for loop. Each level completes before the next level begins, ensuring all dependencies are satisfied.
+
+## Performance Benefits
+
+Parallel execution can significantly reduce flow execution time, especially for:
+- Image processing pipelines with multiple transformations
+- Multi-branch conditional flows
+- Independent data processing tasks
+- Complex validation and transformation chains
+
+Expected performance improvements depend on:
+- Number of independent processing branches
+- Individual node execution time
+- Available system resources
+
+## Example Flow Structure
+
+```
+Input Node
+    ↓
+┌─────────┼─────────┐
+↓         ↓         ↓
+ProcessA  ProcessB  ProcessC  ← Level 1 (parallel)
+└─────────┼─────────┘
+          ↓
+      Merge Node              ← Level 2 (sequential)
+          ↓
+     Output Node              ← Level 3 (sequential)
+```
+
+In this example:
+- ProcessA, ProcessB, and ProcessC run in parallel
+- Merge Node waits for all parallel processes to complete
+- Output Node processes the merged result
+
+## Error Handling
+
+If any node in a parallel level fails:
+- The error is propagated immediately (Effect's `Promise.all` behavior)
+- Remaining nodes in the level may continue, but the flow halts
+- Error details are available for debugging
+- Resources are properly cleaned up through Effect's resource management
+
+## Monitoring and Debugging
+
+The parallel scheduler provides execution level information and statistics:
+
+```typescript
+const scheduler = new ParallelScheduler({ maxConcurrency: 4 });
+
+// Get execution levels
+const levels = scheduler.groupNodesByExecutionLevel(nodes, edges);
+console.log(`Flow has ${levels.length} execution levels`);
+levels.forEach(level => {
+  console.log(`Level ${level.level}: [${level.nodes.join(', ')}]`);
+});
+
+// Get scheduler stats
+const stats = scheduler.getStats();
+console.log(`Max concurrency: ${stats.maxConcurrency}`);
+```
+
+### Debug Logging
+
+When parallel execution is enabled, the flow engine emits debug logs:
+```
+Flow my-flow: Executing in parallel mode (maxConcurrency: 4)
+Flow my-flow: Grouped nodes into 3 execution levels
+Flow my-flow: Executing level 0 with nodes: input_1
+Flow my-flow: Executing level 1 with nodes: resize_1, optimize_1
+Flow my-flow: Executing level 2 with nodes: output_1
+```
+
+## Limitations & Considerations
+
+- **Pausable nodes**: If a node pauses in a level, the entire level pauses
+- **Conditional nodes**: Conditions are evaluated before parallel execution begins; the node is either included or skipped for the level
+- **Multi-input nodes**: Must have all dependencies completed before execution (enforced by level grouping)
+- **Resource-intensive nodes**: May benefit from lower `maxConcurrency` settings to prevent resource contention
+
+## Migration from Sequential Flows
+
+Existing flows work without any changes:
+- Default behavior remains sequential execution (`enabled: false`)
+- Enable parallel execution by adding the `parallelExecution` configuration
+- No changes required to existing node implementations
+- Flows automatically respect dependency constraints
+
+## Implementation Details
+
+The parallel execution system consists of three main components:
+
+### 1. ParallelScheduler (`parallel-scheduler.ts`)
+- Analyzes flow dependencies using Kahn's algorithm
+- Groups nodes into execution levels
+- Provides `executeNodesInParallel()` which uses `Effect.all()` with concurrency control
+- Type-safe Effect-based API with full TypeScript support
+
+```typescript
+const scheduler = new ParallelScheduler({ maxConcurrency: 4 });
+const levels = scheduler.groupNodesByExecutionLevel(nodes, edges);
+const results = yield* scheduler.executeNodesInParallel(executors);
+```
+
+### 2. Flow Engine Integration (`flow.ts`)
+- Detects when `parallelExecution.enabled` is true
+- Switches between sequential and parallel execution paths
+- Maintains backward compatibility (sequential is default)
+- Properly handles paused nodes in parallel execution
+
+### 3. Effect-Based Concurrency
+Uses Effect's `Effect.all()` with `concurrency` option:
+```typescript
+Effect.all(nodeExecutors, { concurrency: maxConcurrency })
+```
+This ensures resource-safe parallel execution without manual semaphore management.
+
+## Performance Characteristics
+
+### Best Case Scenarios
+- **Independent processing branches**: 3+ parallel nodes can reduce execution time proportionally
+- **I/O-bound operations**: Network calls or disk I/O can run concurrently
+- **CPU-bound with other operations**: Can interleave with other workloads
+
+### Example Performance Gain
+```
+Sequential: Input (1s) → Resize (2s) → Optimize (2s) → Output (1s) = 6 seconds
+Parallel:   Input (1s) → [Resize (2s) + Optimize (2s) in parallel] → Output (1s) = 4 seconds
+            Speedup: 33% faster with just 2 parallel operations
+```
+
+## Future Enhancements
+
+Potential improvements for future releases:
+- Dynamic concurrency adjustment based on resource availability
+- Per-node concurrency limits for resource-intensive operations
+- Parallel level visualization in flow builder
+- Performance metrics collection and reporting