@icazemier/sway 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Ivo Cazemier
+
+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,90 @@
+<img src="gibbons.png" width="200" />
+
+# @icazemier/sway
+
+`Promise.all()` with adaptive concurrency control. A gradient-based controller continuously measures throughput and adjusts the concurrency level to maximise task completion speed — zero dependencies.
+
+## Install
+
+```bash
+npm install @icazemier/sway
+```
+
+## Usage
+
+```ts
+import { sway } from '@icazemier/sway';
+
+const { results, stats } = await sway(
+  urls.map(url => () => fetch(url).then(r => r.json())),
+  { maxConcurrency: 16 }
+);
+
+console.log(results);              // resolved values in original order
+console.log(stats.peakConcurrency); // highest concurrency reached
+console.log(stats.avgConcurrency);  // average concurrency across the run
+```
+
+## How it works
+
+Sway starts at `initialConcurrency` and probes every `probeInterval` completed tasks. Each probe measures throughput (tasks/sec) using an exponential moving average and compares it to the previous measurement:
+
+- **Gradient > 0** — throughput improving, increase concurrency by 1
+- **Gradient < 0** — throughput degrading, decrease concurrency by 1
+- **Gradient = 0** — at optimum, hold steady
+
+Concurrency is always clamped between `minConcurrency` and `maxConcurrency`. The `smoothingFactor` controls how responsive the EMA is to change (lower = calmer).
+
+## Options
+
+All values are **counts** or **ratios** — no time-based units.
+
+| Option               | Default | Unit  | Description                                   |
+| -------------------- | ------- | ----- | --------------------------------------------- |
+| `maxConcurrency`     | `64`    | tasks | Max concurrent in-flight tasks                |
+| `minConcurrency`     | `1`    | tasks  | Min concurrent in-flight tasks                |
+| `initialConcurrency` | `4`    | tasks  | Concurrent in-flight tasks to start with      |
+| `smoothingFactor`    | `0.3`  | ratio  | EMA smoothing (0–1), lower = calmer           |
+| `probeInterval`      | `8`    | tasks  | Completed tasks between probe adjustments     |
+
+## Error handling
+
+Sway rejects on the first error, just like `Promise.all()`.
+
+```ts
+try {
+  await sway(tasks);
+} catch (err) {
+  // first task rejection
+}
+```
+
+## Iterables
+
+Accepts any `Iterable` — arrays, generators, or custom iterables. Tasks are pulled lazily from the iterator.
+
+```ts
+function* generateTasks() {
+  for (const id of ids) {
+    yield () => processItem(id);
+  }
+}
+
+const { results } = await sway(generateTasks());
+```
+
+## Advanced: AdaptiveController
+
+The controller is exported separately for custom integrations.
+
+```ts
+import { AdaptiveController } from '@icazemier/sway';
+
+const controller = new AdaptiveController({ maxConcurrency: 32 });
+controller.getConcurrency();  // current level
+controller.recordCompletion(); // signal a completed task
+```
+
+## License
+
+MIT

package/build/cjs/adaptive-controller.d.ts

