@markwharton/api-core 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,71 @@
+# @markwharton/api-core
+
+Shared utilities for API client packages.
+
+## Install
+
+```bash
+npm install @markwharton/api-core
+```
+
+## API Reference
+
+### TTLCache
+
+In-memory TTL cache with request coalescing. When multiple concurrent callers request the same expired key, only one factory call is made.
+
+```typescript
+import { TTLCache } from '@markwharton/api-core';
+
+const cache = new TTLCache();
+
+// Get or populate a cached value (5 minute TTL)
+const data = await cache.get('employees', 5 * 60_000, () => fetchEmployees());
+
+// Invalidate by key prefix
+cache.invalidate('timesheet:');
+
+// Clear all cached data
+cache.clear();
+```
+
+### fetchWithRetry
+
+Automatic retry on HTTP 429 and 503 with exponential backoff. Respects the `Retry-After` header.
+
+```typescript
+import { fetchWithRetry } from '@markwharton/api-core';
+
+const response = await fetchWithRetry(url, init, {
+  retry: { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 10000 },
+  onRetry: ({ attempt, delayMs, status }) => {
+    console.log(`Retry ${attempt} after ${delayMs}ms (HTTP ${status})`);
+  },
+});
+```
+
+### batchMap
+
+Map over items with bounded concurrency.
+
+```typescript
+import { batchMap } from '@markwharton/api-core';
+
+const results = await batchMap(items, 5, async (item) => fetchItem(item.id));
+```
+
+### getErrorMessage
+
+Extract a safe error message from any error type.
+
+```typescript
+import { getErrorMessage } from '@markwharton/api-core';
+
+try { ... } catch (err) {
+  console.error(getErrorMessage(err));
+}
+```
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -3,5 +3,28 @@
  */
 /**
  * Get a safe error message from any error type
+ *
+ * @param error - The caught error value
+ * @param fallback - Custom fallback message (default: 'Unknown error')
  */
-export declare function getErrorMessage(error: unknown): string;
+export declare function getErrorMessage(error: unknown, fallback?: string): string;
+/**
+ * Parsed error from a JSON API response
+ */
+export interface ParsedError {
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * Parse a JSON error response body into a human-readable message.
+ *
+ * Handles common API error formats:
+ * - `{ "message": "..." }`
+ * - `{ "error": "..." }`
+ * - Plain text
+ *
+ * @param errorText - Raw error response text
+ * @param statusCode - HTTP status code (used as fallback message)
+ * @returns Parsed error with message
+ */
+export declare function parseJsonErrorResponse(errorText: string, statusCode: number): ParsedError;

package/dist/errors.js

@@ -5,10 +5,41 @@
 const DEFAULT_ERROR_MESSAGE = 'Unknown error';
 /**
  * Get a safe error message from any error type
+ *
+ * @param error - The caught error value
+ * @param fallback - Custom fallback message (default: 'Unknown error')
  */
-export function getErrorMessage(error) {
+export function getErrorMessage(error, fallback) {
     if (error instanceof Error) {
         return error.message;
     }
-    return DEFAULT_ERROR_MESSAGE;
+    return fallback ?? DEFAULT_ERROR_MESSAGE;
+}
+/**
+ * Parse a JSON error response body into a human-readable message.
+ *
+ * Handles common API error formats:
+ * - `{ "message": "..." }`
+ * - `{ "error": "..." }`
+ * - Plain text
+ *
+ * @param errorText - Raw error response text
+ * @param statusCode - HTTP status code (used as fallback message)
+ * @returns Parsed error with message
+ */
+export function parseJsonErrorResponse(errorText, statusCode) {
+    try {
+        const errorJson = JSON.parse(errorText);
+        if (errorJson.message) {
+            return { message: errorJson.message };
+        }
+        if (errorJson.error) {
+            return { message: errorJson.error };
+        }
+        return { message: `HTTP ${statusCode}` };
+    }
+    catch {
+        // Not JSON, return as-is or fallback
+        return { message: errorText || `HTTP ${statusCode}` };
+    }
 }

package/dist/index.d.ts

@@ -3,8 +3,11 @@
  *
  * Shared utilities for API client packages.
  */
+export { ok, okVoid, err } from './result.js';
+export type { Result } from './result.js';
 export { TTLCache } from './cache.js';
 export { batchMap } from './utils.js';
-export { getErrorMessage } from './errors.js';
+export { getErrorMessage, parseJsonErrorResponse } from './errors.js';
+export type { ParsedError } from './errors.js';
 export { fetchWithRetry } from './retry.js';
 export type { RetryConfig, FetchWithRetryOptions } from './retry.js';

package/dist/index.js

@@ -3,11 +3,13 @@
  *
  * Shared utilities for API client packages.
  */
+// Result
+export { ok, okVoid, err } from './result.js';
 // Cache
 export { TTLCache } from './cache.js';
 // Utilities
 export { batchMap } from './utils.js';
 // Errors
-export { getErrorMessage } from './errors.js';
+export { getErrorMessage, parseJsonErrorResponse } from './errors.js';
 // Retry
 export { fetchWithRetry } from './retry.js';

package/dist/result.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Universal Result Type
+ *
+ * Standard return type for all fallible API operations.
+ * Aligned with @markwharton/pwa-core Result<T>.
+ */
+/**
+ * Result of a fallible operation
+ *
+ * @example
+ * ```typescript
+ * // Success
+ * const result: Result<User> = { ok: true, data: user };
+ *
+ * // Error
+ * const result: Result<User> = { ok: false, error: 'Not found', status: 404 };
+ * ```
+ */
+export interface Result<T> {
+    /** Whether the operation succeeded */
+    ok: boolean;
+    /** The data if successful */
+    data?: T;
+    /** Error message if failed */
+    error?: string;
+    /** HTTP status code (present on error, sometimes on success) */
+    status?: number;
+}
+/**
+ * Create a successful Result with data
+ */
+export declare function ok<T>(data: T): Result<T>;
+/**
+ * Create a successful Result with no data
+ */
+export declare function okVoid(): Result<void>;
+/**
+ * Create a failed Result with an error message and optional status code
+ */
+export declare function err<T = never>(error: string, status?: number): Result<T>;

package/dist/result.js

@@ -0,0 +1,27 @@
+/**
+ * Universal Result Type
+ *
+ * Standard return type for all fallible API operations.
+ * Aligned with @markwharton/pwa-core Result<T>.
+ */
+/**
+ * Create a successful Result with data
+ */
+export function ok(data) {
+    return { ok: true, data };
+}
+/**
+ * Create a successful Result with no data
+ */
+export function okVoid() {
+    return { ok: true };
+}
+/**
+ * Create a failed Result with an error message and optional status code
+ */
+export function err(error, status) {
+    const result = { ok: false, error };
+    if (status !== undefined)
+        result.status = status;
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/api-core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Shared utilities for API client packages",
   "type": "module",
   "main": "dist/index.js",