strata-storage 2.4.0 → 2.4.2

package/README.md

@@ -0,0 +1,295 @@
+# Strata Storage
+
+> Zero-dependency universal storage plugin providing a unified API for all storage operations across web, Android, and iOS platforms.
+
+[![npm version](https://img.shields.io/npm/v/strata-storage.svg)](https://www.npmjs.com/package/strata-storage)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
+[![Platform](https://img.shields.io/badge/platform-Web%20%7C%20iOS%20%7C%20Android-lightgrey.svg)](https://github.com/aoneahsan/strata-storage)
+
+## Features
+
+- **🚀 Zero Dependencies** - No external runtime dependencies, pure TypeScript implementation
+- **🌐 Universal API** - Single consistent API across web, iOS, and Android
+- **🔒 Built-in Encryption** - Secure data storage using native crypto APIs
+- **📦 Compression** - Automatic data compression for large objects
+- **⏱️ TTL Support** - Automatic expiration with time-to-live
+- **🔄 Cross-Tab Sync** - Real-time synchronization across browser tabs
+- **🎯 Advanced Queries** - Tag-based querying and filtering
+- **📱 Mobile Ready** - Native iOS and Android storage with Capacitor
+- **💾 Multiple Adapters** - localStorage, IndexedDB, SQLite, Keychain, and more
+- **🎨 Framework Integrations** - React hooks, Vue composables, Angular services
+
+## Installation
+
+```bash
+npm install strata-storage
+```
+
+Or using yarn:
+
+```bash
+yarn add strata-storage
+```
+
+Or using pnpm:
+
+```bash
+pnpm add strata-storage
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { Strata } from 'strata-storage';
+
+// Create and initialize storage
+const storage = new Strata();
+await storage.initialize();
+
+// Store data
+await storage.set('username', 'john_doe');
+await storage.set('user', {
+  id: 123,
+  name: 'John Doe',
+  email: 'john@example.com'
+});
+
+// Retrieve data
+const username = await storage.get('username');
+const user = await storage.get('user');
+
+// Remove data
+await storage.remove('username');
+
+// Clear all data
+await storage.clear();
+```
+
+### Advanced Features
+
+#### Encryption
+
+```typescript
+const storage = new Strata({
+  encryption: {
+    enabled: true,
+    password: 'your-secure-password'
+  }
+});
+
+await storage.initialize();
+await storage.set('sensitiveData', { token: 'secret' });
+```
+
+#### Time-To-Live (TTL)
+
+```typescript
+// Data expires in 1 hour
+await storage.set('sessionData', data, {
+  ttl: 60 * 60 * 1000
+});
+```
+
+#### Compression
+
+```typescript
+const storage = new Strata({
+  compression: {
+    enabled: true,
+    threshold: 1024 // Compress data larger than 1KB
+  }
+});
+
+await storage.initialize();
+await storage.set('largeData', bigObject);
+```
+
+#### Cross-Tab Sync
+
+```typescript
+const storage = new Strata({
+  sync: { enabled: true }
+});
+
+await storage.initialize();
+
+// Subscribe to changes from other tabs
+storage.subscribe((change) => {
+  console.log(`Key ${change.key} changed to:`, change.newValue);
+});
+```
+
+## Platform Support
+
+### Web Browsers
+- **localStorage** - Simple key-value storage
+- **sessionStorage** - Session-scoped storage
+- **IndexedDB** - Large structured data
+- **Cookies** - Cookie-based storage
+- **Cache API** - HTTP cache storage
+- **Memory** - In-memory storage
+
+### iOS (via Capacitor)
+- **UserDefaults** - User preferences
+- **Keychain** - Secure credential storage
+- **SQLite** - Database storage
+- **FileManager** - File-based storage
+
+### Android (via Capacitor)
+- **SharedPreferences** - Simple key-value storage
+- **EncryptedSharedPreferences** - Secure storage
+- **SQLite** - Database storage
+- **File Storage** - File-based storage
+
+## Framework Integrations
+
+### React
+
+```typescript
+import { useStrata } from 'strata-storage/react';
+
+function MyComponent() {
+  const { data, loading, set, remove } = useStrata('myKey');
+
+  return (
+    <div>
+      <p>{data}</p>
+      <button onClick={() => set('newValue')}>Update</button>
+    </div>
+  );
+}
+```
+
+### Vue
+
+```typescript
+import { useStrata } from 'strata-storage/vue';
+
+export default {
+  setup() {
+    const { data, loading, set, remove } = useStrata('myKey');
+
+    return { data, loading, set, remove };
+  }
+};
+```
+
+### Angular
+
+```typescript
+import { StrataService } from 'strata-storage/angular';
+
+@Component({ /* ... */ })
+export class MyComponent {
+  constructor(private storage: StrataService) {}
+
+  async saveData() {
+    await this.storage.set('key', 'value');
+  }
+}
+```
+
+## Documentation
+
+- **[Getting Started](docs/getting-started/installation.md)** - Installation and setup guide
+- **[Quick Start](docs/getting-started/quick-start.md)** - Get up and running in minutes
+- **[API Reference](docs/api/README.md)** - Complete API documentation
+- **[Platform Guides](docs/guides/platforms/web.md)** - Platform-specific information
+- **[Examples](docs/examples/README.md)** - Real-world usage examples
+- **[Migration Guide](docs/MIGRATION.md)** - Migrating from other storage solutions
+
+## Storage Adapters
+
+| Adapter | Platform | Use Case |
+|---------|----------|----------|
+| `localStorage` | Web | Simple key-value, persistent |
+| `sessionStorage` | Web | Session-scoped data |
+| `indexedDB` | Web | Large structured data |
+| `cookies` | Web | Cookie-based storage |
+| `cache` | Web | HTTP cache |
+| `memory` | All | Temporary in-memory |
+| `preferences` | Mobile | User preferences (UserDefaults/SharedPreferences) |
+| `secure` | Mobile | Encrypted storage (Keychain/EncryptedSharedPreferences) |
+| `sqlite` | Mobile | Database storage |
+| `filesystem` | Mobile | File-based storage |
+
+## Requirements
+
+- **Node.js**: 18.0.0 or higher
+- **TypeScript**: 5.0+ (optional, but recommended)
+- **Capacitor**: 5.x or 6.x (for mobile platforms)
+
+## Browser Support
+
+- Chrome/Edge: Latest 2 versions
+- Firefox: Latest 2 versions
+- Safari: Latest 2 versions
+- iOS Safari: iOS 13+
+- Android WebView: Android 8+
+
+## Why Strata Storage?
+
+### Zero Dependencies
+Unlike other storage solutions that depend on multiple packages, Strata Storage has **zero runtime dependencies**. Everything is built from scratch, ensuring:
+- Smaller bundle size
+- No dependency conflicts
+- Better security
+- Full control over implementation
+
+### Universal API
+One API works everywhere. No need to learn different APIs for web and mobile, or switch between libraries:
+
+```typescript
+// Same code works on web, iOS, and Android
+await storage.set('key', 'value');
+const value = await storage.get('key');
+```
+
+### Built-in Features
+Advanced features included out of the box:
+- Encryption (Web Crypto API / Native Crypto)
+- Compression (LZ-string algorithm)
+- TTL/Expiration
+- Cross-tab sync
+- Advanced queries
+- Data migrations
+
+## Contributing
+
+Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+**Ahsan Mahmood**
+- Email: aoneahsan@gmail.com
+- LinkedIn: [linkedin.com/in/aoneahsan](https://linkedin.com/in/aoneahsan)
+- Portfolio: [aoneahsan.com](https://aoneahsan.com)
+- GitHub: [@aoneahsan](https://github.com/aoneahsan)
+- NPM: [npmjs.com/~aoneahsan](https://www.npmjs.com/~aoneahsan)
+- Phone/WhatsApp: +923046619706
+
+## Links
+
+- **NPM Package**: [npmjs.com/package/strata-storage](https://www.npmjs.com/package/strata-storage)
+- **GitHub Repository**: [github.com/aoneahsan/strata-storage](https://github.com/aoneahsan/strata-storage)
+- **Issue Tracker**: [github.com/aoneahsan/strata-storage/issues](https://github.com/aoneahsan/strata-storage/issues)
+- **Documentation**: [github.com/aoneahsan/strata-storage/tree/main/docs](https://github.com/aoneahsan/strata-storage/tree/main/docs)
+
+## Support
+
+If you encounter any issues or have questions:
+
+1. Check the [FAQ](docs/reference/faq.md)
+2. Search [existing issues](https://github.com/aoneahsan/strata-storage/issues)
+3. Create a [new issue](https://github.com/aoneahsan/strata-storage/issues/new)
+
+---
+
+Made with ❤️ by [Ahsan Mahmood](https://aoneahsan.com)

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

@@ -3,8 +3,11 @@ package com.strata.storage;
 import android.content.Context;
 import android.content.SharedPreferences;
 import android.os.Build;
+import android.util.Log;
 import androidx.security.crypto.EncryptedSharedPreferences;
 import androidx.security.crypto.MasterKey;
+import java.security.GeneralSecurityException;
+import java.io.IOException;
 import java.util.Set;
 import java.util.HashSet;
 import java.util.Map;
@@ -18,28 +21,34 @@ public class EncryptedStorage {
     private SharedPreferences.Editor editor;
     private static final String DEFAULT_NAME = "StrataSecureStorage";
     
-    public EncryptedStorage(Context context) throws Exception {
+    public EncryptedStorage(Context context) throws GeneralSecurityException, IOException {
         this(context, DEFAULT_NAME);
     }
-    
-    public EncryptedStorage(Context context, String name) throws Exception {
+
+    public EncryptedStorage(Context context, String name) throws GeneralSecurityException, IOException {
         String fileName = name != null ? name : DEFAULT_NAME;
-        
+
         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();
+            try {
+                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();
+            } catch (GeneralSecurityException | IOException e) {
+                Log.e("StrataStorage", "Failed to initialize encrypted storage", e);
+                throw e;
+            }
         } else {
+            Log.w("StrataStorage", "API < 23, using unencrypted SharedPreferences");
             // Fallback to regular SharedPreferences for older devices
             encryptedPrefs = context.getSharedPreferences(fileName, Context.MODE_PRIVATE);
             editor = encryptedPrefs.edit();
@@ -68,7 +77,7 @@ public class EncryptedStorage {
             editor.putString(key, stringValue);
             return editor.commit();
         } catch (Exception e) {
-            e.printStackTrace();
+            Log.e("StrataStorage", "Failed to set value in encrypted storage", e);
             return false;
         }
     }

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

@@ -5,6 +5,7 @@ import android.database.Cursor;
 import android.database.sqlite.SQLiteDatabase;
 import android.database.sqlite.SQLiteOpenHelper;
 import android.content.ContentValues;
+import android.util.Log;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.HashMap;
@@ -78,7 +79,7 @@ public class SQLiteStorage extends SQLiteOpenHelper {
                 valueBytes = json.getBytes(StandardCharsets.UTF_8);
             }
         } catch (Exception e) {
-            e.printStackTrace();
+            Log.e("StrataStorage", "Failed to set value in SQLite", e);
             return false;
         }
         SQLiteDatabase db = this.getWritableDatabase();
@@ -112,36 +113,41 @@ public class SQLiteStorage extends SQLiteOpenHelper {
     
     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));
+        Cursor cursor = null;
+        try {
+            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));
+                }
             }
-            
-            int metadataIndex = cursor.getColumnIndex(KEY_METADATA);
-            if (!cursor.isNull(metadataIndex)) {
-                result.put("metadata", cursor.getString(metadataIndex));
+            return result;
+        } finally {
+            if (cursor != null) {
+                cursor.close();
             }
-            
-            cursor.close();
+            db.close();
         }
-        db.close();
-        return result;
     }
     
     public boolean remove(String key) {
@@ -179,52 +185,73 @@ public class SQLiteStorage extends SQLiteOpenHelper {
         List<String> keys = new ArrayList<>();
         String selectQuery;
         String[] selectionArgs = null;
-        
+
         if (pattern != null) {
             selectQuery = "SELECT " + KEY_ID + " FROM " + TABLE_NAME + " WHERE " + KEY_ID + " LIKE ?";
-            selectionArgs = new String[]{"% " + pattern + "%"};
+            selectionArgs = new String[]{"%" + pattern + "%"};
         } else {
             selectQuery = "SELECT " + KEY_ID + " FROM " + TABLE_NAME;
         }
-        
+
         SQLiteDatabase db = this.getReadableDatabase();
-        Cursor cursor = db.rawQuery(selectQuery, selectionArgs);
-        
-        if (cursor.moveToFirst()) {
-            do {
-                keys.add(cursor.getString(0));
-            } while (cursor.moveToNext());
+        Cursor cursor = null;
+        try {
+            cursor = db.rawQuery(selectQuery, selectionArgs);
+
+            if (cursor != null && cursor.moveToFirst()) {
+                do {
+                    keys.add(cursor.getString(0));
+                } while (cursor.moveToNext());
+            }
+            return keys;
+        } finally {
+            if (cursor != null) {
+                cursor.close();
+            }
+            db.close();
         }
-        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;
+        Cursor cursor = null;
+        try {
+            cursor = db.query(TABLE_NAME, new String[]{KEY_ID}, KEY_ID + "=?",
+                    new String[]{key}, null, null, null, null);
+            boolean exists = cursor != null && cursor.getCount() > 0;
+            return exists;
+        } finally {
+            if (cursor != null) {
+                cursor.close();
+            }
+            db.close();
+        }
     }
     
     public SizeInfo size() {
         SQLiteDatabase db = this.getReadableDatabase();
-        Cursor cursor = db.rawQuery("SELECT COUNT(*), SUM(LENGTH(" + KEY_VALUE + ")) FROM " + TABLE_NAME, null);
-        
-        long totalSize = 0;
-        int count = 0;
-        
-        if (cursor != null && cursor.moveToFirst()) {
-            count = cursor.getInt(0);
-            totalSize = cursor.getLong(1);
-            cursor.close();
+        Cursor cursor = null;
+        try {
+            cursor = db.rawQuery("SELECT COUNT(*), SUM(LENGTH(" + KEY_VALUE + ")) FROM " + TABLE_NAME, null);
+
+            long totalSize = 0;
+            int count = 0;
+
+            if (cursor != null && cursor.moveToFirst()) {
+                count = cursor.getInt(0);
+                // Check for NULL values from SQL SUM function
+                if (!cursor.isNull(1)) {
+                    totalSize = cursor.getLong(1);
+                }
+            }
+
+            return new SizeInfo(totalSize, count);
+        } finally {
+            if (cursor != null) {
+                cursor.close();
+            }
+            db.close();
         }
-        
-        db.close();
-        return new SizeInfo(totalSize, count);
     }
     
     /**

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

@@ -2,6 +2,7 @@ package com.strata.storage;
 
 import android.content.Context;
 import android.content.SharedPreferences;
+import android.util.Log;
 import java.util.Map;
 import java.util.Set;
 import java.util.HashSet;
@@ -37,7 +38,13 @@ public class SharedPreferencesStorage {
             } else if (value instanceof Boolean) {
                 editor.putBoolean(key, (Boolean) value);
             } else if (value instanceof Set) {
-                editor.putStringSet(key, (Set<String>) value);
+                // Safely convert to Set<String>
+                Set<?> rawSet = (Set<?>) value;
+                Set<String> stringSet = new HashSet<>();
+                for (Object item : rawSet) {
+                    stringSet.add(item != null ? item.toString() : "null");
+                }
+                editor.putStringSet(key, stringSet);
             } else {
                 // Convert complex objects to JSON
                 String json;
@@ -56,7 +63,7 @@ public class SharedPreferencesStorage {
             }
             return editor.commit();
         } catch (Exception e) {
-            e.printStackTrace();
+            Log.e("StrataStorage", "Failed to set value in SharedPreferences", e);
             return false;
         }
     }