feat(core-kernel): initial draft of cache

packages/core-kernel/src/contracts/core-kernel/cache.ts

@@ -1,51 +1,165 @@
-export interface ICacheStore {
+import { IApplication } from "./application";
+
+export interface ICacheStore<K, T> {
+    /**
+     * Create a new instance of the cache store.
+     *
+     * @param {IApplication} app
+     * @returns {ICacheStore<K, T>}
+     * @memberof ICacheStore
+     */
+    make(app: IApplication): Promise<ICacheStore<K, T>>;
+
+    /**
+     * Get all of the items in the cache.
+     *
+     * @returns {Array<[K, T]>}
+     * @memberof ICacheStore
+     */
+    all(): Promise<Array<[K, T]>>;
+
+    /**
+     * Get the keys of the cache items.
+     *
+     * @returns {K[]}
+     * @memberof ICacheStore
+     */
+    keys(): Promise<K[]>;
+
+    /**
+     * Get the values of the cache items.
+     *
+     * @returns {T[]}
+     * @memberof ICacheStore
+     */
+    values(): Promise<T[]>;
+
     /**
      * Retrieve an item from the cache by key.
+     *
+     * @param {K} key
+     * @returns {(T | undefined)}
+     * @memberof ICacheStore
      */
-    get(key: string): Promise<any>;
+    get(key: K): Promise<T | undefined>;
 
     /**
      * Retrieve multiple items from the cache by key.
+     *
+     * @param {K[]} keys
+     * @returns {(Array<T | undefined>)}
+     * @memberof ICacheStore
      */
-    many(keys: string[]): Promise<Record<string, any>>;
+    getMany(keys: K[]): Promise<Array<T | undefined>>;
 
     /**
-     * Store an item in the cache for a given number of milliseconds.
+     * Store an item in the cache for a given number of seconds.
+     *
+     * @param {K} key
+     * @param {T} value
+     * @param {number} seconds
+     * @returns {boolean}
+     * @memberof ICacheStore
      */
-    put(key: string, value: any, ttl?: number): Promise<void>;
+    put(key: K, value: T, seconds: number): Promise<boolean>;
 
     /**
-     * Store multiple items in the cache for a given number of milliseconds.
+     * Store multiple items in the cache for a given number of seconds.
+     *
+     * @param {Array<[K, T]>} values
+     * @param {number} seconds
+     * @returns {boolean[]}
+     * @memberof ICacheStore
      */
-    putMany(values: string[], ttl?: number): Promise<void>;
+    putMany(values: Array<[K, T]>, seconds: number): Promise<boolean[]>;
 
     /**
-     * Increment the value of an item in the cache.
+     * Determine if an item exists in the cache.
+     *
+     * @param {K} key
+     * @returns {boolean}
+     * @memberof ICacheStore
      */
-    increment(key: string, value: number): Promise<void>;
+    has(key: K): Promise<boolean>;
 
     /**
-     * Decrement the value of an item in the cache.
+     * Determine multiple items exist in the cache.
+     *
+     * @param {K[]} keys
+     * @returns {boolean[]}
+     * @memberof ICacheStore
      */
-    decrement(key: string, value: number): Promise<void>;
+    hasMany(keys: K[]): Promise<boolean[]>;
 
     /**
-     * Check if an item exists in the cache by key.
+     * Determine if an item doesn't exist in the cache.
+     *
+     * @param {K} key
+     * @returns {boolean}
+     * @memberof ICacheStore
      */
-    has(key: string): Promise<boolean>;
+    missing(key: K): Promise<boolean>;
+
+    /**
+     * Determine multiple items don't exist in the cache.
+     *
+     * @param {K[]} keys
+     * @returns {boolean[]}
+     * @memberof ICacheStore
+     */
+    missingMany(keys: K[]): Promise<boolean[]>;
 
     /**
      * Store an item in the cache indefinitely.
+     *
+     * @param {K} key
+     * @param {T} value
+     * @returns {boolean}
+     * @memberof ICacheStore
+     */
+    forever(key: K, value: T): Promise<boolean>;
+
+    /**
+     * Store multiple items in the cache indefinitely.
+     *
+     * @param {Array<[K, T]>} values
+     * @param {T} value
+     * @returns {boolean[]}
+     * @memberof ICacheStore
      */
-    forever(key: string, value: string): Promise<void>;
+    foreverMany(values: Array<[K, T]>, value: T): Promise<boolean[]>;
 
     /**
      * Remove an item from the cache.
+     *
+     * @param {K} key
+     * @returns {boolean}
+     * @memberof ICacheStore
      */
-    forget(key: string): Promise<void>;
+    forget(key: K): Promise<boolean>;
+
+    /**
+     * Remove multiple items from the cache.
+     *
+     * @param {K[]} keys
+     * @returns {boolean[]}
+     * @memberof ICacheStore
+     */
+    forgetMany(keys: K[]): Promise<boolean[]>;
 
     /**
      * Remove all items from the cache.
+     *
+     * @returns {boolean}
+     * @memberof ICacheStore
+     */
+    flush(): Promise<boolean>;
+
+    /**
+     * Get the cache key prefix.
+     *
+     * @returns {string}
+     * @memberof ICacheStore
      */
-    flush(): Promise<void>;
+    getPrefix(): Promise<string>;
 }

packages/core-kernel/src/errors.ts

@@ -225,3 +225,19 @@ export class FailedDependencySatisfaction extends KernelError {
         super(`Expected "${dep}" to satisfy "${expected}" but received "${given}".`);
     }
 }
+
+/**
+ * @export
+ * @class NotImplementedError
+ * @extends {KernelError}
+ */
+export class NotImplementedError extends KernelError {
+    /**
+     * @param {string} klass
+     * @param {string} method
+     * @memberof NotImplementedError
+     */
+    constructor(klass: string, method: string) {
+        super(`Method [${method}] is not implemented in [${klass}].`);
+    }
+}