strata-storage
Version:
Zero-dependency universal storage plugin providing a unified API for all storage operations across web, Android, and iOS platforms
278 lines • 9.21 kB
TypeScript
/**
* Strata Storage - Main entry point
* Zero-dependency universal storage solution
*/
import type { StrataConfig, StorageAdapter, StorageOptions, StorageType, Platform, SizeInfo, ClearOptions, ExportOptions, ImportOptions, SubscriptionCallback, UnsubscribeFunction, QueryCondition, StorageCapabilities } from '@/types';
import { AdapterRegistry } from './AdapterRegistry';
/**
* Main Strata class - unified storage interface
*/
export declare class Strata {
private config;
private registry;
private defaultAdapter?;
private adapters;
private readonly _platform;
private encryptionManager?;
private compressionManager?;
private syncManager?;
private ttlManager?;
private _initialized;
constructor(config?: StrataConfig);
/**
* Check if Strata has been initialized
*/
get isInitialized(): boolean;
/**
* Get the detected platform
*/
get platform(): Platform;
/**
* Initialize Strata with available adapters
*/
initialize(): Promise<void>;
/**
* Get a value from storage
*
* @param key - The key to retrieve
* @param options - Storage options
* @param options.storage - Specific storage type to use (e.g., 'localStorage', 'indexedDB')
* @param options.decrypt - Whether to decrypt the value (default: auto-detect)
* @param options.decryptionPassword - Password for decryption (uses config password if not provided)
* @returns The stored value or null if not found
* @throws {StorageError} If the storage adapter is not available
* @throws {EncryptionError} If decryption fails
*
* @example
* ```typescript
* // Simple get
* const value = await storage.get('myKey');
*
* // Get from specific storage
* const value = await storage.get('myKey', { storage: 'indexedDB' });
*
* // Get encrypted value
* const value = await storage.get('secure-key', {
* decryptionPassword: 'myPassword'
* });
* ```
*/
get<T = unknown>(key: string, options?: StorageOptions): Promise<T | null>;
/**
* Set a value in storage
*
* @param key - The key to store under
* @param value - The value to store (can be any serializable type)
* @param options - Storage options
* @param options.storage - Specific storage type to use
* @param options.encrypt - Whether to encrypt the value
* @param options.encryptionPassword - Password for encryption
* @param options.compress - Whether to compress the value
* @param options.ttl - Time-to-live in milliseconds
* @param options.tags - Tags for categorization
* @param options.metadata - Additional metadata to store
* @throws {StorageError} If the storage adapter is not available
* @throws {EncryptionError} If encryption fails
*
* @example
* ```typescript
* // Simple set
* await storage.set('myKey', 'myValue');
*
* // Set with TTL (expires in 1 hour)
* await storage.set('tempKey', data, { ttl: 3600000 });
*
* // Set with encryption and compression
* await storage.set('secure-key', sensitiveData, {
* encrypt: true,
* compress: true,
* encryptionPassword: 'myPassword'
* });
*
* // Set with metadata
* await storage.set('user-123', userData, {
* tags: ['user', 'active'],
* metadata: { version: 2, source: 'api' }
* });
* ```
*/
set<T = unknown>(key: string, value: T, options?: StorageOptions): Promise<void>;
/**
* Remove a value from storage
*
* @param key - The key to remove
* @param options - Storage options
* @param options.storage - Specific storage type to use
* @throws {StorageError} If the storage adapter is not available
*
* @example
* ```typescript
* // Remove from default storage
* await storage.remove('myKey');
*
* // Remove from specific storage
* await storage.remove('myKey', { storage: 'cookies' });
* ```
*/
remove(key: string, options?: StorageOptions): Promise<void>;
/**
* Check if a key exists in storage
*
* @param key - The key to check
* @param options - Storage options
* @param options.storage - Specific storage type to check
* @returns True if the key exists, false otherwise
* @throws {StorageError} If the storage adapter is not available
*
* @example
* ```typescript
* // Check in default storage
* const exists = await storage.has('myKey');
*
* // Check in specific storage
* const exists = await storage.has('myKey', { storage: 'sessionStorage' });
* ```
*/
has(key: string, options?: StorageOptions): Promise<boolean>;
/**
* Clear storage
*
* @param options - Clear options
* @param options.storage - Specific storage to clear (clears all if not specified)
* @param options.prefix - Only clear keys with this prefix
* @param options.tags - Only clear items with these tags
* @param options.olderThan - Only clear items older than this date
* @throws {StorageError} If the storage adapter is not available
*
* @example
* ```typescript
* // Clear all storage
* await storage.clear();
*
* // Clear specific storage
* await storage.clear({ storage: 'localStorage' });
*
* // Clear by prefix
* await storage.clear({ prefix: 'temp-' });
*
* // Clear old items
* const yesterday = Date.now() - 86400000;
* await storage.clear({ olderThan: yesterday });
* ```
*/
clear(options?: ClearOptions & StorageOptions): Promise<void>;
/**
* Get all keys from storage
*
* @param pattern - Optional pattern to filter keys (string prefix or RegExp)
* @param options - Storage options
* @param options.storage - Specific storage to get keys from (gets from all if not specified)
* @returns Array of matching keys
* @throws {StorageError} If the storage adapter is not available
*
* @example
* ```typescript
* // Get all keys
* const keys = await storage.keys();
*
* // Get keys with prefix
* const userKeys = await storage.keys('user-');
*
* // Get keys with regex pattern
* const tempKeys = await storage.keys(/^temp-.*$/);
*
* // Get keys from specific storage
* const localKeys = await storage.keys(null, { storage: 'localStorage' });
* ```
*/
keys(pattern?: string | RegExp, options?: StorageOptions): Promise<string[]>;
/**
* Get storage size information
*/
size(detailed?: boolean): Promise<SizeInfo>;
/**
* Subscribe to storage changes
*/
subscribe(callback: SubscriptionCallback, options?: StorageOptions): UnsubscribeFunction;
/**
* Query storage (if supported)
*/
query<T = unknown>(condition: QueryCondition, options?: StorageOptions): Promise<Array<{
key: string;
value: T;
}>>;
/**
* Export storage data
*/
export(options?: ExportOptions): Promise<string>;
/**
* Import storage data
*/
import(data: string, options?: ImportOptions): Promise<void>;
/**
* Get available storage types
*/
getAvailableStorageTypes(): StorageType[];
/**
* Get adapter capabilities
*/
getCapabilities(storage?: StorageType): StorageCapabilities | Record<string, StorageCapabilities>;
/**
* Generate a secure password for encryption
*/
generatePassword(length?: number): string;
/**
* Hash data using SHA-256
*/
hash(data: string): Promise<string>;
/**
* Get TTL (time to live) for a key
*/
getTTL(key: string, options?: StorageOptions): Promise<number | null>;
/**
* Extend TTL for a key
*/
extendTTL(key: string, extension: number, options?: StorageOptions): Promise<void>;
/**
* Make a key persistent (remove TTL)
*/
persist(key: string, options?: StorageOptions): Promise<void>;
/**
* Get items expiring within a time window
*/
getExpiring(timeWindow: number, options?: StorageOptions): Promise<Array<{
key: string;
expiresIn: number;
}>>;
/**
* Manually trigger TTL cleanup
*/
cleanupExpired(options?: StorageOptions): Promise<number>;
/**
* Register a custom storage adapter
* This allows external adapters to be registered after initialization
*
* @example
* ```typescript
* import { MyCustomAdapter } from './my-adapter';
* storage.registerAdapter(new MyCustomAdapter());
* ```
*/
registerAdapter(adapter: StorageAdapter): void;
/**
* Get the adapter registry (for advanced use cases)
* @internal
*/
getRegistry(): AdapterRegistry;
/**
* Close all adapters
*/
close(): Promise<void>;
private normalizeConfig;
private detectPlatform;
private getDefaultStorages;
private selectDefaultAdapter;
private initializeAdapters;
private selectAdapter;
}
//# sourceMappingURL=Strata.d.ts.map