@@ -0,0 +1,54 @@
+import { SwayOptions, SwayStats } from './interfaces.js';
+/**
+ * Gradient-based concurrency controller.
+ *
+ * Measures throughput via an exponential moving average (EMA) and adjusts the
+ * concurrency level to maximise task completion speed. The controller probes
+ * every {@link SwayOptions.probeInterval | probeInterval} completed tasks,
+ * compares the current EMA throughput against the previous one, and nudges
+ * concurrency up or down by one depending on the gradient direction.
+ *
+ * @example
+ * ```ts
+ * const controller = new AdaptiveController({ maxConcurrency: 16 });
+ * controller.getConcurrency(); // 4 (default initial)
+ * controller.recordCompletion();
+ * ```
+ */
+export declare class AdaptiveController {
+    private concurrency;
+    private readonly maxConcurrency;
+    private readonly minConcurrency;
+    private readonly smoothingFactor;
+    private readonly probeInterval;
+    private completionsSinceLastProbe;
+    private emaThroughput;
+    private previousEmaThroughput;
+    private lastProbeTime;
+    private peakConcurrency;
+    private concurrencySum;
+    private concurrencySamples;
+    private adjustmentCount;
+    /**
+     * @param options - Tuning knobs for the controller (all optional)
+     */
+    constructor(options?: SwayOptions);
+    /**
+     * Signal that a task has completed. Triggers a probe when
+     * {@link SwayOptions.probeInterval | probeInterval} completions have accumulated.
+     */
+    recordCompletion(): void;
+    /** Returns the current concurrency level. */
+    getConcurrency(): number;
+    /**
+     * Build a {@link SwayStats} snapshot.
+     *
+     * @param totalTasks - Total tasks executed
+     * @param totalDurationMs - Wall-clock duration of the run in milliseconds
+     * @returns Performance telemetry
+     */
+    getStats(totalTasks: number, totalDurationMs: number): SwayStats;
+    private probe;
+    private setConcurrency;
+    private clamp;
+}

package/build/cjs/adaptive-controller.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdaptiveController = void 0;
+const DEFAULT_MAX_CONCURRENCY = 64;
+const DEFAULT_MIN_CONCURRENCY = 1;
+const DEFAULT_INITIAL_CONCURRENCY = 4;
+const DEFAULT_SMOOTHING_FACTOR = 0.3;
+const DEFAULT_PROBE_INTERVAL = 8;
+/**
+ * Gradient-based concurrency controller.
+ *
+ * Measures throughput via an exponential moving average (EMA) and adjusts the
+ * concurrency level to maximise task completion speed. The controller probes
+ * every {@link SwayOptions.probeInterval | probeInterval} completed tasks,
+ * compares the current EMA throughput against the previous one, and nudges
+ * concurrency up or down by one depending on the gradient direction.
+ *
+ * @example
+ * ```ts
+ * const controller = new AdaptiveController({ maxConcurrency: 16 });
+ * controller.getConcurrency(); // 4 (default initial)
+ * controller.recordCompletion();
+ * ```
+ */
+class AdaptiveController {
+    /**
+     * @param options - Tuning knobs for the controller (all optional)
+     */
+    constructor(options) {
+        var _a, _b, _c, _d, _e;
+        this.completionsSinceLastProbe = 0;
+        this.emaThroughput = null;
+        this.previousEmaThroughput = null;
+        this.concurrencySum = 0;
+        this.concurrencySamples = 0;
+        this.adjustmentCount = 0;
+        this.maxConcurrency = (_a = options === null || options === void 0 ? void 0 : options.maxConcurrency) !== null && _a !== void 0 ? _a : DEFAULT_MAX_CONCURRENCY;
+        this.minConcurrency = (_b = options === null || options === void 0 ? void 0 : options.minConcurrency) !== null && _b !== void 0 ? _b : DEFAULT_MIN_CONCURRENCY;
+        this.concurrency =
+            (_c = options === null || options === void 0 ? void 0 : options.initialConcurrency) !== null && _c !== void 0 ? _c : DEFAULT_INITIAL_CONCURRENCY;
+        this.smoothingFactor = (_d = options === null || options === void 0 ? void 0 : options.smoothingFactor) !== null && _d !== void 0 ? _d : DEFAULT_SMOOTHING_FACTOR;
+        this.probeInterval = (_e = options === null || options === void 0 ? void 0 : options.probeInterval) !== null && _e !== void 0 ? _e : DEFAULT_PROBE_INTERVAL;
+        this.concurrency = this.clamp(this.concurrency);
+        this.peakConcurrency = this.concurrency;
+        this.lastProbeTime = performance.now();
+    }
+    /**
+     * Signal that a task has completed. Triggers a probe when
+     * {@link SwayOptions.probeInterval | probeInterval} completions have accumulated.
+     */
+    recordCompletion() {
+        this.completionsSinceLastProbe++;
+        this.concurrencySum += this.concurrency;
+        this.concurrencySamples++;
+        if (this.completionsSinceLastProbe >= this.probeInterval) {
+            this.probe();
+        }
+    }
+    /** Returns the current concurrency level. */
+    getConcurrency() {
+        return this.concurrency;
+    }
+    /**
+     * Build a {@link SwayStats} snapshot.
+     *
+     * @param totalTasks - Total tasks executed
+     * @param totalDurationMs - Wall-clock duration of the run in milliseconds
+     * @returns Performance telemetry
+     */
+    getStats(totalTasks, totalDurationMs) {
+        return {
+            totalTasks,
+            totalDurationMs,
+            peakConcurrency: this.peakConcurrency,
+            avgConcurrency: this.concurrencySamples > 0
+                ? this.concurrencySum / this.concurrencySamples
+                : this.concurrency,
+            adjustments: this.adjustmentCount,
+        };
+    }
+    probe() {
+        const now = performance.now();
+        const elapsed = now - this.lastProbeTime;
+        if (elapsed <= 0) {
+            this.completionsSinceLastProbe = 0;
+            this.lastProbeTime = now;
+            return;
+        }
+        const currentThroughput = this.completionsSinceLastProbe / (elapsed / 1000);
+        if (this.emaThroughput === null) {
+            this.emaThroughput = currentThroughput;
+        }
+        else {
+            this.emaThroughput =
+                this.smoothingFactor * currentThroughput +
+                    (1 - this.smoothingFactor) * this.emaThroughput;
+        }
+        if (this.previousEmaThroughput !== null) {
+            const gradient = this.emaThroughput - this.previousEmaThroughput;
+            if (gradient > 0) {
+                this.setConcurrency(this.concurrency + 1);
+            }
+            else if (gradient < 0) {
+                this.setConcurrency(this.concurrency - 1);
+            }
+        }
+        this.previousEmaThroughput = this.emaThroughput;
+        this.completionsSinceLastProbe = 0;
+        this.lastProbeTime = now;
+    }
+    setConcurrency(value) {
+        const clamped = this.clamp(value);
+        if (clamped !== this.concurrency) {
+            this.concurrency = clamped;
+            this.adjustmentCount++;
+            if (this.concurrency > this.peakConcurrency) {
+                this.peakConcurrency = this.concurrency;
+            }
+        }
+    }
+    clamp(value) {
+        return Math.max(this.minConcurrency, Math.min(this.maxConcurrency, value));
+    }
+}
+exports.AdaptiveController = AdaptiveController;

