Added @Cacheable() decorator

Author: Denis Khrunov

projects/ngx-http-decorators/README.md

@@ -11,7 +11,8 @@ A library to simplify working with Http requests by describing these requests in
   - [Request with Body](#request-with-body)
   - [Request with Query Params](#request-with-query-params)
   - [Request with Headers](#request-with-headers)
-  - [Reqeust with HttpContext](#request-with-httpcontext)
+  - [Reqeust with HttpContext](#reqeust-with-httpcontext)
+  - [Cacheable request](#cacheable-request)
 - [Decorators](#decorators)
   - [@HttpController()](#httpcontroller)
   - [@Get()](#get)
@@ -25,6 +26,7 @@ A library to simplify working with Http requests by describing these requests in
   - [@Body()](#body)
   - [@Header()](#header)
   - [@Context()](#context)
+  - [@Cacheable()](#cacheable)
 
 ## Settings
 
@@ -302,6 +304,27 @@ export class PostService {
 }
 ```
 
+### Cacheable request
+
+To cache the result of a query, we can use the `@Cacheable()` decorator.
+The `@Cacheable()` decorator has several options, [more on the @Cacheable() decorator](#cacheable),
+but in most cases a decorator with no options is sufficient.
+
+```typescript
+@Injectable({
+  providedIn: 'root',
+})
+@HttpController('/api/posts')
+export class PostService {
+
+  @Cacheable()
+  @Get()
+  public getAll(): Observable<Post[]> {
+    return request(this.getAll);
+  }
+}
+```
+
 ## Decorators
 
 Decorators documentation.
@@ -561,3 +584,100 @@ export class PostService {
   }
 }
 ```
+
+### @Cacheable()
+
+Method decorator. Caching the result of the request, the cached request does not make a repeated http call.
+
+This decorator has optional options:
+- __`key`__ - The key under which the cached value will be stored, by default use this `'{{className}}_{{methodName}}_{{args}}'`. Can be just a string or a dynamic function that returns a key.
+- __`write`__ - A function that describes how to write http response data to the cache.
+- __`read`__ - A function that describes how to read cached data (if it exists) from the cache.
+- __`cache`__ - specifies a different cache store for the decorated method, accepts `InjectionToken<ICache>`, before using another cache store, you must provide it to the `NgxHttpDecoratorsModule`.
+
+```typescript
+@Injectable({
+  providedIn: 'root',
+})
+@HttpController('/api/posts')
+export class PostService {
+
+  @Cacheable({
+    key: 'GET_ALL_POSTS',
+    write: ({ incoming, existing}) => ({ ...existing, ...incoming })
+    read: ({ args, existing }) => {
+      if (!existing) {
+        // Has no cached values
+        return;
+      }
+
+      // There may be some logic here to retrieve data from the cache
+
+      return existing;
+    }
+  })
+  @Get()
+  public getAll(): Observable<Post[]> {
+    return request(this.getAll);
+  }
+}
+```
+
+You can also create your own cache store by creating a service and implementing the `ICache` interface.
+
+Cache service:
+```typescript
+const MY_HTT_CACHE_TOKEN = new InjectionToken<ICache>(
+  'MY_HTT_CACHE_TOKEN',
+  {
+    providedIn: 'root',
+    factory: () => new MyHttpCache()
+  }
+);
+
+@Injectable()
+export class MyHttpCache implements ICache {
+  private readonly cache = new Map<string, unknown>();
+
+  public set<T>(key: string, value: T): void {
+    this.cache.set(key, value);
+  }
+
+  public get<T>(key: string): T | undefined {
+    return this.cache.get(key) as T;
+  }
+
+  public delete(key: string | string[]): void {
+    if (Array.isArray(key)) {
+      key.forEach((k) => this.cache.delete(k));
+    } else {
+      this.cache.delete(key);
+    }
+  }
+
+  public clear(): void {
+    this.cache.clear();
+  }
+}
+```
+
+Used in @Cacheable() decaorator:
+
+```typescript
+@Injectable({
+  providedIn: 'root',
+})
+@HttpController('/api/posts')
+export class PostService {
+
+  @Cacheable({
+    key: 'GET_ALL_POSTS',
+    cache: MY_HTT_CACHE_TOKEN
+  })
+  @Get()
+  public getAll(): Observable<Post[]> {
+    return request(this.getAll);
+  }
+}
+```
+

projects/ngx-http-decorators/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-http-decorators",
-  "version": "15.0.0",
+  "version": "15.1.0",
   "license": "MIT",
 	"repository": {
 		"type": "GitHub",

projects/ngx-http-decorators/src/lib/cache/abstractions/cache.interface.ts

@@ -0,0 +1,21 @@
+export interface ICache {
+  /**
+   * Save value by key in the cache.
+   */
+  set<T>(key: string, value: T): void;
+
+  /**
+   * Get cached value by key.
+   */
+  get<T>(key: string): T | undefined;
+
+  /**
+   * Delete cached value by key.
+   */
+  delete(key: string | string[]): void;
+
+  /**
+   * Clear all values in the cache.
+   */
+  clear(): void;
+}

projects/ngx-http-decorators/src/lib/cache/abstractions/index.ts

@@ -0,0 +1 @@
+export * from './cache.interface';

projects/ngx-http-decorators/src/lib/cache/constants/default-cache.token.ts

@@ -0,0 +1,12 @@
+import { inject, InjectionToken } from '@angular/core';
+import { NgxHttpDecoratorsModule } from '../../ngx-http-decorators.module';
+import { ICache } from '../abstractions';
+import { NgxHttpInMemoryCache } from '../in-memory-cache.service';
+
+export const DEFAULT_CACHE = new InjectionToken<ICache>(
+  'Nhd/DEFAULT_CACHE',
+  {
+    providedIn: NgxHttpDecoratorsModule,
+    factory: () => inject(NgxHttpInMemoryCache)
+  }
+);

projects/ngx-http-decorators/src/lib/cache/constants/index.ts

@@ -0,0 +1 @@
+export * from './default-cache.token';

projects/ngx-http-decorators/src/lib/cache/decorators/cacheable/cacheable.decorator.ts

@@ -0,0 +1,163 @@
+/* eslint-disable prefer-arrow/prefer-arrow-functions */
+/* eslint-disable jsdoc/require-jsdoc */
+/* eslint-disable require-jsdoc */
+import { inject } from '@angular/core';
+import { Observable, of, shareReplay, tap } from 'rxjs';
+import { ICache } from '../../abstractions';
+import { DEFAULT_CACHE } from '../../constants';
+import { CacheableOptions } from './types/cacheable-options.type';
+
+const generateCacheKey = (
+  target: object,
+  methodName: string | symbol,
+  args: unknown[]
+): string => {
+  const cacheKeyPrefix = `${target.constructor.name}_${methodName.toString()}`;
+  const key = `${cacheKeyPrefix}_${JSON.stringify(args)}`;
+
+  return key;
+};
+
+function resolveCacheStorage<TIncoming, TExisting = TIncoming>(
+  options?: Pick<CacheableOptions<TIncoming, TExisting>, 'cache'>
+): ICache {
+  if (options?.cache) {
+    return inject(options.cache);
+  }
+
+  return inject(DEFAULT_CACHE);
+}
+
+const resolveCacheKey = <TIncoming, TExisting = TIncoming>(
+  target: object,
+  methodName: string | symbol,
+  args: unknown[],
+  options?: Pick<CacheableOptions<TIncoming, TExisting>, 'key'>
+): string => {
+  if (options?.key) {
+    if (typeof options.key === 'function') {
+      return options.key({ args });
+    }
+
+    return options?.key;
+  }
+
+  return generateCacheKey(target, methodName, args);
+};
+
+const readCachedValue = <TIncoming, TExisting = TIncoming>(
+  args: unknown[],
+  cache: ICache,
+  cacheKey: string,
+  options?: Pick<CacheableOptions<TIncoming, TExisting>, 'read'>
+): TIncoming | undefined => {
+  if (options?.read) {
+    const existing = cache.get<TExisting>(cacheKey);
+    return options.read({ args, existing });
+  }
+
+  return cache.get<TIncoming>(cacheKey);
+};
+
+const writeCacheValue = <TIncoming, TExisting = TIncoming>(
+  args: unknown[],
+  incoming: TIncoming,
+  cache: ICache,
+  cacheKey: string,
+  options?: Pick<CacheableOptions<TIncoming, TExisting>, 'write'>
+): void => {
+  if (options?.write) {
+    const existing = cache.get<TExisting>(cacheKey);
+    const value = options.write({ args, incoming, existing });
+    cache.set<TExisting>(cacheKey, value);
+  } else {
+    cache.set<TIncoming>(cacheKey, incoming);
+  }
+};
+
+/**
+ * Caches the result of an http request. On subsequent calls to the decorated method,
+ * data will be returned from the cache until the cache is invalidated (reset).
+ *----------------
+ *
+ * __IMPORTANT:__
+ *
+ * 1. Use a subscription to a cached request with a `take(1)` operator, or with an unsubscribe, because the original `Observable`
+ * returned from `HttpClient` turns from `Cold Observable` to `Hot Observable`,
+ * if `Cold Observable` creates a new thread (new request) for each subscription, then `Hot Observable` fumbles this subscription.
+ *
+ * 2. The method being decorated should not have side effects, because after caching the body of this function will not be re-executed,
+ * because the value of the request is immediately taken from their cache.
+ *
+ * @example
+ * ```typescript
+ * ...
+ * \@Cacheable<Response, UsersService>({ key: 'CustomKey', })
+ * public request(): Observable<Response> { }
+ * ...
+ * ```
+ * ----------------
+ * @param options Опцци кеширования.
+ */
+// eslint-disable-next-line prefer-arrow/prefer-arrow-functions, require-jsdoc, max-lines-per-function
+export function Cacheable<TIncoming, TExisting = TIncoming>(
+  options?: CacheableOptions<TIncoming, TExisting>
+): MethodDecorator {
+  // eslint-disable-next-line max-lines-per-function
+  return (
+    target: object,
+    methodName: string | symbol,
+    descriptor: TypedPropertyDescriptor<any>
+  ) => {
+    if (!(descriptor?.value instanceof Function)) {
+      throw new TypeError(
+        '"Cacheable" decorator can only be applied to a class method that returns an Observable'
+      );
+    }
+
+    const originalMethod = descriptor.value as (
+      ...args: unknown[]
+    ) => Observable<TIncoming>;
+
+    descriptor.value = function (...args: unknown[]): Observable<TIncoming> {
+      const cache = resolveCacheStorage.bind(target)<TIncoming, TExisting>(
+        options
+      );
+      const cacheKey = resolveCacheKey<TIncoming, TExisting>(
+        target,
+        methodName,
+        args,
+        options
+      );
+      const cachedValue = readCachedValue<TIncoming, TExisting>(
+        args,
+        cache,
+        cacheKey,
+        options
+      );
+
+      if (cachedValue) {
+        return of(cachedValue);
+      }
+
+      const originalRequest = originalMethod.apply(this, args);
+
+      if (!(originalRequest instanceof Observable)) {
+        throw new TypeError(
+          `"Cacheable": Decorated method "${methodName.toString()}" in class "${
+            target.constructor.name
+          }" must return an Observable value.`
+        );
+      }
+
+      return originalRequest.pipe(
+        tap((incoming) =>
+          writeCacheValue(args, incoming, cache, cacheKey, options)
+        ),
+        shareReplay(1)
+      );
+    };
+
+    return descriptor;
+  };
+}

projects/ngx-http-decorators/src/lib/cache/decorators/cacheable/index.ts

@@ -0,0 +1,6 @@
+export * from './cacheable.decorator';
+export * from './types/cache-key.type';
+export * from './types/cache-read.type';
+export * from './types/cache-write.type';
+export * from './types/cacheable-options.type';
+

projects/ngx-http-decorators/src/lib/cache/decorators/cacheable/types/cache-key.type.ts

@@ -0,0 +1,5 @@
+export type CacheKeyFunctionOptions = {
+  args: unknown[];
+};
+
+export type CacheKeyFunction = (options: CacheKeyFunctionOptions) => string;

projects/ngx-http-decorators/src/lib/cache/decorators/cacheable/types/cache-read.type.ts

@@ -0,0 +1,8 @@
+export type CacheReadFunctionOptions<TExisting> = {
+  args: unknown[];
+  existing: TExisting | undefined;
+};
+
+export type CacheRead<TIncoming, TExisting = TIncoming> = (
+  options: CacheReadFunctionOptions<TExisting>
+) => TIncoming | undefined;