strata-storage 2.5.0 → 2.6.1

package/AI-INTEGRATION-GUIDE.md

@@ -1,6 +1,6 @@
 # AI Integration Guide - strata-storage
 
-Quick reference for AI development agents (Claude Code, Cursor, Copilot, etc.) to integrate `strata-storage` into web and mobile projects. Current version: **2.5.0**.
+Quick reference for AI development agents (Claude Code, Cursor, Copilot, etc.) to integrate `strata-storage` into web and mobile projects. Current version: **2.6.1**.
 
 ## Installation
 
@@ -160,15 +160,24 @@ const storage = defineStorage();
 
 ```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());
 storage.registerAdapter(new SecureStorageAdapter());
+storage.registerAdapter(new SqliteAdapter());       // 2.6.0 — multi-store (database + table)
+storage.registerAdapter(new FilesystemAdapter());   // 2.6.0 — file-per-key, atomic writes
 await storage.set('secret', token, { storage: 'secure' });
 ```
 
-Native adapters depend on the downstream Capacitor project setup; verify behavior on-device.
+**SQLite multi-store** (2.6.0): each `new SqliteAdapter({ database, table })` is an isolated store — distinct `(database, table)` pairs map to distinct physical `.db` files / tables natively and cannot collide. **Filesystem** (2.6.0): one JSON file per key under the app's documents/files directory; `isAvailable()` now returns `true` on iOS and Android.
+
+Native adapters depend on the downstream Capacitor project setup; follow `docs/guides/platforms/device-verification.md` to verify on a real iOS + Android device.
 
 ## Strata API (most-used methods)
 

package/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/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

package/android/CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md — android/
 
-Last Updated: 2026-04-03
+Last Updated: 2026-05-27
 
 ## Android Native Plugin
 
@@ -12,8 +12,9 @@ Java implementation of native storage backends for Capacitor.
 |------|------|---------|
 | `StrataStoragePlugin.java` | `src/main/java/com/stratastorage/` | Main Capacitor plugin entry |
 | `SharedPreferencesStorage.java` | `src/main/java/com/strata/storage/` | SharedPreferences general storage |
-| `EncryptedStorage.java` | `src/main/java/com/strata/storage/` | EncryptedSharedPreferences secure storage |
-| `SQLiteStorage.java` | `src/main/java/com/strata/storage/` | SQLite database storage |
+| `EncryptedStorage.java` | `src/main/java/com/strata/storage/` | EncryptedSharedPreferences secure storage (`androidx.security 1.1.0`) |
+| `SQLiteStorage.java` | `src/main/java/com/strata/storage/` | SQLite database storage — multi-store (v2.6.0) |
+| `FilesystemStorage.java` | `src/main/java/com/strata/storage/` | File-per-key storage under `Context.getFilesDir()/strata_storage/` (new in v2.6.0) |
 
 ### Configuration
 
@@ -23,27 +24,64 @@ Java implementation of native storage backends for Capacitor.
 
 **Note**: There are two Java package paths — `com.stratastorage` (plugin) and `com.strata.storage` (implementations).
 
