jitterbug 1.0.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cory Lewis
+
+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,176 @@
+# jitterbug
+
+Jitterbug is a lightweight library for building reliable retry behavior in distributed systems and API clients.
+
+![Build Status](https://github.com/mecharmor/jitterbug/actions/workflows/build.yml/badge.svg?branch=main)
+![Tests](https://img.shields.io/github/actions/workflow/status/mecharmor/jitterbug/build.yml?branch=main&label=tests)
+![Version](https://img.shields.io/npm/v/jitterbug?label=version)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+
+## Installation
+
+```bash
+npm install jitterbug
+```
+
+## Usage
+
+### JavaScript/TypeScript
+
+```typescript
+import { retry, type RetryOptions } from 'jitterbug';
+
+// Basic usage
+const fetchWithRetry = retry(async (url) => {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error('Request failed');
+  return response.json();
+});
+
+// With options
+const fetchWithRetry = retry(async (url) => {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error('Request failed');
+  return response.json();
+}, {
+  maxAttempts: 5,
+  delay: 1000,
+  backoff: 'exponential', // 'exponential', 'linear', or 'fixed'
+  onRetry: (error, attempt, waitTime) => {
+    console.log(`Retry attempt ${attempt} after ${waitTime}ms`);
+  }
+});
+
+// Use it
+try {
+  const data = await fetchWithRetry('https://api.example.com/data');
+  console.log(data);
+} catch (error) {
+  console.error('All retry attempts failed:', error);
+}
+```
+
+## API
+
+### `retry<T>(fn: T, options?: RetryOptions): T`
+
+Creates a retry wrapper function.
+
+**Parameters:**
+- `fn`: The async function to retry
+- `options`: Configuration object (optional)
+  - `maxAttempts` (number, default: 3): Maximum number of retry attempts
+  - `delay` (number, default: 1000): Base delay in milliseconds
+  - `backoff` ('exponential' | 'linear' | 'fixed', default: 'exponential'): Backoff strategy
+  - `onRetry` ((error: Error, attempt: number, waitTime: number) => void, optional): Callback called before each retry
+
+**Returns:** A function that wraps the original function with retry logic
+
+**TypeScript Types:**
+```typescript
+import type { RetryOptions, BackoffStrategy } from 'jitterbug';
+```
+
+## Development
+
+### Building
+
+```bash
+# Build the project
+npm run build
+
+# Build in watch mode
+npm run dev
+
+# Type check without building
+npm run typecheck
+```
+
+### Running Tests
+
+```bash
+# Run tests in watch mode
+npm test
+
+# Run tests once
+npm run test:run
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+### Publishing
+
+Publishing to npm is automated via GitHub Actions. To publish a new version:
+
+```bash
+# Choose one based on the type of change:
+npm version patch  # Bug fixes: 0.1.0 -> 0.1.1
+npm version minor  # New features: 0.1.0 -> 0.2.0
+npm version major  # Breaking changes: 0.1.0 -> 1.0.0
+
+# This automatically:
+# - Updates package.json version
+# - Builds the project (via version script)
+# - Creates a git commit
+# - Creates a git tag (v0.1.1, v0.2.0, etc.)
+
+# Then push both the commit and tags:
+git push && git push --tags
+```
+
+**Publishing alpha/beta versions:**
+
+For pre-release versions (alpha, beta, rc):
+
+```bash
+# Create an alpha version
+npm version prepatch --preid=alpha  # 0.1.0 -> 0.1.1-alpha.0
+npm version preminor --preid=alpha  # 0.1.0 -> 0.2.0-alpha.0
+npm version premajor --preid=alpha  # 0.1.0 -> 1.0.0-alpha.0
+
+# Increment alpha version
+npm version prerelease --preid=alpha  # 0.1.1-alpha.0 -> 0.1.1-alpha.1
+
+# Push the commit and tag
+git push && git push --tags
+```
+
+The CI/CD pipeline will automatically:
+- Run all tests
+- Build the project
+- Verify version matches the tag
+- Publish to npm (if tests pass)
+
+**Note:** `NPM_TOKEN` secret needs to be setupas a GitHub secret with your npm access token.
+
+### Project Structure
+
+```
+jitterbug/
+├── src/              # TypeScript source code
+│   ├── retry.ts      # Core retry implementation
+│   └── index.ts      # Main entry point
+├── dist/             # Built output (ESM + CJS + types)
+├── test/             # Test files
+│   └── retry.test.js
+├── tsconfig.json     # TypeScript configuration
+├── tsup.config.ts    # Build configuration
+└── package.json
+```
+
+## Test Coverage
+
+![Coverage](https://img.shields.io/badge/coverage-37.31%25-red)
+
+| Metric | Coverage |
+|--------|----------|
+| Statements | 37.31% |
+| Branches | 82.35% |
+| Functions | 66.67% |
+| Lines | 37.31% |
+
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// src/retry.ts
+function calculateDelay(baseDelay, attempt, backoff) {
+  switch (backoff) {
+    case "exponential":
+      return baseDelay * Math.pow(2, attempt - 1);
+    case "linear":
+      return baseDelay * attempt;
+    case "fixed":
+    default:
+      return baseDelay;
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function retry(fn, options = {}) {
+  const {
+    maxAttempts = 3,
+    delay = 1e3,
+    backoff = "exponential",
+    onRetry = () => {
+    }
+  } = options;
+  return (async function(...args) {
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fn(...args);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt < maxAttempts) {
+          const waitTime = calculateDelay(delay, attempt, backoff);
+          onRetry(lastError, attempt, waitTime);
+          await sleep(waitTime);
+        }
+      }
+    }
+    throw lastError;
+  });
+}
+
+// src/index.ts
+var index_default = {
+  retry
+};
+
+exports.calculateDelay = calculateDelay;
+exports.default = index_default;
+exports.retry = retry;
+exports.sleep = sleep;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/retry.ts","../src/index.ts"],"names":[],"mappings":";;;;;AAiBA,SAAS,cAAA,CAAe,SAAA,EAAmB,OAAA,EAAiB,OAAA,EAAkC;AAC5F,EAAA,QAAQ,OAAA;AAAS,IACf,KAAK,aAAA;AACH,MAAA,OAAO,SAAA,GAAY,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,UAAU,CAAC,CAAA;AAAA,IAC5C,KAAK,QAAA;AACH,MAAA,OAAO,SAAA,GAAY,OAAA;AAAA,IACrB,KAAK,OAAA;AAAA,IACL;AACE,MAAA,OAAO,SAAA;AAAA;AAEb;AAEA,SAAS,MAAM,EAAA,EAA2B;AACxC,EAAA,OAAO,IAAI,OAAA,CAAQ,CAAA,OAAA,KAAW,UAAA,CAAW,OAAA,EAAS,EAAE,CAAC,CAAA;AACvD;AAQO,SAAS,KAAA,CACd,EAAA,EACA,OAAA,GAAwB,EAAC,EACtB;AACH,EAAA,MAAM;AAAA,IACJ,WAAA,GAAc,CAAA;AAAA,IACd,KAAA,GAAQ,GAAA;AAAA,IACR,OAAA,GAAU,aAAA;AAAA,IACV,UAAU,MAAM;AAAA,IAAC;AAAA,GACnB,GAAI,OAAA;AAEJ,EAAA,QAAQ,kBAAkB,IAAA,EAA6C;AACrE,IAAA,IAAI,SAAA;AAEJ,IAAA,KAAA,IAAS,OAAA,GAAU,CAAA,EAAG,OAAA,IAAW,WAAA,EAAa,OAAA,EAAA,EAAW;AACvD,MAAA,IAAI;AACF,QAAA,OAAO,MAAM,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,MACzB,SAAS,KAAA,EAAO;AACd,QAAA,SAAA,GAAY,iBAAiB,KAAA,GAAQ,KAAA,GAAQ,IAAI,KAAA,CAAM,MAAA,CAAO,KAAK,CAAC,CAAA;AAEpE,QAAA,IAAI,UAAU,WAAA,EAAa;AACzB,UAAA,MAAM,QAAA,GAAW,cAAA,CAAe,KAAA,EAAO,OAAA,EAAS,OAAO,CAAA;AACvD,UAAA,OAAA,CAAQ,SAAA,EAAW,SAAS,QAAQ,CAAA;AACpC,UAAA,MAAM,MAAM,QAAQ,CAAA;AAAA,QACtB;AAAA,MACF;AAAA,IACF;AAEA,IAAA,MAAM,SAAA;AAAA,EACR,CAAA;AACF;;;AC7DA,IAAO,aAAA,GAAQ;AAAA,EACb;AACF","file":"index.cjs","sourcesContent":["/**\n * Core retry logic implementation\n */\n\nexport type BackoffStrategy = 'exponential' | 'linear' | 'fixed';\n\nexport interface RetryOptions {\n  /** Maximum number of retry attempts (default: 3) */\n  maxAttempts?: number;\n  /** Base delay in milliseconds (default: 1000) */\n  delay?: number;\n  /** Backoff strategy: 'exponential', 'linear', or 'fixed' (default: 'exponential') */\n  backoff?: BackoffStrategy;\n  /** Callback called before each retry (error, attempt, waitTime) */\n  onRetry?: (error: Error, attempt: number, waitTime: number) => void;\n}\n\nfunction calculateDelay(baseDelay: number, attempt: number, backoff: BackoffStrategy): number {\n  switch (backoff) {\n    case 'exponential':\n      return baseDelay * Math.pow(2, attempt - 1);\n    case 'linear':\n      return baseDelay * attempt;\n    case 'fixed':\n    default:\n      return baseDelay;\n  }\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n\n/**\n * Creates a retry wrapper function\n * @param fn - The async function to retry\n * @param options - Retry configuration\n * @returns A function that wraps the original function with retry logic\n */\nexport function retry<T extends (...args: any[]) => Promise<any>>(\n  fn: T,\n  options: RetryOptions = {}\n): T {\n  const {\n    maxAttempts = 3,\n    delay = 1000,\n    backoff = 'exponential',\n    onRetry = () => {}\n  } = options;\n\n  return (async function(...args: Parameters<T>): Promise<ReturnType<T>> {\n    let lastError: Error;\n    \n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n      try {\n        return await fn(...args);\n      } catch (error) {\n        lastError = error instanceof Error ? error : new Error(String(error));\n        \n        if (attempt < maxAttempts) {\n          const waitTime = calculateDelay(delay, attempt, backoff);\n          onRetry(lastError, attempt, waitTime);\n          await sleep(waitTime);\n        }\n      }\n    }\n    \n    throw lastError!;\n  }) as T;\n}\n\nexport { calculateDelay, sleep };\n\n","/**\n * Jitterbug - A lightweight library for building reliable retry behavior\n */\n\nexport { retry, calculateDelay, sleep, type RetryOptions, type BackoffStrategy } from './retry';\n\nimport { retry } from './retry';\n\nexport default {\n  retry\n};\n\n"]}

package/dist/index.d.cts

@@ -0,0 +1,35 @@
+/**
+ * Core retry logic implementation
+ */
+type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Base delay in milliseconds (default: 1000) */
+    delay?: number;
+    /** Backoff strategy: 'exponential', 'linear', or 'fixed' (default: 'exponential') */
+    backoff?: BackoffStrategy;
+    /** Callback called before each retry (error, attempt, waitTime) */
+    onRetry?: (error: Error, attempt: number, waitTime: number) => void;
+}
+declare function calculateDelay(baseDelay: number, attempt: number, backoff: BackoffStrategy): number;
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Creates a retry wrapper function
+ * @param fn - The async function to retry
+ * @param options - Retry configuration
+ * @returns A function that wraps the original function with retry logic
+ */
+declare function retry<T extends (...args: any[]) => Promise<any>>(fn: T, options?: RetryOptions): T;
+
+/**
+ * Jitterbug - A lightweight library for building reliable retry behavior
+ */
+
+declare const _default: {
+    retry: typeof retry;
+};
+
+// @ts-ignore
+export = _default;
+export { type BackoffStrategy, type RetryOptions, calculateDelay, retry, sleep };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Core retry logic implementation
+ */
+type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Base delay in milliseconds (default: 1000) */
+    delay?: number;
+    /** Backoff strategy: 'exponential', 'linear', or 'fixed' (default: 'exponential') */
+    backoff?: BackoffStrategy;
+    /** Callback called before each retry (error, attempt, waitTime) */
+    onRetry?: (error: Error, attempt: number, waitTime: number) => void;
+}
+declare function calculateDelay(baseDelay: number, attempt: number, backoff: BackoffStrategy): number;
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Creates a retry wrapper function
+ * @param fn - The async function to retry
+ * @param options - Retry configuration
+ * @returns A function that wraps the original function with retry logic
+ */
+declare function retry<T extends (...args: any[]) => Promise<any>>(fn: T, options?: RetryOptions): T;
+
+/**
+ * Jitterbug - A lightweight library for building reliable retry behavior
+ */
+
+declare const _default: {
+    retry: typeof retry;
+};
+
+export { type BackoffStrategy, type RetryOptions, calculateDelay, _default as default, retry, sleep };

package/dist/index.js

@@ -0,0 +1,49 @@
+// src/retry.ts
+function calculateDelay(baseDelay, attempt, backoff) {
+  switch (backoff) {
+    case "exponential":
+      return baseDelay * Math.pow(2, attempt - 1);
+    case "linear":
+      return baseDelay * attempt;
+    case "fixed":
+    default:
+      return baseDelay;
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function retry(fn, options = {}) {
+  const {
+    maxAttempts = 3,
+    delay = 1e3,
+    backoff = "exponential",
+    onRetry = () => {
+    }
+  } = options;
+  return (async function(...args) {
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fn(...args);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt < maxAttempts) {
+          const waitTime = calculateDelay(delay, attempt, backoff);
+          onRetry(lastError, attempt, waitTime);
+          await sleep(waitTime);
+        }
+      }
+    }
+    throw lastError;
+  });
+}
+
+// src/index.ts
+var index_default = {
+  retry
+};
+
+export { calculateDelay, index_default as default, retry, sleep };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/retry.ts","../src/index.ts"],"names":[],"mappings":";AAiBA,SAAS,cAAA,CAAe,SAAA,EAAmB,OAAA,EAAiB,OAAA,EAAkC;AAC5F,EAAA,QAAQ,OAAA;AAAS,IACf,KAAK,aAAA;AACH,MAAA,OAAO,SAAA,GAAY,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,UAAU,CAAC,CAAA;AAAA,IAC5C,KAAK,QAAA;AACH,MAAA,OAAO,SAAA,GAAY,OAAA;AAAA,IACrB,KAAK,OAAA;AAAA,IACL;AACE,MAAA,OAAO,SAAA;AAAA;AAEb;AAEA,SAAS,MAAM,EAAA,EAA2B;AACxC,EAAA,OAAO,IAAI,OAAA,CAAQ,CAAA,OAAA,KAAW,UAAA,CAAW,OAAA,EAAS,EAAE,CAAC,CAAA;AACvD;AAQO,SAAS,KAAA,CACd,EAAA,EACA,OAAA,GAAwB,EAAC,EACtB;AACH,EAAA,MAAM;AAAA,IACJ,WAAA,GAAc,CAAA;AAAA,IACd,KAAA,GAAQ,GAAA;AAAA,IACR,OAAA,GAAU,aAAA;AAAA,IACV,UAAU,MAAM;AAAA,IAAC;AAAA,GACnB,GAAI,OAAA;AAEJ,EAAA,QAAQ,kBAAkB,IAAA,EAA6C;AACrE,IAAA,IAAI,SAAA;AAEJ,IAAA,KAAA,IAAS,OAAA,GAAU,CAAA,EAAG,OAAA,IAAW,WAAA,EAAa,OAAA,EAAA,EAAW;AACvD,MAAA,IAAI;AACF,QAAA,OAAO,MAAM,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,MACzB,SAAS,KAAA,EAAO;AACd,QAAA,SAAA,GAAY,iBAAiB,KAAA,GAAQ,KAAA,GAAQ,IAAI,KAAA,CAAM,MAAA,CAAO,KAAK,CAAC,CAAA;AAEpE,QAAA,IAAI,UAAU,WAAA,EAAa;AACzB,UAAA,MAAM,QAAA,GAAW,cAAA,CAAe,KAAA,EAAO,OAAA,EAAS,OAAO,CAAA;AACvD,UAAA,OAAA,CAAQ,SAAA,EAAW,SAAS,QAAQ,CAAA;AACpC,UAAA,MAAM,MAAM,QAAQ,CAAA;AAAA,QACtB;AAAA,MACF;AAAA,IACF;AAEA,IAAA,MAAM,SAAA;AAAA,EACR,CAAA;AACF;;;AC7DA,IAAO,aAAA,GAAQ;AAAA,EACb;AACF","file":"index.js","sourcesContent":["/**\n * Core retry logic implementation\n */\n\nexport type BackoffStrategy = 'exponential' | 'linear' | 'fixed';\n\nexport interface RetryOptions {\n  /** Maximum number of retry attempts (default: 3) */\n  maxAttempts?: number;\n  /** Base delay in milliseconds (default: 1000) */\n  delay?: number;\n  /** Backoff strategy: 'exponential', 'linear', or 'fixed' (default: 'exponential') */\n  backoff?: BackoffStrategy;\n  /** Callback called before each retry (error, attempt, waitTime) */\n  onRetry?: (error: Error, attempt: number, waitTime: number) => void;\n}\n\nfunction calculateDelay(baseDelay: number, attempt: number, backoff: BackoffStrategy): number {\n  switch (backoff) {\n    case 'exponential':\n      return baseDelay * Math.pow(2, attempt - 1);\n    case 'linear':\n      return baseDelay * attempt;\n    case 'fixed':\n    default:\n      return baseDelay;\n  }\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n\n/**\n * Creates a retry wrapper function\n * @param fn - The async function to retry\n * @param options - Retry configuration\n * @returns A function that wraps the original function with retry logic\n */\nexport function retry<T extends (...args: any[]) => Promise<any>>(\n  fn: T,\n  options: RetryOptions = {}\n): T {\n  const {\n    maxAttempts = 3,\n    delay = 1000,\n    backoff = 'exponential',\n    onRetry = () => {}\n  } = options;\n\n  return (async function(...args: Parameters<T>): Promise<ReturnType<T>> {\n    let lastError: Error;\n    \n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n      try {\n        return await fn(...args);\n      } catch (error) {\n        lastError = error instanceof Error ? error : new Error(String(error));\n        \n        if (attempt < maxAttempts) {\n          const waitTime = calculateDelay(delay, attempt, backoff);\n          onRetry(lastError, attempt, waitTime);\n          await sleep(waitTime);\n        }\n      }\n    }\n    \n    throw lastError!;\n  }) as T;\n}\n\nexport { calculateDelay, sleep };\n\n","/**\n * Jitterbug - A lightweight library for building reliable retry behavior\n */\n\nexport { retry, calculateDelay, sleep, type RetryOptions, type BackoffStrategy } from './retry';\n\nimport { retry } from './retry';\n\nexport default {\n  retry\n};\n\n"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "jitterbug",
+  "version": "1.0.0-alpha.2",
+  "description": "A lightweight library for building reliable retry behavior in distributed systems and API clients",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run test:run",
+    "version": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "@vitest/coverage-v8": "^1.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^1.2.0"
+  },
+  "keywords": [
+    "retry",
+    "retry-logic",
+    "api-client",
+    "distributed-systems"
+  ],
+  "author": "Cory Lewis",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mecharmor/jitterbug.git"
+  }
+}