fetchT


Type-safe Fetch API wrapper with abortable requests, timeout support, progress tracking, automatic retry, and Rust-like Result error handling.

---

中文 | API Documentation

---

Features

- Abortable Requests - Cancel requests anytime via FetchTask.abort()
- Type-safe Responses - Specify return type with responseType parameter (text, json, arraybuffer, bytes, blob, stream)
- Timeout Support - Auto-abort requests after specified milliseconds
- Progress Tracking - Monitor download progress with onProgress callback
- Chunk Streaming - Access raw data chunks via onChunk callback
- Automatic Retry - Configurable retry strategies with retry option
- Result Error Handling - Rust-like Result type for explicit error handling
- Cross-platform - Works with Deno, Node.js, Bun, and browsers

Installation

``sh


npm

npm install @happy-ts/fetch-t

yarn

yarn add @happy-ts/fetch-t

pnpm

pnpm add @happy-ts/fetch-t

JSR (Deno)

deno add @happy-ts/fetch-t

JSR (Bun)

bunx jsr add @happy-ts/fetch-t
`

Quick Start

$3

`ts
import { fetchT } from '@happy-ts/fetch-t';

// GET JSON data
const result = await fetchT<{ id: number; title: string }>('https://api.example.com/data', {
responseType: 'json',
});

result.inspect(data => {
console.log(data.title);
}).inspectErr(err => {
console.error('Request failed:', err.message);
});
`

$3

`ts
const task = fetchT('https://api.example.com/large-file', {
abortable: true,
responseType: 'arraybuffer',
});

// Abort after 5 seconds
setTimeout(() => {
task.abort('User cancelled');
}, 5000);

const result = await task.result;
`

$3

`ts
const result = await fetchT('https://api.example.com/data', {
retry: {
retries: 3,
delay: (attempt) => Math.min(1000 * Math.pow(2, attempt - 1), 10000),
when: [500, 502, 503, 504],
onRetry: (error, attempt) => console.log(Retry ${attempt}: ${error.message}),
},
responseType: 'json',
});
`

Examples

- Basic - Basic fetch requests
- Progress Tracking - Download progress and chunk streaming
- Abortable - Cancel and timeout requests
- Retry - Automatic retry strategies
- Error Handling - Error handling patterns

Error Handling Design

fetchT distinguishes between two types of errors:

$3

Invalid parameters throw immediately for fail-fast behavior:

`ts
// These throw synchronously - no try/catch around await needed
fetchT('https://example.com', { timeout: -1 }); // Error: timeout must be > 0
fetchT('https://example.com', { timeout: 'bad' }); // TypeError: timeout must be a number
fetchT('not-a-url'); // TypeError: Invalid URL
`

This differs from native fetch, which returns rejected Promises for parameter errors. Synchronous throws provide clearer stack traces and catch bugs during development.

$3

Network failures and HTTP errors are wrapped in Result type:

`ts
const result = await fetchT('https://api.example.com/data', { responseType: 'json' });

if (result.isErr()) {
const error = result.unwrapErr();
// FetchError with status code, or network Error
}
``

License

MIT