+## v2.6.0 Changes
+
+### `androidx.security:security-crypto` 1.1.0 (stable)
+`EncryptedStorage.java` depends on `androidx.security:security-crypto`. The
+dependency was upgraded from `1.1.0-alpha06` to `1.1.0` (stable) in v2.6.0.
+The `EncryptedSharedPreferences` / `MasterKey` API is unchanged. The stable
+version requires `compileSdkVersion 34` — if Gradle sync fails after this
+change, bump `compileSdkVersion` and `targetSdkVersion` in
+`android/app/build.gradle` to 34.
+
+### SQLite multi-store
+`SQLiteStorage.java` now accepts `database` and `table` parameters from
+`call.getString("database")` / `call.getString("table")`. Each unique pair
+opens a distinct `.db` file in the app's internal storage. Table identifiers
+are sanitised to `[A-Za-z0-9_]`. The full `StorageValue` wrapper is serialised
+to JSON and stored in a single `value` column; native `get` returns the full
+wrapper so TTL, tags, and metadata survive the round-trip. `size(detailed)`
+returns per-column byte breakdown.
+
+### FilesystemStorage.java (new)
+Stores each key as `getFilesDir()/strata_storage/<sanitised-key>.json`. Writes
+are atomic: value is written to `strata_storage/.staging/<key>.tmp`, then
+renamed into place using `renameTo()`. Staging artifacts are excluded from
+`keys()`. No external filesystem permissions are needed (`getFilesDir()` is
+app-private). `isAvailable()` returns `true`. `size(detailed)` supported.
+
+> **Pending on-device verification** — native code is complete and reviewed; see
+> `docs/guides/platforms/device-verification.md` for the test matrix.
+
 ## Rules
 
 ### Security (IRON-SOLID)
 - Sensitive data MUST use `EncryptedStorage` (EncryptedSharedPreferences)
 - NEVER store credentials, tokens, or secrets in `SharedPreferencesStorage`
 - Follow Android Keystore best practices
+- `androidx.security:security-crypto 1.1.0` (stable) is the required version
 
 ### SQL Safety (IRON-SOLID)
 - ALWAYS use parameterized queries in `SQLiteStorage`
 - NEVER concatenate user input into SQL strings
 - Use `SQLiteDatabase.query()` or prepared statements
 
+### Filesystem Safety
+- NEVER read from `strata_storage/.staging/` — staging files are transient
+- Key sanitisation must be consistent between `set`, `get`, `remove`, and `keys`
+- `getFilesDir()` is app-private; no external storage permissions required
+
 ### Plugin Architecture
 - All native methods exposed through `StrataStoragePlugin.java`
 - Plugin bridges Capacitor JS calls to Java implementations
 - Each storage backend is a separate Java class
+- Two package paths: `com.stratastorage` (plugin) and `com.strata.storage` (impl)
 
 ### Build
 - Gradle-based build system
+- `compileSdkVersion 34` required for `androidx.security 1.1.0`
 - Proguard rules configured for release builds
-- Test on Android emulator after changes
+- Test on Android emulator after changes; follow device-verification guide
 
 ### Before Modifying
 - Understand the Capacitor plugin protocol for Android

package/android/build.gradle

@@ -51,7 +51,7 @@ dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
-    implementation 'androidx.security:security-crypto:1.1.0-alpha06'
+    implementation 'androidx.security:security-crypto:1.1.0'
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"

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

