graphql-http 1.0.0 → 1.3.0

package/README.md

@@ -3,7 +3,7 @@
 
   <h3>graphql-http</h3>
 
-  <h6>Simple, plugable, zero-dependency, <a href="https://graphql.github.io/graphql-over-http">GraphQL over HTTP Protocol</a> compliant server and client.</h6>
+  <h6>Simple, pluggable, zero-dependency, <a href="https://graphql.github.io/graphql-over-http">GraphQL over HTTP Protocol</a> compliant server and client.</h6>
 
 [![Continuous integration](https://github.com/enisdenjo/graphql-http/workflows/Continuous%20integration/badge.svg)](https://github.com/enisdenjo/graphql-http/actions?query=workflow%3A%22Continuous+integration%22) [![graphql-http](https://img.shields.io/npm/v/graphql-http.svg?label=graphql-http&logo=npm)](https://www.npmjs.com/package/graphql-http)
 
@@ -207,6 +207,43 @@ fastify.listen(4000);
 console.log('Listening to port 4000');
 ```
 
+##### With [`Deno`](https://deno.land/)
+
+```ts
+import { serve } from 'https://deno.land/std@0.151.0/http/server.ts';
+import { createHandler } from 'https://esm.sh/graphql-http';
+import { schema } from './previous-step';
+
+// Create the GraphQL over HTTP handler
+const handler = createHandler<Request>({ schema });
+
+// Start serving on `/graphql` using the handler
+await serve(
+  async (req: Request) => {
+    const [path, _search] = req.url.split('?');
+    if (!path.endsWith('/graphql')) {
+      return new Response(null, { status: 404, statusText: 'Not Found' });
+    }
+
+    const headers: Record<string, string> = {};
+    req.headers.forEach((value, key) => (headers[key] = value));
+    const [body, init] = await handler({
+      url: req.url,
+      method: req.method,
+      headers,
+      body: await req.text(),
+      raw: req,
+    });
+    return new Response(body, init);
+  },
+  {
+    port: 4000,
+  },
+);
+
+// Listening to port 4000
+```
+
 #### Use the client
 
 ```js
@@ -515,6 +552,21 @@ const client = createClient({
 
 </details>
 
+<details id="deno-client">
+<summary><a href="#deno-client">🔗</a> Client usage in Deno</summary>
+
+```js
+import { createClient } from 'graphql-http';
+
+const client = createClient({
+  url: 'http://deno.earth:4000/graphql',
+});
+
+// consider other recipes for usage inspiration
+```
+
+</details>
+
 <details id="auth">
 <summary><a href="#auth">🔗</a> Server handler usage with authentication</summary>
 

package/lib/client.d.ts

@@ -3,7 +3,7 @@
  * client
  *
  */
-import { ExecutionResult } from 'graphql';
+import type { ExecutionResult } from 'graphql';
 import { RequestParams, Sink } from './common';
 /** This file is the entry point for browsers, re-export common elements. */
 export * from './common';
@@ -18,8 +18,11 @@ export interface ClientOptions {
      *
      * A good use-case for having a function is when using the URL for authentication,
      * where subsequent requests (due to auth) may have a refreshed identity token.
+     *
+     * Function receives the request params. Useful for example, to ease up debugging and DevTools
+     * navigation you might want to use the operation name in the URL's search params (`/graphql?MyQuery`).
      */
-    url: string | (() => Promise<string> | string);
+    url: string | ((request: RequestParams) => Promise<string> | string);
     /**
      * Indicates whether the user agent should send cookies from the other domain in the case
      * of cross-origin requests.
@@ -140,7 +143,12 @@ export declare class NetworkError<Response extends ResponseLike = ResponseLike>
     response: Response | undefined;
     constructor(msgOrErrOrResponse: string | Error | Response);
 }
-interface ResponseLike {
+/**
+ * Concrete interface a response needs to implement for the client.
+ *
+ * @category Client
+ */
+export interface ResponseLike {
     readonly ok: boolean;
     readonly status: number;
     readonly statusText: string;

package/lib/client.js

@@ -91,7 +91,7 @@ function createClient(options) {
                     }
                     try {
                         const url = typeof options.url === 'function'
-                            ? await options.url()
+                            ? await options.url(request)
                             : options.url;
                         if (control.signal.aborted)
                             return;
@@ -105,7 +105,7 @@ function createClient(options) {
                             res = await fetchFn(url, {
                                 signal: control.signal,
                                 method: 'POST',
-                                headers: Object.assign(Object.assign({}, headers), { 'content-type': 'application/json; charset=utf-8', accept: 'application/graphql+json, application/json' }),
+                                headers: Object.assign(Object.assign({}, headers), { 'content-type': 'application/json; charset=utf-8', accept: 'application/graphql-response+json, application/json' }),
                                 credentials,
                                 referrer,
                                 referrerPolicy,
@@ -122,7 +122,7 @@ function createClient(options) {
                         const contentType = res.headers.get('content-type');
                         if (!contentType)
                             throw new Error('Missing response content-type');
-                        if (!contentType.includes('application/graphql+json') &&
+                        if (!contentType.includes('application/graphql-response+json') &&
                             !contentType.includes('application/json')) {
                             throw new Error(`Unsupported response content-type ${contentType}`);
                         }

package/lib/client.mjs

@@ -74,7 +74,7 @@ export function createClient(options) {
                     }
                     try {
                         const url = typeof options.url === 'function'
-                            ? await options.url()
+                            ? await options.url(request)
                             : options.url;
                         if (control.signal.aborted)
                             return;
@@ -88,7 +88,7 @@ export function createClient(options) {
                             res = await fetchFn(url, {
                                 signal: control.signal,
                                 method: 'POST',
-                                headers: Object.assign(Object.assign({}, headers), { 'content-type': 'application/json; charset=utf-8', accept: 'application/graphql+json, application/json' }),
+                                headers: Object.assign(Object.assign({}, headers), { 'content-type': 'application/json; charset=utf-8', accept: 'application/graphql-response+json, application/json' }),
                                 credentials,
                                 referrer,
                                 referrerPolicy,
@@ -105,7 +105,7 @@ export function createClient(options) {
                         const contentType = res.headers.get('content-type');
                         if (!contentType)
                             throw new Error('Missing response content-type');
-                        if (!contentType.includes('application/graphql+json') &&
+                        if (!contentType.includes('application/graphql-response+json') &&
                             !contentType.includes('application/json')) {
                             throw new Error(`Unsupported response content-type ${contentType}`);
                         }

package/lib/common.d.ts

@@ -3,42 +3,6 @@
  * common
  *
  */
-/**
- * Concrete interface that the headers map should implement.
- *
- * @category Common
- */
-export interface Headers {
-    accept?: string | undefined;
-    allow?: string | undefined;
-    'content-type'?: string | undefined;
-    /**
-     * Always an array in Node. Duplicates are added to it.
-     * Not necessarily true for other environments, make sure
-     * to check the type during runtime.
-     */
-    'set-cookie'?: string | string[] | undefined;
-    [key: string]: string | string[] | undefined;
-}
-/**
- * Server agnostic request interface containing the raw request
- * which is server dependant.
- *
- * @category Common
- */
-export interface Request<RawRequest> {
-    readonly method: string;
-    readonly url: string;
-    readonly headers: Headers;
-    readonly body: string | Record<string, unknown> | null;
-    /**
-     * The raw request itself from the implementing server.
-     *
-     * For example: `express.Request` when using Express, or maybe
-     * `http.IncomingMessage` when just using Node with `http.createServer`.
-     */
-    readonly raw: RawRequest;
-}
 /**
  * Parameters for GraphQL's request for execution.
  *
@@ -52,37 +16,6 @@ export interface RequestParams {
     variables?: Record<string, unknown> | undefined;
     extensions?: Record<string, unknown> | undefined;
 }
-/**
- * Server agnostic response body returned from `graphql-http` needing
- * to be coerced to the server implementation in use.
- *
- * @category Common
- */
-export declare type ResponseBody = string;
-/**
- * Server agnostic response options (ex. status and headers) returned from
- * `graphql-http` needing to be coerced to the server implementation in use.
- *
- * @category Common
- */
-export interface ResponseInit {
-    readonly status: number;
-    readonly statusText?: string;
-    readonly headers?: Headers;
-}
-/**
- * Server agnostic response returned from `graphql-http` containing the
- * body and init options needing to be coerced to the server implementation in use.
- *
- * @category Common
- */
-export declare type Response = readonly [body: ResponseBody | null, init: ResponseInit];
-/**
- * Checks whether the passed value is the `graphql-http` server agnostic response.
- *
- * @category Common
- */
-export declare function isResponse(val: unknown): val is Response;
 /**
  * A representation of any set of values over any amount of time.
  *

package/lib/common.js

@@ -5,15 +5,3 @@
  *
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isResponse = void 0;
-const utils_1 = require("./utils");
-/**
- * Checks whether the passed value is the `graphql-http` server agnostic response.
- *
- * @category Common
- */
-function isResponse(val) {
-    // TODO: make sure the contents of init match ResponseInit
-    return Array.isArray(val) && typeof val[0] === 'string' && (0, utils_1.isObject)(val[1]);
-}
-exports.isResponse = isResponse;

package/lib/common.mjs

@@ -3,13 +3,4 @@
  * common
  *
  */
-import { isObject } from './utils.mjs';
-/**
- * Checks whether the passed value is the `graphql-http` server agnostic response.
- *
- * @category Common
- */
-export function isResponse(val) {
-    // TODO: make sure the contents of init match ResponseInit
-    return Array.isArray(val) && typeof val[0] === 'string' && isObject(val[1]);
-}
+export {};

package/lib/handler.d.ts

@@ -3,8 +3,89 @@
  * handler
  *
  */
-import { ExecutionArgs, ExecutionResult, GraphQLSchema, validate as graphqlValidate, execute as graphqlExecute } from 'graphql';
-import { Request, RequestParams, Response } from './common';
+import { ExecutionArgs, ExecutionResult, GraphQLSchema, validate as graphqlValidate, execute as graphqlExecute, parse as graphqlParse, getOperationAST as graphqlGetOperationAST, GraphQLError } from 'graphql';
+import { RequestParams } from './common';
+/**
+ * The incoming request headers the implementing server should provide.
+ *
+ * @category Common
+ */
+export interface RequestHeaders {
+    accept?: string | undefined;
+    allow?: string | undefined;
+    'content-type'?: string | undefined;
+    /**
+     * Always an array in Node. Duplicates are added to it.
+     * Not necessarily true for other environments, make sure
+     * to check the type during runtime.
+     */
+    'set-cookie'?: string | string[] | undefined;
+    [key: string]: string | string[] | undefined;
+}
+/**
+ * Server agnostic request interface containing the raw request
+ * which is server dependant.
+ *
+ * @category Common
+ */
+export interface Request<RawRequest, Context> {
+    readonly method: string;
+    readonly url: string;
+    readonly headers: RequestHeaders;
+    readonly body: string | Record<string, unknown> | null;
+    /**
+     * The raw request itself from the implementing server.
+     *
+     * For example: `express.Request` when using Express, or maybe
+     * `http.IncomingMessage` when just using Node with `http.createServer`.
+     */
+    readonly raw: RawRequest;
+    /**
+     * Context value about the incoming request, you're free to pass any information here.
+     */
+    readonly context: Context;
+}
+/**
+ * The response headers that get returned from graphql-http.
+ *
+ * @category Common
+ */
+export declare type ResponseHeaders = {
+    accept?: string;
+    allow?: string;
+    'content-type'?: string;
+} & Record<string, string>;
+/**
+ * Server agnostic response body returned from `graphql-http` needing
+ * to be coerced to the server implementation in use.
+ *
+ * @category Common
+ */
+export declare type ResponseBody = string;
+/**
+ * Server agnostic response options (ex. status and headers) returned from
+ * `graphql-http` needing to be coerced to the server implementation in use.
+ *
+ * @category Common
+ */
+export interface ResponseInit {
+    readonly status: number;
+    readonly statusText: string;
+    readonly headers?: ResponseHeaders;
+}
+/**
+ * Server agnostic response returned from `graphql-http` containing the
+ * body and init options needing to be coerced to the server implementation in use.
+ *
+ * @category Common
+ */
+export declare type Response = readonly [body: ResponseBody | null, init: ResponseInit];
+/**
+ * Checks whether the passed value is the `graphql-http` server agnostic response.
+ *
+ * @category Common
+ */
+export declare function isResponse(val: unknown): val is Response;
 /**
  * A concrete GraphQL execution context value type.
  *
@@ -17,7 +98,7 @@ import { Request, RequestParams, Response } from './common';
  */
 export declare type ExecutionContext = object | symbol | number | string | boolean | undefined | null;
 /** @category Server */
-export interface HandlerOptions<RawRequest = unknown> {
+export interface HandlerOptions<RawRequest = unknown, Context = unknown> {
     /**
      * The GraphQL schema on which the operations will
      * be executed and validated against.
@@ -34,16 +115,18 @@ export interface HandlerOptions<RawRequest = unknown> {
      * you should do by returning a `Request` argument which will stop
      * further execution.
      */
-    schema?: GraphQLSchema | ((req: Request<RawRequest>, args: Omit<ExecutionArgs, 'schema'>) => Promise<GraphQLSchema | Response> | GraphQLSchema | Response);
+    schema?: GraphQLSchema | ((req: Request<RawRequest, Context>, args: Omit<ExecutionArgs, 'schema'>) => Promise<GraphQLSchema | Response> | GraphQLSchema | Response);
     /**
      * A value which is provided to every resolver and holds
      * important contextual information like the currently
      * logged in user, or access to a database.
      */
-    context?: ExecutionContext | ((req: Request<RawRequest>, args: ExecutionArgs) => Promise<ExecutionContext | Response> | ExecutionContext | Response);
+    context?: ExecutionContext | ((req: Request<RawRequest, Context>, args: ExecutionArgs) => Promise<ExecutionContext | Response> | ExecutionContext | Response);
     /**
      * A custom GraphQL validate function allowing you to apply your
      * own validation rules.
+     *
+     * Will not be used when implementing a custom `onSubscribe`.
      */
     validate?: typeof graphqlValidate;
     /**
@@ -51,14 +134,31 @@ export interface HandlerOptions<RawRequest = unknown> {
      * used to execute the query and mutation operations.
      */
     execute?: typeof graphqlExecute;
+    /**
+     * GraphQL parse function allowing you to apply a custom parser.
+     */
+    parse?: typeof graphqlParse;
+    /**
+     * GraphQL operation AST getter used for detecting the operation type.
+     */
+    getOperationAST?: typeof graphqlGetOperationAST;
     /**
      * The subscribe callback executed right after processing the request
      * before proceeding with the GraphQL operation execution.
      *
+     * If you return `ExecutionResult` from the callback, it will be used
+     * directly for responding to the request. Useful for implementing a response
+     * cache.
+     *
      * If you return `ExecutionArgs` from the callback, it will be used instead of
      * trying to build one internally. In this case, you are responsible for providing
      * a ready set of arguments which will be directly plugged in the operation execution.
      *
+     * You *must* validate the `ExecutionArgs` yourself if returning them.
+     *
+     * If you return an array of `GraphQLError` from the callback, they will be reported
+     * to the client while complying with the spec.
+     *
      * Omitting the fields `contextValue` from the returned `ExecutionArgs` will use the
      * provided `context` option, if available.
      *
@@ -70,7 +170,7 @@ export interface HandlerOptions<RawRequest = unknown> {
      * you should do by returning a `Request` argument which will stop
      * further execution.
      */
-    onSubscribe?: (req: Request<RawRequest>, params: RequestParams) => Promise<ExecutionArgs | Response | void> | ExecutionArgs | Response | void;
+    onSubscribe?: (req: Request<RawRequest, Context>, params: RequestParams) => Promise<ExecutionResult | ExecutionArgs | readonly GraphQLError[] | Response | void> | ExecutionResult | ExecutionArgs | readonly GraphQLError[] | Response | void;
     /**
      * Executed after the operation call resolves.
      *
@@ -84,7 +184,7 @@ export interface HandlerOptions<RawRequest = unknown> {
      * you should do by returning a `Request` argument which will stop
      * further execution.
      */
-    onOperation?: (req: Request<RawRequest>, args: ExecutionArgs, result: ExecutionResult) => Promise<ExecutionResult | Response | void> | ExecutionResult | Response | void;
+    onOperation?: (req: Request<RawRequest, Context>, args: ExecutionArgs, result: ExecutionResult) => Promise<ExecutionResult | Response | void> | ExecutionResult | Response | void;
 }
 /**
  * The ready-to-use handler. Simply plug it in your favourite HTTP framework
@@ -96,7 +196,7 @@ export interface HandlerOptions<RawRequest = unknown> {
  *
  * @category Server
  */
-export declare type Handler<RawRequest = unknown> = (req: Request<RawRequest>) => Promise<Response>;
+export declare type Handler<RawRequest = unknown, Context = unknown> = (req: Request<RawRequest, Context>) => Promise<Response>;
 /**
  * Makes a GraphQL over HTTP Protocol compliant server handler. The handler can
  * be used with your favourite server library.
@@ -152,4 +252,28 @@ export declare type Handler<RawRequest = unknown> = (req: Request<RawRequest>) =
  *
  * @category Server
  */
-export declare function createHandler<RawRequest = unknown>(options: HandlerOptions<RawRequest>): Handler<RawRequest>;
+export declare function createHandler<RawRequest = unknown, Context = unknown>(options: HandlerOptions<RawRequest, Context>): Handler<RawRequest, Context>;
+/**
+ * Request's Media-Type that the server accepts.
+ *
+ * @category Server
+ */
+export declare 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 Protocol.
+ *
+ * @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 _any_ object without the `data` field, it will be treated as an error (as per the spec)
+ * and the response will be constructed with the help of `acceptedMediaType` complying with the GraphQL over HTTP Protocol.
+ *
+ * @category Server
+ */
+export declare function makeResponse(resultOrErrors: Readonly<ExecutionResult> | Readonly<GraphQLError[]> | Readonly<GraphQLError>, acceptedMediaType: AcceptableMediaType): Response;