strata-storage 2.4.3 → 2.5.0

package/dist/core/Strata.js

@@ -3,12 +3,19 @@
  * Zero-dependency universal storage solution
  */
 import { AdapterRegistry } from "./AdapterRegistry.js";
-import { isBrowser, isNode, deepMerge } from "../utils/index.js";
-import { StorageError, EncryptionError } from "../utils/errors.js";
+import { isBrowser, isNode, deepMerge, isObject, isSafeKey } from "../utils/index.js";
+import { logger, setLogLevel, exposeLogLevelControls } from "../utils/logger.js";
+import { StorageError, EncryptionError, IntegrityError } from "../utils/errors.js";
+import { computeChecksum, verifyChecksum } from "../features/integrity.js";
 import { EncryptionManager } from "../features/encryption.js";
 import { CompressionManager } from "../features/compression.js";
 import { SyncManager } from "../features/sync.js";
 import { TTLManager } from "../features/ttl.js";
+const VERBOSITY_TO_LEVEL = {
+    minimal: 'warn',
+    normal: 'info',
+    verbose: 'debug',
+};
 /**
  * Main Strata class - unified storage interface
  */
@@ -23,8 +30,14 @@ export class Strata {
     syncManager;
     ttlManager;
     _initialized = false;
+    _readyPromise;
+    _autoBackupTimer;
     constructor(config = {}) {
         this.config = this.normalizeConfig(config);
+        if (this.config.debug?.enabled) {
+            setLogLevel(VERBOSITY_TO_LEVEL[this.config.debug.verbosity ?? 'normal']);
+            exposeLogLevelControls();
+        }
         this._platform = this.detectPlatform();
         this.registry = new AdapterRegistry();
     }
@@ -41,20 +54,33 @@ export class Strata {
         return this._platform;
     }
     /**
-     * Initialize Strata with available adapters
+     * Initialize Strata with available adapters. Idempotent — repeated calls
+     * return the same in-flight/completed promise, so it is safe to call from a
+     * framework Provider, from defineStorage(), or lazily on first operation.
      */
     async initialize() {
-        // No automatic adapter registration - adapters should be registered before initialize()
-        // This allows for zero-dependency operation and explicit opt-in for features
-        // Find and set default adapter
-        await this.selectDefaultAdapter();
-        // Initialize configured adapters
+        if (!this._readyPromise) {
+            this._readyPromise = this._performInitialization();
+        }
+        return this._readyPromise;
+    }
+    async _performInitialization() {
+        // Initialize every registered adapter that is available on this platform, so
+        // multi-adapter operations (keys/clear/size/subscribe without an explicit
+        // `storage`) span everything the user registered — not just the default.
         await this.initializeAdapters();
+        // Pick the default adapter (first available in the configured preference order).
+        this.selectDefaultAdapter();
+        if (!this.defaultAdapter) {
+            throw new StorageError(`No available storage adapters. Configured preference: ` +
+                `${(this.config.defaultStorages ?? []).join(', ') || '(none)'}. ` +
+                `Registered: ${this.registry.getNames().join(', ') || '(none)'}.`);
+        }
         // Initialize encryption if enabled
         if (this.config.encryption?.enabled) {
             this.encryptionManager = new EncryptionManager(this.config.encryption);
             if (!this.encryptionManager.isAvailable()) {
-                console.warn('Encryption enabled but Web Crypto API not available');
+                logger.warn('Encryption enabled but Web Crypto API not available');
             }
         }
         // Initialize compression if enabled
@@ -65,10 +91,11 @@ export class Strata {
         if (this.config.sync?.enabled) {
             this.syncManager = new SyncManager(this.config.sync);
             await this.syncManager.initialize();
-            // Subscribe to sync events
-            this.syncManager.subscribe((_change) => {
-                // Forward sync events to subscribers
-                // The adapters will handle their own change events
+            // Apply changes received from other tabs/devices to the matching local
+            // adapter so BroadcastChannel-only backends (memory/indexedDB/cache) stay
+            // in sync, then let that adapter notify local subscribers.
+            this.syncManager.subscribe((change) => {
+                void this.applyRemoteChange(change);
             });
         }
         // Initialize TTL manager
@@ -77,9 +104,30 @@ export class Strata {
         if (this.defaultAdapter && this.config.ttl?.autoCleanup !== false) {
             this.ttlManager.startAutoCleanup(() => this.defaultAdapter.keys(), (key) => this.defaultAdapter.get(key), (key) => this.defaultAdapter.remove(key));
         }
+        // Start periodic auto-backup if configured
+        if (this.config.autoBackup?.interval) {
+            this.startAutoBackup();
+        }
         // Mark as initialized
         this._initialized = true;
     }
+    /**
+     * Ensure the instance is initialized before an operation runs. This powers the
+     * "create an instance and use it anywhere" pattern — callers never have to
+     * await initialize() manually unless autoInitialize is explicitly disabled.
+     */
+    async ensureReady() {
+        if (this._initialized)
+            return;
+        if (this._readyPromise) {
+            await this._readyPromise;
+            return;
+        }
+        if (this.config.autoInitialize === false) {
+            throw new StorageError('Strata is not initialized. Call initialize() first (autoInitialize is disabled).');
+        }
+        await this.initialize();
+    }
     /**
      * Get a value from storage
      *
@@ -123,6 +171,19 @@ export class Strata {
                 await adapter.set(key, updatedValue);
             }
         }
+        // Verify integrity; on corruption, try mirror read-repair, then honor the
+        // ignoreCorruption option, else surface a typed IntegrityError.
+        if (value.checksum && !verifyChecksum(value.value, value.checksum)) {
+            const repaired = await this.repairFromMirror(key, options);
+            if (repaired !== undefined)
+                return repaired;
+            if (options?.ignoreCorruption)
+                return null;
+            throw new IntegrityError(`Integrity check failed for key "${key}" (data may be corrupted)`, {
+                key,
+                storage: adapter.name,
+            });
+        }
         // Handle decryption if needed
         if (value.encrypted && this.encryptionManager) {
             try {
@@ -137,7 +198,7 @@ export class Strata {
             }
             catch (error) {
                 if (options?.ignoreDecryptionErrors) {
-                    console.warn(`Failed to decrypt key ${key}:`, error);
+                    logger.warn(`Failed to decrypt key ${key}:`, error);
                     return null;
                 }
                 throw error;
@@ -150,7 +211,7 @@ export class Strata {
                 return decompressed;
             }
             catch (error) {
-                console.warn(`Failed to decompress key ${key}:`, error);
+                logger.warn(`Failed to decompress key ${key}:`, error);
                 return value.value;
             }
         }
@@ -229,7 +290,17 @@ export class Strata {
             encrypted: encrypted,
             compressed: compressed,
         };
+        // Integrity checksum over the stored (processed) value, when enabled.
+        if (this.config.integrity || options?.verify) {
+            storageValue.checksum = computeChecksum(processedValue);
+        }
         await adapter.set(key, storageValue);
+        // Durable write: read back and verify, retrying on mismatch.
+        if (this.config.durableWrites || options?.durable) {
+            await this.verifyDurableWrite(adapter, key, storageValue);
+        }
+        // Mirror the write to any configured backup adapters.
+        await this.mirrorWrite(key, storageValue, adapter.name);
         // Broadcast change for sync
         if (this.syncManager) {
             this.syncManager.broadcast({
@@ -261,6 +332,8 @@ export class Strata {
     async remove(key, options) {
         const adapter = await this.selectAdapter(options?.storage);
         await adapter.remove(key);
+        // Mirror the removal to any configured backup adapters.
+        await this.mirrorRemove(key, adapter.name);
         // Broadcast removal for sync
         if (this.syncManager) {
             this.syncManager.broadcast({
@@ -320,6 +393,7 @@ export class Strata {
      * ```
      */
     async clear(options) {
+        await this.ensureReady();
         if (options?.storage) {
             const adapter = await this.selectAdapter(options.storage);
             await adapter.clear(options);
@@ -356,6 +430,7 @@ export class Strata {
      * ```
      */
     async keys(pattern, options) {
+        await this.ensureReady();
         if (options?.storage) {
             const adapter = await this.selectAdapter(options.storage);
             return adapter.keys(pattern);
@@ -368,10 +443,169 @@ export class Strata {
         }
         return Array.from(allKeys);
     }
+    // ===========================================================================
+    // Synchronous API
+    //
+    // Works only on sync-capable adapters (memory, localStorage, sessionStorage,
+    // cookies, url). Throws a clear error on async-only backends (indexedDB,
+    // cache, sqlite, filesystem, secure, preferences) and when encryption or
+    // compression is requested (those are inherently async — use the async API).
+    // No await is needed; the adapter lookup falls back to the registry so sync
+    // calls work even before async initialize() has completed.
+    // ===========================================================================
+    /** Synchronous get. Throws on async-only backends and on encrypted/compressed values. */
+    getSync(key, options) {
+        const adapter = this.requireSyncAdapter(options?.storage);
+        const value = adapter.getSync(key);
+        if (!value)
+            return null;
+        if (value.encrypted || value.compressed) {
+            throw new StorageError(`Cannot synchronously read encrypted/compressed key "${key}". Use the async get() instead.`);
+        }
+        return value.value;
+    }
+    /** Synchronous set. Cannot encrypt or compress (those operations are async). */
+    setSync(key, value, options) {
+        if (options?.encrypt || options?.compress) {
+            throw new StorageError('Synchronous set cannot encrypt or compress (those operations are async). Use the async set() instead.');
+        }
+        const adapter = this.requireSyncAdapter(options?.storage);
+        const now = Date.now();
+        const storageValue = {
+            value,
+            created: now,
+            updated: now,
+            expires: this.computeExpiration(options),
+            tags: options?.tags,
+            metadata: options?.metadata,
+            encrypted: false,
+            compressed: false,
+        };
+        adapter.setSync(key, storageValue);
+        if (this.syncManager) {
+            this.syncManager.broadcast({
+                type: 'set',
+                key,
+                value: storageValue,
+                storage: adapter.name,
+                timestamp: now,
+            });
+        }
+    }
+    /** Synchronous remove. */
+    removeSync(key, options) {
+        const adapter = this.requireSyncAdapter(options?.storage);
+        adapter.removeSync(key);
+        if (this.syncManager) {
+            this.syncManager.broadcast({
+                type: 'remove',
+                key,
+                storage: adapter.name,
+                timestamp: Date.now(),
+            });
+        }
+    }
+    /** Synchronous existence check. */
+    hasSync(key, options) {
+        return this.requireSyncAdapter(options?.storage).hasSync(key);
+    }
+    /** Synchronous keys. With no `storage`, aggregates across sync-capable adapters. */
+    keysSync(pattern, options) {
+        if (options?.storage) {
+            return this.requireSyncAdapter(options.storage).keysSync(pattern);
+        }
+        const all = new Set();
+        for (const adapter of this.syncCapableAdapters()) {
+            try {
+                for (const key of adapter.keysSync(pattern)) {
+                    all.add(key);
+                }
+            }
+            catch (error) {
+                // An adapter may be registered but unusable in this environment (e.g.
+                // localStorage during SSR) — skipping it is expected, not a problem.
+                logger.debug(`Synchronous keys: skipped unavailable adapter "${adapter.name}"`, error);
+            }
+        }
+        return Array.from(all);
+    }
+    /** Synchronous clear. With no `storage`, clears all sync-capable adapters. */
+    clearSync(options) {
+        if (options?.storage) {
+            this.requireSyncAdapter(options.storage).clearSync(options);
+            return;
+        }
+        for (const adapter of this.syncCapableAdapters()) {
+            try {
+                adapter.clearSync(options);
+            }
+            catch (error) {
+                logger.debug(`Synchronous clear: skipped unavailable adapter "${adapter.name}"`, error);
+            }
+        }
+    }
+    // Resolve a single sync-capable adapter or throw a clear, actionable error.
+    requireSyncAdapter(storage) {
+        const adapter = this.selectAdapterSync(storage);
+        if (!adapter.capabilities.synchronous || !adapter.getSync) {
+            throw new StorageError(`Storage "${adapter.name}" does not support synchronous operations. Use the async API, ` +
+                `or target a sync-capable adapter (memory, localStorage, sessionStorage, cookies, url).`);
+        }
+        return adapter;
+    }
+    // Synchronous adapter lookup — falls back to the registry so sync operations
+    // work even before async initialize() has completed.
+    selectAdapterSync(storage) {
+        if (storage) {
+            const names = Array.isArray(storage) ? storage : [storage];
+            for (const name of names) {
+                const adapter = this.adapters.get(name) ?? this.registry.get(name);
+                if (adapter)
+                    return adapter;
+            }
+            throw new StorageError(`No adapter registered for storage type(s): ${names.join(', ')}`);
+        }
+        if (this.defaultAdapter)
+            return this.defaultAdapter;
+        const preferred = this.config.defaultStorages ?? [];
+        for (const name of preferred) {
+            const adapter = this.adapters.get(name) ?? this.registry.get(name);
+            if (adapter)
+                return adapter;
+        }
+        const first = this.registry.getAll().values().next().value;
+        if (first)
+            return first;
+        throw new StorageError('No storage adapter registered for synchronous operation.');
+    }
+    // All sync-capable adapters (initialized set, or the registry before init).
+    syncCapableAdapters() {
+        const source = this.adapters.size > 0 ? this.adapters.values() : this.registry.getAll().values();
+        const result = [];
+        for (const adapter of source) {
+            if (adapter.capabilities.synchronous && adapter.keysSync && adapter.clearSync) {
+                result.push(adapter);
+            }
+        }
+        return result;
+    }
+    // Compute an expiration timestamp from options without requiring the TTL
+    // manager (which only exists after initialize()).
+    computeExpiration(options) {
+        if (this.ttlManager)
+            return this.ttlManager.calculateExpiration(options);
+        if (typeof options?.ttl === 'number')
+            return Date.now() + options.ttl;
+        if (options?.expireAt !== undefined) {
+            return typeof options.expireAt === 'number' ? options.expireAt : options.expireAt.getTime();
+        }
+        return undefined;
+    }
     /**
      * Get storage size information
      */
     async size(detailed) {
+        await this.ensureReady();
         let total = 0;
         let count = 0;
         const byStorage = {};
@@ -402,24 +636,38 @@ export class Strata {
      * Subscribe to storage changes
      */
     subscribe(callback, options) {
+        let cancelled = false;
         const unsubscribers = [];
-        if (options?.storage) {
-            const adapter = this.adapters.get(options.storage);
-            if (adapter?.subscribe) {
-                unsubscribers.push(adapter.subscribe(callback));
-            }
-        }
-        else {
-            // Subscribe to all adapters that support it
-            for (const adapter of this.adapters.values()) {
-                if (adapter.subscribe) {
+        const attach = () => {
+            if (cancelled)
+                return;
+            const targets = options?.storage !== undefined
+                ? [this.adapters.get(options.storage)]
+                : Array.from(this.adapters.values());
+            for (const adapter of targets) {
+                if (adapter?.subscribe) {
                     unsubscribers.push(adapter.subscribe(callback));
                 }
             }
+        };
+        // Attach now if ready; otherwise once initialization completes — so a
+        // subscription created before initialization still receives changes.
+        if (this._initialized) {
+            attach();
         }
-        // Return function to unsubscribe from all
+        else {
+            void this.ensureReady()
+                .then(attach)
+                .catch(() => {
+                /* init errors surface through operations, not subscriptions */
+            });
+        }
+        // Return a function that unsubscribes from all (even if attach ran later).
         return () => {
-            unsubscribers.forEach((unsub) => unsub());
+            cancelled = true;
+            while (unsubscribers.length > 0) {
+                unsubscribers.pop()?.();
+            }
         };
     }
     /**
@@ -465,8 +713,21 @@ export class Strata {
         if (format !== 'json') {
             throw new StorageError(`Import format ${format} not supported`);
         }
-        const parsed = JSON.parse(data);
+        let parsed;
+        try {
+            parsed = JSON.parse(data);
+        }
+        catch {
+            throw new StorageError('Cannot import: data is not valid JSON');
+        }
+        if (!isObject(parsed)) {
+            throw new StorageError('Cannot import: expected a JSON object of key/value pairs');
+        }
         for (const [key, value] of Object.entries(parsed)) {
+            // Never write a prototype-pollution key as a storage key, and never let
+            // it reach deepMerge below.
+            if (!isSafeKey(key))
+                continue;
             const exists = await this.has(key);
             if (!exists || options?.overwrite) {
                 await this.set(key, value);
@@ -474,7 +735,8 @@ export class Strata {
             else if (options?.merge) {
                 const existing = await this.get(key);
                 if (options.merge === 'deep' && typeof existing === 'object' && typeof value === 'object') {
-                    // Use deep merge utility for proper nested object merging
+                    // Use deep merge utility for proper nested object merging.
+                    // deepMerge itself strips prototype-pollution keys defensively.
                     const merged = deepMerge(existing, value);
                     await this.set(key, merged);
                 }
@@ -484,6 +746,67 @@ export class Strata {
             }
         }
     }
+    /**
+     * Create a portable, integrity-verified snapshot of all stored data. The
+     * returned string embeds a manifest (version, timestamp, checksum) so
+     * restore() can detect a corrupted backup. Pair with config.autoBackup for
+     * scheduled snapshots.
+     */
+    async snapshot(options) {
+        const payload = await this.export({ includeMetadata: true, ...options });
+        const manifest = {
+            __strataSnapshot: 1,
+            createdAt: Date.now(),
+            checksum: computeChecksum(payload),
+            payload,
+        };
+        return JSON.stringify(manifest);
+    }
+    /**
+     * Restore data from a snapshot() string. Validates the manifest checksum and
+     * throws IntegrityError if the backup is corrupted. A raw export string (no
+     * manifest) is also accepted.
+     */
+    async restore(snapshot, options) {
+        let parsed;
+        try {
+            parsed = JSON.parse(snapshot);
+        }
+        catch {
+            throw new IntegrityError('Cannot restore: snapshot is not valid JSON');
+        }
+        const manifest = parsed;
+        // A plain export string (no manifest) — import directly.
+        if (!manifest || manifest.__strataSnapshot === undefined) {
+            await this.import(snapshot, { overwrite: true, ...options });
+            return;
+        }
+        if (typeof manifest.payload !== 'string' ||
+            typeof manifest.checksum !== 'string' ||
+            !verifyChecksum(manifest.payload, manifest.checksum)) {
+            throw new IntegrityError('Cannot restore: snapshot checksum mismatch (backup is corrupted)');
+        }
+        // Snapshots embed full value wrappers (metadata + checksum), so write them
+        // back directly — going through set() would re-wrap them and lose TTL, tags,
+        // encryption flags, and checksums.
+        let data;
+        try {
+            data = JSON.parse(manifest.payload);
+        }
+        catch {
+            throw new IntegrityError('Cannot restore: snapshot payload is not valid JSON');
+        }
+        if (!isObject(data)) {
+            throw new IntegrityError('Cannot restore: snapshot payload is not an object');
+        }
+        const adapter = await this.selectAdapter();
+        for (const [key, wrapper] of Object.entries(data)) {
+            // Skip prototype-pollution keys; never use them as a storage key.
+            if (!isSafeKey(key))
+                continue;
+            await adapter.set(key, wrapper);
+        }
+    }
     /**
      * Get available storage types
      */
@@ -608,6 +931,10 @@ export class Strata {
      * Close all adapters
      */
     async close() {
+        if (this._autoBackupTimer) {
+            clearInterval(this._autoBackupTimer);
+            this._autoBackupTimer = undefined;
+        }
         for (const adapter of this.adapters.values()) {
             if (adapter.close) {
                 await adapter.close();
@@ -654,41 +981,162 @@ export class Strata {
         }
         return (available.length > 0 ? available : registered);
     }
-    async selectDefaultAdapter() {
-        const storages = this.config.defaultStorages || this.getDefaultStorages();
-        if (storages.length === 0) {
-            throw new StorageError('No storage adapters registered or configured');
-        }
-        for (const storage of storages) {
+    async initializeAdapters() {
+        for (const [name, adapter] of this.registry.getAll()) {
+            if (this.adapters.has(name))
+                continue;
+            // Honor an explicit `adapters: { <name>: false }` opt-out.
+            const rawConfig = this.config.adapters?.[name];
+            if (rawConfig === false)
+                continue;
             try {
-                const adapter = this.registry.get(storage);
-                if (!adapter) {
-                    continue;
-                }
-                const isAvailable = await adapter.isAvailable();
-                if (!isAvailable) {
+                if (!(await adapter.isAvailable()))
                     continue;
-                }
-                // Initialize adapter with config if provided
-                const config = this.config.adapters?.[storage];
-                await adapter.initialize(config);
+                const adapterConfig = typeof rawConfig === 'object' ? rawConfig : undefined;
+                await adapter.initialize(adapterConfig);
+                this.adapters.set(name, adapter);
+            }
+            catch (error) {
+                logger.warn(`Failed to initialize ${name} adapter:`, error);
+            }
+        }
+    }
+    selectDefaultAdapter() {
+        const preferred = this.config.defaultStorages ?? this.getDefaultStorages();
+        for (const name of preferred) {
+            const adapter = this.adapters.get(name);
+            if (adapter) {
                 this.defaultAdapter = adapter;
-                this.adapters.set(storage, adapter);
                 return;
             }
+        }
+        // Fall back to any initialized adapter so a misconfigured preference list
+        // still yields a usable default instead of leaving the instance unusable.
+        const fallback = this.adapters.values().next().value;
+        if (fallback) {
+            this.defaultAdapter = fallback;
+        }
+    }
+    /**
+     * Apply a change received from another tab/device (via the sync manager) to
+     * the matching local adapter, then let the adapter notify local subscribers.
+     * Never re-broadcasts — prevents sync loops. localStorage propagates cross-tab
+     * natively via the `storage` event and sessionStorage is per-tab, so both are
+     * skipped here to avoid redundant re-writes.
+     */
+    async applyRemoteChange(change) {
+        if (change.source !== 'remote' || !change.key || change.key === '*')
+            return;
+        if (change.storage === 'localStorage' || change.storage === 'sessionStorage')
+            return;
+        const adapter = this.adapters.get(change.storage);
+        if (!adapter)
+            return;
+        try {
+            if (change.newValue === undefined || change.newValue === null) {
+                await adapter.remove(change.key);
+            }
+            else {
+                await adapter.set(change.key, change.newValue);
+            }
+        }
+        catch (error) {
+            logger.warn(`Failed to apply remote sync change for "${change.key}":`, error);
+        }
+    }
+    // --- Recovery helpers ------------------------------------------------------
+    // Resolve the configured mirror adapters, excluding the primary.
+    mirrorAdapters(excludeName) {
+        const mirrors = this.config.mirror;
+        if (!mirrors?.length)
+            return [];
+        const result = [];
+        for (const name of mirrors) {
+            if (name === excludeName)
+                continue;
+            const adapter = this.adapters.get(name);
+            if (adapter)
+                result.push(adapter);
+        }
+        return result;
+    }
+    async mirrorWrite(key, value, primaryName) {
+        for (const adapter of this.mirrorAdapters(primaryName)) {
+            try {
+                await adapter.set(key, value);
+            }
             catch (error) {
-                console.warn(`Failed to initialize ${storage} adapter:`, error);
-                // Continue to next adapter
+                logger.warn(`Mirror write to "${adapter.name}" failed for key "${key}":`, error);
             }
         }
-        throw new StorageError(`No available storage adapters found. Tried: ${storages.join(', ')}. ` +
-            `Registered adapters: ${Array.from(this.registry.getAll().keys()).join(', ')}`);
     }
-    async initializeAdapters() {
-        // Adapters are already initialized in selectDefaultAdapter
-        // This method is kept for compatibility but doesn't re-initialize
+    async mirrorRemove(key, primaryName) {
+        for (const adapter of this.mirrorAdapters(primaryName)) {
+            try {
+                await adapter.remove(key);
+            }
+            catch (error) {
+                logger.warn(`Mirror remove on "${adapter.name}" failed for key "${key}":`, error);
+            }
+        }
+    }
+    // Read the value back after writing and verify it; rewrite + retry on mismatch.
+    async verifyDurableWrite(adapter, key, expected) {
+        const expectedChecksum = expected.checksum ?? computeChecksum(expected.value);
+        const maxAttempts = 3;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            const readback = await adapter.get(key);
+            const actualChecksum = readback
+                ? (readback.checksum ?? computeChecksum(readback.value))
+                : undefined;
+            if (actualChecksum === expectedChecksum)
+                return;
+            if (attempt < maxAttempts)
+                await adapter.set(key, expected);
+        }
+        throw new StorageError(`Durable write verification failed for key "${key}" after ${maxAttempts} attempts`, { key, storage: adapter.name });
+    }
+    // Recover a corrupted primary value from a mirror that still verifies, writing
+    // it back to the primary (read-repair). Returns the decoded value or undefined.
+    async repairFromMirror(key, options) {
+        const mirrors = this.config.mirror;
+        if (!mirrors?.length)
+            return undefined;
+        const primary = await this.selectAdapter(options?.storage);
+        for (const name of mirrors) {
+            if (name === primary.name)
+                continue;
+            const mirror = this.adapters.get(name);
+            if (!mirror)
+                continue;
+            try {
+                const mirrorValue = await mirror.get(key);
+                if (mirrorValue && verifyChecksum(mirrorValue.value, mirrorValue.checksum)) {
+                    await primary.set(key, mirrorValue); // read-repair the primary
+                    logger.warn(`Repaired corrupted key "${key}" from mirror "${name}"`);
+                    // Decode via the normal path now that the primary is valid again.
+                    return (await this.get(key, { ...options, ignoreCorruption: false })) ?? undefined;
+                }
+            }
+            catch (error) {
+                logger.debug(`Mirror read-repair from "${name}" failed for "${key}":`, error);
+            }
+        }
+        return undefined;
+    }
+    startAutoBackup() {
+        const cfg = this.config.autoBackup;
+        if (!cfg?.interval)
+            return;
+        const backupKey = cfg.key ?? '__strata_backup__';
+        this._autoBackupTimer = setInterval(() => {
+            void this.snapshot()
+                .then((snap) => this.set(backupKey, snap, { storage: cfg.storage }))
+                .catch((error) => logger.warn('Auto-backup failed:', error));
+        }, cfg.interval);
     }
     async selectAdapter(storage) {
+        await this.ensureReady();
         if (!storage) {
             if (!this.defaultAdapter) {
                 throw new StorageError('No default adapter available');