feat(client-core): add CacheMode type (#10091)

* feat(client-core): add CacheMode type

* feat(client-core): add synchronization comment for CacheMode type

Author: johancube

packages/cubejs-client-core/src/index.ts

@@ -6,6 +6,7 @@ import ProgressResult from './ProgressResult';
 import HttpTransport, { ErrorResponse, ITransport, TransportOptions } from './HttpTransport';
 import RequestError from './RequestError';
 import {
+  CacheMode,
   ExtractTimeMembers,
   LoadResponse,
   MetaResponse,
@@ -107,6 +108,10 @@ export type CubeSqlOptions = LoadMethodOptions & {
    * Query timeout in milliseconds
    */
   timeout?: number;
+  /**
+   * Cache mode for query execution
+   */
+  cache?: CacheMode;
 };
 
 export type CubeSqlSchemaColumn = {
@@ -711,6 +716,7 @@ class CubeApi {
       () => {
         const request = this.request('cubesql', {
           query: sqlQuery,
+          cache: options?.cache,
           method: 'POST',
           signal: options?.signal,
           fetchTimeout: options?.timeout
@@ -768,7 +774,8 @@ class CubeApi {
       fetchTimeout: options?.timeout,
       baseRequestId: uuidv4(),
       params: {
-        query: sqlQuery
+        query: sqlQuery,
+        cache: options?.cache
       }
     });
 

packages/cubejs-client-core/src/types.ts

@@ -526,3 +526,30 @@ export type ProgressResponse = {
   stage: string;
   timeElapsed: number;
 };
+
+// NOTE: This type must be kept in sync with CacheMode in @cubejs-backend/shared (packages/cubejs-backend-shared/src/shared-types.ts)
+// This duplication is intentional as @cubejs-client/core does not depend on @cubejs-backend/shared
+/**
+ * Cache mode options for query execution.
+ *
+ * - **stale-if-slow** (default): Equivalent to previously used `renewQuery: false`.
+ *   If refresh keys are up-to-date, returns the value from cache.
+ *   If refresh keys are expired, tries to return the value from the database.
+ *   Returns fresh value from the database if the query executed until the first "Continue wait" interval is reached.
+ *   Returns stale value from cache otherwise.
+ *
+ * - **stale-while-revalidate**: AKA "backgroundRefresh".
+ *   If refresh keys are up-to-date, returns the value from cache.
+ *   If refresh keys are expired, returns stale data from cache.
+ *   Updates the cache in background.
+ *
+ * - **must-revalidate**: Equivalent to previously used `renewQuery: true`.
+ *   If refresh keys are up-to-date, returns the value from cache.
+ *   If refresh keys are expired, tries to return the value from the database.
+ *   Returns fresh value from the database even if it takes minutes and many "Continue wait" intervals.
+ *
+ * - **no-cache**: AKA "forceRefresh".
+ *   Skips refresh key checks.
+ *   Returns fresh data from the database, even if it takes minutes and many "Continue wait" intervals.
+ */
+export type CacheMode = 'stale-if-slow' | 'stale-while-revalidate' | 'must-revalidate' | 'no-cache';