@as-integrations/h3 1.1.6 → 1.2.1

package/README.md

@@ -31,12 +31,14 @@ import { ApolloServer } from '@apollo/server'
 import { startServerAndCreateH3Handler } from '@as-integrations/h3'
 
 const apollo = new ApolloServer({
-  // Specify server options here
+  // Specify server options like schema and resolvers here
 })
 
 export default startServerAndCreateH3Handler(apollo, {
   // Optional: Specify context
-  context: (event) => {...}
+  context: (event) => {
+    /*...*/
+  },
 })
 ```
 
@@ -45,26 +47,77 @@ export default startServerAndCreateH3Handler(apollo, {
 Create and configure an instance of Apollo Server as described in the [documentation](https://www.apollographql.com/docs/apollo-server/getting-started#step-6-create-an-instance-of-apolloserver) and then register it as a route handler in your `h3` application.
 
 ```js
-import { createApp, toNodeListener } from 'h3'
+import { createApp } from 'h3'
 import { ApolloServer } from '@apollo/server'
 import { startServerAndCreateH3Handler } from '@as-integrations/h3'
 
 const apollo = new ApolloServer({
-  // Specify server options here
+  // Specify server options like schema and resolvers here
 })
 
-const app = createApp()
+export const app = createApp()
 app.use(
   '/api',
   startServerAndCreateH3Handler(apollo, {
     // Optional: Specify context
-    context: (event) => {...}
-  })
+    context: (event) => {
+      /*...*/
+    },
+  }),
 )
