or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client.mdcommon.mdindex.mdserver-adapters.mdserver.md
tile.json

index.mddocs/

GraphQL-WS

GraphQL-WS is a comprehensive GraphQL over WebSocket implementation that enables real-time GraphQL subscriptions, queries, and mutations over WebSocket connections. It provides both client and server implementations that are fully compliant with the GraphQL over WebSocket Protocol, featuring zero dependencies, lazy connection handling, and simple integration patterns.

Package Information

  • Package Name: graphql-ws
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install graphql-ws

Core Imports

import { createClient, makeServer } from "graphql-ws";

For client-only usage:

import { createClient } from "graphql-ws/client";

CommonJS:

const { createClient, makeServer } = require("graphql-ws");

Basic Usage

Client Usage

import { createClient } from "graphql-ws";

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

// Subscribe to a GraphQL subscription
const unsubscribe = client.subscribe(
  {
    query: "subscription { messageAdded { id content } }",
  },
  {
    next: (data) => console.log("Received:", data),
    error: (err) => console.error("Error:", err),
    complete: () => console.log("Subscription completed"),
  }
);

// Later, unsubscribe
unsubscribe();

Server Usage

import { makeServer } from "graphql-ws";
import { WebSocketServer } from "ws";

const server = makeServer({
  schema, // Your GraphQL schema
});

const wsServer = new WebSocketServer({ port: 4000, path: "/graphql" });
wsServer.on("connection", (socket, request) => {
  const closed = server.opened(socket, { socket, request });
  socket.once("close", closed);
});

Architecture

GraphQL-WS is designed around several key components:

  • Protocol Compliance: Full implementation of the GraphQL over WebSocket Protocol
  • Client Implementation: Feature-rich WebSocket client with connection management, retries, and event handling
  • Server Implementation: Flexible server with customizable hooks and execution control
  • Multi-Runtime Support: Adapters for different WebSocket server implementations (ws, uWebSockets.js, Fastify, Bun, crossws, Deno)
  • Type Safety: Complete TypeScript support with generic type preservation
  • Zero Dependencies: No external dependencies for core functionality

Capabilities

Client API

Core client functionality for establishing WebSocket connections and managing GraphQL subscriptions with comprehensive configuration options.

function createClient<P = Record<string, unknown>>(
  options: ClientOptions<P>
): Client;

interface Client extends Disposable {
  on<E extends Event>(event: E, listener: EventListener<E>): () => void;
  subscribe<Data = Record<string, unknown>, Extensions = unknown>(
    payload: SubscribePayload,
    sink: Sink<FormattedExecutionResult<Data, Extensions>>
  ): () => void;
  iterate<Data = Record<string, unknown>, Extensions = unknown>(
    payload: SubscribePayload
  ): AsyncIterableIterator<FormattedExecutionResult<Data, Extensions>>;
  terminate(): void;
}

Client API

Server API

Server-side GraphQL over WebSocket implementation with extensive customization hooks and execution control.

function makeServer<P = Record<string, unknown>, E = unknown>(
  options: ServerOptions<P, E>
): Server<E>;

interface Server<E = unknown> {
  opened(
    socket: WebSocket,
    ctxExtra: E
  ): (code?: number, reason?: string) => Promise<void>;
}

Server API

Server Adapters

Specialized adapters for integrating with different WebSocket server implementations across multiple JavaScript runtimes.

// ws adapter
function useServer<P = Record<string, unknown>, E = unknown>(
  options: ServerOptions<P, Extra & Partial<E>>,
  ws: WebSocketServer,
  keepAlive?: number
): Disposable;

// uWebSockets.js adapter
function makeBehavior<P = Record<string, unknown>, E = unknown>(
  options: ServerOptions<P, Extra & Partial<E>>,
  behavior?: uWS.WebSocketBehavior<unknown>,
  keepAlive?: number
): uWS.WebSocketBehavior<unknown>;

Server Adapters

Common Types & Protocol

Shared types, constants, and utilities used by both client and server implementations, including the complete GraphQL over WebSocket Protocol message types.

const GRAPHQL_TRANSPORT_WS_PROTOCOL = "graphql-transport-ws";

enum CloseCode {
  InternalServerError = 4500,
  BadRequest = 4400,
  Unauthorized = 4401,
  Forbidden = 4403,
  // ... additional codes
}

enum MessageType {
  ConnectionInit = "connection_init",
  Subscribe = "subscribe",
  Next = "next",
  Error = "error",
  Complete = "complete",
  // ... additional types
}

Common Types & Protocol

Error Handling

GraphQL-WS provides comprehensive error handling through:

  • Close Codes: Standard WebSocket close codes for different error conditions
  • Error Messages: Structured error messages following the GraphQL over WebSocket Protocol
  • Event System: Error events for monitoring and handling connection issues
  • Retry Logic: Configurable retry mechanisms for connection failures

Common error scenarios include connection timeouts, authentication failures, and protocol violations, all with appropriate close codes and error reporting.