package/build/cjs/index.d.ts

@@ -0,0 +1,3 @@
+export { sway } from './sway.js';
+export { AdaptiveController } from './adaptive-controller.js';
+export type { SwayOptions, SwayResult, SwayStats } from './interfaces.js';

package/build/cjs/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdaptiveController = exports.sway = void 0;
+var sway_js_1 = require("./sway.js");
+Object.defineProperty(exports, "sway", { enumerable: true, get: function () { return sway_js_1.sway; } });
+var adaptive_controller_js_1 = require("./adaptive-controller.js");
+Object.defineProperty(exports, "AdaptiveController", { enumerable: true, get: function () { return adaptive_controller_js_1.AdaptiveController; } });

package/build/cjs/interfaces.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Configuration options for {@link sway}.
+ */
+export interface SwayOptions {
+    /** Upper bound for concurrent in-flight tasks (default: `64`) */
+    maxConcurrency?: number;
+    /** Lower bound for concurrent in-flight tasks (default: `1`) */
+    minConcurrency?: number;
+    /** Number of concurrent in-flight tasks to start with (default: `4`) */
+    initialConcurrency?: number;
+    /** EMA smoothing factor, ratio between 0 and 1 — lower values produce calmer adjustments (default: `0.3`) */
+    smoothingFactor?: number;
+    /** Number of completed tasks between probe adjustments (default: `8`) */
+    probeInterval?: number;
+}
+/**
+ * Performance telemetry collected during a {@link sway} run.
+ */
+export interface SwayStats {
+    /** Total number of tasks that were executed */
+    totalTasks: number;
+    /** Wall-clock duration of the entire run in milliseconds */
+    totalDurationMs: number;
+    /** Highest concurrency level reached */
+    peakConcurrency: number;
+    /** Weighted average concurrency level across the run */
+    avgConcurrency: number;
+    /** Number of times the controller changed the concurrency level */
+    adjustments: number;
+}
+/**
+ * Return value of {@link sway}.
+ *
+ * @typeParam T - The resolved type of each task
+ */
+export interface SwayResult<T> {
+    /** Resolved values in the same order as the input tasks */
+    results: T[];
+    /** Performance telemetry for the run */
+    stats: SwayStats;
+}

