@vercube/storage 0.0.14 → 0.0.15

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { IOC } from "@vercube/di";
+import { S3ClientConfig } from "@aws-sdk/client-s3";
 
 //#region src/Service/Storage.d.ts
 
@@ -13,14 +14,15 @@ import { IOC } from "@vercube/di";
  * It supports basic operations like get, set, delete, and querying storage state.
  * Concrete implementations must provide the actual storage mechanism.
  */
-declare abstract class Storage {
+declare abstract class Storage<T = undefined> {
   /**
-   * Initializes the storage implementation
-   * Must be called before using any other storage operations
-   * @param {unknown} [options] - Optional initialization parameters
-   * @returns {Promise<void>} A promise that resolves when initialization is complete
+   * Initializes the storage implementation.
+   * Must be called before using any other storage operations.
+   *
+   * @param {T} options - Initialization parameters. May be omitted if not required by the storage implementation.
+   * @returns {Promise<void>} A promise that resolves when initialization is complete.
    */
-  abstract initialize(options?: unknown): void | Promise<void>;
+  abstract initialize(options: T): void | Promise<void>;
   /**
    * Retrieves a value from storage by its key
    * @template T - The type of the stored value
@@ -71,13 +73,16 @@ declare namespace StorageTypes {
   interface BaseOptions {
     storage?: string;
   }
-  interface Mount {
+  type Mount<T extends Storage<unknown>> = {
     name?: string;
-    storage: IOC.Newable<Storage>;
+    storage: IOC.Newable<T>;
+  } & (T extends Storage<undefined> ? {
     initOptions?: unknown;
-  }
+  } : T extends Storage<infer U> ? {
+    initOptions: U;
+  } : never);
   interface Storages<T = unknown> {
-    storage: Storage;
+    storage: Storage<T>;
     initOptions?: T;
   }
   interface GetItem extends BaseOptions {
@@ -97,6 +102,9 @@ declare namespace StorageTypes {
   interface GetKeys extends BaseOptions {}
   interface Clear extends BaseOptions {}
   interface Size extends BaseOptions {}
+  interface S3BaseOptions extends S3ClientConfig {
+    bucket: string;
+  }
 }
 //#endregion
 //#region src/Service/StorageManager.d.ts
@@ -119,11 +127,11 @@ declare class StorageManager {
    * @param {IOC.Newable<Storage>} params.storage - Storage implementation to mount
    * @returns {Promise<void>} A promise that resolves when mounting is complete
    */
-  mount({
+  mount<T extends Storage<unknown>>({
     name,
     storage,
     initOptions
-  }: StorageTypes.Mount): Promise<void>;
+  }: StorageTypes.Mount<T>): Promise<void>;
   /**
    * Retrieves a registered storage instance by name
    * @param {string} name - Name of the storage instance to retrieve
@@ -272,4 +280,84 @@ declare class MemoryStorage implements Storage {
   size(): number;
 }
 //#endregion
-export { MemoryStorage, Storage, StorageManager, StorageTypes };
+//#region src/Storages/S3Storage.d.ts
+/**
+* S3 storage implementation of the Storage interface.
+* Provides key-value operations backed by AWS S3.
+*
+* @implements {Storage}
+*/
+declare class S3Storage implements Storage<StorageTypes.S3BaseOptions> {
+  private s3;
+  private bucket;
+  /**
+  * Initializes the S3 storage client.
+  *
+  * @param {StorageTypes.S3BaseOptions} options - Configuration options for the S3 client.
+  * @returns {Promise<void>} A promise that resolves when initialization is complete.
+  */
+  initialize(options: StorageTypes.S3BaseOptions): Promise<void>;
+  /**
+  * Retrieves and parses a value from S3 storage by its key.
+  *
+  * @template T
+  * @param {string} key - The key whose value should be retrieved.
+  * @returns {Promise<T | undefined>} The stored value parsed as type T, or undefined if the key does not exist.
+  * @throws Will rethrow any S3 error except for missing key (`NoSuchKey`).
+  */
+  getItem<T = unknown>(key: string): Promise<T>;
+  /**
+  * Stores a value in S3 storage under the specified key.
+  *
+  * @template T
+  * @template U
+  * @param {string} key - The key under which to store the value.
+  * @param {T} value - The value to store (will be JSON serialized).
+  * @param {U} [options] - Additional options (currently unused).
+  * @returns {Promise<void>} A promise that resolves when the value has been stored.
+  */
+  setItem<T = unknown, U = unknown>(key: string, value: T, options?: U): Promise<void>;
+  /**
+  * Removes an item from S3 storage by its key.
+  *
+  * @param {string} key - The key of the item to delete.
+  * @returns {Promise<void>} A promise that resolves when the item has been deleted.
+  */
+  deleteItem(key: string): Promise<void>;
+  /**
+  * Checks if a key exists in S3 storage.
+  *
+  * @param {string} key - The key to check.
+  * @returns {Promise<boolean>} True if the key exists, false otherwise.
+  * @throws Will rethrow any S3 error except for missing key (`NoSuchKey`).
+  */
+  hasItem(key: string): Promise<boolean>;
+  /**
+  * Retrieves a list of all keys stored in the S3 bucket.
+  *
+  * @returns {Promise<string[]>} An array of all stored keys.
+  */
+  getKeys(): Promise<string[]>;
+  /**
+  * Deletes all items from S3 storage.
+  *
+  * @returns {Promise<void>} A promise that resolves when all items have been deleted.
+  */
+  clear(): Promise<void>;
+  /**
+  * Gets the total number of stored items.
+  *
+  * @returns {Promise<number>} The count of stored items.
+  */
+  size(): Promise<number>;
+  /**
+  * Converts a Node.js readable stream into a UTF-8 string.
+  *
+  * @private
+  * @param {Readable} stream - The readable stream to convert.
+  * @returns {Promise<string>} The stream contents as a string.
+  */
+  private streamToString;
+}
+//#endregion
+export { MemoryStorage, S3Storage, Storage, StorageManager, StorageTypes };