vinh-async-utils 3.1.0

package/README.md

@@ -0,0 +1,129 @@
+# @org/async
+
+Async utility functions with retry logic and error handling for TypeScript applications.
+
+## 📦 Package Information
+
+- **Version**: 0.0.1
+- **Publishable**: ✅ Yes
+- **Tag**: `scope:async`
+- **Module Boundaries**: Can only import from `scope:shared` packages
+
+## ⚠️ CI Demo Note
+
+**This package includes an intentionally failing test to demonstrate Nx's self-healing CI feature.** When you run tests, you'll see one failure. This is by design to showcase how `nx fix-ci` works in the CI pipeline.
+
+## 🚀 Features
+
+This package provides powerful async utilities:
+
+- **retry** - Retry failed async operations with configurable options
+- **createRetry** - Create reusable retry functions with default options
+- **withRetry** - Wrap functions to automatically retry on failure
+- **retryAll** - Retry multiple operations and wait for all
+- **retryRace** - Race multiple operations with retry
+- **retryAllSettled** - Get all results regardless of success/failure
+- **TimeoutError** - Custom error class for timeout scenarios
+
+## 📝 Usage Examples
+
+```typescript
+import { retry, createRetry, withRetry, TimeoutError } from '@org/async';
+
+// Basic retry with default options
+const result = await retry(async () => {
+  const response = await fetch('/api/data');
+  return response.json();
+});
+
+// Retry with custom options
+const data = await retry(
+  async (attempt) => {
+    console.log(`Attempt ${attempt + 1}`);
+    return await riskyOperation();
+  },
+  {
+    retries: 3,      // Max 3 retries
+    delay: 1000,     // 1 second delay
+    backoff: 2       // Exponential backoff factor
+  }
+);
+
+// Create a reusable retry function
+const retryWithDefaults = createRetry({
+  retries: 2,
+  delay: 500
+});
+
+const result1 = await retryWithDefaults(operation1);
+const result2 = await retryWithDefaults(operation2);
+
+// Wrap a function to automatically retry
+const safeFunction = withRetry(riskyFunction, { retries: 3 });
+const result = await safeFunction(arg1, arg2);
+
+// Retry multiple operations
+const results = await retryAll([
+  operation1,
+  operation2,
+  operation3
+], { retries: 2 });
+
+// Race operations with retry
+const fastest = await retryRace([
+  slowOperation,
+  fastOperation
+]);
+```
+
+## 🧪 Testing
+
+```bash
+# Run tests for this package (includes 1 intentional failure for CI demo)
+nx test async
+
+# Run tests in watch mode
+nx test async --watch
+
+# Run specific test file
+nx test async --testFile=async-retry.spec.ts
+```
+
+## 🏗️ Building
+
+```bash
+# Build the package
+nx build async
+
+# The build output will be in dist/packages/async
+```
+
+## 📋 Available Commands
+
+```bash
+nx build async    # Build the package
+nx test async     # Run tests (includes intentional failure)
+nx lint async     # Lint the package
+```
+
+## 🔒 Module Boundaries
+
+This package has the tag `scope:async` and can only import from:
+- `@org/utils` (tagged with `scope:shared`)
+
+Attempting to import from `@org/colors` or `@org/strings` will result in a linting error due to module boundary constraints.
+
+## 🔧 Self-Healing CI Demo
+
+This package demonstrates Nx's self-healing CI capabilities. The intentionally failing test helps showcase:
+
+1. How CI detects failures
+2. How `nx fix-ci` provides automated suggestions
+3. How the system can self-correct common issues
+
+To see this in action in CI, the workflow runs:
+```bash
+npx nx fix-ci
+```
+
+This command analyzes failures and provides actionable fixes.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/async-retry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export * from './lib/async-retry.js';

