strata-storage 2.6.1 → 2.7.0

package/dist/core/StorageStrategy.js

@@ -1,200 +0,0 @@
-/**
- * Storage strategy implementation for automatic adapter selection
- */
-import { StorageStrategy } from '@/types';
-import { AdapterRegistry } from "./AdapterRegistry.js";
-/**
- * Strategy manager for selecting appropriate storage adapters
- */
-export class StrategyManager {
-    registry;
-    strategy;
-    constructor(registry, strategy = StorageStrategy.PERFORMANCE_FIRST) {
-        this.registry = registry;
-        this.strategy = strategy;
-    }
-    /**
-     * Get the best adapter based on current strategy
-     */
-    async getBestAdapter(preferredTypes, requirements) {
-        const available = await this.registry.getAvailable();
-        // Filter by preferred types if specified
-        let candidates = preferredTypes
-            ? available.filter((adapter) => preferredTypes.includes(adapter.name))
-            : available;
-        // Filter by requirements
-        if (requirements) {
-            candidates = candidates.filter((adapter) => this.meetsRequirements(adapter.capabilities, requirements));
-        }
-        // Sort by strategy
-        candidates.sort((a, b) => this.compareAdapters(a, b));
-        return candidates[0] || null;
-    }
-    /**
-     * Get multiple adapters sorted by preference
-     */
-    async getAdapterChain(count, preferredTypes, requirements) {
-        const available = await this.registry.getAvailable();
-        let candidates = preferredTypes
-            ? available.filter((adapter) => preferredTypes.includes(adapter.name))
-            : available;
-        if (requirements) {
-            candidates = candidates.filter((adapter) => this.meetsRequirements(adapter.capabilities, requirements));
-        }
-        candidates.sort((a, b) => this.compareAdapters(a, b));
-        return candidates.slice(0, count);
-    }
-    /**
-     * Check if capabilities meet requirements
-     */
-    meetsRequirements(capabilities, requirements) {
-        for (const [key, value] of Object.entries(requirements)) {
-            const capKey = key;
-            if (typeof value === 'boolean' && capabilities[capKey] !== value) {
-                return false;
-            }
-            if (capKey === 'maxSize' && typeof value === 'number') {
-                const capSize = capabilities.maxSize;
-                if (capSize !== -1 && capSize < value) {
-                    return false;
-                }
-            }
-        }
-        return true;
-    }
-    /**
-     * Compare two adapters based on current strategy
-     */
-    compareAdapters(a, b) {
-        switch (this.strategy) {
-            case StorageStrategy.PERFORMANCE_FIRST:
-                return this.comparePerformance(a, b);
-            case StorageStrategy.PERSISTENCE_FIRST:
-                return this.comparePersistence(a, b);
-            case StorageStrategy.SECURITY_FIRST:
-                return this.compareSecurity(a, b);
-            case StorageStrategy.CAPACITY_FIRST:
-                return this.compareCapacity(a, b);
-            default:
-                return 0;
-        }
-    }
-    /**
-     * Compare adapters by performance
-     */
-    comparePerformance(a, b) {
-        // Priority order for performance
-        const performanceOrder = [
-            'memory',
-            'sessionStorage',
-            'localStorage',
-            'cache',
-            'indexedDB',
-            'preferences',
-            'sqlite',
-            'filesystem',
-            'cookies',
-            'secure',
-        ];
-        const aIndex = performanceOrder.indexOf(a.name);
-        const bIndex = performanceOrder.indexOf(b.name);
-        // Prefer synchronous adapters for performance
-        if (a.capabilities.synchronous !== b.capabilities.synchronous) {
-            return a.capabilities.synchronous ? -1 : 1;
-        }
-        return aIndex - bIndex;
-    }
-    /**
-     * Compare adapters by persistence
-     */
-    comparePersistence(a, b) {
-        // Prefer persistent storage
-        if (a.capabilities.persistent !== b.capabilities.persistent) {
-            return a.capabilities.persistent ? -1 : 1;
-        }
-        // Priority order for persistence
-        const persistenceOrder = [
-            'sqlite',
-            'filesystem',
-            'secure',
-            'indexedDB',
-            'preferences',
-            'localStorage',
-            'cache',
-            'cookies',
-            'sessionStorage',
-            'memory',
-        ];
-        const aIndex = persistenceOrder.indexOf(a.name);
-        const bIndex = persistenceOrder.indexOf(b.name);
-        return aIndex - bIndex;
-    }
-    /**
-     * Compare adapters by security
-     */
-    compareSecurity(a, b) {
-        // Prefer encrypted storage
-        if (a.capabilities.encrypted !== b.capabilities.encrypted) {
-            return a.capabilities.encrypted ? -1 : 1;
-        }
-        // Priority order for security
-        const securityOrder = [
-            'secure',
-            'preferences',
-            'sqlite',
-            'indexedDB',
-            'filesystem',
-            'localStorage',
-            'sessionStorage',
-            'cache',
-            'memory',
-            'cookies',
-        ];
-        const aIndex = securityOrder.indexOf(a.name);
-        const bIndex = securityOrder.indexOf(b.name);
-        return aIndex - bIndex;
-    }
-    /**
-     * Compare adapters by capacity
-     */
-    compareCapacity(a, b) {
-        // Compare max sizes (-1 means unlimited)
-        const aSize = a.capabilities.maxSize;
-        const bSize = b.capabilities.maxSize;
-        if (aSize === -1 && bSize !== -1)
-            return -1;
-        if (bSize === -1 && aSize !== -1)
-            return 1;
-        if (aSize !== -1 && bSize !== -1) {
-            return bSize - aSize; // Higher capacity first
-        }
-        // Priority order for capacity
-        const capacityOrder = [
-            'filesystem',
-            'sqlite',
-            'indexedDB',
-            'cache',
-            'preferences',
-            'secure',
-            'localStorage',
-            'memory',
-            'sessionStorage',
-            'cookies',
-        ];
-        const aIndex = capacityOrder.indexOf(a.name);
-        const bIndex = capacityOrder.indexOf(b.name);
-        return aIndex - bIndex;
-    }
-    /**
-     * Update strategy
-     */
-    setStrategy(strategy) {
-        this.strategy = strategy;
-    }
-    /**
-     * Get current strategy
-     */
-    getStrategy() {
-        return this.strategy;
-    }
-}

