nitro-graphql 1.6.0 → 1.7.0-beta.0

package/dist/templates/subscribe-client.mjs

@@ -0,0 +1,59 @@
+//#region src/templates/subscribe-client.ts
+/**
+* Template for GraphQL subscription client config
+* Small config file that users can customize (like ofetch.ts pattern)
+*/
+const subscribeClientTemplate = `// 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)
+`;
+
+//#endregion
+export { subscribeClientTemplate };

package/dist/types/index.d.mts

@@ -187,12 +187,27 @@ interface PathsConfig {
   /** Types directory (default: '{buildDir}/types') */
   typesDir?: string;
 }
+/**
+ * WebSocket subscriptions configuration
+ */
+interface SubscriptionsConfig {
+  /** Enable WebSocket subscriptions support */
+  enabled?: boolean;
+  /** WebSocket endpoint path (default: '/api/graphql/ws') */
+  endpoint?: string;
+  /** WebSocket protocol (currently only graphql-ws is supported) */
+  protocol?: 'graphql-ws';
+}
 interface NitroGraphQLOptions {
   framework: 'graphql-yoga' | 'apollo-server';
   endpoint?: {
     graphql?: string;
     healthCheck?: string;
+    /** WebSocket endpoint path (default: '/api/graphql/ws') */
+    ws?: string;
   };
+  /** WebSocket subscriptions configuration */
+  subscriptions?: SubscriptionsConfig;
   playground?: boolean;
   typedefs?: string[];
   resolvers?: Array<IResolvers<any, any>>;
@@ -243,4 +258,4 @@ interface NitroGraphQLOptions {
   paths?: PathsConfig;
 }
 //#endregion
-export { ClientUtilsConfig, CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, ExternalServicePaths, FederationConfig, FileGenerationConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions, PathsConfig, ScaffoldConfig, SdkConfig, TypesConfig };
+export { ClientUtilsConfig, CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, ExternalServicePaths, FederationConfig, FileGenerationConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions, PathsConfig, ScaffoldConfig, SdkConfig, SubscriptionsConfig, TypesConfig };

package/dist/utils/apollo.d.mts

@@ -1,5 +1,5 @@
-import { ApolloServer, BaseContext, ContextFunction } from "@apollo/server";
 import { EventHandler, H3Event } from "h3";
+import { ApolloServer, BaseContext, ContextFunction } from "@apollo/server";
 import { WithRequired } from "@apollo/utils.withrequired";
 import { Hooks } from "crossws";
 

package/dist/utils/apollo.mjs

@@ -1,5 +1,5 @@
-import { HeaderMap } from "@apollo/server";
 import { eventHandler, getHeaders, isMethod, readBody, setHeaders } from "h3";
+import { HeaderMap } from "@apollo/server";
 
 //#region src/utils/apollo.ts
 function startServerAndCreateH3Handler(server, options) {

package/dist/utils/client-codegen.d.mts

@@ -34,5 +34,19 @@ declare function generateExternalClientTypes(service: ExternalGraphQLService, sc
   types: string;
   sdk: string;
 } | false>;
+/**
+ * Extract subscription info from documents
+ */
+interface SubscriptionInfo {
+  name: string;
+  methodName: string;
+  fieldName: string;
+  hasVariables: boolean;
+}
+declare function extractSubscriptions(docs: Source[]): SubscriptionInfo[];
+/**
+ * Generate subscription builder code (Drizzle-style API) + Vue Composables
+ */
+declare function generateSubscriptionBuilder(docs: Source[]): string;
 //#endregion
-export { GraphQLLoadSchemaOptions, GraphQLTypeDefPointer, downloadAndSaveSchema, generateClientTypes, generateExternalClientTypes, graphQLLoadSchemaSync, loadExternalSchema, loadGraphQLDocuments };
+export { GraphQLLoadSchemaOptions, GraphQLTypeDefPointer, SubscriptionInfo, downloadAndSaveSchema, extractSubscriptions, generateClientTypes, generateExternalClientTypes, generateSubscriptionBuilder, graphQLLoadSchemaSync, loadExternalSchema, loadGraphQLDocuments };

package/dist/utils/client-codegen.mjs

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { consola as consola$1 } from "consola";
 import { defu as defu$1 } from "defu";
 import { dirname, resolve } from "pathe";
-import { parse } from "graphql";
+import { Kind, parse } from "graphql";
 import { printSchemaWithDirectives } from "@graphql-tools/utils";
 import { createHash } from "node:crypto";
 import { codegen } from "@graphql-codegen/core";
@@ -265,14 +265,16 @@ export function getSdk(requester: Requester): Sdk {
 				typescriptGenericSdk: { plugin: plugin$1 }
 			}
 		});
