@travetto/cache 8.0.0-alpha.8 → 8.0.0

package/README.md

@@ -13,7 +13,7 @@ npm install @travetto/cache
 yarn add @travetto/cache
 ```
 
-Provides a foundational structure for integrating caching at the method level.  This allows for easy extension with a variety of providers, and is usable with or without [Dependency Injection](https://github.com/travetto/travetto/tree/main/module/di#readme "Dependency registration/management and injection support.").  The code aims to handle use cases surrounding common/basic usage.
+Provides a foundational structure for integrating caching at the method level. This allows for easy extension with a variety of providers, and is usable with or without [Dependency Injection](https://github.com/travetto/travetto/tree/main/module/di#readme "Dependency registration/management and injection support."). The code aims to handle use cases surrounding common/basic usage.
 
 The cache module requires an [Expiry](https://github.com/travetto/travetto/tree/main/module/model/src/types/expiry.ts#L10) to provide functionality for reading and writing streams. You can use any existing providers to serve as your [Expiry](https://github.com/travetto/travetto/tree/main/module/model/src/types/expiry.ts#L10), or you can roll your own.
 
@@ -38,16 +38,16 @@ Currently, the following are packages that provide [Expiry](https://github.com/t
    *  [File Model Support](https://github.com/travetto/travetto/tree/main/module/model-file#readme "File system backing for the travetto model module.") - @travetto/model-file
 
 ## 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.
+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.
 
-Additionally, to use the decorators you will need to have a [CacheService](https://github.com/travetto/travetto/tree/main/module/cache/src/service.ts#L32) object accessible on the class instance. This can be dependency injected, or manually constructed. The decorators will detect the field at time of method execution, which decouples construction of your class from the cache construction.
+Additionally, to use the decorators you will need to have a [CacheService](https://github.com/travetto/travetto/tree/main/module/cache/src/service.ts#L35) object accessible on the class instance. This can be dependency injected, or manually constructed. The decorators will detect the field at time of method execution, which decouples construction of your class from the cache construction.
 
-[@Cache](https://github.com/travetto/travetto/tree/main/module/cache/src/decorator.ts#L12) is a decorator that will cache all successful results, keyed by a computation based on the method arguments.  Given the desire for supporting remote caches (e.g. [redis](https://redis.io), [memcached](https://memcached.org)), only asynchronous methods are supported.
+[@Cache](https://github.com/travetto/travetto/tree/main/module/cache/src/decorator.ts#L12) is a decorator that will cache all successful results, keyed by a computation based on the method arguments. Given the desire for supporting remote caches (e.g. [redis](https://redis.io), [memcached](https://memcached.org)), only asynchronous methods are supported.
 
 **Code: Using decorators to cache expensive async call**
 ```typescript
-import { MemoryModelService } from '@travetto/model-memory';
 import { Cache, CacheService } from '@travetto/cache';