package/build/cjs/interfaces.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/build/cjs/sway.d.ts

@@ -0,0 +1,25 @@
+import { SwayOptions, SwayResult } from './interfaces.js';
+/**
+ * Run async tasks concurrently with adaptive concurrency control.
+ *
+ * Works like `Promise.all()` but automatically tunes the number of in-flight
+ * tasks using a gradient-based controller that maximises throughput.
+ * Rejects on the first error (fail-fast), just like `Promise.all()`.
+ *
+ * @typeParam T - The resolved type of each task
+ * @param tasks - An iterable of zero-argument async functions (thunks)
+ * @param options - Optional tuning parameters for the adaptive controller
+ * @returns Resolved values in input order together with performance stats
+ *
+ * @example
+ * ```ts
+ * import { sway } from '@icazemier/sway';
+ *
+ * const { results, stats } = await sway(
+ *   urls.map(url => () => fetch(url).then(r => r.json())),
+ *   { maxConcurrency: 16 }
+ * );
+ * console.log(stats.peakConcurrency, stats.avgConcurrency);
+ * ```
+ */
+export declare function sway<T>(tasks: Iterable<() => Promise<T>>, options?: SwayOptions): Promise<SwayResult<T>>;

package/build/cjs/sway.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sway = sway;
+const adaptive_controller_js_1 = require("./adaptive-controller.js");
+/**
+ * Run async tasks concurrently with adaptive concurrency control.
+ *
+ * Works like `Promise.all()` but automatically tunes the number of in-flight
+ * tasks using a gradient-based controller that maximises throughput.
+ * Rejects on the first error (fail-fast), just like `Promise.all()`.
+ *
+ * @typeParam T - The resolved type of each task
+ * @param tasks - An iterable of zero-argument async functions (thunks)
+ * @param options - Optional tuning parameters for the adaptive controller
+ * @returns Resolved values in input order together with performance stats
+ *
+ * @example
+ * ```ts
+ * import { sway } from '@icazemier/sway';
+ *
+ * const { results, stats } = await sway(
+ *   urls.map(url => () => fetch(url).then(r => r.json())),
+ *   { maxConcurrency: 16 }
+ * );
+ * console.log(stats.peakConcurrency, stats.avgConcurrency);
+ * ```
+ */
+async function sway(tasks, options) {
+    const controller = new adaptive_controller_js_1.AdaptiveController(options);
+    const iterator = tasks[Symbol.iterator]();
+    const results = [];
+    const startTime = performance.now();
+    let nextIndex = 0;
+    let activeTasks = 0;
+    let settled = false;
+    let totalTasks = 0;
+    return new Promise((resolve, reject) => {
+        const tryReject = (error) => {
+            if (!settled) {
+                settled = true;
+                reject(error);
+            }
+        };
+        const scheduleNext = () => {
+            while (!settled && activeTasks < controller.getConcurrency()) {
+                const next = iterator.next();
+                if (next.done) {
+                    if (activeTasks === 0) {
+                        settled = true;
+                        const totalDurationMs = performance.now() - startTime;
+                        resolve({
+                            results,
+                            stats: controller.getStats(totalTasks, totalDurationMs),
+                        });
+                    }
+                    return;
+                }
+                const index = nextIndex++;
+                totalTasks++;
+                activeTasks++;
+                next
+                    .value()
+                    .then((value) => {
+                    if (settled)
+                        return;
+                    results[index] = value;
+                    activeTasks--;
+                    controller.recordCompletion();
+                    scheduleNext();
+                })
+                    .catch(tryReject);
+            }
+        };
+        scheduleNext();
+        if (nextIndex === 0 && activeTasks === 0) {
+            settled = true;
+            const totalDurationMs = performance.now() - startTime;
+            resolve({
+                results,
+                stats: controller.getStats(0, totalDurationMs),
+            });
+        }
+    });
+}

