https://github.com/wutility/stretto
🔥 zero-dependency TypeScript library for streaming HTTP requests with support for Server-Sent Events (SSE), NDJSON, and custom data format
https://github.com/wutility/stretto
deno event-sourcing fecth-api nodejs openai-api server-sent-events sse sse-client streaming-data streams
Last synced: 2 months ago
JSON representation
🔥 zero-dependency TypeScript library for streaming HTTP requests with support for Server-Sent Events (SSE), NDJSON, and custom data format
- Host: GitHub
- URL: https://github.com/wutility/stretto
- Owner: wutility
- License: mit
- Created: 2025-08-23T00:49:09.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-23T01:09:04.000Z (10 months ago)
- Last Synced: 2025-08-23T03:33:14.720Z (10 months ago)
- Topics: deno, event-sourcing, fecth-api, nodejs, openai-api, server-sent-events, sse, sse-client, streaming-data, streams
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/stretto
- Size: 12.7 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Stretto 🚀
A robust, high-performance TypeScript fetch wrapper with built-in retry logic, exponential backoff, streaming capabilities, and Server-Sent Events (SSE) support.
- Memory Efficiency: Zero-copy streaming and buffer reuse keep memory usage low.
- Minimal Allocations: Optimized hot paths reduce overhead.
- Buffer Overflow Protection: Configurable limits prevent memory exhaustion attacks.
- Data Security: Internal buffers are zeroed out to avoid leaks in memory dumps.
## 📦 Installation
```shell
# npm
npm install stretto
# Deno
deno add jsr:@wutility/stretto
```
Or use the CDN:
```html
```
## 🚀 Quick Start
### Basic Usage
```typescript
import stretto from 'stretto';
// jsr
// import stretto, { JSONStreamTransformer } from "jsr:@wutility/stretto";
// Simple GET request
const response = await stretto('https://jsonplaceholder.typicode.com/todos/1');
const data = await response.json();
```
### With Options
```typescript
const response = await stretto('https://api.example.com/data', {
retries: 5,
timeout: 10000,
headers: {'Authorization': 'Bearer token'}
});
```
### Streaming Responses
```typescript
const response = await stretto('https://stream.wikimedia.org/v2/stream/recentchange', {
stream: true
});
// Use as AsyncIterable
for await (const chunk of response) {
console.log('Received chunk:', chunk);
}
```
### Server-Sent Events (SSE)
```typescript
import stretto, { JSONStreamTransformer } from 'stretto';
const response = await stretto('https://sse.dev/test', {
stream: true,
transformers: [new JSONStreamTransformer()]
});
for await (const event of response) {
console.log('SSE Event:', event);
}
```
## 📖 API Reference
### `stretto(url, options?)`
Main function for making HTTP requests.
**Parameters:**
- `url: string | URL` - The URL to fetch
- `options?: StrettoOptions` - Configuration options
**Returns:** `Promise>`
### StrettoOptions
```typescript
interface StrettoOptions extends Omit {
retries?: number; // Default: 3
timeout?: number; // Default: 30000ms
backoffStrategy?: (attempt: number) => number;
retryOn?: (error: unknown, response?: Response) => boolean;
stream?: boolean; // Default: false
transformers?: TransformStream[];
signal?: AbortSignal;
}
```
### JSONStreamTransformer
A specialized transformer for parsing Server-Sent Events with JSON payloads.
```typescript
import { JSONStreamTransformer } from 'stretto';
const transformer = new JSONStreamTransformer({
maxBuffer: 8192, // Maximum line buffer size
parseData: true, // Parse JSON automatically
donePrefix: '[DONE]', // Custom termination marker
onBufferOverflow: 'skip', // 'skip' | 'throw'
onParseError: 'skip' // 'skip' | 'throw'
});
```
## 🔧 Advanced Usage
### Custom Retry Strategy
```typescript
const response = await stretto('https://api.example.com/data', {
retries: 5,
retryOn: (error, response) => {
// Custom retry logic
if (response?.status === 429) return true; // Rate limited
if (error instanceof TypeError) return true; // Network error
return false;
},
backoffStrategy: (attempt) => {
// Custom backoff: linear instead of exponential
return attempt * 1000;
}
});
```
### Request Cancellation
```typescript
const controller = new AbortController();
// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);
try {
const response = await stretto('https://api.example.com/data', {
signal: controller.signal
});
} catch (error) {
if (error.name === 'AbortError') {
console.log('Request was cancelled');
}
}
```
### Multiple Transform Streams
```typescript
import stretto, { JSONStreamTransformer } from 'stretto';
const response = await stretto('https://sse.dev/test', {
stream: true,
transformers: [new JSONStreamTransformer()]
});
for await (const chunk of stream) {}
```
## 📊 Performance Features
- **Zero-copy streaming**: No unnecessary data copying during stream processing
- **Optimized backoff**: Uses bitwise operations for fast exponential calculations
- **Memory efficient**: Reuses buffers and minimizes allocations
- **V8 optimized**: Takes advantage of JavaScript engine optimizations
## 🧪 Testing
```bash
npm test
```
## 🤝 Contributing
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
## 📄 License
MIT License - see the [LICENSE](LICENSE) file for details.