asyncsse
v1.3.2
Published
Fetch Server-Sent Events (SSE) as an async iterable
Downloads
36
Maintainers
Readme
asyncSSE
Fetch Server-Sent Events (SSE) as an async iterable.
Features
- 🚀 Lightweight (<1KB) and dependency-free
- 🔄 Works with any SSE-compatible API
- 🌐 Browser and Node.js compatible
- 📦 Easy to use with ES modules
Installation
npm install asyncsse
Usage
Browser (via CDN)
<script type="module">
import { asyncSSE } from "https://cdn.jsdelivr.net/npm/asyncsse@1";
// Example usage
(async () => {
for await (const event of asyncSSE("https://api.example.com/sse")) {
console.log(event);
}
})();
</script>
Node.js or bundled projects
import { asyncSSE } from "asyncsse";
// Example usage
(async () => {
for await (const event of asyncSSE("https://api.example.com/sse")) {
console.log(event);
}
})();
API
asyncSSE(url: string, options?: RequestInit, config?: SSEConfig): AsyncIterable<SSEEvent>
Fetches Server-Sent Events from the specified URL and returns an async iterable.
url
: The URL to fetch SSE fromoptions
: Optional fetch optionsconfig
: Optional configuration objectfetch
: Custom fetch implementation (defaults to global fetch)onResponse
: Async callback to inspect or modify the Response before streaming begins
Returns an async iterable that yields SSEEvent
objects.
Example: OpenAI Chat Completions
import { asyncSSE } from "asyncsse";
const apiKey = "YOUR_OPENAI_API_KEY";
const url = "https://api.openai.com/v1/chat/completions";
const options = {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${apiKey}`,
},
body: JSON.stringify({
model: "gpt-4",
stream: true,
messages: [{ role: "user", content: "Hello, world!" }],
}),
};
const config = {
onResponse: async (response) => {
console.log("Requests remaining:", response.headers.get("X-Ratelimit-Remaining-Requests"));
},
};
// Fetch the stream, event by event
for await (const event of asyncSSE(url, options, config)) {
console.log(JSON.parse(event.data));
}
Testing with Text Input
You can directly stream SSE events from a text string using the provided fetchText
helper:
import { asyncSSE } from "https://cdn.jsdelivr.net/npm/asyncsse@1";
import { fetchText } from "https://cdn.jsdelivr.net/npm/asyncsse@1/dist/fetchtext.js";
const text = "data: Hello\n\ndata: World\n\n";
// Stream events from text
for await (const event of asyncSSE(text, {}, { fetch: fetchText })) {
console.log(event);
}
This outputs:
{ data: "Hello" }
{ data: "World" }
This is particularly useful for testing SSE parsing without making actual HTTP requests.
Changelog
- 1.3.2: Update repo links
- 1.3.1: Add
fetchText
helper for mocking SSE responses. Add source maps and TypeScript - 1.2.1: Add
config.fetch
parameter for custom fetch implementations - 1.1.0: Add
config.onResponse
callback - 1.0.0: Initial release
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License - see the LICENSE file for details.