package/build/esm/adaptive-controller.d.ts

@@ -0,0 +1,54 @@
+import { SwayOptions, SwayStats } from './interfaces.js';
+/**
+ * Gradient-based concurrency controller.
+ *
+ * Measures throughput via an exponential moving average (EMA) and adjusts the
+ * concurrency level to maximise task completion speed. The controller probes
+ * every {@link SwayOptions.probeInterval | probeInterval} completed tasks,
+ * compares the current EMA throughput against the previous one, and nudges
+ * concurrency up or down by one depending on the gradient direction.
+ *
+ * @example
+ * ```ts
+ * const controller = new AdaptiveController({ maxConcurrency: 16 });
+ * controller.getConcurrency(); // 4 (default initial)
+ * controller.recordCompletion();
+ * ```
+ */
+export declare class AdaptiveController {
+    private concurrency;
+    private readonly maxConcurrency;
+    private readonly minConcurrency;
+    private readonly smoothingFactor;
+    private readonly probeInterval;
+    private completionsSinceLastProbe;
+    private emaThroughput;
+    private previousEmaThroughput;
+    private lastProbeTime;
+    private peakConcurrency;
+    private concurrencySum;
+    private concurrencySamples;
+    private adjustmentCount;
+    /**
+     * @param options - Tuning knobs for the controller (all optional)
+     */
+    constructor(options?: SwayOptions);
+    /**
+     * Signal that a task has completed. Triggers a probe when
+     * {@link SwayOptions.probeInterval | probeInterval} completions have accumulated.
+     */
+    recordCompletion(): void;
+    /** Returns the current concurrency level. */
+    getConcurrency(): number;
+    /**
+     * Build a {@link SwayStats} snapshot.
+     *
+     * @param totalTasks - Total tasks executed
+     * @param totalDurationMs - Wall-clock duration of the run in milliseconds
+     * @returns Performance telemetry
+     */
+    getStats(totalTasks: number, totalDurationMs: number): SwayStats;
+    private probe;
+    private setConcurrency;
+    private clamp;
+}

package/build/esm/adaptive-controller.js

