strata-storage 2.4.3 → 2.6.0

package/dist/ios/Plugin/StrataStoragePlugin.swift

@@ -3,93 +3,159 @@ import Capacitor
 
 /**
  * Main Capacitor plugin for Strata Storage
- * Coordinates between different storage types on iOS
+ * Coordinates between different storage types on iOS.
+ *
+ * NOTE: Method registration with the Capacitor bridge lives in
+ * StrataStoragePlugin.m (CAP_PLUGIN / CAP_PLUGIN_METHOD). Keep the two in
+ * sync when adding or renaming methods.
  */
 @objc(StrataStoragePlugin)
 public class StrataStoragePlugin: CAPPlugin {
     private let userDefaultsStorage = UserDefaultsStorage()
     private let keychainStorage = KeychainStorage()
-    private let sqliteStorage = SQLiteStorage()
-    
+    private let filesystemStorage = FilesystemStorage()
+
+    /// Storage types that have a real native backend on iOS.
+    private let supportedStorageTypes: Set<String> = ["preferences", "secure", "sqlite", "filesystem"]
+
+    // MARK: - SQLite multi-store helpers
+
+    /// Default database name (→ file `strata_storage.db`) and table.
+    private static let defaultDatabase = "strata_storage"
+    private static let defaultTable = "storage"
+
+    /// Sanitizes a database name into a safe `.db` filename. Strips everything
+    /// outside `[A-Za-z0-9_]` (which also blocks path separators / traversal),
+    /// then appends `.db`. Empty input falls back to the default. The filename
+    /// CANNOT be a bound parameter, so it must be sanitized before use.
+    private func sqliteFileName(from database: String?) -> String {
+        let raw = database ?? StrataStoragePlugin.defaultDatabase
+        let cleaned = String(raw.unicodeScalars.filter { CharacterSet(charactersIn: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_").contains($0) })
+        let safe = cleaned.isEmpty ? StrataStoragePlugin.defaultDatabase : cleaned
+        return "\(safe).db"
+    }
+
+    /// Sanitizes a table name to a safe SQL identifier matching `^[A-Za-z0-9_]+$`.
+    /// Disallowed characters are removed; empty input falls back to the default.
+    /// The table name is interpolated into SQL (it cannot be bound), so this is
+    /// the single point that guarantees injection-safety for the identifier.
+    private func sqliteTableName(from table: String?) -> String {
+        let raw = table ?? StrataStoragePlugin.defaultTable
+        let cleaned = String(raw.unicodeScalars.filter { CharacterSet(charactersIn: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_").contains($0) })
+        return cleaned.isEmpty ? StrataStoragePlugin.defaultTable : cleaned
+    }
+
+    /// Returns the cached SQLite store for the call's `database` option.
+    private func sqliteStore(for call: CAPPluginCall) -> SQLiteStorage {
+        return SQLiteStorageManager.shared.store(forFile: sqliteFileName(from: call.getString("database")))
+    }
+
     /**
-     * Check if storage is available
+     * Check if a specific storage type is available.
+     * Matches the JS contract: resolves `{ available: boolean }`.
      */
     @objc func isAvailable(_ call: CAPPluginCall) {
+        let storage = call.getString("storage") ?? "preferences"
         call.resolve([
-            "available": true,
-            "platform": "ios",
-            "adapters": [
-                "preferences": true,
-                "secure": true,
-                "sqlite": true,
-                "filesystem": true
-            ]
+            "available": supportedStorageTypes.contains(storage)
         ])
     }
-    
+
     /**
-     * Get value from storage
+     * Get value from storage.
+     * For sqlite/filesystem the resolved `value` is the full StorageValue
+     * wrapper object (or NSNull on a miss).
      */
     @objc func get(_ call: CAPPluginCall) {
         guard let key = call.getString("key") else {
             call.reject("Key is required")
             return
         }
-        
+
         let storage = call.getString("storage") ?? "preferences"
-        
+
         do {
             let value: Any?
-            
+
             switch storage {
             case "secure":
                 value = try keychainStorage.get(key: key)
             case "sqlite":
-                value = try sqliteStorage.get(key: key)
+                value = sqliteStore(for: call).get(table: sqliteTableName(from: call.getString("table")), key: key)
+            case "filesystem":
+                value = filesystemStorage.get(key: key)
             case "preferences":
                 fallthrough
             default:
                 value = userDefaultsStorage.get(key: key)
             }
-            
+
             call.resolve([
                 "value": value ?? NSNull()
             ])
         } catch {
-            call.reject("Failed to get value", error.localizedDescription)
+            call.reject("Failed to get value", nil, error)
         }
     }
-    
+
     /**
-     * Set value in storage
+     * Set value in storage.
+     * For sqlite/filesystem the `value` option is the full StorageValue
+     * wrapper object and is stored verbatim (JSON) for a perfect round-trip.
      */
     @objc func set(_ call: CAPPluginCall) {
         guard let key = call.getString("key") else {
             call.reject("Key is required")
             return
         }
-        
-        let value = call.getValue("value") ?? NSNull()
+
         let storage = call.getString("storage") ?? "preferences"
-        
+
         do {
             switch storage {
             case "secure":
-                try keychainStorage.set(key: key, value: value)
+                let value = call.getValue("value") ?? NSNull()
+                _ = try keychainStorage.set(key: key, value: value)
             case "sqlite":
-                try sqliteStorage.set(key: key, value: value)
+                // getObject returns JSObject ([String: JSValue]); upcast each
+                // value to Any (the canonical Capacitor pattern) so the bridged
+                // Foundation values are JSONSerialization-compatible.
+                guard let jsObject = call.getObject("value") else {
+                    call.reject("SQLite value must be a StorageValue object")
+                    return
+                }
+                let ok = try sqliteStore(for: call).set(
+                    table: sqliteTableName(from: call.getString("table")),
+                    key: key,
+                    wrapper: jsObject as [String: Any]
+                )
+                if !ok {
+                    call.reject("Failed to write value to SQLite")
+                    return
+                }
+            case "filesystem":
+                guard let jsObject = call.getObject("value") else {
+                    call.reject("Filesystem value must be a StorageValue object")
+                    return
+                }
+                let ok = try filesystemStorage.set(key: key, wrapper: jsObject as [String: Any])
+                if !ok {
+                    call.reject("Failed to write value to filesystem")
+                    return
+                }
             case "preferences":
                 fallthrough
             default:
+                let value = call.getValue("value") ?? NSNull()
                 userDefaultsStorage.set(key: key, value: value)
             }
-            
+
             call.resolve()
         } catch {
-            call.reject("Failed to set value", error.localizedDescription)
+            call.reject("Failed to set value", nil, error)
         }
     }
-    
+
     /**
      * Remove value from storage
      */
@@ -98,107 +164,248 @@ public class StrataStoragePlugin: CAPPlugin {
             call.reject("Key is required")
             return
         }
-        
+
         let storage = call.getString("storage") ?? "preferences"
-        
+
         do {
             switch storage {
             case "secure":
-                try keychainStorage.remove(key: key)
+                _ = try keychainStorage.remove(key: key)
             case "sqlite":
-                try sqliteStorage.remove(key: key)
+                _ = sqliteStore(for: call).remove(table: sqliteTableName(from: call.getString("table")), key: key)
+            case "filesystem":
+                _ = filesystemStorage.remove(key: key)
             case "preferences":
                 fallthrough
             default:
                 userDefaultsStorage.remove(key: key)
             }
-            
+
             call.resolve()
         } catch {
-            call.reject("Failed to remove value", error.localizedDescription)
+            call.reject("Failed to remove value", nil, error)
         }
     }
-    
+
     /**
-     * Clear storage
+     * Clear storage.
+     * The JS contract sends an optional `pattern`. The native backends accept
+     * a prefix; we use `pattern` as that prefix (prefix/contains matching).
      */
     @objc func clear(_ call: CAPPluginCall) {
         let storage = call.getString("storage") ?? "preferences"
-        let prefix = call.getString("prefix")
-        
+        // Accept both `pattern` (JS contract) and legacy `prefix`.
+        let prefix = call.getString("pattern") ?? call.getString("prefix")
+
         do {
             switch storage {
             case "secure":
-                try keychainStorage.clear(prefix: prefix)
+                _ = try keychainStorage.clear(prefix: prefix)
             case "sqlite":
-                try sqliteStorage.clear(prefix: prefix)
+                _ = sqliteStore(for: call).clear(table: sqliteTableName(from: call.getString("table")), prefix: prefix)
+            case "filesystem":
+                _ = filesystemStorage.clear(prefix: prefix)
             case "preferences":
                 fallthrough
             default:
                 userDefaultsStorage.clear(prefix: prefix)
             }
-            
+
             call.resolve()
         } catch {
-            call.reject("Failed to clear storage", error.localizedDescription)
+            call.reject("Failed to clear storage", nil, error)
         }
     }
-    
+
     /**
      * Get all keys from storage
      */
     @objc func keys(_ call: CAPPluginCall) {
         let storage = call.getString("storage") ?? "preferences"
         let pattern = call.getString("pattern")
-        
+
         do {
             let keys: [String]
-            
+
             switch storage {
             case "secure":
                 keys = try keychainStorage.keys(pattern: pattern)
             case "sqlite":
-                keys = try sqliteStorage.keys(pattern: pattern)
+                keys = sqliteStore(for: call).keys(table: sqliteTableName(from: call.getString("table")), pattern: pattern)
+            case "filesystem":
+                keys = filesystemStorage.keys(pattern: pattern)
             case "preferences":
                 fallthrough
             default:
                 keys = userDefaultsStorage.keys(pattern: pattern)
             }
-            
+
             call.resolve([
                 "keys": keys
             ])
         } catch {
-            call.reject("Failed to get keys", error.localizedDescription)
+            call.reject("Failed to get keys", nil, error)
         }
     }
-    
+
     /**
-     * Get storage size information
+     * Get storage size information.
+     * When `detailed` is true, resolves `{ total, count, detailed: { keys,
+     * values, metadata } }`; otherwise `{ total, count }`.
      */
     @objc func size(_ call: CAPPluginCall) {
         let storage = call.getString("storage") ?? "preferences"
-        
+        let detailed = call.getBool("detailed") ?? false
+
         do {
-            let sizeInfo: (total: Int, count: Int)
-            
+            // segments carries total/count/keys/values/metadata in bytes.
+            let segments: [String: Int]
+
             switch storage {
             case "secure":
-                sizeInfo = try keychainStorage.size()
+                let info = try keychainStorage.size()
+                segments = ["total": info.total, "count": info.count, "keys": 0, "values": info.total, "metadata": 0]
             case "sqlite":
-                sizeInfo = try sqliteStorage.size()
+                segments = try sqliteStore(for: call).size(table: sqliteTableName(from: call.getString("table")))
+            case "filesystem":
+                segments = filesystemStorage.size()
             case "preferences":
                 fallthrough
             default:
-                sizeInfo = userDefaultsStorage.size()
+                let info = userDefaultsStorage.size()
+                segments = ["total": info.total, "count": info.count, "keys": 0, "values": info.total, "metadata": 0]
             }
-            
-            call.resolve([
-                "total": sizeInfo.total,
-                "count": sizeInfo.count
-            ])
+
+            var result: [String: Any] = [
+                "total": segments["total"] ?? 0,
+                "count": segments["count"] ?? 0
+            ]
+            if detailed {
+                result["detailed"] = [
+                    "keys": segments["keys"] ?? 0,
+                    "values": segments["values"] ?? 0,
+                    "metadata": segments["metadata"] ?? 0
+                ]
+            }
+            call.resolve(result)
+        } catch {
+            call.reject("Failed to get size", nil, error)
+        }
+    }
+
+    /**
+     * Query SQLite-backed storage.
+     * Matches the optional `query` method in the JS contract:
+     * resolves `{ results: [{ key }] }` (JS re-fetches each value via get).
+     */
+    @objc func query(_ call: CAPPluginCall) {
+        let storage = call.getString("storage") ?? "sqlite"
+
+        guard storage == "sqlite" else {
+            call.reject("Query is only supported for the 'sqlite' storage type")
+            return
+        }
+
+        let condition = call.getObject("condition") ?? [:]
+        let results = sqliteStore(for: call).query(
+            table: sqliteTableName(from: call.getString("table")),
+            condition: condition
+        )
+        call.resolve([
+            "results": results
+        ])
+    }
+
+    /**
+     * iOS-specific: read a UserDefaults value.
+     * Resolves `{ value: unknown }`.
+     */
+    @objc func getUserDefaults(_ call: CAPPluginCall) {
+        guard let key = call.getString("key") else {
+            call.reject("Key is required")
+            return
+        }
+        let suiteName = call.getString("suiteName")
+        let store = suiteName != nil ? UserDefaultsStorage(suiteName: suiteName) : userDefaultsStorage
+        call.resolve([
+            "value": store.get(key: key) ?? NSNull()
+        ])
+    }
+
+    /**
+     * iOS-specific: write a UserDefaults value.
+     */
+    @objc func setUserDefaults(_ call: CAPPluginCall) {
+        guard let key = call.getString("key") else {
+            call.reject("Key is required")
+            return
+        }
+        let value = call.getValue("value") ?? NSNull()
+        let suiteName = call.getString("suiteName")
+        let store = suiteName != nil ? UserDefaultsStorage(suiteName: suiteName) : userDefaultsStorage
+        _ = store.set(key: key, value: value)
+        call.resolve()
+    }
+
+    /**
+     * iOS-specific: read a Keychain value. Resolves `{ value: string | null }`.
+     */
+    @objc func getKeychain(_ call: CAPPluginCall) {
+        guard let key = call.getString("key") else {
+            call.reject("Key is required")
+            return
+        }
+        let service = call.getString("service")
+        let accessGroup = call.getString("accessGroup")
+        let store = (service != nil || accessGroup != nil)
+            ? KeychainStorage(service: service, accessGroup: accessGroup)
+            : keychainStorage
+
+        do {
+            let value = try store.get(key: key)
+            // The JS contract types this as `string | null`. Serialize
+            // non-string values to a JSON string so the bridge stays typed.
+            if let value = value {
+                if let str = value as? String {
+                    call.resolve(["value": str])
+                } else if let data = try? JSONSerialization.data(withJSONObject: value, options: []),
+                          let str = String(data: data, encoding: .utf8) {
+                    call.resolve(["value": str])
+                } else {
+                    call.resolve(["value": NSNull()])
+                }
+            } else {
+                call.resolve(["value": NSNull()])
+            }
+        } catch {
+            call.reject("Failed to read keychain item", nil, error)
+        }
+    }
+
+    /**
+     * iOS-specific: write a Keychain value, honoring the `accessible` option.
+     */
+    @objc func setKeychain(_ call: CAPPluginCall) {
+        guard let key = call.getString("key") else {
+            call.reject("Key is required")
+            return
+        }
+        guard let value = call.getString("value") else {
+            call.reject("Value is required and must be a string")
+            return
+        }
+        let service = call.getString("service")
+        let accessGroup = call.getString("accessGroup")
+        let accessible = call.getString("accessible")
+        let store = (service != nil || accessGroup != nil)
+            ? KeychainStorage(service: service, accessGroup: accessGroup)
+            : keychainStorage
+
+        do {
+            _ = try store.set(key: key, value: value, accessible: accessible)
+            call.resolve()
         } catch {
-            call.reject("Failed to get size", error.localizedDescription)
+            call.reject("Failed to write keychain item", nil, error)
         }
     }
-}
+}

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strata-storage",
-  "version": "2.4.3",
+  "version": "2.6.0",
   "description": "Zero-dependency universal storage plugin providing a unified API for all storage operations across web, Android, and iOS platforms",
   "type": "module",
   "main": "./index.js",
@@ -17,6 +17,18 @@
     "./firebase": {
       "types": "./firebase.d.ts",
       "default": "./firebase.js"
+    },
+    "./react": {
+      "types": "./integrations/react/index.d.ts",
+      "default": "./integrations/react/index.js"
+    },
+    "./vue": {
+      "types": "./integrations/vue/index.d.ts",
+      "default": "./integrations/vue/index.js"
+    },
+    "./angular": {
+      "types": "./integrations/angular/index.d.ts",
+      "default": "./integrations/angular/index.js"
     }
   },
   "author": "Ahsan Mahmood",
@@ -45,11 +57,18 @@
   ],
   "peerDependencies": {
     "@angular/core": ">=21.0.6",
+    "@angular/forms": ">=21.0.6",
     "@capacitor/core": ">=8.0.0",
     "react": ">=19.2.3",
     "vue": ">=3.5.26"
   },
   "peerDependenciesMeta": {
+    "@angular/core": {
+      "optional": true
+    },
+    "@angular/forms": {
+      "optional": true
+    },
     "@capacitor/core": {
       "optional": true
     },
@@ -58,9 +77,6 @@
     },
     "vue": {
       "optional": true
-    },
-    "@angular/core": {
-      "optional": true
     }
   },
   "capacitor": {
@@ -74,6 +90,6 @@
   },
   "sideEffects": false,
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=24.13.0"
   }
 }

