Create mechanism to add experimental features to Apollo Client (#12915)

* Create mechanism to add experimental features to Apollo Client

* add comment, v1

* Clean up Prettier, Size-limit, and Api-Extractor

---------

Co-authored-by: phryneas <[email protected]>

Author: phryneas

.api-reports/api-report-core.api.md

@@ -195,6 +195,13 @@ export namespace ApolloClient {
         }
     }
     // (undocumented)
+    export interface Experiment {
+        // (undocumented)
+        (this: ApolloClient, options: ApolloClient.Options): void;
+        // (undocumented)
+        v: 1;
+    }
+    // (undocumented)
     export type MutateOptions<TData = unknown, TVariables extends OperationVariables = OperationVariables, TCache extends ApolloCache = ApolloCache> = {
         optimisticResponse?: Unmasked<NoInfer<TData>> | ((vars: TVariables, { IGNORE }: {
             IGNORE: IgnoreModifier;
@@ -231,6 +238,7 @@ export namespace ApolloClient {
         documentTransform?: DocumentTransform;
         // (undocumented)
         enhancedClientAwareness?: ClientAwarenessLink.EnhancedClientAwarenessOptions;
+        experiments?: ApolloClient.Experiment[];
         incrementalHandler?: Incremental.Handler<any>;
         link: ApolloLink;
         // (undocumented)
@@ -1132,7 +1140,7 @@ export type WatchQueryOptions<TVariables extends OperationVariables = OperationV
 
 // Warnings were encountered during analysis:
 //
-// src/core/ApolloClient.ts:353:5 - (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts
+// src/core/ApolloClient.ts:362:5 - (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts
 // src/core/ObservableQuery.ts:368:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts
 // src/core/QueryManager.ts:180:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts
 

.api-reports/api-report.api.md

@@ -201,6 +201,13 @@ export namespace ApolloClient {
             variables?: TVariables;
         }
     }
+    // (undocumented)
+    export interface Experiment {
+        // (undocumented)
+        (this: ApolloClient, options: ApolloClient.Options): void;
+        // (undocumented)
+        v: 1;
+    }
     // Warning: (ae-forgotten-export) The symbol "VariablesOption" needs to be exported by the entry point index.d.ts
     //
     // (undocumented)
@@ -242,6 +249,7 @@ export namespace ApolloClient {
         documentTransform?: DocumentTransform;
         // (undocumented)
         enhancedClientAwareness?: ClientAwarenessLink.EnhancedClientAwarenessOptions;
+        experiments?: ApolloClient.Experiment[];
         // Warning: (ae-forgotten-export) The symbol "Incremental" needs to be exported by the entry point index.d.ts
         incrementalHandler?: Incremental.Handler<any>;
         link: ApolloLink;
@@ -2711,8 +2719,8 @@ interface WriteContext extends ReadMergeModifyContext {
 // src/cache/inmemory/policies.ts:167:3 - (ae-forgotten-export) The symbol "KeySpecifier" needs to be exported by the entry point index.d.ts
 // src/cache/inmemory/policies.ts:167:3 - (ae-forgotten-export) The symbol "KeyArgsFunction" needs to be exported by the entry point index.d.ts
 // src/cache/inmemory/types.ts:134:3 - (ae-forgotten-export) The symbol "KeyFieldsFunction" needs to be exported by the entry point index.d.ts
-// src/core/ApolloClient.ts:159:5 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts
-// src/core/ApolloClient.ts:353:5 - (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts
+// src/core/ApolloClient.ts:168:5 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts
+// src/core/ApolloClient.ts:362:5 - (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts
 // src/core/ObservableQuery.ts:368:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts
 // src/core/QueryManager.ts:180:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts
 // src/local-state/LocalState.ts:147:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts

.changeset/olive-queens-fold.md

@@ -0,0 +1,5 @@
+---
+"@apollo/client": patch
+---
+
+Create mechanism to add experimental features to Apollo Client

.size-limits.json

@@ -1,6 +1,6 @@
 {
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 44574,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 39359,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 33705,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27700
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 44542,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 39461,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 33696,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 27707
 }

src/core/ApolloClient.ts

@@ -132,6 +132,15 @@ export declare namespace ApolloClient {
      * queries.
      */
     incrementalHandler?: Incremental.Handler<any>;
+
+    /**
+     * @experimental
+     * Allows passing in "experiments", experimental features that might one day
+     * become part of Apollo Client's core functionality.
+     * Keep in mind that these features might change the core of Apollo Client.
+     * Do not pass in experiments that are not provided by Apollo.
+     */
+    experiments?: ApolloClient.Experiment[];
   }
 
   interface DevtoolsOptions {
@@ -610,6 +619,11 @@ export declare namespace ApolloClient {
       variables?: TVariables;
     }
   }
+
+  export interface Experiment {
+    (this: ApolloClient, options: ApolloClient.Options): void;
+    v: 1;
+  }
 }
 
 /**
@@ -708,6 +722,7 @@ export class ApolloClient {
       dataMasking,
       link,
       incrementalHandler = new NotImplementedHandler(),
+      experiments = [],
     } = options;
 
     this.link = link;
@@ -759,6 +774,8 @@ export class ApolloClient {
     }
 
     if (this.devtoolsConfig.enabled) this.connectToDevTools();
+
+    experiments.forEach((experiment) => experiment.call(this, options));
   }
 
   private connectToDevTools() {