strata-storage 2.4.3 → 2.6.0

package/dist/core/BaseAdapter.js

@@ -3,6 +3,7 @@
  */
 import { NotSupportedError } from "../utils/errors.js";
 import { EventEmitter, matchGlob, getObjectSize } from "../utils/index.js";
+import { logger } from "../utils/logger.js";
 import { QueryEngine } from "../features/query.js";
 /**
  * Abstract base adapter that implements common functionality
@@ -23,7 +24,7 @@ export class BaseAdapter {
                 await this.cleanupExpired();
             }
             catch (error) {
-                console.error(`TTL cleanup error in ${this.name}:`, error);
+                logger.error(`TTL cleanup error in ${this.name}:`, error);
             }
         }, this.ttlCheckInterval);
     }
@@ -78,6 +79,31 @@ export class BaseAdapter {
     calculateSize(value) {
         return getObjectSize(value);
     }
+    /**
+     * Determine whether a query targets wrapper metadata instead of the stored value.
+     */
+    isStorageMetadataQuery(condition) {
+        const storageProps = ['tags', 'metadata', 'created', 'updated', 'expires'];
+        return Object.keys(condition).some((key) => storageProps.some((storageProp) => key === storageProp || key.startsWith(`${storageProp}.`)));
+    }
+    /**
+     * Normalize value-targeted queries so callers can use either `name` or `value.name`.
+     */
+    normalizeValueQueryCondition(condition) {
+        if (Array.isArray(condition)) {
+            return condition.map((entry) => this.normalizeValueQueryCondition(entry));
+        }
+        if (!condition || typeof condition !== 'object') {
+            return condition;
+        }
+        return Object.fromEntries(Object.entries(condition).map(([key, value]) => {
+            if (key.startsWith('$')) {
+                return [key, this.normalizeValueQueryCondition(value)];
+            }
+            const normalizedKey = key.startsWith('value.') ? key.slice(6) : key;
+            return [normalizedKey, this.normalizeValueQueryCondition(value)];
+        }));
+    }
     /**
      * Default has implementation using get
      */
@@ -194,19 +220,13 @@ export class BaseAdapter {
         for (const key of keys) {
             const item = await this.get(key);
             if (item && !this.isExpired(item)) {
-                // Check if querying storage metadata (tags, metadata, etc) or the actual value
-                let matches = false;
-                // Check for storage-level properties
-                const storageProps = ['tags', 'metadata', 'created', 'updated', 'expires'];
-                const isStorageQuery = Object.keys(condition).some((k) => storageProps.includes(k));
-                if (isStorageQuery) {
-                    // Query against the storage wrapper
-                    matches = this.queryEngine.matches(item, condition);
-                }
-                else {
-                    // Query against the stored value
-                    matches = this.queryEngine.matches(item.value, condition);
-                }
+                const isStorageQuery = this.isStorageMetadataQuery(condition);
+                const normalizedCondition = isStorageQuery
+                    ? condition
+                    : this.normalizeValueQueryCondition(condition);
+                const matches = isStorageQuery
+                    ? this.queryEngine.matches(item, normalizedCondition)
+                    : this.queryEngine.matches(item.value, normalizedCondition);
                 if (matches) {
                     results.push({ key, value: item.value });
                 }

package/dist/core/Strata.d.ts

@@ -18,6 +18,8 @@ export declare class Strata {
     private syncManager?;
     private ttlManager?;
     private _initialized;
+    private _readyPromise?;
+    private _autoBackupTimer?;
     constructor(config?: StrataConfig);
     /**
      * Check if Strata has been initialized
@@ -28,9 +30,18 @@ export declare class Strata {
      */
     get platform(): 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.
      */
     initialize(): Promise<void>;
+    private _performInitialization;
+    /**
+     * 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.
+     */
+    private ensureReady;
     /**
      * Get a value from storage
      *
@@ -186,6 +197,22 @@ export declare class Strata {
      * ```
      */
     keys(pattern?: string | RegExp, options?: StorageOptions): Promise<string[]>;
+    /** Synchronous get. Throws on async-only backends and on encrypted/compressed values. */
+    getSync<T = unknown>(key: string, options?: StorageOptions): T | null;
+    /** Synchronous set. Cannot encrypt or compress (those operations are async). */
+    setSync<T = unknown>(key: string, value: T, options?: StorageOptions): void;
+    /** Synchronous remove. */
+    removeSync(key: string, options?: StorageOptions): void;
+    /** Synchronous existence check. */
+    hasSync(key: string, options?: StorageOptions): boolean;
+    /** Synchronous keys. With no `storage`, aggregates across sync-capable adapters. */
+    keysSync(pattern?: string | RegExp, options?: StorageOptions): string[];
+    /** Synchronous clear. With no `storage`, clears all sync-capable adapters. */
+    clearSync(options?: ClearOptions & StorageOptions): void;
+    private requireSyncAdapter;
+    private selectAdapterSync;
+    private syncCapableAdapters;
+    private computeExpiration;
     /**
      * Get storage size information
      */
@@ -209,6 +236,19 @@ export declare class Strata {
      * Import storage data
      */
     import(data: string, options?: ImportOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    snapshot(options?: ExportOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    restore(snapshot: string, options?: ImportOptions): Promise<void>;
     /**
      * Get available storage types
      */
@@ -271,8 +311,22 @@ export declare class Strata {
     private normalizeConfig;
     private detectPlatform;
     private getDefaultStorages;
-    private selectDefaultAdapter;
     private initializeAdapters;
+    private selectDefaultAdapter;
+    /**
+     * 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.
+     */
+    private applyRemoteChange;
+    private mirrorAdapters;
+    private mirrorWrite;
+    private mirrorRemove;
+    private verifyDurableWrite;
+    private repairFromMirror;
+    private startAutoBackup;
     private selectAdapter;
 }
 //# sourceMappingURL=Strata.d.ts.map

package/dist/core/Strata.d.ts.map

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