@@ -0,0 +1,127 @@
+const DEFAULT_MAX_CONCURRENCY = 64;
+const DEFAULT_MIN_CONCURRENCY = 1;
+const DEFAULT_INITIAL_CONCURRENCY = 4;
+const DEFAULT_SMOOTHING_FACTOR = 0.3;
+const DEFAULT_PROBE_INTERVAL = 8;
+/**
+ * Gradient-based concurrency controller.
+ *
+ * Measures throughput via an exponential moving average (EMA) and adjusts the
+ * concurrency level to maximise task completion speed. The controller probes
+ * every {@link SwayOptions.probeInterval | probeInterval} completed tasks,
+ * compares the current EMA throughput against the previous one, and nudges
+ * concurrency up or down by one depending on the gradient direction.
+ *
+ * @example
+ * ```ts
+ * const controller = new AdaptiveController({ maxConcurrency: 16 });
+ * controller.getConcurrency(); // 4 (default initial)
+ * controller.recordCompletion();
+ * ```
+ */
+export class AdaptiveController {
+    concurrency;
+    maxConcurrency;
+    minConcurrency;
+    smoothingFactor;
+    probeInterval;
+    completionsSinceLastProbe = 0;
+    emaThroughput = null;
+    previousEmaThroughput = null;
+    lastProbeTime;
+    peakConcurrency;
+    concurrencySum = 0;
+    concurrencySamples = 0;
+    adjustmentCount = 0;
+    /**
+     * @param options - Tuning knobs for the controller (all optional)
+     */
+    constructor(options) {
+        this.maxConcurrency = options?.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY;
+        this.minConcurrency = options?.minConcurrency ?? DEFAULT_MIN_CONCURRENCY;
+        this.concurrency =
+            options?.initialConcurrency ?? DEFAULT_INITIAL_CONCURRENCY;
+        this.smoothingFactor = options?.smoothingFactor ?? DEFAULT_SMOOTHING_FACTOR;
+        this.probeInterval = options?.probeInterval ?? DEFAULT_PROBE_INTERVAL;
+        this.concurrency = this.clamp(this.concurrency);
+        this.peakConcurrency = this.concurrency;
+        this.lastProbeTime = performance.now();
+    }
+    /**
+     * Signal that a task has completed. Triggers a probe when
+     * {@link SwayOptions.probeInterval | probeInterval} completions have accumulated.
+     */
+    recordCompletion() {
+        this.completionsSinceLastProbe++;
+        this.concurrencySum += this.concurrency;
+        this.concurrencySamples++;
+        if (this.completionsSinceLastProbe >= this.probeInterval) {
+            this.probe();
+        }
+    }
+    /** Returns the current concurrency level. */
+    getConcurrency() {
+        return this.concurrency;
+    }
+    /**
+     * Build a {@link SwayStats} snapshot.
+     *
+     * @param totalTasks - Total tasks executed
+     * @param totalDurationMs - Wall-clock duration of the run in milliseconds
+     * @returns Performance telemetry
+     */
+    getStats(totalTasks, totalDurationMs) {
+        return {
+            totalTasks,
+            totalDurationMs,
+            peakConcurrency: this.peakConcurrency,
+            avgConcurrency: this.concurrencySamples > 0
+                ? this.concurrencySum / this.concurrencySamples
+                : this.concurrency,
+            adjustments: this.adjustmentCount,
+        };
+    }
+    probe() {
+        const now = performance.now();
+        const elapsed = now - this.lastProbeTime;
+        if (elapsed <= 0) {
+            this.completionsSinceLastProbe = 0;
+            this.lastProbeTime = now;
+            return;
+        }
+        const currentThroughput = this.completionsSinceLastProbe / (elapsed / 1000);
+        if (this.emaThroughput === null) {
+            this.emaThroughput = currentThroughput;
+        }
+        else {
+            this.emaThroughput =
+                this.smoothingFactor * currentThroughput +
+                    (1 - this.smoothingFactor) * this.emaThroughput;
+        }
+        if (this.previousEmaThroughput !== null) {
+            const gradient = this.emaThroughput - this.previousEmaThroughput;
+            if (gradient > 0) {
+                this.setConcurrency(this.concurrency + 1);
+            }
+            else if (gradient < 0) {
+                this.setConcurrency(this.concurrency - 1);
+            }
+        }
+        this.previousEmaThroughput = this.emaThroughput;
+        this.completionsSinceLastProbe = 0;
+        this.lastProbeTime = now;
+    }
+    setConcurrency(value) {
+        const clamped = this.clamp(value);
+        if (clamped !== this.concurrency) {
+            this.concurrency = clamped;
+            this.adjustmentCount++;
+            if (this.concurrency > this.peakConcurrency) {
+                this.peakConcurrency = this.concurrency;
+            }
+        }
+    }
+    clamp(value) {
+        return Math.max(this.minConcurrency, Math.min(this.maxConcurrency, value));
+    }
+}

package/build/esm/index.d.ts

@@ -0,0 +1,3 @@
+export { sway } from './sway.js';
+export { AdaptiveController } from './adaptive-controller.js';
+export type { SwayOptions, SwayResult, SwayStats } from './interfaces.js';

package/build/esm/index.js

@@ -0,0 +1,2 @@
+export { sway } from './sway.js';
+export { AdaptiveController } from './adaptive-controller.js';

