@anishhs/retryq 1.1.0 → 1.2.0

package/README.md

@@ -10,15 +10,18 @@ A production-ready, zero-dependency retry queue manager for Node.js with support
 
 - ✅ **Concurrency control** - Limit concurrent job execution
 - ✅ **Priority queue** - Higher priority jobs execute first
-- ✅ **Exponential backoff** with configurable delay, multiplier, and jitter
+- ✅ **Exponential backoff** with configurable delay, multiplier, `maxDelay`, and jitter
+- ✅ **Lifecycle events & hooks** - `retry`/`success`/`failure`/`cancel`/`idle` events + per-job callbacks
+- ✅ **Conditional retries** - `shouldRetry(error, attempt)` predicate to skip non-retryable errors
 - ✅ **Force cancellation** - Abort in-progress jobs with AbortController
 - ✅ **Cooperative cancellation** - Graceful job termination
+- ✅ **Real time limits** - `maxTime` (and `attemptTimeout`) actively abort in-flight attempts
+- ✅ **Queue draining** - `onIdle()` / `drain()` to await all work
 - ✅ **Memory safe** - Bounded job history with LRU eviction
-- ✅ **Time limits** - Global timeout per job with `maxTime`
 - ✅ **Job introspection** - List, find, and track jobs by ID or label
-- ✅ **TypeScript** - Full type safety with bundled declarations
+- ✅ **TypeScript** - Generic, fully-typed API with bundled declarations
+- ✅ **Dual ESM + CJS** - Ships both module formats with an `exports` map
 - ✅ **Zero dependencies** - Minimal footprint, no external packages
-- ✅ **Production tested** - 50+ tests covering all features
 
 ## Installation
 
@@ -268,6 +271,68 @@ retryQ.clearHistory();
 
 ---
 
+#### onIdle() / drain()
+
+```typescript
+onIdle(): Promise<void>
+drain(): Promise<void>   // alias
+```
+
+Resolves when the queue is fully idle (no pending **and** no running jobs).
+Resolves immediately if already idle.
+
+```typescript
+for (const item of items) {
+  retryQ.createJob(() => process(item), { retries: 3 });
+}
+await retryQ.onIdle(); // wait for the whole batch to settle
+```
+
+---
+
+### Events
+
+`RetryQManager` extends Node's `EventEmitter` and emits typed events:
+
+```typescript
+retryQ.on('retry',   ({ job, info })   => console.log(`retry #${info.attempt} in ${info.nextDelay}ms`));
+retryQ.on('success', ({ job, result }) => console.log('done', job.label));
+retryQ.on('failure', ({ job, error })  => console.error('failed', job.label, error));
+retryQ.on('cancel',  ({ job })         => console.log('cancelled', job.label));
+retryQ.on('idle',    ()                => console.log('queue drained'));
+```
+
+| Event | Payload | Fired when |
+|-------|---------|-----------|
+| `retry` | `{ job, info: RetryInfo }` | A failed attempt schedules another try |
+| `success` | `{ job, result }` | A job completes successfully |
+| `failure` | `{ job, error }` | A job fails terminally |
+| `cancel` | `{ job }` | A job is cancelled |
+| `idle` | _(none)_ | The queue transitions to fully idle |
+
+Prefer per-job feedback? Use the `onRetry` / `onSuccess` / `onFailure` /
+`onCancel` callbacks in `RetryQJobOptions`.
+
+---
+
+### Conditional Retries
+
+Skip retries for errors that will never succeed:
+
+```typescript
+retryQ.createJob(async (signal) => {
+  const res = await fetch(url, { signal });
+  if (!res.ok) throw Object.assign(new Error('HTTP'), { status: res.status });
+  return res.json();
+}, {
+  retries: 5,
+  // Retry 5xx and network errors; give up on 4xx immediately.
+  shouldRetry: (err) => !(err?.status >= 400 && err?.status < 500),
+});
+```
+
+---
+
 ### RetryQJob Interface
 
 ```typescript
