@glxalokesh/retri 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alokesh Maitra
+
+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,141 @@
+# retri
+![npm](https://img.shields.io/npm/v/retri)
+![license](https://img.shields.io/npm/l/retri)
+![issues](https://img.shields.io/github/issues/GLXALOKESH/retri)
+
+A lightweight, configurable retry utility for async JavaScript. Features built-in support for backoff strategies, jitter, lifecycle hooks, and abort signals.
+
+## Features
+
+- **Configurable retries**: Set max attempts, delay, and custom retry logic.
+- **Backoff strategies**: Built-in support for `fixed`, `linear`, and `exponential` backoff.
+- **Jitter**: Add randomness to delays to prevent thundering herd problems.
+- **Lifecycle Hooks**: Track execution using `onSuccess`, `onFail`, and `onRetry` callbacks.
+- **Abort controller support**: Cancel pending retries seamlessly using an `AbortSignal`.
+- **Custom retry logic**: Determine dynamically whether an error is retryable using `shouldRetry`.
+
+## Installation
+
+```bash
+npm install @glxalokesh/retri
+```
+
+## Usage
+
+### Basic Usage
+
+```javascript
+import { retry } from 'retri';
+
+async function fetchData() {
+    const response = await fetch('https://api.example.com/data');
+    if (!response.ok) throw new Error('Network error');
+    return response.json();
+}
+
+// Retries up to 3 times (4 attempts total) with a fixed delay of 300ms
+const data = await retry(fetchData);
+```
+
+### Advanced Usage with Options
+
+```javascript
+import { retry } from 'retri';
+
+const abortController = new AbortController();
+
+const options = {
+    retries: 5,                  // Number of retry attempts (default: 3)
+    delay: 500,                  // Initial delay in ms (default: 300)
+    backoff: 'exponential',      // Backoff strategy: 'fixed', 'linear', or 'exponential' (default: 'fixed')
+    factor: 2,                   // Multiplier for exponential backoff (default: 2)
+    jitter: 0.2,                 // Jitter fraction (e.g., 0.2 means +/- 20% randomness)
+    signal: abortController.signal, // Pass an AbortSignal to cancel early
+
+    // Only retry on specific errors
+    shouldRetry: (error, ctx) => {
+        if (error.message.includes('Fatal')) return false; // Stop retrying
+        return true;
+    },
+
+    // Lifecycle hooks
+    onRetry: (ctx) => console.log(`Retrying... attempt ${ctx.attempt}. Errors left: ${ctx.retriesLeft}`),
+    onSuccess: (ctx) => console.log(`Success on attempt ${ctx.attempt}! Time elapsed: ${ctx.timeElapsed}ms`),
+    onFail: (ctx) => console.error(`Failed after ${ctx.attempt} attempts.`)
+};
+
+try {
+    const result = await retry(fetchData, options);
+} catch (error) {
+    console.error('Operation failed:', error);
+}
+```
+
+## API Reference
+
+### `retry(fn, options?)`
+
+Executes the async function `fn` and automatically retries it upon failure according to the provided `options`.
+
+#### Arguments
+
+- `fn` *(Function)*: An asynchronous function that returns a Promise.
+- `options` *(Object)*: Configuration options (optional).
+
+#### Options Available
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `retries` | `number` | `3` | Maximum number of **retries** (total attempts will be `retries + 1`). |
+| `delay` | `number` | `300` | Initial delay between attempts, in milliseconds. |
+| `backoff` | `string` | `'fixed'` | Strategy for calculating delay: `'fixed'`, `'linear'`, or `'exponential'`. |
+| `factor` | `number` | `2` | Multiplier used when `backoff` is `'exponential'`. |
+| `jitter` | `number` | `0` | Fraction (`0` to `1`) of jitter to apply to the delay. `0.2` adds ±20% randomness. |
+| `signal` | `AbortSignal` | `null` | Used to abort the retry process entirely. Throws a `DOMException` error. |
+| `shouldRetry` | `Function`| `() => true`| Predicate function `(error, context)` returning a boolean. If `false`, retries are aborted. |
+| `onSuccess` | `Function`| `-` | Hook executed when `fn` completes successfully. |
+| `onRetry`   | `Function`| `-` | Hook executed right before a retry wait period begins. |
+| `onFail`    | `Function`| `-` | Hook executed when all retries are exhausted or `shouldRetry` returns false. |
+
+
+### Context Object (`ctx`)
+
+Lifecycle hooks (`onSuccess`, `onRetry`, `onFail`) and the `shouldRetry` predicate receive a context object with useful properties:
+
+- `ctx.attempt`: The current attempt number (starts at 1).
+- `ctx.retriesLeft`: Number of remaining allowed retries.
+- `ctx.timeElapsed`: Milliseconds elapsed since the primary execution started.
+- `ctx.error`: The most recent error encountered (is `null` in `onSuccess`).
+- `ctx.result`: The returned result (only available in `onSuccess`).
+- `ctx.errors`: An array of all errors encountered so far (available in `onFail`).
+
+### Errors
+
+When exceptions bubble out of the `retry` utility, they might be custom Error classes depending on the reason:
+
+- **`RetriError`**: Thrown when maximum retries are exceeded or if `shouldRetry` returns false. Contains properties `.attempt`, `.errors` (array of all caught errors), and `.lastError`.
+- **`DOMException`**: Standard DOMException with name `"AbortError"` is thrown when the provided `AbortSignal` is aborted.
+## Contributing 
+
+retri is an **open-source project**, and contributions are welcome.
+
+- Found a bug? → Open an issue
+- Have a feature idea? → Start a discussion
+- Want to improve code or docs? → Open a pull request
+
+GitHub Repository:  
+👉 **https://github.com/GLXALOKESH/retri**
+
+The issue tracker is open to everyone — no contribution is too small.
+## Stability & Versioning
+
+retri follows semantic versioning:
+
+- **PATCH**: Bug fixes
+- **MINOR**: New features (may introduce new options)
+- **MAJOR**: Breaking changes (will be clearly documented)
+
+Breaking changes will be avoided where possible and clearly announced.
+## License
+
+MIT

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@glxalokesh/retri",
+  "version": "1.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "A lightweight, configurable retry utility for async JavaScript with backoff, jitter, hooks, and abort support",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "directories": {
+    "doc": "docs",
+    "test": "test"
+  },
+  "scripts": {
+    "test": "vitest",
+    "prepublishOnly": "npm test -- --run"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GLXALOKESH/retri.git"
+  },
+  "keywords": [
+    "retry",
+    "async",
+    "promise",
+    "util"
+  ],
+  "author": "alokesh maitra",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/GLXALOKESH/retri/issues"
+  },
+  "homepage": "https://github.com/GLXALOKESH/retri#readme",
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  }
+}