package/dist/ios/AGENTS.md

@@ -1,48 +0,0 @@
-# AGENTS.md — ios/
-
-Last Updated: 2026-05-27
-
-> Agent instructions for iOS native development.
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `Plugin/StrataStoragePlugin.swift` | Capacitor plugin entry |
-| `Plugin/UserDefaultsStorage.swift` | General key-value storage |
-| `Plugin/KeychainStorage.swift` | Secure storage |
-| `Plugin/SQLiteStorage.swift` | SQLite database storage — multi-store (v2.6.0), `database`/`table` options honoured, full `StorageValue` wrapper round-trip, `size(detailed)` supported |
-| `Plugin/FilesystemStorage.swift` | File-per-key native storage under `NSDocumentsDirectory/strata_storage/` (new in v2.6.0); atomic writes via staging rename; `isAvailable()` returns `true` |
-
-## v2.6.0 Notes
-
-- **SQLite multi-store:** `database` option → distinct `.db` file. `table` option → sanitised table identifier `[A-Za-z0-9_]`. Previously both were ignored and all adapters shared one table.
-- **SQLite value shape:** `get` now returns the full `StorageValue` wrapper (`value`, `created`, `updated`, `expires`, `tags`, `metadata`). Corrupt rows are treated as a miss.
-- **SQLite bind safety:** text/blob binds use `SQLITE_TRANSIENT` — removes a latent use-after-free for transient Swift buffers.
-- **FilesystemStorage.swift:** new file. Writes are atomic (staging temp → rename). `keys()` excludes `.staging/` artifacts. `size(detailed: true)` returns `{ keys, values, metadata }`.
-- **Pending on-device verification** — see `docs/guides/platforms/device-verification.md`.
-
-## Agent Rules
-
-### Security (IRON-SOLID)
-- Sensitive data MUST use `KeychainStorage`
-- NEVER store secrets in `UserDefaultsStorage`
-
-### SQL Safety
-- ALWAYS use parameterized queries in `SQLiteStorage`
-- NEVER string-interpolate SQL values
-- Use `SQLITE_TRANSIENT` for text/blob binds
-
-### 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.swift`
-- Each storage backend is a separate Swift file
-- Bridges Capacitor JS calls to native Swift
-- The `CAP_PLUGIN` macro must include every callable method name
-
-### Before Modifying
-- Understand Capacitor plugin protocol
-- Test on iOS simulator after changes; follow device-verification guide

