v6.0.0

Major Changes

• b668b30 Thanks @enisdenjo! - @fastify/websocket WebSocket in the context extra has been renamed from connection to socket

  Migrating from v5 to v6

  import { makeHandler } from 'graphql-ws/use/@fastify/websocket';
  
  makeHandler({
    schema(ctx) {
  -   const websocket = ctx.extra.connection;
  +   const websocket = ctx.extra.socket;
    },
    context(ctx) {
  -   const websocket = ctx.extra.connection;
  +   const websocket = ctx.extra.socket;
    },
    onConnect(ctx) {
  -   const websocket = ctx.extra.connection;
  +   const websocket = ctx.extra.socket;
    },
    onDisconnect(ctx) {
  -   const websocket = ctx.extra.connection;
  +   const websocket = ctx.extra.socket;
    },
    onClose(ctx) {
  -   const websocket = ctx.extra.connection;
  +   const websocket = ctx.extra.socket;
    },
    onSubscribe(ctx) {
  -   const websocket = ctx.extra.connection;
  +   const websocket = ctx.extra.socket;
    },
    onOperation(ctx) {
  -   const websocket = ctx.extra.connection;
  +   const websocket = ctx.extra.socket;
    },
    onError(ctx) {
  -   const websocket = ctx.extra.connection;
  +   const websocket = ctx.extra.socket;
    },
    onNext(ctx) {
  -   const websocket = ctx.extra.connection;
  +   const websocket = ctx.extra.socket;
    },
    onComplete(ctx) {
  -   const websocket = ctx.extra.connection;
  +   const websocket = ctx.extra.socket;
    },
  });

• #613 3f11aba Thanks @enisdenjo! - Drop support for ws v7

  ws v7 has been deprecated. Please upgrade and use v8.

• #613 3f11aba Thanks @enisdenjo! - Drop support for deprecated fastify-websocket

  fastify-websocket has been deprecated since v4.3.0.. Please upgrade and use @fastify/websocket.

• #613 3f11aba Thanks @enisdenjo! - The /lib/ part from imports has been removed, for example graphql-ws/lib/use/ws becomes graphql-ws/use/ws

  Migrating from v5 to v6

  Simply remove the /lib/ part from your graphql-ws imports that use a handler.

  ws

  - import { useServer } from 'graphql-ws/lib/use/ws';
  + import { useServer } from 'graphql-ws/use/ws';

  uWebSockets.js

  - import { makeBehavior } from 'graphql-ws/lib/use/uWebSockets';
  + import { makeBehavior } from 'graphql-ws/use/uWebSockets';

  @fastify/websocket

  - import { makeHandler } from 'graphql-ws/lib/use/@fastify/websocket';
  + import { makeHandler } from 'graphql-ws/use/@fastify/websocket';

  Bun

  - import { handleProtocols, makeHandler } from 'graphql-ws/lib/use/bun';
  + import { handleProtocols, makeHandler } from 'graphql-ws/use/bun';

  Deno

  - import { makeHandler } from 'https://esm.sh/graphql-ws/lib/use/deno';
  + import { makeHandler } from 'https://esm.sh/graphql-ws/use/deno';

• #613 3f11aba Thanks @enisdenjo! - ErrorMessage uses and onError returns GraphQLFormattedError (instead of GraphQLError)

  Thanks @benjie for working on this in #599

• #613 3f11aba Thanks @enisdenjo! - Least supported Node version is v20

  Node v10 has been deprecated for years now. There is no reason to support it. Bumping the engine to the current LTS (v20) also allows the code to be leaner and use less polyfills.

• #613 3f11aba Thanks @enisdenjo! - Least supported graphql peer dependency is ^15.10.1 and ^16

  Users are advised to use the latest of graphql because of various improvements in performance and security.

• #613 3f11aba Thanks @enisdenjo! - NextMessage uses and onNext returns FormattedExecutionResult (instead of ExecutionResult)

