Add generic cache for graphQL querys (as opt-in per query)

[isaacroldan]

WHY are these changes introduced?

Improve performance by adding caching capabilities to GraphQL requests in the CLI.

WHAT is this pull request doing?

Adds caching support for GraphQL requests with configurable TTL options ranging from 1 hour to 30 days. The cache implementation:

• Adds cacheTTL and cacheExtraKey parameters to GraphQL request functions
• Implements cache key generation using query and variable hashing
• Provides predefined TTL options (1h, 6h, 12h, 1d, 3d, 7d, 14d, 30d)

How to test your changes?

1. Make a GraphQL request with caching enabled:

await graphqlRequest({
  query: "...",
  token: "...",
  cacheTTL: "1h",
  cacheExtraKey: "optional-key"
})

2. Make the same request again within the TTL period
3. Verify that the second request returns cached data without making a network call

NOTE: The cache is not enabled right now for any existing query, that will happen in the following PR

Measuring impact

• Existing analytics will cater for this addition (network timing metrics will reflect cached responses)

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes

[isaacroldan]

• Add generic cache for graphQL querys (as opt-in per query) #5343 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	75.34% (-0.11% 🔻)	9015/11965
🟡	Branches	70.49% (-0.14% 🔻)	4396/6236
🟡	Functions	75.22% (-0.04% 🔻)	2365/3144
🟡	Lines	75.86% (-0.1% 🔻)	8517/11227

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / app-event-watcher.ts	95.18% (-1.2% 🔻)	86.49% (-2.7% 🔻)	95.45%	100%
🔴	... / graphql.ts	53.19% (-30.81% 🔻)	18.18% (-19.32% 🔻)	80% (-20% 🔻)	52.17% (-31.16% 🔻)

Test suite run success

2035 tests passing in 909 suites.

Report generated by 🧪jest coverage report action from 5f488a1

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/private/node/conf-store.d.ts

@@ -7,15 +7,17 @@ export type IntrospectionUrlKey = ;
 export type PackageVersionKey = ;
 export type NotificationsKey = ;
 export type NotificationKey = ;
+export type GraphQLRequestKey = ;
 type MostRecentOccurrenceKey = ;
 type RateLimitKey = ;
-type ExportedKey = IntrospectionUrlKey | PackageVersionKey | NotificationsKey | NotificationKey;
+type ExportedKey = IntrospectionUrlKey | PackageVersionKey | NotificationsKey | NotificationKey | GraphQLRequestKey;
 interface Cache {
     [introspectionUrlKey: IntrospectionUrlKey]: CacheValue<string>;
     [packageVersionKey: PackageVersionKey]: CacheValue<string>;
     [notifications: NotificationsKey]: CacheValue<string>;
     [notification: NotificationKey]: CacheValue<string>;
-    [MostRecentOccurrenceKey: MostRecentOccurrenceKey]: CacheValue<boolean>;
+    [graphQLRequestKey: GraphQLRequestKey]: CacheValue<string>;
+    [mostRecentOccurrenceKey: MostRecentOccurrenceKey]: CacheValue<boolean>;
     [rateLimitKey: RateLimitKey]: CacheValue<number[]>;
 }
 export interface ConfSchema {

packages/cli-kit/dist/public/node/api/app-management.d.ts

@@ -1,4 +1,4 @@
-import { GraphQLResponse } from './graphql.js';
+import { CacheOptions, GraphQLResponse } from './graphql.js';
 import { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { Variables } from 'graphql-request';
 /**
@@ -8,9 +8,10 @@ import { Variables } from 'graphql-request';
  * @param query - GraphQL query to execute.
  * @param token - Partners token.
  * @param variables - GraphQL variables to pass to the query.
+ * @param cacheOptions - Cache options for the request. If not present, the request will not be cached.
  * @returns The response of the query of generic type <T>.
  */
-export declare function appManagementRequestDoc<TResult, TVariables extends Variables>(orgId: string, query: TypedDocumentNode<TResult, TVariables>, token: string, variables?: TVariables): Promise<TResult>;
+export declare function appManagementRequestDoc<TResult, TVariables extends Variables>(orgId: string, query: TypedDocumentNode<TResult, TVariables>, token: string, variables?: TVariables, cacheOptions?: CacheOptions): Promise<TResult>;
 /**
  * Sets the next deprecation date from [GraphQL response extensions](https://www.apollographql.com/docs/resources/graphql-glossary/#extensions)
  * if  objects contain a  (ISO 8601-formatted string).

packages/cli-kit/dist/public/node/api/business-platform.d.ts

@@ -1,4 +1,4 @@
-import { Exact, GraphQLVariables } from './graphql.js';
+import { CacheOptions, Exact, GraphQLVariables } from './graphql.js';
 import { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { Variables } from 'graphql-request';
 /**
@@ -7,18 +7,20 @@ import { Variables } from 'graphql-request';
  * @param query - GraphQL query to execute.
  * @param token - Business Platform token.
  * @param variables - GraphQL variables to pass to the query.
+ * @param cacheOptions - Cache options for the request. If not present, the request will not be cached.
  * @returns The response of the query of generic type <T>.
  */
-export declare function businessPlatformRequest<T>(query: string, token: string, variables?: GraphQLVariables): Promise<T>;
+export declare function businessPlatformRequest<T>(query: string, token: string, variables?: GraphQLVariables, cacheOptions?: CacheOptions): Promise<T>;
 /**
  * Executes a GraphQL query against the Business Platform Destinations API. Uses typed documents.
  *
  * @param query - GraphQL query to execute.
  * @param token - Business Platform token.
  * @param variables - GraphQL variables to pass to the query.
+ * @param cacheOptions - Cache options for the request. If not present, the request will not be cached.
  * @returns The response of the query of generic type <TResult>.
  */
-export declare function businessPlatformRequestDoc<TResult, TVariables extends Variables>(query: TypedDocumentNode<TResult, TVariables>, token: string, variables?: TVariables): Promise<TResult>;
+export declare function businessPlatformRequestDoc<TResult, TVariables extends Variables>(query: TypedDocumentNode<TResult, TVariables>, token: string, variables?: TVariables, cacheOptions?: CacheOptions): Promise<TResult>;
 /**
  * Executes a GraphQL query against the Business Platform Organizations API.
  *

packages/cli-kit/dist/public/node/api/graphql.d.ts

@@ -9,6 +9,11 @@ export interface GraphQLVariables {
     [key: string]: any;
 }
 export type GraphQLResponse<T> = Awaited<ReturnType<typeof rawRequest<T>>>;
+export interface CacheOptions {
+    cacheTTL?: CacheTTL;
+    cacheExtraKey?: string;
+}
+export type CacheTTL = '1h' | '6h' | '12h' | '1d' | '3d' | '7d' | '14d' | '30d';
 interface GraphQLRequestBaseOptions<TResult> {
     api: string;
     url: string;
@@ -17,6 +22,8 @@ interface GraphQLRequestBaseOptions<TResult> {
         [header: string]: string;
     };
     responseOptions?: GraphQLResponseOptions<TResult>;
+    cacheTTL?: CacheTTL;
+    cacheExtraKey?: string;
 }
 export type GraphQLRequestOptions<T> = GraphQLRequestBaseOptions<T> & {
     query: RequestDocument;