strata-storage 1.5.0 → 1.6.0

package/dist/README.md

@@ -0,0 +1,116 @@
+# Strata Storage
+
+## 📚 Documentation
+
+- **[Getting Started](./docs/getting-started/installation.md)** - Installation and setup
+- **[Quick Start Guide](./docs/getting-started/quick-start.md)** - Get running in minutes
+- **[API Reference](./docs/api/README.md)** - Complete API documentation
+- **[Configuration](./docs/getting-started/configuration.md)** - Configuration options
+- **[Platform Guides](./docs/guides/platforms/web.md)** - Platform-specific guides
+- **[Examples](./docs/examples/README.md)** - Code examples and recipes
+- **[GitHub](https://github.com/aoneahsan/strata-storage)** - Source code
+- **[NPM](https://www.npmjs.com/package/strata-storage)** - Package registry
+
+---
+
+**One API. Every Storage. Everywhere.**
+
+Zero-dependency universal storage plugin providing a unified API for all storage operations across web, Android, and iOS platforms.
+
+## 🚀 Quick Start
+
+```bash
+npm install strata-storage
+```
+
+```typescript
+import { Strata } from 'strata-storage';
+
+const storage = new Strata();
+await storage.initialize();
+
+// Works everywhere - web, iOS, Android
+await storage.set('user', { name: 'John', age: 30 });
+const user = await storage.get('user');
+```
+
+## ✨ Features
+
+### Core Features
+- ✅ **Zero Dependencies** - No external packages, pure implementation
+- ✅ **Universal API** - Single interface for all storage types
+- ✅ **Cross-Platform** - Web, iOS, Android support
+- ✅ **TypeScript** - Full type safety and IntelliSense
+- ✅ **Auto Fallback** - Intelligent storage selection
+
+### Storage Adapters
+- ✅ **Memory** - Fast in-memory storage
+- ✅ **LocalStorage** - Persistent browser storage
+- ✅ **SessionStorage** - Session-based browser storage
+- ✅ **IndexedDB** - Large-scale browser database
+- ✅ **Cookies** - HTTP cookie storage
+- ✅ **Cache API** - Service worker cache storage
+- ✅ **Capacitor Preferences** - Native mobile preferences
+- ✅ **SQLite** - Mobile SQL database
+- ✅ **Secure Storage** - Keychain (iOS) / Encrypted SharedPreferences (Android)
+- ✅ **Filesystem** - File-based storage
+
+### Advanced Features
+- ✅ **Encryption** - AES-GCM encryption with Web Crypto API
+- ✅ **Compression** - LZ-string compression algorithm
+- ✅ **Cross-Tab Sync** - Real-time synchronization across tabs
+- ✅ **Query Engine** - MongoDB-like queries for filtering data
+- ✅ **TTL Support** - Automatic expiration with sliding TTL
+- ✅ **Migration System** - Version-based data migrations
+- 🚧 **Framework Integrations** - React, Vue, Angular (coming soon)
+
+## 📖 Basic Usage
+
+```typescript
+// Initialize with configuration
+const storage = new Strata({
+  defaultStorages: ['indexedDB', 'localStorage', 'memory'],
+  encryption: { enabled: true },
+  compression: { enabled: true },
+  ttl: { defaultTTL: 3600000 } // 1 hour
+});
+
+await storage.initialize();
+
+// Store with options
+await storage.set('key', value, {
+  ttl: 3600000,        // Expire in 1 hour
+  encrypt: true,       // Encrypt this value
+  compress: true,      // Compress if beneficial
+  tags: ['user-data'] // Tag for grouping
+});
+
+// Query data
+const results = await storage.query({
+  tags: { $in: ['user-data'] },
+  'value.age': { $gte: 18 }
+});
+
+// Subscribe to changes
+storage.subscribe((change) => {
+  console.log(`${change.key} changed from ${change.oldValue} to ${change.newValue}`);
+});
+```
+
+## 🏗 Project Status
+
+Currently in active development. Phase 1-5 completed:
+- ✅ Project setup and core architecture
+- ✅ Memory and web storage adapters
+- ✅ Capacitor plugin structure
+- ✅ Advanced features (encryption, compression, sync, query, TTL)
+- 🚧 Native implementations (iOS/Android)
+- 🚧 Testing and documentation
+
+## 📄 License
+
+MIT
+
+---
+
+Created by Ahsan Mahmood

package/dist/adapters/capacitor/FilesystemAdapter.js

@@ -2,10 +2,10 @@
  * Filesystem Adapter - Native file system storage
  * Direct file access on iOS and Android
  */
-import { BaseAdapter } from '@/core/BaseAdapter';
-import { StrataStorage } from '@/plugin';
-import { StorageError } from '@/utils/errors';
-import { isCapacitor } from '@/utils';
+import { BaseAdapter } from "../../core/BaseAdapter.js";
+import { StrataStorage } from "../../plugin/index.js";
+import { StorageError } from "../../utils/errors.js";
+import { isCapacitor } from "../../utils/index.js";
 /**
  * Native filesystem adapter using Capacitor plugin
  */

package/dist/adapters/capacitor/PreferencesAdapter.js

@@ -2,10 +2,10 @@
  * Preferences Adapter - Native preferences storage
  * iOS: UserDefaults, Android: SharedPreferences
  */
-import { BaseAdapter } from '@/core/BaseAdapter';
-import { StrataStorage } from '@/plugin';
-import { StorageError } from '@/utils/errors';
-import { isCapacitor } from '@/utils';
+import { BaseAdapter } from "../../core/BaseAdapter.js";
+import { StrataStorage } from "../../plugin/index.js";
+import { StorageError } from "../../utils/errors.js";
+import { isCapacitor } from "../../utils/index.js";
 /**
  * Native preferences adapter using Capacitor plugin
  */

package/dist/adapters/capacitor/SecureAdapter.js

@@ -2,10 +2,10 @@
  * Secure Adapter - Native secure storage
  * iOS: Keychain, Android: EncryptedSharedPreferences
  */
-import { BaseAdapter } from '@/core/BaseAdapter';
-import { StrataStorage } from '@/plugin';
-import { StorageError } from '@/utils/errors';
-import { isCapacitor } from '@/utils';
+import { BaseAdapter } from "../../core/BaseAdapter.js";
+import { StrataStorage } from "../../plugin/index.js";
+import { StorageError } from "../../utils/errors.js";
+import { isCapacitor } from "../../utils/index.js";
 /**
  * Native secure storage adapter using Capacitor plugin
  */

package/dist/adapters/capacitor/SqliteAdapter.js

@@ -2,10 +2,10 @@
  * SQLite Adapter - Native SQLite database storage
  * Available on iOS and Android
  */
-import { BaseAdapter } from '@/core/BaseAdapter';
-import { StrataStorage } from '@/plugin';
-import { StorageError, TransactionError } from '@/utils/errors';
-import { isCapacitor } from '@/utils';
+import { BaseAdapter } from "../../core/BaseAdapter.js";
+import { StrataStorage } from "../../plugin/index.js";
+import { StorageError, TransactionError } from "../../utils/errors.js";
+import { isCapacitor } from "../../utils/index.js";
 /**
  * Native SQLite adapter using Capacitor plugin
  */

package/dist/adapters/capacitor/index.js

@@ -2,7 +2,7 @@
  * Capacitor Native Storage Adapters
  * Export all native platform storage implementations
  */
-export { PreferencesAdapter } from './PreferencesAdapter';
-export { SqliteAdapter } from './SqliteAdapter';
-export { SecureAdapter } from './SecureAdapter';
-export { FilesystemAdapter } from './FilesystemAdapter';
+export { PreferencesAdapter } from "./PreferencesAdapter.js";
+export { SqliteAdapter } from "./SqliteAdapter.js";
+export { SecureAdapter } from "./SecureAdapter.js";
+export { FilesystemAdapter } from "./FilesystemAdapter.js";

package/dist/adapters/web/CacheAdapter.js

@@ -2,9 +2,9 @@
  * Cache Adapter - Service Worker Cache API implementation
  * Provides network-aware storage for offline support
  */
-import { BaseAdapter } from '@/core/BaseAdapter';
-import { getObjectSize } from '@/utils';
-import { StorageError, QuotaExceededError, NotSupportedError } from '@/utils/errors';
+import { BaseAdapter } from "../../core/BaseAdapter.js";
+import { getObjectSize } from "../../utils/index.js";
+import { StorageError, QuotaExceededError, NotSupportedError } from "../../utils/errors.js";
 /**
  * Cache API adapter for Service Worker environments
  */

package/dist/adapters/web/CookieAdapter.js

@@ -2,8 +2,8 @@
  * Cookie Adapter - Browser cookie implementation
  * Provides limited storage with 4KB per cookie limit
  */
-import { BaseAdapter } from '@/core/BaseAdapter';
-import { StorageError, QuotaExceededError } from '@/utils/errors';
+import { BaseAdapter } from "../../core/BaseAdapter.js";
+import { StorageError, QuotaExceededError } from "../../utils/errors.js";
 /**
  * Browser cookie adapter
  */

package/dist/adapters/web/IndexedDBAdapter.js

@@ -2,9 +2,9 @@
  * IndexedDB Adapter - Browser IndexedDB implementation
  * Provides large-scale persistent storage with advanced features
  */
-import { BaseAdapter } from '@/core/BaseAdapter';
-import { createDeferred, getObjectSize } from '@/utils';
-import { StorageError, QuotaExceededError, TransactionError } from '@/utils/errors';
+import { BaseAdapter } from "../../core/BaseAdapter.js";
+import { createDeferred, getObjectSize } from "../../utils/index.js";
+import { StorageError, QuotaExceededError, TransactionError } from "../../utils/errors.js";
 /**
  * Browser IndexedDB adapter
  */

package/dist/adapters/web/LocalStorageAdapter.js

@@ -2,9 +2,9 @@
  * LocalStorage Adapter - Browser localStorage implementation
  * Provides persistent storage with 5-10MB limit
  */
-import { BaseAdapter } from '@/core/BaseAdapter';
-import { serialize, deserialize, getObjectSize } from '@/utils';
-import { QuotaExceededError, SerializationError } from '@/utils/errors';
+import { BaseAdapter } from "../../core/BaseAdapter.js";
+import { serialize, deserialize, getObjectSize } from "../../utils/index.js";
+import { QuotaExceededError, SerializationError } from "../../utils/errors.js";
 /**
  * Browser localStorage adapter
  */

package/dist/adapters/web/MemoryAdapter.js

@@ -2,8 +2,8 @@
  * Memory Adapter - In-memory storage implementation
  * Provides fast, non-persistent storage using Map
  */
-import { BaseAdapter } from '@/core/BaseAdapter';
-import { deepClone } from '@/utils';
+import { BaseAdapter } from "../../core/BaseAdapter.js";
+import { deepClone } from "../../utils/index.js";
 /**
  * In-memory storage adapter using Map
  */

package/dist/adapters/web/SessionStorageAdapter.js

@@ -2,7 +2,7 @@
  * SessionStorage Adapter - Browser sessionStorage implementation
  * Provides session-scoped storage with 5-10MB limit
  */
-import { LocalStorageAdapter } from './LocalStorageAdapter';
+import { LocalStorageAdapter } from "./LocalStorageAdapter.js";
 /**
  * Browser sessionStorage adapter
  * Extends LocalStorageAdapter as the API is identical

package/dist/adapters/web/index.js

@@ -1,9 +1,9 @@
 /**
  * Web storage adapters
  */
-export { MemoryAdapter } from './MemoryAdapter';
-export { LocalStorageAdapter } from './LocalStorageAdapter';
-export { SessionStorageAdapter } from './SessionStorageAdapter';
-export { IndexedDBAdapter } from './IndexedDBAdapter';
-export { CookieAdapter } from './CookieAdapter';
-export { CacheAdapter } from './CacheAdapter';
+export { MemoryAdapter } from "./MemoryAdapter.js";
+export { LocalStorageAdapter } from "./LocalStorageAdapter.js";
+export { SessionStorageAdapter } from "./SessionStorageAdapter.js";
+export { IndexedDBAdapter } from "./IndexedDBAdapter.js";
+export { CookieAdapter } from "./CookieAdapter.js";
+export { CacheAdapter } from "./CacheAdapter.js";

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

@@ -0,0 +1,65 @@
+package com.strata.storage;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.os.Build;
+import androidx.security.crypto.EncryptedSharedPreferences;
+import androidx.security.crypto.MasterKey;
+import java.util.Set;
+import java.util.Map;
+
+public class EncryptedStorage {
+    private SharedPreferences encryptedPrefs;
+    private SharedPreferences.Editor editor;
+    
+    public EncryptedStorage(Context context, String name) throws Exception {
+        String fileName = name != null ? name : "StrataSecureStorage";
+        
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+            MasterKey masterKey = new MasterKey.Builder(context)
+                .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+                .build();
+                
+            encryptedPrefs = EncryptedSharedPreferences.create(
+                context,
+                fileName,
+                masterKey,
+                EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+                EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
+            );
+            
+            editor = encryptedPrefs.edit();
+        } else {
+            // Fallback to regular SharedPreferences for older devices
+            encryptedPrefs = context.getSharedPreferences(fileName, Context.MODE_PRIVATE);
+            editor = encryptedPrefs.edit();
+        }
+    }
+    
+    public boolean set(String key, String value) {
+        editor.putString(key, value);
+        return editor.commit();
+    }
+    
+    public String get(String key) {
+        return encryptedPrefs.getString(key, null);
+    }
+    
+    public boolean remove(String key) {
+        editor.remove(key);
+        return editor.commit();
+    }
+    
+    public boolean clear() {
+        editor.clear();
+        return editor.commit();
+    }
+    
+    public Set<String> keys() {
+        return encryptedPrefs.getAll().keySet();
+    }
+    
+    public boolean has(String key) {
+        return encryptedPrefs.contains(key);
+    }
+}

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

@@ -0,0 +1,147 @@
+package com.strata.storage;
+
+import android.content.Context;
+import android.database.Cursor;
+import android.database.sqlite.SQLiteDatabase;
+import android.database.sqlite.SQLiteOpenHelper;
+import android.content.ContentValues;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.HashMap;
+import java.util.Map;
+
+public class SQLiteStorage extends SQLiteOpenHelper {
+    private static final int DATABASE_VERSION = 1;
+    private static final String TABLE_NAME = "strata_storage";
+    
+    private static final String KEY_ID = "key";
+    private static final String KEY_VALUE = "value";
+    private static final String KEY_CREATED = "created";
+    private static final String KEY_UPDATED = "updated";
+    private static final String KEY_EXPIRES = "expires";
+    private static final String KEY_TAGS = "tags";
+    private static final String KEY_METADATA = "metadata";
+    
+    public SQLiteStorage(Context context, String dbName) {
+        super(context, dbName != null ? dbName : "strata.db", null, DATABASE_VERSION);
+    }
+    
+    @Override
+    public void onCreate(SQLiteDatabase db) {
+        String CREATE_TABLE = "CREATE TABLE " + TABLE_NAME + "("
+                + KEY_ID + " TEXT PRIMARY KEY,"
+                + KEY_VALUE + " BLOB NOT NULL,"
+                + KEY_CREATED + " INTEGER NOT NULL,"
+                + KEY_UPDATED + " INTEGER NOT NULL,"
+                + KEY_EXPIRES + " INTEGER,"
+                + KEY_TAGS + " TEXT,"
+                + KEY_METADATA + " TEXT" + ")";
+        db.execSQL(CREATE_TABLE);
+    }
+    
+    @Override
+    public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
+        db.execSQL("DROP TABLE IF EXISTS " + TABLE_NAME);
+        onCreate(db);
+    }
+    
+    public boolean set(String key, byte[] value, Long expires, String tags, String metadata) {
+        SQLiteDatabase db = this.getWritableDatabase();
+        ContentValues values = new ContentValues();
+        
+        long now = System.currentTimeMillis();
+        values.put(KEY_ID, key);
+        values.put(KEY_VALUE, value);
+        values.put(KEY_CREATED, now);
+        values.put(KEY_UPDATED, now);
+        
+        if (expires != null) {
+            values.put(KEY_EXPIRES, expires);
+        }
+        if (tags != null) {
+            values.put(KEY_TAGS, tags);
+        }
+        if (metadata != null) {
+            values.put(KEY_METADATA, metadata);
+        }
+        
+        long result = db.insertWithOnConflict(TABLE_NAME, null, values, SQLiteDatabase.CONFLICT_REPLACE);
+        db.close();
+        return result != -1;
+    }
+    
+    public Map<String, Object> get(String key) {
+        SQLiteDatabase db = this.getReadableDatabase();
+        Cursor cursor = db.query(TABLE_NAME, null, KEY_ID + "=?",
+                new String[]{key}, null, null, null, null);
+                
+        Map<String, Object> result = null;
+        if (cursor != null && cursor.moveToFirst()) {
+            result = new HashMap<>();
+            result.put("key", key);
+            result.put("value", cursor.getBlob(cursor.getColumnIndex(KEY_VALUE)));
+            result.put("created", cursor.getLong(cursor.getColumnIndex(KEY_CREATED)));
+            result.put("updated", cursor.getLong(cursor.getColumnIndex(KEY_UPDATED)));
+            
+            int expiresIndex = cursor.getColumnIndex(KEY_EXPIRES);
+            if (!cursor.isNull(expiresIndex)) {
+                result.put("expires", cursor.getLong(expiresIndex));
+            }
+            
+            int tagsIndex = cursor.getColumnIndex(KEY_TAGS);
+            if (!cursor.isNull(tagsIndex)) {
+                result.put("tags", cursor.getString(tagsIndex));
+            }
+            
+            int metadataIndex = cursor.getColumnIndex(KEY_METADATA);
+            if (!cursor.isNull(metadataIndex)) {
+                result.put("metadata", cursor.getString(metadataIndex));
+            }
+            
+            cursor.close();
+        }
+        db.close();
+        return result;
+    }
+    
+    public boolean remove(String key) {
+        SQLiteDatabase db = this.getWritableDatabase();
+        int result = db.delete(TABLE_NAME, KEY_ID + " = ?", new String[]{key});
+        db.close();
+        return result > 0;
+    }
+    
+    public boolean clear() {
+        SQLiteDatabase db = this.getWritableDatabase();
+        db.delete(TABLE_NAME, null, null);
+        db.close();
+        return true;
+    }
+    
+    public List<String> keys() {
+        List<String> keys = new ArrayList<>();
+        String selectQuery = "SELECT " + KEY_ID + " FROM " + TABLE_NAME;
+        
+        SQLiteDatabase db = this.getReadableDatabase();
+        Cursor cursor = db.rawQuery(selectQuery, null);
+        
+        if (cursor.moveToFirst()) {
+            do {
+                keys.add(cursor.getString(0));
+            } while (cursor.moveToNext());
+        }
+        cursor.close();
+        db.close();
+        return keys;
+    }
+    
+    public boolean has(String key) {
+        SQLiteDatabase db = this.getReadableDatabase();
+        Cursor cursor = db.query(TABLE_NAME, new String[]{KEY_ID}, KEY_ID + "=?",
+                new String[]{key}, null, null, null, null);
+        boolean exists = cursor.getCount() > 0;
+        cursor.close();
+        db.close();
+        return exists;
+    }
+}

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

