strata-storage 2.6.1 → 2.7.1

package/dist/core/Strata.js

@@ -3,14 +3,15 @@
  * Zero-dependency universal storage solution
  */
 import { AdapterRegistry } from "./AdapterRegistry.js";
-import { isBrowser, isNode, deepMerge, isObject, isSafeKey } from "../utils/index.js";
+import { isBrowser, isNode, deepMerge, isObject, isValidKey, isValidValue, matchGlob, getObjectSize, } from "../utils/index.js";
 import { logger, setLogLevel, exposeLogLevelControls } from "../utils/logger.js";
-import { StorageError, EncryptionError, IntegrityError } from "../utils/errors.js";
+import { StorageError, EncryptionError, IntegrityError, ValidationError } 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";
+import { QueryEngine } from "../features/query.js";
 const VERBOSITY_TO_LEVEL = {
     minimal: 'warn',
     normal: 'info',
@@ -29,9 +30,11 @@ export class Strata {
     compressionManager;
     syncManager;
     ttlManager;
+    queryEngine = new QueryEngine();
     _initialized = false;
     _readyPromise;
     _autoBackupTimer;
+    _ttlCleanupTimer;
     constructor(config = {}) {
         this.config = this.normalizeConfig(config);
         if (this.config.debug?.enabled) {
@@ -60,7 +63,13 @@ export class Strata {
      */
     async initialize() {
         if (!this._readyPromise) {
-            this._readyPromise = this._performInitialization();
+            // On failure, clear the cached promise so a later call can retry instead
+            // of permanently re-awaiting a rejected promise (e.g. a transient adapter
+            // error during init should not brick the instance forever).
+            this._readyPromise = this._performInitialization().catch((error) => {
+                this._readyPromise = undefined;
+                throw error;
+            });
         }
         return this._readyPromise;
     }
@@ -100,9 +109,13 @@ export class Strata {
         }
         // Initialize TTL manager
         this.ttlManager = new TTLManager(this.config.ttl);
-        // Set up TTL cleanup for default adapter
-        if (this.defaultAdapter && this.config.ttl?.autoCleanup !== false) {
-            this.ttlManager.startAutoCleanup(() => this.defaultAdapter.keys(), (key) => this.defaultAdapter.get(key), (key) => this.defaultAdapter.remove(key));
+        // Set up periodic TTL cleanup across ALL initialized adapters (not just the
+        // default), so expired items in every registered backend are reaped.
+        if (this.config.ttl?.autoCleanup !== false) {
+            const interval = this.config.ttl?.cleanupInterval ?? 60000;
+            this._ttlCleanupTimer = setInterval(() => {
+                void this.cleanupAllAdapters();
+            }, interval);
         }
         // Start periodic auto-backup if configured
         if (this.config.autoBackup?.interval) {
@@ -135,7 +148,7 @@ export class Strata {
      * @param options - Storage options
      * @param options.storage - Specific storage type to use (e.g., 'localStorage', 'indexedDB')
      * @param options.decrypt - Whether to decrypt the value (default: auto-detect)
-     * @param options.decryptionPassword - Password for decryption (uses config password if not provided)
+     * @param options.encryptionPassword - Password for decryption (uses config password if not provided)
      * @returns The stored value or null if not found
      * @throws {StorageError} If the storage adapter is not available
      * @throws {EncryptionError} If decryption fails
@@ -150,25 +163,31 @@ export class Strata {
      *
      * // Get encrypted value
      * const value = await storage.get('secure-key', {
-     *   decryptionPassword: 'myPassword'
+     *   encryptionPassword: 'myPassword'
      * });
      * ```
      */
     async get(key, options) {
+        if (!isValidKey(key)) {
+            throw new ValidationError('Invalid storage key', { key });
+        }
         const adapter = await this.selectAdapter(options?.storage);
-        const value = await adapter.get(key);
+        const physicalKey = this.resolveKey(key, options);
+        const value = await adapter.get(physicalKey);
         if (!value)
             return null;
         // Handle TTL
         if (this.ttlManager && this.ttlManager.isExpired(value)) {
-            await adapter.remove(key);
+            await adapter.remove(physicalKey);
             return null;
         }
-        // Update sliding TTL if configured
-        if (options?.sliding && value.expires && this.ttlManager) {
-            const updatedValue = this.ttlManager.updateExpiration(value, options);
+        // Update sliding TTL — honored per-call (`options.sliding`) or via the
+        // instance default (`config.ttl.slidingTTL`).
+        const shouldSlide = options?.sliding ?? this.config.ttl?.slidingTTL;
+        if (shouldSlide && value.expires && this.ttlManager) {
+            const updatedValue = this.ttlManager.updateExpiration(value, { ...options, sliding: true });
             if (updatedValue !== value) {
-                await adapter.set(key, updatedValue);
+                await adapter.set(physicalKey, updatedValue);
             }
         }
         // Verify integrity; on corruption, try mirror read-repair, then honor the
@@ -184,17 +203,28 @@ export class Strata {
                 storage: adapter.name,
             });
         }
-        // Handle decryption if needed
+        // Decode through the shared pipeline: decrypt first, then decompress (the
+        // write path is compress -> encrypt, so the read path must reverse it).
+        return this.decodeStoredValue(value, key, options);
+    }
+    /**
+     * Reverse the write-time transform pipeline on a stored wrapper: decrypt (if
+     * encrypted) and then decompress (if compressed). Shared by get() and query()
+     * so query results are decoded identically to direct reads. Returns the raw
+     * encrypted payload when `skipDecryption` is set.
+     */
+    async decodeStoredValue(value, key, options) {
+        let payload = value.value;
         if (value.encrypted && this.encryptionManager) {
+            if (options?.skipDecryption) {
+                return payload;
+            }
             try {
-                if (!options?.skipDecryption) {
-                    const password = options?.encryptionPassword || this.config.encryption?.password;
-                    if (!password) {
-                        throw new EncryptionError('Encrypted value requires password for decryption');
-                    }
-                    const decrypted = await this.encryptionManager.decrypt(value.value, password);
-                    return decrypted;
+                const password = options?.encryptionPassword || this.config.encryption?.password;
+                if (!password) {
+                    throw new EncryptionError('Encrypted value requires password for decryption');
                 }
+                payload = await this.encryptionManager.decrypt(payload, password);
             }
             catch (error) {
                 if (options?.ignoreDecryptionErrors) {
@@ -204,18 +234,10 @@ export class Strata {
                 throw error;
             }
         }
-        // Handle decompression if needed
         if (value.compressed && this.compressionManager) {
-            try {
-                const decompressed = await this.compressionManager.decompress(value.value);
-                return decompressed;
-            }
-            catch (error) {
-                logger.warn(`Failed to decompress key ${key}:`, error);
-                return value.value;
-            }
+            return this.compressionManager.decompress(payload);
         }
-        return value.value;
+        return payload;
     }
     /**
      * Set a value in storage
@@ -256,20 +278,29 @@ export class Strata {
      * ```
      */
     async set(key, value, options) {
+        if (!isValidKey(key)) {
+            throw new ValidationError('Invalid storage key', { key });
+        }
+        if (!isValidValue(value)) {
+            throw new ValidationError('Invalid storage value: undefined, functions, and symbols cannot be stored', { key });
+        }
         const adapter = await this.selectAdapter(options?.storage);
+        const physicalKey = this.resolveKey(key, options);
         const now = Date.now();
         let processedValue = value;
         let compressed = false;
         // Handle compression if needed
         const shouldCompress = options?.compress ?? this.config.compression?.enabled;
         if (shouldCompress && this.compressionManager) {
-            const compressedResult = await this.compressionManager.compress(value);
+            const compressedResult = await this.compressionManager.compress(processedValue);
             if (this.compressionManager.isCompressedData(compressedResult)) {
                 processedValue = compressedResult;
                 compressed = true;
             }
         }
-        // Handle encryption if needed
+        // Handle encryption if needed. Encrypt whatever `processedValue` currently
+        // holds — the compressed payload when compression ran — so the transforms
+        // compose as compress-then-encrypt and the `compressed` flag stays truthful.
         const shouldEncrypt = options?.encrypt ?? this.config.encryption?.enabled;
         let encrypted = false;
         if (shouldEncrypt && this.encryptionManager) {
@@ -277,7 +308,7 @@ export class Strata {
             if (!password) {
                 throw new EncryptionError('Encryption enabled but no password provided');
             }
-            processedValue = await this.encryptionManager.encrypt(value, password);
+            processedValue = await this.encryptionManager.encrypt(processedValue, password);
             encrypted = true;
         }
         const storageValue = {
@@ -294,18 +325,18 @@ export class Strata {
         if (this.config.integrity || options?.verify) {
             storageValue.checksum = computeChecksum(processedValue);
         }
-        await adapter.set(key, storageValue);
+        await adapter.set(physicalKey, storageValue);
         // Durable write: read back and verify, retrying on mismatch.
         if (this.config.durableWrites || options?.durable) {
-            await this.verifyDurableWrite(adapter, key, storageValue);
+            await this.verifyDurableWrite(adapter, physicalKey, storageValue);
         }
         // Mirror the write to any configured backup adapters.
-        await this.mirrorWrite(key, storageValue, adapter.name);
+        await this.mirrorWrite(physicalKey, storageValue, adapter.name);
         // Broadcast change for sync
         if (this.syncManager) {
             this.syncManager.broadcast({
                 type: 'set',
-                key,
+                key: physicalKey,
                 value: storageValue,
                 storage: adapter.name,
                 timestamp: now,
@@ -330,15 +361,19 @@ export class Strata {
      * ```
      */
     async remove(key, options) {
+        if (!isValidKey(key)) {
+            throw new ValidationError('Invalid storage key', { key });
+        }
         const adapter = await this.selectAdapter(options?.storage);
-        await adapter.remove(key);
+        const physicalKey = this.resolveKey(key, options);
+        await adapter.remove(physicalKey);
         // Mirror the removal to any configured backup adapters.
-        await this.mirrorRemove(key, adapter.name);
+        await this.mirrorRemove(physicalKey, adapter.name);
         // Broadcast removal for sync
         if (this.syncManager) {
             this.syncManager.broadcast({
                 type: 'remove',
-                key,
+                key: physicalKey,
                 storage: adapter.name,
                 timestamp: Date.now(),
             });
@@ -363,8 +398,11 @@ export class Strata {
      * ```
      */
     async has(key, options) {
+        if (!isValidKey(key)) {
+            throw new ValidationError('Invalid storage key', { key });
+        }
         const adapter = await this.selectAdapter(options?.storage);
-        return adapter.has(key);
+        return adapter.has(this.resolveKey(key, options));
     }
     /**
      * Clear storage
@@ -394,17 +432,83 @@ export class Strata {
      */
     async clear(options) {
         await this.ensureReady();
-        if (options?.storage) {
-            const adapter = await this.selectAdapter(options.storage);
-            await adapter.clear(options);
-        }
-        else {
-            // Clear all adapters
-            for (const adapter of this.adapters.values()) {
-                await adapter.clear(options);
+        const adapters = options?.storage
+            ? [await this.selectAdapter(options.storage)]
+            : Array.from(this.adapters.values());
+        const ns = this.effectiveNamespace(options);
+        const olderThanTs = options?.olderThan !== undefined ? Strata.normalizeTimestamp(options.olderThan) : undefined;
+        const needsInspection = !!(ns ||
+            options?.prefix ||
+            options?.pattern ||
+            options?.tags ||
+            options?.expiredOnly ||
+            olderThanTs !== undefined);
+        for (const adapter of adapters) {
+            // Fast path: an unfiltered, un-namespaced clear wipes the whole adapter.
+            if (!needsInspection) {
+                await adapter.clear();
+                // Propagate the full clear cross-tab so other tabs converge, matching
+                // the set/remove broadcasts. ONLY full clears broadcast — a filtered or
+                // namespaced clear must not wipe the whole adapter elsewhere.
+                // localStorage/sessionStorage propagate natively and are skipped on the
+                // receiving side; applyRemoteChange clears the adapter directly (no
+                // re-broadcast), so there is no sync loop.
+                if (this.syncManager) {
+                    this.syncManager.broadcast({
+                        type: 'clear',
+                        storage: adapter.name,
+                        timestamp: Date.now(),
+                    });
+                }
+                continue;
+            }
+            // `expiredOnly` with no other narrowing filter: delegate to the adapter's
+            // bulk expired-reclamation when it has one (SQLite reaps in a single
+            // DELETE). The key-inspection loop below cannot reach expired rows on
+            // backends whose keys() already filters them out (SQLite filters in SQL),
+            // so without this it would be a silent no-op there.
+            if (options?.expiredOnly &&
+                !ns &&
+                !options?.prefix &&
+                !options?.pattern &&
+                !options?.tags &&
+                olderThanTs === undefined &&
+                typeof adapter.cleanupExpired === 'function') {
+                await adapter.cleanupExpired();
+                continue;
+            }
+            // Filtered/namespaced clear: inspect keys and remove only the matches.
+            const scopedPrefix = ns
+                ? `${this.namespacePrefix(ns)}${options?.prefix ?? ''}`
+                : options?.prefix;
+            for (const physicalKey of await adapter.keys()) {
+                if (ns && !physicalKey.startsWith(this.namespacePrefix(ns)))
+                    continue;
+                if (scopedPrefix && !physicalKey.startsWith(scopedPrefix))
+                    continue;
+                if (options?.pattern &&
+                    this.filterKeysByPattern([physicalKey], options.pattern).length === 0)
+                    continue;
+                if (options?.tags || options?.expiredOnly || olderThanTs !== undefined) {
+                    const value = await adapter.get(physicalKey);
+                    if (options?.tags &&
+                        (!value?.tags || !options.tags.some((tag) => value.tags?.includes(tag))))
+                        continue;
+                    if (options?.expiredOnly && (!value || !this.isItemExpired(value)))
+                        continue;
+                    if (olderThanTs !== undefined && (!value || value.created >= olderThanTs))
+                        continue;
+                }
+                await adapter.remove(physicalKey);
             }
         }
     }
+    /** Expiry check that works before the TTL manager exists (e.g. pre-init). */
+    isItemExpired(value) {
+        if (this.ttlManager)
+            return this.ttlManager.isExpired(value);
+        return value.expires !== undefined && Date.now() > value.expires;
+    }
     /**
      * Get all keys from storage
      *
@@ -431,17 +535,23 @@ export class Strata {
      */
     async keys(pattern, options) {
         await this.ensureReady();
+        const ns = this.effectiveNamespace(options);
         if (options?.storage) {
             const adapter = await this.selectAdapter(options.storage);
-            return adapter.keys(pattern);
+            // When namespaced, fetch all physical keys and strip/scope ourselves;
+            // otherwise let the adapter apply the pattern directly.
+            const raw = ns ? await adapter.keys() : await adapter.keys(pattern);
+            return ns ? this.scopeAndStripKeys(raw, ns, pattern) : raw;
         }
         // Get keys from all adapters and deduplicate
         const allKeys = new Set();
         for (const adapter of this.adapters.values()) {
-            const keys = await adapter.keys(pattern);
-            keys.forEach((key) => allKeys.add(key));
+            const raw = ns ? await adapter.keys() : await adapter.keys(pattern);
+            for (const key of raw)
+                allKeys.add(key);
         }
-        return Array.from(allKeys);
+        const collected = Array.from(allKeys);
+        return ns ? this.scopeAndStripKeys(collected, ns, pattern) : collected;
     }
     // ===========================================================================
     // Synchronous API
@@ -455,8 +565,11 @@ export class Strata {
     // ===========================================================================
     /** Synchronous get. Throws on async-only backends and on encrypted/compressed values. */
     getSync(key, options) {
+        if (!isValidKey(key)) {
+            throw new ValidationError('Invalid storage key', { key });
+        }
         const adapter = this.requireSyncAdapter(options?.storage);
-        const value = adapter.getSync(key);
+        const value = adapter.getSync(this.resolveKey(key, options));
         if (!value)
             return null;
         if (value.encrypted || value.compressed) {
@@ -466,10 +579,17 @@ export class Strata {
     }
     /** Synchronous set. Cannot encrypt or compress (those operations are async). */
     setSync(key, value, options) {
+        if (!isValidKey(key)) {
+            throw new ValidationError('Invalid storage key', { key });
+        }
+        if (!isValidValue(value)) {
+            throw new ValidationError('Invalid storage value: undefined, functions, and symbols cannot be stored', { key });
+        }
         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 physicalKey = this.resolveKey(key, options);
         const now = Date.now();
         const storageValue = {
             value,
@@ -481,11 +601,11 @@ export class Strata {
             encrypted: false,
             compressed: false,
         };
-        adapter.setSync(key, storageValue);
+        adapter.setSync(physicalKey, storageValue);
         if (this.syncManager) {
             this.syncManager.broadcast({
                 type: 'set',
-                key,
+                key: physicalKey,
                 value: storageValue,
                 storage: adapter.name,
                 timestamp: now,
@@ -494,12 +614,16 @@ export class Strata {
     }
     /** Synchronous remove. */
     removeSync(key, options) {
+        if (!isValidKey(key)) {
+            throw new ValidationError('Invalid storage key', { key });
+        }
         const adapter = this.requireSyncAdapter(options?.storage);
-        adapter.removeSync(key);
+        const physicalKey = this.resolveKey(key, options);
+        adapter.removeSync(physicalKey);
         if (this.syncManager) {
             this.syncManager.broadcast({
                 type: 'remove',
-                key,
+                key: physicalKey,
                 storage: adapter.name,
                 timestamp: Date.now(),
             });
@@ -507,17 +631,23 @@ export class Strata {
     }
     /** Synchronous existence check. */
     hasSync(key, options) {
-        return this.requireSyncAdapter(options?.storage).hasSync(key);
+        if (!isValidKey(key)) {
+            throw new ValidationError('Invalid storage key', { key });
+        }
+        return this.requireSyncAdapter(options?.storage).hasSync(this.resolveKey(key, options));
     }
     /** Synchronous keys. With no `storage`, aggregates across sync-capable adapters. */
     keysSync(pattern, options) {
+        const ns = this.effectiveNamespace(options);
         if (options?.storage) {
-            return this.requireSyncAdapter(options.storage).keysSync(pattern);
+            const adapter = this.requireSyncAdapter(options.storage);
+            const raw = ns ? adapter.keysSync() : adapter.keysSync(pattern);
+            return ns ? this.scopeAndStripKeys(raw, ns, pattern) : raw;
         }
         const all = new Set();
         for (const adapter of this.syncCapableAdapters()) {
             try {
-                for (const key of adapter.keysSync(pattern)) {
+                for (const key of ns ? adapter.keysSync() : adapter.keysSync(pattern)) {
                     all.add(key);
                 }
             }
@@ -527,17 +657,60 @@ export class Strata {
                 logger.debug(`Synchronous keys: skipped unavailable adapter "${adapter.name}"`, error);
             }
         }
-        return Array.from(all);
+        const collected = Array.from(all);
+        return ns ? this.scopeAndStripKeys(collected, ns, pattern) : collected;
     }
     /** 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()) {
+        const ns = this.effectiveNamespace(options);
+        const olderThanTs = options?.olderThan !== undefined ? Strata.normalizeTimestamp(options.olderThan) : undefined;
+        const needsInspection = !!(ns ||
+            options?.prefix ||
+            options?.pattern ||
+            options?.tags ||
+            options?.expiredOnly ||
+            olderThanTs !== undefined);
+        const adapters = options?.storage
+            ? [this.requireSyncAdapter(options.storage)]
+            : this.syncCapableAdapters();
+        for (const adapter of adapters) {
             try {
-                adapter.clearSync(options);
+                if (!needsInspection) {
+                    adapter.clearSync();
+                    // Propagate the full clear cross-tab (see clear()). Only full clears
+                    // broadcast; localStorage/sessionStorage are skipped on receive.
+                    if (this.syncManager) {
+                        this.syncManager.broadcast({
+                            type: 'clear',
+                            storage: adapter.name,
+                            timestamp: Date.now(),
+                        });
+                    }
+                    continue;
+                }
+                const scopedPrefix = ns
+                    ? `${this.namespacePrefix(ns)}${options?.prefix ?? ''}`
+                    : options?.prefix;
+                for (const physicalKey of adapter.keysSync()) {
+                    if (ns && !physicalKey.startsWith(this.namespacePrefix(ns)))
+                        continue;
+                    if (scopedPrefix && !physicalKey.startsWith(scopedPrefix))
+                        continue;
+                    if (options?.pattern &&
+                        this.filterKeysByPattern([physicalKey], options.pattern).length === 0)
+                        continue;
+                    if (options?.tags || options?.expiredOnly || olderThanTs !== undefined) {
+                        const value = adapter.getSync(physicalKey);
+                        if (options?.tags &&
+                            (!value?.tags || !options.tags.some((tag) => value.tags?.includes(tag))))
+                            continue;
+                        if (options?.expiredOnly && (!value || !this.isItemExpired(value)))
+                            continue;
+                        if (olderThanTs !== undefined && (!value || value.created >= olderThanTs))
+                            continue;
+                    }
+                    adapter.removeSync(physicalKey);
+                }
             }
             catch (error) {
                 logger.debug(`Synchronous clear: skipped unavailable adapter "${adapter.name}"`, error);
@@ -594,33 +767,67 @@ export class Strata {
     computeExpiration(options) {
         if (this.ttlManager)
             return this.ttlManager.calculateExpiration(options);
-        if (typeof options?.ttl === 'number')
-            return Date.now() + options.ttl;
+        // Pre-init fallback: mirror TTLManager.calculateExpiration's precedence
+        // (expireAt > expireAfter > ttl > defaultTTL) and past-guarding, so a write
+        // issued before initialize() expires identically to one issued after.
         if (options?.expireAt !== undefined) {
-            return typeof options.expireAt === 'number' ? options.expireAt : options.expireAt.getTime();
+            const t = options.expireAt instanceof Date ? options.expireAt.getTime() : options.expireAt;
+            return t > Date.now() ? t : undefined;
+        }
+        if (options?.expireAfter !== undefined) {
+            const t = options.expireAfter instanceof Date ? options.expireAfter.getTime() : options.expireAfter;
+            return t > Date.now() ? t : undefined;
         }
+        if (typeof options?.ttl === 'number')
+            return Date.now() + options.ttl;
+        if (this.config.ttl?.defaultTTL)
+            return Date.now() + this.config.ttl.defaultTTL;
         return undefined;
     }
     /**
      * Get storage size information
      */
-    async size(detailed) {
+    async size(detailed, options) {
         await this.ensureReady();
+        const ns = this.effectiveNamespace(options);
         let total = 0;
         let count = 0;
         const byStorage = {};
         const allByKey = {};
         for (const [type, adapter] of this.adapters.entries()) {
-            const sizeInfo = await adapter.size(detailed);
-            total += sizeInfo.total;
-            count += sizeInfo.count;
-            byStorage[type] = sizeInfo.total;
-            // Aggregate byKey data if detailed
-            if (detailed && sizeInfo.byKey) {
-                for (const [key, size] of Object.entries(sizeInfo.byKey)) {
-                    allByKey[key] = (allByKey[key] || 0) + size;
+            if (!ns) {
+                const sizeInfo = await adapter.size(detailed);
+                total += sizeInfo.total;
+                count += sizeInfo.count;
+                byStorage[type] = sizeInfo.total;
+                // Aggregate byKey data if detailed
+                if (detailed && sizeInfo.byKey) {
+                    for (const [key, size] of Object.entries(sizeInfo.byKey)) {
+                        allByKey[key] = (allByKey[key] || 0) + size;
+                    }
                 }
+                continue;
             }
+            let storageTotal = 0;
+            const prefix = this.namespacePrefix(ns);
+            for (const physicalKey of await adapter.keys()) {
+                if (!physicalKey.startsWith(prefix))
+                    continue;
+                const value = await adapter.get(physicalKey);
+                if (!value)
+                    continue;
+                const logicalKey = physicalKey.slice(prefix.length);
+                const keySize = logicalKey.length * 2;
+                const valueSize = getObjectSize(value);
+                const entrySize = keySize + valueSize;
+                total += entrySize;
+                storageTotal += entrySize;
+                count++;
+                if (detailed) {
+                    allByKey[logicalKey] = (allByKey[logicalKey] || 0) + entrySize;
+                }
+            }
+            byStorage[type] = storageTotal;
         }
         const result = {
             total,
@@ -638,6 +845,21 @@ export class Strata {
     subscribe(callback, options) {
         let cancelled = false;
         const unsubscribers = [];
+        // When namespaced, only forward changes for keys this namespace owns and
+        // present the logical (un-prefixed) key to the subscriber.
+        const ns = this.effectiveNamespace(options);
+        const effectiveCallback = ns
+            ? (change) => {
+                if (change.key === '*') {
+                    callback(change);
+                    return;
+                }
+                const prefix = this.namespacePrefix(ns);
+                if (!change.key.startsWith(prefix))
+                    return;
+                callback({ ...change, key: change.key.slice(prefix.length) });
+            }
+            : callback;
         const attach = () => {
             if (cancelled)
                 return;
@@ -646,7 +868,7 @@ export class Strata {
                 : Array.from(this.adapters.values());
             for (const adapter of targets) {
                 if (adapter?.subscribe) {
-                    unsubscribers.push(adapter.subscribe(callback));
+                    unsubscribers.push(adapter.subscribe(effectiveCallback));
                 }
             }
         };
@@ -675,28 +897,77 @@ export class Strata {
      */
     async query(condition, options) {
         const adapter = await this.selectAdapter(options?.storage);
-        if (!adapter.query) {
-            throw new StorageError(`Adapter ${adapter.name} does not support queries`);
+        const ns = this.effectiveNamespace(options);
+        const rawKeys = await adapter.keys();
+        // Query decoded values, not adapter-level stored wrappers. This keeps
+        // query() behavior aligned with get(), including namespace scoping, TTL,
+        // integrity repair, decryption, and decompression.
+        const decoded = [];
+        for (const physicalKey of rawKeys) {
+            if (ns && !physicalKey.startsWith(this.namespacePrefix(ns)))
+                continue;
+            const logicalKey = ns ? physicalKey.slice(this.namespacePrefix(ns).length) : physicalKey;
+            if (!isValidKey(logicalKey))
+                continue;
+            const value = await this.get(logicalKey, options);
+            if (value === null)
+                continue;
+            if (this.queryEngine.matches(value, condition)) {
+                decoded.push({ key: logicalKey, value });
+            }
+        }
+        return this.applyQueryOptions(decoded, options);
+    }
+    /** Apply QueryOptions (sort → skip → limit → select) to decoded query results. */
+    applyQueryOptions(items, options) {
+        let result = items;
+        if (options?.sort) {
+            const spec = typeof options.sort === 'string'
+                ? { [options.sort]: 1 }
+                : options.sort;
+            // Sort by fields of the stored value (prefix paths so the engine reads
+            // `item.value.<field>`).
+            const sortBy = Object.fromEntries(Object.entries(spec).map(([field, dir]) => [`value.${field}`, dir]));
+            result = this.queryEngine.sort(result, sortBy);
+        }
+        if (typeof options?.skip === 'number' && options.skip > 0) {
+            result = result.slice(options.skip);
+        }
+        if (typeof options?.limit === 'number') {
+            result = result.slice(0, Math.max(0, options.limit));
+        }
+        if (options?.select && options.select.length > 0) {
+            const projection = {};
+            for (const field of options.select)
+                projection[field] = 1;
+            result = result.map((item) => ({
+                key: item.key,
+                value: this.queryEngine.project(item.value, projection),
+            }));
         }
-        return adapter.query(condition);
+        return result;
     }
     /**
      * Export storage data
      */
     async export(options) {
         const data = {};
-        const keys = options?.keys || (await this.keys());
+        const opts = options?.storage
+            ? { storage: options.storage }
+            : undefined;
+        const keys = options?.keys || (await this.keys(undefined, opts));
         for (const key of keys) {
-            const value = await this.get(key);
-            if (value !== null) {
-                if (options?.includeMetadata) {
-                    const adapter = await this.selectAdapter();
-                    const storageValue = await adapter.get(key);
+            if (options?.includeMetadata) {
+                // Read the full wrapper from the targeted adapter (physical key).
+                const adapter = await this.selectAdapter(options?.storage);
+                const storageValue = await adapter.get(this.resolveKey(key, opts));
+                if (storageValue)
                     data[key] = storageValue;
-                }
-                else {
+            }
+            else {
+                const value = await this.get(key, opts);
+                if (value !== null)
                     data[key] = value;
-                }
             }
         }
         const format = options?.format || 'json';
@@ -705,6 +976,12 @@ export class Strata {
         }
         throw new StorageError(`Export format ${format} not supported`);
     }
+    /** Detect a full StorageValue wrapper (e.g. from export({ includeMetadata })). */
+    isStorageValueWrapper(value) {
+        if (!isObject(value))
+            return false;
+        return ('value' in value && typeof value.created === 'number' && typeof value.updated === 'number');
+    }
     /**
      * Import storage data
      */
@@ -723,25 +1000,38 @@ export class Strata {
         if (!isObject(parsed)) {
             throw new StorageError('Cannot import: expected a JSON object of key/value pairs');
         }
+        const opts = options?.storage
+            ? { storage: options.storage }
+            : undefined;
         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))
+            // Never write a prototype-pollution / invalid key, and never let it reach
+            // deepMerge below (isValidKey also rejects __proto__/constructor/prototype).
+            if (!isValidKey(key))
                 continue;
-            const exists = await this.has(key);
+            const exists = await this.has(key, opts);
+            // A full StorageValue wrapper (from export({ includeMetadata })) is written
+            // straight to the adapter so its TTL/tags/metadata/flags survive — routing
+            // it through set() would wrap the wrapper and corrupt the shape.
+            if (this.isStorageValueWrapper(value)) {
+                if (!exists || options?.overwrite) {
+                    const adapter = await this.selectAdapter(options?.storage);
+                    await adapter.set(this.resolveKey(key, opts), value);
+                }
+                continue;
+            }
             if (!exists || options?.overwrite) {
-                await this.set(key, value);
+                await this.set(key, value, opts);
             }
             else if (options?.merge) {
-                const existing = await this.get(key);
+                const existing = await this.get(key, opts);
                 if (options.merge === 'deep' && typeof existing === 'object' && typeof value === 'object') {
                     // 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);
+                    await this.set(key, merged, opts);
                 }
                 else {
-                    await this.set(key, value);
+                    await this.set(key, value, opts);
                 }
             }
         }
@@ -799,12 +1089,14 @@ export class Strata {
         if (!isObject(data)) {
             throw new IntegrityError('Cannot restore: snapshot payload is not an object');
         }
-        const adapter = await this.selectAdapter();
+        const adapter = await this.selectAdapter(options?.storage);
         for (const [key, wrapper] of Object.entries(data)) {
-            // Skip prototype-pollution keys; never use them as a storage key.
-            if (!isSafeKey(key))
+            // Skip prototype-pollution / invalid keys; never use them as a storage key.
+            if (!isValidKey(key))
                 continue;
-            await adapter.set(key, wrapper);
+            // Snapshots have no per-call namespace; the instance-level namespace (if
+            // any) is applied via resolveKey().
+            await adapter.set(this.resolveKey(key), wrapper);
         }
     }
     /**
@@ -853,7 +1145,7 @@ export class Strata {
         if (!this.ttlManager)
             return null;
         const adapter = await this.selectAdapter(options?.storage);
-        const value = await adapter.get(key);
+        const value = await adapter.get(this.resolveKey(key, options));
         if (!value)
             return null;
         return this.ttlManager.getTimeToLive(value);
@@ -866,12 +1158,13 @@ export class Strata {
             throw new StorageError('TTL manager not initialized');
         }
         const adapter = await this.selectAdapter(options?.storage);
-        const value = await adapter.get(key);
+        const physicalKey = this.resolveKey(key, options);
+        const value = await adapter.get(physicalKey);
         if (!value) {
             throw new StorageError(`Key ${key} not found`);
         }
         const updated = this.ttlManager.extendTTL(value, extension);
-        await adapter.set(key, updated);
+        await adapter.set(physicalKey, updated);
     }
     /**
      * Make a key persistent (remove TTL)
@@ -881,12 +1174,13 @@ export class Strata {
             throw new StorageError('TTL manager not initialized');
         }
         const adapter = await this.selectAdapter(options?.storage);
-        const value = await adapter.get(key);
+        const physicalKey = this.resolveKey(key, options);
+        const value = await adapter.get(physicalKey);
         if (!value) {
             throw new StorageError(`Key ${key} not found`);
         }
         const persisted = this.ttlManager.persist(value);
-        await adapter.set(key, persisted);
+        await adapter.set(physicalKey, persisted);
     }
     /**
      * Get items expiring within a time window
@@ -895,7 +1189,13 @@ export class Strata {
         if (!this.ttlManager)
             return [];
         const adapter = await this.selectAdapter(options?.storage);
-        return this.ttlManager.getExpiring(timeWindow, () => adapter.keys(), (key) => adapter.get(key));
+        const ns = this.effectiveNamespace(options);
+        const items = await this.ttlManager.getExpiring(timeWindow, () => adapter.keys(), (physicalKey) => adapter.get(physicalKey));
+        return ns
+            ? items
+                .filter((item) => item.key.startsWith(this.namespacePrefix(ns)))
+                .map((item) => ({ ...item, key: item.key.slice(this.namespacePrefix(ns).length) }))
+            : items;
     }
     /**
      * Manually trigger TTL cleanup
@@ -904,7 +1204,19 @@ export class Strata {
         if (!this.ttlManager)
             return 0;
         const adapter = await this.selectAdapter(options?.storage);
-        const expired = await this.ttlManager.cleanup(() => adapter.keys(), (key) => adapter.get(key), (key) => adapter.remove(key));
+        // SQLite filters expired rows in SQL, so its keys() no longer surfaces them
+        // — the per-key sweep below would reclaim nothing. Delegate to the adapter's
+        // own bulk reclamation (one DELETE), matching what the automatic TTL tick
+        // does. Reclamation here is backend-wide (not namespace-scoped), consistent
+        // with that tick.
+        if (adapter.name === 'sqlite' && typeof adapter.cleanupExpired === 'function') {
+            return adapter.cleanupExpired();
+        }
+        const ns = this.effectiveNamespace(options);
+        const expired = await this.ttlManager.cleanup(async () => {
+            const keys = await adapter.keys();
+            return ns ? keys.filter((key) => key.startsWith(this.namespacePrefix(ns))) : keys;
+        }, (physicalKey) => adapter.get(physicalKey), (physicalKey) => adapter.remove(physicalKey));
         return expired.length;
     }
     /**
@@ -920,6 +1232,21 @@ export class Strata {
     registerAdapter(adapter) {
         this.registry.register(adapter);
     }
+    /**
+     * Initialize and attach any registered adapters that are not yet active, then
+     * re-pick the default adapter. Call this after `registerAdapter()` on an
+     * already-initialized instance (e.g. `registerCapacitorAdapters()`), so the
+     * newly registered adapters become available to multi-adapter operations
+     * (keys/clear/size/subscribe) — not just to explicit `{ storage }` calls.
+     */
+    async refreshAdapters() {
+        if (!this._initialized) {
+            await this.initialize();
+            return;
+        }
+        await this.initializeAdapters();
+        this.selectDefaultAdapter();
+    }
     /**
      * Get the adapter registry (for advanced use cases)
      * @internal
@@ -935,6 +1262,10 @@ export class Strata {
             clearInterval(this._autoBackupTimer);
             this._autoBackupTimer = undefined;
         }
+        if (this._ttlCleanupTimer) {
+            clearInterval(this._ttlCleanupTimer);
+            this._ttlCleanupTimer = undefined;
+        }
         for (const adapter of this.adapters.values()) {
             if (adapter.close) {
                 await adapter.close();
@@ -953,14 +1284,37 @@ export class Strata {
         if (this.ttlManager) {
             this.ttlManager.clear();
         }
+        // Reset initialization state so the instance can be re-initialized after
+        // close() (framework unmount/remount, test teardown, adapter swap).
+        this.defaultAdapter = undefined;
+        this._initialized = false;
+        this._readyPromise = undefined;
     }
     // Private methods
     normalizeConfig(config) {
-        return {
+        const normalized = {
             platform: config.platform || this.detectPlatform(),
-            defaultStorages: config.defaultStorages || ['memory'], // Default to memory adapter
             ...config,
         };
+        // Normalize the singular `defaultStorage` into `defaultStorages` so it is no
+        // longer a silent no-op: it is prepended to (or seeds) the preference list.
+        if (config.defaultStorage) {
+            const existing = config.defaultStorages ?? [];
+            normalized.defaultStorages = existing.includes(config.defaultStorage)
+                ? existing
+                : [config.defaultStorage, ...existing];
+        }
+        if (!normalized.defaultStorages || normalized.defaultStorages.length === 0) {
+            // Persistent-first, matching the default `storage` singleton: prefer
+            // durable backends so writes survive a reload, with sync-capable
+            // localStorage ahead of async-only indexedDB, and volatile `memory` as the
+            // last-resort fallback (SSR / no web storage). selectDefaultAdapter only
+            // picks from adapters that are actually available, so unusable entries are
+            // skipped. (A bare instance previously defaulted to memory-only, silently
+            // contradicting the documented persistent-first behavior.)
+            normalized.defaultStorages = ['localStorage', 'indexedDB', 'sessionStorage', 'memory'];
+        }
+        return normalized;
     }
     detectPlatform() {
         if (isBrowser())
@@ -969,11 +1323,62 @@ export class Strata {
             return 'node';
         return 'web'; // Default to web
     }
+    // --- Namespace + key helpers ----------------------------------------------
+    /** Effective namespace for an operation: a per-call value wins over the
+     * instance default (`config.namespace`). Empty strings are treated as none. */
+    effectiveNamespace(options) {
+        const ns = options?.namespace ?? this.config.namespace;
+        return ns && ns.length > 0 ? ns : undefined;
+    }
+    /**
+     * Encode a namespace into an unambiguous physical-key prefix component.
+     * `:` is a legal character in user keys, so a bare `${ns}:${key}` join lets
+     * namespace `a` + key `b:c` collide with namespace `a:b` + key `c` (both
+     * `a:b:c`), leaking keys across namespaces. Percent-encoding `:` (and the `%`
+     * escape itself) in the namespace component removes the ambiguity while
+     * leaving the user key — including any `:` — untouched. Namespaces without a
+     * `:` are unchanged, so existing namespaced data keeps the same physical key.
+     */
+    encodeNamespace(ns) {
+        return ns.replace(/%/g, '%25').replace(/:/g, '%3A');
+    }
+    /** The physical-key prefix (with trailing `:`) for a namespace. */
+    namespacePrefix(ns) {
+        return `${this.encodeNamespace(ns)}:`;
+    }
+    /** Map a logical key to the physical key actually stored (namespace-prefixed). */
+    resolveKey(key, options) {
+        const ns = this.effectiveNamespace(options);
+        return ns ? `${this.encodeNamespace(ns)}:${key}` : key;
+    }
+    /** Reduce physical keys to the logical keys owned by `ns`, then apply pattern. */
+    scopeAndStripKeys(physicalKeys, ns, pattern) {
+        const prefix = `${this.encodeNamespace(ns)}:`;
+        const logical = physicalKeys
+            .filter((key) => key.startsWith(prefix))
+            .map((key) => key.slice(prefix.length));
+        return this.filterKeysByPattern(logical, pattern);
+    }
+    /** Pattern matcher mirroring BaseAdapter.filterKeys (prefix / glob / RegExp). */
+    filterKeysByPattern(keys, pattern) {
+        if (!pattern)
+            return keys;
+        if (pattern instanceof RegExp)
+            return keys.filter((key) => pattern.test(key));
+        if (!pattern.includes('*') && !pattern.includes('?')) {
+            return keys.filter((key) => key.startsWith(pattern));
+        }
+        return keys.filter((key) => matchGlob(pattern, key));
+    }
+    static normalizeTimestamp(value) {
+        return value instanceof Date ? value.getTime() : value;
+    }
     getDefaultStorages() {
         // Only return adapters that are actually registered
         const registered = Array.from(this.registry.getAll().keys()).map((key) => String(key));
-        // Prefer these storages in order if available
-        const preferredOrder = ['indexedDB', 'localStorage', 'sessionStorage', 'memory'];
+        // Prefer these storages in order if available (sync-capable localStorage
+        // ahead of async-only indexedDB, mirroring normalizeConfig's default).
+        const preferredOrder = ['localStorage', 'indexedDB', 'sessionStorage', 'memory'];
         const available = preferredOrder.filter((storage) => registered.includes(storage));
         // Always include memory as fallback if registered
         if (available.length === 0 && registered.includes('memory')) {
@@ -1024,9 +1429,39 @@ export class Strata {
      * natively via the `storage` event and sessionStorage is per-tab, so both are
      * skipped here to avoid redundant re-writes.
      */
+    // Run a TTL cleanup pass across every initialized adapter.
+    async cleanupAllAdapters() {
+        if (!this.ttlManager)
+            return;
+        for (const adapter of this.adapters.values()) {
+            try {
+                await this.ttlManager.cleanup(() => adapter.keys(), (key) => adapter.get(key), (key) => adapter.remove(key));
+            }
+            catch (error) {
+                logger.debug(`TTL cleanup failed for adapter "${adapter.name}":`, error);
+            }
+        }
+    }
     async applyRemoteChange(change) {
-        if (change.source !== 'remote' || !change.key || change.key === '*')
+        if (change.source !== 'remote' || !change.key)
+            return;
+        // A full-clear broadcast arrives as a keyless ('*') change. Apply it to the
+        // matching adapter so cleared state stays consistent cross-tab. Clearing the
+        // adapter directly (not this.clear()) avoids re-broadcasting, so no loop.
+        if (change.key === '*') {
+            if (change.storage === 'localStorage' || change.storage === 'sessionStorage')
+                return;
+            const clearTarget = this.adapters.get(change.storage);
+            if (clearTarget) {
+                try {
+                    await clearTarget.clear();
+                }
+                catch (error) {
+                    logger.warn(`Failed to apply remote clear for "${change.storage}":`, error);
+                }
+            }
             return;
+        }
         if (change.storage === 'localStorage' || change.storage === 'sessionStorage')
             return;
         const adapter = this.adapters.get(change.storage);
@@ -1037,7 +1472,18 @@ export class Strata {
                 await adapter.remove(change.key);
             }
             else {
-                await adapter.set(change.key, change.newValue);
+                let incoming = change.newValue;
+                // When a local value already exists for this key, apply the configured
+                // conflict-resolution strategy (default 'latest' keeps the incoming
+                // value, matching prior behavior; 'merge' / a custom resolver now take
+                // effect instead of being silently ignored).
+                if (this.syncManager) {
+                    const existing = await adapter.get(change.key);
+                    if (existing) {
+                        incoming = this.syncManager.resolveConflict([existing, incoming]);
+                    }
+                }
+                await adapter.set(change.key, incoming);
             }
         }
         catch (error) {
@@ -1103,6 +1549,7 @@ export class Strata {
         if (!mirrors?.length)
             return undefined;
         const primary = await this.selectAdapter(options?.storage);
+        const physicalKey = this.resolveKey(key, options);
         for (const name of mirrors) {
             if (name === primary.name)
                 continue;
@@ -1110,9 +1557,9 @@ export class Strata {
             if (!mirror)
                 continue;
             try {
-                const mirrorValue = await mirror.get(key);
+                const mirrorValue = await mirror.get(physicalKey);
                 if (mirrorValue && verifyChecksum(mirrorValue.value, mirrorValue.checksum)) {
-                    await primary.set(key, mirrorValue); // read-repair the primary
+                    await primary.set(physicalKey, 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;
@@ -1130,9 +1577,18 @@ export class Strata {
             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));
+            void (async () => {
+                try {
+                    // Exclude the backup key itself so each snapshot doesn't nest the
+                    // previous backup (which would grow without bound).
+                    const keys = (await this.keys()).filter((key) => key !== backupKey);
+                    const snap = await this.snapshot({ keys });
+                    await this.set(backupKey, snap, { storage: cfg.storage });
+                }
+                catch (error) {
+                    logger.warn('Auto-backup failed:', error);
+                }
+            })();
         }, cfg.interval);
     }
     async selectAdapter(storage) {