fyflow-scheduler 0.1.0

package/dist/types/core/workerManager.d.ts

@@ -0,0 +1,141 @@
+import { ThreadWrapper } from "./threadWrapper.js";
+import { InlineWrapper } from "./inlineWrapper.js";
+import { WorkerStatus } from "./workerInterface.js";
+type WorkerInstance = ThreadWrapper | InlineWrapper;
+export interface WorkerManagerOptions {
+    /**
+     * Maximum worker instances in this pool. Default 2.
+     *
+     * Despite the name this is a count of worker *instances*, not OS threads.
+     * With `inline: false` each instance is a real worker thread. With
+     * `inline: true` they all live in the main process, and the name is a
+     * misnomer - see {@link WorkerManagerOptions.inline}.
+     */
+    maxThreads?: number;
+    /**
+     * Tasks each worker instance may run at once. Default 1. Total pool capacity
+     * is `maxThreads x maxConcurrentTasks` for both pool types. Raise this for
+     * async/IO workers; leave it at 1 for CPU-bound ones.
+     */
+    maxConcurrentTasks?: number;
+    /** Ms an idle worker is kept before termination. Default 5000. `0` never terminates. */
+    idleTimeout?: number;
+    /**
+     * Run workers in the main process instead of worker threads. Default false.
+     * Inline suits async/IO work; threaded suits CPU-bound work, since an inline
+     * worker shares the event loop and a synchronous task blocks the scheduler.
+     *
+     * For an inline pool, `maxThreads` creates that many instances of your worker
+     * class in the same process - no threads are involved. Concurrency comes from
+     * overlapping `await`s, so only the PRODUCT matters for throughput:
+     * `maxThreads: 4, maxConcurrentTasks: 5` and
+     * `maxThreads: 1, maxConcurrentTasks: 20` both cap at 20 in-flight tasks and
+     * measure the same.
+     *
+     * What the split does change is state isolation: each instance is constructed
+     * separately, so 4 instances means 4 connection pools, caches or whatever
+     * per-instance state your worker holds, while 1 instance funnels all 20
+     * concurrent tasks through one object.
+     */
+    inline?: boolean;
+    /** Passed as the first constructor argument to every worker instance in this pool. */
+    config?: any;
+    /** Resource group ids every task in this pool must acquire before running. */
+    groups?: string[];
+    /** Requeue a worker's in-flight tasks when it fails, rather than failing them. Default true. */
+    requeueFailedTasks?: boolean;
+    /** Restarts allowed before the pool gives up and emits `worker.restart_limit_exceeded`. Default 3. */
+    maxWorkerRestarts?: number;
+}
+/**
+ * A pool of workers of one type, created from a single worker script.
+ *
+ * ```typescript
+ * const pool = new WorkerManager(workerUrl, {
+ *   maxThreads: 4,
+ *   maxConcurrentTasks: 1,
+ *   groups: ['cpu']
+ * });
+ * ```
+ *
+ * Emits: `task.started`, `task.completed`, `task.failed`, `task.progress`,
+ * `task.spawn_request`, `task.requeue_required`, `worker.failed`,
+ * `worker.self_terminated`, `worker.restart_limit_exceeded`, and the worker
+ * lifecycle events `worker.initialization.started|completed|failed`,
+ * `worker.setup.started|completed` and
+ * `worker.teardown.started|completed|failed`.
+ *
+ * Lifecycle events carry `{ workerId, workerType, timestamp }` plus `duration`
+ * on `*.completed` and `error` on `*.failed`. They fire on every worker
+ * creation and idle-timeout teardown, so keep their listeners cheap.
+ *
+ * Workers are created lazily on first use, up to `maxThreads`.
+ */
+export declare class WorkerManager extends EventTarget {
+    threads: WorkerInstance[];
+    maxThreads: number;
+    maxConcurrentTasks: number;
+    scriptUrl: string;
+    idleTimeout: number;
+    inline: boolean;
+    config: any;
+    groups: string[];
+    requeueFailedTasks: boolean;
+    maxWorkerRestarts: number;
+    private poolRestartCount;
+    private shuttingDown;
+    private allListeners;
+    private initializingThreads;
+    private idleCheckTimer;
+    private readonly IDLE_CHECK_INTERVAL;
+    constructor(scriptUrl: string, options?: WorkerManagerOptions);
+    enqueueNoQueue(taskId: string, payload: any): Promise<any>;
+    private _createPredictiveThread;
+    addEventListener(event: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    private _addInternalListener;
+    private _trackListener;
+    private _removeAllListeners;
+    private _setupWorkerEventListeners;
+    private _handleWorkerTerminationRequest;
+    private _setupWorkerFailureHandling;
+    private _handleWorkerFailure;
+    private _markWorkerAsFailed;
+    private _releaseWorkerGroupResources;
+    private _removeAndReplaceWorker;
+    /** Ids of the workers that currently exist in this pool (created lazily). */
+    getWorkerIds(): string[];
+    /**
+     * Health and activity of one worker, or `null` if no such worker exists.
+     * Useful for building supervision on top of `worker.failed`.
+     */
+    getWorkerStatus(workerId: string): WorkerStatus | null;
+    /** `getWorkerStatus` for every live worker, keyed by worker id. */
+    getAllWorkerStatuses(): Map<string, WorkerStatus>;
+    /**
+     * Terminate a worker and create a replacement, optionally merging `newConfig`
+     * over the pool's `config`. The replacement gets a new id.
+     *
+     * @returns false if no worker with that id exists.
+     */
+    restartWorker(workerId: string, newConfig?: any): Promise<boolean>;
+    /** Alias for {@link WorkerManager.restartWorker}. */
+    replaceWorker(workerId: string, newConfig?: any): Promise<boolean>;
+    /**
+     * Merge `config` into a live worker's config object.
+     *
+     * Note this mutates the config a worker instance already holds - a worker that
+     * copied values in its constructor will not see the change. Use
+     * {@link WorkerManager.restartWorker} when the worker must be rebuilt.
+     *
+     * @returns false if no worker with that id exists.
+     */
+    updateWorkerConfig(workerId: string, config: any): Promise<boolean>;
+    private startIdleTimer;
+    private stopIdleTimer;
+    private checkIdleWorkers;
+    private _removeIdleWorker;
+    /** Terminate every worker in the pool and drop its listeners. */
+    shutdown(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=workerManager.d.ts.map

package/dist/types/core/workerManager.d.ts.map

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

package/dist/types/core/workerWrapper.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workerWrapper.d.ts.map

package/dist/types/core/workerWrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerWrapper.d.ts","sourceRoot":"","sources":["../../../core/workerWrapper.ts"],"names":[],"mappings":""}

package/dist/types/core/workerWrapperUrl.bundled.d.ts

@@ -0,0 +1,2 @@
+export default function getWorkerUrl(): Promise<string>;
+//# sourceMappingURL=workerWrapperUrl.bundled.d.ts.map

package/dist/types/core/workerWrapperUrl.bundled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerWrapperUrl.bundled.d.ts","sourceRoot":"","sources":["../../../core/workerWrapperUrl.bundled.ts"],"names":[],"mappings":"AAcA,wBAA8B,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAM5D"}

package/dist/types/core/workerWrapperUrl.d.ts

@@ -0,0 +1,2 @@
+export default function getWorkerUrl(): Promise<string>;
+//# sourceMappingURL=workerWrapperUrl.d.ts.map

package/dist/types/core/workerWrapperUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerWrapperUrl.d.ts","sourceRoot":"","sources":["../../../core/workerWrapperUrl.ts"],"names":[],"mappings":"AACA,wBAA8B,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAE5D"}

package/dist/types/groups/concurrentLimitGroup.d.ts

@@ -0,0 +1,33 @@
+import type { ResourceGroup, ResourceGroupMetrics, ResourceGroupStats } from './resourceGroup.ts';
+/**
+ * ConcurrentLimitGroup - Optimistic resource limits with soft concurrency control
+ *
+ * Uses optimistic allocation: checks capacity at dispatch, acquires at execution.
+ * May temporarily exceed limit by up to maxThreads × maxConcurrentTasks due to race conditions.
+ *
+ * Best for:
+ * - CPU scheduling (soft limit, temporary overshoot acceptable)
+ * - Throughput limiting (approximate rate control)
+ * - Load balancing (advisory limits)
+ *
+ * Note: May temporarily exceed limit by up to maxThreads × maxConcurrentTasks due to race conditions.
+ *
+ * Example:
+ * ```typescript
+ * const cpuLimit = new ConcurrentLimitGroup(8, 'cpu'); // ~8 concurrent, may briefly exceed
+ * ```
+ */
+export declare class ConcurrentLimitGroup extends EventTarget implements ResourceGroup {
+    readonly id: string;
+    readonly type: "concurrent";
+    limit: number;
+    running: number;
+    private stats;
+    constructor(limit: number, id?: string);
+    canRun(): boolean;
+    getMetrics(): ResourceGroupMetrics;
+    getStats(): ResourceGroupStats;
+    onStart(): void;
+    onFinish(): void;
+}
+//# sourceMappingURL=concurrentLimitGroup.d.ts.map

package/dist/types/groups/concurrentLimitGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrentLimitGroup.d.ts","sourceRoot":"","sources":["../../../groups/concurrentLimitGroup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAElG;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,oBAAqB,SAAQ,WAAY,YAAW,aAAa;IAC1E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,SAAK;IACZ,OAAO,CAAC,KAAK,CAGX;gBAEU,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM;IAMtC,MAAM,IAAI,OAAO;IAIjB,UAAU,IAAI,oBAAoB;IASlC,QAAQ,IAAI,kBAAkB;IAO9B,OAAO;IAeP,QAAQ;CAkBT"}

package/dist/types/groups/keyedRateLimitGroup.d.ts

@@ -0,0 +1,98 @@
+import type { ResourceGroup, ResourceGroupMetrics, ResourceGroupStats } from './resourceGroup.ts';
+import type { RateWindow } from './rateLimitGroup.ts';
+/** Shape the group needs from a task in order to derive its key. */
+export interface KeyedTaskLike {
+    id?: string;
+    limitKey?: string;
+    payload?: any;
+}
+export interface KeyedRateLimitGroupOptions {
+    /** Stable id used in `workerGroups` / pool `groups`. Generated if omitted. */
+    id?: string;
+    /**
+     * Which bucket a task belongs to. Defaults to `task.limitKey`, so tasks can
+     * carry the key directly instead of the group deriving it:
+     *
+     * ```typescript
+     * new KeyedRateLimitGroup(windows, { id: 'api', keyFrom: t => t.payload.endpoint })
+     * ```
+     *
+     * Returning undefined or an empty string makes `addTask` throw.
+     */
+    keyFrom?: (task: KeyedTaskLike) => string | undefined;
+    /**
+     * How long a key with no running tasks is kept after its last activity.
+     * Defaults to twice the largest window, which is the point past which the key
+     * can no longer affect any limit. Without eviction, high-cardinality keys grow
+     * without bound.
+     */
+    idleKeyTtlMs?: number;
+}
+/**
+ * Rate limiting applied independently per key, for when different endpoints,
+ * tenants or accounts each have their own quota.
+ *
+ * ```typescript
+ * const api = new KeyedRateLimitGroup(
+ *   [{ limit: 10, windowMs: 1000 }],          // 10/sec PER KEY, not in total
+ *   { id: 'api', keyFrom: t => t.payload.endpoint }
+ * );
+ *
+ * const pool = new WorkerManager(url, { groups: ['api'], inline: true });
+ * new FyflowScheduler({ ApiWorker: pool }, { api });
+ * ```
+ *
+ * Every window must have room in that key's bucket before a task runs. Tasks
+ * over the limit wait in a per-key blocked queue, so a saturated key never
+ * delays tasks belonging to another key.
+ *
+ * Like the other groups this is optimistic: a key's limit can be briefly
+ * exceeded by up to `maxThreads x maxConcurrentTasks` under race conditions.
+ */
+export declare class KeyedRateLimitGroup extends EventTarget implements ResourceGroup {
+    readonly id: string;
+    readonly type: "keyed-rate-limit";
+    readonly keyed = true;
+    private windows;
+    private keyFrom;
+    private idleKeyTtlMs;
+    private keys;
+    private stats;
+    constructor(windows: RateWindow[], options?: KeyedRateLimitGroupOptions);
+    /** Bucket this task belongs to. The scheduler throws if this returns nothing. */
+    keyFor(task: unknown): string | undefined;
+    /**
+     * Whether one more task may start.
+     *
+     * With a key, checks that key's bucket. Without one - which is how the
+     * scheduler pre-filters before walking blocked queues - reports whether any
+     * known key has capacity, treating an unknown key as free.
+     */
+    canRun(key?: string): boolean;
+    onStart(key?: string): void;
+    onFinish(key?: string): void;
+    /**
+     * Aggregate view across keys. `limit` is the per-key limit of the most
+     * restrictive window, `running` is summed over every key. Use
+     * {@link KeyedRateLimitGroup.getKeyMetrics} for one bucket.
+     */
+    getMetrics(): ResourceGroupMetrics & {
+        activeKeys: number;
+    };
+    /** Per-bucket view. Returns zeroes for a key that has not been used. */
+    getKeyMetrics(key: string): ResourceGroupMetrics;
+    /** Keys currently holding state, busiest first. */
+    getActiveKeys(): string[];
+    getStats(): ResourceGroupStats;
+    private _tightestLimit;
+    private _stateFor;
+    private _keyCanRun;
+    /**
+     * Drop keys that hold no running tasks and have been quiet longer than
+     * `idleKeyTtlMs`. Their windows can no longer constrain anything, so the state
+     * is pure memory. Swept lazily rather than on a timer, so an idle group costs
+     * nothing.
+     */
+    private _evictIdleKeys;
+}
+//# sourceMappingURL=keyedRateLimitGroup.d.ts.map

package/dist/types/groups/keyedRateLimitGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyedRateLimitGroup.d.ts","sourceRoot":"","sources":["../../../groups/keyedRateLimitGroup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAClG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED,MAAM,WAAW,0BAA0B;IACzC,8EAA8E;IAC9E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAWD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,mBAAoB,SAAQ,WAAY,YAAW,aAAa;IAC3E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAU;IAC5C,QAAQ,CAAC,KAAK,QAAQ;IAEtB,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,IAAI,CAA+B;IAC3C,OAAO,CAAC,KAAK,CAGX;gBAEU,OAAO,EAAE,UAAU,EAAE,EAAE,OAAO,GAAE,0BAA+B;IAU3E,iFAAiF;IACjF,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAKzC;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO;IAc7B,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAgB3B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAqB5B;;;;OAIG;IACH,UAAU,IAAI,oBAAoB,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE;IAiB3D,wEAAwE;IACxE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB;IAahD,mDAAmD;IACnD,aAAa,IAAI,MAAM,EAAE;IAOzB,QAAQ,IAAI,kBAAkB;IAO9B,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,SAAS;IAcjB,OAAO,CAAC,UAAU;IAsBlB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;CAUvB"}

package/dist/types/groups/rateLimitGroup.d.ts

@@ -0,0 +1,79 @@
+import type { ResourceGroup, ResourceGroupMetrics, ResourceGroupStats } from './resourceGroup.ts';
+/** Per-window view returned by {@link RateLimitGroup.getStatus}. */
+export interface RateWindowStatus {
+    limit: number;
+    windowMs: number;
+    current: number;
+    completed: number;
+    running: number;
+    remaining: number;
+    resetTime: number;
+}
+/** Snapshot returned by {@link RateLimitGroup.getStatus}. */
+export interface RateLimitStatus {
+    running: number;
+    windows: RateWindowStatus[];
+    canAcceptNew: boolean;
+}
+export interface RateWindow {
+    limit: number;
+    windowMs: number;
+}
+/**
+ * Time-window throttling, for API quotas and similar limits.
+ *
+ * ```typescript
+ * const api = new RateLimitGroup([
+ *   { limit: 10,  windowMs: 1000 },   // 10 per second
+ *   { limit: 100, windowMs: 60_000 }  // and 100 per minute
+ * ], 'api');
+ * ```
+ *
+ * Every window must have room before a task runs. Tasks over the limit wait in
+ * the scheduler's blocked queue and are retried once a window rolls over - they
+ * are never dropped.
+ */
+export declare class RateLimitGroup extends EventTarget implements ResourceGroup {
+    readonly id: string;
+    readonly type: "rate-limit";
+    private windows;
+    private requestCounts;
+    private runningStartTimes;
+    private running;
+    private stats;
+    constructor(windows: RateWindow[], id?: string);
+    /**
+     * Check if a new request can be accepted based on all rate limit windows
+     */
+    canRun(): boolean;
+    getMetrics(): ResourceGroupMetrics;
+    getStats(): ResourceGroupStats;
+    /**
+     * Called when a task starts - tracks running count and reserves slot in rate limit
+     */
+    onStart(): void;
+    /**
+     * Called when a task finishes - records completion in rate limit windows and removes from running
+     */
+    onFinish(): void;
+    /**
+     * Get current status for monitoring
+     */
+    getStatus(): RateLimitStatus;
+    /**
+     * Clear all rate limit history (useful for testing or reset)
+     */
+    reset(): void;
+    /**
+     * Helper to create common rate limit configurations
+     */
+    static createWindows(configs: Array<{
+        limit: number;
+        seconds: number;
+    }>): RateWindow[];
+}
+export declare function createRateLimitGroup(configs: Array<{
+    limit: number;
+    seconds: number;
+}>): RateLimitGroup;
+//# sourceMappingURL=rateLimitGroup.d.ts.map

package/dist/types/groups/rateLimitGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimitGroup.d.ts","sourceRoot":"","sources":["../../../groups/rateLimitGroup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAElG,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,SAAQ,WAAY,YAAW,aAAa;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IACtC,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,iBAAiB,CAAgB;IACzC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,KAAK,CAGX;gBAEU,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM;IAU9C;;OAEG;IACH,MAAM,IAAI,OAAO;IA6BjB,UAAU,IAAI,oBAAoB;IAYlC,QAAQ,IAAI,kBAAkB;IAO9B;;OAEG;IACH,OAAO,IAAI,IAAI;IAOf;;OAEG;IACH,QAAQ,IAAI,IAAI;IAkBhB;;OAEG;IACH,SAAS,IAAI,eAAe;IAkC5B;;OAEG;IACH,KAAK,IAAI,IAAI;IASb;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC,GAAG,UAAU,EAAE;CAMrF;AAGD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC,GAAG,cAAc,CAErG"}

package/dist/types/groups/resourceGroup.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Resource Group Interfaces
+ *
+ * Unified interfaces for all resource group types (ConcurrentLimitGroup, RateLimitGroup)
+ */
+export interface ResourceGroupMetrics {
+    limit: number;
+    running: number;
+    available: number;
+    utilization: number;
+}
+export interface ResourceGroupStats {
+    totalAcquired: number;
+    totalReleased: number;
+}
+export interface ResourceGroup extends EventTarget {
+    readonly id: string;
+    readonly type: 'concurrent' | 'rate-limit' | 'keyed-rate-limit';
+    /**
+     * True when this group limits per key rather than globally. The scheduler
+     * resolves a key with {@link ResourceGroup.keyFor} and passes it to
+     * `canRun`/`onStart`/`onFinish`, and queues blocked tasks per key so a
+     * saturated key cannot stall the others.
+     */
+    readonly keyed?: boolean;
+    /**
+     * Key this task belongs to, for keyed groups. Returning undefined or an empty
+     * string makes `addTask` throw - a task with no key would otherwise silently
+     * bypass or share a bucket.
+     */
+    keyFor?(task: unknown): string | undefined;
+    /**
+     * Capacity check (synchronous). `key` is supplied only for keyed groups; a
+     * keyed group called without one reports whether ANY key has capacity, which
+     * the scheduler uses as a cheap pre-filter.
+     */
+    canRun(key?: string): boolean;
+    getMetrics(): ResourceGroupMetrics;
+    getStats?(): ResourceGroupStats;
+}
+//# sourceMappingURL=resourceGroup.d.ts.map

package/dist/types/groups/resourceGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceGroup.d.ts","sourceRoot":"","sources":["../../../groups/resourceGroup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,GAAG,kBAAkB,CAAC;IAEhE;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;OAIG;IACH,MAAM,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAE3C;;;;OAIG;IACH,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAG9B,UAAU,IAAI,oBAAoB,CAAC;IAGnC,QAAQ,CAAC,IAAI,kBAAkB,CAAC;CAKjC"}

package/dist/types/index.d.ts

@@ -0,0 +1,15 @@
+export { FyflowScheduler, FyflowTask } from "./core/FyflowScheduler.js";
+export type { FyflowSchedulerOptions, AddTaskOptions } from "./core/FyflowScheduler.js";
+export { ConcurrentLimitGroup } from "./groups/concurrentLimitGroup.js";
+export { RateLimitGroup } from "./groups/rateLimitGroup.js";
+export type { RateWindow } from "./groups/rateLimitGroup.js";
+export { KeyedRateLimitGroup } from "./groups/keyedRateLimitGroup.js";
+export type { KeyedRateLimitGroupOptions, KeyedTaskLike } from "./groups/keyedRateLimitGroup.js";
+export type { ResourceGroup, ResourceGroupMetrics, ResourceGroupStats } from "./groups/resourceGroup.js";
+export { WorkerManager } from "./core/workerManager.js";
+export { ThreadWrapper } from "./core/threadWrapper.js";
+export { InlineWrapper } from "./core/inlineWrapper.js";
+export type { WorkerManagerOptions } from "./core/workerManager.js";
+export type { WorkerInterface, WorkerConfig, BaseWorkerContext, TaskWorkerContext, WorkerContext, SpawnTaskConfig, ProgressData, WorkerStatus, WorkerInstanceState } from "./core/workerInterface.js";
+export { BaseWorker, WorkerTerminationError } from "./core/workerInterface.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACxE,YAAY,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAMxF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,YAAY,EAAE,0BAA0B,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACjG,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAGzG,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAGxD,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,YAAY,EACV,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC"}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "fyflow-scheduler",
+  "version": "0.1.0",
+  "description": "Parallel task scheduler with resource management, worker pools, and cross-platform support",
+  "main": "./dist/node/index.js",
+  "browser": "./dist/browser/index.js",
+  "types": "./dist/types/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "node esbuild.config.js",
+    "build:dev": "node esbuild.config.js --dev",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build:dev && node dev-dist/node/tests/runner.js",
+    "test:core": "npm run build:dev && node dev-dist/node/tests/runner.js core",
+    "test:error": "npm run build:dev && node dev-dist/node/tests/runner.js error",
+    "test:spawning": "npm run build:dev && node dev-dist/node/tests/runner.js spawning",
+    "test:settlement": "npm run build:dev && node dev-dist/node/tests/runner.js settlement",
+    "test:docs": "npm run build:dev && node dev-dist/node/tests/runner.js docs",
+    "test:performance": "npm run build:dev && node dev-dist/node/tests/runner.js performance",
+    "test:deno": "deno task test",
+    "test:deno:core": "deno task test:core",
+    "test:deno:error": "deno task test:error",
+    "test:deno:spawning": "deno task test:spawning",
+    "test:browser": "npm run build:dev && npx playwright test",
+    "test:browser:headed": "npm run build:dev && npx playwright test --headed",
+    "test:browser:debug": "npm run build:dev && npx playwright test --debug",
+    "test:browser:chromium": "npm run build:dev && npx playwright test --project=chromium",
+    "test:browser:firefox": "npm run build:dev && npx playwright test --project=firefox",
+    "test:browser:webkit": "npm run build:dev && npx playwright test --project=webkit",
+    "test:all": "npm run test && npm run test:browser",
+    "serve:test": "npx http-server . -p 3000 -c-1 --cors",
+    "benchmark": "npm run build:dev && node dev-dist/node/benchmark/runBenchmarks.js",
+    "benchmark:quick": "npm run build:dev && node dev-dist/node/benchmark/runBenchmarks.js --quick",
+    "benchmark:baseline": "npm run build:dev && node dev-dist/node/benchmark/runBenchmarks.js --categories baseline",
+    "benchmark:variance": "npm run build:dev && node dev-dist/node/benchmark/runBenchmarks.js --quick --runs 3",
+    "benchmark:startup": "npm run build:dev && node dev-dist/node/benchmark/runBenchmarks.js --categories startup",
+    "benchmark:contention": "npm run build:dev && node dev-dist/node/benchmark/runBenchmarks.js --categories contention",
+    "benchmark:overlapping": "npm run build:dev && node dev-dist/node/benchmark/runBenchmarks.js --categories overlapping",
+    "benchmark:help": "npm run build:dev && node dev-dist/node/benchmark/runBenchmarks.js --help"
+  },
+  "keywords": ["scheduler", "task", "worker", "async", "concurrency", "workflow", "parallel", "typescript"],
+  "author": "FyFlow Team",
+  "license": "MIT",
+  "homepage": "https://github.com/fyflow/fyflow-scheduler#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fyflow/fyflow-scheduler.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fyflow/fyflow-scheduler/issues"
+  },
+  "exports": {
+    ".": {
+      "node": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/node/index.js"
+      },
+      "browser": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/browser/index.js"
+      },
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/node/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "packageManager": "pnpm@10.12.1",
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.55.1",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.25.10",
+    "http-server": "^14.1.1",
+    "typescript": "^5.9.2"
+  }
+}