tomevault-io API Client Skill
Patterns for fetch-based API communication with robust error handling, retry logic, and response caching.
Philosophy
- Native
fetch()only - No axios or other libraries - Errors should be explicit - No swallowed promises
- Requests should be cancellable - Use AbortController
- Fail gracefully - Handle network issues elegantly
Base Fetch Wrapper
A typed wrapper around fetch with consistent error handling:
/**
* @typedef {Object} ApiError
* @property {number} status - HTTP status code
* @property {string} statusText - HTTP status text
* @property {Object} [body] - Parsed error response body
* @property {string} message - Error message
*/
/**
* Custom error class for API failures
*/
class ApiError extends Error {
/**
* @param {Response} response
* @param {Object} [body]
*/
constructor(response, body = null) {
super(`API Error: ${response.status} ${response.statusText}`);
this.name = 'ApiError';
this.status = response.status;
this.statusText = response.statusText;
this.body = body;
}
}
/**
* Base fetch wrapper with consistent error handling
* @template T
* @param {string} endpoint
* @param {RequestInit} [options={}]
* @returns {Promise<T>}
* @throws {ApiError}
*/
async function api(endpoint, options = {}) {
const response = await fetch(endpoint, {
headers: {
'Content-Type': 'application/json',
...options.headers
},
...options
});
if (!response.ok) {
let body = null;
try {
body = await response.json();
} catch {
// Response may not be JSON
}
throw new ApiError(response, body);
}
// Handle empty responses (204 No Content)
if (response.status === 204) {
return /** @type {T} */ (null);
}
return response.json();
}
Usage
// GET request
const user = await api('/api/users/123');
// POST request
const newUser = await api('/api/users', {
method: 'POST',
body: JSON.stringify({ name: 'Alice', email: 'alice@example.com' })
});
// With error handling
try {
const data = await api('/api/protected');
} catch (error) {
if (error instanceof ApiError) {
if (error.status === 401) {
// Redirect to login
} else if (error.status === 404) {
// Show not found
}
}
throw error;
}
Error Handling Patterns
Typed Error Responses
/**
* @typedef {'validation' | 'auth' | 'not_found' | 'server'} ErrorType
*/
/**
* @typedef {Object} ValidationError
* @property {'validation'} type
* @property {Object<string, string[]>} errors - Field-level errors
*/
/**
* Check error type and handle appropriately
* @param {ApiError} error
*/
function handleApiError(error) {
const body = error.body;
if (error.status === 400 && body?.type === 'validation') {
// Show field-level errors
Object.entries(body.errors).forEach(([field, messages]) => {
console.error(`${field}: ${messages.join(', ')}`);
});
return;
}
if (error.status === 401) {
// Redirect to login
window.location.href = '/login';
return;
}
if (error.status === 403) {
// Show permission denied
showNotification('You do not have permission for this action');
return;
}
if (error.status >= 500) {
// Show generic server error
showNotification('Something went wrong. Please try again later.');
return;
}
// Unknown error - log and show generic message
console.error('Unexpected API error:', error);
showNotification('An unexpected error occurred');
}
Error Boundary Integration
/**
* Report error to monitoring service
* @param {Error} error
* @param {Object} [context]
*/
function reportError(error, context = {}) {
// Use sendBeacon for reliability
navigator.sendBeacon('/api/errors', JSON.stringify({
message: error.message,
stack: error.stack,
status: error instanceof ApiError ? error.status : undefined,
url: window.location.href,
timestamp: Date.now(),
...context
}));
}
Retry with Exponential Backoff
/**
* @typedef {Object} RetryOptions
* @property {number} [retries=3] - Maximum retry attempts
* @property {number} [delay=1000] - Initial delay in ms
* @property {(status: number) => boolean} [retryOn] - Function to determine if status should retry
*/
/**
* Fetch with automatic retry on failure
* @template T
* @param {string} url
* @param {RequestInit} [options={}]
* @param {RetryOptions} [retryOptions={}]
* @returns {Promise<T>}
*/
async function fetchWithRetry(url, options = {}, retryOptions = {}) {
const {
retries = 3,
delay = 1000,
retryOn = (status) => status >= 500 && status <= 504
} = retryOptions;
let lastError;
for (let attempt = 0; attempt <= retries; attempt++) {
try {
return await api(url, options);
} catch (error) {
lastError = error;
// Don't retry on client errors or if not a retryable status
if (error instanceof ApiError && !retryOn(error.status)) {
throw error;
}
// Don't retry if we've exhausted attempts
if (attempt === retries) {
throw error;
}
// Exponential backoff: 1s, 2s, 4s, 8s...
const backoff = delay * Math.pow(2, attempt);
await new Promise(resolve => setTimeout(resolve, backoff));
}
}
throw lastError;
}
Usage
// Retry up to 3 times with exponential backoff
const data = await fetchWithRetry('/api/unstable-endpoint', {}, {
retries: 3,
delay: 1000,
retryOn: (status) => status === 503 || status === 429
});
Request Cancellation
Timeout Pattern
/**
* Fetch with automatic timeout
* @template T
* @param {string} url
* @param {RequestInit & {timeout?: number}} [options={}]
* @returns {Promise<T>}
*/
async function fetchWithTimeout(url, options = {}) {
const { timeout = 10000, ...fetchOptions } = options;
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), timeout);
try {
return await api(url, {
...fetchOptions,
signal: controller.signal
});
} catch (error) {
if (error.name === 'AbortError') {
throw new Error(`Request timed out after ${timeout}ms`);
}
throw error;
} finally {
clearTimeout(timeoutId);
}
}
Component Cleanup
class DataComponent extends HTMLElement {
/** @type {AbortController | null} */
#controller = null;
async connectedCallback() {
this.#controller = new AbortController();
try {
const data = await api('/api/data', {
signal: this.#controller.signal
});
this.render(data);
} catch (error) {
if (error.name === 'AbortError') {
// Component was disconnected - ignore
return;
}
this.renderError(error);
}
}
disconnectedCallback() {
// Cancel any in-flight requests
this.#controller?.abort();
}
}
Response Caching
In-Memory Cache with TTL
/**
* @typedef {Object} CacheEntry
* @property {*} data
* @property {number} expires
*/
/**
* Create a cached fetch function
* @param {number} ttl - Time to live in milliseconds
* @returns {<T>(url: string, options?: RequestInit) => Promise<T>}
*/
function createCachedFetch(ttl = 60000) {
/** @type {Map<string, CacheEntry>} */
const cache = new Map();
return async function cachedFetch(url, options = {}) {
// Only cache GET requests
const method = options.method?.toUpperCase() || 'GET';
if (method !== 'GET') {
return api(url, options);
}
const cacheKey = url;
const cached = cache.get(cacheKey);
if (cached && cached.expires > Date.now()) {
return cached.data;
}
const data = await api(url, options);
cache.set(cacheKey, {
data,
expires: Date.now() + ttl
});
return data;
};
}
Cache Invalidation
/**
* Create a cache manager with invalidation
*/
function createCacheManager(ttl = 60000) {
const cache = new Map();
return {
async fetch(url, options = {}) {
// Same caching logic as above
},
/**
* Invalidate specific URL
* @param {string} url
*/
invalidate(url) {
cache.delete(url);
},
/**
* Invalidate URLs matching pattern
* @param {RegExp} pattern
*/
invalidatePattern(pattern) {
for (const key of cache.keys()) {
if (pattern.test(key)) {
cache.delete(key);
}
}
},
/**
* Clear entire cache
*/
clear() {
cache.clear();
}
};
}
Request Deduplication
Prevent duplicate in-flight requests:
/**
* Create a deduplicated fetch function
* @returns {<T>(url: string, options?: RequestInit) => Promise<T>}
*/
function createDedupedFetch() {
/** @type {Map<string, Promise<*>>} */
const pending = new Map();
return async function dedupedFetch(url, options = {}) {
const method = options.method?.toUpperCase() || 'GET';
// Only dedupe GET requests
if (method !== 'GET') {
return api(url, options);
}
const key = url;
// Return existing promise if request is in-flight
if (pending.has(key)) {
return pending.get(key);
}
// Create new request
const promise = api(url, options).finally(() => {
pending.delete(key);
});
pending.set(key, promise);
return promise;
};
}
Usage
const dedupedFetch = createDedupedFetch();
// These will only make ONE network request
const [user1, user2, user3] = await Promise.all([
dedupedFetch('/api/users/123'),
dedupedFetch('/api/users/123'),
dedupedFetch('/api/users/123')
]);
Offline Queue
Queue failed mutations for retry when online:
/**
* @typedef {Object} QueuedRequest
* @property {string} url
* @property {RequestInit} options
* @property {number} timestamp
*/
/**
* Create an offline-capable mutation queue
*/
function createOfflineQueue() {
const STORAGE_KEY = 'offline-queue';
/**
* Load queue from storage
* @returns {QueuedRequest[]}
*/
function loadQueue() {
const stored = localStorage.getItem(STORAGE_KEY);
return stored ? JSON.parse(stored) : [];
}
/**
* Save queue to storage
* @param {QueuedRequest[]} queue
*/
function saveQueue(queue) {
localStorage.setItem(STORAGE_KEY, JSON.stringify(queue));
}
/**
* Add request to queue
* @param {string} url
* @param {RequestInit} options
*/
function enqueue(url, options) {
const queue = loadQueue();
queue.push({ url, options, timestamp: Date.now() });
saveQueue(queue);
}
/**
* Process all queued requests
*/
async function flush() {
const queue = loadQueue();
const failed = [];
for (const request of queue) {
try {
await api(request.url, request.options);
} catch (error) {
// Keep failed requests for next attempt
failed.push(request);
}
}
saveQueue(failed);
}
// Auto-flush when coming online
window.addEventListener('online', flush);
return {
/**
* Execute request, queue if offline
* @template T
* @param {string} url
* @param {RequestInit} options
* @returns {Promise<T>}
*/
async execute(url, options) {
if (!navigator.onLine) {
enqueue(url, options);
throw new Error('Request queued - you are offline');
}
try {
return await api(url, options);
} catch (error) {
// Queue network errors for retry
if (error.name === 'TypeError') {
enqueue(url, options);
throw new Error('Request queued - network error');
}
throw error;
}
},
flush,
getQueue: loadQueue
};
}
Complete API Client
Combining all patterns:
/**
* Create a full-featured API client
* @param {Object} config
* @param {string} config.baseUrl
* @param {number} [config.timeout=10000]
* @param {number} [config.cacheTtl=60000]
* @param {number} [config.retries=3]
*/
function createApiClient(config) {
const { baseUrl, timeout = 10000, cacheTtl = 60000, retries = 3 } = config;
const cache = new Map();
const pending = new Map();
/**
* @template T
* @param {string} endpoint
* @param {RequestInit & {skipCache?: boolean}} [options={}]
* @returns {Promise<T>}
*/
async function request(endpoint, options = {}) {
const url = `${baseUrl}${endpoint}`;
const method = options.method?.toUpperCase() || 'GET';
const { skipCache = false, ...fetchOptions } = options;
// Check cache for GET requests
if (method === 'GET' && !skipCache) {
const cached = cache.get(url);
if (cached && cached.expires > Date.now()) {
return cached.data;
}
}
// Dedupe GET requests
if (method === 'GET' && pending.has(url)) {
return pending.get(url);
}
// Set up abort controller for timeout
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), timeout);
const promise = fetchWithRetry(url, {
...fetchOptions,
signal: controller.signal
}, { retries })
.then(data => {
// Cache GET responses
if (method === 'GET') {
cache.set(url, { data, expires: Date.now() + cacheTtl });
}
return data;
})
.finally(() => {
clearTimeout(timeoutId);
pending.delete(url);
});
if (method === 'GET') {
pending.set(url, promise);
}
return promise;
}
return {
get: (endpoint, options) => request(endpoint, options),
post: (endpoint, body, options) => request(endpoint, {
method: 'POST',
body: JSON.stringify(body),
...options
}),
put: (endpoint, body, options) => request(endpoint, {
method: 'PUT',
body: JSON.stringify(body),
...options
}),
delete: (endpoint, options) => request(endpoint, {
method: 'DELETE',
...options
}),
invalidateCache: (pattern) => {
for (const key of cache.keys()) {
if (key.includes(pattern)) {
cache.delete(key);
}
}
}
};
}
API Client Checklist
When implementing API calls:
- All requests have a timeout
- AbortController used for cancellation
- Errors include status code and parsed body
- Retry only on safe/idempotent operations
- Cache keys include all relevant parameters
- Component cleanup aborts in-flight requests
- Consider offline queue for mutations
- Use JSDoc types for request/response shapes
Related Skills
- state-management - Client-side state patterns for Web Components
- authentication - Implement secure authentication with JWT, sessions, OAuth...
- rest-api - Write REST API endpoints with HTTP methods, status codes,...
- observability - Implement error tracking, performance monitoring, and use...
Converted and distributed by TomeVault — claim your Tome and manage your conversions.