package/dist/plugin/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugin/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,mBAAmB,EASpB,MAAM,eAAe,CAAC;AA8IvB,eAAO,MAAM,aAAa,EAAE,mBAAmD,CAAC;AAEhF,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugin/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,mBAAmB,EASpB,MAAM,eAAe,CAAC;AA+IvB,eAAO,MAAM,aAAa,EAAE,mBAAmD,CAAC;AAEhF,cAAc,eAAe,CAAC"}

package/dist/plugin/index.js

@@ -4,6 +4,7 @@
  * This is now optional and only loaded when Capacitor adapters are used
  */
 import { NotSupportedError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
 // Mock implementation for when Capacitor is not available
 const mockPlugin = {
     isAvailable: async () => ({ available: false }),
@@ -56,7 +57,7 @@ class LazyStrataStoragePlugin {
                     });
                 }
                 catch (error) {
-                    console.warn('Failed to register StrataStorage plugin:', error);
+                    logger.warn('Failed to register StrataStorage plugin:', error);
                     this.plugin = mockPlugin;
                 }
             }

package/dist/types/index.d.ts

@@ -5,7 +5,7 @@
 /**
  * Supported storage types across all platforms
  */
-export type StorageType = 'memory' | 'localStorage' | 'sessionStorage' | 'indexedDB' | 'cookies' | 'cache' | 'preferences' | 'sqlite' | 'filesystem' | 'secure';
+export type StorageType = 'memory' | 'localStorage' | 'sessionStorage' | 'indexedDB' | 'cookies' | 'cache' | 'url' | 'preferences' | 'sqlite' | 'filesystem' | 'secure';
 /**
  * Platform types
  */
