strata-storage 2.5.0 → 2.6.1

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

@@ -8,10 +8,11 @@ import com.getcapacitor.PluginMethod;
 import com.getcapacitor.annotation.CapacitorPlugin;
 import com.strata.storage.SharedPreferencesStorage;
 import com.strata.storage.EncryptedStorage;
+import com.strata.storage.FilesystemStorage;
 import com.strata.storage.SQLiteStorage;
 import android.util.Log;
 import org.json.JSONArray;
-import org.json.JSONException;
+import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
@@ -19,15 +20,24 @@ import java.util.Map;
  * Main Capacitor plugin for Strata Storage
  * Coordinates between different storage types on Android.
  *
- * Storage types with a real native backend: preferences, secure, sqlite.
- * `filesystem` is NOT implemented natively and is rejected explicitly rather
- * than silently falling through to SharedPreferences.
+ * Storage types with a real native backend: preferences, secure, sqlite,
+ * filesystem.
+ *
+ * SQLite supports multi-store: the `database` option selects the DB file and
+ * `table` selects the table within it. SQLite helper instances are cached per
+ * database name so the connection is not reopened per call.
  */
 @CapacitorPlugin(name = "StrataStorage")
 public class StrataStoragePlugin extends Plugin {
+    private static final String DEFAULT_DATABASE = "strata_storage";
+    private static final String DEFAULT_TABLE = "storage";
+
     private SharedPreferencesStorage sharedPrefsStorage;
     private EncryptedStorage encryptedStorage;
-    private SQLiteStorage sqliteStorage;
+    private FilesystemStorage filesystemStorage;
+
+    /** SQLite helper cache keyed by resolved database name (without ".db"). */
+    private final Map<String, SQLiteStorage> sqliteStores = new HashMap<>();
 
     @Override
     public void load() {
@@ -44,18 +54,43 @@ public class StrataStoragePlugin extends Plugin {
             Log.e("StrataStorage", "Failed to initialize encrypted storage", e);
         }
         try {
-            sqliteStorage = new SQLiteStorage(getContext());
+            filesystemStorage = new FilesystemStorage(getContext());
         } catch (Exception e) {
-            Log.e("StrataStorage", "Failed to initialize SQLite storage", e);
+            Log.e("StrataStorage", "Failed to initialize filesystem storage", e);
         }
     }
 
-    private void rejectUnsupportedFilesystem(PluginCall call) {
-        call.reject(
-            "Filesystem storage is not implemented in the native Android plugin. " +
-            "Use the 'preferences', 'secure', or 'sqlite' storage types, or a " +
-            "web/Capacitor Filesystem-backed adapter."
-        );
+    /**
+     * Sanitize a database name to a safe file stem ({@code ^[A-Za-z0-9_]+$})
+     * and return the resolved stem. The ".db" suffix is appended when opening.
+     */
+    private static String sanitizeDatabase(String database) {
+        if (database == null || database.isEmpty()) {
+            return DEFAULT_DATABASE;
+        }
+        String cleaned = database.replaceAll("[^A-Za-z0-9_]", "");
+        return cleaned.isEmpty() ? DEFAULT_DATABASE : cleaned;
+    }
+
+    /**
+     * Return (creating + caching on first use) the SQLite helper for the given
+     * database name. The cache is keyed by the sanitized DB stem so the
+     * connection is reused across bridge calls. May return {@code null} if the
+     * helper cannot be constructed.
+     */
+    private synchronized SQLiteStorage getSqliteStore(String database) {
+        String dbStem = sanitizeDatabase(database);
+        SQLiteStorage store = sqliteStores.get(dbStem);
+        if (store == null) {
+            try {
+                store = new SQLiteStorage(getContext(), dbStem + ".db");
+                sqliteStores.put(dbStem, store);
+            } catch (Exception e) {
+                Log.e("StrataStorage", "Failed to open SQLite database " + dbStem, e);
+                return null;
+            }
+        }
+        return store;
     }
 
     /**
@@ -71,11 +106,10 @@ public class StrataStoragePlugin extends Plugin {
                 available = encryptedStorage != null;
                 break;
             case "sqlite":
-                available = sqliteStorage != null;
+                available = getSqliteStore(call.getString("database", DEFAULT_DATABASE)) != null;
                 break;
             case "filesystem":
-                // No native filesystem backend.
-                available = false;
+                available = filesystemStorage != null;
                 break;
             case "preferences":
             default:
@@ -89,7 +123,10 @@ public class StrataStoragePlugin extends Plugin {
     }
 
     /**
-     * Get value from storage
+     * Get value from storage.
+     *
+     * For sqlite/filesystem the resolved `value` is the full wrapper object
+     * (parsed back from JSON). A miss resolves `value` = null.
      */
     @PluginMethod
     public void get(PluginCall call) {
@@ -102,46 +139,70 @@ public class StrataStoragePlugin extends Plugin {
         String storage = call.getString("storage", "preferences");
 
         try {
-            Object value = null;
-
             switch (storage) {
-                case "secure":
+                case "secure": {
                     if (encryptedStorage == null) {
                         call.reject("Encrypted storage not available");
                         return;
                     }
-                    value = encryptedStorage.get(key);
-                    break;
-                case "sqlite":
-                    if (sqliteStorage == null) {
+                    resolveValue(call, encryptedStorage.get(key));
+                    return;
+                }
+                case "sqlite": {
+                    SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+                    if (store == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    value = sqliteStorage.get(key);
-                    break;
-                case "filesystem":
-                    rejectUnsupportedFilesystem(call);
+                    String table = call.getString("table", DEFAULT_TABLE);
+                    resolveValue(call, store.get(table, key));
                     return;
+                }
+                case "filesystem": {
+                    if (filesystemStorage == null) {
+                        call.reject("Filesystem storage not available");
+                        return;
+                    }
+                    resolveValue(call, filesystemStorage.get(key));
+                    return;
+                }
                 case "preferences":
-                default:
+                default: {
                     if (sharedPrefsStorage == null) {
                         call.reject("Preferences storage not available");
                         return;
                     }
-                    value = sharedPrefsStorage.get(key);
-                    break;
+                    resolveValue(call, sharedPrefsStorage.get(key));
+                    return;
+                }
             }
-
-            JSObject result = new JSObject();
-            result.put("value", value);
-            call.resolve(result);
         } catch (Exception e) {
             call.reject("Failed to get value", e);
         }
     }
 
     /**
-     * Set value in storage
+     * Resolve a get() call, mapping a Java {@code null} to a JS {@code null}
+     * value so the TS adapters treat it as a miss.
+     */
+    private void resolveValue(PluginCall call, Object value) {
+        JSObject result = new JSObject();
+        if (value == null) {
+            result.put("value", JSObject.NULL);
+        } else {
+            result.put("value", value);
+        }
+        call.resolve(result);
+    }
+
+    /**
+     * Set value in storage.
+     *
+     * For sqlite/filesystem the `value` is the FULL wrapper object
+     * ({ value, created, updated, expires?, tags?, metadata? }); it is read via
+     * call.getObject("value") and stored verbatim (with TTL/query columns
+     * extracted for sqlite). For preferences/secure the raw value is forwarded
+     * unchanged.
      */
     @PluginMethod
     public void set(PluginCall call) {
@@ -151,7 +212,6 @@ public class StrataStoragePlugin extends Plugin {
             return;
         }
 
-        Object value = call.getData().opt("value");
         String storage = call.getString("storage", "preferences");
 
         try {
@@ -162,25 +222,42 @@ public class StrataStoragePlugin extends Plugin {
                         call.reject("Encrypted storage not available");
                         return;
                     }
-                    ok = encryptedStorage.set(key, value);
+                    ok = encryptedStorage.set(key, call.getData().opt("value"));
                     break;
-                case "sqlite":
-                    if (sqliteStorage == null) {
+                case "sqlite": {
+                    SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+                    if (store == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    ok = sqliteStorage.set(key, value);
+                    JSObject wrapper = call.getObject("value");
+                    if (wrapper == null) {
+                        call.reject("A wrapper object 'value' is required for sqlite storage");
+                        return;
+                    }
+                    ok = store.set(call.getString("table", DEFAULT_TABLE), key, wrapper);
                     break;
-                case "filesystem":
-                    rejectUnsupportedFilesystem(call);
-                    return;
+                }
+                case "filesystem": {
+                    if (filesystemStorage == null) {
+                        call.reject("Filesystem storage not available");
+                        return;
+                    }
+                    JSObject wrapper = call.getObject("value");
+                    if (wrapper == null) {
+                        call.reject("A wrapper object 'value' is required for filesystem storage");
+                        return;
+                    }
+                    ok = filesystemStorage.set(key, wrapper);
+                    break;
+                }
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
                         call.reject("Preferences storage not available");
                         return;
                     }
-                    ok = sharedPrefsStorage.set(key, value);
+                    ok = sharedPrefsStorage.set(key, call.getData().opt("value"));
                     break;
             }
 
@@ -216,16 +293,22 @@ public class StrataStoragePlugin extends Plugin {
                     }
                     encryptedStorage.remove(key);
                     break;
-                case "sqlite":
-                    if (sqliteStorage == null) {
+                case "sqlite": {
+                    SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+                    if (store == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    sqliteStorage.remove(key);
+                    store.remove(call.getString("table", DEFAULT_TABLE), key);
                     break;
+                }
                 case "filesystem":
-                    rejectUnsupportedFilesystem(call);
-                    return;
+                    if (filesystemStorage == null) {
+                        call.reject("Filesystem storage not available");
+                        return;
+                    }
+                    filesystemStorage.remove(key);
+                    break;
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
@@ -263,16 +346,22 @@ public class StrataStoragePlugin extends Plugin {
                     }
                     encryptedStorage.clear(prefix);
                     break;
-                case "sqlite":
-                    if (sqliteStorage == null) {
+                case "sqlite": {
+                    SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+                    if (store == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    sqliteStorage.clear(prefix);
+                    store.clear(call.getString("table", DEFAULT_TABLE), prefix);
                     break;
+                }
                 case "filesystem":
-                    rejectUnsupportedFilesystem(call);
-                    return;
+                    if (filesystemStorage == null) {
+                        call.reject("Filesystem storage not available");
+                        return;
+                    }
+                    filesystemStorage.clear(prefix);
+                    break;
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
@@ -298,7 +387,7 @@ public class StrataStoragePlugin extends Plugin {
         String pattern = call.getString("pattern");
 
         try {
-            List<String> keys = null;
+            List<String> keys;
 
             switch (storage) {
                 case "secure":
@@ -308,16 +397,22 @@ public class StrataStoragePlugin extends Plugin {
                     }
                     keys = encryptedStorage.keys(pattern);
                     break;
-                case "sqlite":
-                    if (sqliteStorage == null) {
+                case "sqlite": {
+                    SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+                    if (store == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    keys = sqliteStorage.keys(pattern);
+                    keys = store.keys(call.getString("table", DEFAULT_TABLE), pattern);
                     break;
+                }
                 case "filesystem":
-                    rejectUnsupportedFilesystem(call);
-                    return;
+                    if (filesystemStorage == null) {
+                        call.reject("Filesystem storage not available");
+                        return;
+                    }
+                    keys = filesystemStorage.keys(pattern);
+                    break;
                 case "preferences":
                 default:
                     if (sharedPrefsStorage == null) {
@@ -337,17 +432,21 @@ public class StrataStoragePlugin extends Plugin {
     }
 
     /**
-     * Get storage size information
+     * Get storage size information.
+     *
+     * When `detailed` is true the result also carries a byte breakdown
+     * { detailed: { keys, values, metadata } }.
      */
     @PluginMethod
     public void size(PluginCall call) {
         String storage = call.getString("storage", "preferences");
+        boolean detailed = Boolean.TRUE.equals(call.getBoolean("detailed", false));
 
         try {
             JSObject result = new JSObject();
 
             switch (storage) {
-                case "secure":
+                case "secure": {
                     if (encryptedStorage == null) {
                         call.reject("Encrypted storage not available");
                         return;
@@ -356,20 +455,29 @@ public class StrataStoragePlugin extends Plugin {
                     result.put("total", encryptedSizeInfo.total);
                     result.put("count", encryptedSizeInfo.count);
                     break;
-                case "sqlite":
-                    if (sqliteStorage == null) {
+                }
+                case "sqlite": {
+                    SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+                    if (store == null) {
                         call.reject("SQLite storage not available");
                         return;
                     }
-                    SQLiteStorage.SizeInfo sqliteSizeInfo = sqliteStorage.size();
-                    result.put("total", sqliteSizeInfo.total);
-                    result.put("count", sqliteSizeInfo.count);
+                    SQLiteStorage.SizeInfo sqliteSizeInfo =
+                            store.size(call.getString("table", DEFAULT_TABLE), detailed);
+                    putSizeInfo(result, sqliteSizeInfo);
                     break;
-                case "filesystem":
-                    rejectUnsupportedFilesystem(call);
-                    return;
+                }
+                case "filesystem": {
+                    if (filesystemStorage == null) {
+                        call.reject("Filesystem storage not available");
+                        return;
+                    }
+                    SQLiteStorage.SizeInfo fsSizeInfo = filesystemStorage.size(detailed);
+                    putSizeInfo(result, fsSizeInfo);
+                    break;
+                }
                 case "preferences":
-                default:
+                default: {
                     if (sharedPrefsStorage == null) {
                         call.reject("Preferences storage not available");
                         return;
@@ -378,6 +486,7 @@ public class StrataStoragePlugin extends Plugin {
                     result.put("total", prefsSizeInfo.total);
                     result.put("count", prefsSizeInfo.count);
                     break;
+                }
             }
 
             call.resolve(result);
@@ -386,12 +495,27 @@ public class StrataStoragePlugin extends Plugin {
         }
     }
 
+    /**
+     * Populate a size result, including the detailed byte breakdown when the
+     * {@link SQLiteStorage.SizeInfo} carries one.
+     */
+    private void putSizeInfo(JSObject result, SQLiteStorage.SizeInfo info) {
+        result.put("total", info.total);
+        result.put("count", info.count);
+        if (info.detailed) {
+            JSObject breakdown = new JSObject();
+            breakdown.put("keys", info.keysBytes);
+            breakdown.put("values", info.valuesBytes);
+            breakdown.put("metadata", info.metadataBytes);
+            result.put("detailed", breakdown);
+        }
+    }
+
     /**
      * Query SQLite-backed storage.
      * Matches the optional `query` method in the JS contract:
-     * resolves { results: [{ key, value }] }. The JS SqliteAdapter applies the
-     * real condition by re-fetching/filtering, so this enumerates candidate
-     * rows.
+     * resolves { results: [{ key }] }. The JS SqliteAdapter applies the real
+     * condition by re-fetching/filtering, so this enumerates candidate keys.
      */
     @PluginMethod
     public void query(PluginCall call) {
@@ -400,18 +524,18 @@ public class StrataStoragePlugin extends Plugin {
             call.reject("Query is only supported for the 'sqlite' storage type");
             return;
         }
-        if (sqliteStorage == null) {
+        SQLiteStorage store = getSqliteStore(call.getString("database", DEFAULT_DATABASE));
+        if (store == null) {
             call.reject("SQLite storage not available");
             return;
         }
 
         try {
-            List<Map<String, Object>> rows = sqliteStorage.query();
+            List<Map<String, Object>> rows = store.query(call.getString("table", DEFAULT_TABLE));
             JSArray results = new JSArray();
             for (Map<String, Object> row : rows) {
                 JSObject obj = new JSObject();
                 obj.put("key", row.get("key"));
-                obj.put("value", row.get("value"));
                 results.put(obj);
             }
             JSObject result = new JSObject();

package/dist/README.md

@@ -9,7 +9,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
 [![Platform](https://img.shields.io/badge/platform-Web%20%7C%20iOS%20%7C%20Android-lightgrey.svg)](https://github.com/aoneahsan/strata-storage)
 
-- **Version:** `2.5.0`
+- **Version:** `2.6.1`
 - **License:** Apache-2.0
 - **Node.js:** `>= 24.13.0`
 - **Module format:** ESM only
@@ -390,15 +390,22 @@ const active = await storage.query({
 
 ### iOS and Android (via Capacitor)
 
-Register native adapters yourself when running under Capacitor:
+Register the native adapters you need when running under Capacitor. All four are zero-runtime-dependency: SQLite is hand-rolled (no plugin dependency) and filesystem uses the platform's native `FileManager` / `java.io.File`.
 
 ```typescript
 import { defineStorage } from 'strata-storage';
-import { PreferencesAdapter, SecureStorageAdapter } from 'strata-storage/capacitor';
+import {
+  PreferencesAdapter,
+  SecureStorageAdapter,
+  SqliteAdapter,
+  FilesystemAdapter,
+} from 'strata-storage/capacitor';
 
 const storage = defineStorage();
-storage.registerAdapter(new PreferencesAdapter());  // UserDefaults / SharedPreferences
+storage.registerAdapter(new PreferencesAdapter());   // UserDefaults / SharedPreferences
 storage.registerAdapter(new SecureStorageAdapter()); // Keychain / EncryptedSharedPreferences
+storage.registerAdapter(new SqliteAdapter());        // native SQLite
+storage.registerAdapter(new FilesystemAdapter());    // native files
 
 await storage.set('secret', token, { storage: 'secure' });
 ```
@@ -407,10 +414,25 @@ await storage.set('secret', token, { storage: 'secure' });
 |---------|-------------|-----------------|
 | `preferences` | UserDefaults | SharedPreferences |
 | `secure` | Keychain | EncryptedSharedPreferences |
-| `sqlite` | SQLite | SQLite |
-| `filesystem` | FileManager | Filesystem |
+| `sqlite` | SQLite (multi-store) | SQLite (multi-store) |
+| `filesystem` | FileManager | java.io.File |
 
-> **Honest note:** the native iOS/Android adapters depend on your downstream Capacitor project setup and platform configuration. Behavior on a real device should be verified on-device — native storage cannot be exercised by the web/Node test suite.
+**SQLite multi-store** (2.6.0+): each `SqliteAdapter` instance binds to a `(database, table)` pair, so distinct logical stores map to distinct physical SQLite files / tables and cannot collide.
+
+```typescript
+import { SqliteAdapter } from 'strata-storage/capacitor';
+
+const analytics = defineStorage();
+analytics.registerAdapter(new SqliteAdapter({ database: 'analytics', table: 'events' }));
+
+const audit = defineStorage();
+audit.registerAdapter(new SqliteAdapter({ database: 'audit', table: 'rows' }));
+// → separate physical .db files; writes to `analytics` can never bleed into `audit`.
+```
+
+`await storage.size(true)` aggregates `{ total, count, byStorage, ... }`; native SQLite and filesystem additionally report a per-column byte breakdown (keys / values / metadata) when called on those adapters directly.
+
+> **Honest note:** the native iOS/Android adapters depend on your downstream Capacitor project setup and platform configuration, and native behavior cannot be exercised by the web/Node test suite. Follow [`docs/guides/platforms/device-verification.md`](./docs/guides/platforms/device-verification.md) to verify on a real iOS and Android device after integrating.
 
 ### Firebase (optional cloud sync)
 
@@ -436,8 +458,8 @@ await storage.set('data', value, { storage: 'firestore' });
 | `url` | Web | ✅ | async only | Shareable UI state, length-limited |
 | `preferences` | Mobile | ❌ | async only | UserDefaults / SharedPreferences |
 | `secure` | Mobile | ❌ | async only | Keychain / EncryptedSharedPreferences |
-| `sqlite` | Mobile | ❌ | async only | Native SQLite |
-| `filesystem` | Mobile | ❌ | async only | Native files |
+| `sqlite` | Mobile | ❌ | async only | Native SQLite — multi-store via `(database, table)` (2.6.0+) |
+| `filesystem` | Mobile | ❌ | async only | Native files — file-per-key with atomic writes (2.6.0+) |
 
 "async only" means encryption and compression require the `await storage.set(...)` path — the synchronous API cannot encrypt or compress.
 

package/dist/android/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — android/
 
-Last Updated: 2026-04-03
+Last Updated: 2026-05-27
 
 > Agent instructions for Android native development.
 
@@ -8,27 +8,44 @@ Last Updated: 2026-04-03
 
 | File | Purpose |
 |------|---------|
-| `StrataStoragePlugin.java` | Capacitor plugin entry (com.stratastorage) |
-| `SharedPreferencesStorage.java` | General key-value storage (com.strata.storage) |
-| `EncryptedStorage.java` | Secure storage (com.strata.storage) |
-| `SQLiteStorage.java` | Database storage (com.strata.storage) |
+| `StrataStoragePlugin.java` | Capacitor plugin entry (`com.stratastorage`) |
+| `SharedPreferencesStorage.java` | General key-value storage (`com.strata.storage`) |
+| `EncryptedStorage.java` | Secure storage via EncryptedSharedPreferences (`com.strata.storage`); requires `androidx.security:security-crypto 1.1.0` (stable, upgraded in v2.6.0) |
+| `SQLiteStorage.java` | SQLite database storage — multi-store (v2.6.0): `database`/`table` options honoured, full `StorageValue` wrapper round-trip, `size(detailed)` supported (`com.strata.storage`) |
+| `FilesystemStorage.java` | File-per-key native storage under `getFilesDir()/strata_storage/` (new in v2.6.0); atomic writes via staging rename; `isAvailable()` returns `true`; no external permissions needed (`com.strata.storage`) |
+
+## v2.6.0 Notes
+
+- **`androidx.security 1.1.0`:** upgraded from `1.1.0-alpha06`. Requires `compileSdkVersion 34`. If Gradle sync fails, bump `compileSdkVersion` and `targetSdkVersion` to 34 in `android/app/build.gradle`.
+- **SQLite multi-store:** `call.getString("database")` and `call.getString("table")` are now read and used. Each `(database, table)` pair → distinct `.db` file. Previously ignored.
+- **SQLite value shape:** native `get` returns full `StorageValue` wrapper. Corrupt rows → treated as miss (no throw).
+- **FilesystemStorage.java:** new class. Writes are atomic (staging temp → `renameTo`). `keys()` excludes `.staging/` artifacts. `size(detailed)` → `{ keys, values, metadata }`.
+- **Pending on-device verification** — see `docs/guides/platforms/device-verification.md`.
 
 ## Agent Rules
 
 ### Security (IRON-SOLID)
 - Sensitive data MUST use `EncryptedStorage`
 - NEVER store secrets in `SharedPreferencesStorage`
+- `androidx.security:security-crypto` version MUST be `1.1.0` (stable) — not alpha
 
 ### SQL Safety (IRON-SOLID)
 - ALWAYS use parameterized queries
 - NEVER concatenate user input into SQL strings
 
+### Filesystem Safety
+- NEVER read from `strata_storage/.staging/` — staging files are transient
+- Key sanitisation must be consistent between `set`, `get`, `remove`, and `keys`
+
 ### Plugin Architecture
 - Methods exposed through `StrataStoragePlugin.java`
 - Each storage backend is a separate Java class
 - Two package paths: `com.stratastorage` (plugin) and `com.strata.storage` (impl)
 
+### Build
+- `compileSdkVersion 34` required for `androidx.security 1.1.0`
+- Verify Gradle build succeeds after any change
+
 ### Before Modifying
 - Understand Capacitor plugin protocol for Android
-- Test on Android emulator after changes
-- Verify Gradle build succeeds
+- Test on Android emulator after changes; follow device-verification guide