@wowistudio/grit 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeroen Huisman
+
+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,147 @@
+# Grit
+
+> ⚠️ **Work in Progress**: This library is currently under active development. The API may change and some features may be incomplete.
+
+A fluent API for configurable retries with error filtering and backoff strategies (fixed, exponential, random jitter)
+
+## Installation
+
+```bash
+# Using npm
+npm install @wowistudio/grit
+# Using pnpm
+pnpm add @wowistudio/grit
+# Using yarn
+yarn add @wowistudio/grit
+```
+
+## Usage Examples
+
+### Retry
+
+Retry an operation a specified numbers of times. The total attempts will be 1 + n retries.
+
+```typescript
+import { Grit } from '@wowistudio/grit';
+
+class ValidationError extends Error {}
+class NetworkError extends Error {}
+class TimeoutError extends Error {}
+
+// Basic
+const result = await Grit.retry(3)
+  .attempt(fetchData);
+
+console.log(result)
+
+// Basic with access to attempt count
+await Grit.retry(3)
+  .attempt((attemptCount) => {
+    console.log('Attempt:', attemptCount)
+    return apiCall()
+  })
+
+// Retry only specific errors
+await Grit.retry(5)
+  .onlyErrors([NetworkError, TimeoutError])
+  .attempt(() => makeNetworkRequest);
+
+// Do not retry specific errors
+await Grit.retry(3)
+  .skipErrors([ValidationError])
+  .attempt(apiCall);
+```
+
+### Delay
+
+```typescript
+import { Grit } from '@wowistudio/grit';
+
+// Delay with fixed intervals (in ms)
+await Grit.retry(3)
+  .withDelay(1000)
+  .attempt(apiCall);
+
+// Delay with exponential backoff
+// This setup generates delay: [2000, 4000, 8000]
+await Grit.retry(3)
+  .withDelay({ 
+    delay: 2000, 
+    factor: 2
+  })
+  .attempt(apiCall);
+
+// Delay with randomness
+await Grit.retry(4)
+  .withDelay({
+    minDelay: 3000, 
+    maxDelay: 4000,
+  })
+  .attempt(apiCall);
+
+// Delay with exact delays for each retry
+await Grit.retry(3)
+  .withDelay([500, 1000, 1500])
+  .attempt(apiCall);
+```
+
+### Timeout
+
+> ⚠️ **Note**: JavaScript timeouts don't actually stop the execution of the underlying operation. The timeout will reject/throw an error after the specified duration, but the original operation may continue running in the background.
+
+```typescript
+import { Grit } from '@wowistudio/grit';
+
+// Operation timeout after specified amount of time
+await Grit.retry(3)
+  .withTimeout(5000)
+  .attempt(apiCall);
+```
+
+### Fallback
+
+```typescript
+import { Grit } from '@wowistudio/grit';
+
+const fastCacheLookup = async () => {}
+const slowerDbFetch = async () => {}
+
+// Attempt with fallback
+await Grit.retry(0)
+  .withTimeout(100)
+  .fallback(slowerDbFetch)
+  .attempt(fastCacheLookup)
+
+// Attempt return type is typesafe and will be a union of return type .fallback & .attempt
+const result: number | string = await Grit.retry(0)
+  .withTimeout(100)
+  .fallback(() => 1)
+  .attempt(() => 'a')
+```
+
+
+## Reusable Builder Instances
+
+You can define a builder instance once and reuse it. Each call to `.attempt()` creates a new execution context, so retry state is independent between calls:
+
+```typescript
+import { Grit } from '@wowistudio/grit';
+
+// Define a shared builder configuration
+const grit = Grit.retry(3)
+  .withDelay(2000)
+  .withTimeout(5000)
+  .onlyErrors([NetworkError])
+  .beforeRetry((retryCount) => {
+    console.log(`Retrying (attempt ${retryCount})...`);
+  });
+
+// Use the same builder for multiple different operations
+const userData = await grit.attempt(fetchUserData);
+const orderData = await grit.attempt(fetchOrderData);
+```
+
+## License
+
+This project is licensed under the MIT License.
+

package/dist/builder.d.ts

