@markwharton/api-core 1.0.0

package/dist/cache.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Simple in-memory TTL cache with request coalescing
+ *
+ * Provides per-instance memoization for API client responses.
+ * In serverless environments (Azure Functions, Static Web Apps),
+ * module-level state persists across warm invocations within the
+ * same instance — this cache leverages that behavior.
+ *
+ * Request coalescing: when multiple concurrent callers request the
+ * same expired key, only one factory call is made. All callers
+ * receive the same resolved value (or the same rejection).
+ *
+ * Not a distributed cache: each instance has its own cache.
+ * Cold starts and instance recycling naturally clear stale data.
+ */
+export declare class TTLCache {
+    private store;
+    private inflight;
+    /**
+     * Get a cached value, or call the factory to populate it.
+     *
+     * If a factory call is already in progress for this key,
+     * returns the existing promise instead of starting a duplicate.
+     *
+     * @param key - Cache key
+     * @param ttlMs - Time-to-live in milliseconds
+     * @param factory - Async function to produce the value on cache miss
+     */
+    get<T>(key: string, ttlMs: number, factory: () => Promise<T>): Promise<T>;
+    /**
+     * Invalidate cache entries matching a key prefix.
+     *
+     * Also cancels any in-flight requests for matching keys,
+     * so subsequent calls will start fresh factory invocations.
+     *
+     * Example: invalidate('timesheet:') clears all timesheet entries.
+     */
+    invalidate(prefix: string): void;
+    /**
+     * Clear all cached data and in-flight requests.
+     */
+    clear(): void;
+}

package/dist/cache.js

@@ -0,0 +1,78 @@
+/**
+ * Simple in-memory TTL cache with request coalescing
+ *
+ * Provides per-instance memoization for API client responses.
+ * In serverless environments (Azure Functions, Static Web Apps),
+ * module-level state persists across warm invocations within the
+ * same instance — this cache leverages that behavior.
+ *
+ * Request coalescing: when multiple concurrent callers request the
+ * same expired key, only one factory call is made. All callers
+ * receive the same resolved value (or the same rejection).
+ *
+ * Not a distributed cache: each instance has its own cache.
+ * Cold starts and instance recycling naturally clear stale data.
+ */
+export class TTLCache {
+    constructor() {
+        this.store = new Map();
+        this.inflight = new Map();
+    }
+    /**
+     * Get a cached value, or call the factory to populate it.
+     *
+     * If a factory call is already in progress for this key,
+     * returns the existing promise instead of starting a duplicate.
+     *
+     * @param key - Cache key
+     * @param ttlMs - Time-to-live in milliseconds
+     * @param factory - Async function to produce the value on cache miss
+     */
+    async get(key, ttlMs, factory) {
+        const existing = this.store.get(key);
+        if (existing && existing.expiresAt > Date.now()) {
+            return existing.data;
+        }
+        const pending = this.inflight.get(key);
+        if (pending) {
+            return pending;
+        }
+        const promise = factory().then((data) => {
+            this.store.set(key, { data, expiresAt: Date.now() + ttlMs });
+            this.inflight.delete(key);
+            return data;
+        }, (err) => {
+            this.inflight.delete(key);
+            throw err;
+        });
+        this.inflight.set(key, promise);
+        return promise;
+    }
+    /**
+     * Invalidate cache entries matching a key prefix.
+     *
+     * Also cancels any in-flight requests for matching keys,
+     * so subsequent calls will start fresh factory invocations.
+     *
+     * Example: invalidate('timesheet:') clears all timesheet entries.
+     */
+    invalidate(prefix) {
+        for (const key of this.store.keys()) {
+            if (key.startsWith(prefix)) {
+                this.store.delete(key);
+            }
+        }
+        for (const key of this.inflight.keys()) {
+            if (key.startsWith(prefix)) {
+                this.inflight.delete(key);
+            }
+        }
+    }
+    /**
+     * Clear all cached data and in-flight requests.
+     */
+    clear() {
+        this.store.clear();
+        this.inflight.clear();
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared Error Utilities
+ */
+/**
+ * Get a safe error message from any error type
+ */
+export declare function getErrorMessage(error: unknown): string;

package/dist/errors.js

@@ -0,0 +1,14 @@
+/**
+ * Shared Error Utilities
+ */
+/** Default error message when none is available */
+const DEFAULT_ERROR_MESSAGE = 'Unknown error';
+/**
+ * Get a safe error message from any error type
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return DEFAULT_ERROR_MESSAGE;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @markwharton/api-core
+ *
+ * Shared utilities for API client packages.
+ */
+export { TTLCache } from './cache.js';
+export { batchMap } from './utils.js';
+export { getErrorMessage } from './errors.js';
+export { fetchWithRetry } from './retry.js';
+export type { RetryConfig, FetchWithRetryOptions } from './retry.js';

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * @markwharton/api-core
+ *
+ * Shared utilities for API client packages.
+ */
+// Cache
+export { TTLCache } from './cache.js';
+// Utilities
+export { batchMap } from './utils.js';
+// Errors
+export { getErrorMessage } from './errors.js';
+// Retry
+export { fetchWithRetry } from './retry.js';

package/dist/retry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Fetch with Retry
+ *
+ * Automatic retry on HTTP 429 (Too Many Requests) and 503 (Service Unavailable)
+ * with exponential backoff. Respects the Retry-After header when present.
+ */
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay in milliseconds before first retry (default: 1000) */
+    initialDelayMs?: number;
+    /** Maximum delay cap in milliseconds (default: 10000) */
+    maxDelayMs?: number;
+}
+/**
+ * Options for fetchWithRetry
+ */
+export interface FetchWithRetryOptions {
+    /** Retry configuration (required to enable retry) */
+    retry?: Required<RetryConfig>;
+    /** Callback invoked before each retry attempt */
+    onRetry?: (info: {
+        attempt: number;
+        maxRetries: number;
+        delayMs: number;
+        status: number;
+    }) => void;
+}
+/**
+ * Fetch with automatic retry on 429/503 using exponential backoff.
+ * Respects Retry-After header.
+ *
+ * @param url - URL to fetch
+ * @param init - Standard fetch RequestInit
+ * @param options - Retry options
+ * @returns Response from the final attempt
+ */
+export declare function fetchWithRetry(url: string, init: RequestInit, options?: FetchWithRetryOptions): Promise<Response>;

package/dist/retry.js

@@ -0,0 +1,48 @@
+/**
+ * Fetch with Retry
+ *
+ * Automatic retry on HTTP 429 (Too Many Requests) and 503 (Service Unavailable)
+ * with exponential backoff. Respects the Retry-After header when present.
+ */
+/**
+ * Fetch with automatic retry on 429/503 using exponential backoff.
+ * Respects Retry-After header.
+ *
+ * @param url - URL to fetch
+ * @param init - Standard fetch RequestInit
+ * @param options - Retry options
+ * @returns Response from the final attempt
+ */
+export async function fetchWithRetry(url, init, options = {}) {
+    const { retry, onRetry } = options;
+    const maxAttempts = retry ? 1 + retry.maxRetries : 1;
+    let lastResponse;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        lastResponse = await fetch(url, init);
+        // Check if this is a retryable status
+        if (retry && (lastResponse.status === 429 || lastResponse.status === 503)) {
+            if (attempt >= retry.maxRetries) {
+                return lastResponse; // Exhausted retries
+            }
+            // Calculate delay: respect Retry-After header, or use exponential backoff
+            let delayMs;
+            const retryAfterHeader = lastResponse.headers.get('Retry-After');
+            if (retryAfterHeader) {
+                const retryAfterSeconds = parseInt(retryAfterHeader, 10);
+                delayMs = Number.isFinite(retryAfterSeconds)
+                    ? retryAfterSeconds * 1000
+                    : retry.initialDelayMs * Math.pow(2, attempt);
+            }
+            else {
+                delayMs = retry.initialDelayMs * Math.pow(2, attempt);
+            }
+            delayMs = Math.min(delayMs, retry.maxDelayMs);
+            // Notify caller of retry
+            onRetry?.({ attempt: attempt + 1, maxRetries: retry.maxRetries, delayMs, status: lastResponse.status });
+            await new Promise(resolve => setTimeout(resolve, delayMs));
+            continue;
+        }
+        return lastResponse;
+    }
+    return lastResponse;
+}

