@apollo/client 4.0.0-rc.6 → 4.0.0-rc.7

package/link/core/ApolloLink.d.ts

@@ -1,15 +1,361 @@
+import type { DocumentNode, FormattedExecutionResult, OperationTypeNode } from "graphql";
 import type { Observable } from "rxjs";
-import type { ExecuteContext, FetchResult, GraphQLRequest, NextLink, Operation, RequestHandler } from "./types.js";
+import type { ApolloClient, DefaultContext, OperationVariables } from "@apollo/client";
+import type { AdditionalApolloLinkResultTypes } from "./types.js";
+export declare namespace ApolloLink {
+    /**
+     * Context provided for link execution, such as the client executing the
+     * request. It is separate from the request operation context.
+     */
+    interface ExecuteContext {
+        /**
+         * The Apollo Client instance that executed the GraphQL request.
+         */
+        client: ApolloClient;
+    }
+    /**
+    * A function that when called will execute the next link in the link chain.
+    * 
+    * @example
+    * 
+    * ```ts
+    * const link = new ApolloLink((operation, forward) => {
+    *   // process the request
+    * 
+    *   // Call `forward` to execute the next link in the chain
+    *   return forward(operation);
+    * });
+    * ```
+    * 
+    * @param operation - The current `ApolloLink.Operation` object for the
+    * request.
+    */
+    type ForwardFunction = (operation: ApolloLink.Operation) => Observable<ApolloLink.Result>;
+    /**
+     * The input object provided to `ApolloLink.execute` to send a GraphQL request through
+     * the link chain.
+     */
+    interface Request {
+        /**
+         * The parsed GraphQL document that will be sent with the GraphQL request to
+         * the server.
+         */
+        query: DocumentNode;
+        /**
+         * The variables provided for the query.
+         */
+        variables?: OperationVariables;
+        /**
+         * Context provided to the link chain. Context is not sent to the server and
+         * is used to communicate additional metadata from a request to individual
+         * links in the link chain.
+         */
+        context?: DefaultContext;
+        /**
+         * A map of extensions that will be sent with the GraphQL request to the
+         * server.
+         */
+        extensions?: Record<string, any>;
+    }
+    /**
+    * A request handler is responsible for performing some logic and executing the
+    * request, either by [forwarding](https://apollographql.com/docs/react/api/link/introduction#the-request-handler) the operation to the next link in the
+    * chain, or sending the operation to the destination that executes it, such as
+    * a GraphQL server.
+    * 
+    * @param operation - The `Operation` object that provides information about the
+    * currently executed GraphQL request.
+    * 
+    * @param forward - A function that is called to execute the next link in the
+    * chain.
+    */
+    type RequestHandler = (operation: ApolloLink.Operation, forward: ApolloLink.ForwardFunction) => Observable<ApolloLink.Result>;
+    type Result<TData = Record<string, any>, TExtensions = Record<string, any>> = FormattedExecutionResult<TData, TExtensions> | AdditionalApolloLinkResultTypes<TData, TExtensions>[keyof AdditionalApolloLinkResultTypes<TData, TExtensions>];
+    /**
+     * The currently executed operation object provided to an `ApolloLink.RequestHandler`
+     * for each link in the link chain.
+     */
+    interface Operation {
+        /**
+         * A `DocumentNode` that describes the operation taking place.
+         */
+        query: DocumentNode;
+        /**
+         * A map of GraphQL variables being sent with the operation.
+         */
+        variables: OperationVariables;
+        /**
+         * The string name of the GraphQL operation. If it is anonymous,
+         * `operationName` will be `undefined`.
+         */
+        operationName: string | undefined;
+        /**
+         * The type of the GraphQL operation, such as query or mutation.
+         */
+        operationType: OperationTypeNode;
+        /**
+         * A map that stores extensions data to be sent to the server.
+         */
+        extensions: Record<string, any>;
+        /**
+         * A function that takes either a new context object, or a function which
+         * takes in the previous context and returns a new one. See [managing
+         * context](https://apollographql.com/docs/react/api/link/introduction#managing-context).
+         */
+        setContext: {
+            (context: Partial<ApolloLink.OperationContext>): void;
+            (updateContext: (previousContext: Readonly<ApolloLink.OperationContext>) => Partial<ApolloLink.OperationContext>): void;
+        };
+        /**
+         * A function that gets the current context of the request. This can be used
+         * by links to determine which actions to perform. See [managing context](https://apollographql.com/docs/react/api/link/introduction#managing-context)
+         */
+        getContext: () => Readonly<ApolloLink.OperationContext>;
+        /**
+         * The Apollo Client instance executing the request.
+         */
+        readonly client: ApolloClient;
+    }
+    /**
+     * The `context` object that can be read and modified by links using the
+     * `operation.getContext()` and `operation.setContext()` methods.
+     */
+    interface OperationContext extends DefaultContext {
+    }
+    namespace DocumentationTypes {
+        /**
+         * A request handler is responsible for performing some logic and executing the
+         * request, either by [forwarding](https://apollographql.com/docs/react/api/link/introduction#the-request-handler) the operation to the next link in the
+         * chain, or sending the operation to the destination that executes it, such as
+         * a GraphQL server.
+         *
+         * @param operation - The `Operation` object that provides information about the
+         * currently executed GraphQL request.
+         *
+         * @param forward - A function that is called to execute the next link in the
+         * chain.
+         */
+        function RequestHandler(operation: ApolloLink.Operation, forward: ApolloLink.ForwardFunction): Observable<ApolloLink.Result>;
+        /**
+         * A function that when called will execute the next link in the link chain.
+         *
+         * @example
+         *
+         * ```ts
+         * const link = new ApolloLink((operation, forward) => {
+         *   // process the request
+         *
+         *   // Call `forward` to execute the next link in the chain
+         *   return forward(operation);
+         * });
+         * ```
+         *
+         * @param operation - The current `ApolloLink.Operation` object for the
+         * request.
+         */
+        function ForwardFunction(operation: ApolloLink.Operation): Observable<ApolloLink.Result>;
+    }
+}
+/**
+ * The base class for all links in Apollo Client. A link represents either a
+ * self-contained modification to a GraphQL operation or a side effect (such as
+ * logging).
+ *
+ * @remarks
+ *
+ * Links enable you to customize Apollo Client's request flow by composing
+ * together different pieces of functionality into a chain of links. Each
+ * link represents a specific capability, such as adding authentication headers,
+ * retrying failed requests, batching operations, or sending requests to a
+ * GraphQL server.
+ *
+ * Every link must define a request handler via its constructor or by extending
+ * this class and implementing the `request` method.
+ *
+ * @example
+ *
+ * ```ts
+ * import { ApolloLink } from "@apollo/client";
+ *
+ * const link = new ApolloLink((operation, forward) => {
+ *   console.log("Operation:", operation.operationName);
+ *   return forward(operation);
+ * });
+ * ```
+ */
 export declare class ApolloLink {
+    /**
+     * Creates a link that completes immediately and does not emit a result.
+     *
+     * @example
+     *
+     * ```ts
+     * const link = ApolloLink.empty();
+     * ```
+     */
     static empty(): ApolloLink;
-    static from(links: (ApolloLink | RequestHandler)[]): ApolloLink;
-    static split(test: (op: Operation) => boolean, left: ApolloLink | RequestHandler, right?: ApolloLink | RequestHandler): ApolloLink;
-    static execute(link: ApolloLink, operation: GraphQLRequest, context: ExecuteContext): Observable<FetchResult>;
-    static concat(first: ApolloLink | RequestHandler, second: ApolloLink | RequestHandler): ApolloLink;
-    constructor(request?: RequestHandler);
-    split(test: (op: Operation) => boolean, left: ApolloLink | RequestHandler, right?: ApolloLink | RequestHandler): ApolloLink;
-    concat(next: ApolloLink | RequestHandler): ApolloLink;
-    request(operation: Operation, forward?: NextLink): Observable<FetchResult> | null;
+    /**
+     * Composes multiple links into a single composed link that executes each
+     * provided link in serial order.
+     *
+     * @example
+     *
+     * ```ts
+     * import { from, HttpLink, ApolloLink } from "@apollo/client";
+     * import { RetryLink } from "@apollo/client/link/retry";
+     * import MyAuthLink from "../auth";
+     *
+     * const link = ApolloLink.from([
+     *   new RetryLink(),
+     *   new MyAuthLink(),
+     *   new HttpLink({ uri: "http://localhost:4000/graphql" }),
+     * ]);
+     * ```
+     *
+     * @param links - An array of `ApolloLink` instances or request handlers that
+     * are executed in serial order.
+     */
+    static from(links: ApolloLink[]): ApolloLink;
+    /**
+     * Creates a link that conditionally routes a request to different links.
+     *
+     * @example
+     *
+     * ```ts
+     * import { ApolloLink, HttpLink } from "@apollo/client";
+     *
+     * const link = ApolloLink.split(
+     *   (operation) => operation.getContext().version === 1,
+     *   new HttpLink({ uri: "http://localhost:4000/v1/graphql" }),
+     *   new HttpLink({ uri: "http://localhost:4000/v2/graphql" })
+     * );
+     * ```
+     *
+     * @param test - A predicate function that receives the current `operation`
+     * and returns a boolean indicating which link to execute. Returning `true`
+     * executes the `left` link. Returning `false` executes the `right` link.
+     *
+     * @param left - The link that executes when the `test` function returns
+     * `true`.
+     *
+     * @param right - The link that executes when the `test` function returns
+     * `false`. If the `right` link is not provided, the request is forwarded to
+     * the next link in the chain.
+     */
+    static split(test: (op: ApolloLink.Operation) => boolean, left: ApolloLink, right?: ApolloLink): ApolloLink;
+    /**
+     * Executes a GraphQL request against a link. The `execute` function begins
+     * the request by calling the request handler of the link.
+     *
+     * @example
+     *
+     * ```ts
+     * const observable = ApolloLink.execute(link, { query, variables }, { client });
+     *
+     * observable.subscribe({
+     *   next(value) {
+     *     console.log("Received", value);
+     *   },
+     *   error(error) {
+     *     console.error("Oops got error", error);
+     *   },
+     *   complete() {
+     *     console.log("Request complete");
+     *   },
+     * });
+     * ```
+     *
+     * @param link - The `ApolloLink` instance to execute the request.
+     *
+     * @param request - The GraphQL request details, such as the `query` and
+     * `variables`.
+     *
+     * @param context - The execution context for the request, such as the
+     * `client` making the request.
+     */
+    static execute(link: ApolloLink, request: ApolloLink.Request, context: ApolloLink.ExecuteContext): Observable<ApolloLink.Result>;
+    /**
+     * Combines multiple links into a single composed link.
+     *
+     * @example
+     *
+     * ```ts
+     * const link = ApolloLink.concat(firstLink, secondLink, thirdLink);
+     * ```
+     *
+     * @param links - The links to concatenate into a single link. Each link will
+     * execute in serial order.
+     *
+     * @deprecated Use `ApolloLink.from` instead. `ApolloLink.concat` will be
+     * removed in a future major version.
+     */
+    static concat(...links: ApolloLink[]): ApolloLink;
+    constructor(request?: ApolloLink.RequestHandler);
+    /**
+     * Concatenates a link that conditionally routes a request to different links.
+     *
+     * @example
+     *
+     * ```ts
+     * import { ApolloLink, HttpLink } from "@apollo/client";
+     *
+     * const previousLink = new ApolloLink((operation, forward) => {
+     *   // Handle the request
+     *
+     *   return forward(operation);
+     * });
+     *
+     * const link = previousLink.split(
+     *   (operation) => operation.getContext().version === 1,
+     *   new HttpLink({ uri: "http://localhost:4000/v1/graphql" }),
+     *   new HttpLink({ uri: "http://localhost:4000/v2/graphql" })
+     * );
+     * ```
+     *
+     * @param test - A predicate function that receives the current `operation`
+     * and returns a boolean indicating which link to execute. Returning `true`
+     * executes the `left` link. Returning `false` executes the `right` link.
+     *
+     * @param left - The link that executes when the `test` function returns
+     * `true`.
+     *
+     * @param right - The link that executes when the `test` function returns
+     * `false`. If the `right` link is not provided, the request is forwarded to
+     * the next link in the chain.
+     */
+    split(test: (op: ApolloLink.Operation) => boolean, left: ApolloLink, right?: ApolloLink): ApolloLink;
+    /**
+     * Combines the link with other links into a single composed link.
+     *
+     * @example
+     *
+     * ```ts
+     * import { ApolloLink, HttpLink } from "@apollo/client";
+     *
+     * const previousLink = new ApolloLink((operation, forward) => {
+     *   // Handle the request
+     *
+     *   return forward(operation);
+     * });
+     *
+     * const link = previousLink.concat(
+     *   link1,
+     *   link2,
+     *   new HttpLink({ uri: "http://localhost:4000/graphql" })
+     * );
+     * ```
+     */
+    concat(...links: ApolloLink[]): ApolloLink;
+    private combine;
+    /**
+     * Runs the request handler for the provided operation.
+     *
+     * > [!NOTE]
+     * > This is called by the `ApolloLink.execute` function for you and should
+     * > not be called directly. Prefer using `ApolloLink.execute` to make the
+     * > request instead.
+     */
+    request(operation: ApolloLink.Operation, forward: ApolloLink.ForwardFunction): Observable<ApolloLink.Result>;
     /**
     * @internal
     * Used to iterate through all links that are concatenations or `split` links.

package/link/core/ApolloLink.js

@@ -1,79 +1,250 @@
-import { __DEV__ } from "@apollo/client/utilities/environment";
 import { EMPTY } from "rxjs";
-import { createOperation, transformOperation, validateOperation, } from "@apollo/client/link/utils";
+import { createOperation } from "@apollo/client/link/utils";
+import { __DEV__ } from "@apollo/client/utilities/environment";
 import { invariant, newInvariantError, } from "@apollo/client/utilities/invariant";
-function passthrough(op, forward) {
-    return (forward ? forward(op) : EMPTY);
-}
-function toLink(handler) {
-    return typeof handler === "function" ? new ApolloLink(handler) : handler;
-}
-function isTerminating(link) {
-    return link.request.length <= 1;
-}
+/**
+ * The base class for all links in Apollo Client. A link represents either a
+ * self-contained modification to a GraphQL operation or a side effect (such as
+ * logging).
+ *
+ * @remarks
+ *
+ * Links enable you to customize Apollo Client's request flow by composing
+ * together different pieces of functionality into a chain of links. Each
+ * link represents a specific capability, such as adding authentication headers,
+ * retrying failed requests, batching operations, or sending requests to a
+ * GraphQL server.
+ *
+ * Every link must define a request handler via its constructor or by extending
+ * this class and implementing the `request` method.
+ *
+ * @example
+ *
+ * ```ts
+ * import { ApolloLink } from "@apollo/client";
+ *
+ * const link = new ApolloLink((operation, forward) => {
+ *   console.log("Operation:", operation.operationName);
+ *   return forward(operation);
+ * });
+ * ```
+ */
 export class ApolloLink {
+    /**
+     * Creates a link that completes immediately and does not emit a result.
+     *
+     * @example
+     *
+     * ```ts
+     * const link = ApolloLink.empty();
+     * ```
+     */
     static empty() {
         return new ApolloLink(() => EMPTY);
     }
+    /**
+     * Composes multiple links into a single composed link that executes each
+     * provided link in serial order.
+     *
+     * @example
+     *
+     * ```ts
+     * import { from, HttpLink, ApolloLink } from "@apollo/client";
+     * import { RetryLink } from "@apollo/client/link/retry";
+     * import MyAuthLink from "../auth";
+     *
+     * const link = ApolloLink.from([
+     *   new RetryLink(),
+     *   new MyAuthLink(),
+     *   new HttpLink({ uri: "http://localhost:4000/graphql" }),
+     * ]);
+     * ```
+     *
+     * @param links - An array of `ApolloLink` instances or request handlers that
+     * are executed in serial order.
+     */
     static from(links) {
         if (links.length === 0)
             return ApolloLink.empty();
-        return links.map(toLink).reduce((x, y) => x.concat(y));
+        const [first, ...rest] = links;
+        return first.concat(...rest);
     }
-    static split(test, left, right) {
-        const leftLink = toLink(left);
-        const rightLink = toLink(right || new ApolloLink(passthrough));
-        let ret;
-        if (isTerminating(leftLink) && isTerminating(rightLink)) {
-            ret = new ApolloLink((operation) => {
-                return test(operation) ?
-                    leftLink.request(operation) || EMPTY
-                    : rightLink.request(operation) || EMPTY;
-            });
-        }
-        else {
-            ret = new ApolloLink((operation, forward) => {
-                return test(operation) ?
-                    leftLink.request(operation, forward) || EMPTY
-                    : rightLink.request(operation, forward) || EMPTY;
-            });
-        }
-        return Object.assign(ret, { left: leftLink, right: rightLink });
+    /**
+     * Creates a link that conditionally routes a request to different links.
+     *
+     * @example
+     *
+     * ```ts
+     * import { ApolloLink, HttpLink } from "@apollo/client";
+     *
+     * const link = ApolloLink.split(
+     *   (operation) => operation.getContext().version === 1,
+     *   new HttpLink({ uri: "http://localhost:4000/v1/graphql" }),
+     *   new HttpLink({ uri: "http://localhost:4000/v2/graphql" })
+     * );
+     * ```
+     *
+     * @param test - A predicate function that receives the current `operation`
+     * and returns a boolean indicating which link to execute. Returning `true`
+     * executes the `left` link. Returning `false` executes the `right` link.
+     *
+     * @param left - The link that executes when the `test` function returns
+     * `true`.
+     *
+     * @param right - The link that executes when the `test` function returns
+     * `false`. If the `right` link is not provided, the request is forwarded to
+     * the next link in the chain.
+     */
+    static split(test, left, right = new ApolloLink((op, forward) => forward(op))) {
+        const link = new ApolloLink((operation, forward) => {
+            const result = test(operation);
+            if (__DEV__) {
+                if (typeof result !== "boolean") {
+                    __DEV__ && invariant.warn(61, result);
+                }
+            }
+            return result ?
+                left.request(operation, forward)
+                : right.request(operation, forward);
+        });
+        return Object.assign(link, { left, right });
     }
-    static execute(link, operation, context) {
-        return (link.request(createOperation(operation.context, transformOperation(validateOperation(operation)), context)) || EMPTY);
+    /**
+     * Executes a GraphQL request against a link. The `execute` function begins
+     * the request by calling the request handler of the link.
+     *
+     * @example
+     *
+     * ```ts
+     * const observable = ApolloLink.execute(link, { query, variables }, { client });
+     *
+     * observable.subscribe({
+     *   next(value) {
+     *     console.log("Received", value);
+     *   },
+     *   error(error) {
+     *     console.error("Oops got error", error);
+     *   },
+     *   complete() {
+     *     console.log("Request complete");
+     *   },
+     * });
+     * ```
+     *
+     * @param link - The `ApolloLink` instance to execute the request.
+     *
+     * @param request - The GraphQL request details, such as the `query` and
+     * `variables`.
+     *
+     * @param context - The execution context for the request, such as the
+     * `client` making the request.
+     */
+    static execute(link, request, context) {
+        return link.request(createOperation(request, context), () => {
+            if (__DEV__) {
+                __DEV__ && invariant.warn(62);
+            }
+            return EMPTY;
+        });
     }
-    static concat(first, second) {
-        const firstLink = toLink(first);
-        if (isTerminating(firstLink)) {
-            __DEV__ && invariant.warn(62, firstLink);
-            return firstLink;
-        }
-        const nextLink = toLink(second);
-        let ret;
-        if (isTerminating(nextLink)) {
-            ret = new ApolloLink((operation) => firstLink.request(operation, (op) => nextLink.request(op) || EMPTY) ||
-                EMPTY);
-        }
-        else {
-            ret = new ApolloLink((operation, forward) => {
-                return (firstLink.request(operation, (op) => {
-                    return nextLink.request(op, forward) || EMPTY;
-                }) || EMPTY);
-            });
-        }
-        return Object.assign(ret, { left: firstLink, right: nextLink });
+    /**
+     * Combines multiple links into a single composed link.
+     *
+     * @example
+     *
+     * ```ts
+     * const link = ApolloLink.concat(firstLink, secondLink, thirdLink);
+     * ```
+     *
+     * @param links - The links to concatenate into a single link. Each link will
+     * execute in serial order.
+     *
+     * @deprecated Use `ApolloLink.from` instead. `ApolloLink.concat` will be
+     * removed in a future major version.
+     */
+    static concat(...links) {
+        return ApolloLink.from(links);
     }
     constructor(request) {
         if (request)
             this.request = request;
     }
+    /**
+     * Concatenates a link that conditionally routes a request to different links.
+     *
+     * @example
+     *
+     * ```ts
+     * import { ApolloLink, HttpLink } from "@apollo/client";
+     *
+     * const previousLink = new ApolloLink((operation, forward) => {
+     *   // Handle the request
+     *
+     *   return forward(operation);
+     * });
+     *
+     * const link = previousLink.split(
+     *   (operation) => operation.getContext().version === 1,
+     *   new HttpLink({ uri: "http://localhost:4000/v1/graphql" }),
+     *   new HttpLink({ uri: "http://localhost:4000/v2/graphql" })
+     * );
+     * ```
+     *
+     * @param test - A predicate function that receives the current `operation`
+     * and returns a boolean indicating which link to execute. Returning `true`
+     * executes the `left` link. Returning `false` executes the `right` link.
+     *
+     * @param left - The link that executes when the `test` function returns
+     * `true`.
+     *
+     * @param right - The link that executes when the `test` function returns
+     * `false`. If the `right` link is not provided, the request is forwarded to
+     * the next link in the chain.
+     */
     split(test, left, right) {
-        return this.concat(ApolloLink.split(test, left, right || new ApolloLink(passthrough)));
+        return this.concat(ApolloLink.split(test, left, right));
     }
-    concat(next) {
-        return ApolloLink.concat(this, next);
+    /**
+     * Combines the link with other links into a single composed link.
+     *
+     * @example
+     *
+     * ```ts
+     * import { ApolloLink, HttpLink } from "@apollo/client";
+     *
+     * const previousLink = new ApolloLink((operation, forward) => {
+     *   // Handle the request
+     *
+     *   return forward(operation);
+     * });
+     *
+     * const link = previousLink.concat(
+     *   link1,
+     *   link2,
+     *   new HttpLink({ uri: "http://localhost:4000/graphql" })
+     * );
+     * ```
+     */
+    concat(...links) {
+        if (links.length === 0) {
+            return this;
+        }
+        return links.reduce(this.combine.bind(this), this);
     }
+    combine(left, right) {
+        const link = new ApolloLink((operation, forward) => {
+            return left.request(operation, (op) => right.request(op, forward));
+        });
+        return Object.assign(link, { left, right });
+    }
+    /**
+     * Runs the request handler for the provided operation.
+     *
+     * > [!NOTE]
+     * > This is called by the `ApolloLink.execute` function for you and should
+     * > not be called directly. Prefer using `ApolloLink.execute` to make the
+     * > request instead.
+     */
     request(operation, forward) {
         throw newInvariantError(63);
     }