graphql-sse

Zero-dependency, HTTP/1 safe, simple, GraphQL over Server-Sent Events Protocol server and client.

Use WebSockets instead? Check out graphql-ws!

Get started

Swiftly start with the get started guide on the website.

Recipes

Short and concise code snippets for starting with common use-cases. Available on the website.

Documentation

Auto-generated by TypeDoc and then rendered on the website.

How does it work?

Read about the exact transport intricacies used by the library in the GraphQL over Server-Sent Events Protocol document.

Want to help?

File a bug, contribute with code, or improve documentation? Read up on our guidelines for contributing and drive development with yarn test --watch away!

2.5.4 (2025-01-10)

Bug Fixes

• client: Conversion to async iterable from Response.body (#114) (f2adc92)

2.5.3 (2024-03-27)

Bug Fixes

• use/fastify: Include middleware headers (134c1b0), closes #91

2.5.2 (2023-12-20)

Bug Fixes

• remove package.json workspaces entry in release (c6dc093)

2.5.1 (2023-12-14)

Bug Fixes

• use/koa: Use parsed body from request (#87) (b290b90)

2.5.0 (2023-12-13)

Features

• use/koa: expose full Koa context to options (#86) (b37a6f9)

2.4.1 (2023-12-13)

Bug Fixes

• Add koa exports to package.json (#85) (e99cf99)

2.4.0 (2023-11-29)

Bug Fixes

• client: Use closures instead of bindings (with this) (8ecdf3c)

Features

• client: Event listeners for both operation modes (#84) (6274f44)

2.3.0 (2023-09-07)

Features

• handler: Use Koa (#80) (283b453), closes #78

2.2.3 (2023-08-23)

Bug Fixes

• use/http,use/http2,use/express,use/fastify: Check writable instead of closed before writing to response (3c71f69), closes #69

2.2.2 (2023-08-22)

Bug Fixes

• use/http,use/http2,use/express,use/fastify: Handle cases where response's close event is late (#75) (4457cba), closes #69

2.2.1 (2023-07-31)

Bug Fixes

• handler: Always include the data field in stream messages (#71) (4643c9a)

2.2.0 (2023-06-22)

Features

• client: Async iterator for subscriptions (#66) (fb8bf11)

2.1.4 (2023-06-12)

Bug Fixes

• Request parameters query field can only be a string (16c9600), closes #65

2.1.3 (2023-05-15)

Bug Fixes

• client: Respect retry attempts when server goes away after connecting in single connection mode (#59) (e895c5b), closes #55
• handler: Detect ExecutionArgs in onSubscribe return value (a16b921), closes #58

2.1.2 (2023-05-10)

Bug Fixes

• client: Respect retry attempts when server goes away after connecting (#57) (75c9f17), closes #55

Reverts

• Revert "Revert "docs: website (#50)"" (0e4f4b5), closes #50

2.1.1 (2023-03-31)

Bug Fixes

• Add file extensions to imports/exports in ESM type definitions (bbf23b1)

2.1.0 (2023-02-17)

Bug Fixes

• use/express,use/fastify: Resolve body if previously parsed (6573e94)

Features

• handler: Export handler options type for each integration (2a2e517)

2.0.0 (2022-12-20)

Features

• handler: Server and environment agnostic handler (#37) (22cf03d)

BREAKING CHANGES

• handler: The handler is now server agnostic and can run anywhere

• Core of graphql-sse is now server agnostic and as such offers a handler that implements a generic request/response model

• Handler does not await for whole operation to complete anymore. Only the processing part (parsing, validating and executing)
• GraphQL context is now typed
• Hook arguments have been changed, they're not providing the Node native req/res anymore - they instead provide the generic request/response
• onSubscribe hook can now return an execution result too (useful for caching for example)
• Throwing in onNext and onComplete hooks will bubble the error to the returned iterator

Migration

Even though the core of graphql-sse is now completely server agnostic, there are adapters to ease the integration with existing solutions. Migrating is actually not a headache!

Beware that the adapters don't handle internal errors, it's your responsibility to take care of that and behave accordingly.

http

import http from 'http';
- import { createHandler } from 'graphql-sse';
+ import { createHandler } from 'graphql-sse/lib/use/http';

// Create the GraphQL over SSE handler
const handler = createHandler({ schema });

// Create an HTTP server using the handler on `/graphql/stream`
const server = http.createServer((req, res) => {
  if (req.url.startsWith('/graphql/stream')) {
    return handler(req, res);
  }
  res.writeHead(404).end();
});

server.listen(4000);
console.log('Listening to port 4000');

http2

import fs from 'fs';
import http2 from 'http2';
- import { createHandler } from 'graphql-sse';
+ import { createHandler } from 'graphql-sse/lib/use/http2';

// Create the GraphQL over SSE handler
const handler = createHandler({ schema });

// Create an HTTP server using the handler on `/graphql/stream`
const server = http.createServer((req, res) => {
  if (req.url.startsWith('/graphql/stream')) {
    return handler(req, res);
  }
  res.writeHead(404).end();
});

server.listen(4000);
console.log('Listening to port 4000');

express

import express from 'express'; // yarn add express
- import { createHandler } from 'graphql-sse';
+ import { createHandler } from 'graphql-sse/lib/use/express';

// Create the GraphQL over SSE handler
const handler = createHandler({ schema });

// Create an express app
const app = express();

// Serve all methods on `/graphql/stream`
app.use('/graphql/stream', handler);

server.listen(4000);
console.log('Listening to port 4000');

fastify

import Fastify from 'fastify'; // yarn add fastify
- import { createHandler } from 'graphql-sse';
+ import { createHandler } from 'graphql-sse/lib/use/fastify';

// Create the GraphQL over SSE handler
const handler = createHandler({ schema });

// Create a fastify app
const fastify = Fastify();

// Serve all methods on `/graphql/stream`
fastify.all('/graphql/stream', handler);

fastify.listen({ port: 4000 });
console.log('Listening to port 4000');

1.3.2 (2022-12-06)

Bug Fixes

• handler: Correct typings and support for http2 (08d6ca3), closes #38

1.3.1 (2022-12-05)

Bug Fixes

• client: Abort request when reporting error (91057bd)
• client: Operation requests are of application/json content-type (0084de7)

1.3.0 (2022-07-20)

Features

• client: Accept referrer and referrerPolicy fetch options (#32) (dbaa90a)

1.2.5 (2022-07-17)

Bug Fixes

• client: Leverage active streams for reliable network error retries (607b468)

1.2.4 (2022-07-01)

Bug Fixes

• Add types path to package.json exports (44f95b6)

1.2.3 (2022-06-13)

Bug Fixes

• client: Retry if connection is closed while having active streams (83a0178), closes #28

1.2.2 (2022-06-09)

Bug Fixes

• client: Network errors during event emission contain the keyword "stream" in Firefox (054f16b)

1.2.1 (2022-06-09)

Bug Fixes

• client: Retry network errors even if they occur during event emission (489b1b0), closes #27

Performance Improvements

• client: Avoid recreating result variables when reading the response stream (16f6a6c)

1.2.0 (2022-04-14)

Bug Fixes

• client: TypeScript generic for ensuring proper arguments when using "single connection mode" (be2ae7d)

Features

• client: Inspect incoming messages through ClientOptions.onMessage (496e74b), closes #20

1.1.0 (2022-03-09)

Features

• client: Add credentials property for requests (79d0266)
• client: Add lazyCloseTimeout as a close timeout after last operation completes (16e5e31), closes #17

1.0.6 (2021-11-18)

Bug Fixes

• client: Avoid bundling DOM types, have the implementor supply his own Response type (98780c0)
• handler: Support generics for requests and responses (9ab10c0)

1.0.5 (2021-11-02)

Bug Fixes

• client: Should not call complete after subscription error (d8b7634)
• handler: Use 3rd body argument only if is object or string (2062579)

1.0.4 (2021-09-08)

Bug Fixes

• Define graphql execution results (89da803)
• server: Operation result can be async generator or iterable (24b6078)

1.0.3 (2021-08-26)

Bug Fixes

• Bump graphql version to v16 in package.json (af219f9)

1.0.2 (2021-08-26)

Bug Fixes

• Add support for graphql@v16 (89367f2)

1.0.1 (2021-08-23)

Bug Fixes

• Prefer X-GraphQL-Event-Stream-Token header name for clarity (9aaa0a9)

1.0.0 (2021-08-21)

Features

• Client (#3) (754487d)
• Server request handler (#2) (8381796)