@daiso-tech/core 0.16.0 → 0.19.0

package/dist/types/cache/implementations/derivables/cache-settings.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @module Cache
+ */
+import type { ICacheAdapter } from "../../../cache/contracts/_module";
+import type { IBuildable, OneOrMore } from "../../../utilities/_module";
+import type { TimeSpan } from "../../../utilities/_module";
+import type { BackoffPolicy, RetryPolicy } from "../../../async/_module";
+import type { IGroupableEventBus } from "../../../event-bus/contracts/_module";
+import type { IFlexibleSerde } from "../../../serde/contracts/_module";
+/**
+ * @group Derivables
+ */
+export type CacheSettings = {
+    /**
+     * You can pass one or more <i>{@link IFlexibleSerde}</i> that will be used to register all <i>{@link IGroupableCache}</i> related errors and events.
+     * @default {true}
+     */
+    serde: OneOrMore<IFlexibleSerde>;
+    /**
+     * If set to true, all <i>{@link IGroupableCache}</i> related errors will be registered with the specified <i>IFlexibleSerde</i> during constructor initialization.
+     * This ensures that all <i>{@link IGroupableCache}</i> related errors will be serialized correctly.
+     * @default {true}
+     */
+    shouldRegisterErrors?: boolean;
+    /**
+     * If set to true, all <i>{@link IGroupableCache}</i> related events will be registered with the specified <i>IFlexibleSerde</i> during constructor initialization.
+     * This ensures that all <i>{@link IGroupableCache}</i> related events will be serialized correctly.
+     * @default {true}
+     */
+    shouldRegisterEvents?: boolean;
+    adapter: ICacheAdapter<any>;
+    /**
+     * In order to listen to events of <i>{@link Cache}</i> class you must pass in <i>{@link IGroupableEventBus}</i>.
+     */
+    eventBus?: IGroupableEventBus<any>;
+    /**
+     * You can decide the default ttl value. If null is passed then no ttl will be used by default.
+     * @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;
+};
+/**
+ * The <i>CacheSettingsBuilder</i> is an immutable builder class, meaning that each method invocation creates a new instance.
+ * @group Derivables
+ */
+export declare class CacheSettingsBuilder<TSettings extends Partial<CacheSettings>> implements IBuildable<CacheSettings> {
+    private readonly settings;
+    constructor(settings?: TSettings);
+    setShouldRegisterErrors(shouldRegisterErrors: boolean): CacheSettingsBuilder<TSettings & {
+        shouldRegisterErrors: boolean;
+    }>;
+    setShouldRegisterEvents(shouldRegisterEvents: boolean): CacheSettingsBuilder<TSettings & {
+        shouldRegisterEvents: boolean;
+    }>;
+    setSerde(serde: OneOrMore<IFlexibleSerde>): CacheSettingsBuilder<TSettings & {
+        serde: OneOrMore<IFlexibleSerde>;
+    }>;
+    setAdapter(adapter: ICacheAdapter<any>): CacheSettingsBuilder<TSettings & {
+        adapter: ICacheAdapter<any>;
+    }>;
+    setEventBus(eventBus: IGroupableEventBus<any>): CacheSettingsBuilder<TSettings & {
+        eventBus: IGroupableEventBus<any>;
+    }>;
+    setDefultTtl(time: TimeSpan): CacheSettingsBuilder<TSettings & {
+        defaultTtl: TimeSpan;
+    }>;
+    setRetryAttempts(attempts: number | null): CacheSettingsBuilder<TSettings & {
+        retryAttempts: number | null;
+    }>;
+    setBackoffPolicy(policy: BackoffPolicy | null): CacheSettingsBuilder<TSettings & {
+        backoffPolicy: BackoffPolicy | null;
+    }>;
+    setRetryPolicy(policy: RetryPolicy | null): CacheSettingsBuilder<TSettings & {
+        retryPolicy: RetryPolicy | null;
+    }>;
+    setTimeout(time: TimeSpan | null): CacheSettingsBuilder<TSettings & {
+        timeout: TimeSpan | null;
+    }>;
+    build(this: CacheSettingsBuilder<CacheSettings>): CacheSettings;
+}

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

@@ -2,44 +2,91 @@
  * @module Cache
  */
 import type { CacheEvents, WithTtlValue } from "../../../cache/contracts/_module";
-import { type ICache, type ICacheAdapter } from "../../../cache/contracts/_module";
+import { KeyFoundCacheEvent, KeyNotFoundCacheEvent, KeyAddedCacheEvent, KeyUpdatedCacheEvent, KeyRemovedCacheEvent, KeyIncrementedCacheEvent, KeyDecrementedCacheEvent, KeysClearedCacheEvent, type ICache } from "../../../cache/contracts/_module";
+import { CacheError, KeyNotFoundCacheError, TypeCacheError, UnexpectedCacheError } from "../../../cache/contracts/_module";
 import { type IGroupableCache } from "../../../cache/contracts/_module";
 import type { AsyncLazyable, GetOrAddValue, OneOrMore } from "../../../utilities/_module";
 import type { TimeSpan } from "../../../utilities/_module";
-import type { LazyPromiseSettings } from "../../../async/_module";
 import { LazyPromise } from "../../../async/_module";
-import type { IGroupableEventBus, Listener, SelectEvent, Unsubscribe } from "../../../event-bus/contracts/_module";
-/**
- * @group Derivables
- */
-export type CacheSettings<TType> = {
-    /**
-     * In order to listen to events of <i>{@link Cache}</i> class you must pass in <i>{@link IGroupableEventBus}</i>.
-     */
-    eventBus?: IGroupableEventBus<CacheEvents<TType>>;
-    /**
-     * You can decide the default ttl value. If null is passed then no ttl will be used by default.
-     */
-    defaultTtl?: TimeSpan | null;
-    lazyPromiseSettings?: LazyPromiseSettings;
-};
+import type { Listener, Unsubscribe, EventClass, EventInstance } from "../../../event-bus/contracts/_module";
+import type { CacheSettings } from "../../../cache/implementations/derivables/cache-settings";
+import { CacheSettingsBuilder } from "../../../cache/implementations/derivables/cache-settings";
 /**
  * <i>Cache</i> class can be derived from any <i>{@link ICacheAdapter}</i>.
  * @group Derivables
- * @example
- * ```ts
- * import { Cache, MemoryCacheAdapter } from "@daiso-tech/core";
- *
- * const cache = new Cache(new MemoryCacheAdapter());
- * ```
  */
 export declare class Cache<TType = unknown> implements IGroupableCache<TType> {
+    static readonly errors: {
+        readonly Error: typeof CacheError;
+        readonly Unexpected: typeof UnexpectedCacheError;
+        readonly Type: typeof TypeCacheError;
+        readonly KeyNotFound: typeof KeyNotFoundCacheError;
+    };
+    static readonly events: {
+        readonly KeyFound: typeof KeyFoundCacheEvent;
+        readonly KeyNotFound: typeof KeyNotFoundCacheEvent;
+        readonly KeyAdded: typeof KeyAddedCacheEvent;
+        readonly KeyUpdated: typeof KeyUpdatedCacheEvent;
+        readonly KeyRemoved: typeof KeyRemovedCacheEvent;
+        readonly KeyIncremented: typeof KeyIncrementedCacheEvent;
+        readonly KeyDecremented: typeof KeyDecrementedCacheEvent;
+        readonly KeysCleared: typeof KeysClearedCacheEvent;
+    };
+    /**
+     * @example
+     * ```ts
+     * import { Cache, MemoryCacheAdapter, TimeSpan, SuperJsonSerde } from "@daiso-tech/core";
+     *
+     * const cache = new Cache(
+     *   Cache
+     *     .settings()
+     *     .setSerde(new SuperJsonSerde())
+     *     .setAdapter(new MemoryCacheAdapter({ rootGroup: "@global" }))
+     *     .setEventBus(new EventBus(new MemoryEventBusAdapter({ rootGroup: "@global" })))
+     *     .setDefaultTtl(TimeSpan.fromMinutes(2))
+     *     .build()
+     * );
+     * ```
+     */
+    static settings<TSettings extends Partial<CacheSettings>>(): CacheSettingsBuilder<TSettings>;
+    private static defaultRetryPolicy;
     private readonly groupdEventBus;
     private readonly eventBus;
-    private readonly cacheAdapter;
+    private readonly adapter;
     private readonly defaultTtl;
-    private readonly lazyPromiseSettings?;
-    constructor(cacheAdapter: ICacheAdapter<any>, settings?: CacheSettings<TType>);
+    private readonly retryAttempts;
+    private readonly backoffPolicy;
+    private readonly retryPolicy;
+    private readonly timeout;
+    private readonly serde;
+    private readonly shouldRegisterErrors;
+    private readonly shouldRegisterEvents;
+    /**
+     *@example
+     * ```ts
+     * import { Cache, MemoryCacheAdapter, EventBus, MemoryEventBusAdapter } from "@daiso-tech/core";
+     *
+     * const eventBus = new EventBus({
+     *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
+     * });
+     * const cache = new Cache({
+     *   serde: new SuperJsonSerde();
+     *   adapter: new MemoryCacheAdapter({
+     *     rootGroup: "@global"
+     *   }),
+     *   eventBus,
+     * });
+     * ```
+     */
+    constructor(settings: CacheSettings);
+    /**
+     * Registers all cache-related events within the given <i>IFlexibleSerde</i> contract.
+     */
+    private registerEvents;
+    /**
+     * Registers all cache-related error within the given <i>IFlexibleSerde</i> contract.
+     */
+    private registerErrors;
     private createLayPromise;
     private createKeyFoundEvent;
     private createKeyNotFoundEvent;
@@ -49,22 +96,30 @@ export declare class Cache<TType = unknown> implements IGroupableCache<TType> {
     private createKeysClearedEvent;
     private createKeyIncrementedEvent;
     private createKeyDecrementedEvent;
+    addListener<TEventClass extends EventClass<CacheEvents>>(eventName: TEventClass, listener: Listener<EventInstance<TEventClass>>): LazyPromise<void>;
+    addListenerMany<TEventClass extends EventClass<CacheEvents>>(eventNames: TEventClass[], listener: Listener<EventInstance<TEventClass>>): LazyPromise<void>;
+    removeListener<TEventClass extends EventClass<CacheEvents>>(eventName: TEventClass, listener: Listener<EventInstance<TEventClass>>): LazyPromise<void>;
+    removeListenerMany<TEventClass extends EventClass<CacheEvents>>(eventNames: TEventClass[], listener: Listener<EventInstance<TEventClass>>): LazyPromise<void>;
+    listenOnce<TEventClass extends EventClass<CacheEvents>>(eventName: TEventClass, listener: Listener<EventInstance<TEventClass>>): LazyPromise<void>;
+    subscribe<TEventClass extends EventClass<CacheEvents>>(eventName: TEventClass, listener: Listener<EventInstance<TEventClass>>): LazyPromise<Unsubscribe>;
+    subscribeMany<TEventClass extends EventClass<CacheEvents>>(eventNames: TEventClass[], listener: Listener<EventInstance<TEventClass>>): LazyPromise<Unsubscribe>;
     withGroup(group: OneOrMore<string>): ICache<TType>;
     getGroup(): string;
     get(key: string): LazyPromise<TType | null>;
-    add(key: string, value: TType, ttl?: TimeSpan | null): LazyPromise<boolean>;
+    add(key: string, value: TType, 
+    /**
+     * @default null
+     */
+    ttl?: TimeSpan | null): LazyPromise<boolean>;
     update(key: string, value: TType): LazyPromise<boolean>;
-    put(key: string, value: TType, ttl?: TimeSpan | null): LazyPromise<boolean>;
+    put(key: string, value: TType, 
+    /**
+     * @default null
+     */
+    ttl?: TimeSpan | null): LazyPromise<boolean>;
     remove(key: string): LazyPromise<boolean>;
     increment(key: string, value?: Extract<TType, number>): LazyPromise<boolean>;
     clear(): LazyPromise<void>;
-    addListener<TEventName extends keyof CacheEvents>(eventName: TEventName, listener: Listener<SelectEvent<CacheEvents, TEventName>>): LazyPromise<void>;
-    addListenerMany<TEventName extends keyof CacheEvents>(eventNames: TEventName[], listener: Listener<SelectEvent<CacheEvents, TEventName>>): LazyPromise<void>;
-    removeListener<TEventName extends keyof CacheEvents>(eventName: TEventName, listener: Listener<SelectEvent<CacheEvents, TEventName>>): LazyPromise<void>;
-    removeListenerMany<TEventName extends keyof CacheEvents>(eventNames: TEventName[], listener: Listener<SelectEvent<CacheEvents, TEventName>>): LazyPromise<void>;
-    listenOnce<TEventName extends keyof CacheEvents>(eventName: TEventName, listener: Listener<SelectEvent<CacheEvents, TEventName>>): LazyPromise<void>;
-    subscribe<TEventName extends keyof CacheEvents>(eventName: TEventName, listener: Listener<SelectEvent<CacheEvents, TEventName>>): LazyPromise<Unsubscribe>;
-    subscribeMany<TEventName extends keyof CacheEvents>(eventNames: TEventName[], listener: Listener<SelectEvent<CacheEvents, TEventName>>): LazyPromise<Unsubscribe>;
     exists(key: string): LazyPromise<boolean>;
     existsMany<TKeys extends string>(keys: TKeys[]): LazyPromise<Record<TKeys, boolean>>;
     missing(key: string): LazyPromise<boolean>;
@@ -78,6 +133,10 @@ export declare class Cache<TType = unknown> implements IGroupableCache<TType> {
     putMany<TKeys extends string>(values: Record<TKeys, WithTtlValue<TType>>): LazyPromise<Record<TKeys, boolean>>;
     removeMany<TKeys extends string>(keys: TKeys[]): LazyPromise<Record<TKeys, boolean>>;
     getAndRemove(key: string): LazyPromise<TType | null>;
-    getOrAdd(key: string, valueToAdd: AsyncLazyable<GetOrAddValue<TType>>, ttl?: TimeSpan): LazyPromise<TType>;
+    getOrAdd(key: string, valueToAdd: AsyncLazyable<GetOrAddValue<TType>>, 
+    /**
+     * @default {null}
+     */
+    ttl?: TimeSpan): LazyPromise<TType>;
     decrement(key: string, value?: Extract<TType, number>): LazyPromise<boolean>;
 }