+```
+
+Then run your h3 server as usual, e.g. with `npx --yes listhen -w --open ./app.ts`.
+Visit http://localhost:3000/api in your browser to access the Apollo Sandbox.
+
+## Subscriptions with WebSockets
 
-createServer(toNodeListener(app)).listen(process.env.PORT || 3000)
+This package also supports subscriptions over WebSockets. To enable this feature, you need to install the `graphql-ws` package:
+
+```sh
+# npm
+npm install graphql-ws
+
+# yarn
+yarn add graphql-ws
+
+# pnpm
+pnpm add graphql-ws
 ```
 
+Then you can add a WebSocket handler to your `h3` app using the `defineGraphqlWebSocketHandler` or `defineGraphqlWebSocket` functions from this package. Here is an example that combines the HTTP and WebSocket handlers in a single app.
+
+```js
+import { createApp } from 'h3'
+import { ApolloServer } from '@apollo/server'
+import {
+  startServerAndCreateH3Handler,
+  defineGraphqlWebSocketHandler,
+} from '@as-integrations/h3'
+import { makeExecutableSchema } from '@graphql-tools/schema'
+
+// Define your schema and resolvers
+const typeDefs = `...`
+const resolvers = {
+  /*...*/
+}
+const schema = makeExecutableSchema({ typeDefs, resolvers })
+
+const apollo = new ApolloServer({ schema })
+
+export const app = createApp()
+app.use(
+  '/api',
+  startServerAndCreateH3Handler(apollo, {
+    websocket: defineGraphqlWebSocketHandler({ schema }),
+  }),
+)
+```
+
+Then you can connect to the WebSocket endpoint using the Apollo Sandbox or any other client that supports the `graphql-ws` protocol.
+
+See the [WebSocket example](./examples/websocket.ts) for a complete example.
+
 ## 💻 Development
 
 - Clone this repository

package/dist/index.cjs

@@ -2,35 +2,89 @@
 
 const server = require('@apollo/server');
 const h3 = require('h3');
+const graphqlWs = require('graphql-ws');
+
+function defineGraphqlWebSocket(options) {
+  const server = graphqlWs.makeServer(options);
+  const peers = /* @__PURE__ */ new WeakMap();
+  return h3.defineWebSocket({
+    open(peer) {
+      const client = {
+        handleMessage: () => {
+          throw new Error("Message received before handler was registered");
+        },
+        closed: () => {
+          throw new Error("Closed before handler was registered");
+        }
+      };
+      client.closed = server.opened(
+        {
+          // TODO: use protocol on socket once h3 exposes it
+          // https://github.com/unjs/crossws/issues/31
+          protocol: graphqlWs.GRAPHQL_TRANSPORT_WS_PROTOCOL,
+          send: (message) => {
+            if (peers.has(peer)) {
+              peer.send(message);
+            }
+          },
+          close: (_code, _reason) => {
+            if (peers.has(peer)) ;
+          },
+          onMessage: (cb) => client.handleMessage = cb
+        },
+        { peer }
+      );
+      peers.set(peer, client);
+    },
+    message(peer, message) {
+      const client = peers.get(peer);
+      if (!client)
+        throw new Error("Message received for a missing client");
+      return client.handleMessage(message.text());
+    },
+    close(peer, details) {
+      const client = peers.get(peer);
+      if (!client)
+        throw new Error("Closing a missing client");
+      return client.closed(details.code ?? 1e3, details.reason ?? "");
+    }
+  });
+}
+function defineGraphqlWebSocketHandler(options) {
+  return h3.defineWebSocketHandler(defineGraphqlWebSocket(options));
+}
 
 function startServerAndCreateH3Handler(server, options) {
   server.startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests();
   const defaultContext = () => Promise.resolve({});
   const contextFunction = options?.context ?? defaultContext;
-  return h3.eventHandler(async (event) => {
-    if (h3.isMethod(event, "OPTIONS")) {
-      return null;
-    }
-    try {
-      const graphqlRequest = await toGraphqlRequest(event);
-      const { body, headers, status } = await server.executeHTTPGraphQLRequest({
-        httpGraphQLRequest: graphqlRequest,
-        context: () => contextFunction({ event })
-      });
-      if (body.kind === "chunked") {
-        throw new Error("Incremental delivery not implemented");
+  return h3.eventHandler({
+    async handler(event) {
+      if (h3.isMethod(event, "OPTIONS")) {
+        return null;
       }
-      h3.setHeaders(event, Object.fromEntries(headers));
-      event.res.statusCode = status || 200;
-      return body.string;
-    } catch (error) {
-      if (error instanceof SyntaxError) {
-        event.res.statusCode = 400;
-        return error.message;
-      } else {
-        throw error;
+      try {
+        const graphqlRequest = await toGraphqlRequest(event);
+        const { body, headers, status } = await server.executeHTTPGraphQLRequest({
+          httpGraphQLRequest: graphqlRequest,
+          context: () => contextFunction({ event })
+        });
+        if (body.kind === "chunked") {
+          throw new Error("Incremental delivery not implemented");
+        }
+        h3.setHeaders(event, Object.fromEntries(headers));
+        event.res.statusCode = status || 200;
+        return body.string;
+      } catch (error) {
+        if (error instanceof SyntaxError) {
+          event.res.statusCode = 400;
+          return error.message;
+        } else {
+          throw error;
+        }
       }
-    }
+    },
+    websocket: options?.websocket
   });
 }
 async function toGraphqlRequest(event) {
@@ -65,4 +119,6 @@ async function normalizeBody(event) {
   }
 }
 
+exports.defineGraphqlWebSocket = defineGraphqlWebSocket;
+exports.defineGraphqlWebSocketHandler = defineGraphqlWebSocketHandler;
 exports.startServerAndCreateH3Handler = startServerAndCreateH3Handler;

package/dist/index.d.cts

@@ -1,5 +1,32 @@
 import { BaseContext, ContextFunction, ApolloServer } from '@apollo/server';
-import { H3Event, EventHandler } from 'h3';
+import { Hooks, Peer } from 'crossws';
+import { EventHandler, EventHandlerRequest, H3Event } from 'h3';
+import { ConnectionInitMessage, ServerOptions } from 'graphql-ws';
+
+/**
+ * The extra that will be put in the `Context`.
+ *
+ * @category Server/h3
+ */
+interface Extra {
+    /**
+     * The underlying WebSocket peer.
+     */
+    readonly peer: Peer;
+}
+/**
+ * Create the WebSocket hooks to be used with [h3](https://h3.unjs.io/).
+ *
+ * Use this over {@link defineGraphqlWebSocketHandler} if you need more control over the WebSocket server or
+ * if you want to add custom hooks (e.g. for authentication or logging).
+ */
+declare function defineGraphqlWebSocket<P extends ConnectionInitMessage['payload'] = ConnectionInitMessage['payload'], E extends Record<PropertyKey, unknown> = Record<PropertyKey, never>>(options: ServerOptions<P, Extra & Partial<E>>): Partial<Hooks>;
+/**
+ * Create a event handler to be used with [h3](https://h3.unjs.io/).
+ *
+ * @category Server/h3
+ */
+declare function defineGraphqlWebSocketHandler<P extends ConnectionInitMessage['payload'] = ConnectionInitMessage['payload'], E extends Record<PropertyKey, unknown> = Record<PropertyKey, never>>(options: ServerOptions<P, Extra & Partial<E>>): EventHandler<EventHandlerRequest, never>;
 
 type WithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
 interface H3ContextFunctionArgument {
@@ -7,8 +34,9 @@ interface H3ContextFunctionArgument {
 }
 interface H3HandlerOptions<TContext extends BaseContext> {
     context?: ContextFunction<[H3ContextFunctionArgument], TContext>;
+    websocket?: Partial<Hooks>;
 }
 declare function startServerAndCreateH3Handler(server: ApolloServer<BaseContext>, options?: H3HandlerOptions<BaseContext>): EventHandler;
 declare function startServerAndCreateH3Handler<TContext extends BaseContext>(server: ApolloServer<TContext>, options: WithRequired<H3HandlerOptions<TContext>, 'context'>): EventHandler;
 
-export { type H3ContextFunctionArgument, type H3HandlerOptions, startServerAndCreateH3Handler };
+export { type H3ContextFunctionArgument, type H3HandlerOptions, defineGraphqlWebSocket, defineGraphqlWebSocketHandler, startServerAndCreateH3Handler };

package/dist/index.d.mts

@@ -1,5 +1,32 @@
 import { BaseContext, ContextFunction, ApolloServer } from '@apollo/server';
-import { H3Event, EventHandler } from 'h3';
+import { Hooks, Peer } from 'crossws';
+import { EventHandler, EventHandlerRequest, H3Event } from 'h3';
+import { ConnectionInitMessage, ServerOptions } from 'graphql-ws';
+
+/**
+ * The extra that will be put in the `Context`.
+ *
+ * @category Server/h3
+ */
+interface Extra {
+    /**
+     * The underlying WebSocket peer.
+     */
+    readonly peer: Peer;
+}
+/**
+ * Create the WebSocket hooks to be used with [h3](https://h3.unjs.io/).
+ *
+ * Use this over {@link defineGraphqlWebSocketHandler} if you need more control over the WebSocket server or
+ * if you want to add custom hooks (e.g. for authentication or logging).
+ */
+declare function defineGraphqlWebSocket<P extends ConnectionInitMessage['payload'] = ConnectionInitMessage['payload'], E extends Record<PropertyKey, unknown> = Record<PropertyKey, never>>(options: ServerOptions<P, Extra & Partial<E>>): Partial<Hooks>;
+/**
+ * Create a event handler to be used with [h3](https://h3.unjs.io/).
+ *
+ * @category Server/h3
+ */
+declare function defineGraphqlWebSocketHandler<P extends ConnectionInitMessage['payload'] = ConnectionInitMessage['payload'], E extends Record<PropertyKey, unknown> = Record<PropertyKey, never>>(options: ServerOptions<P, Extra & Partial<E>>): EventHandler<EventHandlerRequest, never>;
 
 type WithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
 interface H3ContextFunctionArgument {
@@ -7,8 +34,9 @@ interface H3ContextFunctionArgument {
 }
 interface H3HandlerOptions<TContext extends BaseContext> {
     context?: ContextFunction<[H3ContextFunctionArgument], TContext>;
+    websocket?: Partial<Hooks>;
 }
 declare function startServerAndCreateH3Handler(server: ApolloServer<BaseContext>, options?: H3HandlerOptions<BaseContext>): EventHandler;
 declare function startServerAndCreateH3Handler<TContext extends BaseContext>(server: ApolloServer<TContext>, options: WithRequired<H3HandlerOptions<TContext>, 'context'>): EventHandler;
 
-export { type H3ContextFunctionArgument, type H3HandlerOptions, startServerAndCreateH3Handler };
+export { type H3ContextFunctionArgument, type H3HandlerOptions, defineGraphqlWebSocket, defineGraphqlWebSocketHandler, startServerAndCreateH3Handler };

package/dist/index.d.ts

@@ -1,5 +1,32 @@
 import { BaseContext, ContextFunction, ApolloServer } from '@apollo/server';
-import { H3Event, EventHandler } from 'h3';
+import { Hooks, Peer } from 'crossws';
+import { EventHandler, EventHandlerRequest, H3Event } from 'h3';
+import { ConnectionInitMessage, ServerOptions } from 'graphql-ws';
+
+/**
+ * The extra that will be put in the `Context`.
+ *
+ * @category Server/h3
+ */
+interface Extra {
+    /**
+     * The underlying WebSocket peer.
+     */
+    readonly peer: Peer;
+}
+/**
+ * Create the WebSocket hooks to be used with [h3](https://h3.unjs.io/).
+ *
+ * Use this over {@link defineGraphqlWebSocketHandler} if you need more control over the WebSocket server or
+ * if you want to add custom hooks (e.g. for authentication or logging).
+ */
+declare function defineGraphqlWebSocket<P extends ConnectionInitMessage['payload'] = ConnectionInitMessage['payload'], E extends Record<PropertyKey, unknown> = Record<PropertyKey, never>>(options: ServerOptions<P, Extra & Partial<E>>): Partial<Hooks>;
+/**
+ * Create a event handler to be used with [h3](https://h3.unjs.io/).
+ *
+ * @category Server/h3
+ */
+declare function defineGraphqlWebSocketHandler<P extends ConnectionInitMessage['payload'] = ConnectionInitMessage['payload'], E extends Record<PropertyKey, unknown> = Record<PropertyKey, never>>(options: ServerOptions<P, Extra & Partial<E>>): EventHandler<EventHandlerRequest, never>;
 
 type WithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
 interface H3ContextFunctionArgument {
@@ -7,8 +34,9 @@ interface H3ContextFunctionArgument {
 }
 interface H3HandlerOptions<TContext extends BaseContext> {
     context?: ContextFunction<[H3ContextFunctionArgument], TContext>;
+    websocket?: Partial<Hooks>;
 }
 declare function startServerAndCreateH3Handler(server: ApolloServer<BaseContext>, options?: H3HandlerOptions<BaseContext>): EventHandler;
 declare function startServerAndCreateH3Handler<TContext extends BaseContext>(server: ApolloServer<TContext>, options: WithRequired<H3HandlerOptions<TContext>, 'context'>): EventHandler;
 
-export { type H3ContextFunctionArgument, type H3HandlerOptions, startServerAndCreateH3Handler };
+export { type H3ContextFunctionArgument, type H3HandlerOptions, defineGraphqlWebSocket, defineGraphqlWebSocketHandler, startServerAndCreateH3Handler };

package/dist/index.mjs

@@ -1,34 +1,88 @@
 import { HeaderMap } from '@apollo/server';
-import { eventHandler, isMethod, setHeaders, getHeaders, readBody } from 'h3';
+import { defineWebSocket, defineWebSocketHandler, eventHandler, isMethod, setHeaders, getHeaders, readBody } from 'h3';
+import { makeServer, GRAPHQL_TRANSPORT_WS_PROTOCOL } from 'graphql-ws';
+
+function defineGraphqlWebSocket(options) {
+  const server = makeServer(options);
+  const peers = /* @__PURE__ */ new WeakMap();
+  return defineWebSocket({
+    open(peer) {
+      const client = {
+        handleMessage: () => {
+          throw new Error("Message received before handler was registered");
+        },
+        closed: () => {
+          throw new Error("Closed before handler was registered");
+        }
+      };
+      client.closed = server.opened(
+        {
+          // TODO: use protocol on socket once h3 exposes it
+          // https://github.com/unjs/crossws/issues/31
+          protocol: GRAPHQL_TRANSPORT_WS_PROTOCOL,
+          send: (message) => {
+            if (peers.has(peer)) {
+              peer.send(message);
+            }
+          },
+          close: (_code, _reason) => {
+            if (peers.has(peer)) ;
+          },
+          onMessage: (cb) => client.handleMessage = cb
+        },
+        { peer }
+      );
+      peers.set(peer, client);
+    },
+    message(peer, message) {
+      const client = peers.get(peer);
+      if (!client)
+        throw new Error("Message received for a missing client");
+      return client.handleMessage(message.text());
+    },
+    close(peer, details) {
+      const client = peers.get(peer);
+      if (!client)
+        throw new Error("Closing a missing client");
+      return client.closed(details.code ?? 1e3, details.reason ?? "");
+    }
+  });
+}
+function defineGraphqlWebSocketHandler(options) {
+  return defineWebSocketHandler(defineGraphqlWebSocket(options));
+}
 
 function startServerAndCreateH3Handler(server, options) {
   server.startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests();
   const defaultContext = () => Promise.resolve({});
   const contextFunction = options?.context ?? defaultContext;
-  return eventHandler(async (event) => {
-    if (isMethod(event, "OPTIONS")) {
-      return null;
-    }
-    try {
-      const graphqlRequest = await toGraphqlRequest(event);
-      const { body, headers, status } = await server.executeHTTPGraphQLRequest({
-        httpGraphQLRequest: graphqlRequest,
-        context: () => contextFunction({ event })
-      });
-      if (body.kind === "chunked") {
-        throw new Error("Incremental delivery not implemented");
+  return eventHandler({
+    async handler(event) {
+      if (isMethod(event, "OPTIONS")) {
+        return null;
       }
-      setHeaders(event, Object.fromEntries(headers));
-      event.res.statusCode = status || 200;
-      return body.string;
-    } catch (error) {
-      if (error instanceof SyntaxError) {
-        event.res.statusCode = 400;
-        return error.message;
-      } else {
-        throw error;
+      try {
+        const graphqlRequest = await toGraphqlRequest(event);
+        const { body, headers, status } = await server.executeHTTPGraphQLRequest({
+          httpGraphQLRequest: graphqlRequest,
+          context: () => contextFunction({ event })
+        });
+        if (body.kind === "chunked") {
+          throw new Error("Incremental delivery not implemented");
+        }
+        setHeaders(event, Object.fromEntries(headers));
+        event.res.statusCode = status || 200;
+        return body.string;
+      } catch (error) {
+        if (error instanceof SyntaxError) {
+          event.res.statusCode = 400;
+          return error.message;
+        } else {
+          throw error;
+        }
       }
-    }
+    },
+    websocket: options?.websocket
   });
 }
 async function toGraphqlRequest(event) {
@@ -63,4 +117,4 @@ async function normalizeBody(event) {
   }
 }
 
-export { startServerAndCreateH3Handler };
+export { defineGraphqlWebSocket, defineGraphqlWebSocketHandler, startServerAndCreateH3Handler };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@as-integrations/h3",
-  "version": "1.1.6",
+  "version": "1.2.1",
   "description": "An Apollo Server integration for use with h3 or Nuxt",
   "repository": "github:apollo-server-integrations/apollo-server-integration-h3",
   "license": "MIT",
@@ -8,6 +8,7 @@
   "type": "module",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     }
@@ -20,38 +21,56 @@
   ],
   "peerDependencies": {
     "@apollo/server": "^4.1.1",
-    "h3": "^1.8.0"
+    "h3": "^1.11.0",
+    "graphql": "^16.0.0",
+    "graphql-ws": "^5.0.0",
+    "crossws": "^0.2.4"
+  },
+  "peerDependenciesMeta": {
+    "graphql-ws": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@apollo/server": "^4.9.1",
-    "@apollo/server-integration-testsuite": "^4.9.1",
+    "@apollo/server": "^4.10.4",
+    "@apollo/server-integration-testsuite": "^4.10.4",
     "@apollo/utils.withrequired": "^3.0.0",
-    "@jest/globals": "^29.6.3",
-    "@nuxtjs/eslint-config-typescript": "^12.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.4.1",
-    "@typescript-eslint/parser": "^6.4.1",
-    "@vitest/coverage-c8": "^0.33.0",
-    "eslint": "^8.47.0",
-    "eslint-config-prettier": "^9.0.0",
-    "eslint-plugin-unused-imports": "^3.0.0",
-    "graphql": "^16.8.0",
-    "h3": "^1.8.0",
-    "jest": "^29.6.3",
-    "prettier": "^3.0.2",
+    "@graphql-tools/schema": "^10.0.3",
+    "@jest/globals": "^29.7.0",
+    "@typescript-eslint/parser": "^7.16.0",
+    "crossws": "^0.2.4",
+    "@vitest/coverage-v8": "^2.0.1",
+    "eslint": "^9.6.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-config-unjs": "^0.3.2",
+    "eslint-plugin-unused-imports": "^4.0.0",
+    "graphql": "^16.9.0",
+    "graphql-subscriptions": "^2.0.0",
+    "graphql-ws": "^5.15.0",
+    "h3": "^1.12.0",
+    "jest": "^29.7.0",
+    "listhen": "^1.7.2",
+    "prettier": "^3.3.2",
     "standard-version": "^9.5.0",
-    "ts-jest": "^29.1.1",
-    "typescript": "^5.1.6",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.5.3",
     "unbuild": "^2.0.0",
-    "vitest": "^0.34.2"
+    "vitest": "^2.0.1"
+  },
+  "engines": {
+    "node": "^16.10.0 || >=18.0.0"
   },
-  "packageManager": "pnpm@8.6.12",
   "scripts": {
+    "dev:prepare": "unbuild --stub",
     "build": "unbuild",
     "test": "vitest dev",
     "test:integration": "jest",
+    "test:types": "tsc --noEmit --skipLibCheck",
     "lint": "pnpm lint:eslint && pnpm lint:prettier",
-    "lint:eslint": "eslint --ext .ts,.js,.vue,.graphql --ignore-path .gitignore --report-unused-disable-directives .",
+    "lint:eslint": "eslint --report-unused-disable-directives .",
     "lint:prettier": "prettier --check --ignore-path .gitignore . '!pnpm-lock.yaml'",
+    "example:simple": "listhen -w --open ./examples/simple.ts",
+    "example:websocket": "listhen -w --ws --open ./examples/websocket.ts",
     "release": "pnpm test && standard-version && git push --follow-tags && pnpm publish"
   }
 }