package/src/backoff.js

@@ -0,0 +1,24 @@
+
+
+async function backoff(type, delay, attempt, factor) {
+
+    attempt = attempt ? attempt : 0;
+    factor = factor ? factor : 2;
+
+    if (type === "fixed") {
+
+        return delay;
+    }
+    else if (type === "linear") {
+
+        return delay * attempt;
+    }
+    else if (type === "exponential") {
+        return delay * factor ^ (attempt - 1);
+    }
+
+
+}
+
+
+export { backoff }

package/src/delay.js

@@ -0,0 +1,16 @@
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            return reject(new DOMException("Aborted", "AbortError"));
+        }
+
+        const timer = setTimeout(resolve, ms);
+
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(new DOMException("Aborted", "AbortError"));
+        }, { once: true });
+    });
+}
+
+export { delay };

package/src/error.js

@@ -0,0 +1,21 @@
+export class RetriError extends Error {
+
+    constructor(message, attempt, errors) {
+        super(message);
+        this.name = 'RetriError';
+        this.attempt = attempt;
+        this.errors = errors;
+        this.lastError = errors[errors.length - 1];
+    }
+}
+
+export class AbortError extends Error {
+
+    constructor(message, attempt, errors) {
+        super(message);
+        this.name = 'AbortError';
+        this.attempt = attempt;
+        this.errors = errors;
+        this.lastError = errors[errors.length - 1];
+    }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { retry } from "./retry.js";
+export { RetriError, AbortError } from "./error.js";

package/src/jitter.js

@@ -0,0 +1,12 @@
+
+
+async function jitter(delay, fraction) {
+    const jitterAmount = delay * fraction;
+    const min = delay - jitterAmount;
+    const max = delay + jitterAmount;
+    const result = Math.random() * (max - min) + min;
+
+    return result;
+}
+
+export { jitter }

package/src/retry.js

@@ -0,0 +1,77 @@
+import { RetriError, AbortError } from "./error.js";
+import { delay } from "./delay.js";
+import { backoff } from "./backoff.js";
+import { jitter } from "./jitter.js";
+import { createContext } from "./retryContext.js";
+
+async function retry(fn, options = {}) {
+    const retries = options.retries ?? 3;
+    const errors = [];
+    const delayms = options.delay ?? 300;
+    const backoffSelection = options.backoff ?? "fixed"
+    let currentDelay = delayms;
+    const factor = options.factor ?? 2;
+    const jitterVal = options.jitter ?? 0;
+    const maxAttempts = retries + 1;
+    let currentDelaywithJitter = currentDelay;
+    const startTime = Date.now();
+    const signal = options?.signal ?? null
+    function runHooks(hook, payload) {
+        try {
+            hook?.(payload);
+        } catch (error) {
+
+        }
+    }
+
+    function throwIfAborted() {
+        if (signal?.aborted) {
+            throw new DOMException("Aborted", "AbortError");
+        }
+    }
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        throwIfAborted();
+        try {
+            const result = await fn();
+            const ctx = createContext({ attempt, retries, startTime, error: null })
+            runHooks(options.onSuccess, { ...ctx, result });
+            return result;
+        } catch (error) {
+            errors.push(error);
+
+            const ctx = createContext({ attempt, retries, startTime, error })
+            const allowretry = options.shouldRetry ? options.shouldRetry(error, ctx) : true;
+            if (allowretry != true || attempt === maxAttempts) {
+                runHooks(options.onFail, { ...ctx, errors });
+                if (attempt === maxAttempts) {
+                    throw new RetriError("Maximum Retries Exceeded", attempt, errors);
+                }
+                throw new RetriError("Error not allowed to retry", attempt, errors);
+            }
+
+            runHooks(options.onRetry, { ...ctx })
+
+            if (jitterVal) {
+                currentDelaywithJitter = await jitter(currentDelay, jitterVal);
+            }
+
+        }
+
+        await delay(currentDelaywithJitter, signal);
+        if (backoffSelection === "fixed") {
+            currentDelay = await backoff(backoffSelection, delayms)
+        }
+        else if (backoffSelection === "linear") {
+            currentDelay = await backoff(backoffSelection, delayms, attempt + 1)
+        }
+        else if (backoffSelection === "exponential") {
+
+            currentDelay = await backoff(backoffSelection, delayms, attempt, factor)
+        }
+        throwIfAborted();
+    }
+
+}
+
+export { retry }

package/src/retryContext.js

@@ -0,0 +1,12 @@
+
+function createContext({ attempt, retries, startTime, error = null }) {
+    return {
+        attempt,
+        retriesLeft: retries - (attempt - 1),
+        timeElapsed: Date.now() - startTime,
+        error
+    }
+
+}
+
+export { createContext }