@@ -0,0 +1,74 @@
+package com.strata.storage;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import java.util.Map;
+import java.util.Set;
+import java.util.HashSet;
+import org.json.JSONObject;
+import org.json.JSONArray;
+
+public class SharedPreferencesStorage {
+    private final SharedPreferences prefs;
+    private final SharedPreferences.Editor editor;
+    
+    public SharedPreferencesStorage(Context context, String name) {
+        this.prefs = context.getSharedPreferences(name != null ? name : "StrataStorage", Context.MODE_PRIVATE);
+        this.editor = prefs.edit();
+    }
+    
+    public boolean set(String key, Object value) {
+        try {
+            if (value instanceof String) {
+                editor.putString(key, (String) value);
+            } else if (value instanceof Integer) {
+                editor.putInt(key, (Integer) value);
+            } else if (value instanceof Long) {
+                editor.putLong(key, (Long) value);
+            } else if (value instanceof Float) {
+                editor.putFloat(key, (Float) value);
+            } else if (value instanceof Boolean) {
+                editor.putBoolean(key, (Boolean) value);
+            } else if (value instanceof Set) {
+                editor.putStringSet(key, (Set<String>) value);
+            } else {
+                // Convert complex objects to JSON
+                String json = value instanceof JSONObject ? 
+                    ((JSONObject) value).toString() : 
+                    new JSONObject(value).toString();
+                editor.putString(key, json);
+            }
+            return editor.commit();
+        } catch (Exception e) {
+            e.printStackTrace();
+            return false;
+        }
+    }
+    
+    public Object get(String key) {
+        Map<String, ?> all = prefs.getAll();
+        return all.get(key);
+    }
+    
+    public boolean remove(String key) {
+        editor.remove(key);
+        return editor.commit();
+    }
+    
+    public boolean clear() {
+        editor.clear();
+        return editor.commit();
+    }
+    
+    public Set<String> keys() {
+        return prefs.getAll().keySet();
+    }
+    
+    public boolean has(String key) {
+        return prefs.contains(key);
+    }
+    
+    public Map<String, ?> getAll() {
+        return prefs.getAll();
+    }
+}