@daiso-tech/core 0.17.4 → 0.19.0

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

@@ -2,7 +2,8 @@
  * @module Cache
  */
 import type { CacheEvents, WithTtlValue } from "../../../cache/contracts/_module";
-import { type ICache } 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";
@@ -15,14 +16,31 @@ import { CacheSettingsBuilder } from "../../../cache/implementations/derivables/
  * @group Derivables
  */
 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 } from "@daiso-tech/core";
+     * 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))
@@ -40,6 +58,9 @@ export declare class Cache<TType = unknown> implements IGroupableCache<TType> {
     private readonly backoffPolicy;
     private readonly retryPolicy;
     private readonly timeout;
+    private readonly serde;
+    private readonly shouldRegisterErrors;
+    private readonly shouldRegisterEvents;
     /**
      *@example
      * ```ts
@@ -49,6 +70,7 @@ export declare class Cache<TType = unknown> implements IGroupableCache<TType> {
      *   adapter: new MemoryEventBusAdapter({ rootGroup: "@global" })
      * });
      * const cache = new Cache({
+     *   serde: new SuperJsonSerde();
      *   adapter: new MemoryCacheAdapter({
      *     rootGroup: "@global"
      *   }),
@@ -57,6 +79,14 @@ export declare class Cache<TType = unknown> implements IGroupableCache<TType> {
      * ```
      */
     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;

package/dist/types/event-bus/contracts/event-bus.errors.d.ts

@@ -1,28 +1,35 @@
 /**
  * @module EventBus
  */
+import type { ISerializable } from "../../serde/contracts/_module";
+import type { ISerializedError } from "../../utilities/_module";
 /**
  * @group Errors
  */
-export declare class EventBusError extends Error {
+export declare class EventBusError extends Error implements ISerializable<ISerializedError> {
+    static deserialize(deserializedValue: ISerializedError): EventBusError;
     constructor(message: string, cause?: unknown);
+    serialize(): ISerializedError;
 }
 /**
  * @group Errors
  */
 export declare class UnexpectedEventBusError extends EventBusError {
+    static deserialize(deserializedValue: ISerializedError): EventBusError;
     constructor(message: string, cause?: unknown);
 }
 /**
  * @group Errors
  */
 export declare class RemoveListenerEventBusError extends UnexpectedEventBusError {
+    static deserialize(deserializedValue: ISerializedError): EventBusError;
     constructor(message: string, cause?: unknown);
 }
 /**
  * @group Errors
  */
 export declare class AddListenerEventBusError extends UnexpectedEventBusError {
+    static deserialize(deserializedValue: ISerializedError): EventBusError;
     constructor(message: string, cause?: unknown);
 }
 /**

package/dist/types/event-bus/implementations/derivables/event-bus-factory-settings.d.ts

@@ -3,7 +3,8 @@
  */
 import type { BackoffPolicy, RetryPolicy } from "../../../async/_module";
 import type { IGroupableEventBus, IEventBusAdapter } from "../../../event-bus/contracts/_module";
-import type { TimeSpan } from "../../../utilities/_module";
+import type { IFlexibleSerde } from "../../../serde/contracts/_module";
+import type { OneOrMore, TimeSpan } from "../../../utilities/_module";
 /**
  * @group Derivables
  */
@@ -13,6 +14,17 @@ export type EventBusAdapters<TAdapters extends string = string> = Partial<Record
  * @group Derivables
  */
 export type EventBusFactorySettings<TAdapters extends string = string> = {
+    /**
+     * You can pass one or more <i>{@link IFlexibleSerde}</i> that will be used to register all <i>{@link IGroupableEventBus}</i> related errors.
+     * @default {true}
+     */
+    serde: OneOrMore<IFlexibleSerde>;
+    /**
+     * If set to true, all <i>{@link IGroupableEventBus}</i> related errors will be registered with the specified <i>IFlexibleSerde</i> during constructor initialization.
+     * This ensures that all <i>{@link IGroupableEventBus}</i> related errors will be serialized correctly.
+     * @default {true}
+     */
+    shouldRegisterErrors?: boolean;
     adapters: EventBusAdapters<TAdapters>;
     defaultAdapter?: NoInfer<TAdapters>;
     /**
@@ -21,18 +33,22 @@ export type EventBusFactorySettings<TAdapters extends string = string> = {
     eventBus?: IGroupableEventBus<any>;
     /**
      * 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;
 };
@@ -43,6 +59,12 @@ export type EventBusFactorySettings<TAdapters extends string = string> = {
 export declare class EventBusFactorySettingsBuilder<TSettings extends EventBusFactorySettings> {
     private readonly settings;
     constructor(settings?: TSettings);
+    setShouldRegisterErrors(shouldRegisterErrors: boolean): EventBusFactorySettingsBuilder<TSettings & {
+        shouldRegisterErrors: boolean;
+    }>;
+    setSerde(serde: OneOrMore<IFlexibleSerde>): EventBusFactorySettingsBuilder<TSettings & {
+        serde: OneOrMore<IFlexibleSerde>;
+    }>;
     setEventBus(eventBus: IGroupableEventBus<any>): EventBusFactorySettingsBuilder<TSettings & {
         eventBus: IGroupableEventBus<any>;
     }>;

package/dist/types/event-bus/implementations/derivables/event-bus-factory.d.ts

@@ -49,12 +49,16 @@ export declare class EventBusFactory<TAdapters extends string = string> implemen
      * ```
      */
     static settings<TAdapters extends string, TSettings extends EventBusFactorySettings<TAdapters>>(): EventBusFactorySettingsBuilder<TSettings>;
+    private readonly eventBuses;
+    private readonly serde;
     private readonly adapters;
     private readonly defaultAdapter?;
     private readonly retryAttempts?;
     private readonly backoffPolicy?;
     private readonly retryPolicy?;
     private readonly timeout?;
+    private readonly shouldRegisterErrors?;
     constructor(settings: EventBusFactorySettings<TAdapters>);
+    private initCaches;
     use<TEvents extends BaseEvent = BaseEvent>(adapterName?: TAdapters | undefined): IGroupableEventBus<TEvents>;
 }

package/dist/types/event-bus/implementations/derivables/event-bus-settings.d.ts

@@ -3,26 +3,42 @@
  */
 import type { BackoffPolicy, RetryPolicy } from "../../../async/_module";
 import { type IGroupableEventBus, type IEventBusAdapter } from "../../../event-bus/contracts/_module";
-import type { IBuildable, TimeSpan } from "../../../utilities/_module";
+import type { IFlexibleSerde } from "../../../serde/contracts/_module";
+import type { IBuildable, OneOrMore, TimeSpan } from "../../../utilities/_module";
 /**
  * @group Derivables
  */
 export type EventBusSettings = {
+    /**
+     * You can pass one or more <i>{@link IFlexibleSerde}</i> that will be used to register all <i>{@link IGroupableEventBus}</i> related errors.
+     * @default {true}
+     */
+    serde: OneOrMore<IFlexibleSerde>;
+    /**
+     * If set to true, all <i>{@link IGroupableEventBus}</i> related errors will be registered with the specified <i>IFlexibleSerde</i> during constructor initialization.
+     * This ensures that all <i>{@link IGroupableEventBus}</i> related errors will be serialized correctly.
+     * @default {true}
+     */
+    shouldRegisterErrors?: boolean;
     adapter: IEventBusAdapter;
     /**
      * 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;
 };
@@ -33,6 +49,12 @@ export type EventBusSettings = {
 export declare class EventBusSettingsBuilder<TSettings extends Partial<EventBusSettings>> implements IBuildable<EventBusSettings> {
     private readonly settings;
     constructor(settings?: TSettings);
+    setShouldRegisterErrors(shouldRegisterErrors: boolean): EventBusSettingsBuilder<TSettings & {
+        shouldRegisterErrors: boolean;
+    }>;
+    setSerde(serde: OneOrMore<IFlexibleSerde>): EventBusSettingsBuilder<TSettings & {
+        serde: OneOrMore<IFlexibleSerde>;
+    }>;
     setAdapter(adapter: IEventBusAdapter): EventBusSettingsBuilder<TSettings & {
         adapter: IEventBusAdapter;
     }>;

package/dist/types/event-bus/implementations/derivables/event-bus.d.ts

@@ -3,7 +3,7 @@
  */
 import { LazyPromise } from "../../../async/_module";
 import type { EventClass, EventInstance, Unsubscribe } from "../../../event-bus/contracts/_module";
-import { type IEventBus, type IGroupableEventBus, type Listener, type BaseEvent } from "../../../event-bus/contracts/_module";
+import { type IEventBus, type IGroupableEventBus, type Listener, type BaseEvent, RemoveListenerEventBusError, AddListenerEventBusError, UnexpectedEventBusError, EventBusError } from "../../../event-bus/contracts/_module";
 import type { OneOrMore } from "../../../utilities/_module";
 import type { EventBusSettings } from "../../../event-bus/implementations/derivables/event-bus-settings";
 import { EventBusSettingsBuilder } from "../../../event-bus/implementations/derivables/event-bus-settings";
@@ -12,6 +12,12 @@ import { EventBusSettingsBuilder } from "../../../event-bus/implementations/deri
  * @group Derivables
  */
 export declare class EventBus<TEvents extends BaseEvent = BaseEvent> implements IGroupableEventBus<TEvents> {
+    static readonly errors: {
+        readonly Error: typeof EventBusError;
+        readonly Unexpected: typeof UnexpectedEventBusError;
+        readonly RemoveListener: typeof RemoveListenerEventBusError;
+        readonly AddListener: typeof AddListenerEventBusError;
+    };
     /**
      * @example
      * ```ts
@@ -26,12 +32,18 @@ export declare class EventBus<TEvents extends BaseEvent = BaseEvent> implements
      * ```
      */
     static settings<TSettings extends Partial<EventBusSettings>>(): EventBusSettingsBuilder<TSettings>;
+    private readonly serde;
     private readonly adapter;
     private readonly retryAttempts;
     private readonly backoffPolicy;
     private readonly retryPolicy;
     private readonly timeout;
+    private readonly shouldRegisterErrors;
     constructor(settings: EventBusSettings);
+    /**
+     * Registers all event bus related error within the given <i>IFlexibleSerde</i> contract.
+     */
+    private registerErrors;
     private createLayPromise;
     withGroup(group: OneOrMore<string>): IEventBus<TEvents>;
     getGroup(): string;

package/dist/types/serde/contracts/flexible-serde.contract.d.ts

@@ -11,6 +11,20 @@ export type SerializableClass<TSerializedValue> = {
     new (...arguments_: any[]): ISerializable<TSerializedValue>;
     deserialize(serializedValue: TSerializedValue): ISerializable<TSerializedValue>;
 };
+/**
+ * The <i>SerializableClass</i> contract defines standard way to make a error class instance serializable and deserializable.
+ * @group Contracts
+ */
+export type ErrorClass = new (...args: any[]) => Error;
+/**
+ * @group Contracts
+ */
+export type ISerdeTransformer<TDeserializedValue, TSerializedValue> = {
+    name: string;
+    isApplicable(value: unknown): value is TDeserializedValue;
+    deserialize(serializedValue: TSerializedValue): TDeserializedValue;
+    serialize(deserializedValue: TDeserializedValue): TSerializedValue;
+};
 /**
  * The <i>IFlexibleSerde</i> contract defines a standard way to serialize and deserialize both plain data and custom classes.
  * @group Contracts
@@ -49,8 +63,58 @@ export type IFlexibleSerde<TSerializedValue = unknown> = ISerde<TSerializedValue
      *   console.log(user.getInfo());
      *   // "name: Jacob, age: 50"
      * }
-     *
      * ```
      */
     registerClass<TSerializedClassInstance>(class_: SerializableClass<TSerializedClassInstance>): IFlexibleSerde<TSerializedValue>;
+    /**
+     * The <i>registerCustom</i> method is used for registering custom values for serialization and deserialization.
+     * @example
+     * ```ts
+     * import type { IFlexibleSerde, ISerdeTransformer } from "@daiso-tech/core";
+     *
+     * type SerializedUser = {
+     *   name: string;
+     *   age: number;
+     * };
+     *
+     * class User implements ISerializable<SerializedUser> {
+     *   static deserialize(serializedUser: SerializedUser): User {
+     *     return new User(serializedUser.name, serializedUser.age);
+     *   }
+     *
+     *   constructor(public readonly name: string, public readonly age: number) {}
+     *
+     *   getInfo(): string {
+     *     return `name: ${this.name}, age: ${this.age}`;
+     *   }
+     * }
+     *
+     * const transformer: ISerdeTransformer<User, SerializedUser> = {
+     *   name: User.name,
+     *   isApplicable(value): value is User {
+     *     return (
+     *       value instanceof User &&
+     *       value.constructor.name === User.name
+     *     );
+     *   },
+     *   deserialize(serializedValue) {
+     *     return User.deserialize(serializedValue);
+     *   },
+     *   serialize(deserializedValue) {
+     *     return deserializedValue.serialize();
+     *   }
+     * }
+     *
+     * function main(serde: IFlexibleSerde) {
+     *   // You must register the transformer is it will get applied.
+     *   serde.registerCustom(transformer);
+     *
+     *   const user = serde.deserialize(serde.serialize(new User("Jacob", 50)));
+     *
+     *   console.log(user.getInfo());
+     *   // "name: Jacob, age: 50"
+     * }
+     * ```
+     */
+    registerCustom<TCustomSerialized, TCustomDeserialized>(transformer: ISerdeTransformer<TCustomSerialized, TCustomDeserialized>): IFlexibleSerde<TSerializedValue>;
 };

package/dist/types/serde/implementations/no-op-serde/no-op-serde.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module EventBus
  */
-import type { IFlexibleSerde, SerializableClass } from "../../../serde/contracts/_module";
+import type { IFlexibleSerde, ISerdeTransformer, SerializableClass } from "../../../serde/contracts/_module";
 /**
  * This <i>NoOpSerde</i> will do nothing and is used for easily mocking {@link IFlexibleSerde} or {@link ISerde} for testing.
  * @group Adapters
@@ -10,4 +10,5 @@ export declare class NoOpSerde<TSerializedValue> implements IFlexibleSerde<TSeri
     serialize<TValue>(value: TValue): TSerializedValue;
     deserialize<TValue>(serializedValue: TSerializedValue): TValue;
     registerClass<TSerializedClassInstance>(_class: SerializableClass<TSerializedClassInstance>): IFlexibleSerde<TSerializedValue>;
+    registerCustom<TCustomSerialized, TCustomDeserialized>(_transformer: ISerdeTransformer<TCustomSerialized, TCustomDeserialized>): IFlexibleSerde<TSerializedValue>;
 }

package/dist/types/serde/implementations/super-json-serde/super-json-serde.d.ts

@@ -1,14 +1,35 @@
 /**
  * @module Serde
  */
-import type { SerializableClass } from "../../../serde/contracts/_module";
+import type { ISerdeTransformer, SerializableClass } from "../../../serde/contracts/_module";
 import { type IFlexibleSerde } from "../../../serde/contracts/_module";
 /**
+ * The <i>SuperJsonSerde</i> class has direct support for the following values
+ * - String
+ * - Number
+ * - Boolean
+ * - Null,
+ * - Arrays
+ * - Object literals
+ * - Date
+ * - Map
+ * - Set
+ * - BigInt
+ * - Buffer
+ * - Uint8Array
+ * - Int8Array
+ * - Uint16Array
+ * - Int16Array
+ * - Uint32Array
+ * - Int32Array
+ * - Float32Array
+ * - Float64Array
  * @group Adapters
  */
 export declare class SuperJsonSerde implements IFlexibleSerde<string> {
     private readonly superJson;
     constructor();
+    registerCustom<TCustomSerialized, TCustomDeserialized>(transformer: ISerdeTransformer<TCustomSerialized, TCustomDeserialized>): IFlexibleSerde<string>;
     private registerBuffer;
     private registerUint8Array;
     private registerInt8Array;

package/dist/types/utilities/contracts/_module.d.ts

@@ -1,3 +1,4 @@
+export * from "../../utilities/contracts/serialized-error.contract";
 export * from "../../utilities/contracts/buildable.contract";
 export * from "../../utilities/contracts/deinitizable.contract";
 export * from "../../utilities/contracts/initizable.contract";

package/dist/types/utilities/contracts/serialized-error.contract.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @module Utilities
+ */
+/**
+ * @group Contracts
+ */
+export type ISerializedError = {
+    name: string;
+    message: string;
+    cause?: unknown;
+};

package/dist/types/utilities/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module Utilities
  */
-export type OneOrMore<TItem> = TItem | TItem[];
+export type OneOrMore<TItem> = TItem | [TItem, ...TItem[]];
 export type Lazyable<TValue> = TValue | (() => TValue);
 export type Promisable<TValue> = TValue | PromiseLike<TValue>;
 export type AsyncLazyable<TValue> = TValue | (() => Promisable<TValue>);

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@daiso-tech/core",
     "private": false,
-    "version": "0.17.4",
+    "version": "0.19.0",
     "author": "Yousif Abdulkarim",
     "license": "Apache-2.0",
     "main": "./dist/cjs/_module.js",