+		const sdkContent = (await Promise.all(sdkOutput.map(async (config$1) => {
+			return {
+				file: config$1.filename,
+				content: await codegen(config$1)
+			};
+		})))[0]?.content || "";
+		const subscriptionBuilder = generateSubscriptionBuilder(docs);
 		return {
 			types: output,
-			sdk: (await Promise.all(sdkOutput.map(async (config$1) => {
-				return {
-					file: config$1.filename,
-					content: await codegen(config$1)
-				};
-			})))[0]?.content || ""
+			sdk: subscriptionBuilder ? sdkContent + subscriptionBuilder : sdkContent
 		};
 	} catch (error) {
 		consola$1.warn(`[graphql${serviceLabel}] Client type generation failed:`, error);
@@ -285,6 +287,403 @@ export function getSdk(requester: Requester): Sdk {
 async function generateExternalClientTypes(service, schema, docs, virtualTypesPath) {
 	return generateClientTypes(schema, docs, service.codegen?.client || {}, service.codegen?.clientSDK || {}, void 0, service.name, virtualTypesPath);
 }
+/**
+* Convert PascalCase to camelCase
+*/
+function toCamelCase(str) {
+	return str.charAt(0).toLowerCase() + str.slice(1);
+}
+function extractSubscriptions(docs) {
+	const subscriptions = [];
+	for (const doc of docs) {
+		if (!doc.document) continue;
+		for (const def of doc.document.definitions) if (def.kind === Kind.OPERATION_DEFINITION && def.operation === "subscription") {
+			const operationDef = def;
+			const name = operationDef.name?.value;
+			if (!name) continue;
+			const firstSelection = operationDef.selectionSet.selections[0];
+			if (firstSelection.kind !== Kind.FIELD) continue;
+			const fieldName = firstSelection.name.value;
+			const hasVariables = (operationDef.variableDefinitions?.length || 0) > 0;
+			subscriptions.push({
+				name,
+				methodName: toCamelCase(name),
+				fieldName,
+				hasVariables
+			});
+		}
+	}
+	return subscriptions;
+}
+/**
+* Generate subscription builder code (Drizzle-style API) + Vue Composables
+*/
+function generateSubscriptionBuilder(docs) {
+	const subscriptions = extractSubscriptions(docs);
+	if (subscriptions.length === 0) return "";
+	let output = `
+// === Subscription Imports ===
+import { ref, onUnmounted, computed } from 'vue'
+import type { Ref } from 'vue'
+import type {
+  ConnectionState,
+  SubscriptionHandle,
+  SubscriptionSession,
+  SubscriptionTransport,
+  TransportOptions,
+} from 'nitro-graphql/subscribe'
+import { subscriptionClient } from './subscribe'
+
+// === Subscription Types ===
+export type { ConnectionState, SubscriptionHandle, SubscriptionSession, SubscriptionTransport, TransportOptions }
+
+// Forward declaration for UseSubscriptionSessionReturn (defined below)
+export interface UseSubscriptionSessionReturn {
+  /** The underlying session object */
+  session: SubscriptionSession
+  /** Subscribe using the shared session (updates reactive refs) */
+  subscribe: <TData = unknown>(
+    query: string,
+    variables: unknown,
+    onData?: (data: TData) => void,
+    onError?: (error: Error) => void,
+  ) => SubscriptionHandle
+  /** Close all subscriptions and the connection */
+  close: () => void
+  /** Is the session connected (reactive) */
+  isConnected: Ref<boolean>
+  /** Current connection state (reactive) */
+  state: Ref<ConnectionState>
+  /** Number of active subscriptions (reactive) */
+  subscriptionCount: Ref<number>
+}
+
+export interface UseSubscriptionOptions<T> {
+  /** Auto-start subscription on mount (default: false) */
+  immediate?: boolean
+  /** Callback when subscription starts */
+  onStart?: () => void
+  /** Callback when subscription stops */
+  onStop?: () => void
+  /** Callback when data is received */
+  onData?: (data: T) => void
+  /** Callback when error occurs */
+  onError?: (error: Error) => void
+  /** Callback when WebSocket connects */
+  onConnected?: () => void
+  /** Callback when WebSocket reconnects */
+  onReconnected?: () => void
+  /** Callback when WebSocket disconnects */
+  onDisconnected?: () => void
+  /** Callback when connection state changes */
+  onStateChange?: (state: ConnectionState) => void
+  /** Use existing session for multiplexing (pass result from useSubscriptionSession) */
+  session?: UseSubscriptionSessionReturn
+  /** Use SSE transport instead of WebSocket (shorthand for transport: 'sse') */
+  sse?: boolean
+  /** Transport type: 'websocket' (default), 'sse', or 'auto' (WS first, SSE fallback) */
+  transport?: SubscriptionTransport
+}
+
+export interface UseSubscriptionReturn<T> {
+  /** Reactive subscription data */
+  data: Ref<T | null>
+  /** Reactive error state */
+  error: Ref<Error | null>
+  /** Is subscription active */
+  isActive: Ref<boolean>
+  /** Connection state */
+  state: Ref<ConnectionState>
+  /** Active transport type ('websocket' | 'sse') */
+  transport: Ref<'websocket' | 'sse'>
+  /** Start subscription */
+  start: () => void
+  /** Stop subscription */
+  stop: () => void
+  /** Restart subscription */
+  restart: () => void
+}
+
+// === Subscription Builder (Drizzle-style API) ===
+interface SubscriptionBuilder<TData> {
+  onData(fn: (data: TData) => void): SubscriptionBuilder<TData>
+  onError(fn: (error: Error) => void): SubscriptionBuilder<TData>
+  start(): SubscriptionHandle
+  subscribe(fn: (data: TData) => void): SubscriptionHandle
+}
+
+function createSubscriptionBuilder<TData>(query: string, variables: unknown): SubscriptionBuilder<TData> {
+  let onDataFn: ((data: TData) => void) | undefined
+  let onErrorFn: ((error: Error) => void) | undefined
+
+  const builder: SubscriptionBuilder<TData> = {
+    onData(fn: (data: TData) => void) {
+      onDataFn = fn
+      return builder
+    },
+    onError(fn: (error: Error) => void) {
+      onErrorFn = fn
+      return builder
+    },
+    start(): SubscriptionHandle {
+      return subscriptionClient.subscribe(query, variables, onDataFn, onErrorFn)
+    },
+    subscribe(fn: (data: TData) => void): SubscriptionHandle {
+      return subscriptionClient.subscribe(query, variables, fn, undefined)
+    },
+  }
+
+  return builder
+}
+
+export const subscription = {
+`;
+	for (const sub of subscriptions) if (sub.hasVariables) output += `  ${sub.methodName}(variables: Types.${sub.name}SubscriptionVariables): SubscriptionBuilder<Types.${sub.name}Subscription['${sub.fieldName}']> {
+    return createSubscriptionBuilder<Types.${sub.name}Subscription['${sub.fieldName}']>(${sub.name}Document, variables)
+  },
+`;
+	else output += `  ${sub.methodName}(): SubscriptionBuilder<Types.${sub.name}Subscription['${sub.fieldName}']> {
+    return createSubscriptionBuilder<Types.${sub.name}Subscription['${sub.fieldName}']>(${sub.name}Document, undefined)
+  },
+`;
+	output += `}
+
+// === Framework-Agnostic Session (for non-Vue usage) ===
+/**
+ * Create a multiplexed subscription session (framework-agnostic)
+ * All subscriptions share a single WebSocket connection.
+ *
+ * @example
+ * // Vanilla JS / Node.js / React / etc.
+ * const session = createSubscriptionSession()
+ * const sub1 = session.subscribe(query1, vars1, onData1)
+ * const sub2 = session.subscribe(query2, vars2, onData2)
+ * // Both use the same WebSocket connection
+ * sub1.unsubscribe()
+ * session.close() // Close all
+ *
+ * @returns SubscriptionSession - Framework-agnostic session object
+ */
+export function createSubscriptionSession(): SubscriptionSession {
+  return subscriptionClient.createSession()
+}
+
+// === Vue Composable: useSubscriptionSession (Multiplexing) ===
+export interface UseSubscriptionSessionReturn {
+  /** The underlying session object */
+  session: SubscriptionSession
+  /** Subscribe using the shared session */
+  subscribe: <TData = unknown>(
+    query: string,
+    variables: unknown,
+    onData?: (data: TData) => void,
+    onError?: (error: Error) => void,
+  ) => SubscriptionHandle
+  /** Close all subscriptions and the connection */
+  close: () => void
+  /** Is the session connected (reactive) */
+  isConnected: Ref<boolean>
+  /** Current connection state (reactive) */
+  state: Ref<ConnectionState>
+  /** Number of active subscriptions (reactive) */
+  subscriptionCount: Ref<number>
+}
+
+/**
+ * Vue composable for multiplexed subscription session
+ * Provides reactive state and automatic cleanup on unmount.
+ *
+ * @example
+ * // Vue 3 component
+ * const session = useSubscriptionSession()
+ * const { data } = useCountdown({ from: 10 }, { session })
+ * // Session auto-closes on component unmount
+ *
+ * @returns UseSubscriptionSessionReturn - Vue-reactive session wrapper
+ */
+export function useSubscriptionSession(): UseSubscriptionSessionReturn {
+  const session = subscriptionClient.createSession()
+
+  // Use refs for reactivity (session getters are not reactive)
+  const isConnected = ref(session.isConnected)
+  const state = ref<ConnectionState>(session.state)
+  const subscriptionCount = ref(session.subscriptionCount)
+
+  // Update refs when session state changes
+  function updateRefs() {
+    isConnected.value = session.isConnected
+    state.value = session.state
+    subscriptionCount.value = session.subscriptionCount
+  }
+
+  // Subscribe to session state changes for automatic reactivity
+  const unsubscribeStateChange = session.onStateChange(() => {
+    updateRefs()
+  })
+
+  function subscribe<TData = unknown>(
+    query: string,
+    variables: unknown,
+    onData?: (data: TData) => void,
+    onError?: (error: Error) => void,
+  ): SubscriptionHandle {
+    return session.subscribe(query, variables, onData as (data: unknown) => void, onError)
+  }
+
+  function close() {
+    session.close()
+  }
+
+  onUnmounted(() => {
+    unsubscribeStateChange()
+    close()
+  })
+
+  return {
+    session,
+    subscribe,
+    close,
+    isConnected,
+    state,
+    subscriptionCount,
+  }
+}
+
+// === Vue Composables ===
+function createUseSubscription<TData, TVariables = undefined>(
+  query: string,
+  getVariables: () => TVariables,
+): (options?: UseSubscriptionOptions<TData>) => UseSubscriptionReturn<TData> {
+  return (options: UseSubscriptionOptions<TData> = {}): UseSubscriptionReturn<TData> => {
+    const data = ref<TData | null>(null) as Ref<TData | null>
+    const error = ref<Error | null>(null)
+    const isActive = ref(false)
+    const state = ref<ConnectionState>('idle')
+    const transport = ref<'websocket' | 'sse'>('websocket')
+    let handle: SubscriptionHandle | null = null
+
+    // Resolve transport options
+    const transportOptions: TransportOptions = {
+      sse: options.sse,
+      transport: options.transport,
+    }
+
+    function start() {
+      stop()
+      isActive.value = true
+      error.value = null
+      options.onStart?.()
+
+      const variables = getVariables()
+
+      if (options.session) {
+        // Use existing session for multiplexing (WebSocket only)
+        handle = options.session.subscribe<TData>(
+          query,
+          variables,
+          (d: TData) => {
+            data.value = d
+            options.onData?.(d)
+          },
+          (e: Error) => {
+            error.value = e
+            options.onError?.(e)
+          },
+        )
+        transport.value = 'websocket'
+      } else {
+        // Create dedicated connection with transport selection
+        handle = subscriptionClient.subscribe<TData>(
+          query,
+          variables,
+          (d: TData) => {
+            data.value = d
+            options.onData?.(d)
+          },
+          (e: Error) => {
+            error.value = e
+            options.onError?.(e)
+          },
+          transportOptions,
+        )
+        // Update transport ref from handle
+        transport.value = handle.transport
+      }
+    }
+
+    function stop() {
+      if (handle) {
+        handle.unsubscribe()
+        handle = null
+        isActive.value = false
+        options.onStop?.()
+      }
+    }
+
+    function restart() {
+      stop()
+      start()
+    }
+
+    if (options.immediate) {
+      start()
+    }
+
+    onUnmounted(stop)
+
+    return { data, error, isActive, state, transport, start, stop, restart }
+  }
+}
+
+// === Subscription Return Types ===
+`;
+	for (const sub of subscriptions) {
+		const typeName = `Types.${sub.name}Subscription['${sub.fieldName}']`;
+		output += `/** Return type for use${sub.name} composable */
+export type Use${sub.name}Return = UseSubscriptionReturn<${typeName}>
+`;
+	}
+	output += `
+// === Vue Composables ===
+`;
+	for (const sub of subscriptions) {
+		const typeName = `Types.${sub.name}Subscription['${sub.fieldName}']`;
+		const varsType = `Types.${sub.name}SubscriptionVariables`;
+		if (sub.hasVariables) output += `/**
+ * Vue composable for ${sub.name} subscription
+ * @param variables - Subscription variables
+ * @param options - Subscription options (immediate, onData, onError, session, etc.)
+ * @returns Reactive subscription state: { data, error, isActive, state, start, stop, restart }
+ */
+export function use${sub.name}(
+  variables: ${varsType},
+  options?: UseSubscriptionOptions<${typeName}>,
+): Use${sub.name}Return {
+  return createUseSubscription<${typeName}, ${varsType}>(
+    ${sub.name}Document,
+    () => variables,
+  )(options)
+}
+
+`;
+		else output += `/**
+ * Vue composable for ${sub.name} subscription
+ * @param options - Subscription options (immediate, onData, onError, session, etc.)
+ * @returns Reactive subscription state: { data, error, isActive, state, start, stop, restart }
+ */
+export function use${sub.name}(
+  options?: UseSubscriptionOptions<${typeName}>,
+): Use${sub.name}Return {
+  return createUseSubscription<${typeName}, undefined>(
+    ${sub.name}Document,
+    () => undefined,
+  )(options)
+}
+
+`;
+	}
+	return output;
+}
 
 //#endregion
-export { downloadAndSaveSchema, generateClientTypes, generateExternalClientTypes, graphQLLoadSchemaSync, loadExternalSchema, loadGraphQLDocuments };
+export { downloadAndSaveSchema, extractSubscriptions, generateClientTypes, generateExternalClientTypes, generateSubscriptionBuilder, graphQLLoadSchemaSync, loadExternalSchema, loadGraphQLDocuments };

package/dist/utils/define.d.mts

@@ -1,6 +1,6 @@
 import { GraphQLSchema } from "graphql";
-import { ApolloServerOptions } from "@apollo/server";
 import { H3Event } from "h3";
+import { ApolloServerOptions } from "@apollo/server";
 import { YogaServerOptions } from "graphql-yoga";
 import { NPMConfig, Resolvers, ResolversTypes } from "#graphql/server";
 import { StandardSchemaV1 } from "nitro-graphql";

package/dist/utils/type-generation.mjs

@@ -22,11 +22,15 @@ function generateGraphQLIndexFile(nitro, clientDir, externalServices = []) {
 		let indexContent = `// This file is auto-generated once by nitro-graphql for quick start
 // You can modify this file according to your needs
 //
-// Export your main GraphQL service (auto-generated)
+// === Query/Mutation Client ===
 export * from './default/ofetch'
 
-// Export external GraphQL services (auto-generated for existing services)
-// When you add new external services, don't forget to add their exports here:
+// === Subscription Composables (Vue) ===
+// Export useCountdown, useGreetings, useSubscriptionSession, etc.
+export * from './default/sdk'
+
+// === External GraphQL Services ===
+// When you add new external services, add their exports here:
 // export * from './yourServiceName/ofetch'
 `;
 		for (const service of externalServices) indexContent += `export * from './${service.name}/ofetch'\n`;

package/dist/utils/ws-protocol.d.mts

@@ -0,0 +1,25 @@
+import { GraphQLSchema } from "graphql";
+import { Peer } from "crossws";
+
+//#region src/utils/ws-protocol.d.ts
+declare function devLog(message: string, ...args: any[]): void;
+interface GraphQLWSMessage {
+  id?: string;
+  type: string;
+  payload?: any;
+}
+declare function sendMessage(peer: Peer, message: Record<string, any>): void;
+declare function sendErrorMessage(peer: Peer, id: string | undefined, errors: Array<{
+  message: string;
+  locations?: any;
+  path?: any;
+}>): void;
+declare function sendNextMessage(peer: Peer, id: string, payload: any): void;
+declare function sendCompleteMessage(peer: Peer, id: string): void;
+declare function handleConnectionInit(peer: Peer): void;
+declare function handlePing(peer: Peer): void;
+declare function handleSubscribe(peer: Peer, msg: GraphQLWSMessage, schema: GraphQLSchema, subscriptions: Map<string, AsyncIterator<any>>): Promise<void>;
+declare function handleComplete(msg: GraphQLWSMessage, subscriptions: Map<string, AsyncIterator<any>>): Promise<void>;
+declare function cleanupSubscriptions(subscriptions: Map<string, AsyncIterator<any>>): Promise<void>;
+//#endregion
+export { GraphQLWSMessage, cleanupSubscriptions, devLog, handleComplete, handleConnectionInit, handlePing, handleSubscribe, sendCompleteMessage, sendErrorMessage, sendMessage, sendNextMessage };