feat(trakt-client): adds cache support to endpoints

dvcol · dvcol · commit b369463d575b · 2024-02-17T20:54:18.000+01:00
diff --git a/src/models/trakt/trakt-client.model.ts b/src/models/trakt/trakt-client.model.ts
@@ -1,4 +1,5 @@
 import type { TraktApiFilters } from '~/services/trakt-client/api/trakt-api.filters';
+import type { CacheStore } from '~/utils/cache.utils';
 import type { CancellablePromise } from '~/utils/fetch.utils';
 import type { HttpMethods } from '~/utils/http.utils';
 
@@ -32,6 +33,14 @@ export type TraktClientSettings = {
   useragent: string;
 };
 
+/**
+ * Trakt.tv API client options.
+ */
+export type TraktClientOptions = TraktClientSettings & {
+  /** Optional cache store to manage cache read/write */
+  cacheStore?: CacheStore<TraktApiResponse>;
+};
+
 /**
  * By default, all methods will return minimal info for movies, shows, episodes, people, and users.
  * Minimal info is typically all you need to match locally cached items and includes the title, year, and ids.
@@ -116,6 +125,7 @@ export class TraktClientEndpoint<P extends TraktApiParams = Record<string, never
   body?: Record<string, boolean>;
   init?: TraktApiInit;
   validate?: (param: P) => boolean;
+  cached: Omit<this, 'cached'> & ((param?: P, init?: TraktApiInit) => Promise<TraktApiResponse>);
 
   constructor(template: TraktApiTemplate<P>) {
     this.method = template.method;
@@ -125,6 +135,7 @@ export class TraktClientEndpoint<P extends TraktApiParams = Record<string, never
     this.body = template.body;
 
     this.validate = template.validate;
+    this.cached = this;
   }
 }
 
diff --git a/src/services/trakt-client/clients/base-trakt-client.test.ts b/src/services/trakt-client/clients/base-trakt-client.test.ts
@@ -8,7 +8,8 @@ import { traktClientSettings } from '../trakt-client.service';
 import { BaseTraktClient, parseBody, parseResponse } from './base-trakt-client';
 
 import type { TraktClientAuthentication } from '../../../models/trakt/trakt-authentication.model';
-import type { TraktApiInit, TraktApiParams, TraktApiQuery, TraktApiTemplate } from '../../../models/trakt/trakt-client.model';
+import type { TraktApiInit, TraktApiParams, TraktApiQuery, TraktApiResponse, TraktApiTemplate } from '../../../models/trakt/trakt-client.model';
+import type { CacheStore } from '../../../utils/cache.utils';
 import type { CancellablePromise } from '../../../utils/fetch.utils';
 import type { Updater } from '../../../utils/observable.utils';
 
@@ -31,7 +32,13 @@ class TestableTraktClient extends BaseTraktClient {
 }
 
 describe('base-trakt-client.ts', () => {
-  const client = new TestableTraktClient(traktClientSettings);
+  const cacheStore: CacheStore<TraktApiResponse> = {
+    get: vi.fn(),
+    set: vi.fn(),
+    clear: vi.fn(),
+    delete: vi.fn(),
+  };
+  const client = new TestableTraktClient({ ...traktClientSettings, cacheStore });
   const auth: TraktClientAuthentication = {
     refresh_token: 'refresh_token',
     access_token: 'access_token',
@@ -63,6 +70,24 @@ describe('base-trakt-client.ts', () => {
     expect(client.auth).toBeDefined();
   });
 
+  describe('cache', () => {
+    it('should delete a cached entry', async () => {
+      expect.assertions(1);
+
+      await client.clearCache('key');
+
+      expect(cacheStore.delete).toHaveBeenCalledWith('key');
+    });
+
+    it('should delete a cached entry', async () => {
+      expect.assertions(1);
+
+      await client.clearCache();
+
+      expect(cacheStore.clear).toHaveBeenCalledWith();
+    });
+  });
+
   describe('observers', () => {
     const authObserver = vi.fn();
     const callObserver = vi.fn();
diff --git a/src/services/trakt-client/clients/base-trakt-client.ts b/src/services/trakt-client/clients/base-trakt-client.ts
@@ -6,9 +6,11 @@ import type {
   TraktApiRequest,
   TraktApiResponse,
   TraktApiTemplate,
+  TraktClientOptions,
   TraktClientSettings,
 } from '~/models/trakt/trakt-client.model';
 
+import type { CacheStore } from '~/utils/cache.utils';
 import type { Primitive } from '~/utils/typescript.utils';
 
 import { TraktApiHeaders } from '~/models/trakt/trakt-client.model';
@@ -132,10 +134,22 @@ export const parseResponse = <T>(response: Response): TraktApiResponse<T> => {
  * @class BaseTraktClient
  */
 export class BaseTraktClient {
+  protected _cache: CacheStore<TraktApiResponse>;
   protected _settings: TraktClientSettings;
   protected _authentication: ObservableState<TraktClientAuthentication>;
   protected _callListeners: Observable<TraktApiQuery<unknown>>;
 
+  /**
+   * Clears the cache entry for the specified key.
+   * If no key is provided, clears the entire cache.
+   *
+   * @param key - The cache key.
+   */
+  clearCache(key?: string) {
+    if (key) return this._cache?.delete(key);
+    return this._cache?.clear();
+  }
+
   /**
    * Gets the authentication information.
    *
@@ -191,10 +205,11 @@ export class BaseTraktClient {
     };
   }
 
-  constructor(settings: TraktClientSettings, authentication = {}) {
+  constructor({ cacheStore, ...settings }: TraktClientOptions, authentication = {}) {
     this._settings = settings;
     this._authentication = new ObservableState(authentication);
     this._callListeners = new Observable();
+    this._cache = cacheStore ?? new Map();
   }
 
   /**
diff --git a/src/services/trakt-client/clients/trakt-client.test.ts b/src/services/trakt-client/clients/trakt-client.test.ts
@@ -9,6 +9,8 @@ import { traktClientSettings } from '../trakt-client.service';
 import { TraktClient } from './trakt-client';
 
 import type { TraktAuthentication, TraktDeviceAuthentication } from '../../../models/trakt/trakt-authentication.model';
+import type { TraktApiResponse } from '../../../models/trakt/trakt-client.model';
+import type { CacheStore } from '../../../utils/cache.utils';
 
 import type { RecursiveRecord } from '../../../utils/typescript.utils';
 
@@ -28,6 +30,7 @@ describe('trakt-client.ts', () => {
 
   afterEach(async () => {
     await traktClient.importAuthentication({});
+    await traktClient.clearCache();
 
     vi.clearAllMocks();
   });
@@ -75,6 +78,84 @@ describe('trakt-client.ts', () => {
       expect(fetch).toHaveBeenCalledWith(new URL('/certifications/shows', traktClientSettings.endpoint).toString(), payload);
     });
 
+    describe('cache', () => {
+      it('should not cache calls', async () => {
+        expect.assertions(2);
+
+        await traktClient.certifications({ type: 'movies' });
+        await traktClient.certifications({ type: 'movies' });
+        await traktClient.certifications({ type: 'movies' });
+
+        expect(fetch).toHaveBeenCalledTimes(3);
+        expect(fetch).toHaveBeenCalledWith(new URL('/certifications/movies', traktClientSettings.endpoint).toString(), payload);
+      });
+
+      it('should cache subsequent calls', async () => {
+        expect.assertions(2);
+
+        await traktClient.certifications.cached({ type: 'movies' });
+        await traktClient.certifications.cached({ type: 'movies' });
+        await traktClient.certifications.cached({ type: 'movies' });
+
+        expect(fetch).toHaveBeenCalledTimes(1);
+        expect(fetch).toHaveBeenCalledWith(new URL('/certifications/movies', traktClientSettings.endpoint).toString(), payload);
+      });
+
+      it('should ignore cache if cache cleared', async () => {
+        expect.assertions(2);
+
+        await traktClient.certifications.cached({ type: 'movies' });
+        await traktClient.certifications.cached({ type: 'movies' });
+        await traktClient.clearCache();
+        await traktClient.certifications.cached({ type: 'movies' });
+
+        expect(fetch).toHaveBeenCalledTimes(2);
+        expect(fetch).toHaveBeenCalledWith(new URL('/certifications/movies', traktClientSettings.endpoint).toString(), payload);
+      });
+
+      it('should clear cache after error', async () => {
+        expect.assertions(3);
+
+        const error = new Error('Error');
+        fetch.mockRejectedValueOnce(error);
+
+        let err: unknown;
+        try {
+          await traktClient.certifications.cached({ type: 'movies' });
+        } catch (e) {
+          err = e;
+        } finally {
+          expect(err).toBe(error);
+        }
+        await traktClient.certifications.cached({ type: 'movies' });
+        await traktClient.certifications.cached({ type: 'movies' });
+
+        expect(fetch).toHaveBeenCalledTimes(2);
+        expect(fetch).toHaveBeenCalledWith(new URL('/certifications/movies', traktClientSettings.endpoint).toString(), payload);
+      });
+
+      it('should ignore cache if cache expired', async () => {
+        expect.assertions(2);
+
+        const cacheStore: CacheStore<TraktApiResponse> = new Map();
+        cacheStore.retention = 100;
+        const _traktClient = new TraktClient({ ...traktClientSettings, cacheStore });
+
+        await _traktClient.certifications.cached({ type: 'movies' });
+        await _traktClient.certifications.cached({ type: 'movies' });
+
+        // Wait for cache to expire
+        await new Promise(resolve => {
+          setTimeout(resolve, 200);
+        });
+
+        await _traktClient.certifications.cached({ type: 'movies' });
+
+        expect(fetch).toHaveBeenCalledTimes(2);
+        expect(fetch).toHaveBeenCalledWith(new URL('/certifications/movies', traktClientSettings.endpoint).toString(), payload);
+      });
+    });
+
     const deviceAuthentication: TraktDeviceAuthentication = {
       device_code: 'device_code',
       user_code: 'user_code',
diff --git a/src/services/trakt-client/clients/trakt-client.ts b/src/services/trakt-client/clients/trakt-client.ts
@@ -18,6 +18,7 @@ import type {
   TraktApiParams,
   TraktApiResponse,
   TraktClientEndpointCall,
+  TraktClientOptions,
   TraktClientSettings,
 } from '~/models/trakt/trakt-client.model';
 
@@ -90,11 +91,40 @@ class TraktApi extends BaseTraktClient implements ITraktEndpoints {
     Object.entries(client).forEach(([endpoint, template]) => {
       if (isTraktApiTemplate(template) && isTraktApiTemplate(client[endpoint])) {
         const fn: TraktClientEndpointCall = (param, init) => this._call(template, param, init);
+
+        const cachedFn: TraktClientEndpointCall = async (param, init) => {
+          const key = JSON.stringify({ param, init });
+          const cached = await this._cache.get(key);
+          if (cached) {
+            if (!this._cache.retention) return cached.value;
+            const expires = cached.cachedAt + this._cache.retention;
+            if (expires > Date.now()) return cached.value;
+          }
+          try {
+            const result = await fn(param, init);
+            await this._cache.set(key, {
+              cachedAt: Date.now(),
+              value: result,
+            });
+            return result;
+          } catch (error) {
+            this._cache.delete(key);
+            throw error;
+          }
+        };
+
         Object.entries(client[endpoint]).forEach(([key, value]) => {
-          Object.defineProperty(fn, key, { value });
+          if (key === 'cached') {
+            Object.defineProperty(fn, 'cached', { value: cachedFn });
+          } else {
+            Object.defineProperty(fn, key, { value });
+            Object.defineProperty(cachedFn, key, { value });
+          }
         });
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- generic typing
-        client[endpoint] = fn as any;
+
+        Object.defineProperty(fn, 'cached', { value: cachedFn });
+
+        client[endpoint] = fn as (typeof client)[typeof endpoint];
       } else {
         client[endpoint] = this.bindToEndpoint(client[endpoint] as ITraktApi);
       }
@@ -118,21 +148,8 @@ class TraktApi extends BaseTraktClient implements ITraktEndpoints {
 export class TraktClient extends TraktApi {
   private polling: ReturnType<typeof setTimeout> | undefined;
 
-  constructor({
-    client_id,
-    client_secret,
-    redirect_uri,
-
-    useragent,
-    endpoint,
-  }: TraktClientSettings) {
-    super({
-      client_id,
-      client_secret,
-      redirect_uri,
-      useragent,
-      endpoint,
-    });
+  constructor(options: TraktClientOptions) {
+    super(options);
   }
 
   /**
diff --git a/src/utils/cache.utils.ts b/src/utils/cache.utils.ts
@@ -0,0 +1,14 @@
+export type CacheStoreEntity<T> = {
+  value: T;
+  cachedAt: number;
+  accessedAt?: number;
+};
+
+export type CacheStore<T> = {
+  get(key: string): CacheStoreEntity<T> | Promise<CacheStoreEntity<T>> | undefined;
+  set(key: string, value: CacheStoreEntity<T>): CacheStore<T> | Promise<CacheStore<T>>;
+  delete(key: string): boolean | Promise<boolean>;
+  clear(): void;
+  /** the duration in milliseconds after which the cache will be cleared */
+  retention?: number;
+};
