strata-storage 2.4.2 → 2.5.0

package/dist/adapters/web/URLAdapter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * URL Adapter - persists state in the page URL.
+ *
+ * Stores each key as a URL parameter, either in the query string (`?k=v`) or in
+ * the hash fragment (`#k=v`), selectable via config. Useful for shareable /
+ * bookmarkable UI state (filters, tabs, pagination) that should survive reloads
+ * and round-trip through navigation. Inherently synchronous.
+ *
+ * Limitations (documented honestly):
+ * - URLs have practical length limits (~2000 chars in some browsers/servers), so
+ *   this adapter is for small, simple, serializable state — not bulk data.
+ * - Query mode is visible to the server on navigation; hash mode is client-only.
+ * - Not available outside a browser (SSR/Node) — `isAvailable()` returns false.
+ */
+import { BaseAdapter } from '@/core/BaseAdapter';
+import type { StorageType, StorageCapabilities, StorageValue, ClearOptions } from '@/types';
+/** Configuration for the URL adapter. */
+export interface URLAdapterConfig {
+    /** Where to store params: query string (default) or hash fragment. */
+    mode?: 'query' | 'hash';
+    /** Prefix applied to every param name to avoid collisions (default `strata.`). */
+    prefix?: string;
+    /** History strategy when writing (default `replace` — no new history entry). */
+    history?: 'push' | 'replace';
+    /** Soft warning threshold for total URL length in chars (default 2000). */
+    maxLength?: number;
+}
+export declare class URLAdapter extends BaseAdapter {
+    readonly name: StorageType;
+    readonly capabilities: StorageCapabilities;
+    private mode;
+    private prefix;
+    private historyMode;
+    private maxLength;
+    private snapshot;
+    private changeListener?;
+    isAvailable(): Promise<boolean>;
+    initialize(config?: URLAdapterConfig): Promise<void>;
+    getSync<T = unknown>(key: string): StorageValue<T> | null;
+    setSync<T = unknown>(key: string, value: StorageValue<T>): void;
+    removeSync(key: string): void;
+    hasSync(key: string): boolean;
+    keysSync(pattern?: string | RegExp): string[];
+    clearSync(options?: ClearOptions): void;
+    get<T = unknown>(key: string): Promise<StorageValue<T> | null>;
+    set<T = unknown>(key: string, value: StorageValue<T>): Promise<void>;
+    remove(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    keys(pattern?: string | RegExp): Promise<string[]>;
+    clear(options?: ClearOptions): Promise<void>;
+    close(): Promise<void>;
+    private readParams;
+    private writeParams;
+    private estimateLength;
+    private tryDeserialize;
+    private snapshotParams;
+    private handleExternalChange;
+}
+//# sourceMappingURL=URLAdapter.d.ts.map

package/dist/adapters/web/URLAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"URLAdapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/web/URLAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI5F,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,UAAW,SAAQ,WAAW;IACzC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAS;IACnC,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAUxC;IAEF,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,cAAc,CAAC,CAAa;IAE9B,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAQ/B,UAAU,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB1D,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAmBzD,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAmB/D,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAS7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAK7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE;IAU7C,SAAS,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAoCjC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAI9D,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlC,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAIlD,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,WAAW;IAkBnB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,oBAAoB;CAoB7B"}

package/dist/adapters/web/URLAdapter.js