@@ -0,0 +1,24 @@
+import { GritError } from "./exceptions.js";
+import type { DelayConfig, FunctionToExecute, TimeoutConfig } from "./types.js";
+declare class GritBuilder<FallbackType = never> {
+    #private;
+    private retryCount?;
+    _onlyErrors: (typeof GritError)[];
+    _skipErrors: (typeof GritError)[];
+    fn: FunctionToExecute<any> | undefined;
+    $delay: DelayConfig | undefined;
+    $timeout: TimeoutConfig | undefined;
+    $fallback: FunctionToExecute<any> | undefined;
+    beforeRetryFn?: (retryCount: number) => void;
+    logging: boolean;
+    constructor(retryCount: number);
+    onlyErrors(errors: (typeof GritError)[]): this;
+    skipErrors(errors: (typeof GritError)[]): this;
+    withLogging(enabled?: boolean): this;
+    withDelay(config: DelayConfig): this;
+    withTimeout(timeout: TimeoutConfig): this;
+    beforeRetry(fn: (retryCount: number) => void): this;
+    withFallback<T>(fallback: FunctionToExecute<T>): GritBuilder<T>;
+    attempt<T = FallbackType>(fn: FunctionToExecute<T>): Promise<FallbackType extends never ? T : T | FallbackType>;
+}
+export { GritBuilder };

package/dist/builder.js

@@ -0,0 +1,62 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _GritBuilder_instances, _GritBuilder_build;
+import { Grit } from "./grit.js";
+class GritBuilder {
+    constructor(retryCount) {
+        _GritBuilder_instances.add(this);
+        this._onlyErrors = [];
+        this._skipErrors = [];
+        this.fn = undefined;
+        this.logging = false;
+        this.retryCount = retryCount;
+    }
+    onlyErrors(errors) {
+        this._onlyErrors = errors;
+        return this;
+    }
+    skipErrors(errors) {
+        this._skipErrors = errors;
+        return this;
+    }
+    withLogging(enabled = true) {
+        this.logging = enabled;
+        return this;
+    }
+    withDelay(config) {
+        this.$delay = config;
+        return this;
+    }
+    withTimeout(timeout) {
+        this.$timeout = timeout;
+        return this;
+    }
+    beforeRetry(fn) {
+        this.beforeRetryFn = fn;
+        return this;
+    }
+    withFallback(fallback) {
+        const newBuilder = this;
+        newBuilder.$fallback = fallback;
+        return newBuilder;
+    }
+    attempt(fn) {
+        return __classPrivateFieldGet(this, _GritBuilder_instances, "m", _GritBuilder_build).call(this).attempt(fn);
+    }
+}
+_GritBuilder_instances = new WeakSet(), _GritBuilder_build = function _GritBuilder_build() {
+    return new Grit({
+        retryCount: this.retryCount,
+        onlyErrors: this._onlyErrors,
+        skipErrors: this._skipErrors,
+        delay: this.$delay,
+        timeout: this.$timeout,
+        beforeRetryFn: this.beforeRetryFn,
+        logging: this.logging,
+        fallback: this.$fallback,
+    });
+};
+export { GritBuilder };

package/dist/exceptions.d.ts

@@ -0,0 +1,11 @@
+declare class GritError extends Error {
+    constructor(message: string);
+}
+declare class MaxRetriesError extends Error {
+    constructor(message: string);
+}
+export declare class TimeoutError extends Error {
+    name: string;
+    constructor(message: string);
+}
+export { GritError, MaxRetriesError };

package/dist/exceptions.js

@@ -0,0 +1,20 @@
+class GritError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GritError";
+    }
+}
+class MaxRetriesError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MaxRetriesError";
+    }
+}
+export class TimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TimeoutError';
+        this.name = "TimeoutError";
+    }
+}
+export { GritError, MaxRetriesError };

package/dist/grit.d.ts

@@ -0,0 +1,19 @@
+import { GritBuilder } from "./builder.js";
+import type { FunctionToExecute, GritProps } from "./types.js";
+declare class Grit<T> {
+    #private;
+    private retryCount?;
+    private attempts;
+    private retries;
+    private onlyErrors;
+    private skipErrors;
+    private delay;
+    private fallback;
+    private timeout;
+    private beforeRetryFn?;
+    private logging;
+    constructor(props: GritProps);
+    attempt(fn: FunctionToExecute<T>): Promise<T>;
+    static retry(retryCount: number): GritBuilder<never>;
+}
+export { Grit };

package/dist/grit.js

