graphql-http 0.1.0 → 1.0.0

package/lib/client.d.ts

@@ -0,0 +1,147 @@
+/**
+ *
+ * client
+ *
+ */
+import { 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.
+     */
+    url: string | (() => 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);
+}
+interface ResponseLike {
+    readonly ok: boolean;
+    readonly status: number;
+    readonly statusText: string;
+}

package/lib/client.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ *
+ * client
+ *
+ */
+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.NetworkError = exports.createClient = void 0;
+const utils_1 = require("./utils");
+/** This file is the entry point for browsers, re-export common elements. */
+__exportStar(require("./common"), exports);
+/**
+ * Creates a disposable GraphQL over HTTP client to transmit
+ * GraphQL operation results.
+ *
+ * @category Client
+ */
+function createClient(options) {
+    const { credentials = 'same-origin', referrer, referrerPolicy, shouldRetry = () => false, } = options;
+    const fetchFn = (options.fetchFn || fetch);
+    const AbortControllerImpl = (options.abortControllerImpl ||
+        AbortController);
+    // we dont use yet another AbortController here because of
+    // node's max EventEmitters listeners being only 10
+    const client = (() => {
+        let disposed = false;
+        const listeners = [];
+        return {
+            get disposed() {
+                return disposed;
+            },
+            onDispose(cb) {
+                if (disposed) {
+                    // empty the call stack and then call the cb
+                    setTimeout(() => cb(), 0);
+                    return () => {
+                        // noop
+                    };
+                }
+                listeners.push(cb);
+                return () => {
+                    listeners.splice(listeners.indexOf(cb), 1);
+                };
+            },
+            dispose() {
+                if (disposed)
+                    return;
+                disposed = true;
+                // we copy the listeners so that onDispose unlistens dont "pull the rug under our feet"
+                for (const listener of [...listeners]) {
+                    listener();
+                }
+            },
+        };
+    })();
+    return {
+        subscribe(request, sink) {
+            if (client.disposed)
+                throw new Error('Client has been disposed');
+            const control = new AbortControllerImpl();
+            const unlisten = client.onDispose(() => {
+                unlisten();
+                control.abort();
+            });
+            (async () => {
+                var _a;
+                let retryingErr = null, retries = 0;
+                for (;;) {
+                    if (retryingErr) {
+                        const should = await shouldRetry(retryingErr, retries);
+                        // requst might've been canceled while waiting for retry
+                        if (control.signal.aborted)
+                            return;
+                        if (!should)
+                            throw retryingErr;
+                        retries++;
+                    }
+                    try {
+                        const url = typeof options.url === 'function'
+                            ? await options.url()
+                            : options.url;
+                        if (control.signal.aborted)
+                            return;
+                        const headers = typeof options.headers === 'function'
+                            ? await options.headers()
+                            : (_a = options.headers) !== null && _a !== void 0 ? _a : {};
+                        if (control.signal.aborted)
+                            return;
+                        let res;
+                        try {
+                            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' }),
+                                credentials,
+                                referrer,
+                                referrerPolicy,
+                                body: JSON.stringify(request),
+                            });
+                        }
+                        catch (err) {
+                            throw new NetworkError(err);
+                        }
+                        if (!res.ok)
+                            throw new NetworkError(res);
+                        if (!res.body)
+                            throw new Error('Missing response body');
+                        const contentType = res.headers.get('content-type');
+                        if (!contentType)
+                            throw new Error('Missing response content-type');
+                        if (!contentType.includes('application/graphql+json') &&
+                            !contentType.includes('application/json')) {
+                            throw new Error(`Unsupported response content-type ${contentType}`);
+                        }
+                        const result = await res.json();
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        sink.next(result);
+                        return control.abort();
+                    }
+                    catch (err) {
+                        if (control.signal.aborted)
+                            return;
+                        // all non-network errors are worth reporting immediately
+                        if (!(err instanceof NetworkError))
+                            throw err;
+                        // try again
+                        retryingErr = err;
+                    }
+                }
+            })()
+                .then(() => sink.complete())
+                .catch((err) => sink.error(err));
+            return () => control.abort();
+        },
+        dispose() {
+            client.dispose();
+        },
+    };
+}
+exports.createClient = createClient;
+/**
+ * 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
+ */
+class NetworkError extends Error {
+    constructor(msgOrErrOrResponse) {
+        let message, response;
+        if (isResponseLike(msgOrErrOrResponse)) {
+            response = msgOrErrOrResponse;
+            message =
+                'Server responded with ' +
+                    msgOrErrOrResponse.status +
+                    ': ' +
+                    msgOrErrOrResponse.statusText;
+        }
+        else if (msgOrErrOrResponse instanceof Error)
+            message = msgOrErrOrResponse.message;
+        else
+            message = String(msgOrErrOrResponse);
+        super(message);
+        this.name = this.constructor.name;
+        this.response = response;
+    }
+}
+exports.NetworkError = NetworkError;
+function isResponseLike(val) {
+    return ((0, utils_1.isObject)(val) &&
+        typeof val['ok'] === 'boolean' &&
+        typeof val['status'] === 'number' &&
+        typeof val['statusText'] === 'string');
+}