@@ -525,15 +590,26 @@ process.on('SIGTERM', async () => {
 ### RetryQJobOptions
 
 ```typescript
-type RetryQJobOptions = {
-  retries?: number;      // Number of retry attempts (default: 3)
-  delay?: number;        // Initial delay in ms (default: 1000)
-  backoff?: number;      // Delay multiplier (default: 2)
-  maxTime?: number;      // Total time limit in ms (default: 30000)
-  jitter?: number;       // Jitter fraction 0-1 (default: 0.1)
-  label?: string;        // Human-readable identifier (default: job ID)
-  priority?: number;     // Execution priority (default: 1)
-  signal?: AbortSignal;  // External abort signal (optional)
+type RetryQJobOptions<T = unknown> = {
+  retries?: number;        // Number of retry attempts (default: 3)
+  delay?: number;          // Initial delay in ms (default: 1000)
+  backoff?: number;        // Delay multiplier (default: 2)
+  maxTime?: number;        // Total time limit in ms (default: 30000)
+  maxDelay?: number;       // Cap for a single backoff delay (default: Infinity)
+  attemptTimeout?: number; // Per-attempt timeout in ms (default: Infinity)
+  jitter?: number;         // Jitter fraction 0-1 (default: 0.1)
+  label?: string;          // Human-readable identifier (default: job ID)
+  priority?: number;       // Execution priority (default: 1)
+  signal?: AbortSignal;    // External abort signal (optional)
+
+  // Conditional retry: return false to stop retrying immediately
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+
+  // Per-job lifecycle callbacks
+  onRetry?: (info: RetryInfo) => void;
+  onSuccess?: (result: T) => void;
+  onFailure?: (error: unknown) => void;
+  onCancel?: () => void;
 };
 ```
 
@@ -544,7 +620,9 @@ type RetryQJobOptions = {
 | `retries` | `3` | Number of retry attempts after initial try |
 | `delay` | `1000` | Initial delay between retries (ms) |
 | `backoff` | `2` | Multiplier for exponential backoff |
-| `maxTime` | `30000` | Total execution time limit (30s) |
+| `maxTime` | `30000` | Total execution time limit (30s), enforced during attempts |
+| `maxDelay` | `Infinity` | Cap for a single backoff delay (ms) |
+| `attemptTimeout` | `Infinity` | Per-attempt timeout (ms) |
 | `jitter` | `0.1` | Random delay variation (±10%) |
 | `priority` | `1` | Queue priority (higher = sooner) |
 | `maxConcurrent` | `Infinity` | Concurrent job limit |
@@ -644,6 +722,19 @@ throw new Error('API request failed');
 
 ## Migration Guide
 
+### From v1.1.x to v1.2.x
+
+**No breaking API changes.** All existing code keeps working; new options,
+callbacks, events, and methods are additive. Two behavior fixes to be aware of:
+
+- `listJobs().cancelled` now holds cancelled jobs — they no longer appear under
+  `failed`.
+- `maxTime` now actively aborts an in-flight attempt once the budget is
+  exhausted (previously it only blocked starting a new attempt).
+
+The package now ships **both ESM and CJS** with an `exports` map; `import` and
+`require` both resolve automatically.
+
 ### From v1.0.x to v1.1.x
 
 **No breaking changes!** All existing code works.
@@ -763,7 +854,7 @@ async (signal) => {
 ## FAQ
 
 **Q: Is this production-ready?**
-A: Yes! Tested with 50+ comprehensive tests. Score: 9.5/10
+A: Yes — covered by a `node:test` suite spanning concurrency, cancellation, events, timeouts, and retry semantics.
 
 **Q: Does it work with TypeScript?**
 A: Yes, full TypeScript support with bundled type definitions.
@@ -788,13 +879,43 @@ More examples available at: [github.com/anishhs-gh/retryq-examples](https://gith
 
 ---
 
+## Development
+
+```bash
+npm install        # install dev dependencies
+npm run typecheck  # tsc --noEmit
+npm run build      # emit dual ESM + CJS into dist/ (with .d.ts)
+npm test           # build (pretest) then run node:test suite
+```
+
+The package builds to both module formats:
+
+- CommonJS → `dist/cjs` (`require`)
+- ES modules → `dist/esm` (`import`)
+
+resolved automatically via the `exports` map in `package.json`.
+
+## CI / Release
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| **Test** | push/PR to `develop`/`master` | Typecheck, build, and test on Node 16/18/20 |
+| **Audit** | push/PR + weekly | `npm audit` of production dependencies |
+| **Dry-run publish** | push to `develop`, PRs | Gated on Test + Audit; verifies the npm token authenticates and has publish permission, and that `npm publish` would succeed — without publishing |
+| **Publish (manual)** | `workflow_dispatch` | Gated on Test + Audit; publishes to npm and creates a GitHub Release + version tag |
+
+Releases are **manual**: bump the version in `package.json`, merge to `master`,
+then run the **Publish** workflow from the Actions tab. Requires an `NPM_TOKEN`
+repository secret with publish access to the `@anishhs` scope.
+
 ## Contributing
 
 Contributions welcome! Please:
 1. Fork the repository
-2. Create a feature branch
-3. Add tests for new features
-4. Submit a pull request
+2. Create a feature branch (off `develop`)
+3. Add tests for new features (`tests/*.test.js`, `node:test`)
+4. Ensure `npm test` passes
+5. Submit a pull request into `develop`
 
 ---
 
@@ -813,7 +934,9 @@ See [CHANGELOG.md](./CHANGELOG.md) for version history.
 ## Support
 
 - **Issues**: [GitHub Issues](https://github.com/anishhs-gh/retryq/issues)
-- **Email**: anishsh701@gmail.com
+- **GitHub**: [anishhs-gh](https://github.com/anishhs-gh)
+- **Website**: [anishhs.com](https://anishhs.com)
+- **LinkedIn**: [linkedin.com/in/anishsh](https://linkedin.com/in/anishsh)
 
 ---
 

package/dist/cjs/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@anishhs/retryq` — a production-ready, zero-dependency retry queue manager.
+ *
+ * @packageDocumentation
+ */
+export { RetryQManager } from "./manager.js";
+export { RetryQTimeoutError } from "./utils.js";
+export type { CancelableFunction, CancelEvent, FailureEvent, JobListSnapshot, JobState, JobSummary, RetryEvent, RetryInfo, RetryQEvents, RetryQJob, RetryQJobOptions, RetryQManagerConfig, SuccessEvent, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,UAAU,EACV,UAAU,EACV,SAAS,EACT,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryQTimeoutError = exports.RetryQManager = void 0;
+/**
+ * `@anishhs/retryq` — a production-ready, zero-dependency retry queue manager.
+ *
+ * @packageDocumentation
+ */
+var manager_js_1 = require("./manager.js");
+Object.defineProperty(exports, "RetryQManager", { enumerable: true, get: function () { return manager_js_1.RetryQManager; } });
+var utils_js_1 = require("./utils.js");
+Object.defineProperty(exports, "RetryQTimeoutError", { enumerable: true, get: function () { return utils_js_1.RetryQTimeoutError; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,2CAA6C;AAApC,2GAAA,aAAa,OAAA;AACtB,uCAAgD;AAAvC,8GAAA,kBAAkB,OAAA"}

package/dist/cjs/manager.d.ts

@@ -0,0 +1,139 @@
+import { EventEmitter } from "node:events";
+import type { JobListSnapshot, JobState, RetryQEvents, RetryQJob, RetryQJobOptions, RetryQManagerConfig } from "./types.js";
+/**
+ * In-memory retry queue manager with concurrency control, priority scheduling,
+ * exponential backoff with jitter, lifecycle events, cooperative/force
+ * cancellation, and bounded job history.
+ *
+ * The manager extends {@link EventEmitter}; subscribe to `retry`, `success`,
+ * `failure`, `cancel`, and `idle` events (see {@link RetryQEvents}).
+ *
+ * @example
+ * ```ts
+ * const q = new RetryQManager({ maxConcurrent: 3 });
+ * q.on("failure", ({ job, error }) => console.error(job.label, error));
+ *
+ * const job = q.createJob(async (signal) => {
+ *   const res = await fetch("https://api.example.com", { signal });
+ *   if (!res.ok) throw new Error(`HTTP ${res.status}`);
+ *   return res.json();
+ * }, { retries: 5, shouldRetry: (e) => !`${e}`.includes("404") });
+ *
+ * await job.promise;
+ * await q.onIdle();
+ * ```
+ */
+export declare class RetryQManager extends EventEmitter {
+    private pendingQueue;
+    private runningJobs;
+    private failedJobs;
+    private completedJobs;
+    private cancelledJobs;
+    private maxConcurrent;
+    private maxHistorySize;
+    private registry;
+    /** Cleanup callbacks (e.g. external-signal listener removal) keyed by job id. */
+    private cleanups;
+    /** Resolvers waiting for the queue to become idle. */
+    private idleWaiters;
+    /** Tracks idle state so the `idle` event only fires on transition. */
+    private wasIdle;
+    /**
+     * @param config - Manager configuration, or a number for `maxConcurrent`
+     *   (legacy form, kept for backwards compatibility).
+     */
+    constructor(config?: RetryQManagerConfig | number);
+    /** Subscribe to a manager event. See {@link RetryQEvents}. */
+    on<E extends keyof RetryQEvents>(event: E, listener: RetryQEvents[E]): this;
+    on(event: string | symbol, listener: (...args: any[]) => void): this;
+    /** Subscribe to a manager event once. See {@link RetryQEvents}. */
+    once<E extends keyof RetryQEvents>(event: E, listener: RetryQEvents[E]): this;
+    once(event: string | symbol, listener: (...args: any[]) => void): this;
+    /** Remove a previously registered listener. See {@link RetryQEvents}. */
+    off<E extends keyof RetryQEvents>(event: E, listener: RetryQEvents[E]): this;
+    off(event: string | symbol, listener: (...args: any[]) => void): this;
+    /** Emit a manager event. See {@link RetryQEvents}. */
+    emit<E extends keyof RetryQEvents>(event: E, ...args: Parameters<RetryQEvents[E]>): boolean;
+    emit(event: string | symbol, ...args: any[]): boolean;
+    /**
+     * Create and immediately enqueue a job.
+     *
+     * @typeParam T - Resolved value produced by `fn`.
+     * @param fn - Async function to run. Receives an {@link AbortSignal} that
+     *   aborts on force-cancellation or attempt/`maxTime` timeout.
+     * @param options - Per-job configuration (see {@link RetryQJobOptions}).
+     * @returns The created {@link RetryQJob}. Await `job.promise` for the result.
+     * @throws {Error} If any option fails validation.
+     */
+    createJob<T>(fn: (signal?: AbortSignal) => Promise<T>, options?: RetryQJobOptions<T>): RetryQJob<T>;
+    /**
+     * Cancel a pending or running job.
+     *
+     * Cooperative (default) cancellation stops future retries and interrupts the
+     * delay between them. Force cancellation additionally aborts the in-flight
+     * attempt via its {@link AbortSignal}.
+     *
+     * @param id - Id of the job to cancel.
+     * @param force - When `true`, abort in-progress execution. Defaults to `false`.
+     */
+    cancelJob(id: string, force?: boolean): void;
+    /**
+     * Returns a promise that resolves when the queue is fully idle — no pending
+     * and no running jobs. Resolves immediately if already idle.
+     *
+     * @returns A promise that resolves on idle.
+     */
+    onIdle(): Promise<void>;
+    /**
+     * Alias for {@link RetryQManager.onIdle}.
+     * @returns A promise that resolves when the queue is idle.
+     */
+    drain(): Promise<void>;
+    /**
+     * Clear retained job history.
+     *
+     * @param state - Optional terminal state to clear (`completed`, `failed`, or
+     *   `cancelled`). When omitted, all history is cleared.
+     */
+    clearHistory(state?: JobState): void;
+    /**
+     * Snapshot of all jobs grouped by state.
+     * @returns A {@link JobListSnapshot}.
+     */
+    listJobs(): JobListSnapshot;
+    /**
+     * Find a job by id across every state.
+     * @param id - Job id.
+     * @returns The job, or `null` if not found.
+     */
+    findJobById(id: string): RetryQJob | null;
+    /**
+     * Find all jobs (across every state) with a matching label.
+     * @param label - Label to match.
+     * @returns Matching jobs.
+     */
+    findJobsByLabel(label: string): RetryQJob[];
+    /** Evict the oldest entry from a history map when it reaches the size cap. */
+    private _evictOldest;
+    /** Sort the pending queue by descending priority (stable: FIFO within a tier). */
+    private _sortQueue;
+    /** Promote pending jobs into running while capacity allows (synchronous). */
+    private _processQueue;
+    private _isIdle;
+    /** Resolve idle waiters and emit `idle` once when the queue drains. */
+    private _checkIdle;
+    /** Run and remove a job's cleanup callback, if any. */
+    private _runCleanup;
+    /**
+     * Execute a single attempt, bounded by `timeoutMs`. A per-attempt
+     * AbortController is linked to the job's controller so force-cancellation
+     * still propagates, while a timeout aborts only this attempt (leaving the job
+     * free to retry). Uses `Promise.race` so the loop advances even if `fn`
+     * ignores the signal.
+     */
+    private _runAttempt;
+    /** Core retry loop for a single job. */
+    private _runJob;
+    private _jobSummary;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/cjs/manager.d.ts.map

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