package/dist/lib/async-retry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Options for retry function
+ */
+export interface RetryOptions {
+    /** Maximum number of retries (default: 3) */
+    retries?: number;
+    /** Initial delay in ms (default: 1000) */
+    delay?: number;
+    /** Maximum delay in ms (default: 30000) */
+    maxDelay?: number;
+    /** Exponential backoff factor (default: 2) */
+    factor?: number;
+    /** Callback on each retry */
+    onRetry?: (error: Error, attempt: number, nextDelay: number) => void;
+    /** Function to determine if should retry */
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+}
+/**
+ * Options for retry with timeout
+ */
+export interface RetryWithTimeoutOptions extends RetryOptions {
+    /** Timeout in milliseconds for each attempt */
+    timeout?: number;
+    /** Custom timeout error message */
+    timeoutMessage?: string;
+}
+/**
+ * Timeout error class
+ */
+export declare class TimeoutError extends Error {
+    code: string;
+    constructor(message?: string);
+}
+/**
+ * Retry failed async functions with exponential backoff
+ */
+export declare function retry<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Create a reusable retry wrapper with preset options
+ */
+export declare function createRetry(defaultOptions?: RetryOptions): <T>(fn: (attempt: number) => Promise<T>, overrides?: RetryOptions) => Promise<T>;
+/**
+ * Wrap a function to always retry on failure
+ */
+export declare function withRetry<T extends (...args: any[]) => Promise<any>>(fn: T, options?: RetryOptions): T;
+/**
+ * Execute multiple async operations with individual retry logic
+ */
+export declare function retryAll<T>(fns: Array<(attempt: number) => Promise<T>>, options?: RetryOptions): Promise<T[]>;
+/**
+ * Execute multiple async operations, returning first successful result
+ */
+export declare function retryRace<T>(fns: Array<(attempt: number) => Promise<T>>, options?: RetryOptions): Promise<T>;
+/**
+ * Execute multiple async operations, returning all results (including errors)
+ */
+export declare function retryAllSettled<T>(fns: Array<(attempt: number) => Promise<T>>, options?: RetryOptions): Promise<PromiseSettledResult<T>[]>;
+//# sourceMappingURL=async-retry.d.ts.map

package/dist/lib/async-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-retry.d.ts","sourceRoot":"","sources":["../../src/lib/async-retry.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACrE,4CAA4C;IAC5C,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1D;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,YAAY;IAC3D,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,IAAI,SAAa;gBAEL,OAAO,SAAwB;CAI5C;AAQD;;GAEG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAsCZ;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,cAAc,GAAE,YAAiB,IACnD,CAAC,EACP,IAAI,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,YAAW,YAAiB,KAC3B,OAAO,CAAC,CAAC,CAAC,CAGd;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EAClE,EAAE,EAAE,CAAC,EACL,OAAO,GAAE,YAAiB,GACzB,CAAC,CAIH;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,GAAG,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,EAC3C,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,EAAE,CAAC,CAEd;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,GAAG,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,EAC3C,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,GAAG,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,EAC3C,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC,CAEpC"}

package/dist/lib/async-retry.js

@@ -0,0 +1,77 @@
+/**
+ * Timeout error class
+ */
+export class TimeoutError extends Error {
+    code = 'TIMEOUT';
+    constructor(message = 'Operation timed out') {
+        super(message);
+        this.name = 'TimeoutError';
+    }
+}
+/**
+ * Sleep for specified milliseconds
+ */
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Retry failed async functions with exponential backoff
+ */
+export async function retry(fn, options = {}) {
+    const { retries = 3, delay = 1000, maxDelay = 30000, factor = 2, onRetry = () => {
+        return;
+    }, shouldRetry = () => true, } = options;
+    let lastError;
+    let currentDelay = delay;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return await fn(attempt);
+        }
+        catch (error) {
+            lastError = error;
+            // Check if we should retry
+            if (attempt === retries || !shouldRetry(lastError, attempt)) {
+                throw error;
+            }
+            // Call onRetry callback
+            onRetry(lastError, attempt, currentDelay);
+            // Wait before retrying
+            await sleep(currentDelay);
+            // Calculate next delay with exponential backoff
+            currentDelay = Math.min(currentDelay * factor, maxDelay);
+        }
+    }
+    throw lastError;
+}
+/**
+ * Create a reusable retry wrapper with preset options
+ */
+export function createRetry(defaultOptions = {}) {
+    return (fn, overrides = {}) => {
+        return retry(fn, { ...defaultOptions, ...overrides });
+    };
+}
+/**
+ * Wrap a function to always retry on failure
+ */
+export function withRetry(fn, options = {}) {
+    return (async (...args) => {
+        return retry(() => fn(...args), options);
+    });
+}
+/**
+ * Execute multiple async operations with individual retry logic
+ */
+export async function retryAll(fns, options = {}) {
+    return Promise.all(fns.map((fn) => retry(fn, options)));
+}
+/**
+ * Execute multiple async operations, returning first successful result
+ */
+export async function retryRace(fns, options = {}) {
+    return Promise.race(fns.map((fn) => retry(fn, options)));
+}
+/**
+ * Execute multiple async operations, returning all results (including errors)
+ */
+export async function retryAllSettled(fns, options = {}) {
+    return Promise.allSettled(fns.map((fn) => retry(fn, options)));
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "vinh-async-utils",
+  "version": "3.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@org/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "nx": {
+    "tags": [
+      "scope:async"
+    ]
+  }
+}