@daiso-tech/core 0.8.0 → 0.9.0

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

@@ -5,127 +5,109 @@ import type { IListenable } from "../../event-bus/contracts/_module";
 import { type AnyFunction, type AsyncLazyable, type GetOrAddValue } from "../../_shared/types";
 import type { AllStorageEvents } from "../../storage/contracts/_module";
 export type StorageValue<T> = Exclude<T, AnyFunction | undefined | null>;
+/**
+ * The <i>IStorageListenable</i> contract defines a way for listening <i>{@link IStorage}</i> crud operations.
+ */
+export type IStorageListenable<TType = unknown> = IListenable<AllStorageEvents<TType>>;
 /**
  * The <i>IStorage</i> contract defines a way for storing data as key-value pairs independent of storage.
  * It commes with more convient methods compared to <i>IStorageAdapter</i>.
- * @throws {StorageError} {@link StorageError}
- * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
- * @throws {TypeStorageError} {@link TypeStorageError}
  * @group Contracts
  */
-export type IStorage<TType = unknown> = IListenable<AllStorageEvents<TType>> & {
+export type IStorage<TType = unknown> = IStorageListenable & {
     /**
      * The <i>exists</i> method returns true when <i>key</i> is found otherwise false will be returned.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     exists(key: string): PromiseLike<boolean>;
     /**
      * The <i>existsMany</i> method returns true for the <i>keys</i> that are found otherwise false will be returned.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     existsMany<TKeys extends string>(keys: TKeys[]): PromiseLike<Record<TKeys, boolean>>;
     /**
      * The <i>missing</i> method returns true when <i>key</i> is not found otherwise false will be returned.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     missing(key: string): PromiseLike<boolean>;
     /**
      * The <i>missingMany</i> method returns true for the <i>keys</i> that are not found otherwise false will be returned.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     missingMany<TKeys extends string>(keys: TKeys[]): PromiseLike<Record<TKeys, boolean>>;
     /**
      * The <i>get</i> method returns the value when <i>key</i> is found otherwise null will be returned.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     get(key: string): PromiseLike<TType | null>;
     /**
      * The <i>getMany</i> returns the value for the <i>keys</i> that are found otherwise null will be returned.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     getMany<TKeys extends string>(keys: TKeys[]): PromiseLike<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.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     getOr(key: string, defaultValue: AsyncLazyable<TType>): PromiseLike<TType>;
     /**
      * The <i>getOrMany</i> method returns the value for the keys that are found otherwise defaultValue will be returned.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     getOrMany<TKeys extends string>(keysWithDefaults: Record<TKeys, AsyncLazyable<TType>>): PromiseLike<Record<TKeys, TType>>;
     /**
      * The <i>getOrFail</i> method returns the value when <i>key</i> is found otherwise an error will be thrown.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      * @throws {KeyNotFoundStorageError} {@link KeyNotFoundStorageError}
      */
     getOrFail(key: string): PromiseLike<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.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     add(key: string, value: StorageValue<TType>): PromiseLike<boolean>;
     /**
      * The <i>addMany</i> method adds the keys that doesn't exists. Returns true for the keys that doesn't exists otherwise false will be returned.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     addMany<TKeys extends string>(values: Record<TKeys, StorageValue<TType>>): PromiseLike<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.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     update(key: string, value: TType): PromiseLike<boolean>;
     /**
      * The <i>updateMany</i> method updates the given keys. Returns true for the keys that exists otherwise false will be returned.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     updateMany<TKeys extends string>(values: Record<TKeys, TType>): PromiseLike<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.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     put(key: string, value: StorageValue<TType>): PromiseLike<boolean>;
     /**
      * The <i>putMany</i> method replaces the keys that are found. Adds keys that are not found. Returns true for all the keys that are found otherwise false is returned.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     putMany<TKeys extends string>(values: Record<TKeys, StorageValue<TType>>): PromiseLike<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.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     remove(key: string): PromiseLike<boolean>;
     /**
      * The <i>removesMany</i> method removes the keys that are found. Returns true for the keys that are found otherwise false is returned.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     removeMany<TKeys extends string>(keys: TKeys[]): PromiseLike<Record<TKeys, boolean>>;
     /**
      * The <i>getAndRemove</i> method removes the given <i>key</i> and returns it when found otherwise null will be returned.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     getAndRemove(key: string): PromiseLike<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.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     getOrAdd(key: string, valueToAdd: AsyncLazyable<StorageValue<GetOrAddValue<TType>>>): PromiseLike<TType>;
@@ -133,7 +115,6 @@ export type IStorage<TType = unknown> = IListenable<AllStorageEvents<TType>> & {
      * The <i>increment</i> method will increment the given <i>key</i> if found otherwise nonthing will occur.
      * Returns true if key exists otherwise false will be returned.
      * An error will thrown if the key is not a number.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      * @throws {TypeStorageError} {@link TypeStorageError}
      */
@@ -142,7 +123,6 @@ export type IStorage<TType = unknown> = IListenable<AllStorageEvents<TType>> & {
      * The <i>decrement</i> method will decrement the given <i>key</i> if found otherwise nonthing will occur.
      * Returns true if key exists otherwise false will be returned.
      * An error will thrown if the key is not a number.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      * @throws {TypeStorageError} {@link TypeStorageError}
      * An error will thrown if the key is not a number.
@@ -150,27 +130,55 @@ export type IStorage<TType = unknown> = IListenable<AllStorageEvents<TType>> & {
     decrement(key: string, value?: Extract<TType, number>): PromiseLike<boolean>;
     /**
      * The <i>clear</i> method removes all the keys in the storage.
-     * @throws {StorageError} {@link StorageError}
      * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
      */
     clear(): PromiseLike<void>;
+    /**
+     * The <i>getNamespace</i> method return the complete namespace.
+     * @example
+     * ```ts
+     *   const storage = new Storage(new MemoryStorageAdapter(), {
+     *     rootNamespace: "@root/"
+     *   });
+     *
+     *   // Will be "@root/"
+     *   console.log(storage.getNamespace())
+     *
+     *   const storageA = storage.withNamespace("a/");
+     *
+     *   // Will be "@root/a/"
+     *   console.log(storageA.getNamespace())
+     * ```
+     */
+    getNamespace(): string;
 };
 /**
  * The <i>INamespacedStorage</i> contract defines a way for storing data as key-value pairs independent of storage.
  * It commes with one extra method which is useful for multitennat applications compared to <i>IStorage</i>.
- * @throws {StorageError} {@link StorageError}
- * @throws {UnexpectedStorageError} {@link UnexpectedStorageError}
- * @throws {TypeStorageError} {@link TypeStorageError}
  * @group Contracts
  */
 export type INamespacedStorage<TType = unknown> = IStorage<TType> & {
     /**
      * The <i>withNamespace</i> method returns new instance of <i>{@link IStorage}</i> where all the keys will be prefixed with a given <i>namespace</i>.
      * This useful for multitennat applications.
+     * @example
+     * ```ts
+     * import { Storage, MemoryStorageAdapter } from "@daiso-tech/core";
+     *
+     * (async () => {
+     *   const storage = new Storage(new MemoryStorageAdapter());
+     *
+     *   const storageA = storage.withNamespace("a");
+     *   await storageA.add("a", 1);
+     *
+     *   const storageB = storage.withNamespace("b");
+     *   await storageB.add("b", 2);
+     *
+     *   // Will print { a: 1, b: null }
+     *   console.log(await storageA.getMany(["a", "b"]));
+     * })();
+     *
+     * ```
      */
     withNamespace(namespace: string): IStorage<TType>;
-    /**
-     * The <i>getNamespace</i> method return the complete namespace.
-     */
-    getNamespace(): string;
 };

package/dist/types/storage/implementations/_shared/test-utilities/storage-adapter.test-suite.d.ts

@@ -12,9 +12,25 @@ export type StorageAdapterTestSuiteSettings = {
     test: TestAPI;
     describe: SuiteAPI;
     beforeEach: typeof beforeEach;
-    createAdapter: () => Promisable<IStorageAdapter<unknown>>;
+    createAdapter: () => Promisable<IStorageAdapter>;
 };
 /**
+ * The <i>storageAdapterTestSuite</i> function simplifies the process of testing your custom implementation of <i>{@link IStorageAdapter}</i>.
+ * @example
+ * ```ts
+ * import { storageAdapterTestSuite, MemoryStorageAdapter } from "@daiso-tech/core";
+ * import { expext, test, describe, beforeEach } from "vitest";
+ *
+ * describe("class: MemoryStorageAdapter", () => {
+ *   storageAdapterTestSuite({
+ *     createAdapter: () => new MemoryStorageAdapter(),
+ *     test,
+ *     beforeEach,
+ *     expect,
+ *     describe,
+ *   });
+ * });
+ * ```
  * @group Utilities
  */
-export declare function storageTestSuite(settings: StorageAdapterTestSuiteSettings): void;
+export declare function storageAdapterTestSuite(settings: StorageAdapterTestSuiteSettings): void;

package/dist/types/storage/implementations/storage/storage-manager.d.ts

@@ -1,23 +1,29 @@
 /**
  * @module Storage
  */
-import type { INamespacedStorage, IStorageAdapter, IStorageManager, StorageManagerUseSettings } from "../../../storage/contracts/_module";
-import { type StorageSettings } from "../../../storage/implementations/storage/storage";
+import type { INamespacedEventBus } from "../../../event-bus/contracts/_module";
+import type { IStorageFactory, INamespacedStorage, IStorageAdapter, IStorageManager } from "../../../storage/contracts/_module";
+import type { Validator } from "../../../utilities/_module";
 /**
  * @group Derivables
  */
 export type StorageManagerSettings<TAdapters extends string = string> = {
     adapters: Record<TAdapters, IStorageAdapter<any>>;
     defaultAdapter: NoInfer<TAdapters>;
-    adapterSettings?: Omit<StorageSettings<any>, "validator">;
+    rootNamespace: string;
+    eventBus?: INamespacedEventBus<any>;
 };
 /**
  * @group Derivables
  */
-export declare class StorageManager<TAdapters extends string = string> implements IStorageManager<TAdapters> {
+export declare class StorageManager<TAdapters extends string = string, TType = unknown> implements IStorageManager<TAdapters, TType> {
     private readonly adapters;
     private readonly defaultAdapter;
-    private readonly adapterSettings;
+    private readonly rootNamespace;
+    private readonly eventBus?;
+    private validator;
     constructor(settings: StorageManagerSettings<TAdapters>);
-    use<TType>(adapterSettings?: StorageManagerUseSettings<TType, TAdapters>): INamespacedStorage<TType>;
+    use(adapter?: TAdapters): INamespacedStorage<TType>;
+    withValidation<TOutput extends TType = TType>(validator: Validator<TOutput>): IStorageFactory<TAdapters, TOutput>;
+    withType<TOutput extends TType = TType>(): IStorageFactory<TAdapters, TOutput>;
 }

package/dist/types/storage/implementations/storage/with-event-storage-adapter.d.ts

@@ -3,7 +3,7 @@
  */
 import type { StorageEvent } from "../../../storage/contracts/_module";
 import { type IStorageAdapter, type AllStorageEvents } from "../../../storage/contracts/_module";
-import type { IEventBus } from "../../../event-bus/contracts/_module";
+import { type IEventBus } from "../../../event-bus/contracts/_module";
 import type { WithNamespaceStorageAdapter } from "../../../storage/implementations/storage/with-namespace-storage-adapter";
 /**
  * @internal

package/package.json

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