@@ -75,6 +75,20 @@ export interface StorageOptions {
      * Metadata to attach
      */
     metadata?: Record<string, unknown>;
+    /**
+     * Compute + store an integrity checksum for this write and verify it on read.
+     */
+    verify?: boolean;
+    /**
+     * Durable write — read the value back and verify it after writing, retrying
+     * on mismatch. Guards against silent partial writes.
+     */
+    durable?: boolean;
+    /**
+     * On a checksum mismatch during read, return null instead of throwing
+     * IntegrityError (after mirror read-repair has been attempted).
+     */
+    ignoreCorruption?: boolean;
 }
 /**
  * Storage value with metadata
@@ -112,6 +126,11 @@ export interface StorageValue<T = unknown> {
      * Whether value is compressed
      */
     compressed?: boolean;
+    /**
+     * Integrity checksum (FNV-1a) over the stored value, present when integrity
+     * is enabled. Verified on read to detect corruption.
+     */
+    checksum?: string;
 }
 /**
  * Storage change event
@@ -390,6 +409,32 @@ export interface StrataConfig {
          */
         onExpire?: (keys: string[]) => void;
     };
+    /**
+     * Data integrity — compute + verify an FNV-1a checksum on every value so
+     * corruption is detected on read. Off by default.
+     */
+    integrity?: boolean;
+    /**
+     * Durable writes — read back and verify every write, retrying on mismatch.
+     * Off by default (adds one read per write).
+     */
+    durableWrites?: boolean;
+    /**
+     * Mirror every write/remove to these backup storage types. On a primary read
+     * miss or corruption, the value is recovered from a mirror (read-repair).
+     */
+    mirror?: StorageType[];
+    /**
+     * Periodic automatic snapshot of all data to a durable storage type.
+     */
+    autoBackup?: {
+        /** Interval in milliseconds between snapshots. */
+        interval: number;
+        /** Storage type to write the snapshot to. */
+        storage: StorageType;
+        /** Key to store the snapshot under (default `__strata_backup__`). */
+        key?: string;
+    };
     /**
      * Debug configuration
      */
@@ -460,6 +505,18 @@ export interface StorageAdapter {
      * Get all keys
      */
     keys(pattern?: string | RegExp): Promise<string[]>;
+    /** Synchronous get — sync-capable adapters only. */
+    getSync?<T = unknown>(key: string): StorageValue<T> | null;
+    /** Synchronous set — sync-capable adapters only. */
+    setSync?<T = unknown>(key: string, value: StorageValue<T>): void;
+    /** Synchronous remove — sync-capable adapters only. */
+    removeSync?(key: string): void;
+    /** Synchronous existence check — sync-capable adapters only. */
+    hasSync?(key: string): boolean;
+    /** Synchronous keys — sync-capable adapters only. */
+    keysSync?(pattern?: string | RegExp): string[];
+    /** Synchronous clear — sync-capable adapters only. */
+    clearSync?(options?: ClearOptions): void;
     /**
      * Get storage size
      */
@@ -695,14 +752,6 @@ export interface StorageEvent {
      */
     timestamp: number;
 }
-/**
- * Storage error class
- */
-export declare class StorageError extends Error {
-    code?: string | undefined;
-    details?: unknown | undefined;
-    constructor(message: string, code?: string | undefined, details?: unknown | undefined);
-}
 /**
  * Storage metadata
  */