@sigx/lynx-storage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andreas Ekdahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @sigx/lynx-storage
+
+Persistent key-value storage for sigx-lynx. `UserDefaults` on iOS, `SharedPreferences` on Android. Same shape as `localStorage` / `AsyncStorage` (string keys, string values).
+
+## Install
+
+```bash
+pnpm add @sigx/lynx-storage
+```
+
+```ts
+// sigx.lynx.config.ts
+export default defineLynxConfig({
+    modules: ['@sigx/lynx-storage'],
+});
+```
+
+No special permissions on either platform.
+
+## Usage
+
+```ts
+import { Storage } from '@sigx/lynx-storage';
+
+Storage.setItem('user', JSON.stringify({ name: 'Alice', id: 42 }));
+const raw = await Storage.getItem('user');
+const user = raw ? JSON.parse(raw) : null;
+
+Storage.removeItem('user');
+
+const keys = await Storage.getAllKeys();
+Storage.clear();   // wipes everything in this app's namespace
+```
+
+## API
+
+| Method                                       | Notes                                                                                              |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `setItem(key: string, value: string): void`  | Sync — fire-and-forget write.                                                                      |
+| `getItem(key: string): Promise<string \| null>` | Async. Returns `null` if the key isn't set.                                                     |
+| `removeItem(key: string): void`              | Sync — no error if the key doesn't exist.                                                          |
+| `clear(): void`                              | Wipes the entire app namespace.                                                                    |
+| `getAllKeys(): Promise<string[]>`            | Returns all currently-set keys.                                                                    |
+| `isAvailable(): boolean`                     | Whether the native module is registered in the current build.                                      |
+
+## Gotchas
+
+- **String values only.** Serialize objects with `JSON.stringify` / `JSON.parse` yourself. Don't dump raw binary — use `@sigx/lynx-file-system` for that.
+- **Sync writes can race with reads** if you `setItem` then immediately `getItem` the same key from BG. UserDefaults / SharedPreferences both use a write-behind buffer; values are returned correctly within the same process, just be aware of cross-process scenarios (extension apps on iOS, etc.) where eventual consistency applies.
+- **Persistence semantics.** Both stores survive app updates, are excluded from app-data exports on Android, and follow iCloud-backup rules on iOS (UserDefaults is included by default).
+
+## Reference app
+
+`examples/lynx-one/my-sigx-app/src/cards/StorageCard.tsx` covers a write/read round-trip + getAllKeys + clear.

package/android/com/sigx/storage/StorageModule.kt

@@ -0,0 +1,68 @@
+package com.sigx.storage
+
+import android.content.Context
+import android.content.SharedPreferences
+import com.lynx.jsbridge.LynxMethod
+import com.lynx.jsbridge.LynxModule
+import com.lynx.react.bridge.Callback
+import com.lynx.react.bridge.JavaOnlyArray
+import com.lynx.react.bridge.JavaOnlyMap
+
+/**
+ * Persistent key-value storage module (SharedPreferences-backed).
+ * JS usage: NativeModules.Storage.setItem("key", "value")
+ *           NativeModules.Storage.getItem("key", callback)
+ */
+class StorageModule(context: Context) : LynxModule(context) {
+
+    private val prefs: SharedPreferences by lazy {
+        mContext.getSharedPreferences("sigx_lynxgo_storage", Context.MODE_PRIVATE)
+    }
+
+    @LynxMethod
+    fun setItem(key: String?, value: String?) {
+        if (key != null) {
+            prefs.edit().putString(key, value).apply()
+        }
+    }
+
+    @LynxMethod
+    fun getItem(key: String?, callback: Callback?) {
+        val value = if (key != null) prefs.getString(key, null) else null
+        callback?.invoke(value)
+    }
+
+    @LynxMethod
+    fun removeItem(key: String?) {
+        if (key != null) {
+            prefs.edit().remove(key).apply()
+        }
+    }
+
+    @LynxMethod
+    fun clear() {
+        prefs.edit().clear().apply()
+    }
+
+    @LynxMethod
+    fun getAllKeys(callback: Callback?) {
+        val keys = JavaOnlyArray()
+        prefs.all.keys.forEach { keys.pushString(it) }
+        callback?.invoke(keys)
+    }
+
+    @LynxMethod
+    fun multiGet(keys: String?, callback: Callback?) {
+        // keys is a JSON-encoded string array for simplicity
+        if (keys == null) { callback?.invoke(null); return }
+        val result = JavaOnlyMap()
+        try {
+            val keyList = keys.split(",").map { it.trim() }
+            keyList.forEach { key ->
+                result.putString(key, prefs.getString(key, null))
+            }
+        } catch (_: Exception) {}
+        callback?.invoke(result)
+    }
+}
+

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Storage } from './storage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Storage } from './storage.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/storage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Persistent key-value storage APIs.
+ *
+ * @example
+ * ```ts
+ * import { Storage } from '@sigx/lynx-storage';
+ *
+ * Storage.setItem('user', JSON.stringify({ name: 'Alice' }));
+ * const user = await Storage.getItem('user');
+ * ```
+ */
+export declare const Storage: {
+    readonly setItem: (key: string, value: string) => void;
+    readonly getItem: (key: string) => Promise<string | null>;
+    readonly removeItem: (key: string) => void;
+    readonly clear: () => void;
+    readonly getAllKeys: () => Promise<string[]>;
+    readonly isAvailable: () => boolean;
+};
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO;4BACH,MAAM,SAAS,MAAM,KAAG,IAAI;4BAI5B,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;+BAI5B,MAAM,KAAG,IAAI;0BAIpB,IAAI;+BAIC,OAAO,CAAC,MAAM,EAAE,CAAC;gCAIhB,OAAO;CAGhB,CAAC"}

