createServer

Creates and configures a Socket.IO GraphQL server with live query support.

Signature (Node.js)

import { createServer } from '@requence/socketql/server'

function createServer<Context>(options: ServerOptions<Context>): {
  server: IoServer
  namespace: Namespace
  liveQueryStore: ExtendedLiveQueryStore
  attach: (baseServer: ServerInstance) => void
  addSchema: (opts: { typeDefs: TypeSource; resolvers: IResolvers }) => void
  httpHandler: (opts?) => (c) => Promise<Response>
  generateIntrospection: () => Promise<IntrospectionQuery>
}

Signature (Bun)

import { createServer } from '@requence/socketql/server/bun'

function createServer<Context>(options: ServerOptions<Context>): {
  server: IoServer
  namespace: Namespace
  liveQueryStore: ExtendedLiveQueryStore
  handler: () => { fetch, websocket, idleTimeout }
  addSchema: (opts: { typeDefs: TypeSource; resolvers: IResolvers }) => void
  httpHandler: (opts?) => (c) => Promise<Response>
  generateIntrospection: () => Promise<IntrospectionQuery>
}

Options

Option	Type	Default	Description
path	string	'/ws/'	Socket.IO server path
transports	string[]	['websocket']	Allowed transports
graphqlNamespace	string	'graphql'	Socket.IO namespace for GraphQL
extendContext	(ctx) => Context	() => ({})	Extend GraphQL context per connection
onConnect	(socket) => void	—	Called when a client connects. Throw ConnectionRejectedError(message, data?) to reject.
onDisconnect	(socket, reason) => void	—	Called when a client disconnects
formatError	(error) => GraphQLError	—	Transform GraphQL errors before sending
maxUploadSize	number	—	Max upload size in bytes
transformSchema	SchemaTransformer	identity	Transform the schema after creation
schemas	SocketQLSchema<Context>[]	—	Pre-register schemas at creation time
pingInterval	number	25000	Socket.IO ping interval (ms)
pingTimeout	number	20000	Socket.IO ping timeout (ms)
redis	RedisAdapter	—	Redis adapter from createRedisAdapter
wrapExecute	(execute, context) => result	passthrough	Wrap GraphQL execution (e.g. for tracing)

Return Values

Shared across both entry points:

Property	Type	Description
server	IoServer	The raw Socket.IO server instance
namespace	Namespace	The GraphQL namespace
liveQueryStore	ExtendedLiveQueryStore	Live query store for invalidation
addSchema	(opts) => void	Register type definitions and resolvers
httpHandler	(opts?) => (c) => Promise<Response>	HTTP GraphQL endpoint handler
generateIntrospection	() => Promise<...>	Generate introspection result

Node.js only:

Property	Type	Description
attach	(server) => void	Attach to a Node.js HTTP/HTTPS/HTTP2 server

Bun only:

Property	Type	Description
handler	() => { fetch, websocket, idleTimeout }	Returns Bun-ready config to spread into Bun.serve() or export default
handleRequest	(req, server) => Promise<Response>	Handle a single Socket.IO request directly
withServer	(fallback) => (req, server) => Response	Intercepts SocketQL requests, delegates the rest to the fallback

SocketQLSchema

A schema object containing type definitions and resolvers:

interface SocketQLSchema<Context = any> {
  typeDefs: TypeSource
  resolvers: IResolvers<any, GraphQLContext & Context>
}

defineSchema

A type-safe helper for creating SocketQLSchema objects. It is a simple identity function that provides autocomplete and type checking:

import { defineSchema } from '@requence/socketql/server'

const mySchema = defineSchema({
  typeDefs: /* GraphQL */ `
    type Query {
      hello: String!
    }
  `,
  resolvers: {
    Query: {
      hello: () => 'world',
    },
  },
})

GraphQLContext

The context is a discriminated union on the transport field. Every resolver receives one of two context shapes depending on how the request arrived.

Shared properties

Available in both WebSocket and HTTP contexts:

Property	Type	Description
transport	'websocket' | 'http'	The transport used for the request
queriedFields	QueriedFields	Parsed field selection helpers
unauthorized	(msg) => never	Throw an unauthorized GraphQL error
loader	(load, name?) => DataLoader	Get or create a batched DataLoader
liveQueryStore	ExtendedLiveQueryStore	Live query invalidation

WebSocketGraphQLContext

When transport is 'websocket', the context additionally includes:

Property	Type	Description
namespace	Namespace	The Socket.IO namespace
socket	Socket	The current client’s socket

HttpGraphQLContext

When transport is 'http', socket and namespace are not part of the context.

Type narrowing

if (context.transport === 'websocket') {
  context.socket    // ✅ Socket
  context.namespace // ✅ Namespace
}

if (context.transport === 'http') {
  // socket and namespace do not exist on this type
}

All three types are exported:

import type {
  GraphQLContext,
  WebSocketGraphQLContext,
  HttpGraphQLContext,
} from '@requence/socketql/server'

httpHandler

Returns an HTTP-compatible handler for GraphQL queries and mutations.

httpHandler(opts?: {
  extendContext?: (req: Request) => MaybePromise<Context>
  mapSchema?: (schema: GraphQLSchema) => GraphQLSchema
})

Option	Type	Description
extendContext	(req: Request) => Context	Extend context per HTTP request (e.g. auth from headers)
mapSchema	(schema: GraphQLSchema) => GraphQLSchema	Transform the schema for HTTP (cached after first call)

createRedisAdapter

Imported from @requence/socketql/server/redis. Creates a Redis adapter that provides both Socket.IO multi-instance coordination and Redis-backed live query invalidation.

import { createRedisAdapter } from '@requence/socketql/server/redis'

function createRedisAdapter(options: RedisAdapterOptions): RedisAdapter

Options

Option	Type	Default	Description
url	string	—	Redis connection URL (required)
liveQueryChannel	string	'requence-socketql-sync'	Redis pub/sub channel for live query invalidation

Return Value

Property	Type	Description
adapter	RedisAdapter	Socket.IO Redis adapter for multi-instance coordination
liveQueryStore	ExtendedLiveQueryStore	Redis-backed live query store

Example

import { createServer } from '@requence/socketql/server'
import { createRedisAdapter } from '@requence/socketql/server/redis'

const redis = createRedisAdapter({ url: 'redis://localhost:6379' })

const { attach } = createServer({
  redis,
  schemas: [mySchema],
})

Note

The ioredis and @socket.io/redis-adapter peer dependencies are only required when importing from server/redis.