feat: GraphQL Subscriptions with WebSocket, SSE, and Auto Mode (#57)

* feat: add WebSocket subscription support for GraphQL

- Add WebSocket handlers for GraphQL Yoga and Apollo Server
- Implement graphql-ws protocol for real-time subscriptions
- Add SubscriptionsConfig type and endpoint configuration
- Auto-enable experimental websocket flag when subscriptions enabled
- Add playground examples with PubSub chat implementation

Usage:
```typescript
// nitro.config.ts
graphql: {
  framework: 'graphql-yoga',
  subscriptions: {
    enabled: true,
  },
}
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* feat: implement GraphQL subscription client with WebSocket and SSE support

* feat: implement GraphQL subscription support with cross-platform WebSocket and SSE

* feat: add GraphQL subscription support with countdown, greetings, and server time

* feat: enhance GraphQL subscription support with authentication and connection parameters

* feat: add intentional close handling for subscription connections

* feat: enhance subscription handling with duplicate check and connection state management

* feat: enhance WebSocket client with keep-alive pings and reconnection handling

* feat: implement graceful shutdown for subscriptions with complete message handling

* refactor: update subscription handling and introduce multiplexing support

- Changed import paths for Vue composables in subscriptions.vue to use sdk.ts.
- Enhanced subscribe-client.ts to support multiplexing with createSession() for shared connections.
- Updated subscription client methods to return SubscriptionHandle instead of SubscriptionClient.
- Added new useSubscriptionSession hook for managing multiplexed subscriptions.
- Deprecated generateNuxtSubscriptionComposables function; noted that composables are now generated directly in sdk.ts.
- Improved error handling and connection management in subscription logic.

* refactor: improve subscription session handling and connection management

- Updated `useSubscriptionSession` to maintain reactivity by subscribing to session state changes.
- Refactored multiplexing logic in `multiplexing-test.vue` to use a single session object for all composables.
- Enhanced connection management in `subscribe-client.ts` with a Timer Manager for better handling of timeouts and intervals.
- Introduced keep-alive functionality to maintain WebSocket connections.
- Improved error handling and state notifications for subscriptions.
- Added state change callbacks to `SubscriptionSession` for better reactivity.
- Updated client code generation to include detailed JSDoc comments for subscription composables.

* refactor: streamline GraphQL subscription client configuration and improve code organization

- Simplified the subscription client template for easier customization.
- Reorganized imports and exports in subscription-related files for clarity.
- Updated type generation to include subscription composables and external services.
- Enhanced the tsdown configuration to include subscription-related files.

* feat: add unified transport support for subscriptions with WebSocket, SSE, and auto mode

* refactor: enhance SSE handling by introducing dedicated event listener for subscription data

* refactor: enhance TypeScript configuration handling and remove deprecated subscription composables generation

* chore: update dependencies in pnpm-workspace.yaml

- Bump @antfu/eslint-config from ^6.3.0 to ^6.6.1
- Update @apollo/subgraph from ^2.12.1 to ^2.12.2
- Upgrade @nuxt/kit and @nuxt/schema from ^4.2.1 to ^4.2.2
- Update @types/node from ^24.10.1 to ^24.10.3
- Bump nuxt from ^4.2.1 to ^4.2.2
- Upgrade oxc-parser from ^0.101.0 to ^0.102.0
- Update tailwindcss from ^4.1.17 to ^4.1.18
- Bump tsdown from ^0.16.8 to ^0.17.2
- Update vue-router from ^4.6.3 to ^4.6.4

* refactor: update subscription client configuration and improve client instance export

* refactor: change type of buildSubgraphSchema to any for flexibility

* refactor: update version to 1.7.0-beta.0 and enhance subscription handling in client type generation

* chore: bump version to 1.7.0-beta.1

* chore: bump version to 1.7.0-beta.2 and refactor subscription method generation

* refactor: remove redundant sse shorthand from TransportOptions

Remove the `sse: boolean` property from TransportOptions interface
to simplify the API. Users should now use `transport: 'sse'` instead.

Changes:
- Remove `sse` property from TransportOptions (subscribe/index.ts)
- Simplify resolveTransport() function
- Remove `sse` property from UseSubscriptionOptions (client-codegen.ts)
- Update transportOptions object construction

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* chore: bump version to 1.7.0-beta.5

* feat: implement graceful WebSocket shutdown for Apollo Server and GraphQL Yoga

* feat(dependencies): add vitepress-plugin-llms and update libc specifications for various packages

---------

Co-authored-by: Claude <[email protected]>

Author: productdevbook

playgrounds/nitro/graphql/default/subscribe.ts

@@ -0,0 +1,50 @@
+// This file is auto-generated once by nitro-graphql for quick start
+// You can modify this file to customize the subscription client
+// The implementation comes from nitro-graphql/subscribe - you'll get updates automatically!
+//
+// Usage Examples:
+// ---------------
+// Basic subscription:
+//   subscriptionClient.subscribe(query, variables, onData, onError)
+//
+// Multiplexed subscriptions (shared connection):
+//   const session = subscriptionClient.createSession()
+//   session.subscribe(query1, vars1, onData1)
+//   session.subscribe(query2, vars2, onData2)
+//
+// With authentication:
+//   Edit connectionParams below to add auth headers
+
+import type {
+  ConnectionState,
+  SubscriptionClient,
+  SubscriptionClientConfig,
+  SubscriptionHandle,
+  SubscriptionSession,
+} from 'nitro-graphql/subscribe'
+import { createSubscriptionClient } from 'nitro-graphql/subscribe'
+
+// Re-export types for convenience
+export type { ConnectionState, SubscriptionClient, SubscriptionHandle, SubscriptionSession }
+
+// Configure the subscription client
+// Customize these settings according to your needs
+const config: SubscriptionClientConfig = {
+  // WebSocket endpoint (default: '/api/graphql/ws')
+  wsEndpoint: '/api/graphql/ws',
+
+  // Connection timeout in ms (default: 10000)
+  connectionTimeoutMs: 10000,
+
+  // Max reconnection attempts (default: 5)
+  maxRetries: 5,
+
+  // Authentication params sent with connection_init
+  // Can be a function for dynamic values (e.g., JWT tokens)
+  // connectionParams: () => ({
+  //   authorization: `Bearer ${getToken()}`,
+  // }),
+}
+
+// Export configured client instance
+export const subscriptionClient = createSubscriptionClient(config)

playgrounds/nitro/nitro.config.ts

@@ -7,6 +7,9 @@ export default defineNitroConfig({
   compatibilityDate: '2025-07-01',
   graphql: {
     framework: 'graphql-yoga',
+    subscriptions: {
+      enabled: true,
+    },
   },
   esbuild: {
     options: {

playgrounds/nitro/server/graphql/chat/chat.resolver.ts

@@ -0,0 +1,103 @@
+import { CHANNELS, pubsub } from './pubsub'
+
+interface Message {
+  id: string
+  channel: string
+  content: string
+  author: string
+  createdAt: string
+}
+
+interface UserEvent {
+  type: 'JOINED' | 'LEFT' | 'TYPING' | 'STOPPED_TYPING'
+  channel: string
+  username: string
+  timestamp: string
+}
+
+// Mutations
+export const chatMutations = defineMutation({
+  sendMessage: (_parent, { channel, content, author }: { channel: string, content: string, author: string }) => {
+    const message: Message = {
+      id: crypto.randomUUID(),
+      channel,
+      content,
+      author,
+      createdAt: new Date().toISOString(),
+    }
+
+    // Publish to subscribers
+    pubsub.publish(CHANNELS.MESSAGE(channel), message)
+
+    return message
+  },
+
+  joinChannel: (_parent, { channel, username }: { channel: string, username: string }) => {
+    const event: UserEvent = {
+      type: 'JOINED',
+      channel,
+      username,
+      timestamp: new Date().toISOString(),
+    }
+
+    pubsub.publish(CHANNELS.USER_EVENT(channel), event)
+    return event
+  },
+
+  leaveChannel: (_parent, { channel, username }: { channel: string, username: string }) => {
+    const event: UserEvent = {
+      type: 'LEFT',
+      channel,
+      username,
+      timestamp: new Date().toISOString(),
+    }
+
+    pubsub.publish(CHANNELS.USER_EVENT(channel), event)
+    return event
+  },
+
+  startTyping: (_parent, { channel, username }: { channel: string, username: string }) => {
+    const event: UserEvent = {
+      type: 'TYPING',
+      channel,
+      username,
+      timestamp: new Date().toISOString(),
+    }
+
+    pubsub.publish(CHANNELS.USER_EVENT(channel), event)
+    return event
+  },
+
+  stopTyping: (_parent, { channel, username }: { channel: string, username: string }) => {
+    const event: UserEvent = {
+      type: 'STOPPED_TYPING',
+      channel,
+      username,
+      timestamp: new Date().toISOString(),
+    }
+
+    pubsub.publish(CHANNELS.USER_EVENT(channel), event)
+    return event
+  },
+})
+
+// Subscriptions
+export const chatSubscriptions = defineSubscription({
+  onMessage: {
+    subscribe: (_parent, { channel }: { channel: string }) => {
+      return {
+        [Symbol.asyncIterator]: () => pubsub.asyncIterator<Message>(CHANNELS.MESSAGE(channel)),
+      }
+    },
+    resolve: (payload: Message) => payload,
+  },
+
+  onUserEvent: {
+    subscribe: (_parent, { channel }: { channel: string }) => {
+      return {
+        [Symbol.asyncIterator]: () => pubsub.asyncIterator<UserEvent>(CHANNELS.USER_EVENT(channel)),
+      }
+    },
+    resolve: (payload: UserEvent) => payload,
+  },
+})

playgrounds/nitro/server/graphql/chat/pubsub.ts

@@ -0,0 +1,75 @@
+// Simple in-memory PubSub implementation
+type Subscriber<T> = (data: T) => void
+
+class PubSub {
+  private subscribers: Map<string, Set<Subscriber<any>>> = new Map()
+
+  subscribe<T>(channel: string, callback: Subscriber<T>): () => void {
+    if (!this.subscribers.has(channel)) {
+      this.subscribers.set(channel, new Set())
+    }
+    this.subscribers.get(channel)!.add(callback)
+
+    // Return unsubscribe function
+    return () => {
+      this.subscribers.get(channel)?.delete(callback)
+    }
+  }
+
+  publish<T>(channel: string, data: T): void {
+    const subs = this.subscribers.get(channel)
+    if (subs) {
+      for (const callback of subs) {
+        callback(data)
+      }
+    }
+  }
+
+  // Create an async iterator for subscriptions
+  asyncIterator<T>(channel: string): AsyncIterableIterator<T> {
+    const queue: T[] = []
+    let resolve: ((value: IteratorResult<T>) => void) | null = null
+    let done = false
+
+    const unsubscribe = this.subscribe<T>(channel, (data) => {
+      if (resolve) {
+        resolve({ value: data, done: false })
+        resolve = null
+      }
+      else {
+        queue.push(data)
+      }
+    })
+
+    return {
+      [Symbol.asyncIterator]() {
+        return this
+      },
+      async next(): Promise<IteratorResult<T>> {
+        if (done) {
+          return { value: undefined, done: true }
+        }
+        if (queue.length > 0) {
+          return { value: queue.shift()!, done: false }
+        }
+        return new Promise((res) => {
+          resolve = res
+        })
+      },
+      async return(): Promise<IteratorResult<T>> {
+        done = true
+        unsubscribe()
+        return { value: undefined, done: true }
+      },
+    }
+  }
+}
+
+// Global singleton
+export const pubsub = new PubSub()
+
+// Channel names
+export const CHANNELS = {
+  MESSAGE: (channel: string) => `message:${channel}`,
+  USER_EVENT: (channel: string) => `user_event:${channel}`,
+}

playgrounds/nitro/server/graphql/schema.graphql

@@ -34,9 +34,63 @@ type Mutation {
     email: String! @validate(pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$")
     age: Int! @validate(min: 18, max: 100)
   ): User
-  
+
   updateBio(
     userId: ID!
     bio: String! @validate(maxLength: 500) @transform(trim: true)
   ): User
+
+  """Send a message to a channel"""
+  sendMessage(channel: String!, content: String!, author: String!): Message!
+
+  """Join a channel"""
+  joinChannel(channel: String!, username: String!): UserEvent!
+
+  """Leave a channel"""
+  leaveChannel(channel: String!, username: String!): UserEvent!
+
+  """Send typing indicator"""
+  startTyping(channel: String!, username: String!): UserEvent!
+
+  """Stop typing indicator"""
+  stopTyping(channel: String!, username: String!): UserEvent!
+}
+
+type Subscription {
+  """Simple counter that increments every second"""
+  countdown(from: Int!): Int!
+
+  """Receives a greeting message every 2 seconds"""
+  greetings: String!
+
+  """Current server time updated every second"""
+  serverTime: DateTime!
+
+  """Listen for new messages in a channel"""
+  onMessage(channel: String!): Message!
+
+  """Listen for user events (join/leave/typing)"""
+  onUserEvent(channel: String!): UserEvent!
+}
+
+type Message {
+  id: ID!
+  channel: String!
+  content: String!
+  author: String!
+  createdAt: DateTime!
+}
+
+type UserEvent {
+  type: UserEventType!
+  channel: String!
+  username: String!
+  timestamp: DateTime!
+}
+
+enum UserEventType {
+  JOINED
+  LEFT
+  TYPING
+  STOPPED_TYPING
 }

playgrounds/nitro/server/graphql/subscriptions.resolver.ts

@@ -0,0 +1,36 @@
+export const subscriptionResolvers = defineSubscription({
+  countdown: {
+    async* subscribe(_parent, { from }: { from: number }) {
+      for (let i = from; i >= 0; i--) {
+        yield { countdown: i }
+        await new Promise(resolve => setTimeout(resolve, 1000))
+      }
+    },
+  },
+
+  greetings: {
+    async* subscribe() {
+      const greetings = ['Hello!', 'Merhaba!', 'Bonjour!', 'Hola!', 'Ciao!', 'Hallo!']
+      let index = 0
+
+      while (true) {
+        yield { greetings: greetings[index % greetings.length] }
+        index++
+        await new Promise(resolve => setTimeout(resolve, 2000))
+
+        // Stop after 10 messages for demo
+        if (index >= 10)
+          break
+      }
+    },
+  },
+
+  serverTime: {
+    async* subscribe() {
+      for (let i = 0; i < 30; i++) {
+        yield { serverTime: new Date().toISOString() }
+        await new Promise(resolve => setTimeout(resolve, 1000))
+      }
+    },
+  },
+})

playgrounds/nuxt/app/graphql/default/index.ts

@@ -0,0 +1,13 @@
+// This file is auto-generated once by nitro-graphql for quick start
+// You can modify this file according to your needs
+//
+// === Query/Mutation Client ===
+export * from './ofetch'
+
+// === Subscription Composables (Vue) ===
+// Export useCountdown, useGreetings, useSubscriptionSession, etc.
+export * from './sdk'
+
+// === Subscription Client (low-level) ===
+// Export subscriptionClient for direct WebSocket access
+export * from './subscribe'