strata-storage 2.0.3 → 2.0.4

package/android/src/main/java/com/strata/storage/EncryptedStorage.java

@@ -6,14 +6,20 @@ import android.os.Build;
 import androidx.security.crypto.EncryptedSharedPreferences;
 import androidx.security.crypto.MasterKey;
 import java.util.Set;
+import java.util.HashSet;
 import java.util.Map;
 
 public class EncryptedStorage {
     private SharedPreferences encryptedPrefs;
     private SharedPreferences.Editor editor;
+    private static final String DEFAULT_NAME = "StrataSecureStorage";
+    
+    public EncryptedStorage(Context context) throws Exception {
+        this(context, DEFAULT_NAME);
+    }
     
     public EncryptedStorage(Context context, String name) throws Exception {
-        String fileName = name != null ? name : "StrataSecureStorage";
+        String fileName = name != null ? name : DEFAULT_NAME;
         
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
             MasterKey masterKey = new MasterKey.Builder(context)
@@ -51,12 +57,47 @@ public class EncryptedStorage {
     }
     
     public boolean clear() {
-        editor.clear();
+        return clear(null);
+    }
+    
+    public boolean clear(String prefix) {
+        if (prefix != null) {
+            // Clear only keys with the given prefix
+            Set<String> keysToRemove = new HashSet<>();
+            for (String key : encryptedPrefs.getAll().keySet()) {
+                if (key.startsWith(prefix) || key.contains(prefix)) {
+                    keysToRemove.add(key);
+                }
+            }
+            for (String key : keysToRemove) {
+                editor.remove(key);
+            }
+        } else {
+            // Clear all keys
+            editor.clear();
+        }
         return editor.commit();
     }
     
     public Set<String> keys() {
-        return encryptedPrefs.getAll().keySet();
+        return keys(null);
+    }
+    
+    public Set<String> keys(String pattern) {
+        Set<String> allKeys = encryptedPrefs.getAll().keySet();
+        
+        if (pattern == null) {
+            return allKeys;
+        }
+        
+        // Filter keys by pattern
+        Set<String> filteredKeys = new HashSet<>();
+        for (String key : allKeys) {
+            if (key.startsWith(pattern) || key.contains(pattern)) {
+                filteredKeys.add(key);
+            }
+        }
+        return filteredKeys;
     }
     
     public boolean has(String key) {

package/android/src/main/java/com/strata/storage/SQLiteStorage.java

@@ -13,6 +13,7 @@ import java.util.Map;
 public class SQLiteStorage extends SQLiteOpenHelper {
     private static final int DATABASE_VERSION = 1;
     private static final String TABLE_NAME = "strata_storage";
+    private static final String DEFAULT_DB_NAME = "strata.db";
     
     private static final String KEY_ID = "key";
     private static final String KEY_VALUE = "value";
@@ -22,8 +23,12 @@ public class SQLiteStorage extends SQLiteOpenHelper {
     private static final String KEY_TAGS = "tags";
     private static final String KEY_METADATA = "metadata";
     
+    public SQLiteStorage(Context context) {
+        this(context, DEFAULT_DB_NAME);
+    }
+    
     public SQLiteStorage(Context context, String dbName) {
-        super(context, dbName != null ? dbName : "strata.db", null, DATABASE_VERSION);
+        super(context, dbName != null ? dbName : DEFAULT_DB_NAME, null, DATABASE_VERSION);
     }
     
     @Override
@@ -112,18 +117,43 @@ public class SQLiteStorage extends SQLiteOpenHelper {
     }
     
     public boolean clear() {
+        return clear(null);
+    }
+    
+    public boolean clear(String prefix) {
         SQLiteDatabase db = this.getWritableDatabase();
-        db.delete(TABLE_NAME, null, null);
+        int result;
+        
+        if (prefix != null) {
+            // Clear only keys with the given prefix
+            result = db.delete(TABLE_NAME, KEY_ID + " LIKE ?", new String[]{prefix + "%"});
+        } else {
+            // Clear all keys
+            result = db.delete(TABLE_NAME, null, null);
+        }
+        
         db.close();
-        return true;
+        return result >= 0;
     }
     
     public List<String> keys() {
+        return keys(null);
+    }
+    
+    public List<String> keys(String pattern) {
         List<String> keys = new ArrayList<>();
-        String selectQuery = "SELECT " + KEY_ID + " FROM " + TABLE_NAME;
+        String selectQuery;
+        String[] selectionArgs = null;
+        
+        if (pattern != null) {
+            selectQuery = "SELECT " + KEY_ID + " FROM " + TABLE_NAME + " WHERE " + KEY_ID + " LIKE ?";
+            selectionArgs = new String[]{"% " + pattern + "%"};
+        } else {
+            selectQuery = "SELECT " + KEY_ID + " FROM " + TABLE_NAME;
+        }
         
         SQLiteDatabase db = this.getReadableDatabase();
-        Cursor cursor = db.rawQuery(selectQuery, null);
+        Cursor cursor = db.rawQuery(selectQuery, selectionArgs);
         
         if (cursor.moveToFirst()) {
             do {

package/android/src/main/java/com/strata/storage/SharedPreferencesStorage.java

@@ -11,9 +11,14 @@ import org.json.JSONArray;
 public class SharedPreferencesStorage {
     private final SharedPreferences prefs;
     private final SharedPreferences.Editor editor;
+    private static final String DEFAULT_NAME = "StrataStorage";
+    
+    public SharedPreferencesStorage(Context context) {
+        this(context, DEFAULT_NAME);
+    }
     
     public SharedPreferencesStorage(Context context, String name) {
-        this.prefs = context.getSharedPreferences(name != null ? name : "StrataStorage", Context.MODE_PRIVATE);
+        this.prefs = context.getSharedPreferences(name != null ? name : DEFAULT_NAME, Context.MODE_PRIVATE);
         this.editor = prefs.edit();
     }
     
@@ -56,12 +61,47 @@ public class SharedPreferencesStorage {
     }
     
     public boolean clear() {
-        editor.clear();
+        return clear(null);
+    }
+    
+    public boolean clear(String prefix) {
+        if (prefix != null) {
+            // Clear only keys with the given prefix
+            Set<String> keysToRemove = new HashSet<>();
+            for (String key : prefs.getAll().keySet()) {
+                if (key.startsWith(prefix) || key.contains(prefix)) {
+                    keysToRemove.add(key);
+                }
+            }
+            for (String key : keysToRemove) {
+                editor.remove(key);
+            }
+        } else {
+            // Clear all keys
+            editor.clear();
+        }
         return editor.commit();
     }
     
     public Set<String> keys() {
-        return prefs.getAll().keySet();
+        return keys(null);
+    }
+    
+    public Set<String> keys(String pattern) {
+        Set<String> allKeys = prefs.getAll().keySet();
+        
+        if (pattern == null) {
+            return allKeys;
+        }
+        
+        // Filter keys by pattern
+        Set<String> filteredKeys = new HashSet<>();
+        for (String key : allKeys) {
+            if (key.startsWith(pattern) || key.contains(pattern)) {
+                filteredKeys.add(key);
+            }
+        }
+        return filteredKeys;
     }
     
     public boolean has(String key) {

package/android/src/main/java/com/stratastorage/StrataStoragePlugin.java

@@ -5,9 +5,13 @@ import com.getcapacitor.Plugin;
 import com.getcapacitor.PluginCall;
 import com.getcapacitor.PluginMethod;
 import com.getcapacitor.annotation.CapacitorPlugin;
+import com.strata.storage.SharedPreferencesStorage;
+import com.strata.storage.EncryptedStorage;
+import com.strata.storage.SQLiteStorage;
 import org.json.JSONArray;
 import org.json.JSONException;
 import java.util.List;
+import java.util.Set;
 
 /**
  * Main Capacitor plugin for Strata Storage
@@ -21,9 +25,14 @@ public class StrataStoragePlugin extends Plugin {
 
     @Override
     public void load() {
-        sharedPrefsStorage = new SharedPreferencesStorage(getContext());
-        encryptedStorage = new EncryptedStorage(getContext());
-        sqliteStorage = new SQLiteStorage(getContext());
+        try {
+            sharedPrefsStorage = new SharedPreferencesStorage(getContext());
+            encryptedStorage = new EncryptedStorage(getContext());
+            sqliteStorage = new SQLiteStorage(getContext());
+        } catch (Exception e) {
+            // Log error but don't crash - some storage types may not be available
+            e.printStackTrace();
+        }
     }
 
     /**

package/dist/android/src/main/java/com/strata/storage/EncryptedStorage.java

@@ -6,14 +6,20 @@ import android.os.Build;
 import androidx.security.crypto.EncryptedSharedPreferences;
 import androidx.security.crypto.MasterKey;
 import java.util.Set;
+import java.util.HashSet;
 import java.util.Map;
 
 public class EncryptedStorage {
     private SharedPreferences encryptedPrefs;
     private SharedPreferences.Editor editor;
+    private static final String DEFAULT_NAME = "StrataSecureStorage";
+    
+    public EncryptedStorage(Context context) throws Exception {
+        this(context, DEFAULT_NAME);
+    }
     
     public EncryptedStorage(Context context, String name) throws Exception {
-        String fileName = name != null ? name : "StrataSecureStorage";
+        String fileName = name != null ? name : DEFAULT_NAME;
         
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
             MasterKey masterKey = new MasterKey.Builder(context)
@@ -51,12 +57,47 @@ public class EncryptedStorage {
     }
     
     public boolean clear() {
-        editor.clear();
+        return clear(null);
+    }
+    
+    public boolean clear(String prefix) {
+        if (prefix != null) {
+            // Clear only keys with the given prefix
+            Set<String> keysToRemove = new HashSet<>();
+            for (String key : encryptedPrefs.getAll().keySet()) {
+                if (key.startsWith(prefix) || key.contains(prefix)) {
+                    keysToRemove.add(key);
+                }
+            }
+            for (String key : keysToRemove) {
+                editor.remove(key);
+            }
+        } else {
+            // Clear all keys
+            editor.clear();
+        }
         return editor.commit();
     }
     
     public Set<String> keys() {
-        return encryptedPrefs.getAll().keySet();
+        return keys(null);
+    }
+    
+    public Set<String> keys(String pattern) {
+        Set<String> allKeys = encryptedPrefs.getAll().keySet();
+        
+        if (pattern == null) {
+            return allKeys;
+        }
+        
+        // Filter keys by pattern
+        Set<String> filteredKeys = new HashSet<>();
+        for (String key : allKeys) {
+            if (key.startsWith(pattern) || key.contains(pattern)) {
+                filteredKeys.add(key);
+            }
+        }
+        return filteredKeys;
     }
     
     public boolean has(String key) {

package/dist/android/src/main/java/com/strata/storage/SQLiteStorage.java

@@ -13,6 +13,7 @@ import java.util.Map;
 public class SQLiteStorage extends SQLiteOpenHelper {
     private static final int DATABASE_VERSION = 1;
     private static final String TABLE_NAME = "strata_storage";
+    private static final String DEFAULT_DB_NAME = "strata.db";
     
     private static final String KEY_ID = "key";
     private static final String KEY_VALUE = "value";
@@ -22,8 +23,12 @@ public class SQLiteStorage extends SQLiteOpenHelper {
     private static final String KEY_TAGS = "tags";
     private static final String KEY_METADATA = "metadata";
     
+    public SQLiteStorage(Context context) {
+        this(context, DEFAULT_DB_NAME);
+    }
+    
     public SQLiteStorage(Context context, String dbName) {
-        super(context, dbName != null ? dbName : "strata.db", null, DATABASE_VERSION);
+        super(context, dbName != null ? dbName : DEFAULT_DB_NAME, null, DATABASE_VERSION);
     }
     
     @Override
@@ -112,18 +117,43 @@ public class SQLiteStorage extends SQLiteOpenHelper {
     }
     
     public boolean clear() {
+        return clear(null);
+    }
+    
+    public boolean clear(String prefix) {
         SQLiteDatabase db = this.getWritableDatabase();
-        db.delete(TABLE_NAME, null, null);
+        int result;
+        
+        if (prefix != null) {
+            // Clear only keys with the given prefix
+            result = db.delete(TABLE_NAME, KEY_ID + " LIKE ?", new String[]{prefix + "%"});
+        } else {
+            // Clear all keys
+            result = db.delete(TABLE_NAME, null, null);
+        }
+        
         db.close();
-        return true;
+        return result >= 0;
     }
     
     public List<String> keys() {
+        return keys(null);
+    }
+    
+    public List<String> keys(String pattern) {
         List<String> keys = new ArrayList<>();
-        String selectQuery = "SELECT " + KEY_ID + " FROM " + TABLE_NAME;
+        String selectQuery;
+        String[] selectionArgs = null;
+        
+        if (pattern != null) {
+            selectQuery = "SELECT " + KEY_ID + " FROM " + TABLE_NAME + " WHERE " + KEY_ID + " LIKE ?";
+            selectionArgs = new String[]{"% " + pattern + "%"};
+        } else {
+            selectQuery = "SELECT " + KEY_ID + " FROM " + TABLE_NAME;
+        }
         
         SQLiteDatabase db = this.getReadableDatabase();
-        Cursor cursor = db.rawQuery(selectQuery, null);
+        Cursor cursor = db.rawQuery(selectQuery, selectionArgs);
         
         if (cursor.moveToFirst()) {
             do {

package/dist/android/src/main/java/com/strata/storage/SharedPreferencesStorage.java

@@ -11,9 +11,14 @@ import org.json.JSONArray;
 public class SharedPreferencesStorage {
     private final SharedPreferences prefs;
     private final SharedPreferences.Editor editor;
+    private static final String DEFAULT_NAME = "StrataStorage";
+    
+    public SharedPreferencesStorage(Context context) {
+        this(context, DEFAULT_NAME);
+    }
     
     public SharedPreferencesStorage(Context context, String name) {
-        this.prefs = context.getSharedPreferences(name != null ? name : "StrataStorage", Context.MODE_PRIVATE);
+        this.prefs = context.getSharedPreferences(name != null ? name : DEFAULT_NAME, Context.MODE_PRIVATE);
         this.editor = prefs.edit();
     }
     
@@ -56,12 +61,47 @@ public class SharedPreferencesStorage {
     }
     
     public boolean clear() {
-        editor.clear();
+        return clear(null);
+    }
+    
+    public boolean clear(String prefix) {
+        if (prefix != null) {
+            // Clear only keys with the given prefix
+            Set<String> keysToRemove = new HashSet<>();
+            for (String key : prefs.getAll().keySet()) {
+                if (key.startsWith(prefix) || key.contains(prefix)) {
+                    keysToRemove.add(key);
+                }
+            }
+            for (String key : keysToRemove) {
+                editor.remove(key);
+            }
+        } else {
+            // Clear all keys
+            editor.clear();
+        }
         return editor.commit();
     }
     
     public Set<String> keys() {
-        return prefs.getAll().keySet();
+        return keys(null);
+    }
+    
+    public Set<String> keys(String pattern) {
+        Set<String> allKeys = prefs.getAll().keySet();
+        
+        if (pattern == null) {
+            return allKeys;
+        }
+        
+        // Filter keys by pattern
+        Set<String> filteredKeys = new HashSet<>();
+        for (String key : allKeys) {
+            if (key.startsWith(pattern) || key.contains(pattern)) {
+                filteredKeys.add(key);
+            }
+        }
+        return filteredKeys;
     }
     
     public boolean has(String key) {

package/dist/android/src/main/java/com/stratastorage/StrataStoragePlugin.java

@@ -5,9 +5,13 @@ import com.getcapacitor.Plugin;
 import com.getcapacitor.PluginCall;
 import com.getcapacitor.PluginMethod;
 import com.getcapacitor.annotation.CapacitorPlugin;
+import com.strata.storage.SharedPreferencesStorage;
+import com.strata.storage.EncryptedStorage;
+import com.strata.storage.SQLiteStorage;
 import org.json.JSONArray;
 import org.json.JSONException;
 import java.util.List;
+import java.util.Set;
 
 /**
  * Main Capacitor plugin for Strata Storage
@@ -21,9 +25,14 @@ public class StrataStoragePlugin extends Plugin {
 
     @Override
     public void load() {
-        sharedPrefsStorage = new SharedPreferencesStorage(getContext());
-        encryptedStorage = new EncryptedStorage(getContext());
-        sqliteStorage = new SQLiteStorage(getContext());
+        try {
+            sharedPrefsStorage = new SharedPreferencesStorage(getContext());
+            encryptedStorage = new EncryptedStorage(getContext());
+            sqliteStorage = new SQLiteStorage(getContext());
+        } catch (Exception e) {
+            // Log error but don't crash - some storage types may not be available
+            e.printStackTrace();
+        }
     }
 
     /**

package/dist/capacitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capacitor.d.ts","sourceRoot":"","sources":["../src/capacitor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAO5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAG3E,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;GAGG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB9E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAMhD;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,EAAE,CAEnD"}
+{"version":3,"file":"capacitor.d.ts","sourceRoot":"","sources":["../src/capacitor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAO5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAG3E,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;GAGG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB9E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAShD;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,EAAE,CAEnD"}

package/dist/capacitor.js

@@ -17,7 +17,7 @@ export async function registerCapacitorAdapters(storage) {
     // Check if Capacitor is available
     const hasCapacitor = typeof window !== 'undefined' &&
         window.Capacitor &&
-        window.Capacitor.isNativePlatform();
+        window.Capacitor?.isNativePlatform?.();
     if (!hasCapacitor) {
         console.warn('Capacitor not detected. Capacitor adapters will not be registered.');
         return;
@@ -36,9 +36,10 @@ export async function registerCapacitorAdapters(storage) {
  * Helper to check if running in Capacitor environment
  */
 export function isCapacitorEnvironment() {
-    return (typeof window !== 'undefined' &&
+    return ((typeof window !== 'undefined' &&
         window.Capacitor &&
-        window.Capacitor.isNativePlatform());
+        window.Capacitor?.isNativePlatform?.()) ??
+        false);
 }
 /**
  * Get Capacitor-specific storage types

package/dist/core/Strata.d.ts

@@ -33,26 +33,157 @@ export declare class Strata {
     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
+     * 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
+     * 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[]>;
     /**