@daiso-tech/core 0.15.0 → 0.17.4

package/dist/types/cache/contracts/cache-factory.contract.d.ts

@@ -1,23 +1,26 @@
 /**
  * @module Cache
  */
-import type { INamespacedCache } from "../../cache/contracts/cache.contract";
+import type { IGroupableCache } from "../../cache/contracts/cache.contract";
 /**
- * The <i>ICacheFactory</i> contract makes it easy to configure and switch between different <i>{@link INamespacedCache}</i> dynamically.
+ * The <i>ICacheFactory</i> contract makes it easy to configure and switch between different <i>{@link IGroupableCache}</i> dynamically.
  * @group Contracts
  */
-export type ICacheFactory<TDrivers extends string = string, TType = unknown> = {
+export type ICacheFactory<TAdapters extends string = string> = {
     /**
-     * The <i>use</i> method will throw an error if you provide it unregisted driver.
-     * If no default driver is defined an error will be thrown by <i>use</i> method.
-     * @throws {UnregisteredDriverError} {@link UnregisteredDriverError}
-     * @throws {DefaultDriverNotDefinedError} {@link DefaultDriverNotDefinedError}
+     * The <i>use</i> method will throw an error if you provide it unregisted adapter.
+     * If no default adapter is defined an error will be thrown by <i>use</i> method.
+     * @throws {UnregisteredAdapterError} {@link UnregisteredAdapterError}
+     * @throws {DefaultAdapterNotDefinedError} {@link DefaultAdapterNotDefinedError}
      * @example
      * ```ts
      * import { type ICacheFactory } from "@daiso-tech/core";
+     * import Redis from "ioredis"
      *
+     * // Asume the inputed cacheFactory has registered both a memory and Redis ICacheAdapter.
+     * // The memory ICacheAdapter adapter is the default.
      * async function main(cacheFactory: ICacheFactory): Promise<void> {
-     *   // Will add key using the default driver
+     *   // Will add key using the default adapter
      *   await cacheFactory
      *     .use()
      *     .add("a", 1);
@@ -28,21 +31,5 @@ export type ICacheFactory<TDrivers extends string = string, TType = unknown> = {
      * }
      * ```
      */
-    use(driverName?: TDrivers): INamespacedCache<TType>;
-    /**
-     * The <i>withTypes</i> method is used to set the value types of the cache.
-     * @example
-     * ```ts
-     * import { type ICacheFactory zodValidator } from "@daiso-tech/core";
-     *
-     * async function main(cacheFactory: ICacheFactory): Promise<void> {
-     *   await cacheFactory
-     *     .withTypes<string>()
-     *     .use()
-     *     // You will se an typescript error
-     *     .add("a", 1)
-     * }
-     * ```
-     */
-    withType<TOutput extends TType = TType>(): ICacheFactory<TDrivers, TOutput>;
+    use<TType = unknown>(adapterName?: TAdapters): IGroupableCache<TType>;
 };

package/dist/types/cache/contracts/cache.contract.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module Cache
  */
-import type { IListenable } from "../../event-bus/contracts/_module";
+import type { IEventListener } from "../../event-bus/contracts/_module";
 import type { OneOrMore } from "../../utilities/_module";
 import { type AsyncLazyable, type GetOrAddValue } from "../../utilities/_module";
 import type { CacheEvents } from "../../cache/contracts/_module";
@@ -11,7 +11,7 @@ import type { LazyPromise } from "../../async/_module";
  * The <i>ICacheListenable</i> contract defines a way for listening <i>{@link ICache}</i> crud operations.
  * @group Contracts
  */
-export type ICacheListenable<TType = unknown> = IListenable<CacheEvents<TType>>;
+export type ICacheListener<TType = unknown> = IEventListener<CacheEvents<TType>>;
 /**
  * @group Contracts
  */
@@ -27,84 +27,404 @@ export type WithTtlValue<TType> = {
  * It commes with more convient methods compared to <i>ICacheAdapter</i>.
  * @group Contracts
  */
-export type ICache<TType = unknown> = ICacheListenable & {
+export type ICache<TType = unknown> = ICacheListener & {
     /**
      * The <i>exists</i> method returns true when <i>key</i> is found otherwise false will be returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.exists("a");
+     *   // false
+     * }
+     * ```
      */
     exists(key: string): LazyPromise<boolean>;
     /**
      * The <i>existsMany</i> method returns true for the <i>keys</i> that are found otherwise false will be returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.existsMany(["a", "b"]);
+     *   // { a: false, b: false }
+     * }
+     * ```
      */
     existsMany<TKeys extends string>(keys: TKeys[]): LazyPromise<Record<TKeys, boolean>>;
     /**
      * The <i>missing</i> method returns true when <i>key</i> is not found otherwise false will be returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.exists("a");
+     *   // true
+     * }
+     * ```
      */
     missing(key: string): LazyPromise<boolean>;
     /**
      * The <i>missingMany</i> method returns true for the <i>keys</i> that are not found otherwise false will be returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.existsMany(["a", "b"]);
+     *   // { a: true, b: true }
+     * }
+     * ```
      */
     missingMany<TKeys extends string>(keys: TKeys[]): LazyPromise<Record<TKeys, boolean>>;
     /**
      * The <i>get</i> method returns the value when <i>key</i> is found otherwise null will be returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.get("a");
+     *   // null
+     * }
+     * ```
      */
     get(key: string): LazyPromise<TType | null>;
     /**
      * The <i>getMany</i> returns the value for the <i>keys</i> that are found otherwise null will be returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.getMany(["a", "b"]);
+     *   // { a: null, b: null }
+     * }
+     * ```
      */
     getMany<TKeys extends string>(keys: TKeys[]): LazyPromise<Record<TKeys, TType | null>>;
     /**
      * The <i>getOr</i> method returns the value when <i>key</i> is found otherwise <i>defaultValue</i> will be returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.getOr("a", -1);
+     *   // -1
+     * }
+     * ```
      */
     getOr(key: string, defaultValue: AsyncLazyable<TType>): LazyPromise<TType>;
     /**
      * The <i>getOrMany</i> method returns the value for the keys that are found otherwise defaultValue will be returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.getOrMany({ a: -1, b: () => -2, c: async () => -3 });
+     *   // { a: -1, b: -2, c: -3 }
+     * }
+     * ```
      */
     getOrMany<TKeys extends string>(keysWithDefaults: Record<TKeys, AsyncLazyable<TType>>): LazyPromise<Record<TKeys, TType>>;
     /**
      * The <i>getOrFail</i> method returns the value when <i>key</i> is found otherwise an error will be thrown.
      * @throws {KeyNotFoundCacheError} {@link KeyNotFoundCacheError}
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.getOrFail("a");
+     *   // An error will be thrown
+     * }
+     * ```
      */
     getOrFail(key: string): LazyPromise<TType>;
     /**
      * The <i>add</i> method adds a <i>key</i> with given <i>value</i> when key doesn't exists. Returns true when key doesn't exists otherwise false will be returned.
      * You can provide a <i>ttl</i> value. If null is passed, the item will not expire.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.add("a", 1);
+     *   // true
+     *
+     *   await cache.add("a", 2);
+     *   // false
+     *
+     *   await cache.get("a");
+     *   // 1
+     * }
+     * ```
+     * @example
+     * ```ts
+     * import { type ICache, TimeSpan, delay } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   const ttl = TimeSpan.fromSeconds(1);
+     *
+     *   await cache.add("a", 1, ttl);
+     *   // true
+     *
+     *   await delay(ttl)
+     *
+     *   await cache.add("a", 2);
+     *   // true
+     *
+     *   await cache.get("a");
+     *   // 2
+     * }
+     * ```
      */
     add(key: string, value: TType, ttl?: TimeSpan | null): LazyPromise<boolean>;
     /**
      * The <i>addMany</i> method adds new keys. Returns true for the keys that where added otherwise false will be returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.addMany({ a: { value: 1 } });
+     *   // { a: true }
+     *
+     *   await cache.addMany({ a: { value: 2 } });
+     *   // { a: false }
+     *
+     *   await cache.get("a");
+     *   // 1
+     * }
+     * ```
+     * @example
+     * ```ts
+     * import { type ICache, TimeSpan, delay } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   const ttl = TimeSpan.fromSeconds(1);
+     *
+     *   await cache.addMany({ a: { value: 1, ttl } });
+     *   // { a: true }
+     *
+     *   await delay(ttl)
+     *
+     *   await cache.addMany({ a: { value: 2 } });
+     *   // { a: true }
+     *
+     *   await cache.get("a");
+     *   // 2
+     * }
+     * ```
      */
     addMany<TKeys extends string>(values: Record<TKeys, WithTtlValue<TType>>): LazyPromise<Record<TKeys, boolean>>;
     /**
      * The <i>update</i> method updates the given <i>key</i> with given <i>value</i>. Returns true when key otherwise false will be returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.update("a", 1);
+     *   // false
+     *
+     *   await cache.add("a", 1);
+     *
+     *
+     *   await cache.update("a", 2);
+     *   // true
+     *
+     *   await cache.get("a");
+     *   // 2
+     * }
+     * ```
      */
     update(key: string, value: TType): LazyPromise<boolean>;
     /**
      * The <i>updateMany</i> method updates the given keys. Returns true for the keys that where updated otherwise false will be returned.
+     *
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.updateMany({ a: 1 });
+     *   // false
+     *
+     *   await cache.add("a", 1);
+     *
+     *   await cache.updateMany({ a: 2 });
+     *   // true
+     *
+     *   await cache.get("a");
+     *   // 2
+     * }
+     * ```
      */
     updateMany<TKeys extends string>(values: Record<TKeys, TType>): LazyPromise<Record<TKeys, boolean>>;
     /**
-     * The <i>put</i> method replaces the key with given <i>value</i> if found. If the <i>key</i> is not found it will just be added. True is returned if the key is found otherwise false will be returned.
-     * You can provide a <i>ttl</i> value. If null is passed, the item will not expire.
+     * The <i>put</i> method replaces a <i>key</i> if the <i>key</i> exists including the ttl value or adds <i>key</i> that do not exists with a given <i>ttl</i>.
+     * Returns true if the <i>key</i> where replaced otherwise false is returned.
+     * You can provide a <i>ttl</i> value for the replaced key. If <i>null</i> is passed, the item will not expires and <i>null</i> is the default value.
+     * @example
+     * ```ts
+     * import { type ICache, TimeSpan, delay } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.put("a", 1);
+     *   // false
+     *
+     *   const ttl = TimeSpan.fromSeconds(1);
+     *   await cache.put("a", 2, ttl);
+     *   // true
+     *
+     *   await cache.get("a");
+     *   // 2
+     *
+     *   await delay(ttl);
+     *   await cache.get("a");
+     *   // null
+     * }
+     * ```
      */
     put(key: string, value: TType, ttl?: TimeSpan | null): LazyPromise<boolean>;
     /**
-     * The <i>putMany</i> method replaces the keys that exists. Adds keys that do not exists. Returns true for all the keys that where updated otherwise false is returned.
+     * The <i>putMany</i> method replaces the keys that exists including their ttl values or adds keys that do not exists.
+     * Returns true for all the keys that where replaced otherwise false is returned.
+     * @example
+     * ```ts
+     * import { type ICache, TimeSpan, delay } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.putMany({ a: { value: 1 } });
+     *   // { a: false }
+     *
+     *   const ttl = TimeSpan.fromSeconds(1);
+     *   await cache.put({ a: { value: 2, ttl } });
+     *   // { a: true }
+     *
+     *   await cache.get("a");
+     *   // 2
+     *
+     *   await delay(ttl);
+     *   await cache.get("a");
+     *   // null
+     * }
+     * ```
      */
     putMany<TKeys extends string>(values: Record<TKeys, WithTtlValue<TType>>): LazyPromise<Record<TKeys, boolean>>;
     /**
      * The <i>remove</i> method removes the given <i>key</i> when found. Returns true if the key is found otherwise false is returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.remove("a");
+     *   // false
+     * }
+     * ```
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.put("a", 1);
+     *
+     *   await cache.remove("a");
+     *   // true
+     * }
+     * ```
      */
     remove(key: string): LazyPromise<boolean>;
     /**
      * The <i>removeMany</i> method removes keys. Returns true for the keys that are removed otherwise false is returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.removeMany(["a"]);
+     *   // false
+     * }
+     * ```
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.put("a", 1);
+     *
+     *   await cache.removeMany(["a"]);
+     *   // { a: true }
+     * }
+     * ```
      */
     removeMany<TKeys extends string>(keys: TKeys[]): LazyPromise<Record<TKeys, boolean>>;
     /**
      * The <i>getAndRemove</i> method removes the given <i>key</i> and returns it when found otherwise null will be returned.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.getAndRemove("a");
+     *   // null
+     *
+     *   await cache.put("a", 1)
+     *
+     *   await cache.getAndRemove("a");
+     *   // "a"
+     *
+     *   await cache.get("a");
+     *   // null
+     * }
+     * ```
      */
     getAndRemove(key: string): LazyPromise<TType | null>;
     /**
      * The <i>getOrAdd</i> method will retrieve the given <i>key</i> if found otherwise <i>valueToAdd</i> will be added and returned.
+     * The <i>valueToAdd<i> can be async or sync function.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.getOrAdd("a", 1);
+     *   // 1
+     *
+     *   await cache.getOrAdd("a", async () => -1);
+     *   // 1
+     * }
+     * ```
      */
     getOrAdd(key: string, valueToAdd: AsyncLazyable<GetOrAddValue<TType>>, ttl?: TimeSpan | null): LazyPromise<TType>;
     /**
@@ -112,6 +432,24 @@ export type ICache<TType = unknown> = ICacheListenable & {
      * Returns true if key is incremented otherwise false will be returned.
      * An error will thrown if the key is not a number.
      * @throws {TypeCacheError} {@link TypeCacheError}
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.increment("a", 1);
+     *   // false
+     *
+     *   await cache.put("a", 1);
+     *
+     *   await cache.increment("a", 1);
+     *   // true
+     *
+     *   await cache.get("a");
+     *   // 2
+     * }
+     * ```
      */
     increment(key: string, value?: Extract<TType, number>): LazyPromise<boolean>;
     /**
@@ -119,7 +457,24 @@ export type ICache<TType = unknown> = ICacheListenable & {
      * Returns true if key exists otherwise false will be returned.
      * An error will thrown if the key is not a number.
      * @throws {TypeCacheError} {@link TypeCacheError}
-     * An error will thrown if the key is not a number.
+     * @example
+     * ```ts
+     * import type { ICache } from "@daiso-tech/core";
+     *
+     * // Asume the inputed cache is empty
+     * async function main(cache: ICache): Promise<void> {
+     *   await cache.decrement("a", 1);
+     *   // false
+     *
+     *   await cache.put("a", 1);
+     *
+     *   await cache.decrement("a", 1);
+     *   // true
+     *
+     *   await cache.get("a");
+     *   // 0
+     * }
+     * ```
      */
     decrement(key: string, value?: Extract<TType, number>): LazyPromise<boolean>;
     /**
@@ -127,48 +482,53 @@ export type ICache<TType = unknown> = ICacheListenable & {
      */
     clear(): LazyPromise<void>;
     /**
-     * The <i>getNamespace</i> method returns the complete namespace.
+     * The <i>getGroup</i> method returns the group name.
      * @example
      * ```ts
      * import type { ICache } from "@daiso-tech/core";
      *
-     * async function main(cache: ICache) {
-     *   // Will be "@root"
-     *   console.log(cache.getNamespace())
+     * // Asume the inputed cache is empty and the default rootGroup is "@global"
+     * async function main(cache: ICache): Promise<void> {
+     *   console.log(cache.getGroup())
      *
-     *   const cacheA = cache.withNamespace("a");
+     *   const cacheA = cache.withGroup("a");
      *
-     *   // Will be "@root/a"
-     *   console.log(cacheA.getNamespace())
+     *   // Will be "@global/a"
+     *   console.log(cacheA.getGroup())
      * }
      * ```
      */
-    getNamespace(): string;
+    getGroup(): string;
 };
 /**
- * The <i>INamespacedCache</i> contract defines a way for storing data as key-value pairs independent of data storage.
+ * The <i>IGroupableCache</i> contract defines a way for storing data as key-value pairs independent of data storage.
  * It commes with one extra method which is useful for multitennat applications compared to <i>ICache</i>.
  * @group Contracts
  */
-export type INamespacedCache<TType = unknown> = ICache<TType> & {
+export type IGroupableCache<TType = unknown> = ICache<TType> & {
     /**
-     * The <i>withNamespace</i> method returns new instance of <i>{@link ICache}</i> where all the keys will be prefixed with a given <i>namespace</i>.
+     * The <i>withGroup</i> method returns a new <i>{@link ICache}</i> instance that groups keys together.
+     * Only keys in the group can be updated, removed, or retrieved, leaving keys outside the group unaffected.
      * This useful for multitennat applications.
      * @example
      * ```ts
-     * import { type ICache } from "@daiso-tech/core";
+     * import type { ICache } from "@daiso-tech/core";
      *
+     * // Asume the inputed cache is empty and the default rootGroup is "@global"
      * async function main(cache: ICache): Promise<void> {
-     *   const cacheA = cache.withNamespace("a");
+     *   const cacheA = cache.withGroup("a");
      *   await cacheA.add("a", 1);
      *
-     *   const cacheB = cache.withNamespace("b");
+     *   const cacheB = cache.withGroup("b");
      *   await cacheB.add("b", 2);
      *
      *   // Will print { a: 1, b: null }
      *   console.log(await cacheA.getMany(["a", "b"]));
+     *
+     *   // Will print { a: nullp, b: 2 }
+     *   console.log(await cacheB.getMany(["a", "b"]));
      * }
      * ```
      */
-    withNamespace(namespace: OneOrMore<string>): ICache<TType>;
+    withGroup(group: OneOrMore<string>): ICache<TType>;
 };