@@ -0,0 +1,129 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Grit_instances, _Grit_currentDelay_get, _Grit_handleBeforeRetry, _Grit_backoff, _Grit_withTimeout, _Grit_processError, _Grit_execute;
+import { GritBuilder } from "./builder.js";
+import { GritError, TimeoutError } from "./exceptions.js";
+import { isObject, validateGritConfig } from "./utils.js";
+class Grit {
+    constructor(props) {
+        _Grit_instances.add(this);
+        this.attempts = 1;
+        this.retries = 0;
+        this.logging = false;
+        const { retryCount, fn, onlyErrors, skipErrors, delay, timeout, beforeRetryFn, logging, fallback } = props;
+        this.retryCount = retryCount;
+        this.onlyErrors = onlyErrors || [];
+        this.skipErrors = skipErrors || [];
+        this.delay = delay;
+        this.fallback = fallback;
+        this.timeout = timeout;
+        this.beforeRetryFn = beforeRetryFn;
+        this.logging = logging || false;
+        validateGritConfig(delay, retryCount);
+    }
+    attempt(fn) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return __classPrivateFieldGet(this, _Grit_instances, "m", _Grit_execute).call(this, fn);
+        });
+    }
+    static retry(retryCount) {
+        return new GritBuilder(retryCount);
+    }
+}
+_Grit_instances = new WeakSet(), _Grit_currentDelay_get = function _Grit_currentDelay_get() {
+    let delay = undefined;
+    if (typeof this.delay === "number") {
+        delay = this.delay;
+    }
+    else if (Array.isArray(this.delay)) {
+        delay = this.delay.shift();
+    }
+    else if (isObject(this.delay) && "delay" in this.delay) {
+        const { factor, delay: initialDelay } = this.delay;
+        delay = initialDelay * Math.pow(factor || 1, this.attempts - 2);
+    }
+    else if (isObject(this.delay) && "minDelay" in this.delay) {
+        const { minDelay, maxDelay, factor } = this.delay;
+        const randomDelay = Math.random() * (maxDelay - minDelay) + minDelay;
+        delay = factor ? randomDelay * Math.pow(factor, this.attempts - 2) : randomDelay;
+    }
+    if (!delay)
+        throw new GritError("No delay. Should never happen.");
+    if (this.logging)
+        console.debug("Delaying for", delay, "ms");
+    return delay;
+}, _Grit_handleBeforeRetry = function _Grit_handleBeforeRetry() {
+    if (this.retries > 0 && this.beforeRetryFn)
+        this.beforeRetryFn(this.retries);
+}, _Grit_backoff = function _Grit_backoff() {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Promise((resolve) => setTimeout(resolve, __classPrivateFieldGet(this, _Grit_instances, "a", _Grit_currentDelay_get)));
+    });
+}, _Grit_withTimeout = function _Grit_withTimeout(promise) {
+    let timer = undefined;
+    const wrappedPromise = new Promise((resolve, reject) => {
+        // Use .then() instead of async IIFE to preserve stack traces
+        // eslint-disable-next-line promise/prefer-await-to-then, promise/prefer-catch
+        promise.then(resolve, reject);
+        if (this.timeout === Number.POSITIVE_INFINITY)
+            return;
+        // We create the error outside of `setTimeout` to preserve the stack trace.
+        const message = `Promise timed out after ${this.timeout} milliseconds`;
+        const timeoutError = new TimeoutError(message);
+        timer = setTimeout(() => {
+            reject(timeoutError);
+        }, this.timeout);
+    });
+    // eslint-disable-next-line promise/prefer-await-to-then
+    wrappedPromise.clear = () => {
+        clearTimeout(timer);
+        timer = undefined;
+    };
+    const cancelablePromise = wrappedPromise.finally(() => {
+        cancelablePromise.clear();
+    });
+    return cancelablePromise;
+}, _Grit_processError = function _Grit_processError(error) {
+    if (error && typeof error === 'object' && 'constructor' in error) {
+        if (this.skipErrors.length > 0 && this.skipErrors.includes(error.constructor))
+            throw error;
+        if (this.onlyErrors.length > 0 && !this.onlyErrors.includes(error.constructor))
+            throw error;
+    }
+    this.attempts++;
+    this.retries++;
+}, _Grit_execute = function _Grit_execute(fn) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            __classPrivateFieldGet(this, _Grit_instances, "m", _Grit_handleBeforeRetry).call(this);
+            console.log('this.timeout', this.timeout);
+            if (this.timeout)
+                return yield __classPrivateFieldGet(this, _Grit_instances, "m", _Grit_withTimeout).call(this, Promise.resolve(fn(this.attempts)));
+            return yield fn(this.attempts);
+        }
+        catch (error) {
+            if (this.retries >= this.retryCount) {
+                if (this.fallback)
+                    return this.fallback(this.attempts);
+                throw error;
+            }
+            __classPrivateFieldGet(this, _Grit_instances, "m", _Grit_processError).call(this, error);
+            if (this.delay)
+                return __classPrivateFieldGet(this, _Grit_instances, "m", _Grit_backoff).call(this).then(() => __classPrivateFieldGet(this, _Grit_instances, "m", _Grit_execute).call(this, fn));
+            return yield __classPrivateFieldGet(this, _Grit_instances, "m", _Grit_execute).call(this, fn);
+        }
+    });
+};
+export { Grit };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { GritBuilder } from "./builder.js";
+export { Grit } from "./grit.js";
+export type { DelayConfig, FunctionToExecute } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { GritBuilder } from "./builder.js";
+export { Grit } from "./grit.js";

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export type GritProps = {
+    retryCount?: number;
+    fn?: FunctionToExecute<any>;
+    fallback?: FunctionToExecute<any>;
+    onlyErrors?: (typeof Error)[];
+    skipErrors?: (typeof Error)[];
+    delay?: DelayConfig;
+    timeout?: TimeoutConfig;
+    beforeRetryFn?: (retryCount: number) => void;
+    logging?: boolean;
+};
+export type TimeoutConfig = number;
+export type DelayConfig = number | number[] | {
+    factor?: number;
+    delay: number;
+} | {
+    factor?: number;
+    minDelay: number;
+    maxDelay: number;
+};
+export type FunctionToExecute<T> = (attempts?: number) => (Promise<T> | T);

