@travetto/cache 2.1.5 → 2.2.0

package/README.md

@@ -19,13 +19,13 @@ npm install @travetto/model-{provider}
 
 Currently, the following are packages that provide [Expiry](https://github.com/travetto/travetto/tree/main/module/model/src/service/expiry.ts#L11):
    
-   *  [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") - [FileModelService](https://github.com/travetto/travetto/tree/main/module/model/src/provider/file.ts#L47), [MemoryModelService](https://github.com/travetto/travetto/tree/main/module/model/src/provider/memory.ts#L50)
-   *  [DynamoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-dynamodb#readme "DynamoDB backing for the travetto model module.") - [DynamoDBModelService](https://github.com/travetto/travetto/tree/main/module/model-dynamodb/src/service.ts#L57)
-   *  [Elasticsearch Model Source](https://github.com/travetto/travetto/tree/main/module/model-elasticsearch#readme "Elasticsearch backing for the travetto model module, with real-time modeling support for Elasticsearch mappings.") - [ElasticsearchModelService](https://github.com/travetto/travetto/tree/main/module/model-elasticsearch/src/service.ts#L40)
-   *  [MongoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-mongo#readme "Mongo backing for the travetto model module.") - [MongoModelService](https://github.com/travetto/travetto/tree/main/module/model-mongo/src/service.ts#L44)
+   *  [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") - [FileModelService](https://github.com/travetto/travetto/tree/main/module/model/src/provider/file.ts#L49), [MemoryModelService](https://github.com/travetto/travetto/tree/main/module/model/src/provider/memory.ts#L54)
+   *  [DynamoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-dynamodb#readme "DynamoDB backing for the travetto model module.") - [DynamoDBModelService](https://github.com/travetto/travetto/tree/main/module/model-dynamodb/src/service.ts#L58)
+   *  [Elasticsearch Model Source](https://github.com/travetto/travetto/tree/main/module/model-elasticsearch#readme "Elasticsearch backing for the travetto model module, with real-time modeling support for Elasticsearch mappings.") - [ElasticsearchModelService](https://github.com/travetto/travetto/tree/main/module/model-elasticsearch/src/service.ts#L42)
+   *  [MongoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-mongo#readme "Mongo backing for the travetto model module.") - [MongoModelService](https://github.com/travetto/travetto/tree/main/module/model-mongo/src/service.ts#L49)
    *  [Redis Model Support](https://github.com/travetto/travetto/tree/main/module/model-redis#readme "Redis backing for the travetto model module.") - [RedisModelService](https://github.com/travetto/travetto/tree/main/module/model-redis/src/service.ts#L26)
-   *  [S3 Model Support](https://github.com/travetto/travetto/tree/main/module/model-s3#readme "S3 backing for the travetto model module.") - [S3ModelService](https://github.com/travetto/travetto/tree/main/module/model-s3/src/service.ts#L32)
-   *  [SQL Model Service](https://github.com/travetto/travetto/tree/main/module/model-sql#readme "SQL backing for the travetto model module, with real-time modeling support for SQL schemas.") - [SQLModelService](https://github.com/travetto/travetto/tree/main/module/model-sql/src/service.ts#L36)
+   *  [S3 Model Support](https://github.com/travetto/travetto/tree/main/module/model-s3#readme "S3 backing for the travetto model module.") - [S3ModelService](https://github.com/travetto/travetto/tree/main/module/model-s3/src/service.ts#L34)
+   *  [SQL Model Service](https://github.com/travetto/travetto/tree/main/module/model-sql#readme "SQL backing for the travetto model module, with real-time modeling support for SQL schemas.") - [SQLModelService](https://github.com/travetto/travetto/tree/main/module/model-sql/src/service.ts#L38)
 
 ## Decorators
 The caching framework provides method decorators that enables simple use cases.  One of the requirements to use the caching decorators is that the method arguments, and return values need to be serializable into [JSON](https://www.json.org).  Any other data types are not currently supported and would require either manual usage of the caching services directly, or specification of serialization/deserialization routines in the cache config.
@@ -39,10 +39,10 @@ Additionally, to use the decorators you will need to have a [CacheService](https
 import { MemoryModelService } from '@travetto/model';
 import { Cache, CacheService } from '@travetto/cache';
 
-async function request(url: string) {
-  let value;
+async function request(url: string): Promise<string> {
+  let value: string;
   // ...fetch content
-  return value;
+  return value!;
 }
 
 export class Worker {
@@ -52,7 +52,7 @@ export class Worker {
   );
 
   @Cache('myCache', '1s')
-  async calculateExpensiveResult(expression: string) {
+  async calculateExpensiveResult(expression: string): Promise<string> {
     const value = await request(`https://google.com?q=${expression}`);
     return value;
   }
@@ -74,9 +74,9 @@ The [@Cache](https://github.com/travetto/travetto/tree/main/module/cache/src/dec
       *  `serialize` the function to execute before storing a cacheable value.  This allows for any custom data modification needed to persist as a string properly.
       *  `reinstate` the function to execute on return of a cached value.  This allows for any necessary operations to conform to expected output (e.g. re-establishing class instances, etc.).  This method should not be used often, as the return values of the methods should naturally serialize to/from `JSON` and the values should be usable either way.
 
-### [@EvictCache](https://github.com/travetto/travetto/tree/main/module/cache/src/decorator.ts#L37)
+### [@EvictCache](https://github.com/travetto/travetto/tree/main/module/cache/src/decorator.ts#L41)
 
-Additionally, there is support for planned eviction via the [@EvictCache](https://github.com/travetto/travetto/tree/main/module/cache/src/decorator.ts#L37) decorator.  On successful execution of a method with this decorator, the matching keySpace/key value will be evicted from the cache.  This requires coordination between multiple methods, to use the same `keySpace` and `key` to compute the expected key.
+Additionally, there is support for planned eviction via the [@EvictCache](https://github.com/travetto/travetto/tree/main/module/cache/src/decorator.ts#L41) decorator.  On successful execution of a method with this decorator, the matching keySpace/key value will be evicted from the cache.  This requires coordination between multiple methods, to use the same `keySpace` and `key` to compute the expected key.
 
 **Code: Using decorators to cache/evict user access**
 ```typescript
@@ -95,17 +95,17 @@ export class UserService {
   };
 
   @Cache('myCache', '5m', { keySpace: 'user.id' })
-  async getUser(id: string) {
+  async getUser(id: string): Promise<User> {
     return this.database.lookupUser(id);
   }
 
   @EvictCache('myCache', { keySpace: 'user.id', params: user => [user.id] })
-  async updateUser(user: User) {
+  async updateUser(user: User): Promise<void> {
     this.database.updateUser(user);
   }
 
   @EvictCache('myCache', { keySpace: 'user.id' })
-  async deleteUser(userId: string) {
+  async deleteUser(userId: string): Promise<void> {
     this.database.deleteUser(userId);
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@travetto/cache",
   "displayName": "Caching",
-  "version": "2.1.5",
+  "version": "2.2.0",
   "description": "Caching functionality with decorators for declarative use.",
   "keywords": [
     "typescript",
@@ -27,9 +27,9 @@
     "directory": "module/cache"
   },
   "dependencies": {
-    "@travetto/transformer": "^2.1.4",
-    "@travetto/di": "^2.1.5",
-    "@travetto/model": "^2.1.5"
+    "@travetto/transformer": "^2.2.0",
+    "@travetto/di": "^2.2.0",
+    "@travetto/model": "^2.2.0"
   },
   "docDependencies": {
     "@travetto/model-dynamodb": true,

package/src/decorator.ts

@@ -13,7 +13,9 @@ import { CacheAware, CacheConfigⲐ, EvictConfigⲐ } from './internal/types';
  */
 export function Cache<F extends string, U extends Record<F, CacheService>>(field: F, maxAge: number | TimeSpan, config?: Omit<CacheConfig, 'maxAge'>): MethodDecorator;
 export function Cache<F extends string, U extends Record<F, CacheService>>(field: F, cfg?: CacheConfig): MethodDecorator;
-export function Cache<F extends string, U extends Record<F, CacheService>>(field: F, cfg?: number | TimeSpan | CacheConfig, config: Exclude<CacheConfig, 'maxAge'> = {}) {
+export function Cache<F extends string, U extends Record<F, CacheService>>(
+  field: F, cfg?: number | TimeSpan | CacheConfig, config: Exclude<CacheConfig, 'maxAge'> = {}
+): MethodDecorator {
   if (cfg !== undefined) {
     if (typeof cfg === 'string' || typeof cfg === 'number') {
       config.maxAge = Util.timeToMs(cfg);
@@ -21,10 +23,12 @@ export function Cache<F extends string, U extends Record<F, CacheService>>(field
       config = cfg;
     }
   }
-  return function <R extends Promise<unknown>>(target: U & CacheAware, propertyKey: string, descriptor: MethodDescriptor<R>) {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  const dec = function <R extends Promise<unknown>>(target: U & CacheAware, propertyKey: string, descriptor: MethodDescriptor<R>): void {
     config.keySpace ??= `${target.constructor.name}.${propertyKey}`;
-    (target[CacheConfigⲐ] ??= {})[propertyKey] = config as CacheConfig;
-  };
+    (target[CacheConfigⲐ] ??= {})[propertyKey] = config;
+  } as MethodDecorator;
+  return dec;
 }
 
 /**
@@ -35,7 +39,7 @@ export function Cache<F extends string, U extends Record<F, CacheService>>(field
  * @augments `@trv:cache/Evict`
  */
 export function EvictCache<F extends string, U extends Record<F, CacheService>>(field: F, config: CoreCacheConfig = {}) {
-  return function <R extends Promise<unknown>>(target: U & CacheAware, propertyKey: string, descriptor: MethodDescriptor<R>) {
+  return function <R extends Promise<unknown>>(target: U & CacheAware, propertyKey: string, descriptor: MethodDescriptor<R>): void {
     config.keySpace ??= `${target.constructor.name}.${propertyKey}`;
     (target[EvictConfigⲐ] ??= {})[propertyKey] = config;
   };

package/src/service.ts

@@ -34,18 +34,18 @@ export class CacheService {
     this.#modelService = modelService;
   }
 
-  async postConstruct() {
+  async postConstruct(): Promise<void> {
     if (isStorageSupported(this.#modelService) && EnvUtil.isDynamic()) {
       await this.#modelService.createModel?.(CacheRecord);
     }
   }
 
   /**
-   * Get an item thowing an error if missing or expired.  Allows for extending expiry based on access
+   * Get an item throwing an error if missing or expired.  Allows for extending expiry based on access
    * @param id Record identifier
-   * @param extendOnAccess should the expiry be extended on acces
+   * @param extendOnAccess should the expiry be extended on access
    */
-  async get(id: string, extendOnAccess = true) {
+  async get(id: string, extendOnAccess = true): Promise<unknown> {
     const { expiresAt, issuedAt } = await this.#modelService.get(CacheRecord, id);
 
     const delta = expiresAt.getTime() - Date.now();
@@ -77,7 +77,7 @@ export class CacheService {
    * @param maxAge Max age in ms
    * @returns
    */
-  async set(id: string, entry: unknown, maxAge?: number) {
+  async set(id: string, entry: unknown, maxAge?: number): Promise<unknown> {
     const entryText = CacheUtil.toSafeJSON(entry);
 
     const store = await this.#modelService.upsert(CacheRecord,
@@ -96,14 +96,14 @@ export class CacheService {
    * Remove an item by id
    * @param id
    */
-  async delete(id: string) {
+  async delete(id: string): Promise<void> {
     await this.#modelService.delete(CacheRecord, id);
   }
 
   /**
    * Purge the cache store of all data, if supported
    */
-  async purge() {
+  async purge(): Promise<void> {
     if (isStorageSupported(this.#modelService) && this.#modelService.truncateModel) {
       await this.#modelService.truncateModel(CacheRecord);
     } else {
@@ -114,9 +114,9 @@ export class CacheService {
   /**
    * Get an item optionally, returning undefined if missing.  Allows for extending expiry based on access
    * @param id Record identifier
-   * @param extendOnAccess should the expiry be extended on acces
+   * @param extendOnAccess should the expiry be extended on access
    */
-  async getOptional(id: string, extendOnAccess = true) {
+  async getOptional(id: string, extendOnAccess = true): Promise<unknown | undefined> {
     let res: unknown;
 
     try {
@@ -137,7 +137,7 @@ export class CacheService {
    * @param fn Function to execute
    * @param params input parameters
    */
-  async cache(target: CacheAware, method: string, fn: Function, params: unknown[]) {
+  async cache(target: CacheAware, method: string, fn: Function, params: unknown[]): Promise<unknown | undefined> {
     const config = target[CacheConfigⲐ]![method];
 
     const id = CacheUtil.generateKey(config, params);
@@ -164,7 +164,7 @@ export class CacheService {
    * @param fn Function to execute
    * @param params Input params to the function
    */
-  async evict(target: CacheAware, method: string, fn: Function, params: unknown[]) {
+  async evict(target: CacheAware, method: string, fn: Function, params: unknown[]): Promise<unknown> {
     const config = target[EvictConfigⲐ]![method];
     const id = CacheUtil.generateKey(config, params);
     const val = await fn.apply(target, params);

package/src/util.ts

@@ -13,9 +13,9 @@ export class CacheUtil {
    * @param value The value to make safe for storage
    * @param all Should functions and regex be included
    */
-  static toSafeJSON(value: unknown, all = false) {
+  static toSafeJSON(value: unknown, all = false): string {
     const replacer = all ?
-      ((key: string, val: unknown) => (Util.isFunction(val) || val instanceof RegExp) ? (val as RegExp)?.source : val) :
+      ((key: string, val: unknown): unknown => (val && val instanceof RegExp) ? val.source : (Util.isFunction(val) ? val.toString() : val)) :
       undefined;
 
     return Buffer.from(JSON.stringify(value, replacer)).toString('base64');
@@ -25,14 +25,14 @@ export class CacheUtil {
    * Read safe JSON back into an object
    * @param value The value to read as safe JSON
    */
-  static fromSafeJSON(value: string | undefined) {
+  static fromSafeJSON(value: string | undefined): unknown {
     return value ? JSON.parse(Buffer.from(value, 'base64').toString('utf8')) : undefined;
   }
 
   /**
    * Generate key given config, cache source and input params
    */
-  static generateKey(config: CoreCacheConfig, params: unknown[]) {
+  static generateKey(config: CoreCacheConfig, params: unknown[]): string {
     const input = config.params?.(params) ?? params;
     const keyParams = config.key?.(...input) ?? input;
     const key = `${config.keySpace!}_${this.toSafeJSON(keyParams)}`;

package/support/transformer.cache.ts

@@ -13,7 +13,7 @@ export class CacheTransformer {
    * When `@Cache` and `@Evict` are present
    */
   @OnMethod('Cache', 'Evict')
-  static instrumentCache(state: TransformerState, node: ts.MethodDeclaration, dm?: DecoratorMeta) {
+  static instrumentCache(state: TransformerState, node: ts.MethodDeclaration, dm?: DecoratorMeta): ts.MethodDeclaration {
 
     const isCache = !!state.findDecorator(this, node, 'Cache');
     const dec = dm?.dec;
@@ -21,7 +21,7 @@ export class CacheTransformer {
     // If valid function
     if (dec && ts.isCallExpression(dec.expression)) {
       const params = dec.expression.arguments;
-      const id = params[0] as ts.Identifier;
+      const mainExpression = params[0];
 
       const op = isCache ? 'cache' : 'evict';
 
@@ -50,7 +50,7 @@ export class CacheTransformer {
           state.factory.createReturnStatement(
             state.factory.createCallExpression(
               state.factory.createPropertyAccessExpression(
-                state.factory.createElementAccessExpression(state.factory.createThis(), id), op
+                state.factory.createElementAccessExpression(state.factory.createThis(), mainExpression), op
               ),
               undefined,
               [
@@ -60,7 +60,8 @@ export class CacheTransformer {
                 state.factory.createArrayLiteralExpression([
                   state.factory.createSpreadElement(state.createIdentifier('arguments'))
                 ])
-              ] as (readonly ts.Expression[]))
+              ]
+            )
           )
         ])
       );