push.rocks/webrequest
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix(tests): Fix tests and documentation: adjust test server routes and expectations, add timeout/fallback routes, and refresh README

Browse Source
This commit is contained in:
Jürgen Kunz
2025-10-20 13:41:03 +00:00
parent 54afcc46e2
commit c9c35169fc
6 changed files with 663 additions and 478 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
changelog.md Normal file
View File

@@ -0,0 +1,62 @@
# Changelog
## 2025-10-20 - 4.0.1 - fix(tests)
Fix tests and documentation: adjust test server routes and expectations, add timeout/fallback routes, and refresh README
- Update tests to expect 500 on /apiroute1 instead of 429
- Remove an invalid fallback (apiroute4) from test fallback list and add explicit always-fails route for fallback testing
- Add /slow route to support reliable timeout tests and change timeout test to target /slow with a short timeout
- Adjust fallback test to target the newly added always-fails route and assert response.ok and response.status
- Add additional assertions in tests to ensure correct response properties are present
- Remove migration-v4.md (cleanup of legacy migration guide) and substantially refresh README with comprehensive v4 documentation and examples
## 2025-10-20 - 4.0.0 - feat: Web request client with caching, retries, interceptors
Implemented a comprehensive web request system providing caching strategies, request/response interception, retries with backoff, deduplication and timeout handling. Designed for fetch-compatible integration and convenient HTTP helpers.
- Added cache strategies: NetworkFirst, CacheFirst, StaleWhileRevalidate, NetworkOnly, CacheOnly.
- Introduced InterceptorManager to manage request, response and error interceptors (global and per-request).
- Developed RetryManager with customizable retry/backoff strategies.
- Implemented RequestDeduplicator to prevent simultaneous identical requests.
- Created timeout utilities for aborting/timing out requests.
- Enhanced WebrequestClient to support global interceptors, caching, retry logic and convenience methods.
- Added convenience methods for common HTTP verbs (GET, POST, PUT, DELETE) with JSON handling.
- Exposed a fetch-compatible webrequest function for seamless integration.
- Defined core types for caching, retry options, interceptors and web request configurations.
## 2024-05-29 - 3.0.0..3.0.37 - maintenance
Series of patch and minor releases across the 3.0.x line focused on internal fixes, TypeScript configuration and packaging metadata updates. No major API additions; primarily stabilization and build/config tweaks.
- Numerous "fix(core): update" patches addressing internal issues and small bugfixes across many 3.0.x releases.
- Updated TypeScript configuration (tsconfig) to improve build/typing behavior.
- Updated packaging metadata (npmextra.json) including githost adjustments.
- Regular maintenance bumps (3.0.0 through 3.0.37) to keep the 3.x line stable.
## 2022-03-16 - 2.0.16 - BREAKING CHANGE(core): switch to ESM
Breaking change: project switched module format to ESM.
- Migrated package/module resolution to ESM (breaking change for consumers).
- This release concludes the 2.0.x line with the module format change; follow-up 2.0.x releases prior to this were maintenance updates.
## 2022-03-16 - 2.0.0..2.0.15 - maintenance
Patch/minor releases in the 2.0.x series focused on fixes and incremental improvements.
- Multiple "fix(core): update" commits for internal bugfixes and stability.
- No additional breaking API changes aside from the ESM migration in 2.0.16.
## 2019-06-04 - 1.0.8 - BREAKING CHANGE(core): prepare for binary file support
Breaking change: preparation for future support of binary files.
- Introduced change(s) to enable future binary file support (may affect downstream consumers).
- This marks the tip of the 1.0.x line with a forward-looking compatibility change.
## 2019-02-15 - 1.0.6 - feat: support request body
Added support for sending request bodies.
- Now supports request bodies for applicable HTTP methods (improves POST/PUT usage).
- Followed by several small fixes and minor bumps in the 1.0.x series.
## 2018-11-30..2019-06-04 - 1.0.1..1.0.5, 1.0.7 - maintenance
Minor fixes and releases in the 1.0.x series.
- Multiple small "fix(core): update" commits across 1.0.1–1.0.7.
- General stabilization and incremental improvements prior to the 1.0.8 breaking change.

339
migration-v4.md
View File