package/lib/client.mjs

@@ -0,0 +1,170 @@
+/**
+ *
+ * client
+ *
+ */
+import { isObject } from './utils.mjs';
+/** This file is the entry point for browsers, re-export common elements. */
+export * from './common.mjs';
+/**
+ * Creates a disposable GraphQL over HTTP client to transmit
+ * GraphQL operation results.
+ *
+ * @category Client
+ */
+export function createClient(options) {
+    const { credentials = 'same-origin', referrer, referrerPolicy, shouldRetry = () => false, } = options;
+    const fetchFn = (options.fetchFn || fetch);
+    const AbortControllerImpl = (options.abortControllerImpl ||
+        AbortController);
+    // we dont use yet another AbortController here because of
+    // node's max EventEmitters listeners being only 10
+    const client = (() => {
+        let disposed = false;
+        const listeners = [];
+        return {
+            get disposed() {
+                return disposed;
+            },
+            onDispose(cb) {
+                if (disposed) {
+                    // empty the call stack and then call the cb
+                    setTimeout(() => cb(), 0);
+                    return () => {
+                        // noop
+                    };
+                }
+                listeners.push(cb);
+                return () => {
+                    listeners.splice(listeners.indexOf(cb), 1);
+                };
+            },
+            dispose() {
+                if (disposed)
+                    return;
+                disposed = true;
+                // we copy the listeners so that onDispose unlistens dont "pull the rug under our feet"
+                for (const listener of [...listeners]) {
+                    listener();
+                }
+            },
+        };
+    })();
+    return {
+        subscribe(request, sink) {
+            if (client.disposed)
+                throw new Error('Client has been disposed');
+            const control = new AbortControllerImpl();
+            const unlisten = client.onDispose(() => {
+                unlisten();
+                control.abort();
+            });
+            (async () => {
+                var _a;
+                let retryingErr = null, retries = 0;
+                for (;;) {
+                    if (retryingErr) {
+                        const should = await shouldRetry(retryingErr, retries);
+                        // requst might've been canceled while waiting for retry
+                        if (control.signal.aborted)
+                            return;
+                        if (!should)
+                            throw retryingErr;
+                        retries++;
+                    }
+                    try {
+                        const url = typeof options.url === 'function'
+                            ? await options.url()
+                            : options.url;
+                        if (control.signal.aborted)
+                            return;
+                        const headers = typeof options.headers === 'function'
+                            ? await options.headers()
+                            : (_a = options.headers) !== null && _a !== void 0 ? _a : {};
+                        if (control.signal.aborted)
+                            return;
+                        let res;
+                        try {
+                            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' }),
+                                credentials,
+                                referrer,
+                                referrerPolicy,
+                                body: JSON.stringify(request),
+                            });
+                        }
+                        catch (err) {
+                            throw new NetworkError(err);
+                        }
+                        if (!res.ok)
+                            throw new NetworkError(res);
+                        if (!res.body)
+                            throw new Error('Missing response body');
+                        const contentType = res.headers.get('content-type');
+                        if (!contentType)
+                            throw new Error('Missing response content-type');
+                        if (!contentType.includes('application/graphql+json') &&
+                            !contentType.includes('application/json')) {
+                            throw new Error(`Unsupported response content-type ${contentType}`);
+                        }
+                        const result = await res.json();
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        sink.next(result);
+                        return control.abort();
+                    }
+                    catch (err) {
+                        if (control.signal.aborted)
+                            return;
+                        // all non-network errors are worth reporting immediately
+                        if (!(err instanceof NetworkError))
+                            throw err;
+                        // try again
+                        retryingErr = err;
+                    }
+                }
+            })()
+                .then(() => sink.complete())
+                .catch((err) => sink.error(err));
+            return () => control.abort();
+        },
+        dispose() {
+            client.dispose();
+        },
+    };
+}
+/**
+ * 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 class NetworkError extends Error {
+    constructor(msgOrErrOrResponse) {
+        let message, response;
+        if (isResponseLike(msgOrErrOrResponse)) {
+            response = msgOrErrOrResponse;
+            message =
+                'Server responded with ' +
+                    msgOrErrOrResponse.status +
+                    ': ' +
+                    msgOrErrOrResponse.statusText;
+        }
+        else if (msgOrErrOrResponse instanceof Error)
+            message = msgOrErrOrResponse.message;
+        else
+            message = String(msgOrErrOrResponse);
+        super(message);
+        this.name = this.constructor.name;
+        this.response = response;
+    }
+}
+function isResponseLike(val) {
+    return (isObject(val) &&
+        typeof val['ok'] === 'boolean' &&
+        typeof val['status'] === 'number' &&
+        typeof val['statusText'] === 'string');
+}

package/lib/common.d.ts

@@ -0,0 +1,98 @@
+/**
+ *
+ * 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.
+ *
+ * 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;
+}
+/**
+ * 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.
+ *
+ * @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;
+}

package/lib/common.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ *
+ * common
+ *
+ */
+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

@@ -0,0 +1,15 @@
+/**
+ *
+ * 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]);
+}