package/build/esm/interfaces.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Configuration options for {@link sway}.
+ */
+export interface SwayOptions {
+    /** Upper bound for concurrent in-flight tasks (default: `64`) */
+    maxConcurrency?: number;
+    /** Lower bound for concurrent in-flight tasks (default: `1`) */
+    minConcurrency?: number;
+    /** Number of concurrent in-flight tasks to start with (default: `4`) */
+    initialConcurrency?: number;
+    /** EMA smoothing factor, ratio between 0 and 1 — lower values produce calmer adjustments (default: `0.3`) */
+    smoothingFactor?: number;
+    /** Number of completed tasks between probe adjustments (default: `8`) */
+    probeInterval?: number;
+}
+/**
+ * Performance telemetry collected during a {@link sway} run.
+ */
+export interface SwayStats {
+    /** Total number of tasks that were executed */
+    totalTasks: number;
+    /** Wall-clock duration of the entire run in milliseconds */
+    totalDurationMs: number;
+    /** Highest concurrency level reached */
+    peakConcurrency: number;
+    /** Weighted average concurrency level across the run */
+    avgConcurrency: number;
+    /** Number of times the controller changed the concurrency level */
+    adjustments: number;
+}
+/**
+ * Return value of {@link sway}.
+ *
+ * @typeParam T - The resolved type of each task
+ */
+export interface SwayResult<T> {
+    /** Resolved values in the same order as the input tasks */
+    results: T[];
+    /** Performance telemetry for the run */
+    stats: SwayStats;
+}

package/build/esm/interfaces.js

@@ -0,0 +1 @@
+export {};

package/build/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/build/esm/sway.d.ts

@@ -0,0 +1,25 @@
+import { SwayOptions, SwayResult } from './interfaces.js';
+/**
+ * Run async tasks concurrently with adaptive concurrency control.
+ *
+ * Works like `Promise.all()` but automatically tunes the number of in-flight
+ * tasks using a gradient-based controller that maximises throughput.
+ * Rejects on the first error (fail-fast), just like `Promise.all()`.
+ *
+ * @typeParam T - The resolved type of each task
+ * @param tasks - An iterable of zero-argument async functions (thunks)
+ * @param options - Optional tuning parameters for the adaptive controller
+ * @returns Resolved values in input order together with performance stats
+ *
+ * @example
+ * ```ts
+ * import { sway } from '@icazemier/sway';
+ *
+ * const { results, stats } = await sway(
+ *   urls.map(url => () => fetch(url).then(r => r.json())),
+ *   { maxConcurrency: 16 }
+ * );
+ * console.log(stats.peakConcurrency, stats.avgConcurrency);
+ * ```
+ */
+export declare function sway<T>(tasks: Iterable<() => Promise<T>>, options?: SwayOptions): Promise<SwayResult<T>>;

package/build/esm/sway.js