package/dist/storage.js

@@ -0,0 +1,34 @@
+import { callSync, callAsync, isModuleAvailable } from '@sigx/lynx-core';
+const MODULE = 'Storage';
+/**
+ * Persistent key-value storage APIs.
+ *
+ * @example
+ * ```ts
+ * import { Storage } from '@sigx/lynx-storage';
+ *
+ * Storage.setItem('user', JSON.stringify({ name: 'Alice' }));
+ * const user = await Storage.getItem('user');
+ * ```
+ */
+export const Storage = {
+    setItem(key, value) {
+        callSync(MODULE, 'setItem', key, value);
+    },
+    getItem(key) {
+        return callAsync(MODULE, 'getItem', key);
+    },
+    removeItem(key) {
+        callSync(MODULE, 'removeItem', key);
+    },
+    clear() {
+        callSync(MODULE, 'clear');
+    },
+    getAllKeys() {
+        return callAsync(MODULE, 'getAllKeys');
+    },
+    isAvailable() {
+        return isModuleAvailable(MODULE);
+    },
+};
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzE,MAAM,MAAM,GAAG,SAAS,CAAC;AAEzB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;IACnB,OAAO,CAAC,GAAW,EAAE,KAAa;QAC9B,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO,CAAC,GAAW;QACf,OAAO,SAAS,CAAgB,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;IAC5D,CAAC;IAED,UAAU,CAAC,GAAW;QAClB,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC;IAED,KAAK;QACD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED,UAAU;QACN,OAAO,SAAS,CAAW,MAAM,EAAE,YAAY,CAAC,CAAC;IACrD,CAAC;IAED,WAAW;QACP,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;CACK,CAAC"}

package/ios/StorageModule.swift

@@ -0,0 +1,53 @@
+import Foundation
+import Lynx
+
+/// Persistent key-value storage module (UserDefaults-backed).
+/// JS usage: NativeModules.Storage.setItem("key", "value")
+class StorageModule: NSObject, LynxModule {
+
+    @objc static var name: String { "Storage" }
+
+    @objc static var methodLookup: [String: String] {
+        [
+            "setItem": NSStringFromSelector(#selector(setItem(_:value:))),
+            "getItem": NSStringFromSelector(#selector(getItem(_:callback:))),
+            "removeItem": NSStringFromSelector(#selector(removeItem(_:))),
+            "clear": NSStringFromSelector(#selector(clear)),
+            "getAllKeys": NSStringFromSelector(#selector(getAllKeys(_:))),
+        ]
+    }
+
+    required override init() { super.init() }
+    required init(param: Any) { super.init() }
+
+    private lazy var defaults: UserDefaults = {
+        UserDefaults(suiteName: "com.sigx.lynxgo.storage") ?? .standard
+    }()
+
+    @objc func setItem(_ key: String?, value: String?) {
+        guard let key = key else { return }
+        defaults.set(value, forKey: key)
+    }
+
+    @objc func getItem(_ key: String?, callback: LynxCallbackBlock?) {
+        let value: String? = key != nil ? defaults.string(forKey: key!) : nil
+        callback?(value as Any)
+    }
+
+    @objc func removeItem(_ key: String?) {
+        guard let key = key else { return }
+        defaults.removeObject(forKey: key)
+    }
+
+    @objc func clear() {
+        guard let domain = defaults.persistentDomain(forName: "com.sigx.lynxgo.storage") else { return }
+        for key in domain.keys {
+            defaults.removeObject(forKey: key)
+        }
+    }
+
+    @objc func getAllKeys(_ callback: LynxCallbackBlock?) {
+        let keys = Array(defaults.dictionaryRepresentation().keys)
+        callback?(keys)
+    }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@sigx/lynx-storage",
+  "version": "0.1.0",
+  "description": "Persistent key-value storage for sigx-lynx",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./sigx-module.json": "./sigx-module.json"
+  },
+  "files": [
+    "dist",
+    "ios",
+    "android",
+    "sigx-module.json"
+  ],
+  "dependencies": {
+    "@sigx/lynx-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "author": "Andreas Ekdahl",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}

package/sigx-module.json

@@ -0,0 +1,16 @@
+{
+    "name": "Storage",
+    "package": "@sigx/lynx-storage",
+    "description": "Persistent key-value storage",
+    "platforms": ["android", "ios"],
+    "ios": {
+        "moduleClass": "StorageModule",
+        "sourceDir": "ios",
+        "methods": ["getItem","setItem","removeItem","clear","getAllKeys"]
+    },
+    "android": {
+        "moduleClass": "com.sigx.storage.StorageModule",
+        "sourceDir": "android",
+        "permissions": []
+    }
+}