@@ -0,0 +1,287 @@
+package com.strata.storage;
+
+import android.content.Context;
+import android.util.Log;
+import com.getcapacitor.JSObject;
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.net.URLDecoder;
+import java.net.URLEncoder;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+import org.json.JSONException;
+
+/**
+ * Filesystem-backed storage. One file per key lives under
+ * {@code <filesDir>/strata_storage}. The file name is a reversible
+ * URL-encoding of the key (no path separators survive encoding) and the file
+ * contents are the JSON-serialized FULL wrapper object ({@code value, created,
+ * updated, expires?, tags?, metadata?}), mirroring the SQLite value-shape
+ * contract.
+ *
+ * <p>Writes are atomic: a temp file is written then renamed over the target.
+ * All access is synchronized on the instance so overlapping bridge calls are
+ * safe.
+ */
+public class FilesystemStorage {
+    private static final String DIR_NAME = "strata_storage";
+    private static final String ENCODING = "UTF-8";
+    /**
+     * Reserved subdirectory (inside the storage dir) that holds in-flight temp
+     * files for atomic writes. Because it is a directory, the file-only
+     * enumeration in keys()/size()/clear() skips it automatically, and temp
+     * names therefore can never collide with an encoded key file in the storage
+     * dir (e.g. a real key {@code "backup.tmp"}).
+     */
+    private static final String STAGING_DIR_NAME = ".strata-staging";
+
+    private final File baseDir;
+    private final File stagingDir;
+
+    public FilesystemStorage(Context context) {
+        this.baseDir = new File(context.getFilesDir(), DIR_NAME);
+        this.stagingDir = new File(baseDir, STAGING_DIR_NAME);
+        ensureDir();
+    }
+
+    private synchronized void ensureDir() {
+        if (!baseDir.exists()) {
+            // mkdirs() returns false if it already exists due to a race; the
+            // subsequent exists() check below is the real guard.
+            baseDir.mkdirs();
+        }
+        if (!stagingDir.exists()) {
+            stagingDir.mkdirs();
+        }
+    }
+
+    /** Reversibly encode a key into a path-separator-free file name. */
+    private static String encodeKey(String key) {
+        try {
+            return URLEncoder.encode(key, ENCODING);
+        } catch (Exception e) {
+            // UTF-8 is always supported; fall back defensively.
+            return key.replaceAll("[^A-Za-z0-9_-]", "_");
+        }
+    }
+
+    /** Inverse of {@link #encodeKey(String)}. */
+    private static String decodeKey(String fileName) {
+        try {
+            return URLDecoder.decode(fileName, ENCODING);
+        } catch (Exception e) {
+            return fileName;
+        }
+    }
+
+    private File fileForKey(String key) {
+        return new File(baseDir, encodeKey(key));
+    }
+
+    /**
+     * Read + parse the full wrapper for {@code key}. Missing file → {@code null}.
+     * Unparseable contents → {@code null} (treated as a miss; never throws).
+     */
+    public synchronized JSObject get(String key) {
+        File file = fileForKey(key);
+        if (!file.exists() || !file.isFile()) {
+            return null;
+        }
+        try {
+            String json = readFile(file);
+            return new JSObject(json);
+        } catch (JSONException parseError) {
+            Log.w("StrataStorage", "Unparseable filesystem value for key " + key);
+            return null;
+        } catch (IOException ioError) {
+            Log.e("StrataStorage", "Failed to read filesystem value for key " + key, ioError);
+            return null;
+        }
+    }
+
+    /**
+     * Atomically persist the full wrapper for {@code key}: write a temp file
+     * then rename it over the destination.
+     */
+    public synchronized boolean set(String key, JSObject wrapper) {
+        if (wrapper == null) {
+            return false;
+        }
+        ensureDir();
+        File target = fileForKey(key);
+        // Temp file lives in the staging subdir (same filesystem → atomic
+        // rename) with a UUID name, so it can never collide with a key file.
+        File tmp = new File(stagingDir, UUID.randomUUID().toString() + ".tmp");
+        FileOutputStream fos = null;
+        try {
+            fos = new FileOutputStream(tmp);
+            fos.write(wrapper.toString().getBytes(StandardCharsets.UTF_8));
+            fos.flush();
+            fos.getFD().sync();
+            fos.close();
+            fos = null;
+
+            // Rename is atomic on the same filesystem. Remove a stale target
+            // first since File.renameTo can fail when the destination exists.
+            if (target.exists() && !target.delete()) {
+                Log.w("StrataStorage", "Could not delete existing file before rename: " + key);
+            }
+            if (!tmp.renameTo(target)) {
+                tmp.delete();
+                return false;
+            }
+            return true;
+        } catch (IOException e) {
+            Log.e("StrataStorage", "Failed to set filesystem value for key " + key, e);
+            if (tmp.exists()) {
+                tmp.delete();
+            }
+            return false;
+        } finally {
+            if (fos != null) {
+                try {
+                    fos.close();
+                } catch (IOException ignored) {
+                    // best-effort close
+                }
+            }
+        }
+    }
+
+    public synchronized boolean remove(String key) {
+        File file = fileForKey(key);
+        if (!file.exists()) {
+            return false;
+        }
+        return file.delete();
+    }
+
+    /**
+     * Delete all stored entries. {@code prefix}, when non-null, restricts the
+     * delete to keys whose (decoded) name starts with the prefix.
+     */
+    public synchronized boolean clear(String prefix) {
+        File[] files = baseDir.listFiles();
+        if (files == null) {
+            return true;
+        }
+        boolean ok = true;
+        for (File file : files) {
+            // Skips the staging subdirectory (and any other non-file entry).
+            if (!file.isFile()) {
+                continue;
+            }
+            if (prefix == null || decodeKey(file.getName()).startsWith(prefix)) {
+                if (!file.delete()) {
+                    ok = false;
+                }
+            }
+        }
+        // On a full clear, also drop any orphaned in-flight temp files.
+        if (prefix == null) {
+            File[] temps = stagingDir.listFiles();
+            if (temps != null) {
+                for (File t : temps) {
+                    t.delete();
+                }
+            }
+        }
+        return ok;
+    }
+
+    public synchronized List<String> keys(String pattern) {
+        List<String> keys = new ArrayList<>();
+        File[] files = baseDir.listFiles();
+        if (files == null) {
+            return keys;
+        }
+        for (File file : files) {
+            // Skips the staging subdirectory (and any other non-file entry).
+            if (!file.isFile()) {
+                continue;
+            }
+            String key = decodeKey(file.getName());
+            if (pattern == null || key.contains(pattern)) {
+                keys.add(key);
+            }
+        }
+        return keys;
+    }
+
+    public synchronized boolean has(String key) {
+        File file = fileForKey(key);
+        return file.exists() && file.isFile();
+    }
+
+    /**
+     * Size information. {@code total} = {@code keys} + {@code values} (matching
+     * the web adapters' convention), {@code values} = Σ file byte sizes,
+     * {@code keys} = Σ decoded-key byte lengths, {@code metadata} = Σ length of
+     * the parsed {@code metadata} field (0 when absent or unparseable),
+     * {@code count} = number of stored files. The detailed breakdown is only
+     * surfaced to JS when {@code detailed} is true.
+     */
+    public synchronized SQLiteStorage.SizeInfo size(boolean detailed) {
+        File[] files = baseDir.listFiles();
+        long valuesBytes = 0;
+        long keysBytes = 0;
+        long metadataBytes = 0;
+        int count = 0;
+
+        if (files != null) {
+            for (File file : files) {
+                // Skips the staging subdirectory (and any other non-file entry).
+                if (!file.isFile()) {
+                    continue;
+                }
+                count++;
+                valuesBytes += file.length();
+                keysBytes += decodeKey(file.getName()).getBytes(StandardCharsets.UTF_8).length;
+                if (detailed) {
+                    metadataBytes += metadataByteLength(file);
+                }
+            }
+        }
+
+        if (!detailed) {
+            return new SQLiteStorage.SizeInfo(keysBytes + valuesBytes, count);
+        }
+        return new SQLiteStorage.SizeInfo(keysBytes + valuesBytes, count, keysBytes, valuesBytes, metadataBytes);
+    }
+
+    /** Parse the file and return the byte length of its {@code metadata} field. */
+    private long metadataByteLength(File file) {
+        try {
+            JSObject wrapper = new JSObject(readFile(file));
+            Object metadata = wrapper.opt("metadata");
+            if (metadata != null && metadata != org.json.JSONObject.NULL) {
+                return metadata.toString().getBytes(StandardCharsets.UTF_8).length;
+            }
+        } catch (Exception ignored) {
+            // Unparseable → contributes 0 metadata bytes.
+        }
+        return 0;
+    }
+
+    private String readFile(File file) throws IOException {
+        byte[] data = new byte[(int) file.length()];
+        java.io.FileInputStream fis = null;
+        try {
+            fis = new java.io.FileInputStream(file);
+            int offset = 0;
+            int read;
+            while (offset < data.length
+                    && (read = fis.read(data, offset, data.length - offset)) != -1) {
+                offset += read;
+            }
+        } finally {
+            if (fis != null) {
+                fis.close();
+            }
+        }
+        return new String(data, StandardCharsets.UTF_8);
+    }
+}