@anishhs/retryq 1.1.0 → 1.2.0

package/dist/esm/types.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Lifecycle state of a job managed by {@link RetryQManager}.
+ *
+ * ```
+ * pending → running → completed
+ *                  → failed
+ *                  → cancelled
+ * ```
+ */
+export type JobState = "pending" | "running" | "completed" | "failed" | "cancelled";
+/**
+ * Information passed to {@link RetryQJobOptions.onRetry} and emitted with the
+ * manager's `retry` event each time an attempt fails and another is scheduled.
+ */
+export interface RetryInfo {
+    /** 1-based index of the attempt that just failed. */
+    attempt: number;
+    /** The error thrown by the failed attempt. */
+    error: unknown;
+    /** Delay in milliseconds before the next attempt runs (after jitter/caps). */
+    nextDelay: number;
+    /** Number of attempts still remaining after this failure. */
+    retriesLeft: number;
+}
+/**
+ * Per-job configuration accepted by {@link RetryQManager.createJob}.
+ *
+ * @typeParam T - Resolved value produced by the job function.
+ */
+export type RetryQJobOptions<T = unknown> = {
+    /**
+     * Number of retries **after** the initial attempt (total attempts =
+     * `retries + 1`). Must be between `0` and `100`.
+     * @defaultValue 3
+     */
+    retries?: number;
+    /**
+     * Initial delay between attempts, in milliseconds. Must be `>= 0`.
+     * @defaultValue 1000
+     */
+    delay?: number;
+    /**
+     * Multiplier applied to the delay after each failed attempt (exponential
+     * backoff). Must be `>= 1`.
+     * @defaultValue 2
+     */
+    backoff?: number;
+    /**
+     * Total time budget for the job across all attempts, in milliseconds. Now
+     * enforced **during** execution: an in-flight attempt is aborted once the
+     * budget is exhausted. Must be `> 0`.
+     * @defaultValue 30000
+     */
+    maxTime?: number;
+    /**
+     * Upper bound for a single backoff delay, in milliseconds. Prevents the
+     * exponential delay from growing without limit. Must be `>= 0`.
+     * @defaultValue Infinity
+     */
+    maxDelay?: number;
+    /**
+     * Maximum duration of a single attempt, in milliseconds. The attempt is
+     * aborted (and counts as a failure) if it exceeds this. The effective bound
+     * is `min(attemptTimeout, remaining maxTime)`. Must be `> 0` when provided.
+     * @defaultValue Infinity
+     */
+    attemptTimeout?: number;
+    /**
+     * Random variation applied to each delay, as a fraction between `0` and `1`
+     * (e.g. `0.1` = ±10%).
+     * @defaultValue 0.1
+     */
+    jitter?: number;
+    /**
+     * Human-readable identifier used for grouping/lookup via
+     * {@link RetryQManager.findJobsByLabel}. Defaults to the generated job id.
+     */
+    label?: string;
+    /**
+     * Queue priority — higher values are dispatched before lower ones.
+     * @defaultValue 1
+     */
+    priority?: number;
+    /**
+     * External {@link AbortSignal}. Aborting it force-cancels the job.
+     */
+    signal?: AbortSignal;
+    /**
+     * Predicate deciding whether a thrown error should be retried. Return `false`
+     * to stop immediately and mark the job `failed`. When omitted, every error is
+     * retried until attempts are exhausted.
+     *
+     * @param error - The error thrown by the attempt.
+     * @param attempt - 1-based index of the attempt that just failed.
+     */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** Called after each failed attempt that schedules another try. */
+    onRetry?: (info: RetryInfo) => void;
+    /** Called once when the job completes successfully. */
+    onSuccess?: (result: T) => void;
+    /** Called once when the job fails after exhausting retries (or `shouldRetry`). */
+    onFailure?: (error: unknown) => void;
+    /** Called once when the job is cancelled. */
+    onCancel?: () => void;
+};
+/** Configuration for the {@link RetryQManager} itself. */
+export type RetryQManagerConfig = {
+    /**
+     * Maximum number of jobs allowed to run concurrently.
+     * @defaultValue Infinity
+     */
+    maxConcurrent?: number;
+    /**
+     * Maximum number of jobs retained per terminal-state history map
+     * (completed/failed/cancelled) before the oldest are evicted (LRU).
+     * @defaultValue 1000
+     */
+    maxHistorySize?: number;
+};
+/**
+ * A unit of work tracked by {@link RetryQManager}.
+ *
+ * @typeParam T - Resolved value produced by the job function.
+ */
+export interface RetryQJob<T = unknown> {
+    /** Unique identifier generated at creation. */
+    id: string;
+    /** Human-readable label (defaults to {@link RetryQJob.id}). */
+    label: string;
+    /** Current {@link JobState}. */
+    state: JobState;
+    /** Queue priority (higher runs first). */
+    priority: number;
+    /** Remaining attempts (initialised to `retries + 1`). */
+    retriesLeft: number;
+    /** Promise resolving with the job result or rejecting with the last error. */
+    promise: Promise<T>;
+    /**
+     * Cancel this job.
+     * @param force - When `true`, aborts the in-flight attempt via its signal.
+     */
+    cancel: (force?: boolean) => void;
+    /** The async function executed (receives an {@link AbortSignal}). */
+    fn: (signal?: AbortSignal) => Promise<T>;
+    /** Resolved options the job was created with. */
+    options: RetryQJobOptions<T>;
+    /** Creation timestamp (ms since epoch). */
+    createdAt: number;
+    /** Timestamp execution started (ms since epoch), if started. */
+    startedAt?: number;
+    /** Timestamp the job reached a terminal state (ms since epoch), if finished. */
+    finishedAt?: number;
+    /** Last error encountered, if any. */
+    error?: unknown;
+    /** Internal controller used to abort in-flight execution. */
+    abortController?: AbortController;
+}
+/** Compact view of a job returned by {@link RetryQManager.listJobs}. */
+export interface JobSummary {
+    /** Job id. */
+    id: string;
+    /** Job label. */
+    label: string;
+    /** Current state. */
+    state: JobState;
+    /** Remaining attempts. */
+    retriesLeft: number;
+    /** Queue priority. */
+    priority: number;
+}
+/** Snapshot of all jobs grouped by state, returned by {@link RetryQManager.listJobs}. */
+export interface JobListSnapshot {
+    /** Jobs queued and waiting for a slot. */
+    pending: JobSummary[];
+    /** Jobs currently executing. */
+    running: JobSummary[];
+    /** Jobs that exhausted retries (or were rejected by `shouldRetry`). */
+    failed: JobSummary[];
+    /** Jobs that completed successfully. */
+    completed: JobSummary[];
+    /** Jobs that were cancelled. */
+    cancelled: JobSummary[];
+}
+/**
+ * Internal no-op callback augmented with a {@link CancelableFunction.cancelSleep}
+ * hook that interrupts the delay between retries when a job is cancelled.
+ */
+export interface CancelableFunction {
+    (): void;
+    /** Interrupts the in-progress retry delay, if any. */
+    cancelSleep?: () => void;
+}
+/**
+ * Payload emitted with the manager's `retry` event.
+ */
+export interface RetryEvent {
+    /** The job being retried. */
+    job: RetryQJob;
+    /** Details of the failure and the scheduled retry. */
+    info: RetryInfo;
+}
+/** Payload emitted with the manager's `success` event. */
+export interface SuccessEvent {
+    /** The job that completed. */
+    job: RetryQJob;
+    /** The resolved result. */
+    result: unknown;
+}
+/** Payload emitted with the manager's `failure` event. */
+export interface FailureEvent {
+    /** The job that failed. */
+    job: RetryQJob;
+    /** The terminal error. */
+    error: unknown;
+}
+/** Payload emitted with the manager's `cancel` event. */
+export interface CancelEvent {
+    /** The cancelled job. */
+    job: RetryQJob;
+}
+/**
+ * Typed event map for {@link RetryQManager}. Keys are event names; values are
+ * the corresponding listener signatures.
+ */
+export interface RetryQEvents {
+    /** Fired after a failed attempt schedules another try. */
+    retry: (payload: RetryEvent) => void;
+    /** Fired when a job completes successfully. */
+    success: (payload: SuccessEvent) => void;
+    /** Fired when a job fails terminally. */
+    failure: (payload: FailureEvent) => void;
+    /** Fired when a job is cancelled. */
+    cancel: (payload: CancelEvent) => void;
+    /** Fired when the queue transitions to fully idle (no pending/running jobs). */
+    idle: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/esm/utils.d.ts

@@ -0,0 +1,43 @@
+import type { CancelableFunction } from "./types.js";
+/**
+ * Generate a collision-resistant job id.
+ *
+ * Format: `job-{timestamp}-{counter}-{random1}{random2}`. The counter plus two
+ * independent random segments make same-millisecond collisions practically
+ * impossible even under high concurrency.
+ *
+ * @returns A unique job identifier.
+ */
+export declare function randomId(): string;
+/**
+ * Clamp a number into the inclusive range `[min, max]`.
+ *
+ * @param value - Value to clamp.
+ * @param min - Lower bound.
+ * @param max - Upper bound.
+ * @returns The clamped value.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Sleep for `ms` milliseconds. If a {@link CancelableFunction} is supplied, a
+ * `cancelSleep` hook is attached to it so the delay can be interrupted early
+ * (used to abort the wait between retries when a job is cancelled).
+ *
+ * @param ms - Duration to sleep.
+ * @param cancelFn - Optional handle that receives a `cancelSleep` interrupter.
+ * @returns A promise that resolves after `ms`, or rejects if interrupted.
+ */
+export declare function sleep(ms: number, cancelFn?: CancelableFunction): Promise<void>;
+/**
+ * Error thrown when a single attempt exceeds its timeout (either an explicit
+ * {@link RetryQJobOptions.attemptTimeout} or the remaining `maxTime` budget).
+ */
+export declare class RetryQTimeoutError extends Error {
+    /** The timeout, in milliseconds, that was exceeded. */
+    readonly timeoutMs: number;
+    /**
+     * @param timeoutMs - The timeout that was exceeded, in milliseconds.
+     */
+    constructor(timeoutMs: number);
+}
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAKrD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAMjC;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU9E;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;gBACS,SAAS,EAAE,MAAM;CAK9B"}

package/dist/esm/utils.js

@@ -0,0 +1,64 @@
+/** Monotonic counter mixed into ids to harden against same-millisecond collisions. */
+let idCounter = 0;
+/**
+ * Generate a collision-resistant job id.
+ *
+ * Format: `job-{timestamp}-{counter}-{random1}{random2}`. The counter plus two
+ * independent random segments make same-millisecond collisions practically
+ * impossible even under high concurrency.
+ *
+ * @returns A unique job identifier.
+ */
+export function randomId() {
+    const timestamp = Date.now();
+    const counter = (idCounter++ % 10000).toString(36);
+    const random1 = Math.random().toString(36).slice(2, 11);
+    const random2 = Math.random().toString(36).slice(2, 11);
+    return `job-${timestamp}-${counter}-${random1}${random2}`;
+}
+/**
+ * Clamp a number into the inclusive range `[min, max]`.
+ *
+ * @param value - Value to clamp.
+ * @param min - Lower bound.
+ * @param max - Upper bound.
+ * @returns The clamped value.
+ */
+export function clamp(value, min, max) {
+    return Math.max(min, Math.min(value, max));
+}
+/**
+ * Sleep for `ms` milliseconds. If a {@link CancelableFunction} is supplied, a
+ * `cancelSleep` hook is attached to it so the delay can be interrupted early
+ * (used to abort the wait between retries when a job is cancelled).
+ *
+ * @param ms - Duration to sleep.
+ * @param cancelFn - Optional handle that receives a `cancelSleep` interrupter.
+ * @returns A promise that resolves after `ms`, or rejects if interrupted.
+ */
+export function sleep(ms, cancelFn) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(), ms);
+        if (cancelFn) {
+            cancelFn.cancelSleep = () => {
+                clearTimeout(timer);
+                reject(new Error("RetryQ job cancelled"));
+            };
+        }
+    });
+}
+/**
+ * Error thrown when a single attempt exceeds its timeout (either an explicit
+ * {@link RetryQJobOptions.attemptTimeout} or the remaining `maxTime` budget).
+ */
+export class RetryQTimeoutError extends Error {
+    /**
+     * @param timeoutMs - The timeout that was exceeded, in milliseconds.
+     */
+    constructor(timeoutMs) {
+        super(`RetryQ attempt timed out after ${timeoutMs}ms`);
+        this.name = "RetryQTimeoutError";
+        this.timeoutMs = timeoutMs;
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/esm/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,IAAI,SAAS,GAAG,CAAC,CAAC;AAElB;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,CAAC,SAAS,EAAE,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACxD,OAAO,OAAO,SAAS,IAAI,OAAO,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,KAAK,CAAC,KAAa,EAAE,GAAW,EAAE,GAAW;IAC3D,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,QAA6B;IAC7D,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;QAC9C,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,WAAW,GAAG,GAAG,EAAE;gBAC1B,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,MAAM,CAAC,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC,CAAC;YAC5C,CAAC,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAI3C;;OAEG;IACH,YAAY,SAAiB;QAC3B,KAAK,CAAC,kCAAkC,SAAS,IAAI,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF"}

package/dist/esm/validation.d.ts

@@ -0,0 +1,37 @@
+import type { RetryQJobOptions } from "./types.js";
+/** Default values applied to unspecified {@link RetryQJobOptions}. */
+export declare const DEFAULT_OPTIONS: {
+    readonly retries: 3;
+    readonly delay: 1000;
+    readonly backoff: 2;
+    readonly maxTime: 30000;
+    readonly maxDelay: number;
+    readonly attemptTimeout: number;
+    readonly jitter: 0.1;
+    readonly priority: 1;
+};
+/** Hard cap on retries to guard against accidental denial-of-service. */
+export declare const MAX_RETRIES = 100;
+/**
+ * Fully-resolved numeric options used internally by the execution loop. Every
+ * field is guaranteed present after {@link resolveOptions}.
+ */
+export interface ResolvedOptions {
+    retries: number;
+    delay: number;
+    backoff: number;
+    maxTime: number;
+    maxDelay: number;
+    attemptTimeout: number;
+    jitter: number;
+    priority: number;
+}
+/**
+ * Validate and apply defaults to user-supplied job options.
+ *
+ * @param options - Raw options passed to {@link RetryQManager.createJob}.
+ * @returns The resolved numeric options with all defaults applied.
+ * @throws {Error} If any option is outside its allowed range.
+ */
+export declare function resolveOptions(options: RetryQJobOptions<any>): ResolvedOptions;
+//# sourceMappingURL=validation.d.ts.map

package/dist/esm/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,sEAAsE;AACtE,eAAO,MAAM,eAAe;;;;;;;;;CASlB,CAAC;AAEX,yEAAyE;AACzE,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAAG,eAAe,CA6C9E"}

package/dist/esm/validation.js

@@ -0,0 +1,65 @@
+/** Default values applied to unspecified {@link RetryQJobOptions}. */
+export const DEFAULT_OPTIONS = {
+    retries: 3,
+    delay: 1000,
+    backoff: 2,
+    maxTime: 30000,
+    maxDelay: Infinity,
+    attemptTimeout: Infinity,
+    jitter: 0.1,
+    priority: 1,
+};
+/** Hard cap on retries to guard against accidental denial-of-service. */
+export const MAX_RETRIES = 100;
+/**
+ * Validate and apply defaults to user-supplied job options.
+ *
+ * @param options - Raw options passed to {@link RetryQManager.createJob}.
+ * @returns The resolved numeric options with all defaults applied.
+ * @throws {Error} If any option is outside its allowed range.
+ */
+export function resolveOptions(options) {
+    const retries = options.retries ?? DEFAULT_OPTIONS.retries;
+    const delay = options.delay ?? DEFAULT_OPTIONS.delay;
+    const backoff = options.backoff ?? DEFAULT_OPTIONS.backoff;
+    const maxTime = options.maxTime ?? DEFAULT_OPTIONS.maxTime;
+    const maxDelay = options.maxDelay ?? DEFAULT_OPTIONS.maxDelay;
+    const attemptTimeout = options.attemptTimeout ?? DEFAULT_OPTIONS.attemptTimeout;
+    const jitter = options.jitter ?? DEFAULT_OPTIONS.jitter;
+    const priority = options.priority ?? DEFAULT_OPTIONS.priority;
+    if (retries < 0) {
+        throw new Error("retries must be >= 0");
+    }
+    if (retries > MAX_RETRIES) {
+        throw new Error(`retries cannot exceed ${MAX_RETRIES} (DoS protection)`);
+    }
+    if (delay < 0) {
+        throw new Error("delay must be >= 0");
+    }
+    if (backoff < 1) {
+        throw new Error("backoff must be >= 1");
+    }
+    if (maxTime <= 0) {
+        throw new Error("maxTime must be > 0");
+    }
+    if (maxDelay < 0) {
+        throw new Error("maxDelay must be >= 0");
+    }
+    if (attemptTimeout <= 0) {
+        throw new Error("attemptTimeout must be > 0");
+    }
+    if (jitter < 0 || jitter > 1) {
+        throw new Error("jitter must be between 0 and 1");
+    }
+    return {
+        retries,
+        delay,
+        backoff,
+        maxTime,
+        maxDelay,
+        attemptTimeout,
+        jitter,
+        priority,
+    };
+}
+//# sourceMappingURL=validation.js.map

package/dist/esm/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,IAAI;IACX,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,KAAK;IACd,QAAQ,EAAE,QAAQ;IAClB,cAAc,EAAE,QAAQ;IACxB,MAAM,EAAE,GAAG;IACX,QAAQ,EAAE,CAAC;CACH,CAAC;AAEX,yEAAyE;AACzE,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC;AAiB/B;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAA8B;IAC3D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,eAAe,CAAC,OAAO,CAAC;IAC3D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,eAAe,CAAC,KAAK,CAAC;IACrD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,eAAe,CAAC,OAAO,CAAC;IAC3D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,eAAe,CAAC,OAAO,CAAC;IAC3D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAC,QAAQ,CAAC;IAC9D,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,eAAe,CAAC,cAAc,CAAC;IAChF,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,eAAe,CAAC,MAAM,CAAC;IACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAC,QAAQ,CAAC;IAE9D,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,OAAO,GAAG,WAAW,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,yBAAyB,WAAW,mBAAmB,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,OAAO;QACL,OAAO;QACP,KAAK;QACL,OAAO;QACP,OAAO;QACP,QAAQ;QACR,cAAc;QACd,MAAM;QACN,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,21 +1,38 @@
 {
   "name": "@anishhs/retryq",
-  "version": "1.1.0",
-  "description": "Production-ready retry queue with force cancellation, priorities, and exponential backoff",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "version": "1.2.0",
+  "description": "Production-ready retry queue with lifecycle events, force cancellation, priorities, and exponential backoff",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=16"
+  },
   "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && npm run build:cjs && npm run build:esm && node scripts/postbuild.js",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepare": "npm run build",
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "ts-node src/index.ts",
-    "test": "npm run test:verification && npm run test:force-cancel && npm run test:cancellation",
-    "test:verification": "node tests/verification.test.js",
-    "test:force-cancel": "node tests/force-cancellation.test.js",
-    "test:cancellation": "node tests/cancellation-proof.test.js"
+    "pretest": "npm run build",
+    "test": "node --test tests/"
   },
   "keywords": [
     "retryq",
@@ -24,6 +41,7 @@
     "manager",
     "priority",
     "jobs",
+    "events",
     "asynchronous",
     "concurrent",
     "typescript",
@@ -33,7 +51,6 @@
   "license": "ISC",
   "devDependencies": {
     "@types/node": "^24.6.1",
-    "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   }
 }

package/dist/index.d.ts

@@ -1,85 +0,0 @@
-export type RetryQJobOptions = {
-    retries?: number;
-    delay?: number;
-    backoff?: number;
-    maxTime?: number;
-    jitter?: number;
-    label?: string;
-    priority?: number;
-    signal?: AbortSignal;
-};
-export type RetryQManagerConfig = {
-    maxConcurrent?: number;
-    maxHistorySize?: number;
-};
-export type JobState = "pending" | "running" | "completed" | "failed" | "cancelled";
-export interface RetryQJob {
-    id: string;
-    label: string;
-    state: JobState;
-    priority: number;
-    retriesLeft: number;
-    promise: Promise<any>;
-    cancel: (force?: boolean) => void;
-    fn: (signal?: AbortSignal) => Promise<any>;
-    options: RetryQJobOptions;
-    createdAt: number;
-    startedAt?: number;
-    finishedAt?: number;
-    error?: any;
-    abortController?: AbortController;
-}
-export interface CancelableFunction {
-    (): void;
-    cancelSleep?: () => void;
-}
-export declare class RetryQManager {
-    private pendingQueue;
-    private runningJobs;
-    private failedJobs;
-    private completedJobs;
-    private maxConcurrent;
-    private maxHistorySize;
-    private registry;
-    constructor(config?: RetryQManagerConfig | number);
-    private _evictOldest;
-    clearHistory(state?: JobState): void;
-    createJob(fn: (signal?: AbortSignal) => Promise<any>, options?: RetryQJobOptions): RetryQJob;
-    private _sortQueue;
-    private _processQueue;
-    private _runJob;
-    cancelJob(id: string, force?: boolean): void;
-    listJobs(): {
-        pending: {
-            id: string;
-            label: string;
-            state: JobState;
-            retriesLeft: number;
-            priority: number;
-        }[];
-        running: {
-            id: string;
-            label: string;
-            state: JobState;
-            retriesLeft: number;
-            priority: number;
-        }[];
-        failed: {
-            id: string;
-            label: string;
-            state: JobState;
-            retriesLeft: number;
-            priority: number;
-        }[];
-        completed: {
-            id: string;
-            label: string;
-            state: JobState;
-            retriesLeft: number;
-            priority: number;
-        }[];
-    };
-    findJobById(id: string): RetryQJob | null;
-    findJobsByLabel(label: string): RetryQJob[];
-    private _jobSummary;
-}