+import { MemoryModelService } from '@travetto/model-memory';
 
 async function request(url: string): Promise<string> {
   let value: string;
@@ -56,10 +56,7 @@ async function request(url: string): Promise<string> {
 }
 
 export class Worker {
-
-  myCache = new CacheService(
-    new MemoryModelService({ namespace: '' })
-  );
+  myCache = new CacheService(new MemoryModelService({ namespace: '' }));
 
   @Cache('myCache', '1s')
   async calculateExpensiveResult(expression: string): Promise<string> {
@@ -74,26 +71,25 @@ The [@Cache](https://github.com/travetto/travetto/tree/main/module/cache/src/dec
    *  `name` the field name of the current class which points to the desired cache source.
    *  `config` the additional/optional config options, on a per invocation basis
 
-      *  `keySpace` the key space within the cache.  Defaults to class name plus method name.
-      *  `key` the function  will use the inputs to determine the cache key, defaults to all params `JSON.stringify`ied
-      *  `params` the function used to determine the inputs for computing the cache key.  This is an easier place to start to define what parameters are important in ,caching. This defaults to all inputs.
-      *  `maxAge` the number of milliseconds will hold the value before considering the cache entry to be invalid.  By default values will live infinitely.
-      *  `extendOnAccess` determines if the cache timeout should be extended on access.  This only applies to cache values that have specified a `maxAge`.
-      *  `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.
+      *  `keySpace` the key space within the cache. Defaults to class name plus method name.
+      *  `key` the function will use the inputs to determine the cache key, defaults to all params `JSON.stringify`ied
+      *  `params` the function used to determine the inputs for computing the cache key. This is an easier place to start to define what parameters are important in ,caching. This defaults to all inputs.
+      *  `maxAge` the number of milliseconds will hold the value before considering the cache entry to be invalid. By default values will live infinitely.
+      *  `extendOnAccess` determines if the cache timeout should be extended on access. This only applies to cache values that have specified a `maxAge`.
+      *  `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
-Additionally, there is support for planned eviction via the [@EvictCache](https://github.com/travetto/travetto/tree/main/module/cache/src/decorator.ts#L44) 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#L55) 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
+import { Cache, CacheService, EvictCache } from '@travetto/cache';
 import { MemoryModelService } from '@travetto/model-memory';
-import { Cache, EvictCache, CacheService } from '@travetto/cache';
 
-class User { }
+class User {}
 
 export class UserService {
-
   myCache = new CacheService(new MemoryModelService({ namespace: '' }));
   database: {
     lookupUser(id: string): Promise<User>;
@@ -119,14 +115,14 @@ export class UserService {
 ```
 
 ## Extending the Cache Service
-By design, the [CacheService](https://github.com/travetto/travetto/tree/main/module/cache/src/service.ts#L32) relies solely on the [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") module.  Specifically on the [Expiry](https://github.com/travetto/travetto/tree/main/module/model/src/types/expiry.ts#L10).   This combines basic support for CRUD as well as knowledge of how to manage expirable content.  Any model service that honors these contracts is a valid candidate to power the [CacheService](https://github.com/travetto/travetto/tree/main/module/cache/src/service.ts#L32).  The [CacheService](https://github.com/travetto/travetto/tree/main/module/cache/src/service.ts#L32) is expecting the model service to be registered using the @travetto/cache:model:
+By design, the [CacheService](https://github.com/travetto/travetto/tree/main/module/cache/src/service.ts#L35) relies solely on the [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") module. Specifically on the [Expiry](https://github.com/travetto/travetto/tree/main/module/model/src/types/expiry.ts#L10). This combines basic support for CRUD as well as knowledge of how to manage content that expires. Any model service that honors these contracts is a valid candidate to power the [CacheService](https://github.com/travetto/travetto/tree/main/module/cache/src/service.ts#L35). The [CacheService](https://github.com/travetto/travetto/tree/main/module/cache/src/service.ts#L35) is expecting the model service to be registered using the @travetto/cache:model:
 
 **Code: Registering a Custom Model Source**
 ```typescript
+import { CacheModelSymbol } from '@travetto/cache';
 import { InjectableFactory } from '@travetto/di';
 import type { ModelExpirySupport } from '@travetto/model';
 import { MemoryModelService } from '@travetto/model-memory';
-import { CacheModelSymbol } from '@travetto/cache';
 
 class Config {
   @InjectableFactory(CacheModelSymbol)

package/__index__.ts

@@ -1,4 +1,4 @@
-export * from './src/types.ts';
 export * from './src/decorator.ts';
 export * from './src/service.ts';
-export * from './src/util.ts';
+export * from './src/types.ts';
+export * from './src/util.ts';

package/package.json

@@ -1,37 +1,40 @@
 {
   "name": "@travetto/cache",
-  "version": "8.0.0-alpha.8",
-  "type": "module",
+  "version": "8.0.0",
   "description": "Caching functionality with decorators for declarative use.",
   "keywords": [
-    "typescript",
-    "travetto",
+    "cache",
     "decorator",
-    "cache"
+    "travetto",
+    "typescript"
   ],
   "homepage": "https://travetto.io",
   "license": "MIT",
   "author": {
-    "email": "travetto.framework@gmail.com",
-    "name": "Travetto Framework"
+    "name": "Travetto Framework",
+    "email": "travetto.framework@gmail.com"
+  },
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/cache"
   },
   "files": [
     "__index__.ts",
     "src",
     "support"
   ],
+  "type": "module",
   "main": "__index__.ts",
-  "repository": {
-    "url": "git+https://github.com/travetto/travetto.git",
-    "directory": "module/cache"
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "@travetto/di": "^8.0.0-alpha.8",
-    "@travetto/model": "^8.0.0-alpha.8"
+    "@travetto/di": "^8.0.0",
+    "@travetto/model": "^8.0.0"
   },
   "peerDependencies": {
-    "@travetto/test": "^8.0.0-alpha.8",
-    "@travetto/transformer": "^8.0.0-alpha.4"
+    "@travetto/test": "^8.0.0",
+    "@travetto/transformer": "^8.0.0"
   },
   "peerDependenciesMeta": {
     "@travetto/transformer": {
@@ -43,8 +46,5 @@
   },
   "travetto": {
     "displayName": "Caching"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/decorator.ts

@@ -1,7 +1,7 @@
 import { castTo, type MethodDescriptor, type TimeSpan, TimeUtil } from '@travetto/runtime';
 
 import type { CacheService } from './service.ts';
-import { type CoreCacheConfig, type CacheConfig, type CacheAware, CacheConfigSymbol, EvictConfigSymbol } from './types.ts';
+import { type CacheAware, type CacheConfig, CacheConfigSymbol, type CoreCacheConfig, EvictConfigSymbol } from './types.ts';
 
 /**
  * Indicates a method is intended to cache.  The return type must be properly serializable
@@ -9,10 +9,16 @@ import { type CoreCacheConfig, type CacheConfig, type CacheAware, CacheConfigSym
  * @param config The additional cache configuration
  * @kind decorator
  */
-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,
+  maxAge: number | TimeSpan,
+  config?: Omit<CacheConfig, 'maxAge'>
+): MethodDecorator;
 export function Cache<F extends string, U extends Record<F, CacheService>>(field: F, input?: CacheConfig): MethodDecorator;
 export function Cache<F extends string, U extends Record<F, CacheService>>(
-  field: F, input?: number | TimeSpan | CacheConfig, config: Exclude<CacheConfig, 'maxAge'> = {}
+  field: F,
+  input?: number | TimeSpan | CacheConfig,
+  config: Exclude<CacheConfig, 'maxAge'> = {}
 ): MethodDecorator {
   if (input !== undefined) {
     if (typeof input === 'string' || typeof input === 'number') {
@@ -21,12 +27,17 @@ export function Cache<F extends string, U extends Record<F, CacheService>>(
       config = input;
     }
   }
-  const decorator = function <R extends Promise<unknown>>(target: U & CacheAware, propertyKey: string, descriptor: MethodDescriptor<R>): void {
+  const decorator = function <R extends Promise<unknown>>(
+    target: U & CacheAware,
+    propertyKey: string,
+    descriptor: MethodDescriptor<R>
+  ): void {
     config.keySpace ??= `${target.constructor.name}.${propertyKey}`;
     (target[CacheConfigSymbol] ??= {})[propertyKey] = config;
     const handler = descriptor.value!;
     // Allows for DI to run, as the service will not be bound until after the decorator is run
     descriptor.value = castTo(function (this: typeof target) {
+      // biome-ignore lint/complexity/noArguments: We want to use arguments here
       return this[field].cache(this, propertyKey, handler, [...arguments]);
     });
     Object.defineProperty(descriptor.value, 'name', { value: propertyKey, writable: false });
@@ -48,8 +59,9 @@ export function EvictCache<F extends string, U extends Record<F, CacheService>>(
     const handler = descriptor.value!;
     // Allows for DI to run, as the service will not be bound until after the decorator is run
     descriptor.value = castTo(function (this: typeof target) {
+      // biome-ignore lint/complexity/noArguments: We want to use arguments here
       return this[field].evict(this, propertyKey, handler, [...arguments]);
     });
     Object.defineProperty(descriptor.value, 'name', { value: propertyKey, writable: false });
   };
-}
+}

package/src/error.ts

@@ -1,4 +1,4 @@
 import { RuntimeError } from '@travetto/runtime';
 
 /** Cache Error Class */
-export class CacheError extends RuntimeError { }
+export class CacheError extends RuntimeError {}

package/src/service.ts

@@ -1,36 +1,38 @@
-import { ExpiresAt, Index, Model, type ModelExpirySupport, NotFoundError, ModelStorageUtil, ModelIndexedUtil } from '@travetto/model';
-import { Text } from '@travetto/schema';
 import { Inject, Injectable } from '@travetto/di';
-import { RuntimeError, JSONUtil, TimeUtil } from '@travetto/runtime';
+import { ExpiresAt, Model, type ModelExpirySupport, ModelStorageUtil, NotFoundError } from '@travetto/model';
+import { ModelIndexedUtil, sortedIndex } from '@travetto/model-indexed';
+import { JSONUtil, RuntimeError, TimeUtil } from '@travetto/runtime';
+import { MaxLength, Text } from '@travetto/schema';
 
 import { CacheError } from './error.ts';
-import { CacheUtil } from './util.ts';
 import { type CacheAware, CacheConfigSymbol, CacheModelSymbol, EvictConfigSymbol } from './types.ts';
+import { CacheUtil } from './util.ts';
 
 const INFINITE_MAX_AGE = TimeUtil.duration('10y', 'ms');
 
-@Index({
-  name: 'keySpace',
-  type: 'unsorted',
-  fields: [{ keySpace: 1 }]
-})
 @Model({ autoCreate: 'production' })
 export class CacheRecord {
   id: string;
   @Text()
   entry: string;
+  @MaxLength(500)
   keySpace: string;
   @ExpiresAt()
   expiresAt: Date;
   issuedAt: Date;
 }
 
+const keySpaceIndex = sortedIndex(CacheRecord, {
+  name: 'keySpace',
+  key: { keySpace: true },
+  sort: { expiresAt: 1 }
+});
+
 /**
  * Cache source
  */
 @Injectable()
 export class CacheService {
-
   #modelService: ModelExpirySupport;
 
   constructor(@Inject({ qualifier: CacheModelSymbol, resolution: 'loose' }) modelService: ModelExpirySupport) {
@@ -48,7 +50,8 @@ export class CacheService {
     const delta = expiresAt.getTime() - Date.now();
     const maxAge = expiresAt.getTime() - issuedAt.getTime();
 
-    if (delta < 0) { // Expired
+    if (delta < 0) {
+      // Expired
       await this.#modelService.delete(CacheRecord, id);
       throw new CacheError('Key expired', { category: 'data' });
     }
@@ -76,14 +79,15 @@ export class CacheService {
   async set(id: string, keySpace: string, entry: unknown, maxAge?: number): Promise<unknown> {
     const entryText = JSONUtil.toBase64(entry);
 
-    const store = await this.#modelService.upsert(CacheRecord,
+    const store = await this.#modelService.upsert(
+      CacheRecord,
       CacheRecord.from({
         id,
         entry: entryText!,
         keySpace,
         expiresAt: TimeUtil.fromNow(maxAge || INFINITE_MAX_AGE),
         issuedAt: new Date()
-      }),
+      })
     );
 
     return JSONUtil.fromBase64(store.entry);
@@ -104,8 +108,10 @@ export class CacheService {
   async deleteAll(keySpace: string): Promise<void> {
     if (ModelIndexedUtil.isSupported(this.#modelService)) {
       const removes: Promise<void>[] = [];
-      for await (const item of this.#modelService.listByIndex(CacheRecord, 'keySpace', { keySpace })) {
-        removes.push(this.#modelService.delete(CacheRecord, item.id));
+      for await (const batch of this.#modelService.listByIndex(CacheRecord, keySpaceIndex, { keySpace })) {
+        for (const item of batch) {
+          removes.push(this.#modelService.delete(CacheRecord, item.id));
+        }
       }
       await Promise.all(removes);
     } else {
@@ -162,7 +168,8 @@ export class CacheService {
       result = await this.set(id, config.keySpace!, data, config.maxAge);
     }
 
-    if (config.reinstate) { // Reinstate result value if needed
+    if (config.reinstate) {
+      // Reinstate result value if needed
       result = config.reinstate(result);
     }
 
@@ -190,4 +197,4 @@ export class CacheService {
     }
     return result;
   }
-}
+}

package/src/types.ts

@@ -48,4 +48,3 @@ export interface CacheAware {
   [CacheConfigSymbol]?: Record<string, CacheConfig>;
   [EvictConfigSymbol]?: Record<string, CoreCacheConfig>;
 }
-

package/src/util.ts

@@ -6,7 +6,6 @@ import type { CoreCacheConfig } from './types.ts';
  * Standard cache utilities
  */
 export class CacheUtil {
-
   /**
    * Generate key given config, cache source and input params
    */
@@ -16,4 +15,4 @@ export class CacheUtil {
     const key = `${config.keySpace!}_${JSONUtil.toBase64(keyParams)}`;
     return BinaryMetadataUtil.hash(key, { length: 32 });
   }
-}
+}

package/support/test/service.ts

@@ -1,11 +1,12 @@
 import assert from 'node:assert';
 import timers from 'node:timers/promises';
 
-import { Suite, Test } from '@travetto/test';
-import { type ModelExpirySupport, ModelIndexedUtil } from '@travetto/model';
 import { Inject, Injectable } from '@travetto/di';
-import { castTo, type Class } from '@travetto/runtime';
+import type { ModelExpirySupport } from '@travetto/model';
+import { ModelIndexedUtil } from '@travetto/model-indexed';
+import { type Class, castTo } from '@travetto/runtime';
 import { Schema } from '@travetto/schema';
+import { Suite, Test } from '@travetto/test';
 
 import { InjectableSuite } from '@travetto/di/support/test/suite.ts';
 import { ModelSuite } from '@travetto/model/support/test/suite.ts';
@@ -15,11 +16,10 @@ import type { CacheService } from '../../src/service.ts';
 import { CacheModelSymbol } from '../../src/types.ts';
 
 @Schema()
-class User { }
+class User {}
 
 @Injectable()
 class SampleService {
-
   @Inject()
   source: CacheService;
 
@@ -85,7 +85,6 @@ class SampleService {
 @ModelSuite(CacheModelSymbol)
 @InjectableSuite()
 export abstract class CacheServiceSuite {
-
   serviceClass: Class<ModelExpirySupport>;
   configClass: Class;
 
@@ -106,7 +105,7 @@ export abstract class CacheServiceSuite {
     start = Date.now();
     res = await service.basic(10);
     diff = Date.now() - start;
-    assert(diff < (100 + this.baseLatency));
+    assert(diff < 100 + this.baseLatency);
     assert(res === 20);
   }
 
@@ -145,7 +144,7 @@ export abstract class CacheServiceSuite {
       start = Date.now();
       res = await service.ageExtension(10);
       diff = Date.now() - start;
-      assert(diff < (100 + this.baseLatency));
+      assert(diff < 100 + this.baseLatency);
       assert(res === 30);
     }
 
@@ -202,12 +201,12 @@ export abstract class CacheServiceSuite {
     await service.getUser('200');
     const start = Date.now();
     await service.getUser('200');
-    assert((Date.now() - start) <= (this.baseLatency + 100));
+    assert(Date.now() - start <= this.baseLatency + 100);
 
     await service.deleteUser('200');
     const start2 = Date.now();
     await service.getUser('200');
-    assert((Date.now() - start2) >= 100);
+    assert(Date.now() - start2 >= 100);
 
     // First time is free
     await service.deleteUser('200');
@@ -224,33 +223,33 @@ export abstract class CacheServiceSuite {
     const service = this.testService;
 
     // Prime cache
-    for (let i = 0; i < 10; i++) {
+    for (let i = 0; i < 10; i += 1) {
       const start = Date.now();
       await service.getUser(`${i}`);
-      assert((Date.now() - start) >= 100);
+      assert(Date.now() - start >= 100);
     }
 
     // Read cache
-    for (let i = 0; i < 10; i++) {
+    for (let i = 0; i < 10; i += 1) {
       const start = Date.now();
       await service.getUser(`${i}`);
-      assert((Date.now() - start) <= (this.baseLatency + 100));
+      assert(Date.now() - start <= this.baseLatency + 100);
     }
 
     await service.deleteAllUsers();
 
     // Prime cache
-    for (let i = 0; i < 10; i++) {
+    for (let i = 0; i < 10; i += 1) {
       const start = Date.now();
       await service.getUser(`${i}`);
-      assert((Date.now() - start) >= 100);
+      assert(Date.now() - start >= 100);
     }
 
     // Read cache
-    for (let i = 0; i < 10; i++) {
+    for (let i = 0; i < 10; i += 1) {
       const start = Date.now();
       await service.getUser(`${i}`);
-      assert((Date.now() - start) <= (this.baseLatency + 100));
+      assert(Date.now() - start <= this.baseLatency + 100);
     }
   }
-}
+}