graphql-http 1.4.0 → 1.6.1

package/lib/handler.d.mts

@@ -0,0 +1,285 @@
+/**
+ *
+ * handler
+ *
+ */
+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;
+    /**
+     * Parsed request body or a parser function.
+     *
+     * If the provided function throws, the error message "Unparsable JSON body" will
+     * be in the erroneous response.
+     */
+    readonly body: string | Record<string, unknown> | null | (() => string | Record<string, unknown> | null | Promise<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.
+ *
+ * Mainly used because TypeScript collapes unions
+ * with `any` or `unknown` to `any` or `unknown`. So,
+ * we use a custom type to allow definitions such as
+ * the `context` server option.
+ *
+ * @category Server
+ */
+export declare type ExecutionContext = object | symbol | number | string | boolean | undefined | null;
+/** @category Server */
+export interface HandlerOptions<RawRequest = unknown, Context = unknown> {
+    /**
+     * The GraphQL schema on which the operations will
+     * be executed and validated against.
+     *
+     * If a function is provided, it will be called on every
+     * operation request allowing you to manipulate schema
+     * dynamically.
+     *
+     * If the schema is left undefined, you're trusted to
+     * provide one in the returned `ExecutionArgs` from the
+     * `onSubscribe` callback.
+     *
+     * If you want to respond to the client with a custom status and/or body,
+     * you should do by returning a `Request` argument which will stop
+     * further execution.
+     */
+    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, 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;
+    /**
+     * Is the `execute` function from GraphQL which is
+     * 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.
+     *
+     * Useful for preparing the execution arguments following a custom logic. A typical
+     * use-case is persisted queries. You can identify the query from the request parameters
+     * and supply the appropriate GraphQL operation execution arguments.
+     *
+     * If you want to respond to the client with a custom status and/or body,
+     * you should do by returning a `Request` argument which will stop
+     * further execution.
+     */
+    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.
+     *
+     * The `OperationResult` argument is the result of operation
+     * execution. It can be an iterator or already a value.
+     *
+     * Use this callback to listen for GraphQL operations and
+     * execution result manipulation.
+     *
+     * If you want to respond to the client with a custom status and/or body,
+     * you should do by returning a `Request` argument which will stop
+     * further execution.
+     */
+    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
+ * and enjoy.
+ *
+ * Errors thrown from **any** of the provided options or callbacks (or even due to
+ * library misuse or potential bugs) will reject the handler's promise. They are
+ * considered internal errors and you should take care of them accordingly.
+ *
+ * @category Server
+ */
+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.
+ *
+ * Beware that the handler resolves only after the whole operation completes.
+ *
+ * Errors thrown from **any** of the provided options or callbacks (or even due to
+ * library misuse or potential bugs) will reject the handler's promise. They are
+ * considered internal errors and you should take care of them accordingly.
+ *
+ * For production environments, its recommended not to transmit the exact internal
+ * error details to the client, but instead report to an error logging tool or simply
+ * the console.
+ *
+ * Simple example usage with Node:
+ *
+ * ```js
+ * import http from 'http';
+ * import { createHandler } from 'graphql-http';
+ * import { schema } from './my-graphql-schema';
+ *
+ * // Create the GraphQL over HTTP handler
+ * const handler = createHandler({ schema });
+ *
+ * // Create a HTTP server using the handler on `/graphql`
+ * const server = http.createServer(async (req, res) => {
+ *   if (!req.url.startsWith('/graphql')) {
+ *     return res.writeHead(404).end();
+ *   }
+ *
+ *   try {
+ *     const [body, init] = await handler({
+ *       url: req.url,
+ *       method: req.method,
+ *       headers: req.headers,
+ *       body: () => new Promise((resolve) => {
+ *         let body = '';
+ *         req.on('data', (chunk) => (body += chunk));
+ *         req.on('end', () => resolve(body));
+ *       }),
+ *       raw: req,
+ *     });
+ *     res.writeHead(init.status, init.statusText, init.headers).end(body);
+ *   } catch (err) {
+ *     // BEWARE not to transmit the exact internal error message in production environments
+ *     res.writeHead(500).end(err.message);
+ *   }
+ * });
+ *
+ * server.listen(4000);
+ * console.log('Listening to port 4000');
+ * ```
+ *
+ * @category Server
+ */
+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;

package/lib/handler.d.ts

@@ -238,7 +238,7 @@ export declare type Handler<RawRequest = unknown, Context = unknown> = (req: Req
  *       url: req.url,
  *       method: req.method,
  *       headers: req.headers,
- *       body: await new Promise((resolve) => {
+ *       body: () => new Promise((resolve) => {
  *         let body = '';
  *         req.on('data', (chunk) => (body += chunk));
  *         req.on('end', () => resolve(body));

package/lib/handler.js

@@ -55,7 +55,7 @@ exports.isResponse = isResponse;
  *       url: req.url,
  *       method: req.method,
  *       headers: req.headers,
- *       body: await new Promise((resolve) => {
+ *       body: () => new Promise((resolve) => {
  *         let body = '';
  *         req.on('data', (chunk) => (body += chunk));
  *         req.on('end', () => resolve(body));

package/lib/handler.mjs

@@ -35,7 +35,7 @@ export function isResponse(val) {
  * ```js
  * import http from 'http';
  * import { createHandler } from 'graphql-http';
- * import { schema } from './my-graphql-schema.mjs';
+ * import { schema } from './my-graphql-schema/index.mjs';
  *
  * // Create the GraphQL over HTTP handler
  * const handler = createHandler({ schema });
@@ -51,7 +51,7 @@ export function isResponse(val) {
  *       url: req.url,
  *       method: req.method,
  *       headers: req.headers,
- *       body: await new Promise((resolve) => {
+ *       body: () => new Promise((resolve) => {
  *         let body = '';
  *         req.on('data', (chunk) => (body += chunk));
  *         req.on('end', () => resolve(body));

package/lib/index.d.mts

@@ -0,0 +1,4 @@
+export * from './common';
+export * from './handler';
+export * from './client';
+export * from './audits';

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 export * from './common';
 export * from './handler';
 export * from './client';
+export * from './audits';

package/lib/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./common"), exports);
 __exportStar(require("./handler"), exports);
 __exportStar(require("./client"), exports);
+__exportStar(require("./audits"), exports);

package/lib/index.mjs

@@ -1,3 +1,4 @@
 export * from './common.mjs';
 export * from './handler.mjs';
 export * from './client.mjs';
+export * from './audits/index.mjs';

package/lib/utils.d.mts

@@ -0,0 +1,16 @@
+/**
+ *
+ * utils
+ *
+ */
+import type { ExecutionResult, GraphQLError } from 'graphql';
+/** @private */
+export declare function extendedTypeof(val: unknown): 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function' | 'array' | 'null';
+/** @private */
+export declare function isObject(val: unknown): val is Record<PropertyKey, any>;
+/** @private */
+export declare function areGraphQLErrors(obj: unknown): obj is readonly GraphQLError[];
+/** @private */
+export declare function isExecutionResult(val: unknown): val is ExecutionResult;
+/** @private */
+export declare function isAsyncIterable<T = unknown>(val: unknown): val is AsyncIterable<T>;

package/lib/utils.d.ts

@@ -5,6 +5,8 @@
  */
 import type { ExecutionResult, GraphQLError } from 'graphql';
 /** @private */
+export declare function extendedTypeof(val: unknown): 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function' | 'array' | 'null';
+/** @private */
 export declare function isObject(val: unknown): val is Record<PropertyKey, any>;
 /** @private */
 export declare function areGraphQLErrors(obj: unknown): obj is readonly GraphQLError[];

package/lib/utils.js

@@ -5,7 +5,18 @@
  *
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isAsyncIterable = exports.isExecutionResult = exports.areGraphQLErrors = exports.isObject = void 0;
+exports.isAsyncIterable = exports.isExecutionResult = exports.areGraphQLErrors = exports.isObject = exports.extendedTypeof = void 0;
+/** @private */
+function extendedTypeof(val) {
+    if (val === null) {
+        return 'null';
+    }
+    if (Array.isArray(val)) {
+        return 'array';
+    }
+    return typeof val;
+}
+exports.extendedTypeof = extendedTypeof;
 /** @private */
 function isObject(val) {
     return typeof val === 'object' && val !== null;

package/lib/utils.mjs

@@ -4,6 +4,16 @@
  *
  */
 /** @private */
+export function extendedTypeof(val) {
+    if (val === null) {
+        return 'null';
+    }
+    if (Array.isArray(val)) {
+        return 'array';
+    }
+    return typeof val;
+}
+/** @private */
 export function isObject(val) {
     return typeof val === 'object' && val !== null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphql-http",
-  "version": "1.4.0",
+  "version": "1.6.1",
   "description": "Simple, pluggable, zero-dependency, GraphQL over HTTP Protocol compliant server and client",
   "keywords": [
     "graphql",
@@ -24,7 +24,7 @@
   "engines": {
     "node": ">=12"
   },
-  "packageManager": "yarn@3.2.2",
+  "packageManager": "yarn@3.2.3",
   "main": "lib/index.js",
   "module": "lib/index.mjs",
   "browser": "umd/graphql-http.js",
@@ -55,45 +55,50 @@
     "lint": "eslint 'src'",
     "type-check": "tsc --noEmit",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest",
-    "build:esm": "tsc -b tsconfig.esm.json && node scripts/esm-post-process.js",
+    "build:esm": "tsc -b tsconfig.esm.json && node scripts/esm-post-process.mjs",
     "build:cjs": "tsc -b tsconfig.cjs.json",
     "build:umd": "rollup -c && gzip umd/graphql-http.min.js -c > umd/graphql-http.min.js.gz",
     "build": "yarn build:esm && yarn build:cjs && yarn build:umd",
     "release": "semantic-release"
   },
+  "workspaces": [
+    "implementations/*"
+  ],
   "peerDependencies": {
     "graphql": ">=0.11 <=16"
   },
   "devDependencies": {
-    "@babel/core": "^7.18.10",
+    "@babel/core": "^7.18.13",
     "@babel/plugin-proposal-class-properties": "^7.18.6",
     "@babel/plugin-proposal-nullish-coalescing-operator": "^7.18.6",
     "@babel/plugin-proposal-object-rest-spread": "^7.18.9",
     "@babel/plugin-proposal-optional-chaining": "^7.18.9",
     "@babel/preset-env": "^7.18.10",
     "@babel/preset-typescript": "^7.18.6",
-    "@rollup/plugin-typescript": "^8.3.4",
+    "@rollup/plugin-typescript": "^8.4.0",
     "@semantic-release/changelog": "^6.0.1",
     "@semantic-release/git": "^10.0.1",
-    "@types/jest": "^28.1.7",
-    "@typescript-eslint/eslint-plugin": "^5.33.1",
-    "@typescript-eslint/parser": "^5.33.1",
-    "babel-jest": "^28.1.3",
-    "eslint": "^8.22.0",
+    "@types/jest": "^29.0.0",
+    "@typescript-eslint/eslint-plugin": "^5.36.1",
+    "@typescript-eslint/parser": "^5.36.1",
+    "babel-jest": "^29.0.1",
+    "eslint": "^8.23.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-prettier": "^4.2.1",
-    "graphql": "^16.5.0",
-    "jest": "^28.1.3",
-    "jest-jasmine2": "^28.1.3",
+    "graphql": "^16.6.0",
+    "jest": "^29.0.1",
+    "jest-jasmine2": "^29.0.1",
     "node-fetch": "^3.2.10",
     "prettier": "^2.7.1",
-    "replacestream": "^4.0.3",
-    "rollup": "^2.78.0",
+    "rollup": "^2.79.0",
     "rollup-plugin-terser": "^7.0.2",
-    "semantic-release": "^19.0.3",
+    "semantic-release": "^19.0.5",
     "tslib": "^2.4.0",
-    "typedoc": "^0.23.10",
-    "typedoc-plugin-markdown": "^3.13.4",
-    "typescript": "^4.7.4"
+    "typedoc": "^0.23.13",
+    "typedoc-plugin-markdown": "^3.13.5",
+    "typescript": "^4.8.2"
+  },
+  "resolutions": {
+    "npm/libnpmversion": "^3.0.6"
   }
 }