graphql-http

GraphQL on HTTP middleware with built-in validations and GraphQL playground

Features

• GraphQL over HTTP Spec compliant
• application/graphql+json support
• Lean interface, tiny using std and graphql public libraries
• Built-in graphql-playground
• Universal

What

It provides GraphQL on HTTP middleware that can be embedded in any server.

Essentially, it takes a Request object and returns a Response object.

In the meantime, it performs HTTP request validation, processes GraphQL, and response object with the appropriate status code and message.

There is also a built-in GraphQL Playground.

Example

A simple example of creating a GraphQL server.

std/http + grpahql.js

import { graphqlHttp } from "https://deno.land/x/graphql_http@$VERSION/mod.ts";
import {
  Handler,
  serve,
  Status,
} from "https://deno.land/std@$VERSION/http/mod.ts";
import { buildSchema } from "https://esm.sh/graphql@$VERSION";

const graphqlResponse = graphqlHttp({
  schema: buildSchema(`type Query {
    hello: String!
  }`),
  rootValue: {
    hello: () => "world",
  },
  playground: true,
});

const handler: Handler = (req) => {
  const { pathname } = new URL(req.url);
  if (pathname === "/graphql") {
    return graphqlResponse(req);
  }
  return new Response("Not Found", {
    status: Status.NotFound,
  });
};

serve(handler);

Spec

This project is implemented in accordance with GraphQL over HTTP Spec.

We are actively implementing IETF RFC 2119 SHOULD and RECOMMENDED.

Request Parameters

A GraphQL-over-HTTP request is formed of the following parameters:

Response Status

The following responses may be returned.

Below are the specific conditions under which each may occur. Errors are classified into four major categories.

• HTTP Request errors
• (GraphQL) Request errors
• (GraphQL) Field errors
• Unknown errors

HTTP Request errors

HTTP Request errors are errors in the http protocol. This refers to errors that can occur between HTTP and GraphQL, such as missing/incorrect values for required parameters, missing/incorrect values for required headers, etc.

Since these are client-side errors, the appropriate 4XX status is returned.

Request errors

Request errors are defined at [GraphQL Spec] 7.Response - Request errors.

Note here that the status code may be different depending on the Content-Type.

application/json

If Content-Type is application/json, all results of GraphQL Requests including GraphQL validation will be treated as 200 status.

See the [GraphQL over HTTP 6.4.1] application/json#Note for the reason for this.

application/graphql+json

If Content-Type is application/graphql+json, it is possible to respond with a status code other than 200 depending on the result of the GraphQL Request.

If the GraphQL request is invalid (e.g. it is malformed, or does not pass validation) then the response with 400 status code.

Field errors

Field errors are defined at [GraphQL Spec 7.Response] - Field errors.

Even if a Field error occurs, it will always be a 200 status code.

Unknown errors

If an error other than the above occurs on the server side, a 500 status code will be responded.

Upgrade to application/graphql+json

As you may have noticed, application/graphql+json represents a more accurate semantics response.

If you want application/graphql+json content, you must put application/graphql+json as a higher priority than application/json in the Accept header.

Example: Accept: application/graphql+json,application/json.

application/graphql+json vs application/json

Response status

Overwrite response

grpahqlHttp creates a response according to the GraphQL over HTTP specification. You can customize this response.

Example of adding a header:

import { graphqlHttp } from "https://deno.land/x/graphql_http@$VERSION/mod.ts";
import { buildSchema } from "https://esm.sh/graphql@$VERSION";

const responser = graphqlHttp({
  response: (res, ctx) => {
    if (ctx.request.method === "GET") {
      res.headers.set("Cache-Control", "max-age=604800");
    }
    return res;
  },
  schema: buildSchema(`type Query {
    hello: String
  }`),
});

Where the subscription?

Unfortunately, there is currently no specification for subscription and it is not implemented.

You can refer to other projects' implementations using SSE or Websocket.

• graphql-ws
• subscriptions-transport-ws

API

graphqlHttp

Make a GraphQL Response Object that validate to Request Object.

Parameters

ReturnType

(req: Request) => Promise<Response>

Throws

• AggregateError - When graphql schema validation is fail.

gqlFetch

GraphQL client with HTTP.

Example

import { gqlFetch } from "https://deno.land/x/graphql_http@$VERSION/mod.ts";

const { data, errors, extensions } = await gqlFetch({
  url: `<graphql-endpoint>`,
  query: `query Greet(name: $name) {
    hello(name: $name)
  }`,
}, {
  variables: {
    name: "Bob",
  },
  operationName: "Greet",
  method: "GET",
});

Generics

• T extends jsonObject - data field type

Parameters

type json =
  | string
  | number
  | boolean
  | null
  | { [k: string]: json }
  | json[];

type jsonObject = {
  [k: string]: json;
};

ReturnTypes

Promise<Result<T>>

Throws

• Error
• TypeError
• SyntaxError
• DOMException
• AggregateError

createRequest

Create GraphQL Request object.

Example

import { createRequest } from "https://deno.land/x/graphql_http@$VERSION/mod.ts";

const [request, err] = createRequest({
  url: "<graphql-endpoint>",
  query: `query Greet(name: $name) {
    hello(name: $name)
  }`,
  method: "GET",
});

if (!err) {
  const res = await fetch(request);
}

Generics

• T extends jsonObject

Parameters

ReturnType

[data: Request, error: undefined] | [data: undefined, error: TypeError]

resolveResponse

Resolve GraphQL over HTTP response safety.

Example

import {
  resolveResponse,
} from "https://deno.land/x/graphql_http@$VERSION/mod.ts";

const res = new Response(); // any Response
const { data, errors, extensions } = await resolveResponse(res);

Parameters

ReturnType

Promise<Result<T>>

import { GraphQLError } from "https://esm.sh/graphql@$VERSION";
import { json } from "https://deno.land/x/pure_json@$VERSION/mod.ts";
type PickBy<T, K> = {
  [k in keyof T as (K extends T[k] ? k : never)]: T[k];
};

type SerializedGraphQLError = PickBy<GraphQLError, json | undefined>;
type Result<
  T extends Record<string, unknown> = Record<string, unknown>,
> = {
  data?: T;
  errors?: SerializedGraphQLError[];
  extensions?: unknown;
};

Throws

• Error
• AggregateError
• SyntaxError
• TypeError

Recipes

• std/http
• fresh

License

Copyright © 2022-present TomokiMiyauci.

Released under the MIT license