@async-kit/flowx 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+## 0.1.2 (2026-03-11)
+
+### 🩹 Fixes
+
+- **release:** add publishConfig access public to all packages ([82c12ca](https://github.com/NexaLeaf/async-kit/commit/82c12ca))
+
+### ❤️ Thank You
+
+- Palanisamy Muthusamy

package/README.md

@@ -0,0 +1,354 @@
+<div align="center">
+
+<img src="https://capsule-render.vercel.app/api?type=rect&color=gradient&customColorList=2&height=120&section=header&text=flowx&fontSize=60&fontColor=fff&animation=fadeIn&desc=%40async-kit%2Fflowx&descAlignY=75&descAlign=50" width="100%"/>
+
+<br/>
+
+[![npm](https://img.shields.io/npm/v/@async-kit/flowx?style=for-the-badge&logo=npm&color=45B7D1)](https://www.npmjs.com/package/@async-kit/flowx)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](../../LICENSE)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/@async-kit/flowx?style=for-the-badge&color=45B7D1)](https://bundlephobia.com/package/@async-kit/flowx)
+[![Node](https://img.shields.io/badge/Node-%3E%3D18-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Browser](https://img.shields.io/badge/Browser-Supported-4285F4?style=for-the-badge&logo=googlechrome&logoColor=white)](#compatibility)
+
+**Type-safe async pipeline builder — composable steps, fallbacks, per-step timeouts, and concurrency control.**
+
+*Chain transforms, fan-out concurrently, reduce sequentially — all type-safe.*
+
+</div>
+
+---
+
+## Install
+
+```bash
+npm install @async-kit/flowx
+```
+
+## Quick Start
+
+```typescript
+import { pipeline, parallel, sequence } from '@async-kit/flowx';
+
+// Composable async pipeline
+const result = await pipeline<string>()
+  .pipe(s => s.trim())
+  .pipe({ name: 'uppercase', fn: s => s.toUpperCase() })
+  .tap(s => console.log('after uppercase:', s))
+  .run('  hello world  ');
+// → 'HELLO WORLD'
+
+// Concurrent tasks
+const [users, products] = await parallel([
+  () => fetchUsers(),
+  () => fetchProducts(),
+], { concurrency: 2 });
+
+// Async reduce
+const total = await sequence([1, 2, 3], 0, (acc, n) => acc + n);
+// → 6
+```
+
+## API
+
+### `pipeline<T>()`
+
+Creates a new empty pipeline starting with type `T`. Returns a `Pipeline<T, T>` builder.
+
+### `Pipeline<TIn, TOut>`
+
+Each method returns a **new Pipeline** — pipelines are immutable and reusable.
+
+| Method | Returns | Description |
+|---|---|---|
+| `.pipe(step)` | `Pipeline<TIn, TNext>` | Add a transform step |
+| `.pipeWithFallback(step, fallback)` | `Pipeline<TIn, TNext>` | Step with an inline error fallback |
+| `.tap(fn)` | `Pipeline<TIn, TOut>` | Side-effect step; passes value through unchanged |
+| `.run(input, opts?)` | `Promise<TOut>` | Execute the pipeline |
+| `.stepCount` | `number` | Number of non-fallback steps |
+| `.toArray()` | `StepMeta[]` | Metadata array for debugging/tooling |
+
+#### Step formats
+
+```typescript
+// Plain function
+.pipe(value => value.trim())
+
+// Named step with optional per-step timeout
+.pipe({ name: 'normalize', fn: value => value.trim(), timeoutMs: 1000 })
+```
+
+### `FlowxOptions`
+
+```typescript
+interface FlowxOptions {
+  signal?: AbortSignal;           // Checked between steps
+  onStepComplete?: (index, name, result) => void;
+  stepTimeoutMs?: number;         // Default per-step timeout (overridable per step)
+}
+```
+
+### Step Context
+
+Every step receives a `StepContext` as its second argument:
+
+```typescript
+interface StepContext {
+  signal: AbortSignal;
+  stepIndex: number;       // 0-based
+  stepName: string | undefined;
+}
+```
+
+## Fallbacks
+
+`.pipeWithFallback` catches step errors and runs a recovery function instead of propagating:
+
+```typescript
+const result = await pipeline<string>()
+  .pipeWithFallback(
+    { name: 'parse', fn: s => JSON.parse(s) },
+    (err, input) => ({ raw: input, error: err.cause })
+  )
+  .run('invalid json');
+// → { raw: 'invalid json', error: SyntaxError }
+```
+
+## `parallel(tasks, options?)`
+
+Run tasks concurrently, resolve in declaration order. Rejects on first failure.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `concurrency` | `number` | unbounded | Max simultaneous tasks |
+| `signal` | `AbortSignal` | — | Cancel pending tasks |
+
+## `parallelSettled(tasks, options?)`
+
+Same as `parallel` but returns `PromiseSettledResult<T>[]` — never rejects.
+
+## `sequence(items, initial, fn, options?)`
+
+Async left-fold — like `Array.reduce` but supports async reducers and `AbortSignal`.
+
+```typescript
+const total = await sequence(orders, 0, async (acc, order) => {
+  const price = await fetchPrice(order.id);
+  return acc + price;
+});
+```
+
+## Error Types
+
+| Class | When |
+|---|---|
+| `PipelineStepError` | A step threw — has `.stepIndex`, `.stepName`, `.cause`, `.inputValue` |
+| `PipelineTimeoutError` | Per-step timeout exceeded — has `.stepIndex`, `.stepName`, `.timeoutMs` |
+
+## Examples
+
+### Type-safe order processing pipeline
+
+```typescript
+import { pipeline } from '@async-kit/flowx';
+
+interface RawOrder     { id: string; amount: string; userId: string }
+interface ParsedOrder  { id: string; amount: number; userId: string }
+interface EnrichedOrder extends ParsedOrder { user: User; currency: string }
+interface Report       extends EnrichedOrder { formattedAmount: string }
+
+const orderPipeline = pipeline<RawOrder>()
+  // Step 0 — parse
+  .pipe((raw): ParsedOrder => ({ ...raw, amount: parseFloat(raw.amount) }))
+  // Step 1 — validate
+  .pipe(async (order) => {
+    if (order.amount <= 0) throw new Error(`Invalid amount: ${order.amount}`);
+    return order;
+  })
+  // Step 2 — enrich (concurrent sub-calls)
+  .pipe(async (order): Promise<EnrichedOrder> => {
+    const [user, currency] = await Promise.all([
+      userApi.get(order.userId),
+      fxApi.getDefault(order.userId),
+    ]);
+    return { ...order, user, currency };
+  })
+  // Step 3 — format
+  .pipe((order): Report => ({
+    ...order,
+    formattedAmount: new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: order.currency,
+    }).format(order.amount),
+  }));
+
+// Reusable — run with any input
+const report = await orderPipeline.run(rawOrder, {
+  onStepComplete: (i, name) => metrics.track(`order.pipeline.step_${i}_${name}`),
+});
+```
+
+### Fallback to cache when primary fetch fails
+
+```typescript
+import { pipeline } from '@async-kit/flowx';
+
+const enrichedPipeline = pipeline<string>()           // starts with user ID
+  .pipeWithFallback(
+    { name: 'fetchProfile', fn: id => profileApi.get(id), timeoutMs: 2_000 },
+    (_err, id) => cache.get(`profile:${id}`) ?? { id, name: 'Unknown' }
+  )
+  .pipe({ name: 'fetchOrders', fn: profile => orderApi.list(profile.id), timeoutMs: 3_000 })
+  .pipeWithFallback(
+    { name: 'fetchInventory', fn: orders => inventoryApi.check(orders) },
+    (_err, orders) => orders.map(o => ({ ...o, inStock: null }))
+  );
+
+const data = await enrichedPipeline.run(userId);
+```
+
+### Fan-out with bounded concurrency
+
+```typescript
+import { parallel, parallelSettled } from '@async-kit/flowx';
+
+// All succeed — throws if any fail (like Promise.all)
+const [profile, orders, prefs] = await parallel([
+  () => userApi.getProfile(userId),
+  () => orderApi.getOrders(userId),
+  () => prefsApi.get(userId),
+], { concurrency: 2 });           // max 2 in-flight
+
+// Tolerate partial failures
+const results = await parallelSettled([
+  () => analyticsApi.getStats(userId),
+  () => notificationsApi.getUnread(userId),
+  () => recsApi.get(userId),
+]);
+
+for (const r of results) {
+  if (r.status === 'fulfilled') console.log(r.value);
+  else console.warn('Optional data unavailable:', r.reason);
+}
+```
+
+### Async reduce with sequence — build a report
+
+```typescript
+import { sequence } from '@async-kit/flowx';
+
+const report = await sequence(
+  reportSections,
+  { sections: [], totalMs: 0 },
+  async (acc, section) => {
+    const t0 = Date.now();
+    const rendered = await renderSection(section);
+    return {
+      sections: [...acc.sections, rendered],
+      totalMs: acc.totalMs + (Date.now() - t0),
+    };
+  },
+  { signal: abortController.signal }
+);
+
+console.log(`Built ${report.sections.length} sections in ${report.totalMs}ms`);
+```
+
+### Cancellable pipeline with step-level observability
+
+```typescript
+import { pipeline } from '@async-kit/flowx';
+
+const controller = new AbortController();
+
+// Cancel from the UI
+document.getElementById('cancel')!.onclick = () => controller.abort();
+
+const result = await pipeline<Blob>()
+  .pipe({ name: 'upload',    fn: blob => uploadService.store(blob),     timeoutMs: 10_000 })
+  .pipe({ name: 'transcode', fn: ref  => transcodeService.run(ref),     timeoutMs: 60_000 })
+  .pipe({ name: 'thumbnail', fn: ref  => thumbnailService.generate(ref), timeoutMs: 5_000 })
+  .tap(ref => console.log('Asset ready:', ref))
+  .run(file, {
+    signal: controller.signal,
+    onStepComplete: (i, name, result) => {
+      console.log(`Step ${i} (${name}) done:`, result);
+    },
+  });
+```
+
+### Reusable pipeline — define once, run many
+
+```typescript
+import { pipeline } from '@async-kit/flowx';
+
+const csvPipeline = pipeline<string>()
+  .pipe(raw   => raw.trim().split('\n'))
+  .pipe(lines => lines.slice(1))                         // skip header
+  .pipe(lines => lines.map(l => l.split(',')))
+  .pipe(rows  => rows.map(([id, name, score]) => ({
+    id: Number(id),
+    name: name.trim(),
+    score: parseFloat(score),
+  })))
+  .pipe(rows  => rows.filter(r => r.score >= 0.5));      // threshold
+
+// Run against multiple files concurrently
+const [a, b, c] = await Promise.all([
+  csvPipeline.run(await readFile('a.csv', 'utf8')),
+  csvPipeline.run(await readFile('b.csv', 'utf8')),
+  csvPipeline.run(await readFile('c.csv', 'utf8')),
+]);
+```
+
+### Tap for structured logging
+
+```typescript
+import { pipeline } from '@async-kit/flowx';
+
+const pipe = pipeline<Order>()
+  .pipe(validate)
+  .tap(order => logger.info('validated', { orderId: order.id }))
+  .pipe(enrich)
+  .tap(order => logger.info('enriched', { user: order.user.name }))
+  .pipe(persist)
+  .tap(saved => logger.info('persisted', { savedId: saved.id }));
+
+await pipe.run(incomingOrder);
+```
+
+## Types
+
+```typescript
+import type {
+  StepFn,
+  StepContext,
+  NamedStep,
+  FlowxOptions,
+  ParallelOptions,
+  SequenceOptions,
+} from '@async-kit/flowx';
+```
+
+## Compatibility
+
+| Environment | Support | Notes |
+|---|---|---|
+| **Node.js** | ≥ 18 | Recommended ≥ 24 for best performance |
+| **Deno** | ✅ | Via npm specifier (`npm:@async-kit/flowx`) |
+| **Bun** | ✅ | Full support |
+| **Chrome** | ≥ 80 | ESM via bundler or native import |
+| **Firefox** | ≥ 75 | ESM via bundler or native import |
+| **Safari** | ≥ 13.1 | ESM via bundler or native import |
+| **Edge** | ≥ 80 | ESM via bundler or native import |
+| **React Native** | ✅ | Via Metro bundler |
+| **Cloudflare Workers** | ✅ | ESM, `AbortSignal` natively supported |
+| **Vercel Edge Runtime** | ✅ | ESM, no `process` / `fs` dependencies |
+
+**No Node.js built-ins are used.** The package relies only on standard JavaScript (`Promise`, `setTimeout`, `clearTimeout`, `AbortSignal`, `DOMException`) — all available in any modern runtime or browser.
+
+> `PipelineTimeoutError` uses `setTimeout` which is available everywhere. `AbortSignal` is standard since Node.js ≥ 15 and all modern browsers.
+
+## License
+
+MIT © async-kit contributors · Part of the [async-kit](../../README.md) ecosystem

package/dist/index.d.mts

@@ -0,0 +1,124 @@
+/** A pipeline step function: transforms `In` → `Out`, optionally async. */
+type StepFn<In, Out> = (input: In, context: StepContext) => Promise<Out> | Out;
+/** Context injected into every pipeline step. */
+interface StepContext {
+    /** AbortSignal — passed into every step for fine-grained cancellation. */
+    signal: AbortSignal;
+    /** 0-based index of the current step. */
+    stepIndex: number;
+    /** Name of the step, if provided. */
+    stepName: string | undefined;
+}
+/** A named step with an optional per-step timeout override. */
+interface NamedStep<In, Out> {
+    name: string;
+    fn: StepFn<In, Out>;
+    /** Per-step timeout in ms. Overrides `FlowxOptions.stepTimeoutMs`. */
+    timeoutMs?: number;
+}
+/** Options passed to `Pipeline.run()`. */
+interface FlowxOptions {
+    /** AbortSignal — checked between steps and passed into each step's context. */
+    signal?: AbortSignal;
+    /** Called after each step completes successfully. */
+    onStepComplete?: (stepIndex: number, stepName: string | undefined, result: unknown) => void;
+    /** Default timeout per step in ms. Can be overridden per step in `NamedStep`. */
+    stepTimeoutMs?: number;
+}
+/** Options for `parallel()` and `parallelSettled()`. */
+interface ParallelOptions {
+    /** Limit simultaneous tasks. Undefined = unbounded. */
+    concurrency?: number;
+    /** AbortSignal — cancels pending tasks when aborted. */
+    signal?: AbortSignal;
+    /** Called as each task settles. */
+    onSettle?: (index: number, result: PromiseSettledResult<unknown>) => void;
+}
+/** Options for `sequence()`. */
+interface SequenceOptions {
+    signal?: AbortSignal;
+}
+
+declare class PipelineStepError extends Error {
+    readonly stepIndex: number;
+    readonly stepName: string | undefined;
+    readonly cause: unknown;
+    readonly inputValue: unknown;
+    constructor(stepIndex: number, stepName: string | undefined, cause: unknown, inputValue: unknown);
+}
+declare class PipelineTimeoutError extends Error {
+    readonly stepIndex: number;
+    readonly stepName: string | undefined;
+    readonly timeoutMs: number;
+    constructor(stepIndex: number, stepName: string | undefined, timeoutMs: number);
+}
+interface StepRecord {
+    fn: StepFn<unknown, unknown>;
+    name: string | undefined;
+    timeoutMs: number | undefined;
+    isFallback: false;
+}
+interface FallbackRecord {
+    fn: (error: PipelineStepError, input: unknown) => unknown | Promise<unknown>;
+    isFallback: true;
+}
+type AnyRecord = StepRecord | FallbackRecord;
+/**
+ * Flowx — composable, type-safe async pipeline builder.
+ *
+ * Each step receives the output of the previous step as its first argument,
+ * plus a `StepContext` carrying the abort signal, step index, and step name.
+ *
+ * @example
+ * const result = await pipeline<string>()
+ *   .pipe(s => s.trim())
+ *   .pipe({ name: 'uppercase', fn: s => s.toUpperCase() })
+ *   .tap(s => console.log('after uppercase:', s))
+ *   .run('  hello  ');
+ */
+declare class Pipeline<TIn, TOut> {
+    private readonly records;
+    constructor(records?: AnyRecord[]);
+    /**
+     * Add a transform step. Accepts either a plain function or a `NamedStep`
+     * object with an optional per-step `timeoutMs`.
+     */
+    pipe<TNext>(step: StepFn<TOut, TNext> | NamedStep<TOut, TNext>): Pipeline<TIn, TNext>;
+    /**
+     * Add a step with an inline fallback. If the step throws, `fallback` is
+     * called with the error and the original input to that step.
+     */
+    pipeWithFallback<TNext>(step: StepFn<TOut, TNext> | NamedStep<TOut, TNext>, fallback: (error: PipelineStepError, input: TOut) => TNext | Promise<TNext>): Pipeline<TIn, TNext>;
+    /**
+     * Add a side-effect step. Runs `fn` for its effect only; passes the current
+     * value through unchanged. Errors in `fn` propagate normally.
+     */
+    tap(fn: (value: TOut, context: StepContext) => void | Promise<void>): Pipeline<TIn, TOut>;
+    run(input: TIn, options?: FlowxOptions): Promise<TOut>;
+    get stepCount(): number;
+    /** Returns step metadata for debugging/tooling. */
+    toArray(): Array<{
+        index: number;
+        name: string | undefined;
+        timeoutMs: number | undefined;
+    }>;
+}
+/** Create a new empty pipeline starting with type `T`. */
+declare function pipeline<T>(): Pipeline<T, T>;
+/**
+ * Run tasks concurrently, return results in declaration order.
+ * Rejects if any task throws (like `Promise.all`).
+ */
+declare function parallel<T>(tasks: Array<() => Promise<T>>, options?: ParallelOptions): Promise<T[]>;
+/**
+ * Run tasks concurrently and return all results regardless of success/failure.
+ * Equivalent to `Promise.allSettled` but with optional concurrency control.
+ */
+declare function parallelSettled<T>(tasks: Array<() => Promise<T>>, options?: Pick<ParallelOptions, 'concurrency' | 'signal'>): Promise<PromiseSettledResult<T>[]>;
+/**
+ * Async left-fold over an array. Like `Array.reduce` but supports async reducers
+ * and can be cancelled via `AbortSignal`.
+ */
+declare function sequence<T, A>(items: T[], initial: A, fn: (acc: A, item: T, index: number) => Promise<A> | A, options?: SequenceOptions): Promise<A>;
+
+export { type FlowxOptions, type NamedStep, type ParallelOptions, Pipeline, PipelineStepError, PipelineTimeoutError, type SequenceOptions, type StepContext, type StepFn, parallel, parallelSettled, pipeline, sequence };

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+/** A pipeline step function: transforms `In` → `Out`, optionally async. */
+type StepFn<In, Out> = (input: In, context: StepContext) => Promise<Out> | Out;
+/** Context injected into every pipeline step. */
+interface StepContext {
+    /** AbortSignal — passed into every step for fine-grained cancellation. */
+    signal: AbortSignal;
+    /** 0-based index of the current step. */
+    stepIndex: number;
+    /** Name of the step, if provided. */
+    stepName: string | undefined;
+}
+/** A named step with an optional per-step timeout override. */
+interface NamedStep<In, Out> {
+    name: string;
+    fn: StepFn<In, Out>;
+    /** Per-step timeout in ms. Overrides `FlowxOptions.stepTimeoutMs`. */
+    timeoutMs?: number;
+}
+/** Options passed to `Pipeline.run()`. */
+interface FlowxOptions {
+    /** AbortSignal — checked between steps and passed into each step's context. */
+    signal?: AbortSignal;
+    /** Called after each step completes successfully. */
+    onStepComplete?: (stepIndex: number, stepName: string | undefined, result: unknown) => void;
+    /** Default timeout per step in ms. Can be overridden per step in `NamedStep`. */
+    stepTimeoutMs?: number;
+}
+/** Options for `parallel()` and `parallelSettled()`. */
+interface ParallelOptions {
+    /** Limit simultaneous tasks. Undefined = unbounded. */
+    concurrency?: number;
+    /** AbortSignal — cancels pending tasks when aborted. */
+    signal?: AbortSignal;
+    /** Called as each task settles. */
+    onSettle?: (index: number, result: PromiseSettledResult<unknown>) => void;
+}
+/** Options for `sequence()`. */
+interface SequenceOptions {
+    signal?: AbortSignal;
+}
+
+declare class PipelineStepError extends Error {
+    readonly stepIndex: number;
+    readonly stepName: string | undefined;
+    readonly cause: unknown;
+    readonly inputValue: unknown;
+    constructor(stepIndex: number, stepName: string | undefined, cause: unknown, inputValue: unknown);
+}
+declare class PipelineTimeoutError extends Error {
+    readonly stepIndex: number;
+    readonly stepName: string | undefined;
+    readonly timeoutMs: number;
+    constructor(stepIndex: number, stepName: string | undefined, timeoutMs: number);
+}
+interface StepRecord {
+    fn: StepFn<unknown, unknown>;
+    name: string | undefined;
+    timeoutMs: number | undefined;
+    isFallback: false;
+}
+interface FallbackRecord {
+    fn: (error: PipelineStepError, input: unknown) => unknown | Promise<unknown>;
+    isFallback: true;
+}
+type AnyRecord = StepRecord | FallbackRecord;
+/**
+ * Flowx — composable, type-safe async pipeline builder.
+ *
+ * Each step receives the output of the previous step as its first argument,
+ * plus a `StepContext` carrying the abort signal, step index, and step name.
+ *
+ * @example
+ * const result = await pipeline<string>()
+ *   .pipe(s => s.trim())
+ *   .pipe({ name: 'uppercase', fn: s => s.toUpperCase() })
+ *   .tap(s => console.log('after uppercase:', s))
+ *   .run('  hello  ');
+ */
+declare class Pipeline<TIn, TOut> {
+    private readonly records;
+    constructor(records?: AnyRecord[]);
+    /**
+     * Add a transform step. Accepts either a plain function or a `NamedStep`
+     * object with an optional per-step `timeoutMs`.
+     */
+    pipe<TNext>(step: StepFn<TOut, TNext> | NamedStep<TOut, TNext>): Pipeline<TIn, TNext>;
+    /**
+     * Add a step with an inline fallback. If the step throws, `fallback` is
+     * called with the error and the original input to that step.
+     */
+    pipeWithFallback<TNext>(step: StepFn<TOut, TNext> | NamedStep<TOut, TNext>, fallback: (error: PipelineStepError, input: TOut) => TNext | Promise<TNext>): Pipeline<TIn, TNext>;
+    /**
+     * Add a side-effect step. Runs `fn` for its effect only; passes the current
+     * value through unchanged. Errors in `fn` propagate normally.
+     */
+    tap(fn: (value: TOut, context: StepContext) => void | Promise<void>): Pipeline<TIn, TOut>;
+    run(input: TIn, options?: FlowxOptions): Promise<TOut>;
+    get stepCount(): number;
+    /** Returns step metadata for debugging/tooling. */
+    toArray(): Array<{
+        index: number;
+        name: string | undefined;
+        timeoutMs: number | undefined;
+    }>;
+}
+/** Create a new empty pipeline starting with type `T`. */
+declare function pipeline<T>(): Pipeline<T, T>;
+/**
+ * Run tasks concurrently, return results in declaration order.
+ * Rejects if any task throws (like `Promise.all`).
+ */
+declare function parallel<T>(tasks: Array<() => Promise<T>>, options?: ParallelOptions): Promise<T[]>;
+/**
+ * Run tasks concurrently and return all results regardless of success/failure.
+ * Equivalent to `Promise.allSettled` but with optional concurrency control.
+ */
+declare function parallelSettled<T>(tasks: Array<() => Promise<T>>, options?: Pick<ParallelOptions, 'concurrency' | 'signal'>): Promise<PromiseSettledResult<T>[]>;
+/**
+ * Async left-fold over an array. Like `Array.reduce` but supports async reducers
+ * and can be cancelled via `AbortSignal`.
+ */
+declare function sequence<T, A>(items: T[], initial: A, fn: (acc: A, item: T, index: number) => Promise<A> | A, options?: SequenceOptions): Promise<A>;
+
+export { type FlowxOptions, type NamedStep, type ParallelOptions, Pipeline, PipelineStepError, PipelineTimeoutError, type SequenceOptions, type StepContext, type StepFn, parallel, parallelSettled, pipeline, sequence };

package/dist/index.js

@@ -0,0 +1,208 @@
+'use strict';
+
+// src/flowx.ts
+var PipelineStepError = class extends Error {
+  constructor(stepIndex, stepName, cause, inputValue) {
+    super(
+      `Pipeline failed at step ${stepIndex}${stepName ? ` (${stepName})` : ""}: ${String(cause)}`
+    );
+    this.stepIndex = stepIndex;
+    this.stepName = stepName;
+    this.cause = cause;
+    this.inputValue = inputValue;
+    this.name = "PipelineStepError";
+  }
+};
+var PipelineTimeoutError = class extends Error {
+  constructor(stepIndex, stepName, timeoutMs) {
+    super(`Step ${stepIndex}${stepName ? ` (${stepName})` : ""} timed out after ${timeoutMs}ms`);
+    this.stepIndex = stepIndex;
+    this.stepName = stepName;
+    this.timeoutMs = timeoutMs;
+    this.name = "PipelineTimeoutError";
+  }
+};
+var neverAborted = new AbortController().signal;
+function raceStepTimeout(promise, ms, index, name) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new PipelineTimeoutError(index, name, ms)), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+function normalizeStep(step) {
+  if (typeof step === "function") {
+    return { fn: step, name: void 0, timeoutMs: void 0 };
+  }
+  return { fn: step.fn, name: step.name, timeoutMs: step.timeoutMs };
+}
+var Pipeline = class _Pipeline {
+  records;
+  constructor(records = []) {
+    this.records = records;
+  }
+  /**
+   * Add a transform step. Accepts either a plain function or a `NamedStep`
+   * object with an optional per-step `timeoutMs`.
+   */
+  pipe(step) {
+    const { fn, name, timeoutMs } = normalizeStep(step);
+    const record = {
+      fn,
+      name,
+      timeoutMs,
+      isFallback: false
+    };
+    return new _Pipeline([...this.records, record]);
+  }
+  /**
+   * Add a step with an inline fallback. If the step throws, `fallback` is
+   * called with the error and the original input to that step.
+   */
+  pipeWithFallback(step, fallback) {
+    const { fn, name, timeoutMs } = normalizeStep(step);
+    const stepRecord = {
+      fn,
+      name,
+      timeoutMs,
+      isFallback: false
+    };
+    const fallbackRecord = {
+      fn: fallback,
+      isFallback: true
+    };
+    return new _Pipeline([...this.records, stepRecord, fallbackRecord]);
+  }
+  /**
+   * Add a side-effect step. Runs `fn` for its effect only; passes the current
+   * value through unchanged. Errors in `fn` propagate normally.
+   */
+  tap(fn) {
+    const tapStep = async (value, ctx) => {
+      await fn(value, ctx);
+      return value;
+    };
+    return this.pipe(tapStep);
+  }
+  async run(input, options = {}) {
+    const signal = options.signal ?? neverAborted;
+    const { onStepComplete, stepTimeoutMs } = options;
+    let current = input;
+    let stepIndex = 0;
+    for (let i = 0; i < this.records.length; i++) {
+      const record = this.records[i];
+      if (record.isFallback) {
+        continue;
+      }
+      if (signal.aborted) {
+        throw new DOMException("Pipeline aborted", "AbortError");
+      }
+      const inputValue = current;
+      const ctx = { signal, stepIndex, stepName: record.name };
+      const effectiveTimeout = record.timeoutMs ?? stepTimeoutMs;
+      try {
+        const rawResult = record.fn(current, ctx);
+        let stepPromise = rawResult instanceof Promise ? rawResult : Promise.resolve(rawResult);
+        if (effectiveTimeout != null) {
+          stepPromise = raceStepTimeout(stepPromise, effectiveTimeout, stepIndex, record.name);
+        }
+        current = await stepPromise;
+        onStepComplete?.(stepIndex, record.name, current);
+      } catch (err) {
+        const nextRecord = this.records[i + 1];
+        if (nextRecord?.isFallback) {
+          const pipelineErr = new PipelineStepError(stepIndex, record.name, err, inputValue);
+          current = await nextRecord.fn(pipelineErr, inputValue);
+          i++;
+          onStepComplete?.(stepIndex, record.name, current);
+        } else {
+          throw new PipelineStepError(stepIndex, record.name, err, inputValue);
+        }
+      }
+      stepIndex++;
+    }
+    return current;
+  }
+  get stepCount() {
+    return this.records.filter((r) => !r.isFallback).length;
+  }
+  /** Returns step metadata for debugging/tooling. */
+  toArray() {
+    let idx = 0;
+    const result = [];
+    for (const r of this.records) {
+      if (!r.isFallback) {
+        result.push({ index: idx++, name: r.name, timeoutMs: r.timeoutMs });
+      }
+    }
+    return result;
+  }
+};
+function pipeline() {
+  return new Pipeline();
+}
+async function parallel(tasks, options = {}) {
+  const { concurrency, signal } = options;
+  if (concurrency == null || concurrency >= tasks.length) {
+    if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+    return Promise.all(tasks.map((t) => t()));
+  }
+  const results = new Array(tasks.length);
+  let nextIndex = 0;
+  let hasError = false;
+  let firstError;
+  const run = async () => {
+    while (nextIndex < tasks.length) {
+      if (signal?.aborted || hasError) break;
+      const idx = nextIndex++;
+      try {
+        results[idx] = await tasks[idx]();
+      } catch (err) {
+        hasError = true;
+        firstError = err;
+        break;
+      }
+    }
+  };
+  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, run);
+  await Promise.all(workers);
+  if (hasError) throw firstError;
+  return results;
+}
+async function parallelSettled(tasks, options = {}) {
+  const { concurrency, signal } = options;
+  const wrapped = tasks.map(
+    (t) => () => t().then(
+      (value) => ({ status: "fulfilled", value }),
+      (reason) => ({ status: "rejected", reason })
+    )
+  );
+  return parallel(wrapped, { concurrency, signal });
+}
+async function sequence(items, initial, fn, options = {}) {
+  const { signal } = options;
+  let acc = initial;
+  for (let i = 0; i < items.length; i++) {
+    if (signal?.aborted) throw new DOMException("Sequence aborted", "AbortError");
+    acc = await fn(acc, items[i], i);
+  }
+  return acc;
+}
+
+exports.Pipeline = Pipeline;
+exports.PipelineStepError = PipelineStepError;
+exports.PipelineTimeoutError = PipelineTimeoutError;
+exports.parallel = parallel;
+exports.parallelSettled = parallelSettled;
+exports.pipeline = pipeline;
+exports.sequence = sequence;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/flowx.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["export type { StepFn, StepContext, NamedStep, FlowxOptions, ParallelOptions, SequenceOptions } from './types.js';\nimport type { StepFn, StepContext, NamedStep, FlowxOptions, ParallelOptions, SequenceOptions } from './types.js';\n\n// ─── Errors ──────────────────────────────────────────────────────────────────\n\nexport class PipelineStepError extends Error {\n  constructor(\n    public readonly stepIndex: number,\n    public readonly stepName: string | undefined,\n    public override readonly cause: unknown,\n    public readonly inputValue: unknown\n  ) {\n    super(\n      `Pipeline failed at step ${stepIndex}${stepName ? ` (${stepName})` : ''}: ${String(cause)}`\n    );\n    this.name = 'PipelineStepError';\n  }\n}\n\nexport class PipelineTimeoutError extends Error {\n  constructor(\n    public readonly stepIndex: number,\n    public readonly stepName: string | undefined,\n    public readonly timeoutMs: number\n  ) {\n    super(`Step ${stepIndex}${stepName ? ` (${stepName})` : ''} timed out after ${timeoutMs}ms`);\n    this.name = 'PipelineTimeoutError';\n  }\n}\n\n// ─── Internal Step Record ────────────────────────────────────────────────────\n\ninterface StepRecord {\n  fn: StepFn<unknown, unknown>;\n  name: string | undefined;\n  timeoutMs: number | undefined;\n  isFallback: false;\n}\n\ninterface FallbackRecord {\n  fn: (error: PipelineStepError, input: unknown) => unknown | Promise<unknown>;\n  isFallback: true;\n}\n\ntype AnyRecord = StepRecord | FallbackRecord;\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\nconst neverAborted = new AbortController().signal;\n\nfunction raceStepTimeout<T>(\n  promise: Promise<T>,\n  ms: number,\n  index: number,\n  name: string | undefined\n): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    const timer = setTimeout(() => reject(new PipelineTimeoutError(index, name, ms)), ms);\n    promise.then(\n      (v) => { clearTimeout(timer); resolve(v); },\n      (e) => { clearTimeout(timer); reject(e); }\n    );\n  });\n}\n\nfunction normalizeStep<In, Out>(\n  step: StepFn<In, Out> | NamedStep<In, Out>\n): { fn: StepFn<In, Out>; name: string | undefined; timeoutMs: number | undefined } {\n  if (typeof step === 'function') {\n    return { fn: step, name: undefined, timeoutMs: undefined };\n  }\n  return { fn: step.fn, name: step.name, timeoutMs: step.timeoutMs };\n}\n\n// ─── Pipeline ────────────────────────────────────────────────────────────────\n\n/**\n * Flowx — composable, type-safe async pipeline builder.\n *\n * Each step receives the output of the previous step as its first argument,\n * plus a `StepContext` carrying the abort signal, step index, and step name.\n *\n * @example\n * const result = await pipeline<string>()\n *   .pipe(s => s.trim())\n *   .pipe({ name: 'uppercase', fn: s => s.toUpperCase() })\n *   .tap(s => console.log('after uppercase:', s))\n *   .run('  hello  ');\n */\nexport class Pipeline<TIn, TOut> {\n  private readonly records: AnyRecord[];\n\n  constructor(records: AnyRecord[] = []) {\n    this.records = records;\n  }\n\n  /**\n   * Add a transform step. Accepts either a plain function or a `NamedStep`\n   * object with an optional per-step `timeoutMs`.\n   */\n  pipe<TNext>(\n    step: StepFn<TOut, TNext> | NamedStep<TOut, TNext>\n  ): Pipeline<TIn, TNext> {\n    const { fn, name, timeoutMs } = normalizeStep(step);\n    const record: StepRecord = {\n      fn: fn as StepFn<unknown, unknown>,\n      name,\n      timeoutMs,\n      isFallback: false,\n    };\n    return new Pipeline<TIn, TNext>([...this.records, record]);\n  }\n\n  /**\n   * Add a step with an inline fallback. If the step throws, `fallback` is\n   * called with the error and the original input to that step.\n   */\n  pipeWithFallback<TNext>(\n    step: StepFn<TOut, TNext> | NamedStep<TOut, TNext>,\n    fallback: (error: PipelineStepError, input: TOut) => TNext | Promise<TNext>\n  ): Pipeline<TIn, TNext> {\n    const { fn, name, timeoutMs } = normalizeStep(step);\n    const stepRecord: StepRecord = {\n      fn: fn as StepFn<unknown, unknown>,\n      name,\n      timeoutMs,\n      isFallback: false,\n    };\n    const fallbackRecord: FallbackRecord = {\n      fn: fallback as (error: PipelineStepError, input: unknown) => unknown,\n      isFallback: true,\n    };\n    return new Pipeline<TIn, TNext>([...this.records, stepRecord, fallbackRecord]);\n  }\n\n  /**\n   * Add a side-effect step. Runs `fn` for its effect only; passes the current\n   * value through unchanged. Errors in `fn` propagate normally.\n   */\n  tap(fn: (value: TOut, context: StepContext) => void | Promise<void>): Pipeline<TIn, TOut> {\n    const tapStep: StepFn<TOut, TOut> = async (value, ctx) => {\n      await fn(value, ctx);\n      return value;\n    };\n    return this.pipe(tapStep);\n  }\n\n  async run(input: TIn, options: FlowxOptions = {}): Promise<TOut> {\n    const signal = options.signal ?? neverAborted;\n    const { onStepComplete, stepTimeoutMs } = options;\n\n    let current: unknown = input;\n    let stepIndex = 0;\n\n    for (let i = 0; i < this.records.length; i++) {\n      const record = this.records[i];\n\n      if (record.isFallback) {\n        // Fallback records are consumed inline by the preceding step handler.\n        continue;\n      }\n\n      if (signal.aborted) {\n        throw new DOMException('Pipeline aborted', 'AbortError');\n      }\n\n      const inputValue = current;\n      const ctx: StepContext = { signal, stepIndex, stepName: record.name };\n      const effectiveTimeout = record.timeoutMs ?? stepTimeoutMs;\n\n      try {\n        const rawResult = record.fn(current, ctx);\n        let stepPromise: Promise<unknown> = rawResult instanceof Promise ? rawResult : Promise.resolve(rawResult);\n        if (effectiveTimeout != null) {\n          stepPromise = raceStepTimeout(stepPromise, effectiveTimeout, stepIndex, record.name);\n        }\n        current = await stepPromise;\n        onStepComplete?.(stepIndex, record.name, current);\n      } catch (err) {\n        // Check if the next record is a fallback for this step.\n        const nextRecord = this.records[i + 1];\n        if (nextRecord?.isFallback) {\n          const pipelineErr = new PipelineStepError(stepIndex, record.name, err, inputValue);\n          current = await nextRecord.fn(pipelineErr, inputValue);\n          i++; // skip the fallback record in the outer loop\n          onStepComplete?.(stepIndex, record.name, current);\n        } else {\n          throw new PipelineStepError(stepIndex, record.name, err, inputValue);\n        }\n      }\n\n      stepIndex++;\n    }\n\n    return current as TOut;\n  }\n\n  get stepCount(): number {\n    return this.records.filter((r) => !r.isFallback).length;\n  }\n\n  /** Returns step metadata for debugging/tooling. */\n  toArray(): Array<{ index: number; name: string | undefined; timeoutMs: number | undefined }> {\n    let idx = 0;\n    const result: Array<{ index: number; name: string | undefined; timeoutMs: number | undefined }> = [];\n    for (const r of this.records) {\n      if (!r.isFallback) {\n        result.push({ index: idx++, name: r.name, timeoutMs: r.timeoutMs });\n      }\n    }\n    return result;\n  }\n}\n\n// ─── Factory ─────────────────────────────────────────────────────────────────\n\n/** Create a new empty pipeline starting with type `T`. */\nexport function pipeline<T>(): Pipeline<T, T> {\n  return new Pipeline<T, T>();\n}\n\n// ─── parallel ────────────────────────────────────────────────────────────────\n\n/**\n * Run tasks concurrently, return results in declaration order.\n * Rejects if any task throws (like `Promise.all`).\n */\nexport async function parallel<T>(\n  tasks: Array<() => Promise<T>>,\n  options: ParallelOptions = {}\n): Promise<T[]> {\n  const { concurrency, signal } = options;\n\n  if (concurrency == null || concurrency >= tasks.length) {\n    // Unbounded — just Promise.all\n    if (signal?.aborted) throw new DOMException('Aborted', 'AbortError');\n    return Promise.all(tasks.map((t) => t()));\n  }\n\n  // Bounded concurrency via semaphore\n  const results: T[] = new Array(tasks.length);\n  let nextIndex = 0;\n  let hasError = false;\n  let firstError: unknown;\n\n  const run = async (): Promise<void> => {\n    while (nextIndex < tasks.length) {\n      if (signal?.aborted || hasError) break;\n      const idx = nextIndex++;\n      try {\n        results[idx] = await tasks[idx]();\n      } catch (err) {\n        hasError = true;\n        firstError = err;\n        break;\n      }\n    }\n  };\n\n  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, run);\n  await Promise.all(workers);\n\n  if (hasError) throw firstError;\n  return results;\n}\n\n/**\n * Run tasks concurrently and return all results regardless of success/failure.\n * Equivalent to `Promise.allSettled` but with optional concurrency control.\n */\nexport async function parallelSettled<T>(\n  tasks: Array<() => Promise<T>>,\n  options: Pick<ParallelOptions, 'concurrency' | 'signal'> = {}\n): Promise<PromiseSettledResult<T>[]> {\n  const { concurrency, signal } = options;\n  const wrapped = tasks.map((t) => (): Promise<PromiseSettledResult<T>> =>\n    t().then(\n      (value) => ({ status: 'fulfilled' as const, value }),\n      (reason) => ({ status: 'rejected' as const, reason })\n    )\n  );\n\n  return parallel(wrapped, { concurrency, signal }) as Promise<PromiseSettledResult<T>[]>;\n}\n\n// ─── sequence ────────────────────────────────────────────────────────────────\n\n/**\n * Async left-fold over an array. Like `Array.reduce` but supports async reducers\n * and can be cancelled via `AbortSignal`.\n */\nexport async function sequence<T, A>(\n  items: T[],\n  initial: A,\n  fn: (acc: A, item: T, index: number) => Promise<A> | A,\n  options: SequenceOptions = {}\n): Promise<A> {\n  const { signal } = options;\n  let acc = initial;\n  for (let i = 0; i < items.length; i++) {\n    if (signal?.aborted) throw new DOMException('Sequence aborted', 'AbortError');\n    acc = await fn(acc, items[i], i);\n  }\n  return acc;\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,200 @@
+// src/flowx.ts
+var PipelineStepError = class extends Error {
+  constructor(stepIndex, stepName, cause, inputValue) {
+    super(
+      `Pipeline failed at step ${stepIndex}${stepName ? ` (${stepName})` : ""}: ${String(cause)}`
+    );
+    this.stepIndex = stepIndex;
+    this.stepName = stepName;
+    this.cause = cause;
+    this.inputValue = inputValue;
+    this.name = "PipelineStepError";
+  }
+};
+var PipelineTimeoutError = class extends Error {
+  constructor(stepIndex, stepName, timeoutMs) {
+    super(`Step ${stepIndex}${stepName ? ` (${stepName})` : ""} timed out after ${timeoutMs}ms`);
+    this.stepIndex = stepIndex;
+    this.stepName = stepName;
+    this.timeoutMs = timeoutMs;
+    this.name = "PipelineTimeoutError";
+  }
+};
+var neverAborted = new AbortController().signal;
+function raceStepTimeout(promise, ms, index, name) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new PipelineTimeoutError(index, name, ms)), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+function normalizeStep(step) {
+  if (typeof step === "function") {
+    return { fn: step, name: void 0, timeoutMs: void 0 };
+  }
+  return { fn: step.fn, name: step.name, timeoutMs: step.timeoutMs };
+}
+var Pipeline = class _Pipeline {
+  records;
+  constructor(records = []) {
+    this.records = records;
+  }
+  /**
+   * Add a transform step. Accepts either a plain function or a `NamedStep`
+   * object with an optional per-step `timeoutMs`.
+   */
+  pipe(step) {
+    const { fn, name, timeoutMs } = normalizeStep(step);
+    const record = {
+      fn,
+      name,
+      timeoutMs,
+      isFallback: false
+    };
+    return new _Pipeline([...this.records, record]);
+  }
+  /**
+   * Add a step with an inline fallback. If the step throws, `fallback` is
+   * called with the error and the original input to that step.
+   */
+  pipeWithFallback(step, fallback) {
+    const { fn, name, timeoutMs } = normalizeStep(step);
+    const stepRecord = {
+      fn,
+      name,
+      timeoutMs,
+      isFallback: false
+    };
+    const fallbackRecord = {
+      fn: fallback,
+      isFallback: true
+    };
+    return new _Pipeline([...this.records, stepRecord, fallbackRecord]);
+  }
+  /**
+   * Add a side-effect step. Runs `fn` for its effect only; passes the current
+   * value through unchanged. Errors in `fn` propagate normally.
+   */
+  tap(fn) {
+    const tapStep = async (value, ctx) => {
+      await fn(value, ctx);
+      return value;
+    };
+    return this.pipe(tapStep);
+  }
+  async run(input, options = {}) {
+    const signal = options.signal ?? neverAborted;
+    const { onStepComplete, stepTimeoutMs } = options;
+    let current = input;
+    let stepIndex = 0;
+    for (let i = 0; i < this.records.length; i++) {
+      const record = this.records[i];
+      if (record.isFallback) {
+        continue;
+      }
+      if (signal.aborted) {
+        throw new DOMException("Pipeline aborted", "AbortError");
+      }
+      const inputValue = current;
+      const ctx = { signal, stepIndex, stepName: record.name };
+      const effectiveTimeout = record.timeoutMs ?? stepTimeoutMs;
+      try {
+        const rawResult = record.fn(current, ctx);
+        let stepPromise = rawResult instanceof Promise ? rawResult : Promise.resolve(rawResult);
+        if (effectiveTimeout != null) {
+          stepPromise = raceStepTimeout(stepPromise, effectiveTimeout, stepIndex, record.name);
+        }
+        current = await stepPromise;
+        onStepComplete?.(stepIndex, record.name, current);
+      } catch (err) {
+        const nextRecord = this.records[i + 1];
+        if (nextRecord?.isFallback) {
+          const pipelineErr = new PipelineStepError(stepIndex, record.name, err, inputValue);
+          current = await nextRecord.fn(pipelineErr, inputValue);
+          i++;
+          onStepComplete?.(stepIndex, record.name, current);
+        } else {
+          throw new PipelineStepError(stepIndex, record.name, err, inputValue);
+        }
+      }
+      stepIndex++;
+    }
+    return current;
+  }
+  get stepCount() {
+    return this.records.filter((r) => !r.isFallback).length;
+  }
+  /** Returns step metadata for debugging/tooling. */
+  toArray() {
+    let idx = 0;
+    const result = [];
+    for (const r of this.records) {
+      if (!r.isFallback) {
+        result.push({ index: idx++, name: r.name, timeoutMs: r.timeoutMs });
+      }
+    }
+    return result;
+  }
+};
+function pipeline() {
+  return new Pipeline();
+}
+async function parallel(tasks, options = {}) {
+  const { concurrency, signal } = options;
+  if (concurrency == null || concurrency >= tasks.length) {
+    if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+    return Promise.all(tasks.map((t) => t()));
+  }
+  const results = new Array(tasks.length);
+  let nextIndex = 0;
+  let hasError = false;
+  let firstError;
+  const run = async () => {
+    while (nextIndex < tasks.length) {
+      if (signal?.aborted || hasError) break;
+      const idx = nextIndex++;
+      try {
+        results[idx] = await tasks[idx]();
+      } catch (err) {
+        hasError = true;
+        firstError = err;
+        break;
+      }
+    }
+  };
+  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, run);
+  await Promise.all(workers);
+  if (hasError) throw firstError;
+  return results;
+}
+async function parallelSettled(tasks, options = {}) {
+  const { concurrency, signal } = options;
+  const wrapped = tasks.map(
+    (t) => () => t().then(
+      (value) => ({ status: "fulfilled", value }),
+      (reason) => ({ status: "rejected", reason })
+    )
+  );
+  return parallel(wrapped, { concurrency, signal });
+}
+async function sequence(items, initial, fn, options = {}) {
+  const { signal } = options;
+  let acc = initial;
+  for (let i = 0; i < items.length; i++) {
+    if (signal?.aborted) throw new DOMException("Sequence aborted", "AbortError");
+    acc = await fn(acc, items[i], i);
+  }
+  return acc;
+}
+
+export { Pipeline, PipelineStepError, PipelineTimeoutError, parallel, parallelSettled, pipeline, sequence };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/flowx.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["export type { StepFn, StepContext, NamedStep, FlowxOptions, ParallelOptions, SequenceOptions } from './types.js';\nimport type { StepFn, StepContext, NamedStep, FlowxOptions, ParallelOptions, SequenceOptions } from './types.js';\n\n// ─── Errors ──────────────────────────────────────────────────────────────────\n\nexport class PipelineStepError extends Error {\n  constructor(\n    public readonly stepIndex: number,\n    public readonly stepName: string | undefined,\n    public override readonly cause: unknown,\n    public readonly inputValue: unknown\n  ) {\n    super(\n      `Pipeline failed at step ${stepIndex}${stepName ? ` (${stepName})` : ''}: ${String(cause)}`\n    );\n    this.name = 'PipelineStepError';\n  }\n}\n\nexport class PipelineTimeoutError extends Error {\n  constructor(\n    public readonly stepIndex: number,\n    public readonly stepName: string | undefined,\n    public readonly timeoutMs: number\n  ) {\n    super(`Step ${stepIndex}${stepName ? ` (${stepName})` : ''} timed out after ${timeoutMs}ms`);\n    this.name = 'PipelineTimeoutError';\n  }\n}\n\n// ─── Internal Step Record ────────────────────────────────────────────────────\n\ninterface StepRecord {\n  fn: StepFn<unknown, unknown>;\n  name: string | undefined;\n  timeoutMs: number | undefined;\n  isFallback: false;\n}\n\ninterface FallbackRecord {\n  fn: (error: PipelineStepError, input: unknown) => unknown | Promise<unknown>;\n  isFallback: true;\n}\n\ntype AnyRecord = StepRecord | FallbackRecord;\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\nconst neverAborted = new AbortController().signal;\n\nfunction raceStepTimeout<T>(\n  promise: Promise<T>,\n  ms: number,\n  index: number,\n  name: string | undefined\n): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    const timer = setTimeout(() => reject(new PipelineTimeoutError(index, name, ms)), ms);\n    promise.then(\n      (v) => { clearTimeout(timer); resolve(v); },\n      (e) => { clearTimeout(timer); reject(e); }\n    );\n  });\n}\n\nfunction normalizeStep<In, Out>(\n  step: StepFn<In, Out> | NamedStep<In, Out>\n): { fn: StepFn<In, Out>; name: string | undefined; timeoutMs: number | undefined } {\n  if (typeof step === 'function') {\n    return { fn: step, name: undefined, timeoutMs: undefined };\n  }\n  return { fn: step.fn, name: step.name, timeoutMs: step.timeoutMs };\n}\n\n// ─── Pipeline ────────────────────────────────────────────────────────────────\n\n/**\n * Flowx — composable, type-safe async pipeline builder.\n *\n * Each step receives the output of the previous step as its first argument,\n * plus a `StepContext` carrying the abort signal, step index, and step name.\n *\n * @example\n * const result = await pipeline<string>()\n *   .pipe(s => s.trim())\n *   .pipe({ name: 'uppercase', fn: s => s.toUpperCase() })\n *   .tap(s => console.log('after uppercase:', s))\n *   .run('  hello  ');\n */\nexport class Pipeline<TIn, TOut> {\n  private readonly records: AnyRecord[];\n\n  constructor(records: AnyRecord[] = []) {\n    this.records = records;\n  }\n\n  /**\n   * Add a transform step. Accepts either a plain function or a `NamedStep`\n   * object with an optional per-step `timeoutMs`.\n   */\n  pipe<TNext>(\n    step: StepFn<TOut, TNext> | NamedStep<TOut, TNext>\n  ): Pipeline<TIn, TNext> {\n    const { fn, name, timeoutMs } = normalizeStep(step);\n    const record: StepRecord = {\n      fn: fn as StepFn<unknown, unknown>,\n      name,\n      timeoutMs,\n      isFallback: false,\n    };\n    return new Pipeline<TIn, TNext>([...this.records, record]);\n  }\n\n  /**\n   * Add a step with an inline fallback. If the step throws, `fallback` is\n   * called with the error and the original input to that step.\n   */\n  pipeWithFallback<TNext>(\n    step: StepFn<TOut, TNext> | NamedStep<TOut, TNext>,\n    fallback: (error: PipelineStepError, input: TOut) => TNext | Promise<TNext>\n  ): Pipeline<TIn, TNext> {\n    const { fn, name, timeoutMs } = normalizeStep(step);\n    const stepRecord: StepRecord = {\n      fn: fn as StepFn<unknown, unknown>,\n      name,\n      timeoutMs,\n      isFallback: false,\n    };\n    const fallbackRecord: FallbackRecord = {\n      fn: fallback as (error: PipelineStepError, input: unknown) => unknown,\n      isFallback: true,\n    };\n    return new Pipeline<TIn, TNext>([...this.records, stepRecord, fallbackRecord]);\n  }\n\n  /**\n   * Add a side-effect step. Runs `fn` for its effect only; passes the current\n   * value through unchanged. Errors in `fn` propagate normally.\n   */\n  tap(fn: (value: TOut, context: StepContext) => void | Promise<void>): Pipeline<TIn, TOut> {\n    const tapStep: StepFn<TOut, TOut> = async (value, ctx) => {\n      await fn(value, ctx);\n      return value;\n    };\n    return this.pipe(tapStep);\n  }\n\n  async run(input: TIn, options: FlowxOptions = {}): Promise<TOut> {\n    const signal = options.signal ?? neverAborted;\n    const { onStepComplete, stepTimeoutMs } = options;\n\n    let current: unknown = input;\n    let stepIndex = 0;\n\n    for (let i = 0; i < this.records.length; i++) {\n      const record = this.records[i];\n\n      if (record.isFallback) {\n        // Fallback records are consumed inline by the preceding step handler.\n        continue;\n      }\n\n      if (signal.aborted) {\n        throw new DOMException('Pipeline aborted', 'AbortError');\n      }\n\n      const inputValue = current;\n      const ctx: StepContext = { signal, stepIndex, stepName: record.name };\n      const effectiveTimeout = record.timeoutMs ?? stepTimeoutMs;\n\n      try {\n        const rawResult = record.fn(current, ctx);\n        let stepPromise: Promise<unknown> = rawResult instanceof Promise ? rawResult : Promise.resolve(rawResult);\n        if (effectiveTimeout != null) {\n          stepPromise = raceStepTimeout(stepPromise, effectiveTimeout, stepIndex, record.name);\n        }\n        current = await stepPromise;\n        onStepComplete?.(stepIndex, record.name, current);\n      } catch (err) {\n        // Check if the next record is a fallback for this step.\n        const nextRecord = this.records[i + 1];\n        if (nextRecord?.isFallback) {\n          const pipelineErr = new PipelineStepError(stepIndex, record.name, err, inputValue);\n          current = await nextRecord.fn(pipelineErr, inputValue);\n          i++; // skip the fallback record in the outer loop\n          onStepComplete?.(stepIndex, record.name, current);\n        } else {\n          throw new PipelineStepError(stepIndex, record.name, err, inputValue);\n        }\n      }\n\n      stepIndex++;\n    }\n\n    return current as TOut;\n  }\n\n  get stepCount(): number {\n    return this.records.filter((r) => !r.isFallback).length;\n  }\n\n  /** Returns step metadata for debugging/tooling. */\n  toArray(): Array<{ index: number; name: string | undefined; timeoutMs: number | undefined }> {\n    let idx = 0;\n    const result: Array<{ index: number; name: string | undefined; timeoutMs: number | undefined }> = [];\n    for (const r of this.records) {\n      if (!r.isFallback) {\n        result.push({ index: idx++, name: r.name, timeoutMs: r.timeoutMs });\n      }\n    }\n    return result;\n  }\n}\n\n// ─── Factory ─────────────────────────────────────────────────────────────────\n\n/** Create a new empty pipeline starting with type `T`. */\nexport function pipeline<T>(): Pipeline<T, T> {\n  return new Pipeline<T, T>();\n}\n\n// ─── parallel ────────────────────────────────────────────────────────────────\n\n/**\n * Run tasks concurrently, return results in declaration order.\n * Rejects if any task throws (like `Promise.all`).\n */\nexport async function parallel<T>(\n  tasks: Array<() => Promise<T>>,\n  options: ParallelOptions = {}\n): Promise<T[]> {\n  const { concurrency, signal } = options;\n\n  if (concurrency == null || concurrency >= tasks.length) {\n    // Unbounded — just Promise.all\n    if (signal?.aborted) throw new DOMException('Aborted', 'AbortError');\n    return Promise.all(tasks.map((t) => t()));\n  }\n\n  // Bounded concurrency via semaphore\n  const results: T[] = new Array(tasks.length);\n  let nextIndex = 0;\n  let hasError = false;\n  let firstError: unknown;\n\n  const run = async (): Promise<void> => {\n    while (nextIndex < tasks.length) {\n      if (signal?.aborted || hasError) break;\n      const idx = nextIndex++;\n      try {\n        results[idx] = await tasks[idx]();\n      } catch (err) {\n        hasError = true;\n        firstError = err;\n        break;\n      }\n    }\n  };\n\n  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, run);\n  await Promise.all(workers);\n\n  if (hasError) throw firstError;\n  return results;\n}\n\n/**\n * Run tasks concurrently and return all results regardless of success/failure.\n * Equivalent to `Promise.allSettled` but with optional concurrency control.\n */\nexport async function parallelSettled<T>(\n  tasks: Array<() => Promise<T>>,\n  options: Pick<ParallelOptions, 'concurrency' | 'signal'> = {}\n): Promise<PromiseSettledResult<T>[]> {\n  const { concurrency, signal } = options;\n  const wrapped = tasks.map((t) => (): Promise<PromiseSettledResult<T>> =>\n    t().then(\n      (value) => ({ status: 'fulfilled' as const, value }),\n      (reason) => ({ status: 'rejected' as const, reason })\n    )\n  );\n\n  return parallel(wrapped, { concurrency, signal }) as Promise<PromiseSettledResult<T>[]>;\n}\n\n// ─── sequence ────────────────────────────────────────────────────────────────\n\n/**\n * Async left-fold over an array. Like `Array.reduce` but supports async reducers\n * and can be cancelled via `AbortSignal`.\n */\nexport async function sequence<T, A>(\n  items: T[],\n  initial: A,\n  fn: (acc: A, item: T, index: number) => Promise<A> | A,\n  options: SequenceOptions = {}\n): Promise<A> {\n  const { signal } = options;\n  let acc = initial;\n  for (let i = 0; i < items.length; i++) {\n    if (signal?.aborted) throw new DOMException('Sequence aborted', 'AbortError');\n    acc = await fn(acc, items[i], i);\n  }\n  return acc;\n}\n"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@async-kit/flowx",
+  "version": "0.1.2",
+  "description": "Composable async pipeline builder for JavaScript/TypeScript",
+  "keywords": [
+    "async",
+    "pipeline",
+    "flow",
+    "stream",
+    "compose",
+    "transform"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NexaLeaf/async-kit",
+    "directory": "packages/flowx"
+  },
+  "homepage": "https://github.com/NexaLeaf/async-kit/tree/main/packages/flowx#readme",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.lib.json --noEmit"
+  },
+  "devDependencies": {}
+}