package/dist/utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared API Client Utilities
+ */
+/**
+ * Map over items with bounded concurrency
+ *
+ * Processes items in batches of `concurrency`, waiting for each batch
+ * to complete before starting the next. This prevents overwhelming
+ * APIs with too many simultaneous requests.
+ *
+ * @param items - Array of items to process
+ * @param concurrency - Maximum number of concurrent operations
+ * @param fn - Async function to apply to each item
+ * @returns Array of results in the same order as input items
+ */
+export declare function batchMap<T, R>(items: T[], concurrency: number, fn: (item: T) => Promise<R>): Promise<R[]>;

package/dist/utils.js

@@ -0,0 +1,27 @@
+/**
+ * Shared API Client Utilities
+ */
+// ============================================================================
+// Concurrency Helper
+// ============================================================================
+/**
+ * Map over items with bounded concurrency
+ *
+ * Processes items in batches of `concurrency`, waiting for each batch
+ * to complete before starting the next. This prevents overwhelming
+ * APIs with too many simultaneous requests.
+ *
+ * @param items - Array of items to process
+ * @param concurrency - Maximum number of concurrent operations
+ * @param fn - Async function to apply to each item
+ * @returns Array of results in the same order as input items
+ */
+export async function batchMap(items, concurrency, fn) {
+    const results = [];
+    for (let i = 0; i < items.length; i += concurrency) {
+        const batch = items.slice(i, i + concurrency);
+        const batchResults = await Promise.all(batch.map(fn));
+        results.push(...batchResults);
+    }
+    return results;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@markwharton/api-core",
+  "version": "1.0.0",
+  "description": "Shared utilities for API client packages",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MarkWharton/api-packages.git",
+    "directory": "packages/api-core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Mark Wharton",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}