graphql-http 1.4.0 → 1.6.1

package/lib/audits/utils.d.ts

@@ -0,0 +1,38 @@
+/**
+ *
+ * audit/utils
+ *
+ */
+import { ExecutionResult } from 'graphql';
+import { Audit, AuditName } from './common';
+export * from '../utils';
+/**
+ * Wrap and prepare an audit for testing.
+ *
+ * @private
+ */
+export declare function audit(name: AuditName, fn: () => Promise<void>): Audit;
+/**
+ * Will throw a string if the assertion fails.
+ *
+ * All fatal problems will throw an instance of Error.
+ *
+ * @private
+ */
+export declare function assert<T = unknown>(name: string, actual: T): {
+    toBe: (expected: T) => void;
+    toBeLessThanOrEqual: (expected: T extends number ? T : never) => void;
+    toBeGreaterThanOrEqual: (expected: T extends number ? T : never) => void;
+    toContain: (expected: T extends (infer U)[] ? U : T extends string ? T : never) => void;
+    notToContain: (expected: T extends (infer U_1)[] ? U_1 : T extends string ? T : never) => void;
+    toHaveProperty: (prop: T extends Record<any, any> ? PropertyKey : never) => void;
+    notToHaveProperty: (prop: T extends Record<any, any> ? PropertyKey : never) => void;
+};
+/**
+ * Parses the string as JSON and safely reports parsing issues for audits.
+ *
+ * Assumes the parsed JSON will be an `ExecutionResult`.
+ *
+ * @private
+ * */
+export declare function assertBodyAsExecutionResult(res: Response): Promise<ExecutionResult<import("graphql/jsutils/ObjMap").ObjMap<unknown>, import("graphql/jsutils/ObjMap").ObjMap<unknown>>>;

package/lib/audits/utils.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ *
+ * audit/utils
+ *
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertBodyAsExecutionResult = exports.assert = exports.audit = void 0;
+__exportStar(require("../utils"), exports);
+/**
+ * Wrap and prepare an audit for testing.
+ *
+ * @private
+ */
+function audit(name, fn) {
+    return {
+        name,
+        fn: async () => {
+            try {
+                await fn();
+                return {
+                    name,
+                    status: 'ok',
+                };
+            }
+            catch (errOrReason) {
+                if (typeof errOrReason !== 'string') {
+                    // anything thrown that is not an assertion string is considered fatal
+                    throw errOrReason;
+                }
+                return {
+                    name,
+                    status: name.startsWith('MUST')
+                        ? // only failing MUSTs are considered errors
+                            'error'
+                        : // everything else is optional and considered a warning
+                            'warn',
+                    reason: errOrReason,
+                };
+            }
+        },
+    };
+}
+exports.audit = audit;
+/**
+ * Will throw a string if the assertion fails.
+ *
+ * All fatal problems will throw an instance of Error.
+ *
+ * @private
+ */
+function assert(name, actual) {
+    return {
+        toBe: (expected) => {
+            if (actual !== expected) {
+                throw `${name} ${actual} is not ${expected}`;
+            }
+        },
+        toBeLessThanOrEqual: (expected) => {
+            if (!(actual <= expected)) {
+                throw `${name} ${actual} is not less than or equal to ${expected}`;
+            }
+        },
+        toBeGreaterThanOrEqual: (expected) => {
+            if (!(actual >= expected)) {
+                throw `${name} ${actual} is not greater than or equal to ${expected}`;
+            }
+        },
+        toContain: (expected) => {
+            // @ts-expect-error types will match, otherwise never
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (!actual.includes(expected)) {
+                throw `${name} ${JSON.stringify(actual)} does not contain ${JSON.stringify(expected)}`;
+            }
+        },
+        notToContain: (expected) => {
+            // @ts-expect-error types will match, otherwise never
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (actual.includes(expected)) {
+                throw `${name} ${JSON.stringify(actual)} contains ${JSON.stringify(expected)}`;
+            }
+        },
+        toHaveProperty: (
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        prop) => {
+            // @ts-expect-error types will match, otherwise never
+            if (!(prop in actual)) {
+                throw `${name} ${JSON.stringify(actual)} does not have a property '${String(prop)}'`;
+            }
+        },
+        notToHaveProperty: (
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        prop) => {
+            // @ts-expect-error types will match, otherwise never
+            if (prop in actual) {
+                throw `${name} ${JSON.stringify(actual)} does have a property '${String(prop)}'`;
+            }
+        },
+    };
+}
+exports.assert = assert;
+/**
+ * Parses the string as JSON and safely reports parsing issues for audits.
+ *
+ * Assumes the parsed JSON will be an `ExecutionResult`.
+ *
+ * @private
+ * */
+async function assertBodyAsExecutionResult(res) {
+    const str = await res.text();
+    try {
+        return JSON.parse(str);
+    }
+    catch (err) {
+        throw `Response body is not valid JSON. Got ${JSON.stringify(str)}`;
+    }
+}
+exports.assertBodyAsExecutionResult = assertBodyAsExecutionResult;