@@ -0,0 +1,81 @@
+import { AdaptiveController } from './adaptive-controller.js';
+/**
+ * Run async tasks concurrently with adaptive concurrency control.
+ *
+ * Works like `Promise.all()` but automatically tunes the number of in-flight
+ * tasks using a gradient-based controller that maximises throughput.
+ * Rejects on the first error (fail-fast), just like `Promise.all()`.
+ *
+ * @typeParam T - The resolved type of each task
+ * @param tasks - An iterable of zero-argument async functions (thunks)
+ * @param options - Optional tuning parameters for the adaptive controller
+ * @returns Resolved values in input order together with performance stats
+ *
+ * @example
+ * ```ts
+ * import { sway } from '@icazemier/sway';
+ *
+ * const { results, stats } = await sway(
+ *   urls.map(url => () => fetch(url).then(r => r.json())),
+ *   { maxConcurrency: 16 }
+ * );
+ * console.log(stats.peakConcurrency, stats.avgConcurrency);
+ * ```
+ */
+export async function sway(tasks, options) {
+    const controller = new AdaptiveController(options);
+    const iterator = tasks[Symbol.iterator]();
+    const results = [];
+    const startTime = performance.now();
+    let nextIndex = 0;
+    let activeTasks = 0;
+    let settled = false;
+    let totalTasks = 0;
+    return new Promise((resolve, reject) => {
+        const tryReject = (error) => {
+            if (!settled) {
+                settled = true;
+                reject(error);
+            }
+        };
+        const scheduleNext = () => {
+            while (!settled && activeTasks < controller.getConcurrency()) {
+                const next = iterator.next();
+                if (next.done) {
+                    if (activeTasks === 0) {
+                        settled = true;
+                        const totalDurationMs = performance.now() - startTime;
+                        resolve({
+                            results,
+                            stats: controller.getStats(totalTasks, totalDurationMs),
+                        });
+                    }
+                    return;
+                }
+                const index = nextIndex++;
+                totalTasks++;
+                activeTasks++;
+                next
+                    .value()
+                    .then((value) => {
+                    if (settled)
+                        return;
+                    results[index] = value;
+                    activeTasks--;
+                    controller.recordCompletion();
+                    scheduleNext();
+                })
+                    .catch(tryReject);
+            }
+        };
+        scheduleNext();
+        if (nextIndex === 0 && activeTasks === 0) {
+            settled = true;
+            const totalDurationMs = performance.now() - startTime;
+            resolve({
+                results,
+                stats: controller.getStats(0, totalDurationMs),
+            });
+        }
+    });
+}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@icazemier/sway",
+  "private": false,
+  "version": "1.0.0-beta.1",
+  "type": "module",
+  "description": "Adaptive concurrent task runner — like Promise.all() with gradient-based concurrency control",
+  "contributors": [
+    {
+      "name": "Ivo Cazemier",
+      "email": "git@warmemelk.nl",
+      "url": "https://github.com/icazemier"
+    }
+  ],
+  "keywords": [
+    "concurrency",
+    "async",
+    "promise",
+    "parallel",
+    "adaptive",
+    "throttle",
+    "task runner"
+  ],
+  "files": [
+    "build/"
+  ],
+  "main": "./build/cjs/index.js",
+  "module": "./build/esm/index.js",
+  "exports": {
+    ".": {
+      "import": "./build/esm/index.js",
+      "require": "./build/cjs/index.js"
+    }
+  },
+  "types": "./build/esm/index.d.ts",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "scripts": {
+    "test": "cross-env NODE_ENV=test vitest run --coverage",
+    "build:esm": "tsc -p tsconfig-build-esm.json",
+    "build:cjs": "tsc -p tsconfig-build-cjs.json",
+    "build": "rimraf build && npm run build:esm && npm run build:cjs && npm run fixup && npm run docs",
+    "docs": "typedoc --out docs src/index.ts",
+    "fixup": "node ./fixup.mjs",
+    "clean:build": "rimraf build",
+    "clean:docs": "rimraf docs",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "prepare": "husky",
+    "release": "semantic-release",
+    "release:dry": "semantic-release --dry-run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/icazemier/sway"
+  },
+  "homepage": "https://github.com/icazemier/sway#readme",
+  "bugs": {
+    "url": "https://github.com/icazemier/sway/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.6.0",
+    "@commitlint/config-conventional": "^19.6.0",
+    "@eslint/js": "^9.26.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^22.15.15",
+    "@vitest/coverage-v8": "^4.0.18",
+    "conventional-changelog-conventionalcommits": "^8.0.0",
+    "cross-env": "^7.0.3",
+    "eslint": "^9.26.0",
+    "eslint-config-prettier": "^10.1.3",
+    "eslint-plugin-prettier": "^5.4.0",
+    "husky": "^9.1.7",
+    "rimraf": "^6.0.1",
+    "semantic-release": "^25.0.3",
+    "typedoc": "^0.28.3",
+    "typescript": "^5.2.2",
+    "typescript-eslint": "^8.31.1",
+    "vitest": "^4.0.18"
+  }
+}