@@ -1,339 +0,0 @@
# Migration Guide: v3 → v4
## Overview
Version 4.0 is a complete modernization of `@push.rocks/webrequest`, bringing it in line with modern web standards while maintaining backward compatibility through a deprecated API layer.
## What's New in v4
### Core Improvements
- **Fetch-Compatible API**: Drop-in replacement for native `fetch()` with enhanced features
- **Intelligent HTTP Caching**: Respects `Cache-Control`, `ETag`, `Last-Modified`, and `Expires` headers
- **Multiple Cache Strategies**: network-first, cache-first, stale-while-revalidate, network-only, cache-only
- **Advanced Retry System**: Configurable retry with exponential/linear/constant backoff
- **Request/Response Interceptors**: Middleware pattern for transforming requests and responses
- **Request Deduplication**: Automatically deduplicate simultaneous identical requests
- **TypeScript Generics**: Type-safe response parsing with `webrequest.getJson<T>()`
- **Better Fault Tolerance**: Enhanced multi-endpoint fallback with retry strategies
### Bug Fixes
- Fixed: `deleteJson()` now correctly uses `DELETE` method instead of `GET`
## Migration Path
### Option 1: Quick Migration (Recommended)
The v3 `WebRequest` class is still available but marked as deprecated. Your existing code will continue to work:
```typescript
// This still works in v4 (with deprecation warnings)
import { WebRequest } from '@push.rocks/webrequest';
const client = new WebRequest({ logging: true });
const data = await client.getJson('https://api.example.com/data', true);
```
### Option 2: Migrate to New API
#### Basic Fetch-Compatible Usage
```typescript
// v3
import { WebRequest } from '@push.rocks/webrequest';
const client = new WebRequest();
const response = await client.request('https://api.example.com/data', {
method: 'GET'
});
const data = await response.json();
// v4 - Fetch-compatible
import { webrequest } from '@push.rocks/webrequest';
const response = await webrequest('https://api.example.com/data');
const data = await response.json();
```
#### JSON Convenience Methods
```typescript
// v3
const client = new WebRequest();
const data = await client.getJson('https://api.example.com/data', true);
// v4 - Function API
import { webrequest } from '@push.rocks/webrequest';
const data = await webrequest.getJson('https://api.example.com/data', {
cacheStrategy: 'cache-first'
});
// v4 - Client API (similar to v3)
import { WebrequestClient } from '@push.rocks/webrequest';
const client = new WebrequestClient({ logging: true });
const data = await client.getJson('https://api.example.com/data', {
cacheStrategy: 'cache-first'
});
```
## Feature Comparison
### Caching
```typescript
// v3 - Boolean flag
const data = await client.getJson(url, true); // useCache = true
// v4 - Explicit strategies
const data = await webrequest.getJson(url, {
cacheStrategy: 'cache-first',
cacheMaxAge: 60000 // 60 seconds
});
// v4 - HTTP header-based caching (automatic)
const data = await webrequest.getJson(url, {
cacheStrategy: 'network-first' // Respects Cache-Control headers
});
// v4 - Stale-while-revalidate
const data = await webrequest.getJson(url, {
cacheStrategy: 'stale-while-revalidate' // Return cache, update in background
});
```
### Multi-Endpoint Fallback
```typescript
// v3
const client = new WebRequest();
const response = await client.requestMultiEndpoint(
['https://api1.example.com/data', 'https://api2.example.com/data'],
{ method: 'GET' }
);
// v4
import { webrequest } from '@push.rocks/webrequest';
const response = await webrequest('https://api1.example.com/data', {
fallbackUrls: ['https://api2.example.com/data'],
retry: {
maxAttempts: 3,
backoff: 'exponential'
}
});
```
### Timeout
```typescript
// v3
const response = await client.request(url, {
method: 'GET',
timeoutMs: 30000
});
// v4
const response = await webrequest(url, {
timeout: 30000 // milliseconds
});
```
## New Features in v4
### Retry Strategies
```typescript
import { webrequest } from '@push.rocks/webrequest';
const response = await webrequest('https://api.example.com/data', {
retry: {
maxAttempts: 3,
backoff: 'exponential', // or 'linear', 'constant'
initialDelay: 1000,
maxDelay: 30000,
retryOn: [408, 429, 500, 502, 503, 504], // Status codes to retry
onRetry: (attempt, error, nextDelay) => {
console.log(`Retry attempt ${attempt}, waiting ${nextDelay}ms`);
}
}
});
```
### Request/Response Interceptors
```typescript
import { webrequest } from '@push.rocks/webrequest';
// Add global request interceptor
webrequest.addRequestInterceptor((request) => {
// Add auth header
const headers = new Headers(request.headers);
headers.set('Authorization', `Bearer ${getToken()}`);
return new Request(request, { headers });
});
// Add global response interceptor
webrequest.addResponseInterceptor((response) => {
console.log(`Response: ${response.status} ${response.url}`);
return response;
});
// Per-request interceptors
const response = await webrequest('https://api.example.com/data', {
interceptors: {
request: [(req) => {
console.log('Sending request:', req.url);
return req;
}],
response: [(res) => {
console.log('Received response:', res.status);
return res;
}]
}
});
```
### Request Deduplication
```typescript
import { webrequest } from '@push.rocks/webrequest';
// Multiple simultaneous identical requests will be deduplicated
const [res1, res2, res3] = await Promise.all([
webrequest('https://api.example.com/data', { deduplicate: true }),
webrequest('https://api.example.com/data', { deduplicate: true }),
webrequest('https://api.example.com/data', { deduplicate: true }),
]);
// Only one actual network request is made
```
### TypeScript Generics
```typescript
import { webrequest } from '@push.rocks/webrequest';
interface User {
id: number;
name: string;
email: string;
}
// Type-safe response parsing
const user = await webrequest.getJson<User>('https://api.example.com/user/1');
// user is typed as User
const users = await webrequest.getJson<User[]>('https://api.example.com/users');
// users is typed as User[]
```
### Custom Cache Keys
```typescript
import { webrequest } from '@push.rocks/webrequest';
const response = await webrequest('https://api.example.com/search?q=test', {
cacheStrategy: 'cache-first',
cacheKey: (request) => {
// Custom cache key based on URL without query params
const url = new URL(request.url);
return `search:${url.searchParams.get('q')}`;
}
});
```
### Advanced Client Configuration
```typescript
import { WebrequestClient } from '@push.rocks/webrequest';
// Create a client with default options
const apiClient = new WebrequestClient({
logging: true,
timeout: 30000,
cacheStrategy: 'network-first',
retry: {
maxAttempts: 3,
backoff: 'exponential'
}
});
// Add global interceptors
apiClient.addRequestInterceptor((request) => {
const headers = new Headers(request.headers);
headers.set('X-API-Key', process.env.API_KEY);
return new Request(request, { headers });
});
// All requests through this client use the configured defaults
const data = await apiClient.getJson('https://api.example.com/data');
```
## Breaking Changes
### 1. Cache API Changes
**Before (v3):**
```typescript
await client.getJson(url, true); // Boolean for cache
```
**After (v4):**
```typescript
await webrequest.getJson(url, {
cacheStrategy: 'cache-first' // Explicit strategy
});
```
### 2. Multi-Endpoint API
**Before (v3):**
```typescript
await client.requestMultiEndpoint([url1, url2], options);
```
**After (v4):**
```typescript
await webrequest(url1, {
fallbackUrls: [url2],
retry: true
});
```
### 3. Constructor Options
**Before (v3):**
```typescript
const client = new WebRequest({ logging: true });
```
**After (v4):**
```typescript
// Function API (no constructor)
import { webrequest } from '@push.rocks/webrequest';
// Or client API
import { WebrequestClient } from '@push.rocks/webrequest';
const client = new WebrequestClient({ logging: true });
```
## Deprecation Timeline
- **v4.0**: `WebRequest` class marked as deprecated but fully functional
- **v4.x**: Continued support with deprecation warnings
- **v5.0**: `WebRequest` class will be removed
## Recommendation
We strongly recommend migrating to the new API to take advantage of:
- Standards-aligned fetch-compatible interface
- Intelligent HTTP caching with header support
- Advanced retry and fault tolerance
- Request/response interceptors
- Better TypeScript support
- Request deduplication
The migration is straightforward, and the new API is more powerful and flexible while being simpler to use.
## Need Help?
- Check the updated [README.md](./readme.md) for comprehensive examples
- Report issues at: https://code.foss.global/push.rocks/webrequest/issues

