strata-storage 2.4.3 → 2.6.0

package/dist/integrations/react/index.js

@@ -0,0 +1,191 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * React integration for Strata Storage.
+ *
+ * Two usage styles, both fully supported:
+ *
+ * 1. No-provider (Zustand-style, recommended): create an instance anywhere and
+ *    bind hooks to it with `createStrataHooks` — no Provider required.
+ *
+ *    ```tsx
+ *    import { defineStorage } from 'strata-storage';
+ *    import { createStrataHooks } from 'strata-storage/react';
+ *    const storage = defineStorage();
+ *    export const { useStorage } = createStrataHooks(storage);
+ *    ```
+ *
+ * 2. Provider-based (classic): wrap the tree in <StrataProvider> and call the
+ *    exported hooks, which read the instance from context.
+ */
+import { createContext, useContext, useEffect, useState, useCallback, useMemo } from 'react';
+import { Strata } from "../../core/Strata.js";
+import { ValidationError } from "../../utils/errors.js";
+// ---------------------------------------------------------------------------
+// Shared hook implementations (the Strata instance is passed in explicitly).
+// Both the no-provider hooks and the Provider-based hooks delegate here, so the
+// logic lives in exactly one place.
+// ---------------------------------------------------------------------------
+function useStorageImpl(strata, key, defaultValue, options) {
+    const [value, setValue] = useState(null);
+    const [loading, setLoading] = useState(true);
+    // Load the initial value.
+    useEffect(() => {
+        let active = true;
+        strata.get(key, options).then((val) => {
+            if (!active)
+                return;
+            setValue(val ?? defaultValue ?? null);
+            setLoading(false);
+        });
+        return () => {
+            active = false;
+        };
+    }, [key, strata, options, defaultValue]);
+    // Subscribe to changes for this key.
+    useEffect(() => {
+        return strata.subscribe((change) => {
+            if (change.key === key) {
+                setValue(change.newValue);
+            }
+        }, options);
+    }, [key, strata, options]);
+    const updateValue = useCallback(async (newValue, updateOptions) => {
+        if (newValue === null) {
+            await strata.remove(key, updateOptions ?? options);
+        }
+        else {
+            await strata.set(key, newValue, updateOptions ?? options);
+        }
+        setValue(newValue);
+    }, [key, strata, options]);
+    return [value, updateValue, loading];
+}
+function useStorageQueryImpl(strata, condition, options) {
+    const [data, setData] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const conditionKey = useMemo(() => JSON.stringify(condition), [condition]);
+    const refetch = useCallback(async () => {
+        setLoading(true);
+        try {
+            setData(await strata.query(condition, options));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [strata, condition, options]);
+    useEffect(() => {
+        void refetch();
+    }, [conditionKey, refetch]);
+    useEffect(() => {
+        return strata.subscribe(() => {
+            void refetch();
+        }, options);
+    }, [strata, refetch, options]);
+    return { data, loading, refetch };
+}
+function useStorageTTLImpl(strata, key, options) {
+    const [ttl, setTTL] = useState(null);
+    useEffect(() => {
+        let active = true;
+        const checkTTL = async () => {
+            const remaining = await strata.getTTL(key, options);
+            if (active)
+                setTTL(remaining);
+        };
+        void checkTTL();
+        const interval = setInterval(() => void checkTTL(), 1000);
+        return () => {
+            active = false;
+            clearInterval(interval);
+        };
+    }, [key, strata, options]);
+    const extendTTL = useCallback(async (extension) => {
+        await strata.extendTTL(key, extension, options);
+        setTTL(await strata.getTTL(key, options));
+    }, [key, strata, options]);
+    const persist = useCallback(async () => {
+        await strata.persist(key, options);
+        setTTL(null);
+    }, [key, strata, options]);
+    return { ttl, extendTTL, persist };
+}
+// ---------------------------------------------------------------------------
+// No-provider API — bind the hooks to an explicit instance (Zustand-style).
+// ---------------------------------------------------------------------------
+/**
+ * Bind the Strata hooks to a specific instance — the framework-agnostic,
+ * no-Provider pattern (mirrors Zustand's `create`). Call once at module scope
+ * and use the returned hooks in any component, no Provider needed.
+ *
+ * @example
+ * ```tsx
+ * const storage = defineStorage();
+ * export const { useStorage, useStorageQuery, useStorageTTL } =
+ *   createStrataHooks(storage);
+ * ```
+ */
+export function createStrataHooks(strata) {
+    function useStorage(key, defaultValue, options) {
+        return useStorageImpl(strata, key, defaultValue, options);
+    }
+    function useStorageQuery(condition, options) {
+        return useStorageQueryImpl(strata, condition, options);
+    }
+    function useStorageTTL(key, options) {
+        return useStorageTTLImpl(strata, key, options);
+    }
+    return { useStorage, useStorageQuery, useStorageTTL };
+}
+const StrataContext = createContext({
+    strata: null,
+    initialized: false,
+});
+export function StrataProvider({ children, config, instance, loadingComponent, fallback, }) {
+    const [strata] = useState(() => instance ?? new Strata(config));
+    const [initialized, setInitialized] = useState(strata.isInitialized);
+    useEffect(() => {
+        let active = true;
+        strata.initialize().then(() => {
+            if (active)
+                setInitialized(true);
+        });
+        return () => {
+            active = false;
+            // Only close instances this provider created — never a caller-owned one.
+            if (!instance) {
+                void strata.close();
+            }
+        };
+    }, [strata, instance]);
+    const value = useMemo(() => ({
+        strata: initialized ? strata : null,
+        initialized,
+    }), [strata, initialized]);
+    if (!initialized && (loadingComponent || fallback)) {
+        return (loadingComponent ?? fallback);
+    }
+    return _jsx(StrataContext.Provider, { value: value, children: children });
+}
+export function useStrata() {
+    const { strata, initialized } = useContext(StrataContext);
+    if (!initialized || !strata) {
+        throw new ValidationError('useStrata must be used within <StrataProvider>. For provider-free usage, ' +
+            'create an instance with defineStorage() and bind hooks via createStrataHooks(instance).', {
+            hook: 'useStrata',
+            requiredProvider: 'StrataProvider',
+        });
+    }
+    return strata;
+}
+export function useStrataInitialized() {
+    return useContext(StrataContext).initialized;
+}
+export function useStorage(key, defaultValue, options) {
+    return useStorageImpl(useStrata(), key, defaultValue, options);
+}
+export function useStorageQuery(condition, options) {
+    return useStorageQueryImpl(useStrata(), condition, options);
+}
+export function useStorageTTL(key, options) {
+    return useStorageTTLImpl(useStrata(), key, options);
+}

package/dist/integrations/vue/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Vue 3 integration for Strata Storage
+ */
+import type { Ref, ComputedRef, App } from 'vue';
+import { Strata } from '@/core/Strata';
+import type { StrataConfig, StorageOptions, QueryCondition } from '@/types';
+export declare const StrataPlugin: {
+    install(app: App, config?: StrataConfig): void;
+};
+/**
+ * Use Strata instance
+ */
+export declare function useStrata(instance?: Strata): Strata;
+/**
+ * Storage composable with reactive state
+ */
+export declare function useStorage<T = unknown>(key: string, defaultValue?: T, options?: StorageOptions, instance?: Strata): {
+    value: Ref<T | null>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+    refresh: () => Promise<void>;
+    update: (value: T | null, options?: StorageOptions) => Promise<void>;
+    remove: () => Promise<void>;
+};
+/**
+ * Query composable
+ */
+export declare function useStorageQuery<T = unknown>(condition: QueryCondition, options?: StorageOptions, instance?: Strata): {
+    data: Ref<Array<{
+        key: string;
+        value: T;
+    }>>;
+    loading: Ref<boolean>;
+    error: Ref<Error | null>;
+    refetch: () => Promise<void>;
+};
+/**
+ * TTL composable
+ */
+export declare function useStorageTTL(key: string, options?: StorageOptions, instance?: Strata): {
+    ttl: ComputedRef<string | null>;
+    milliseconds: Ref<number | null>;
+    extendTTL: (extension: number) => Promise<void>;
+    persist: () => Promise<void>;
+};
+/**
+ * Storage size composable
+ */
+export declare function useStorageSize(autoRefresh?: boolean, refreshInterval?: number, instance?: Strata): {
+    size: Ref<number>;
+    count: Ref<number>;
+    formatted: ComputedRef<string>;
+    refresh: () => Promise<void>;
+};
+/**
+ * Bind the Strata composables to a specific instance — the provider-free,
+ * no-plugin pattern. Use the returned composables in any component's setup()
+ * without installing StrataPlugin.
+ *
+ * @example
+ * ```ts
+ * import { defineStorage } from 'strata-storage';
+ * import { createStrataComposables } from 'strata-storage/vue';
+ * const storage = defineStorage();
+ * export const { useStorage } = createStrataComposables(storage);
+ * ```
+ */
+export declare function createStrataComposables(strata: Strata): {
+    useStorage: <T = unknown>(key: string, defaultValue?: T, options?: StorageOptions) => {
+        value: Ref<T | null, T | null>;
+        loading: Ref<boolean>;
+        error: Ref<Error | null>;
+        refresh: () => Promise<void>;
+        update: (value: T | null, options?: StorageOptions) => Promise<void>;
+        remove: () => Promise<void>;
+    };
+    useStorageQuery: <T = unknown>(condition: QueryCondition, options?: StorageOptions) => {
+        data: Ref<{
+            key: string;
+            value: T;
+        }[], {
+            key: string;
+            value: T;
+        }[]>;
+        loading: Ref<boolean>;
+        error: Ref<Error | null>;
+        refetch: () => Promise<void>;
+    };
+    useStorageTTL: (key: string, options?: StorageOptions) => {
+        ttl: ComputedRef<string | null>;
+        milliseconds: Ref<number | null>;
+        extendTTL: (extension: number) => Promise<void>;
+        persist: () => Promise<void>;
+    };
+    useStorageSize: (autoRefresh?: boolean, refreshInterval?: number) => {
+        size: Ref<number>;
+        count: Ref<number>;
+        formatted: ComputedRef<string>;
+        refresh: () => Promise<void>;
+    };
+};
+export type { Strata, StrataConfig, StorageOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/integrations/vue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/integrations/vue/index.ts"],"names":[],"mappings":"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"}

package/dist/integrations/vue/index.js

@@ -0,0 +1,274 @@
+/**
+ * Vue 3 integration for Strata Storage
+ */
+import { ref, computed, watch, onMounted, onUnmounted, inject } from 'vue';
+import { Strata } from "../../core/Strata.js";
+import { ValidationError } from "../../utils/errors.js";
+import { logger } from "../../utils/logger.js";
+// Injection key
+const StrataKey = Symbol('strata');
+// Plugin installation
+export const StrataPlugin = {
+    install(app, config) {
+        const strata = new Strata(config);
+        // Initialize asynchronously
+        strata.initialize().catch(logger.error);
+        // Provide globally
+        app.provide(StrataKey, strata);
+        // Add global properties
+        app.config.globalProperties.$strata = strata;
+        // Clean up on app unmount
+        app.unmount = new Proxy(app.unmount, {
+            apply(target, thisArg, argList) {
+                strata.close();
+                return Reflect.apply(target, thisArg, argList);
+            },
+        });
+    },
+};
+// Composition API
+/**
+ * Use Strata instance
+ */
+export function useStrata(instance) {
+    if (instance)
+        return instance;
+    const strata = inject(StrataKey);
+    if (!strata) {
+        throw new ValidationError('Strata not provided. Install the plugin (app.use(StrataPlugin)) or, for ' +
+            'provider-free usage, pass an instance or use createStrataComposables(instance).', { required: 'app.use(StrataPlugin, { config })' });
+    }
+    return strata;
+}
+/**
+ * Storage composable with reactive state
+ */
+export function useStorage(key, defaultValue, options, instance) {
+    const strata = useStrata(instance);
+    const value = ref(null);
+    const loading = ref(true);
+    const error = ref(null);
+    // Load initial value
+    const refresh = async () => {
+        loading.value = true;
+        error.value = null;
+        try {
+            const result = await strata.get(key, options);
+            value.value = result ?? defaultValue ?? null;
+        }
+        catch (e) {
+            error.value = e;
+            value.value = defaultValue ?? null;
+        }
+        finally {
+            loading.value = false;
+        }
+    };
+    // Update value
+    const update = async (newValue, updateOptions) => {
+        loading.value = true;
+        error.value = null;
+        try {
+            if (newValue === null) {
+                await strata.remove(key, updateOptions ?? options);
+            }
+            else {
+                await strata.set(key, newValue, updateOptions ?? options);
+            }
+            value.value = newValue;
+        }
+        catch (e) {
+            error.value = e;
+            throw e;
+        }
+        finally {
+            loading.value = false;
+        }
+    };
+    // Remove value
+    const remove = async () => {
+        await update(null);
+    };
+    // Subscribe to changes
+    onMounted(() => {
+        refresh();
+        const unsubscribe = strata.subscribe((change) => {
+            if (change.key === key) {
+                value.value = change.newValue;
+            }
+        }, options);
+        onUnmounted(unsubscribe);
+    });
+    return {
+        value,
+        loading,
+        error,
+        refresh,
+        update,
+        remove,
+    };
+}
+/**
+ * Query composable
+ */
+export function useStorageQuery(condition, options, instance) {
+    const strata = useStrata(instance);
+    const data = ref([]);
+    const loading = ref(true);
+    const error = ref(null);
+    const refetch = async () => {
+        loading.value = true;
+        error.value = null;
+        try {
+            const results = await strata.query(condition, options);
+            data.value = results;
+        }
+        catch (e) {
+            error.value = e;
+        }
+        finally {
+            loading.value = false;
+        }
+    };
+    // Watch for condition changes
+    watch(() => JSON.stringify(condition), () => refetch(), { immediate: true });
+    // Subscribe to any storage changes
+    onMounted(() => {
+        const unsubscribe = strata.subscribe(() => {
+            refetch();
+        }, options);
+        onUnmounted(unsubscribe);
+    });
+    return {
+        data,
+        loading,
+        error,
+        refetch,
+    };
+}
+/**
+ * TTL composable
+ */
+export function useStorageTTL(key, options, instance) {
+    const strata = useStrata(instance);
+    const milliseconds = ref(null);
+    let intervalId;
+    const ttl = computed(() => {
+        if (milliseconds.value === null || milliseconds.value <= 0) {
+            return null;
+        }
+        return formatTTL(milliseconds.value);
+    });
+    const updateTTL = async () => {
+        try {
+            const remaining = await strata.getTTL(key, options);
+            milliseconds.value = remaining;
+        }
+        catch {
+            milliseconds.value = null;
+        }
+    };
+    const extendTTL = async (extension) => {
+        await strata.extendTTL(key, extension, options);
+        await updateTTL();
+    };
+    const persist = async () => {
+        await strata.persist(key, options);
+        milliseconds.value = null;
+    };
+    onMounted(() => {
+        updateTTL();
+        intervalId = setInterval(updateTTL, 1000);
+    });
+    onUnmounted(() => {
+        if (intervalId) {
+            clearInterval(intervalId);
+        }
+    });
+    return {
+        ttl,
+        milliseconds,
+        extendTTL,
+        persist,
+    };
+}
+/**
+ * Storage size composable
+ */
+export function useStorageSize(autoRefresh = false, refreshInterval = 5000, instance) {
+    const strata = useStrata(instance);
+    const size = ref(0);
+    const count = ref(0);
+    let intervalId;
+    const formatted = computed(() => formatBytes(size.value));
+    const refresh = async () => {
+        const info = await strata.size();
+        size.value = info.total;
+        count.value = info.count;
+    };
+    onMounted(() => {
+        refresh();
+        if (autoRefresh) {
+            intervalId = setInterval(refresh, refreshInterval);
+        }
+    });
+    onUnmounted(() => {
+        if (intervalId) {
+            clearInterval(intervalId);
+        }
+    });
+    return {
+        size,
+        count,
+        formatted,
+        refresh,
+    };
+}
+/**
+ * Bind the Strata composables to a specific instance — the provider-free,
+ * no-plugin pattern. Use the returned composables in any component's setup()
+ * without installing StrataPlugin.
+ *
+ * @example
+ * ```ts
+ * import { defineStorage } from 'strata-storage';
+ * import { createStrataComposables } from 'strata-storage/vue';
+ * const storage = defineStorage();
+ * export const { useStorage } = createStrataComposables(storage);
+ * ```
+ */
+export function createStrataComposables(strata) {
+    return {
+        useStorage: (key, defaultValue, options) => useStorage(key, defaultValue, options, strata),
+        useStorageQuery: (condition, options) => useStorageQuery(condition, options, strata),
+        useStorageTTL: (key, options) => useStorageTTL(key, options, strata),
+        useStorageSize: (autoRefresh, refreshInterval) => useStorageSize(autoRefresh, refreshInterval, strata),
+    };
+}
+// Helper functions
+function formatTTL(milliseconds) {
+    const seconds = Math.floor(milliseconds / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0) {
+        return `${days}d ${hours % 24}h`;
+    }
+    else if (hours > 0) {
+        return `${hours}h ${minutes % 60}m`;
+    }
+    else if (minutes > 0) {
+        return `${minutes}m ${seconds % 60}s`;
+    }
+    else {
+        return `${seconds}s`;
+    }
+}
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 Bytes';
+    const k = 1024;
+    const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}

package/dist/ios/AGENTS.md

@@ -0,0 +1,48 @@
+# 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