/**
 * Generic storage interface contract.
 *
 * All storage implementations (localStorage, IndexedDB) must
 * conform to this interface. Methods use generics to enforce
 * type-safe serialization/deserialization at the consumer level.
 *
 * @example
 * ```ts
 * const user = await storage.getItem<UserProfile>(StorageKey.USER_PROFILE);
 * ```
 */
export interface IStorageService {
  /**
   * Persist a value under the given key.
   * The value is JSON-serialized before storage.
   * If encryption is enabled, the serialized payload is encrypted at rest.
   */
  setItem<T>(key: string, value: T): Promise<void>;

  /**
   * Retrieve and deserialize a value by key.
   * Returns `null` if the key does not exist or decryption/parsing fails.
   */
  getItem<T>(key: string): Promise<T | null>;

  /** Remove a single key from storage. */
  removeItem(key: string): Promise<void>;

  /** Remove all keys managed by this storage instance. */
  clear(): Promise<void>;

  /** Check if a key exists in storage. */
  hasItem(key: string): Promise<boolean>;

  /** Get all keys currently in storage. */
  keys(): Promise<string[]>;
}