package/dist/ios/CLAUDE.md

@@ -1,84 +0,0 @@
-# CLAUDE.md — ios/
-
-Last Updated: 2026-05-27
-
-## iOS Native Plugin
-
-Swift implementation of native storage backends for Capacitor.
-
-### Files
-
-| File | Purpose |
-|------|---------|
-| `Plugin/StrataStoragePlugin.swift` | Main Capacitor plugin entry point |
-| `Plugin/UserDefaultsStorage.swift` | UserDefaults-based general storage |
-| `Plugin/KeychainStorage.swift` | Keychain-based secure storage |
-| `Plugin/SQLiteStorage.swift` | SQLite database storage (multi-store, v2.6.0) |
-| `Plugin/FilesystemStorage.swift` | File-per-key storage under `NSDocumentsDirectory/strata_storage/` (new in v2.6.0) |
-
-### Configuration
-
-- Pod spec: `StrataStorage.podspec` (root)
-- Minimum iOS version: defined in podspec
-- Language: Swift
-
-## v2.6.0 Changes
-
-### SQLite multi-store
-`SQLiteStorage.swift` now accepts `database` and `table` parameters from the
-Capacitor call options. Each unique `(database, table)` pair opens a separate
-`.db` file in the app's documents directory. Table identifiers are sanitised to
-`[A-Za-z0-9_]` before use in SQL. The full `StorageValue` wrapper is serialised
-to JSON and stored in a single `value` column; native `get` deserialises and
-returns the full wrapper so TTL, tags, and metadata survive the round-trip.
-Text/blob binds use `SQLITE_TRANSIENT` (removes a latent use-after-free for
-transient Swift buffers). `size(detailed: true)` returns per-column byte
-breakdown.
-
-### FilesystemStorage.swift (new)
-Stores each key as `NSDocumentsDirectory/strata_storage/<sanitised-key>.json`.
-Writes are atomic: the value is first written to
-`strata_storage/.staging/<key>.tmp`, then renamed into place. Temp files live in
-the staging subdirectory, so they are never exposed by `keys()` and are not
-deleted by a targeted `remove()`. `isAvailable()` returns `true` on device.
-`size(detailed: true)` 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 `KeychainStorage`
-- NEVER store credentials, tokens, or secrets in `UserDefaultsStorage`
-- Keychain items should use appropriate access control flags
-
-### Plugin Architecture
-- All native methods are exposed through `StrataStoragePlugin.swift`
-- Plugin bridges Capacitor JS calls to native Swift implementations
-- Each storage backend is a separate Swift file
-- The `CAP_PLUGIN` macro must list every callable method; missing entries cause
-  silent `undefined` returns on the JS side
-
-### SQLite
-- `SQLiteStorage.swift` opens or creates the `.db` file identified by the
-  `database` call option (default `strata_storage.db`)
-- Handles table creation, migrations, and CRUD operations
-- Use parameterized queries — NEVER string-interpolate SQL
-- Use `SQLITE_TRANSIENT` for text/blob binds
-
-### Filesystem
-- Key strings are sanitised before use as filenames (`/` → `_`, etc.)
-- Staging renames ensure atomic writes; never read from `.staging/`
-- `keys()` lists `.json` files only, ignoring staging artifacts
-
-### Testing
-- Native code is tested through the Capacitor bridge
-- Test via the demo app on iOS simulator following
-  `docs/guides/platforms/device-verification.md`
-- Verify all adapter methods work end-to-end
-
-### Before Modifying
-- Understand the Capacitor plugin protocol
-- Test on iOS simulator after changes
-- Verify podspec still resolves

package/dist/ios/Plugin/FilesystemStorage.swift