• #613 3f11aba Thanks @enisdenjo! - schema, context, onSubscribe, onOperation, onError, onNext and onComplete hooks don't have the full accompanying message anymore, only the ID and the relevant part from the message

  There is really no need to pass the full SubscribeMessage to the onSubscribe hook. The only relevant parts from the message are the id and the payload, the type is useless since the hook inherently has it (onNext is next type, onError is error type, etc).

  The actual techincal reason for not having the full message is to avoid serialising results and errors twice. Both onNext and onError allow the user to augment the result and return it to be used instead. onNext originally had the NextMessage argument which already has the FormattedExecutionResult, and onError originally had the ErrorMessage argument which already has the GraphQLFormattedError, and they both also returned FormattedExecutionResult and GraphQLFormattedError respectivelly - meaning, if the user serialised the results - the serialisation would happen twice.

  Additionally, the onOperation, onError, onNext and onComplete now have the payload which is the SubscribeMessage.payload (SubscribePayload) for easier access to the original query as well as execution params extensions.

  Migrating from v5 to v6

  schema

  import { ExecutionArgs } from 'graphql';
  import { ServerOptions, SubscribePayload } from 'graphql-ws';
  
  const opts: ServerOptions = {
  - schema(ctx, message, argsWithoutSchema: Omit<ExecutionArgs, 'schema'>) {
  -   const messageId = message.id;
  -   const messagePayload: SubscribePayload = message.payload;
  - },
  + schema(ctx, id, payload) {
  +   const messageId = id;
  +   const messagePayload: SubscribePayload = payload;
  + },
  };

  context

  import { ExecutionArgs } from 'graphql';
  import { ServerOptions, SubscribePayload } from 'graphql-ws';
  
  const opts: ServerOptions = {
  - context(ctx, message, args: ExecutionArgs) {
  -   const messageId = message.id;
  -   const messagePayload: SubscribePayload = message.payload;
  - },
  + context(ctx, id, payload, args: ExecutionArgs) {
  +   const messageId = id;
  +   const messagePayload: SubscribePayload = payload;
  + },
  };

  onSubscribe

  import { ServerOptions, SubscribePayload } from 'graphql-ws';
  
  const opts: ServerOptions = {
  - onSubscribe(ctx, message) {
  -   const messageId = message.id;
  -   const messagePayload: SubscribePayload = message.payload;
  - },
  + onSubscribe(ctx, id, payload) {
  +   const messageId = id;
  +   const messagePayload: SubscribePayload = payload;
  + },
  };

  onOperation

  The SubscribeMessage.payload is not useful here at all, the payload has been parsed to ready-to-use graphql execution args and should be used instead.

  import { ExecutionArgs } from 'graphql';
  import { ServerOptions, SubscribePayload, OperationResult } from 'graphql-ws';
  
  const opts: ServerOptions = {
  - onOperation(ctx, message, args: ExecutionArgs, result: OperationResult) {
  -   const messageId = message.id;
  -   const messagePayload: SubscribePayload = message.payload;
  - },
  + onOperation(ctx, id, payload, args: ExecutionArgs, result: OperationResult) {
  +   const messageId = id;
  +   const messagePayload: SubscribePayload = payload;
  + },
  };

  onError

  The ErrorMessage.payload (GraphQLFormattedError[]) is not useful here at all, the user has access to GraphQLError[] that are true instances of the error containing object references to originalErrors and other properties. The user can always convert and return GraphQLFormattedError[] by using the .toJSON() method.

  import { GraphQLError, GraphQLFormattedError } from 'graphql';
  import { ServerOptions, SubscribePayload } from 'graphql-ws';
  
  const opts: ServerOptions = {
  - onError(ctx, message, errors) {
  -   const messageId = message.id;
  -   const graphqlErrors: readonly GraphQLError[] = errors;
  -   const errorMessagePayload: readonly GraphQLFormattedError[]...

v5.16.2

Patch Changes

• #611 6a5fde1 Thanks @enisdenjo! - No more workspaces

  This version does not contain any code changes.

v5.16.1

Patch Changes

• #607 a629ec7 Thanks @enisdenjo! - Release with changesets

  This version does not contain any code changes.

v5.16.0

5.16.0 (2024-03-27)

Bug Fixes

• server: Return all subscriptions regardless of the return invocation order (f442288)
• server: should not send error messages if socket closes before onSubscribe hooks resolves (db47a66), closes #539

Features

• server: Close code and reason are optional (6ae6e6f), closes #547

v5.15.0

5.15.0 (2024-02-12)

Bug Fixes

• client: Use TerminatedCloseEvent class extending an Error for rejecting promises when terminating (74b4ceb), closes #531
• server: Dispose of subscriptions on close even if added late to the subscriptions list (#534) (e45d6b1), closes #532

Features

• server: Add is retry flag to connect events (#507) (9ad853f)

v5.14.3

5.14.3 (2023-12-20)

Bug Fixes

• client: Use closures instead of bindings (with this) (812129d)
• remove package.json workspaces entry in release (63a831e), closes #524

v5.14.2

5.14.2 (2023-10-23)

Bug Fixes

• client: correct close code for Bad Gateway reason (#512) (0438650)

v5.14.1

5.14.1 (2023-09-28)

Bug Fixes

• server: Acknowledge connection before notifying the client to avoid race conditions with slow sends (#506) (8cb82bd), closes #501

v5.14.0

5.14.0 (2023-06-22)

Features

• client: Async iterator for subscriptions (#486) (fb4b967)

Examples

Use the client

import { createClient } from 'graphql-ws';

const client = createClient({
  url: 'ws://localhost:4000/graphql',
});

// query
(async () => {
  const query = client.iterate({
    query: '{ hello }',
  });

  const { value } = await query.next();
  expect(value).toEqual({ hello: 'world' });
})();

// subscription
(async () => {
  const subscription = client.iterate({
    query: 'subscription { greetings }',
  });

  for await (const event of subscription) {
    expect(event).toEqual({ greetings: 'Hi' });

    // complete a running subscription by breaking the iterator loop
    break;
  }
})();

v5.13.1

5.13.1 (2023-05-15)

Bug Fixes

• Remove unnecessary bun-types directives (e9a56f7), closes #478