graphql-http 1.18.0 → 1.20.0

package/README.md

@@ -61,7 +61,7 @@ import { schema } from './previous-step';
 // Create the GraphQL over HTTP Node request handler
 const handler = createHandler({ schema });
 
-// Create a HTTP server using the listner on `/graphql`
+// Create a HTTP server using the listener on `/graphql`
 const server = http.createServer((req, res) => {
   if (req.url.startsWith('/graphql')) {
     handler(req, res);
@@ -158,6 +158,21 @@ app.listen({ port: 4000 });
 console.log('Listening to port 4000');
 ```
 
+##### With [`uWebSockets.js`](https://github.com/uNetworking/uWebSockets.js)
+
+```js
+import uWS from 'uWebSockets.js'; // yarn add uWebSockets.js@uNetworking/uWebSockets.js#<version>
+import { createHandler } from 'graphql-http/lib/use/uWebSockets';
+import { schema } from './previous-step';
+
+uWS
+  .App()
+  .any('/graphql', createHandler({ schema }))
+  .listen(4000, () => {
+    console.log('Listening to port 4000');
+  });
+```
+
 ##### With [`Deno`](https://deno.land/)
 
 ```ts
@@ -545,8 +560,8 @@ const client = createClient({
 
 </details>
 
-<details id="migrating-express-grpahql">
-<summary><a href="#migrating-express-grpahql">🔗</a> Server handler migration from <a href="https://github.com/graphql/express-graphql">express-graphql</a></summary>
+<details id="migrating-express-graphql">
+<summary><a href="#migrating-express-graphql">🔗</a> Server handler migration from <a href="https://github.com/graphql/express-graphql">express-graphql</a></summary>
 
 ```diff
 import express from 'express';
@@ -615,7 +630,7 @@ const handler = createHandler({
   context: async (req, args) => {
     return getDynamicContext(req, args);
   },
-  // or static context by supplying the value direcly
+  // or static context by supplying the value directly
 });
 ```
 
@@ -710,6 +725,78 @@ console.log('Listening to port 4000');
 
 </details>
 
+<details id="graphql-upload-http">
+<summary><a href="#graphql-upload-http">🔗</a> Server handler usage with <a href="https://github.com/jaydenseric/graphql-upload">graphql-upload</a> and <a href="https://nodejs.org/api/http.html">http</a></summary>
+
+```js
+import http from 'http';
+import { createHandler } from 'graphql-http/lib/use/http';
+import processRequest from 'graphql-upload/processRequest.mjs'; // yarn add graphql-upload
+import { schema } from './my-graphql';
+
+const handler = createHandler({
+  schema,
+  async parseRequestParams(req) {
+    const params = await processRequest(req.raw, req.context.res);
+    if (Array.isArray(params)) {
+      throw new Error('Batching is not supported');
+    }
+    return {
+      ...params,
+      // variables must be an object as per the GraphQL over HTTP spec
+      variables: Object(params.variables),
+    };
+  },
+});
+
+const server = http.createServer((req, res) => {
+  if (req.url.startsWith('/graphql')) {
+    handler(req, res);
+  } else {
+    res.writeHead(404).end();
+  }
+});
+
+server.listen(4000);
+console.log('Listening to port 4000');
+```
+
+</details>
+
+<details id="graphql-upload-express">
+<summary><a href="#graphql-upload-express">🔗</a> Server handler usage with <a href="https://github.com/jaydenseric/graphql-upload">graphql-upload</a> and <a href="https://expressjs.com/">express</a></summary>
+
+```js
+import express from 'express'; // yarn add express
+import { createHandler } from 'graphql-http/lib/use/express';
+import processRequest from 'graphql-upload/processRequest.mjs'; // yarn add graphql-upload
+import { schema } from './my-graphql';
+
+const app = express();
+app.all(
+  '/graphql',
+  createHandler({
+    schema,
+    async parseRequestParams(req) {
+      const params = await processRequest(req.raw, req.context.res);
+      if (Array.isArray(params)) {
+        throw new Error('Batching is not supported');
+      }
+      return {
+        ...params,
+        // variables must be an object as per the GraphQL over HTTP spec
+        variables: Object(params.variables),
+      };
+    },
+  }),
+);
+
+app.listen({ port: 4000 });
+console.log('Listening to port 4000');
+```
+
+</details>
+
 <details id="audit-jest">
 <summary><a href="#audit-jest">🔗</a> Audit for servers usage in <a href="https://jestjs.io">Jest</a> environment</summary>
 
@@ -768,7 +855,7 @@ Put the above contents in a file and run it with `deno test --allow-net`.
 
 ## Only [GraphQL over HTTP](https://graphql.github.io/graphql-over-http/)
 
-This is the official [GraphQL over HTTP spec](https://graphql.github.io/graphql-over-http/) reference implementation and as such follows the specification strictly without any additional features (like file uploads, @stream/@defer directives and subscriptions).
+This is the official [GraphQL over HTTP spec](https://graphql.github.io/graphql-over-http/) reference implementation and as such follows the specification strictly without any additional features (like playgrounds or GUIs, file uploads, @stream/@defer directives and subscriptions).
 
 Having said this, graphql-http is mostly aimed for library authors and simple server setups, where the requirements are exact to what the aforementioned spec offers.
 

package/lib/client.d.mts

@@ -76,7 +76,7 @@ export interface ClientOptions {
      *
      * You may implement your own waiting strategy by timing the resolution of the returned promise.
      *
-     * Useful for retrying requests that failed because the service is temporarely unavailable.
+     * Useful for retrying requests that failed because the service is temporarily unavailable.
      *
      * `retries` argument counts actual retries, so it will begin with
      * 0 after the first failed request.
@@ -135,7 +135,7 @@ export declare function createClient(options: ClientOptions): Client;
  */
 export declare class NetworkError<Response extends ResponseLike = ResponseLike> extends Error {
     /**
-     * The underlyig response thats considered an error.
+     * The underlying response thats considered an error.
      *
      * Will be undefined when no response is received,
      * instead an unexpected network error.

package/lib/client.d.ts

@@ -76,7 +76,7 @@ export interface ClientOptions {
      *
      * You may implement your own waiting strategy by timing the resolution of the returned promise.
      *
-     * Useful for retrying requests that failed because the service is temporarely unavailable.
+     * Useful for retrying requests that failed because the service is temporarily unavailable.
      *
      * `retries` argument counts actual retries, so it will begin with
      * 0 after the first failed request.
@@ -135,7 +135,7 @@ export declare function createClient(options: ClientOptions): Client;
  */
 export declare class NetworkError<Response extends ResponseLike = ResponseLike> extends Error {
     /**
-     * The underlyig response thats considered an error.
+     * The underlying response thats considered an error.
      *
      * Will be undefined when no response is received,
      * instead an unexpected network error.

package/lib/common.d.mts

@@ -11,10 +11,10 @@
  * @category Common
  */
 export interface RequestParams {
-    operationName?: string | undefined;
+    operationName?: string | null | undefined;
     query: string;
-    variables?: Record<string, unknown> | undefined;
-    extensions?: Record<string, unknown> | undefined;
+    variables?: Record<string, unknown> | null | undefined;
+    extensions?: Record<string, unknown> | null | undefined;
 }
 /**
  * A representation of any set of values over any amount of time.
@@ -24,7 +24,7 @@ export interface RequestParams {
 export interface Sink<T = unknown> {
     /** Next value arriving. */
     next(value: T): void;
-    /** An error that has occured. This function "closes" the sink. */
+    /** An error that has occurred. This function "closes" the sink. */
     error(error: unknown): void;
     /** The sink has completed. This function "closes" the sink. */
     complete(): void;

package/lib/common.d.ts

@@ -11,10 +11,10 @@
  * @category Common
  */
 export interface RequestParams {
-    operationName?: string | undefined;
+    operationName?: string | null | undefined;
     query: string;
-    variables?: Record<string, unknown> | undefined;
-    extensions?: Record<string, unknown> | undefined;
+    variables?: Record<string, unknown> | null | undefined;
+    extensions?: Record<string, unknown> | null | undefined;
 }
 /**
  * A representation of any set of values over any amount of time.
@@ -24,7 +24,7 @@ export interface RequestParams {
 export interface Sink<T = unknown> {
     /** Next value arriving. */
     next(value: T): void;
-    /** An error that has occured. This function "closes" the sink. */
+    /** An error that has occurred. This function "closes" the sink. */
     error(error: unknown): void;
     /** The sink has completed. This function "closes" the sink. */
     complete(): void;

package/lib/handler.d.mts

@@ -84,16 +84,10 @@ export interface ResponseInit {
  * @category Server
  */
 export type Response = readonly [body: ResponseBody | null, init: ResponseInit];
-/**
- * Checks whether the passed value is the `graphql-http` server agnostic response.
- *
- * @category Server
- */
-export declare function isResponse(val: unknown): val is Response;
 /**
  * A concrete GraphQL execution context value type.
  *
- * Mainly used because TypeScript collapes unions
+ * Mainly used because TypeScript collapses unions
  * with `any` or `unknown` to `any` or `unknown`. So,
  * we use a custom type to allow definitions such as
  * the `context` server option.
@@ -107,6 +101,25 @@ export type OperationContext = Record<PropertyKey, unknown> | symbol | number |
  * @category Server
  */
 export type FormatError = (err: Readonly<GraphQLError | Error>) => GraphQLError | Error;
+/**
+ * The request parser for an incoming GraphQL request. It parses and validates the
+ * request itself, including the request method and the content-type of the body.
+ *
+ * In case you are extending the server to handle more request types, this is the
+ * perfect place to do so.
+ *
+ * If an error is thrown, it will be formatted using the provided {@link FormatError}
+ * and handled following the spec to be gracefully reported to the client.
+ *
+ * Throwing an instance of `Error` will _always_ have the client respond with a `400: Bad Request`
+ * and the error's message in the response body; however, if an instance of `GraphQLError` is thrown,
+ * it will be reported depending on the accepted content-type.
+ *
+ * If you return nothing, the default parser will be used instead.
+ *
+ * @category Server
+ */
+export type ParseRequestParams<RequestRaw = unknown, RequestContext = unknown> = (req: Request<RequestRaw, RequestContext>) => Promise<RequestParams | Response | void> | RequestParams | Response | void;
 /** @category Server */
 export type OperationArgs<Context extends OperationContext = undefined> = ExecutionArgs & {
     contextValue?: Context;
@@ -223,15 +236,21 @@ export interface HandlerOptions<RequestRaw = unknown, RequestContext = unknown,
     onOperation?: (req: Request<RequestRaw, RequestContext>, args: OperationArgs<Context>, result: ExecutionResult) => Promise<ExecutionResult | Response | void> | ExecutionResult | Response | void;
     /**
      * Format handled errors to your satisfaction. Either GraphQL errors
-     * or safe request processing errors are meant by "handleded errors".
+     * or safe request processing errors are meant by "handled errors".
      *
-     * If multiple errors have occured, all of them will be mapped using
+     * If multiple errors have occurred, all of them will be mapped using
      * this formatter.
      */
     formatError?: FormatError;
+    /**
+     * The request parser for an incoming GraphQL request.
+     *
+     * Read more about it in {@link ParseRequestParams}.
+     */
+    parseRequestParams?: ParseRequestParams<RequestRaw, RequestContext>;
 }
 /**
- * The ready-to-use handler. Simply plug it in your favourite HTTP framework
+ * The ready-to-use handler. Simply plug it in your favorite HTTP framework
  * and enjoy.
  *
  * Errors thrown from **any** of the provided options or callbacks (or even due to
@@ -243,7 +262,7 @@ export interface HandlerOptions<RequestRaw = unknown, RequestContext = unknown,
 export type Handler<RequestRaw = unknown, RequestContext = unknown> = (req: Request<RequestRaw, RequestContext>) => Promise<Response>;
 /**
  * Makes a GraphQL over HTTP spec compliant server handler. The handler can
- * be used with your favourite server library.
+ * be used with your favorite server library.
  *
  * Beware that the handler resolves only after the whole operation completes.
  *
@@ -297,30 +316,3 @@ export type Handler<RequestRaw = unknown, RequestContext = unknown> = (req: Requ
  * @category Server
  */
 export declare function createHandler<RequestRaw = unknown, RequestContext = unknown, Context extends OperationContext = undefined>(options: HandlerOptions<RequestRaw, RequestContext, Context>): Handler<RequestRaw, RequestContext>;
-/**
- * Request's Media-Type that the server accepts.
- *
- * @category Server
- */
-export type AcceptableMediaType = 'application/graphql-response+json' | 'application/json';
-/**
- * Inspects the request and detects the appropriate/acceptable Media-Type
- * looking at the `Accept` header while complying with the GraphQL over HTTP spec.
- *
- * @category Server
- */
-export declare function getAcceptableMediaType(acceptHeader: string | null | undefined): AcceptableMediaType | null;
-/**
- * Creates an appropriate GraphQL over HTTP response following the provided arguments.
- *
- * If the first argument is an `ExecutionResult`, the operation will be treated as "successful".
- *
- * If the first argument is (an array of) `GraphQLError`, or an `ExecutionResult` without the `data` field, it will be treated
- * the response will be constructed with the help of `acceptedMediaType` complying with the GraphQL over HTTP spec.
- *
- * If the first argument is an `Error`, the operation will be treated as a bad request responding with `400: Bad Request` and the
- * error will be present in the `ExecutionResult` style.
- *
- * @category Server
- */
-export declare function makeResponse(resultOrErrors: Readonly<ExecutionResult> | Readonly<GraphQLError[]> | Readonly<GraphQLError> | Readonly<Error>, acceptedMediaType: AcceptableMediaType, formatError: FormatError): Response;

package/lib/handler.d.ts

@@ -84,16 +84,10 @@ export interface ResponseInit {
  * @category Server
  */
 export type Response = readonly [body: ResponseBody | null, init: ResponseInit];
-/**
- * Checks whether the passed value is the `graphql-http` server agnostic response.
- *
- * @category Server
- */
-export declare function isResponse(val: unknown): val is Response;
 /**
  * A concrete GraphQL execution context value type.
  *
- * Mainly used because TypeScript collapes unions
+ * Mainly used because TypeScript collapses unions
  * with `any` or `unknown` to `any` or `unknown`. So,
  * we use a custom type to allow definitions such as
  * the `context` server option.
@@ -107,6 +101,25 @@ export type OperationContext = Record<PropertyKey, unknown> | symbol | number |
  * @category Server
  */
 export type FormatError = (err: Readonly<GraphQLError | Error>) => GraphQLError | Error;
+/**
+ * The request parser for an incoming GraphQL request. It parses and validates the
+ * request itself, including the request method and the content-type of the body.
+ *
+ * In case you are extending the server to handle more request types, this is the
+ * perfect place to do so.
+ *
+ * If an error is thrown, it will be formatted using the provided {@link FormatError}
+ * and handled following the spec to be gracefully reported to the client.
+ *
+ * Throwing an instance of `Error` will _always_ have the client respond with a `400: Bad Request`
+ * and the error's message in the response body; however, if an instance of `GraphQLError` is thrown,
+ * it will be reported depending on the accepted content-type.
+ *
+ * If you return nothing, the default parser will be used instead.
+ *
+ * @category Server
+ */
+export type ParseRequestParams<RequestRaw = unknown, RequestContext = unknown> = (req: Request<RequestRaw, RequestContext>) => Promise<RequestParams | Response | void> | RequestParams | Response | void;
 /** @category Server */
 export type OperationArgs<Context extends OperationContext = undefined> = ExecutionArgs & {
     contextValue?: Context;
@@ -223,15 +236,21 @@ export interface HandlerOptions<RequestRaw = unknown, RequestContext = unknown,
     onOperation?: (req: Request<RequestRaw, RequestContext>, args: OperationArgs<Context>, result: ExecutionResult) => Promise<ExecutionResult | Response | void> | ExecutionResult | Response | void;
     /**
      * Format handled errors to your satisfaction. Either GraphQL errors
-     * or safe request processing errors are meant by "handleded errors".
+     * or safe request processing errors are meant by "handled errors".
      *
-     * If multiple errors have occured, all of them will be mapped using
+     * If multiple errors have occurred, all of them will be mapped using
      * this formatter.
      */
     formatError?: FormatError;
+    /**
+     * The request parser for an incoming GraphQL request.
+     *
+     * Read more about it in {@link ParseRequestParams}.
+     */
+    parseRequestParams?: ParseRequestParams<RequestRaw, RequestContext>;
 }
 /**
- * The ready-to-use handler. Simply plug it in your favourite HTTP framework
+ * The ready-to-use handler. Simply plug it in your favorite HTTP framework
  * and enjoy.
  *
  * Errors thrown from **any** of the provided options or callbacks (or even due to
@@ -243,7 +262,7 @@ export interface HandlerOptions<RequestRaw = unknown, RequestContext = unknown,
 export type Handler<RequestRaw = unknown, RequestContext = unknown> = (req: Request<RequestRaw, RequestContext>) => Promise<Response>;
 /**
  * Makes a GraphQL over HTTP spec compliant server handler. The handler can
- * be used with your favourite server library.
+ * be used with your favorite server library.
  *
  * Beware that the handler resolves only after the whole operation completes.
  *
@@ -297,30 +316,3 @@ export type Handler<RequestRaw = unknown, RequestContext = unknown> = (req: Requ
  * @category Server
  */
 export declare function createHandler<RequestRaw = unknown, RequestContext = unknown, Context extends OperationContext = undefined>(options: HandlerOptions<RequestRaw, RequestContext, Context>): Handler<RequestRaw, RequestContext>;
-/**
- * Request's Media-Type that the server accepts.
- *
- * @category Server
- */
-export type AcceptableMediaType = 'application/graphql-response+json' | 'application/json';
-/**
- * Inspects the request and detects the appropriate/acceptable Media-Type
- * looking at the `Accept` header while complying with the GraphQL over HTTP spec.
- *
- * @category Server
- */
-export declare function getAcceptableMediaType(acceptHeader: string | null | undefined): AcceptableMediaType | null;
-/**
- * Creates an appropriate GraphQL over HTTP response following the provided arguments.
- *
- * If the first argument is an `ExecutionResult`, the operation will be treated as "successful".
- *
- * If the first argument is (an array of) `GraphQLError`, or an `ExecutionResult` without the `data` field, it will be treated
- * the response will be constructed with the help of `acceptedMediaType` complying with the GraphQL over HTTP spec.
- *
- * If the first argument is an `Error`, the operation will be treated as a bad request responding with `400: Bad Request` and the
- * error will be present in the `ExecutionResult` style.
- *
- * @category Server
- */
-export declare function makeResponse(resultOrErrors: Readonly<ExecutionResult> | Readonly<GraphQLError[]> | Readonly<GraphQLError> | Readonly<Error>, acceptedMediaType: AcceptableMediaType, formatError: FormatError): Response;