package/lib/audits/utils.mjs

@@ -0,0 +1,112 @@
+/**
+ *
+ * audit/utils
+ *
+ */
+export * from '../utils.mjs';
+/**
+ * Wrap and prepare an audit for testing.
+ *
+ * @private
+ */
+export function audit(name, fn) {
+    return {
+        name,
+        fn: async () => {
+            try {
+                await fn();
+                return {
+                    name,
+                    status: 'ok',
+                };
+            }
+            catch (errOrReason) {
+                if (typeof errOrReason !== 'string') {
+                    // anything thrown that is not an assertion string is considered fatal
+                    throw errOrReason;
+                }
+                return {
+                    name,
+                    status: name.startsWith('MUST')
+                        ? // only failing MUSTs are considered errors
+                            'error'
+                        : // everything else is optional and considered a warning
+                            'warn',
+                    reason: errOrReason,
+                };
+            }
+        },
+    };
+}
+/**
+ * Will throw a string if the assertion fails.
+ *
+ * All fatal problems will throw an instance of Error.
+ *
+ * @private
+ */
+export function assert(name, actual) {
+    return {
+        toBe: (expected) => {
+            if (actual !== expected) {
+                throw `${name} ${actual} is not ${expected}`;
+            }
+        },
+        toBeLessThanOrEqual: (expected) => {
+            if (!(actual <= expected)) {
+                throw `${name} ${actual} is not less than or equal to ${expected}`;
+            }
+        },
+        toBeGreaterThanOrEqual: (expected) => {
+            if (!(actual >= expected)) {
+                throw `${name} ${actual} is not greater than or equal to ${expected}`;
+            }
+        },
+        toContain: (expected) => {
+            // @ts-expect-error types will match, otherwise never
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (!actual.includes(expected)) {
+                throw `${name} ${JSON.stringify(actual)} does not contain ${JSON.stringify(expected)}`;
+            }
+        },
+        notToContain: (expected) => {
+            // @ts-expect-error types will match, otherwise never
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (actual.includes(expected)) {
+                throw `${name} ${JSON.stringify(actual)} contains ${JSON.stringify(expected)}`;
+            }
+        },
+        toHaveProperty: (
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        prop) => {
+            // @ts-expect-error types will match, otherwise never
+            if (!(prop in actual)) {
+                throw `${name} ${JSON.stringify(actual)} does not have a property '${String(prop)}'`;
+            }
+        },
+        notToHaveProperty: (
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        prop) => {
+            // @ts-expect-error types will match, otherwise never
+            if (prop in actual) {
+                throw `${name} ${JSON.stringify(actual)} does have a property '${String(prop)}'`;
+            }
+        },
+    };
+}
+/**
+ * Parses the string as JSON and safely reports parsing issues for audits.
+ *
+ * Assumes the parsed JSON will be an `ExecutionResult`.
+ *
+ * @private
+ * */
+export async function assertBodyAsExecutionResult(res) {
+    const str = await res.text();
+    try {
+        return JSON.parse(str);
+    }
+    catch (err) {
+        throw `Response body is not valid JSON. Got ${JSON.stringify(str)}`;
+    }
+}

package/lib/client.d.mts

