@apollo/client 4.0.0-alpha.16 → 4.0.0-alpha.18

package/CHANGELOG.md

@@ -1,5 +1,138 @@
 # @apollo/client
 
+## 4.0.0-alpha.18
+
+### Minor Changes
+
+- [#12670](https://github.com/apollographql/apollo-client/pull/12670) [`0a880ea`](https://github.com/apollographql/apollo-client/commit/0a880ea4c2360a985fdd2edadb94fcc4b82bad73) Thanks [@phryneas](https://github.com/phryneas)! - Provide a mechanism to override the DataMasking types.
+
+  Up until now, our types `Masked`, `MaskedDocumentNode`, `FragmentType`, `MaybeMasked` and `Unmasked` would assume that you are stictly using the type output format of GraphQL Codegen.
+
+  With this change, you can now modify the behaviour of those types if you use a different form of codegen that produces different types for your queries.
+
+  A simple implementation that would override the `Masked` type to remove all fields starting with `_` from a type would look like this:
+
+  ```ts
+  // your actual implementation of `Masked`
+  type CustomMaskedImplementation<TData> = {
+    [K in keyof TData as K extends `_${string}` ? never : K]: TData[K];
+  };
+
+  import { HKT } from "@apollo/client/utilities";
+  // transform this type into a higher kinded type that can be evaulated at a later time
+  interface CustomMaskedType extends HKT {
+    arg1: unknown; // TData
+    return: CustomMaskedImplementation<this["arg1"]>;
+  }
+
+  // create an "implementation interface" for the types you want to override
+  export interface CustomDataMaskingImplementation {
+    Masked: CustomMaskedType;
+    // other possible keys: `MaskedDocumentNode`, `FragmentType`, `MaybeMasked` and `Unmasked`
+  }
+  ```
+
+  then you would use that `CustomDataMaskingImplementation` interface in your project to extend the `DataMasking` interface exported by `@apollo/client` with it's functionality:
+
+  ```ts
+  declare module "@apollo/client" {
+    export interface DataMasking extends CustomDataMaskingImplementation {}
+  }
+  ```
+
+  After that, all internal usage of `Masked` in Apollo Client as well as all usage in your code base will use the new `CustomMaskedType` implementation.
+
+  If you don't specify overrides, Apollo Client will still default to the GraphQL Codegen data masking implementation.
+  The types for that are also explicitly exported as the `GraphQLCodegenDataMasking` namespace in `@apollo/client/masking`.
+
+## 4.0.0-alpha.17
+
+### Major Changes
+
+- [#12649](https://github.com/apollographql/apollo-client/pull/12649) [`0be92ad`](https://github.com/apollographql/apollo-client/commit/0be92ad51cf8de444fa1cc507bab2c21d230a44e) Thanks [@jerelmiller](https://github.com/jerelmiller)! - The `TData` generic provided to types that return a `dataState` property is now modified by the given `DataState` generic instead of passing a modified `TData` type. For example, a `QueryRef` that could return partial data was defined as `QueryRef<DeepPartial<TData>, TVariables>`. Now `TData` should be provided unmodified and a set of allowed states should be given instead: `QueryRef<TData, TVariables, 'complete' | 'streaming' | 'partial'>`.
+
+  To migrate, use the following guide to replace your type with the right set of states (all types listed below are changed the same way):
+
+  ```diff
+  - QueryRef<TData, TVariables>
+  // `QueryRef`'s default is 'complete' | 'streaming' so this can also be left alone if you prefer
+  // All other types affected by this change default to all states
+  + QueryRef<TData, TVariables>
+  + QueryRef<TData, TVariables, 'complete' | 'streaming'>
+
+  - QueryRef<TData | undefined, TVariables>
+  + QueryRef<TData, TVariables, 'complete' | 'streaming' | 'empty'>
+
+  - QueryRef<DeepPartial<TData>, TVariables>
+  + QueryRef<TData, TVariables, 'complete' | 'streaming' | 'partial'>
+
+  - QueryRef<DeepPartial<TData> | undefined, TVariables>
+  + QueryRef<TData, TVariables, 'complete' | 'streaming' | 'partial' | 'empty'>
+  ```
+
+  The following types are affected. Provide the allowed `dataState` values to the `TDataState` generic:
+
+  - `ApolloQueryResult`
+  - `QueryRef`
+  - `PreloadedQueryRef`
+  - `useLazyQuery.Result`
+  - `useQuery.Result`
+  - `useReadQuery.Result`
+  - `useSuspenseQuery.Result`
+
+  All `*QueryRef` types default to `complete | streaming` states while the rest of the types default to `'complete' | 'streaming' | 'partial' | 'empty'` states. You shouldn't need to provide the states unless you need to either allow for partial data/empty values (`*QueryRef`) or a restricted set of states.
+
+- [#12649](https://github.com/apollographql/apollo-client/pull/12649) [`0be92ad`](https://github.com/apollographql/apollo-client/commit/0be92ad51cf8de444fa1cc507bab2c21d230a44e) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Remove the deprecated `QueryReference` type. Please use `QueryRef` instead.
+
+- [#12633](https://github.com/apollographql/apollo-client/pull/12633) [`9bfb51f`](https://github.com/apollographql/apollo-client/commit/9bfb51fdbca69560da71f9012c74ee172b6c2b69) Thanks [@phryneas](https://github.com/phryneas)! - If the `execute` function of `useLazyQuery` is executed, previously started queries
+  from the same `useLazyQuery` usage will be rejected with an `AbortError` unless
+  `.retain()` is called on the promise returned by previous `execute` calls.
+
+  Please keep in mind that `useLazyQuery` is primarily meant as a means to synchronize
+  your component to the status of a query and that it's purpose it not to make a
+  series of network calls.
+  If you plan on making a series of network calls without the need to synchronize
+  the result with your component, consider using `ApolloClient.query` instead.
+
+### Minor Changes
+
+- [#12633](https://github.com/apollographql/apollo-client/pull/12633) [`9bfb51f`](https://github.com/apollographql/apollo-client/commit/9bfb51fdbca69560da71f9012c74ee172b6c2b69) Thanks [@phryneas](https://github.com/phryneas)! - `ObservableQuery.refetch` and `ObservableQuery.reobserve` and the `execute` function of `useLazyQuery` now return a
+  `ResultPromise` with an additional `.retain` method.
+  If this method is called, the underlying network operation will be kept running even if the `ObservableQuery` itself does
+  not require the result anymore, and the Promise will resolve with the final result instead of resolving with an intermediate
+  result in the case of early cancellation.
+
+- [#12649](https://github.com/apollographql/apollo-client/pull/12649) [`0be92ad`](https://github.com/apollographql/apollo-client/commit/0be92ad51cf8de444fa1cc507bab2c21d230a44e) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add a new `dataState` property that determines the completeness of the `data` property. `dataState` helps narrow the type of `data`. `dataState` is now emitted from `ObservableQuery` and returned from all React hooks that return a `data` property.
+
+  The `dataState` values are:
+
+  - `empty`: No data could be fulfilled from the cache or the result is incomplete. `data` is `undefined`.
+  - `partial`: Some data could be fulfilled from the cache but `data` is incomplete. This is only possible when `returnPartialData` is `true`.
+  - `streaming`: `data` is incomplete as a result of a deferred query and the result is still streaming in.
+  - `complete`: `data` is a fully satisfied query result fulfilled either from the cache or network.
+
+  Example:
+
+  ```ts
+  const { data, dataState } = useQuery<TData>(query);
+
+  if (dataState === "empty") {
+    expectTypeOf(data).toEqualTypeOf<undefined>();
+  }
+
+  if (dataState === "partial") {
+    expectTypeOf(data).toEqualTypeOf<DeepPartial<TData>>();
+  }
+
+  if (dataState === "streaming") {
+    expectTypeOf(data).toEqualTypeOf<TData>();
+  }
+
+  if (dataState === "complete") {
+    expectTypeOf(data).toEqualTypeOf<TData>();
+  }
+  ```
+
 ## 4.0.0-alpha.16
 
 ### Major Changes

package/__cjs/core/ObservableQuery.cjs

@@ -15,17 +15,18 @@ const invariant_1 = require("@apollo/client/utilities/invariant");
 const equalByQuery_js_1 = require("./equalByQuery.cjs");
 const networkStatus_js_1 = require("./networkStatus.cjs");
 const { assign, hasOwnProperty } = Object;
-const newNetworkStatusSymbol = Symbol();
 const uninitialized = {
     loading: true,
     networkStatus: networkStatus_js_1.NetworkStatus.loading,
     data: undefined,
+    dataState: "empty",
     partial: true,
 };
 const empty = {
     loading: false,
     networkStatus: networkStatus_js_1.NetworkStatus.ready,
     data: undefined,
+    dataState: "empty",
     partial: true,
 };
 class ObservableQuery {
@@ -208,19 +209,23 @@ class ObservableQuery {
             : initialFetchPolicy || this.options.fetchPolicy;
         const defaultResult = {
             data: undefined,
+            dataState: "empty",
             loading: true,
             networkStatus: networkStatus_js_1.NetworkStatus.loading,
             partial: true,
         };
         const cacheResult = () => {
             const diff = this.getCacheDiff();
+            // TODO: queryInfo.getDiff should handle this since cache.diff returns a
+            // null when returnPartialData is false
+            const data = this.options.returnPartialData || diff.complete ?
+                diff.result ?? undefined
+                : undefined;
             return this.maskResult({
-                data: 
-                // TODO: queryInfo.getDiff should handle this since cache.diff returns a
-                // null when returnPartialData is false
-                this.options.returnPartialData || diff.complete ?
-                    diff.result ?? undefined
-                    : undefined,
+                data,
+                dataState: diff.complete ? "complete"
+                    : data === undefined ? "empty"
+                        : "partial",
                 loading: !diff.complete,
                 networkStatus: diff.complete ? networkStatus_js_1.NetworkStatus.ready : networkStatus_js_1.NetworkStatus.loading,
                 partial: !diff.complete,
@@ -373,9 +378,8 @@ class ObservableQuery {
                 this.getVariablesWithDefaults({ ...this.variables, ...variables });
         }
         this.queryInfo.resetLastWrite();
-        return this.reobserve({
-            ...reobserveOptions,
-            [newNetworkStatusSymbol]: networkStatus_js_1.NetworkStatus.refetch,
+        return this._reobserve(reobserveOptions, {
+            newNetworkStatus: networkStatus_js_1.NetworkStatus.refetch,
         });
     }
     /**
@@ -501,6 +505,7 @@ class ObservableQuery {
                         // will be overwritten anyways, just here for types sake
                         loading: false,
                         data: data,
+                        dataState: lastResult.dataState === "streaming" ? "streaming" : "complete",
                     },
                     source: "network",
                 });
@@ -607,12 +612,11 @@ class ObservableQuery {
         if (!this.hasObservers()) {
             return (0, internal_1.toQueryResult)(this.getCurrentResult());
         }
-        return this.reobserve({
+        return this._reobserve({
             // Reset options.fetchPolicy to its original value.
             fetchPolicy: this.options.initialFetchPolicy,
             variables,
-            [newNetworkStatusSymbol]: networkStatus_js_1.NetworkStatus.setVariables,
-        });
+        }, { newNetworkStatus: networkStatus_js_1.NetworkStatus.setVariables });
     }
     /**
      * A function that enables you to update the query's cached result without executing a followup GraphQL operation.
@@ -684,7 +688,7 @@ class ObservableQuery {
         }
         return options.fetchPolicy;
     }
-    fetch(options, networkStatus, fetchQuery) {
+    fetch(options, networkStatus, fetchQuery, operator) {
         // TODO Make sure we update the networkStatus (and infer fetchVariables)
         // before actually committing to the fetch.
         const initialFetchPolicy = this.options.fetchPolicy;
@@ -735,7 +739,7 @@ class ObservableQuery {
                 }
             }
         });
-        const { observable, fromLink } = this.queryManager.fetchObservableWithInfo(queryInfo, options, { networkStatus, query: fetchQuery, onCacheHit, fetchQueryOperator });
+        let { observable, fromLink } = this.queryManager.fetchObservableWithInfo(queryInfo, options, { networkStatus, query: fetchQuery, onCacheHit, fetchQueryOperator });
         // track query and variables from the start of the operation
         const { query, variables } = this;
         const operation = {
@@ -746,6 +750,7 @@ class ObservableQuery {
         this.activeOperations.add(operation);
         let forceFirstValueEmit = networkStatus == networkStatus_js_1.NetworkStatus.refetch ||
             networkStatus == networkStatus_js_1.NetworkStatus.setVariables;
+        observable = observable.pipe(operator, (0, rxjs_1.share)());
         const subscription = observable
             .pipe((0, rxjs_1.tap)({
             next: (notification) => {
@@ -795,7 +800,7 @@ class ObservableQuery {
             if (this.pollingInfo) {
                 if (!(0, networkStatus_js_1.isNetworkRequestInFlight)(this.networkStatus) &&
                     !this.options.skipPollAttempt?.()) {
-                    this.reobserve({
+                    this._reobserve({
                         // Most fetchPolicy options don't make sense to use in a polling context, as
                         // users wouldn't want to be polling the cache directly. However, network-only and
                         // no-cache are both useful for when the user wants to control whether or not the
@@ -803,7 +808,8 @@ class ObservableQuery {
                         fetchPolicy: this.options.initialFetchPolicy === "no-cache" ?
                             "no-cache"
                             : "network-only",
-                        [newNetworkStatusSymbol]: networkStatus_js_1.NetworkStatus.poll,
+                    }, {
+                        newNetworkStatus: networkStatus_js_1.NetworkStatus.poll,
                     }).then(poll, poll);
                 }
                 else {
@@ -832,13 +838,11 @@ class ObservableQuery {
      * merged with the current options when given.
      */
     reobserve(newOptions) {
+        return this._reobserve(newOptions);
+    }
+    _reobserve(newOptions, internalOptions) {
         this.isTornDown = false;
-        let newNetworkStatus;
-        if (newOptions) {
-            newNetworkStatus = newOptions[newNetworkStatusSymbol];
-            // Avoid setting the symbol option in this.options
-            delete newOptions[newNetworkStatusSymbol];
-        }
+        let { newNetworkStatus } = internalOptions || {};
         const useDisposableObservable = 
         // Refetching uses a disposable Observable to allow refetches using different
         // options, without permanently altering the options of the
@@ -913,32 +917,38 @@ class ObservableQuery {
             this.cancelPolling();
         }
         this.resubscribeCache();
-        const { subscription, observable, fromLink } = this.fetch(options, newNetworkStatus, query);
-        if (!useDisposableObservable && (fromLink || !this.linkSubscription)) {
-            if (this.linkSubscription) {
-                this.linkSubscription.unsubscribe();
-            }
-            this.linkSubscription = subscription;
-        }
-        return (0, internal_1.preventUnhandledRejection)(
-        // Note: lastValueFrom will create a separate subscription to the
-        // observable which means that terminating this ObservableQuery will not
-        // cancel the request from the link chain.
-        (0, rxjs_1.lastValueFrom)(observable.pipe((0, internal_1.filterMap)((value) => {
+        const { promise, operator: promiseOperator } = getTrackingOperatorPromise((value) => {
             switch (value.kind) {
                 case "E":
                     throw value.error;
                 case "N":
-                    if (value.source !== "newNetworkStatus")
+                    if (value.source !== "newNetworkStatus" && !value.value.loading)
                         return value.value;
             }
-        })), {
-            // This default value should only be used when using a `fetchPolicy` of
-            // `standby` since that fetch policy completes without emitting a
-            // result. Since we are converting this to a QueryResult type, we
-            // omit the extra fields from ApolloQueryResult in the default value.
-            defaultValue: { data: undefined },
-        }).then((result) => (0, internal_1.toQueryResult)(this.maskResult(result))));
+        }, 
+        // This default value should only be used when using a `fetchPolicy` of
+        // `standby` since that fetch policy completes without emitting a
+        // result. Since we are converting this to a QueryResult type, we
+        // omit the extra fields from ApolloQueryResult in the default value.
+        options.fetchPolicy === "standby" ?
+            { data: undefined }
+            : undefined);
+        const { subscription, observable, fromLink } = this.fetch(options, newNetworkStatus, query, promiseOperator);
+        if (!useDisposableObservable && (fromLink || !this.linkSubscription)) {
+            if (this.linkSubscription) {
+                this.linkSubscription.unsubscribe();
+            }
+            this.linkSubscription = subscription;
+        }
+        const ret = Object.assign((0, internal_1.preventUnhandledRejection)(promise.then((result) => (0, internal_1.toQueryResult)(this.maskResult(result)))), {
+            retain: () => {
+                const subscription = observable.subscribe({});
+                const unsubscribe = () => subscription.unsubscribe();
+                promise.then(unsubscribe, unsubscribe);
+                return ret;
+            },
+        });
+        return ret;
     }
     hasObservers() {
         return this.subject.observed;
@@ -1051,6 +1061,9 @@ class ObservableQuery {
                     kind: "N",
                     value: {
                         data: diff.result,
+                        dataState: diff.complete ? "complete"
+                            : diff.result ? "partial"
+                                : "empty",
                         networkStatus: networkStatus_js_1.NetworkStatus.ready,
                         loading: false,
                         error: undefined,
@@ -1167,14 +1180,17 @@ class ObservableQuery {
             result =
                 notification.kind === "E" ?
                     {
-                        data: undefined,
-                        partial: true,
-                        ...(isEqualQuery(previous, notification) ? previous.result : {}),
+                        ...(isEqualQuery(previous, notification) ?
+                            previous.result
+                            : { data: undefined, dataState: "empty", partial: true }),
                         error: notification.error,
                         networkStatus: networkStatus_js_1.NetworkStatus.error,
                         loading: false,
                     }
                     : notification.value;
+            if (result.error && result.dataState === "streaming") {
+                result.dataState = "complete";
+            }
             if (result.error) {
                 meta.shouldEmit = 1 /* EmitBehavior.force */;
             }
@@ -1213,7 +1229,7 @@ class ObservableQuery {
     reobserveCacheFirst() {
         const { fetchPolicy, nextFetchPolicy } = this.options;
         if (fetchPolicy === "cache-and-network" || fetchPolicy === "network-only") {
-            return this.reobserve({
+            this.reobserve({
                 fetchPolicy: "cache-first",
                 // Use a temporary nextFetchPolicy function that replaces itself with the
                 // previous nextFetchPolicy value and returns the original fetchPolicy.
@@ -1231,7 +1247,9 @@ class ObservableQuery {
                 },
             });
         }
-        return this.reobserve();
+        else {
+            this.reobserve();
+        }
     }
     getVariablesWithDefaults(variables) {
         return this.queryManager.getVariables(this.query, variables);
@@ -1246,4 +1264,42 @@ function logMissingFieldErrors(missing) {
 function isEqualQuery(a, b) {
     return !!(a && b && a.query === b.query && (0, equality_1.equal)(a.variables, b.variables));
 }
+function getTrackingOperatorPromise(filterMapCb, defaultValue) {
+    let lastValue = defaultValue, resolve, reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    const operator = (0, rxjs_1.tap)({
+        next(value) {
+            try {
+                const newValue = filterMapCb(value);
+                if (newValue !== undefined) {
+                    lastValue = newValue;
+                }
+            }
+            catch (error) {
+                reject(error);
+            }
+        },
+        finalize: () => {
+            if (lastValue) {
+                resolve(lastValue);
+            }
+            else {
+                const message = "The operation was aborted.";
+                const name = "AbortError";
+                reject(typeof DOMException !== "undefined" ?
+                    new DOMException(message, name)
+                    // some environments do not have `DOMException`, e.g. node
+                    // uses a normal `Error` with a `name` property instead: https://github.com/phryneas/node/blob/d0579b64f0f6b722f8e49bf8a471dd0d0604a21e/lib/internal/errors.js#L964
+                    // error.code is a legacy property that is not used anymore,
+                    // and also inconsistent across environments (in supporting
+                    // browsers it is `20`, in node `'ABORT_ERR'`) so we omit that.
+                    : Object.assign(new Error(message), { name }));
+            }
+        },
+    });
+    return { promise, operator };
+}
 //# sourceMappingURL=ObservableQuery.cjs.map