676
readme.md
View File

@@ -1,159 +1,617 @@
# @push.rocks/webrequest
securely request from browsers
Modern, fetch-compatible web request library with intelligent HTTP caching, retry strategies, and advanced fault tolerance.
## Install
## Features
To use `@push.rocks/webrequest` in your project, install it using npm or yarn:
- 🌐 **Fetch-Compatible API** - Drop-in replacement for native `fetch()` with enhanced features
- 💾 **Intelligent HTTP Caching** - Respects `Cache-Control`, `ETag`, `Last-Modified`, and `Expires` headers (RFC 7234)
- 🔄 **Multiple Cache Strategies** - network-first, cache-first, stale-while-revalidate, network-only, cache-only
- 🔁 **Advanced Retry System** - Configurable retry with exponential/linear/constant backoff
- 🎯 **Request/Response Interceptors** - Middleware pattern for transforming requests and responses
- 🚫 **Request Deduplication** - Automatically deduplicate simultaneous identical requests
- 📘 **TypeScript Generics** - Type-safe response parsing with `webrequest.getJson<T>()`
- 🛡️ **Better Fault Tolerance** - Multi-endpoint fallback with retry strategies
- ⏱️ **Timeout Support** - Configurable request timeouts with AbortController
## Installation
```bash
npm install @push.rocks/webrequest --save
# or with yarn
yarn add @push.rocks/webrequest
pnpm install @push.rocks/webrequest
# or
npm install @push.rocks/webrequest
```
This package is designed to be used in an environment where ECMAScript Modules (ESM) and TypeScript are supported.
This package requires a modern JavaScript environment with ESM and TypeScript support.
## Usage
## Quick Start
`@push.rocks/webrequest` is a powerful module designed to simplify making web requests securely from browsers. It leverages modern JavaScript features and TypeScript for a type-safe development experience. Below are comprehensive examples demonstrating how to utilize the module effectively:
### Setting Up
First, import `WebRequest` from the module:
### Basic Fetch-Compatible Usage
```typescript
import { WebRequest } from '@push.rocks/webrequest';
```
import { webrequest } from '@push.rocks/webrequest';
Create an instance of `WebRequest`. You can optionally pass configuration options:
// Use exactly like fetch()
const response = await webrequest('https://api.example.com/data');
const data = await response.json();
```typescript
const webRequest = new WebRequest({
logging: true, // Optional: enables logging, defaults to true
// With options (fetch-compatible + enhanced)
const response = await webrequest('https://api.example.com/data', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ key: 'value' }),
timeout: 30000,
retry: true
});
```
### Making GET Requests
To fetch JSON data:
### JSON Convenience Methods
```typescript
// Fetch JSON data using GET request
async function fetchJsonData() {
const url = 'https://api.example.com/data';
try {
const jsonData = await webRequest.getJson(url);
console.log(jsonData);
} catch (error) {
console.error(error);
}
import { webrequest } from '@push.rocks/webrequest';
// GET JSON with type safety
interface User {
id: number;
name: string;
email: string;
}
fetchJsonData();
const user = await webrequest.getJson<User>('https://api.example.com/user/1');
// user is typed as User
// POST JSON
const result = await webrequest.postJson('https://api.example.com/users', {
name: 'John Doe',
email: 'john@example.com'
});
// Other convenience methods
await webrequest.putJson(url, data);
await webrequest.patchJson(url, data);
await webrequest.deleteJson(url);
```
### POST, PUT, and DELETE Requests
## Cache Strategies
Similarly, you can make POST, PUT, and DELETE requests to send or manipulate data:
### Network-First (Default)
Always fetch from network, fall back to cache on failure. Respects HTTP caching headers.
```typescript
// Example POST request to submit JSON data
async function postJsonData() {
const url = 'https://api.example.com/submit';
const data = { key: 'value' };
try {
const result = await webRequest.postJson(url, data);
console.log(result);
} catch (error) {
console.error(error);
}
}
postJsonData();
// PUT and DELETE can be similarly used
const data = await webrequest.getJson('https://api.example.com/data', {
cacheStrategy: 'network-first'
});
```
### Using Caches
### Cache-First
The library provides mechanisms to cache responses, which is useful for reducing network load and improving performance. Here’s how to fetch data with caching:
Check cache first, only fetch from network if not cached or stale.
```typescript
// Fetch with caching enabled
async function fetchDataWithCache() {
const url = 'https://api.example.com/data';
try {
// The second parameter enables caching
const jsonData = await webRequest.getJson(url, true);
console.log(jsonData);
} catch (error) {
console.error(error);
}
}
fetchDataWithCache();
const data = await webrequest.getJson('https://api.example.com/data', {
cacheStrategy: 'cache-first',
cacheMaxAge: 60000 // 60 seconds
});
```
### Handling Multiple Endpoints
### Stale-While-Revalidate
`@push.rocks/webrequest` supports querying multiple endpoints with fallbacks to handle the situation where some endpoints may fail or be unavailable:
Return cached data immediately, update in background.
```typescript
// Attempt to request from multiple endpoints
async function requestFromMultipleEndpoints() {
const endpoints = [
'https://api.primary-example.com/data',
'https://api.backup-example.com/data',
];
try {
const response = await webRequest.requestMultiEndpoint(endpoints, {
method: 'GET',
});
const data = await response.json();
console.log(data);
} catch (error) {
console.error('Failed to retrieve data from any endpoint', error);
}
}
requestFromMultipleEndpoints();
const data = await webrequest.getJson('https://api.example.com/data', {
cacheStrategy: 'stale-while-revalidate'
});
```
### Advanced Usage
For advanced scenarios, you can directly use the `request` method to fully customize the request options including headers, request method, and body (for POST/PUT requests):
### Network-Only and Cache-Only
```typescript
// Custom request with timeout
async function customRequest() {
const url = 'https://api.example.com/advanced';
try {
const response = await webRequest.request(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ custom: 'data' }),
timeoutMs: 10000, // Timeout in milliseconds
});
if (response.ok) {
const result = await response.json();
console.log(result);
} else {
console.error('Response error:', response.status);
// Always fetch from network, never cache
const data = await webrequest.getJson(url, {
cacheStrategy: 'network-only'
});
// Only use cache, never fetch from network
const data = await webrequest.getJson(url, {
cacheStrategy: 'cache-only'
});
```
### HTTP Header-Based Caching
The library automatically respects HTTP caching headers:
```typescript
// Server returns: Cache-Control: max-age=3600, ETag: "abc123"
const response = await webrequest('https://api.example.com/data', {
cacheStrategy: 'network-first'
});
// Subsequent requests automatically send:
// If-None-Match: "abc123"
// Server returns 304 Not Modified - cache is used
```
### Custom Cache Keys
```typescript
const response = await webrequest('https://api.example.com/search?q=test', {
cacheStrategy: 'cache-first',
cacheKey: (request) => {
const url = new URL(request.url);
return `search:${url.searchParams.get('q')}`;
}
} catch (error) {
});
```
## Retry Strategies
### Basic Retry
```typescript
const response = await webrequest('https://api.example.com/data', {
retry: true // Uses defaults: 3 attempts, exponential backoff
});
```
### Advanced Retry Configuration
```typescript
const response = await webrequest('https://api.example.com/data', {
retry: {
maxAttempts: 5,
backoff: 'exponential', // or 'linear', 'constant'
initialDelay: 1000, // 1 second
maxDelay: 30000, // 30 seconds
retryOn: [408, 429, 500, 502, 503, 504], // Status codes to retry
onRetry: (attempt, error, nextDelay) => {
console.log(`Retry attempt ${attempt}, waiting ${nextDelay}ms`);
}
}
});
```
### Multi-Endpoint Fallback
```typescript
const response = await webrequest('https://api1.example.com/data', {
fallbackUrls: [
'https://api2.example.com/data',
'https://api3.example.com/data'
],
retry: {
maxAttempts: 3,
backoff: 'exponential'
}
});
```
## Request/Response Interceptors
### Global Interceptors
```typescript
import { webrequest } from '@push.rocks/webrequest';
// Add authentication to all requests
webrequest.addRequestInterceptor((request) => {
const headers = new Headers(request.headers);
headers.set('Authorization', `Bearer ${getToken()}`);
return new Request(request, { headers });
});
// Log all responses
webrequest.addResponseInterceptor((response) => {
console.log(`${response.status} ${response.url}`);
return response;
});
// Handle errors globally
webrequest.addErrorInterceptor((error) => {
console.error('Request failed:', error);
throw error;
});
```
### Per-Request Interceptors
```typescript
const response = await webrequest('https://api.example.com/data', {
interceptors: {
request: [(req) => {
console.log('Sending:', req.url);
return req;
}],
response: [(res) => {
console.log('Received:', res.status);
return res;
}],
error: [(err) => {
console.error('Error:', err);
throw err;
}]
}
});
```
## Request Deduplication
Automatically prevent duplicate simultaneous requests:
```typescript
// Only one actual network request is made
const [res1, res2, res3] = await Promise.all([
webrequest('https://api.example.com/data', { deduplicate: true }),
webrequest('https://api.example.com/data', { deduplicate: true }),
webrequest('https://api.example.com/data', { deduplicate: true }),
]);
// All three get the same response
```
## Client API with Default Options
For more control, use `WebrequestClient` to set default options:
```typescript
import { WebrequestClient } from '@push.rocks/webrequest';
const apiClient = new WebrequestClient({
logging: true,
timeout: 30000,
cacheStrategy: 'network-first',
retry: {
maxAttempts: 3,
backoff: 'exponential'
}
});
// Add global interceptors to this client
apiClient.addRequestInterceptor((request) => {
const headers = new Headers(request.headers);
headers.set('X-API-Key', process.env.API_KEY);
return new Request(request, { headers });
});
// All requests through this client use the configured defaults
const data = await apiClient.getJson('https://api.example.com/data');
// Standard fetch-compatible API also available
const response = await apiClient.request('https://api.example.com/data');
```
## Advanced Features
### Timeout
```typescript
const response = await webrequest('https://api.example.com/data', {
timeout: 5000 // 5 seconds
});
```
### Custom Headers
```typescript
const response = await webrequest('https://api.example.com/data', {
headers: {
'Authorization': 'Bearer token123',
'X-Custom-Header': 'value'
}
});
```
### Cache Management
```typescript
// Clear all cached responses
await webrequest.clearCache();
// Clear specific cache entry
await webrequest.clearCache('https://api.example.com/data');
```
## TypeScript Support
Full TypeScript support with generics for type-safe responses:
```typescript
interface ApiResponse<T> {
data: T;
status: 'success' | 'error';
message?: string;
}
interface User {
id: number;
name: string;
email: string;
}
// Fully typed response
const response = await webrequest.getJson<ApiResponse<User>>(
'https://api.example.com/user/1'
);
// response.data.id, response.data.name, response.data.email are all typed
```
## API Reference
### Main Function
```typescript
webrequest(input: string | Request | URL, options?: IWebrequestOptions): Promise<Response>
```
### Convenience Methods
```typescript
webrequest.getJson<T>(url: string, options?: IWebrequestOptions): Promise<T>
webrequest.postJson<T>(url: string, body: any, options?: IWebrequestOptions): Promise<T>
webrequest.putJson<T>(url: string, body: any, options?: IWebrequestOptions): Promise<T>
webrequest.patchJson<T>(url: string, body: any, options?: IWebrequestOptions): Promise<T>
webrequest.deleteJson<T>(url: string, options?: IWebrequestOptions): Promise<T>
```
### Global Methods
```typescript
webrequest.addRequestInterceptor(interceptor: TRequestInterceptor): void
webrequest.addResponseInterceptor(interceptor: TResponseInterceptor): void
webrequest.addErrorInterceptor(interceptor: TErrorInterceptor): void
webrequest.clearCache(url?: string): Promise<void>
```
### Options Interface
```typescript
interface IWebrequestOptions extends Omit<RequestInit, 'cache'> {
// Standard fetch options
method?: string;
headers?: HeadersInit;
body?: BodyInit;
// Enhanced options
cache?: 'default' | 'no-store' | 'reload' | 'no-cache' | 'force-cache' | 'only-if-cached';
cacheStrategy?: 'network-first' | 'cache-first' | 'stale-while-revalidate' | 'network-only' | 'cache-only';
cacheMaxAge?: number; // milliseconds
cacheKey?: (request: Request) => string;
retry?: boolean | IRetryOptions;
fallbackUrls?: string[];
timeout?: number; // milliseconds
interceptors?: {
request?: TRequestInterceptor[];
response?: TResponseInterceptor[];
error?: TErrorInterceptor[];
};
deduplicate?: boolean;
logging?: boolean;
}
```
## Migration from v3
Version 4.0 is a **complete rewrite** of `@push.rocks/webrequest` with breaking changes. **The v3 API has been completely removed** - all v3 code must be migrated to v4.
### What's New in v4
- **Fetch-Compatible API**: Drop-in replacement for native `fetch()` with enhanced features
- **Intelligent HTTP Caching**: Respects `Cache-Control`, `ETag`, `Last-Modified`, and `Expires` headers (RFC 7234)
- **Multiple Cache Strategies**: network-first, cache-first, stale-while-revalidate, network-only, cache-only
- **Advanced Retry System**: Configurable retry with exponential/linear/constant backoff
- **Request/Response Interceptors**: Middleware pattern for transforming requests and responses
- **Request Deduplication**: Automatically deduplicate simultaneous identical requests
- **TypeScript Generics**: Type-safe response parsing with `webrequest.getJson<T>()`
- **Better Fault Tolerance**: Enhanced multi-endpoint fallback with retry strategies
### Breaking Changes
1. **Removed `WebRequest` class** - Use `webrequest` function or `WebrequestClient` class instead
2. **Cache API changed** - Boolean `useCache` replaced with explicit `cacheStrategy` options
3. **Multi-endpoint API changed** - `requestMultiEndpoint()` replaced with `fallbackUrls` option
### Migration Examples
#### Basic Fetch-Compatible Usage
```typescript
// v3
import { WebRequest } from '@push.rocks/webrequest';
const client = new WebRequest();
const response = await client.request('https://api.example.com/data', {
method: 'GET'
});
const data = await response.json();
// v4 - Fetch-compatible
import { webrequest } from '@push.rocks/webrequest';
const response = await webrequest('https://api.example.com/data');
const data = await response.json();
```
#### JSON Convenience Methods
```typescript
// v3
const client = new WebRequest();
const data = await client.getJson('https://api.example.com/data', true);
// v4 - Function API
import { webrequest } from '@push.rocks/webrequest';
const data = await webrequest.getJson('https://api.example.com/data', {
cacheStrategy: 'cache-first'
});
// v4 - Client API (similar to v3)
import { WebrequestClient } from '@push.rocks/webrequest';
const client = new WebrequestClient({ logging: true });
const data = await client.getJson('https://api.example.com/data', {
cacheStrategy: 'cache-first'
});
```
#### Caching
```typescript
// v3 - Boolean flag
const data = await client.getJson(url, true); // useCache = true
// v4 - Explicit strategies
const data = await webrequest.getJson(url, {
cacheStrategy: 'cache-first',
cacheMaxAge: 60000 // 60 seconds
});
// v4 - HTTP header-based caching (automatic)
const data = await webrequest.getJson(url, {
cacheStrategy: 'network-first' // Respects Cache-Control headers
});
```
#### Multi-Endpoint Fallback
```typescript
// v3
const client = new WebRequest();
const response = await client.requestMultiEndpoint(
['https://api1.example.com/data', 'https://api2.example.com/data'],
{ method: 'GET' }
);
// v4
import { webrequest } from '@push.rocks/webrequest';
const response = await webrequest('https://api1.example.com/data', {
fallbackUrls: ['https://api2.example.com/data'],
retry: {
maxAttempts: 3,
backoff: 'exponential'
}
});
```
#### Timeout
```typescript
// v3
const response = await client.request(url, {
method: 'GET',
timeoutMs: 30000
});
// v4
const response = await webrequest(url, {
timeout: 30000 // milliseconds
});
```
## Examples
### Complete Example with All Features
```typescript
import { webrequest } from '@push.rocks/webrequest';
async function fetchUserData(userId: string) {
interface User {
id: string;
name: string;
email: string;
}
const user = await webrequest.getJson<User>(
`https://api.example.com/users/${userId}`,
{
// Caching
cacheStrategy: 'stale-while-revalidate',
cacheMaxAge: 300000, // 5 minutes
// Retry
retry: {
maxAttempts: 3,
backoff: 'exponential',
retryOn: [500, 502, 503, 504]
},
// Fallback
fallbackUrls: [
'https://api-backup.example.com/users/${userId}'
],
// Timeout
timeout: 10000, // 10 seconds
// Deduplication
deduplicate: true,
// Per-request interceptor
interceptors: {
request: [(req) => {
console.log(`Fetching user ${userId}`);
return req;
}]
}
}
);
return user;
}
```
### Building a Typed API Client
```typescript
import { WebrequestClient } from '@push.rocks/webrequest';
class ApiClient {
private client: WebrequestClient;
constructor(private baseUrl: string, private apiKey: string) {
this.client = new WebrequestClient({
timeout: 30000,
cacheStrategy: 'network-first',
retry: {
maxAttempts: 3,
backoff: 'exponential'
}
});
// Add auth interceptor
this.client.addRequestInterceptor((request) => {
const headers = new Headers(request.headers);
headers.set('Authorization', `Bearer ${this.apiKey}`);
headers.set('Content-Type', 'application/json');
return new Request(request, { headers });
});
}
async getUser(id: string): Promise<User> {
return this.client.getJson<User>(`${this.baseUrl}/users/${id}`);
}
async createUser(data: CreateUserData): Promise<User> {
return this.client.postJson<User>(`${this.baseUrl}/users`, data);
}
async updateUser(id: string, data: UpdateUserData): Promise<User> {
return this.client.putJson<User>(`${this.baseUrl}/users/${id}`, data);
}
async deleteUser(id: string): Promise<void> {
await this.client.deleteJson(`${this.baseUrl}/users/${id}`);
}
}
customRequest();
// Usage
const api = new ApiClient('https://api.example.com', process.env.API_KEY);
const user = await api.getUser('123');
```
### Conclusion
`@push.rocks/webrequest` offers a streamlined, secure way to handle web requests from browsers, supporting various HTTP methods, response caching, and requests to multiple endpoints with fault tolerance. Its TypeScript integration ensures type safety and enhances developer productivity by enabling IntelliSense in supported IDEs.
## License and Legal Information
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.

5
test/test.ts
View File

@@ -16,7 +16,7 @@ tap.test('setup test server', async () => {
testServer.addRoute(
'/apiroute1',
new typedserver.servertools.Handler('GET', (req, res) => {
res.status(429);
res.status(500);
res.end();
}),
);
@@ -48,7 +48,6 @@ tap.test('should handle fallback URLs', async () => {
{
fallbackUrls: [
'http://localhost:2345/apiroute2',
'http://localhost:2345/apiroute4',
'http://localhost:2345/apiroute3',
],
retry: {
@@ -59,6 +58,8 @@ tap.test('should handle fallback URLs', async () => {
}
);
expect(response.ok).toEqual(true);
expect(response.status).toEqual(200);
const data = await response.json();
console.log('response with fallbacks: ' + JSON.stringify(data));
expect(data).toHaveProperty('hithere');

40
test/test.v4.node.ts
View File

@@ -48,6 +48,25 @@ tap.test('setup test server for v4 tests', async () => {
}),
);
// Route that always fails with 500 (for fallback testing)
testServer.addRoute(
'/always-fails',
new typedserver.servertools.Handler('GET', (req, res) => {
res.status(500);
res.end();
}),
);
// Route that takes a long time to respond (for timeout testing)
testServer.addRoute(
'/slow',
new typedserver.servertools.Handler('GET', async (req, res) => {
await new Promise((resolve) => setTimeout(resolve, 5000));
res.status(200);
res.send({ data: 'slow response' });
}),
);
// Route that returns 304 when ETag matches
testServer.addRoute(
'/conditional',
@@ -162,7 +181,7 @@ tap.test('should retry failed requests', async () => {
// Test 7: Fallback URLs
tap.test('should support fallback URLs', async () => {
const response = await webrequest('http://localhost:2346/nonexistent', {
const response = await webrequest('http://localhost:2346/always-fails', {
fallbackUrls: ['http://localhost:2346/dynamic'],
retry: {
maxAttempts: 2
@@ -251,8 +270,8 @@ tap.test('should deduplicate simultaneous requests', async () => {
// Test 12: Timeout
tap.test('should support timeout', async () => {
try {
await webrequest('http://localhost:2346/dynamic', {
timeout: 1 // 1ms timeout should fail
await webrequest('http://localhost:2346/slow', {
timeout: 100 // 100ms timeout should fail (route takes 5000ms)
});
throw new Error('Should have timed out');
} catch (error) {
@@ -289,21 +308,6 @@ tap.test('should clear cache', async () => {
expect(response.ok).toEqual(true);
});
// Test 15: Backward compatibility with WebRequest class
tap.test('should maintain backward compatibility with v3 API', async () => {
const { WebRequest } = await import('../ts/index.js');
const client = new WebRequest({ logging: false });
const data = await client.getJson('http://localhost:2346/dynamic');
expect(data).toHaveProperty('data');
// Test POST
const postData = await client.postJson('http://localhost:2346/post', {
test: 'data'
});
expect(postData).toHaveProperty('received');
});
// Cleanup
tap.test('stop test server', async () => {
await testServer.stop();

9
ts/00_commitinfo_data.ts
View File

@@ -1,9 +1,8 @@
/**
* autocreated commitinfo by @pushrocks/commitinfo
* autocreated commitinfo by @push.rocks/commitinfo
*/
export const commitinfo = {
name: '@push.rocks/webrequest',
version: '3.0.37',
description:
'A module for making secure web requests from browsers with support for caching and fault tolerance.',
};
version: '4.0.1',
description: 'Modern, fetch-compatible web request library with intelligent HTTP caching, retry strategies, and fault tolerance.'
}