@@ -0,0 +1,234 @@
+/**
+ * URL Adapter - persists state in the page URL.
+ *
+ * Stores each key as a URL parameter, either in the query string (`?k=v`) or in
+ * the hash fragment (`#k=v`), selectable via config. Useful for shareable /
+ * bookmarkable UI state (filters, tabs, pagination) that should survive reloads
+ * and round-trip through navigation. Inherently synchronous.
+ *
+ * Limitations (documented honestly):
+ * - URLs have practical length limits (~2000 chars in some browsers/servers), so
+ *   this adapter is for small, simple, serializable state — not bulk data.
+ * - Query mode is visible to the server on navigation; hash mode is client-only.
+ * - Not available outside a browser (SSR/Node) — `isAvailable()` returns false.
+ */
+import { BaseAdapter } from "../../core/BaseAdapter.js";
+import { serialize, deserialize } from "../../utils/index.js";
+import { logger } from "../../utils/logger.js";
+export class URLAdapter extends BaseAdapter {
+    name = 'url';
+    capabilities = {
+        persistent: false, // lives only as long as the URL does
+        synchronous: true, // URL access is synchronous
+        observable: true, // popstate / hashchange
+        transactional: false,
+        queryable: true, // via BaseAdapter scan
+        maxSize: 2000, // practical URL length budget
+        binary: false,
+        encrypted: false,
+        crossTab: false,
+    };
+    mode = 'query';
+    prefix = 'strata.';
+    historyMode = 'replace';
+    maxLength = 2000;
+    snapshot = new Map();
+    changeListener;
+    async isAvailable() {
+        return (typeof window !== 'undefined' &&
+            typeof window.location !== 'undefined' &&
+            typeof window.history !== 'undefined');
+    }
+    async initialize(config) {
+        if (config?.mode)
+            this.mode = config.mode;
+        if (config?.prefix !== undefined)
+            this.prefix = config.prefix;
+        if (config?.history)
+            this.historyMode = config.history;
+        if (typeof config?.maxLength === 'number')
+            this.maxLength = config.maxLength;
+        if (typeof window === 'undefined')
+            return;
+        // Seed the snapshot and listen for external navigation (back/forward, manual
+        // edits) so subscribers are notified of changes that did not originate here.
+        this.snapshot = this.snapshotParams();
+        this.changeListener = () => this.handleExternalChange();
+        const event = this.mode === 'hash' ? 'hashchange' : 'popstate';
+        window.addEventListener(event, this.changeListener);
+    }
+    // --- Synchronous core ------------------------------------------------------
+    getSync(key) {
+        const raw = this.readParams().get(this.prefix + key);
+        if (raw === null)
+            return null;
+        let value;
+        try {
+            value = deserialize(raw);
+        }
+        catch (error) {
+            logger.debug(`URLAdapter: failed to parse key "${key}"`, error);
+            return null;
+        }
+        if (this.isExpired(value)) {
+            this.removeSync(key);
+            return null;
+        }
+        return value;
+    }
+    setSync(key, value) {
+        const params = this.readParams();
+        const oldRaw = params.get(this.prefix + key);
+        const serialized = serialize(value);
+        params.set(this.prefix + key, serialized);
+        this.writeParams(params);
+        const total = this.estimateLength(params);
+        if (total > this.maxLength) {
+            logger.debug(`URLAdapter: URL length (${total}) exceeds soft limit (${this.maxLength}); ` +
+                `consider a different storage for large values.`);
+        }
+        const oldValue = oldRaw !== null ? this.tryDeserialize(oldRaw) : undefined;
+        this.emitChange(key, oldValue, value.value, 'local');
+    }
+    removeSync(key) {
+        const params = this.readParams();
+        const oldRaw = params.get(this.prefix + key);
+        if (oldRaw === null)
+            return;
+        params.delete(this.prefix + key);
+        this.writeParams(params);
+        this.emitChange(key, this.tryDeserialize(oldRaw), undefined, 'local');
+    }
+    hasSync(key) {
+        const value = this.getSync(key);
+        return value !== null;
+    }
+    keysSync(pattern) {
+        const keys = [];
+        for (const name of this.readParams().keys()) {
+            if (name.startsWith(this.prefix)) {
+                keys.push(name.slice(this.prefix.length));
+            }
+        }
+        return this.filterKeys(keys, pattern);
+    }
+    clearSync(options) {
+        const pattern = options?.pattern || options?.prefix;
+        const params = this.readParams();
+        let changed = false;
+        for (const key of this.keysSync()) {
+            let shouldDelete = true;
+            if (pattern) {
+                shouldDelete = this.filterKeys([key], pattern).length > 0;
+            }
+            if (shouldDelete && options?.tags) {
+                const value = this.getSync(key);
+                if (!value?.tags || !options.tags.some((tag) => value.tags?.includes(tag))) {
+                    shouldDelete = false;
+                }
+            }
+            if (shouldDelete && options?.expiredOnly) {
+                const value = this.getSync(key);
+                if (!value || !this.isExpired(value)) {
+                    shouldDelete = false;
+                }
+            }
+            if (shouldDelete) {
+                params.delete(this.prefix + key);
+                changed = true;
+            }
+        }
+        if (changed) {
+            this.writeParams(params);
+            this.emitChange('*', undefined, undefined, 'local');
+        }
+    }
+    // --- Async API delegates to the synchronous core ---------------------------
+    async get(key) {
+        return this.getSync(key);
+    }
+    async set(key, value) {
+        this.setSync(key, value);
+    }
+    async remove(key) {
+        this.removeSync(key);
+    }
+    async has(key) {
+        return this.hasSync(key);
+    }
+    async keys(pattern) {
+        return this.keysSync(pattern);
+    }
+    async clear(options) {
+        this.clearSync(options);
+    }
+    async close() {
+        if (this.changeListener && typeof window !== 'undefined') {
+            const event = this.mode === 'hash' ? 'hashchange' : 'popstate';
+            window.removeEventListener(event, this.changeListener);
+            this.changeListener = undefined;
+        }
+        await super.close();
+    }
+    // --- Internals -------------------------------------------------------------
+    readParams() {
+        if (typeof window === 'undefined')
+            return new URLSearchParams();
+        if (this.mode === 'hash') {
+            const hash = window.location.hash.replace(/^#/, '');
+            return new URLSearchParams(hash);
+        }
+        return new URLSearchParams(window.location.search);
+    }
+    writeParams(params) {
+        if (typeof window === 'undefined')
+            return;
+        const query = params.toString();
+        if (this.mode === 'hash') {
+            const url = `${window.location.pathname}${window.location.search}${query ? `#${query}` : ''}`;
+            window.history[this.historyMode === 'push' ? 'pushState' : 'replaceState']({}, '', url);
+        }
+        else {
+            const url = new URL(window.location.href);
+            url.search = query;
+            window.history[this.historyMode === 'push' ? 'pushState' : 'replaceState']({}, '', url.toString());
+        }
+    }
+    estimateLength(params) {
+        if (typeof window === 'undefined')
+            return params.toString().length;
+        return `${window.location.origin}${window.location.pathname}?${params.toString()}`.length;
+    }
+    tryDeserialize(raw) {
+        try {
+            return deserialize(raw).value;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // Diff the URL against the last known snapshot and emit per-key changes for
+    // anything that changed externally (back/forward navigation, manual edits).
+    snapshotParams() {
+        const map = new Map();
+        for (const [name, value] of this.readParams().entries()) {
+            map.set(name, value);
+        }
+        return map;
+    }
+    handleExternalChange() {
+        const next = this.snapshotParams();
+        const allNames = new Set([...this.snapshot.keys(), ...next.keys()]);
+        for (const name of allNames) {
+            if (!name.startsWith(this.prefix))
+                continue;
+            const before = this.snapshot.get(name);
+            const after = next.get(name);
+            if (before === after)
+                continue;
+            const key = name.slice(this.prefix.length);
+            this.emitChange(key, before !== undefined ? this.tryDeserialize(before) : undefined, after !== undefined ? this.tryDeserialize(after) : undefined, 'remote');
+        }
+        this.snapshot = next;
+    }
+}

package/dist/adapters/web/index.d.ts

@@ -7,4 +7,5 @@ export { SessionStorageAdapter } from './SessionStorageAdapter';
 export { IndexedDBAdapter } from './IndexedDBAdapter';
 export { CookieAdapter } from './CookieAdapter';
 export { CacheAdapter } from './CacheAdapter';
+export { URLAdapter, type URLAdapterConfig } from './URLAdapter';
 //# sourceMappingURL=index.d.ts.map

package/dist/adapters/web/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/web/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/web/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/adapters/web/index.js

@@ -7,3 +7,4 @@ export { SessionStorageAdapter } from "./SessionStorageAdapter.js";
 export { IndexedDBAdapter } from "./IndexedDBAdapter.js";
 export { CookieAdapter } from "./CookieAdapter.js";
 export { CacheAdapter } from "./CacheAdapter.js";
+export { URLAdapter } from "./URLAdapter.js";

package/dist/android/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md — android/
+
+Last Updated: 2026-04-03
+
+> Agent instructions for Android native development.
+
+## Files
+
+| 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) |
+
+## Agent Rules
+
+### Security (IRON-SOLID)
+- Sensitive data MUST use `EncryptedStorage`
+- NEVER store secrets in `SharedPreferencesStorage`
+
+### SQL Safety (IRON-SOLID)
+- ALWAYS use parameterized queries
+- NEVER concatenate user input into SQL strings
+
+### 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)
+
+### Before Modifying
+- Understand Capacitor plugin protocol for Android
+- Test on Android emulator after changes
+- Verify Gradle build succeeds

package/dist/android/CLAUDE.md

@@ -0,0 +1,51 @@
+# CLAUDE.md — android/
+
+Last Updated: 2026-04-03
+
+## Android Native Plugin
+
+Java implementation of native storage backends for Capacitor.
+
+### Files
+
+| File | Path | Purpose |
+|------|------|---------|
+| `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 |
+
+### Configuration
+
+- Build: `build.gradle`
+- Proguard: `proguard-rules.pro`
+- Manifest: `src/main/AndroidManifest.xml`
+
+**Note**: There are two Java package paths — `com.stratastorage` (plugin) and `com.strata.storage` (implementations).
+
+## Rules
+
+### Security (IRON-SOLID)
+- Sensitive data MUST use `EncryptedStorage` (EncryptedSharedPreferences)
+- NEVER store credentials, tokens, or secrets in `SharedPreferencesStorage`
+- Follow Android Keystore best practices
+
+### SQL Safety (IRON-SOLID)
+- ALWAYS use parameterized queries in `SQLiteStorage`
+- NEVER concatenate user input into SQL strings
+- Use `SQLiteDatabase.query()` or prepared statements
+
+### 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
+
+### Build
+- Gradle-based build system
+- Proguard rules configured for release builds
+- Test on Android emulator after changes
+
+### Before Modifying
+- Understand the Capacitor plugin protocol for Android
+- Test on Android emulator after changes
+- Verify Gradle build succeeds

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

@@ -227,6 +227,41 @@ public class SQLiteStorage extends SQLiteOpenHelper {
             db.close();
         }
     }
+
+    /**
+     * Returns every row as a map of { key, value } where value is the decoded
+     * stored payload (UTF-8 string of the BLOB). The JS SqliteAdapter applies
+     * the real query condition by re-fetching/filtering each key, so this only
+     * needs to enumerate candidate rows.
+     */
+    public List<Map<String, Object>> query() {
+        List<Map<String, Object>> rows = new ArrayList<>();
+        SQLiteDatabase db = this.getReadableDatabase();
+        Cursor cursor = null;
+        try {
+            cursor = db.query(TABLE_NAME, new String[]{KEY_ID, KEY_VALUE},
+                    null, null, null, null, null);
+            if (cursor != null && cursor.moveToFirst()) {
+                do {
+                    Map<String, Object> row = new HashMap<>();
+                    row.put("key", cursor.getString(0));
+                    byte[] valueBytes = cursor.getBlob(1);
+                    if (valueBytes != null) {
+                        row.put("value", new String(valueBytes, StandardCharsets.UTF_8));
+                    } else {
+                        row.put("value", null);
+                    }
+                    rows.add(row);
+                } while (cursor.moveToNext());
+            }
+            return rows;
+        } finally {
+            if (cursor != null) {
+                cursor.close();
+            }
+            db.close();
+        }
+    }
     
     public SizeInfo size() {
         SQLiteDatabase db = this.getReadableDatabase();