@@ -0,0 +1,155 @@
+/**
+ *
+ * client
+ *
+ */
+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';
+/** @category Client */
+export interface ClientOptions {
+    /**
+     * URL of the GraphQL over HTTP server to connect.
+     *
+     * If the option is a function, it will be called on each request.
+     * Returning a Promise is supported too and the request will stall until it
+     * resolves.
+     *
+     * 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 | ((request: RequestParams) => Promise<string> | string);
+    /**
+     * Indicates whether the user agent should send cookies from the other domain in the case
+     * of cross-origin requests.
+     *
+     * Possible options are:
+     *   - `omit`: Never send or receive cookies.
+     *   - `same-origin`: Send user credentials (cookies, basic http auth, etc..) if the URL is on the same origin as the calling script.
+     *   - `include`: Always send user credentials (cookies, basic http auth, etc..), even for cross-origin calls.
+     *
+     * @default same-origin
+     */
+    credentials?: 'omit' | 'same-origin' | 'include';
+    /**
+     * A string specifying the referrer of the request. This can be a same-origin URL, about:client, or an empty string.
+     *
+     * @default undefined
+     */
+    referrer?: string;
+    /**
+     * Specifies the referrer policy to use for the request.
+     *
+     * Possible options are:
+     *   - `no-referrer`: Does not send referrer information along with requests to any origin.
+     *   - `no-referrer-when-downgrade`: Sends full referrerURL for requests: whose referrerURL and current URL are both potentially trustworthy URLs, or whose referrerURL is a non-potentially trustworthy URL.
+     *   - `same-origin`: Sends full referrerURL as referrer information when making same-origin-referrer requests.
+     *   - `origin`: Sends only the ASCII serialization of the request’s referrerURL when making both same-origin-referrer requests and cross-origin-referrer requests.
+     *   - `strict-origin`: Sends the ASCII serialization of the origin of the referrerURL for requests: whose referrerURL and current URL are both potentially trustworthy URLs, or whose referrerURL is a non-potentially trustworthy URL
+     *   - `origin-when-cross-origin`: Sends full referrerURL when making same-origin-referrer requests, and only the ASCII serialization of the origin of the request’s referrerURL is sent when making cross-origin-referrer requests
+     *   - `strict-origin-when-cross-origin`: Sends full referrerURL when making same-origin-referrer requests, and only the ASCII serialization of the origin of the request’s referrerURL when making cross-origin-referrer requests: whose referrerURL and current URL are both potentially trustworthy URLs, or whose referrerURL is a non-potentially trustworthy URL.
+     *   - `unsafe-url`: Sends full referrerURL along for both same-origin-referrer requests and cross-origin-referrer requests.
+     *
+     * @default undefined
+     */
+    referrerPolicy?: 'no-referrer' | 'no-referrer-when-downgrade' | 'same-origin' | 'origin' | 'strict-origin' | 'origin-when-cross-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url';
+    /**
+     * HTTP headers to pass along the request.
+     *
+     * If the option is a function, it will be called on each request.
+     * Returning a Promise is supported too and the request will stall until it
+     * resolves.
+     *
+     * 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.
+     */
+    headers?: Record<string, string> | (() => Promise<Record<string, string> | null | void> | Record<string, string> | null | void);
+    /**
+     * Control whether the network request error should be retried.
+     *
+     * Please note that you can **only** control network errors, all other
+     * errors are considered fatal and will be reported immediately.
+     *
+     * 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.
+     *
+     * `retries` argument counts actual retries, so it will begin with
+     * 0 after the first failed request.
+     *
+     * Returning `false` will report the `err` argument; however, throwing a different error from
+     * the `err` argument, will report it instead.
+     *
+     * @default '() => false'
+     */
+    shouldRetry?: (err: NetworkError, retries: number) => Promise<boolean>;
+    /**
+     * The Fetch function to use.
+     *
+     * For NodeJS environments consider using [`node-fetch`](https://github.com/node-fetch/node-fetch).
+     *
+     * @default global.fetch
+     */
+    fetchFn?: unknown;
+    /**
+     * The AbortController implementation to use.
+     *
+     * For NodeJS environments before v15 consider using [`node-abort-controller`](https://github.com/southpolesteve/node-abort-controller).
+     *
+     * @default global.AbortController
+     */
+    abortControllerImpl?: unknown;
+}
+/** @category Client */
+export interface Client {
+    /**
+     * Subscribes to receive a response by making an HTTP request.
+     *
+     * It uses the `sink` to emit the received data or errors. Returns a _dispose_
+     * function used for canceling active requests and cleaning up.
+     */
+    subscribe<Data = Record<string, unknown>, Extensions = unknown>(request: RequestParams, sink: Sink<ExecutionResult<Data, Extensions>>): () => void;
+    /**
+     * Dispose of the client, cancel all active requests and clean up resources.
+     */
+    dispose: () => void;
+}
+/**
+ * Creates a disposable GraphQL over HTTP client to transmit
+ * GraphQL operation results.
+ *
+ * @category Client
+ */
+export declare function createClient(options: ClientOptions): Client;
+/**
+ * A network error caused by the client or an unexpected response from the server.
+ *
+ * To avoid bundling DOM typings (because the client can run in Node env too),
+ * you should supply the `Response` generic depending on your Fetch implementation.
+ *
+ * @category Client
+ */
+export declare class NetworkError<Response extends ResponseLike = ResponseLike> extends Error {
+    /**
+     * The underlyig response thats considered an error.
+     *
+     * Will be undefined when no response is received,
+     * instead an unexpected network error.
+     */
+    response: Response | undefined;
+    constructor(msgOrErrOrResponse: string | Error | Response);
+}
+/**
+ * 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/common.d.mts

@@ -0,0 +1,31 @@
+/**
+ *
+ * common
+ *
+ */
+/**
+ * Parameters for GraphQL's request for execution.
+ *
+ * Reference: https://graphql.github.io/graphql-over-http/draft/#sec-Request-Parameters
+ *
+ * @category Common
+ */
+export interface RequestParams {
+    operationName?: string | undefined;
+    query: string;
+    variables?: Record<string, unknown> | undefined;
+    extensions?: Record<string, unknown> | undefined;
+}
+/**
+ * A representation of any set of values over any amount of time.
+ *
+ * @category Common
+ */
+export interface Sink<T = unknown> {
+    /** Next value arriving. */
+    next(value: T): void;
+    /** An error that has occured. This function "closes" the sink. */
+    error(error: unknown): void;
+    /** The sink has completed. This function "closes" the sink. */
+    complete(): void;
+}