package/dist/types.js

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

package/dist/utils.d.ts

@@ -0,0 +1,4 @@
+import type { DelayConfig } from "./types.js";
+export declare const isObject: (o: any) => o is Record<string, any>;
+export declare const isPromise: <T>(value: any) => value is Promise<T>;
+export declare const validateGritConfig: (config: DelayConfig | undefined, retryCount: number | undefined) => void;

package/dist/utils.js

@@ -0,0 +1,50 @@
+import { GritError } from "./exceptions.js";
+export const isObject = (o) => {
+    return typeof o === 'object' && !Array.isArray(o) && o !== null;
+};
+export const isPromise = (value) => {
+    return value !== null && typeof value === "object" && typeof value.then === "function";
+};
+export const validateGritConfig = (config, retryCount) => {
+    if (!config)
+        return;
+    if (!retryCount)
+        throw new GritError("Missing retry config (Grit.retry(<count>))");
+    // validate array config
+    if (Array.isArray(config)) {
+        if (config.length !== retryCount)
+            throw new GritError("Delay array length must be equal to retry count");
+        for (const delay of config) {
+            if (delay <= 0)
+                throw new GritError("delay must be greater than 0");
+        }
+        return;
+    }
+    if (typeof config === "number") {
+        if (config <= 0)
+            throw new GritError("delay must be greater than 0");
+        return;
+    }
+    if (!isObject(config))
+        throw new GritError("Invalid backoff config");
+    // validate delay config
+    if ("delay" in config) {
+        if (typeof config.delay !== "number")
+            throw new GritError("delay must be a number");
+        if (config.delay <= 0)
+            throw new GritError("delay must be greater than 0");
+        return;
+    }
+    // validate random delay config
+    const { minDelay, maxDelay } = config;
+    if (!minDelay || typeof minDelay !== "number")
+        throw new GritError("minDelay must be a number");
+    if (!maxDelay || typeof maxDelay !== "number")
+        throw new GritError("maxDelay must be a number");
+    if (minDelay >= maxDelay)
+        throw new GritError("minDelay must be less than maxDelay");
+    if (minDelay <= 0)
+        throw new GritError("minDelay must be greater than 0");
+    if (maxDelay <= 0)
+        throw new GritError("maxDelay must be greater than 0");
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@wowistudio/grit",
+  "description": "A library for retry.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "version": "0.0.1",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "vitest": "^2.1.8",
+    "@types/node": "^20.9.0"
+  }
+}