@@ -1,218 +0,0 @@
-import Foundation
-import os.log
-
-/**
- * Filesystem-backed storage: one file per key under
- * `<Documents>/strata_storage/`.
- *
- * Value-shape contract (matches src/plugin/definitions.ts, same as SQLite):
- * - File contents are the JSON-serialized FULL `StorageValue` wrapper
- *   `{ value, created, updated, expires?, tags?, metadata?, ... }`.
- * - `get` parses the bytes back into the wrapper object; the plugin resolves
- *   `{ value: wrapper }`. Missing file OR non-object bytes → miss (no crash).
- *
- * File naming: the storage key is percent-encoded with an allowed set that
- * EXCLUDES `/` (and `%`), so the encoding is reversible and never escapes the
- * storage directory. `decodeFileName` reverses it for `keys()`.
- *
- * Durability: writes go to a temp file in the same directory and are then
- * atomically replaced into place, so a crash mid-write cannot leave a torn
- * file at the real path.
- */
-@objc public class FilesystemStorage: NSObject {
-    private let directory: URL
-    private let stagingDirectory: URL
-    private let logger = OSLog(subsystem: "com.strata.storage", category: "FilesystemStorage")
-
-    /// Reserved staging subdirectory name (inside the storage dir) holding
-    /// in-flight temp files for atomic writes. Enumeration skips it by name, so
-    /// a temp file can never collide with an encoded key file (e.g. a real key
-    /// literally named ".tmp-x").
-    private static let stagingDirName = ".strata-staging"
-
-    /// Characters allowed verbatim in an on-disk file name. Anything else
-    /// (notably `/` and `%`) is percent-escaped, keeping the name reversible
-    /// and confined to a single path component.
-    private static let fileNameAllowed: CharacterSet = {
-        var set = CharacterSet.alphanumerics
-        set.insert(charactersIn: "-_. ")
-        return set
-    }()
-
-    @objc public override init() {
-        let base = (try? FileManager.default.url(
-            for: .documentDirectory, in: .userDomainMask, appropriateFor: nil, create: true
-        )) ?? URL(fileURLWithPath: NSTemporaryDirectory())
-        let storageDir = base.appendingPathComponent("strata_storage", isDirectory: true)
-        self.directory = storageDir
-        self.stagingDirectory = storageDir.appendingPathComponent(FilesystemStorage.stagingDirName, isDirectory: true)
-        super.init()
-        ensureDirectory()
-    }
-
-    private func ensureDirectory() {
-        for dir in [directory, stagingDirectory] {
-            if !FileManager.default.fileExists(atPath: dir.path) {
-                do {
-                    try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
-                } catch {
-                    os_log("Failed to create filesystem storage dir: %{public}@", log: logger, type: .error, error.localizedDescription)
-                }
-            }
-        }
-    }
-
-    /// Reversible encoding of a storage key → safe single-component file name.
-    private func encodeFileName(_ key: String) -> String {
-        // addingPercentEncoding only returns nil for invalid unichar sequences,
-        // which a Swift String key cannot contain; fall back defensively.
-        return key.addingPercentEncoding(withAllowedCharacters: FilesystemStorage.fileNameAllowed) ?? key
-    }
-
-    /// Reverses `encodeFileName`. Returns nil if the name cannot be decoded.
-    private func decodeFileName(_ name: String) -> String? {
-        return name.removingPercentEncoding
-    }
-
-    private func fileURL(forKey key: String) -> URL {
-        return directory.appendingPathComponent(encodeFileName(key), isDirectory: false)
-    }
-
-    /**
-     * Persist the full `StorageValue` wrapper for `key`. The wrapper is
-     * JSON-encoded and written atomically (temp file + replace).
-     */
-    @objc public func set(key: String, wrapper: [String: Any]) throws -> Bool {
-        ensureDirectory()
-        let data = try JSONSerialization.data(withJSONObject: wrapper, options: [])
-        let target = fileURL(forKey: key)
-
-        // Atomic write: stage to a unique temp file in the reserved staging
-        // subdir (same volume → atomic rename), then replace. The staging subdir
-        // keeps temp names out of the key namespace entirely.
-        let temp = stagingDirectory.appendingPathComponent(UUID().uuidString, isDirectory: false)
-        do {
-            try data.write(to: temp, options: .atomic)
-            if FileManager.default.fileExists(atPath: target.path) {
-                _ = try FileManager.default.replaceItemAt(target, withItemAt: temp)
-            } else {
-                try FileManager.default.moveItem(at: temp, to: target)
-            }
-        } catch {
-            // Clean up the temp file on any failure so we don't leak partials.
-            try? FileManager.default.removeItem(at: temp)
-            throw error
-        }
-        return true
-    }
-
-    /**
-     * Read the wrapper object for `key`. Missing file OR bytes that are not a
-     * JSON object → nil (treated as a miss; never throws on corrupt data).
-     */
-    @objc public func get(key: String) -> [String: Any]? {
-        let url = fileURL(forKey: key)
-        guard let data = try? Data(contentsOf: url) else {
-            return nil
-        }
-        guard let wrapper = try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] else {
-            return nil
-        }
-        return wrapper
-    }
-
-    @objc public func remove(key: String) -> Bool {
-        let url = fileURL(forKey: key)
-        if !FileManager.default.fileExists(atPath: url.path) {
-            return true // already absent — treat as success/idempotent
-        }
-        do {
-            try FileManager.default.removeItem(at: url)
-            return true
-        } catch {
-            os_log("Failed to remove filesystem key: %{public}@", log: logger, type: .error, error.localizedDescription)
-            return false
-        }
-    }
-
-    /// Clears stored entries. When `prefix` is set, only keys starting with it
-    /// are removed; otherwise the whole storage directory contents are removed.
-    @objc public func clear(prefix: String? = nil) -> Bool {
-        let names = (try? FileManager.default.contentsOfDirectory(atPath: directory.path)) ?? []
-        var ok = true
-        for name in names {
-            // Skip the staging subdirectory (never a key).
-            if name == FilesystemStorage.stagingDirName { continue }
-            guard let key = decodeFileName(name) else { continue }
-            if let prefix = prefix, !key.hasPrefix(prefix) { continue }
-            do {
-                try FileManager.default.removeItem(at: directory.appendingPathComponent(name, isDirectory: false))
-            } catch {
-                ok = false
-            }
-        }
-        // On a full clear, also drop any orphaned in-flight temp files.
-        if prefix == nil, let temps = try? FileManager.default.contentsOfDirectory(atPath: stagingDirectory.path) {
-            for temp in temps {
-                try? FileManager.default.removeItem(at: stagingDirectory.appendingPathComponent(temp, isDirectory: false))
-            }
-        }
-        return ok
-    }
-
-    /// Lists stored keys, decoding file names back to their original keys.
-    /// When `pattern` is set, applies the same prefix/contains matching the
-    /// other backends use.
-    @objc public func keys(pattern: String? = nil) -> [String] {
-        let names = (try? FileManager.default.contentsOfDirectory(atPath: directory.path)) ?? []
-        var keys: [String] = []
-        for name in names {
-            if name == FilesystemStorage.stagingDirName { continue }
-            guard let key = decodeFileName(name) else { continue }
-            keys.append(key)
-        }
-        guard let pattern = pattern else { return keys }
-        return keys.filter { $0.hasPrefix(pattern) || $0.contains(pattern) }
-    }
-
-    /**
-     * Aggregate sizes over the storage directory.
-     *
-     * `count` = number of entry files; `values` = sum of file byte sizes;
-     * `keys` = sum of decoded-key UTF-8 byte lengths; `metadata` = sum of the
-     * serialized `metadata` segment per file (0 when absent or unparseable);
-     * `total` = `keys` + `values`.
-     */
-    @objc public func size() -> [String: Int] {
-        let names = (try? FileManager.default.contentsOfDirectory(atPath: directory.path)) ?? []
-        var count = 0
-        var keysSize = 0
-        var valuesSize = 0
-        var metadataSize = 0
-
-        for name in names {
-            if name == FilesystemStorage.stagingDirName { continue }
-            guard let key = decodeFileName(name) else { continue }
-            let url = directory.appendingPathComponent(name, isDirectory: false)
-            count += 1
-            keysSize += key.data(using: .utf8)?.count ?? 0
-
-            if let data = try? Data(contentsOf: url) {
-                valuesSize += data.count
-                if let wrapper = try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any],
-                   let metadata = wrapper["metadata"],
-                   let metadataData = try? JSONSerialization.data(withJSONObject: metadata, options: []) {
-                    metadataSize += metadataData.count
-                }
-            }
-        }
-
-        return [
-            "count": count,
-            "keys": keysSize,
-            "values": valuesSize,
-            "metadata": metadataSize,
-            "total": keysSize + valuesSize
-        ]
-    }
-}