@daiso-tech/core 0.27.0 → 0.28.0

package/dist/cache/implementations/derivables/cache/cache.d.ts

@@ -6,7 +6,7 @@ import { type ICache, type ICacheAdapter } from "../../../../cache/contracts/_mo
 import { type IGroupableCache } from "../../../../cache/contracts/_module-exports.js";
 import { type AsyncLazyable, type Invokable, type OneOrMore } from "../../../../utilities/_module-exports.js";
 import { type NoneFunction, type TimeSpan, type Factoryable } from "../../../../utilities/_module-exports.js";
-import type { BackoffPolicy, RetryPolicy } from "../../../../async/_module-exports.js";
+import type { LazyPromiseSettingsBase } from "../../../../async/_module-exports.js";
 import { LazyPromise } from "../../../../async/_module-exports.js";
 import type { IGroupableEventBus, Unsubscribe, EventClass, EventInstance } from "../../../../event-bus/contracts/_module-exports.js";
 import type { IKeyPrefixer, Items } from "../../../../utilities/_module-exports.js";
@@ -15,7 +15,7 @@ import type { IKeyPrefixer, Items } from "../../../../utilities/_module-exports.
  * IMPORT_PATH: ```"@daiso-tech/core/cache"```
  * @group Derivables
  */
-export type CacheSettingsBase = {
+export type CacheSettingsBase = LazyPromiseSettingsBase & {
     keyPrefixer: IKeyPrefixer;
     /**
      * @default
@@ -36,26 +36,6 @@ export type CacheSettingsBase = {
      * @default {null}
      */
     defaultTtl?: TimeSpan | null;
-    /**
-     * The default retry attempt to use in the returned <i>LazyPromise</i>.
-     * @default {null}
-     */
-    retryAttempts?: number | null;
-    /**
-     * The default backof policy to use in the returned <i>LazyPromise</i>.
-     * @default {null}
-     */
-    backoffPolicy?: BackoffPolicy | null;
-    /**
-     * The default retry policy to use in the returned <i>LazyPromise</i>.
-     * @default {null}
-     */
-    retryPolicy?: RetryPolicy | null;
-    /**
-     * The default timeout to use in the returned <i>LazyPromise</i>.
-     * @default {null}
-     */
-    timeout?: TimeSpan | null;
 };
 /**
  *
@@ -88,7 +68,8 @@ export declare class Cache<TType = unknown> implements IGroupableCache<TType> {
     private readonly retryAttempts;
     private readonly backoffPolicy;
     private readonly retryPolicy;
-    private readonly timeout;
+    private readonly retryTimeout;
+    private readonly totalTimeout;
     private readonly keyPrefixer;
     /**
      *
@@ -122,27 +103,29 @@ export declare class Cache<TType = unknown> implements IGroupableCache<TType> {
      * import { SqliteCacheAdapter } from "@daiso-tech/core/cache/adapters";
      * import type { ICacheAdapter } from "@daiso-tech/core/cache/contracts";
      * import { Serde } from "@daiso-tech/core/serde";
+     * import type { ISerde } from "@daiso-tech/core/serde/contracts";
      * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/adapters"
      * import Sqlite from "better-sqlite3";
      * import { Cache } from "@daiso-tech/core/cache";
-     * import { KeyPrefixer, type Promiseable } from "@daiso-tech/core/utilities";
-     *
-     *
-     * async function cahceAdapterFactory(prefix: string): Promiseable<ICacheAdapter> {
-     *   const database = new Sqlite("local.db");
-     *   const serde = new Serde(new SuperJsonSerdeAdapter());
-     *   const cacheAdapter = new SqliteCacheAdapter({
-     *     database,
-     *     serde,
-     *     tableName: `cache_${prefix}`
-     *   });
-     *   await cacheAdapter.init();
-     *   return cacheAdapter;
+     * import { KeyPrefixer, type ISqliteDatabase, type FactoryFn } from "@daiso-tech/core/utilities";
+     *
+     * function cahceAdapterFactory(database: ISqliteDatabase, serde: ISerde<string>): FactoryFn<string, ICacheAdapter> {
+     *   return async (prefix) => {
+     *     const cacheAdapter = new SqliteCacheAdapter({
+     *       database,
+     *       serde,
+     *       tableName: `cache_${prefix}`
+     *     });
+     *     await cacheAdapter.init();
+     *     return cacheAdapter;
+     *   }
      * }
      *
+     * const database = new Sqlite("local.db");
+     * const serde = new Serde(new SuperJsonSerdeAdapter());
      * const cache = new Cache({
      *   keyPrefixer: new KeyPrefixer("cache"),
-     *   adapter: cahceAdapterFactory,
+     *   adapter: cahceAdapterFactory(database, serde),
      * });
      * ```
      *
@@ -152,39 +135,74 @@ export declare class Cache<TType = unknown> implements IGroupableCache<TType> {
      * import { SqliteCacheAdapter } from "@daiso-tech/core/cache/adapters";
      * import type { ICacheAdapter } from "@daiso-tech/core/cache/contracts";
      * import { Serde } from "@daiso-tech/core/serde";
+     * import type { ISerde } from "@daiso-tech/core/serde/contracts";
      * import { SuperJsonSerdeAdapter } from "@daiso-tech/core/serde/adapters"
      * import Sqlite from "better-sqlite3";
      * import { Cache } from "@daiso-tech/core/cache";
-     * import { KeyPrefixer, type IFactoryObject, type Promiseable } from "@daiso-tech/core/utilities";
+     * import { KeyPrefixer, type ISqliteDatabase, type IFactoryObject, type Promiseable } from "@daiso-tech/core/utilities";
      *
      * class CahceAdapterFactory implements IFactoryObject<string, ICacheAdapter> {
+     *   constructor(private readonly database: ISqliteDatabase, private readonly serde: ISerde<string>) {}
+     *
      *   async use(prefix: string): Promiseable<ICacheAdapter> {
-     *     const database = new Sqlite("local.db");
-     *     const serde = new Serde(new SuperJsonSerdeAdapter());
      *     const cacheAdapter = new SqliteCacheAdapter({
-     *       database,
-     *       serde,
+     *       database: this.database,
+     *       serde: this.serde,
      *       tableName: `cache_${prefix}`
      *     });
      *     await cacheAdapter.init();
      *     return cacheAdapter;
      *   }
      * }
-     * const cahceAdapterFactory = new CahceAdapterFactory();
+     *
+     * const database = new Sqlite("local.db");
+     * const serde = new Serde(new SuperJsonSerdeAdapter());
      * const cache = new Cache({
      *   keyPrefixer: new KeyPrefixer("cache"),
-     *   adapter: cahceAdapterFactory,
+     *   adapter: new CahceAdapterFactory(database, serde),
      * });
      * ```
      */
     constructor(settings: CacheSettings);
+    /**
+     * You can listen to the following <i>{@link CacheEvents}</i> of the <i>{@link ICache}</i> instance.
+     * To understand how this method works, refer to <i>{@link IEventListenable}</i>.
+     */
     addListener<TEventClass extends EventClass<CacheEvents<TType>>>(event: TEventClass, listener: Invokable<EventInstance<TEventClass>>): LazyPromise<void>;
+    /**
+     * You can listen to the following <i>{@link CacheEvents}</i> of the <i>{@link ICache}</i> instance.
+     * To understand how this method works, refer to <i>{@link IEventListenable}</i>.
+     */
     addListenerMany<TEventClassArr extends EventClass<CacheEvents<TType>>[]>(events: [...TEventClassArr], listener: Invokable<EventInstance<Items<TEventClassArr>>>): LazyPromise<void>;
+    /**
+     * You can listen to the following <i>{@link CacheEvents}</i> of the <i>{@link ICache}</i> instance.
+     * To understand how this method works, refer to <i>{@link IEventListenable}</i>.
+     */
     removeListener<TEventClass extends EventClass<CacheEvents<TType>>>(event: TEventClass, listener: Invokable<EventInstance<TEventClass>>): LazyPromise<void>;
+    /**
+     * You can listen to the following <i>{@link CacheEvents}</i> of the <i>{@link ICache}</i> instance.
+     * To understand how this method works, refer to <i>{@link IEventListenable}</i>.
+     */
     removeListenerMany<TEventClassArr extends EventClass<CacheEvents<TType>>[]>(events: [...TEventClassArr], listener: Invokable<EventInstance<Items<TEventClassArr>>>): LazyPromise<void>;
+    /**
+     * You can listen to the following <i>{@link CacheEvents}</i> of the <i>{@link ICache}</i> instance.
+     * To understand how this method works, refer to <i>{@link IEventListenable}</i>.
+     */
     listenOnce<TEventClass extends EventClass<CacheEvents<TType>>>(event: TEventClass, listener: Invokable<EventInstance<TEventClass>>): LazyPromise<void>;
+    /**
+     * You can listen to the following <i>{@link CacheEvents}</i> of the <i>{@link ICache}</i> instance.
+     * To understand how this method works, refer to <i>{@link IEventListenable}</i>.
+     */
     asPromise<TEventClass extends EventClass<CacheEvents<TType>>>(event: TEventClass): LazyPromise<EventInstance<TEventClass>>;
+    /**
+     * You can listen to the following <i>{@link CacheEvents}</i> of the <i>{@link ICache}</i> instance.
+     * To understand how this method works, refer to <i>{@link IEventListenable}</i>.
+     */
     subscribe<TEventClass extends EventClass<CacheEvents<TType>>>(event: TEventClass, listener: Invokable<EventInstance<TEventClass>>): LazyPromise<Unsubscribe>;
+    /**
+     * You can listen to the following <i>{@link CacheEvents}</i> of the <i>{@link ICache}</i> instance.
+     * To understand how this method works, refer to <i>{@link IEventListenable}</i>.
+     */
     subscribeMany<TEventClassArr extends EventClass<CacheEvents<TType>>[]>(events: [...TEventClassArr], listener: Invokable<EventInstance<Items<TEventClassArr>>>): LazyPromise<Unsubscribe>;
     private createLazyPromise;
     exists(key: OneOrMore<string>): LazyPromise<boolean>;
@@ -192,7 +210,151 @@ export declare class Cache<TType = unknown> implements IGroupableCache<TType> {
     get(key: OneOrMore<string>): LazyPromise<TType | null>;
     getOrFail(key: OneOrMore<string>): LazyPromise<TType>;
     getAndRemove(key: OneOrMore<string>): LazyPromise<TType | null>;
+    /**
+     * @example
+     * ```ts
+     * import { Cache } from "@daiso-tech/core/cache";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/adapters";
+     * import { KeyPrefixer } from "@daiso-tech/core/utilities";
+     *
+     * const cache = new Cache({
+     *   adapter: new MemoryCacheAdapter(),
+     *   keyPrefixer: new KeyPrefixer("cache")
+     * });
+     *
+     * const value = await cache.getOr("a", 1);
+     *
+     * // Will be 1
+     * console.log(value);
+     * ```
+     *
+     * You can also pass in a function
+     * @example
+     * ```ts
+     * import { Cache } from "@daiso-tech/core/cache";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/adapters";
+     * import { KeyPrefixer } from "@daiso-tech/core/utilities";
+     *
+     * const cache = new Cache({
+     *   adapter: new MemoryCacheAdapter(),
+     *   keyPrefixer: new KeyPrefixer("cache")
+     * });
+     *
+     * const value = await cache.getOr("a", () => 1);
+     *
+     * // Will be 1
+     * console.log(value);
+     * ```
+     *
+     * You can also pass in a async function. This is useful because it allows for retrieval of external data if the key doesnt't.
+     * @example
+     * ```ts
+     * import { Cache } from "@daiso-tech/core/cache";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/adapters";
+     * import { KeyPrefixer } from "@daiso-tech/core/utilities";
+     *
+     * const cache = new Cache({
+     *   adapter: new MemoryCacheAdapter(),
+     *   keyPrefixer: new KeyPrefixer("cache")
+     * });
+     *
+     * const value = await cache.getOr("a", async () => 1);
+     *
+     * // Will be 1
+     * console.log(value);
+     * ```
+     *
+     * You can also pass in a <i>{@link LazyPromise}</i>. This is useful because all other components in this library returns <i>{@link LazyPromise}</i>.
+     * @example
+     * ```ts
+     * import { Cache } from "@daiso-tech/core/cache";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/adapters";
+     * import { KeyPrefixer, LazyPromise } from "@daiso-tech/core/utilities";
+     *
+     * const cache = new Cache({
+     *   adapter: new MemoryCacheAdapter(),
+     *   keyPrefixer: new KeyPrefixer("cache")
+     * });
+     *
+     * const value = await cache.getOr("a", new LazyPromise(async () => 1));
+     *
+     * // Will be 1
+     * console.log(value);
+     * ```
+     */
     getOr(key: OneOrMore<string>, defaultValue: AsyncLazyable<NoneFunction<TType>>): LazyPromise<TType>;
+    /**
+     * @example
+     * ```ts
+     * import { Cache } from "@daiso-tech/core/cache";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/adapters";
+     * import { KeyPrefixer } from "@daiso-tech/core/utilities";
+     *
+     * const cache = new Cache({
+     *   adapter: new MemoryCacheAdapter(),
+     *   keyPrefixer: new KeyPrefixer("cache")
+     * });
+     *
+     * const value = await cache.getOrAdd("a", 1);
+     *
+     * // Will be 1
+     * console.log(value);
+     * ```
+     *
+     * You can also pass in a function
+     * @example
+     * ```ts
+     * import { Cache } from "@daiso-tech/core/cache";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/adapters";
+     * import { KeyPrefixer } from "@daiso-tech/core/utilities";
+     *
+     * const cache = new Cache({
+     *   adapter: new MemoryCacheAdapter(),
+     *   keyPrefixer: new KeyPrefixer("cache")
+     * });
+     *
+     * const value = await cache.getOrAdd("a", () => 1);
+     *
+     * // Will be 1
+     * console.log(value);
+     * ```
+     *
+     * You can also pass in a async function. This is useful because it allows for retrieval of external data if the key doesnt't.
+     * @example
+     * ```ts
+     * import { Cache } from "@daiso-tech/core/cache";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/adapters";
+     * import { KeyPrefixer } from "@daiso-tech/core/utilities";
+     *
+     * const cache = new Cache({
+     *   adapter: new MemoryCacheAdapter(),
+     *   keyPrefixer: new KeyPrefixer("cache")
+     * });
+     *
+     * const value = await cache.getOrAdd("a", async () => 1);
+     *
+     * // Will be 1
+     * console.log(value);
+     * ```
+     *
+     * You can also pass in a <i>{@link LazyPromise}</i>. This is useful because all other components in this library returns <i>{@link LazyPromise}</i>.
+     * @example
+     * ```ts
+     * import { Cache } from "@daiso-tech/core/cache";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/adapters";
+     * import { KeyPrefixer, LazyPromise } from "@daiso-tech/core/utilities";
+     *
+     * const cache = new Cache({
+     *   adapter: new MemoryCacheAdapter(),
+     *   keyPrefixer: new KeyPrefixer("cache")
+     * });
+     *
+     * const value = await cache.getOrAdd("a", new LazyPromise(async () => 1));
+     *
+     * // Will be 1
+     * console.log(value);
+     * ```
+     */
     getOrAdd(key: OneOrMore<string>, valueToAdd: AsyncLazyable<NoneFunction<TType>>, ttl?: TimeSpan | null): LazyPromise<TType>;
     add(key: OneOrMore<string>, value: TType, ttl?: TimeSpan | null): LazyPromise<boolean>;
     put(key: OneOrMore<string>, value: TType, ttl?: TimeSpan | null): LazyPromise<boolean>;
@@ -200,8 +362,51 @@ export declare class Cache<TType = unknown> implements IGroupableCache<TType> {
     increment(key: OneOrMore<string>, value?: Extract<TType, number>): LazyPromise<boolean>;
     decrement(key: OneOrMore<string>, value?: Extract<TType, number>): LazyPromise<boolean>;
     remove(key: OneOrMore<string>): LazyPromise<boolean>;
-    removeMany(keys: OneOrMore<string>[]): LazyPromise<boolean>;
+    removeMany(keys: Iterable<OneOrMore<string>>): LazyPromise<boolean>;
     clear(): LazyPromise<void>;
+    /**
+     * @example
+     * ```ts
+     * import { Cache } from "@daiso-tech/core/cache";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/adapters";
+     * import { KeyPrefixer } from "@daiso-tech/core/utilities";
+     *
+     * const cache = new Cache({
+     *   adapter: new MemoryCacheAdapter(),
+     *   keyPrefixer: new KeyPrefixer("cache")
+     * });
+     *
+     * // Will log null because the cache is not in a group
+     * console.log(cache.getGroup());
+     *
+     * const groupedCache = cache.withGroup("group-a");
+     *
+     * // Will log "group-a" because the groupedCache is in a group
+     * console.log(groupedCache.getGroup());
+     * ```
+     */
     getGroup(): string | null;
+    /**
+     * @example
+     * ```ts
+     * import { Cache } from "@daiso-tech/core/cache";
+     * import { MemoryCacheAdapter } from "@daiso-tech/core/cache/adapters";
+     * import { KeyPrefixer } from "@daiso-tech/core/utilities";
+     *
+     * const cache = new Cache({
+     *   adapter: new MemoryCacheAdapter(),
+     *   keyPrefixer: new KeyPrefixer("cache")
+     * });
+     *
+     * const groupedCache = cache.withGroup("group-a");
+     * await groupedCache.add("a", 1);
+     *
+     * // Will log "a".
+     * console.log(await groupedCache.get("a"));
+     *
+     * // Will log null because the caches are in different groups.
+     * console.log(await cache.get("a"));
+     * ```
+     */
     withGroup(group: OneOrMore<string>): ICache<TType>;
 }