@chainplatform/appstore

🧠 AppStore

A lightweight, dependency-free global store with persistence, hydration, and subscription support — designed for React Native and Web environments.
It lets you manage multiple namespaces (like theme, user, settings, etc) and persist them easily using your own storage backend.

✨ Features

• ✅ Multi-namespace store management (AppStore.use("theme"), AppStore.use("user"))
• 💾 Persistent data via pluggable storage adapter
• 🔁 Auto hydration (load from storage)
• 👂 Reactive subscriptions with subscribe() and onHydrated()
• ⚙️ Custom logging and debounced persistence
• 🔒 Works with encrypted or plain storage

🚀 Installation

npm install @chainplatform/appstore

or

yarn add @chainplatform/appstore

⚙️ Quick Setup

You must configure your storage adapter once before using any stores.

Example with Chain SDK

import AppStore from "@chainplatform/appstore";
import { saveStorage, retrieveStorage, removeStorage } from "@chainplatform/sdk";

const customStorage = {
  get: async (key) => await retrieveStorage(key, { encrypted: true }),
  set: async (key, val) => await saveStorage(key, val, { encrypted: true }),
  remove: async (key) => await removeStorage(key, { encrypted: true }),
};

// Configure once at app startup
AppStore.configure({
  storage: customStorage,
  log: true, // or false, or a custom logger function
});

🧩 Usage Example

// Create or access a store
const themeStore = AppStore.use("theme", { encrypted: true });

// Hydrate data from persistent storage
await themeStore.hydrate();

// Subscribe to changes
const unsubscribe = themeStore.subscribe((newVal, oldVal) => {
  console.log("Theme changed:", newVal);
});

// Set data
themeStore.set({ mode: "dark", primary: "#3498db" });

// Clear only in-memory data
themeStore.clear();

// Clear both in-memory and storage
await themeStore.clearStorage();

// Unsubscribe when needed
unsubscribe();

🔄 Manage Multiple Stores

const userStore = AppStore.use("user");
const drawerStore = AppStore.use("drawer");

// Load all stores in parallel
await AppStore.hydrateAll();

// Clear all memory data (not storage)
AppStore.clearAll();

🧱 API Reference

AppStore.configure(options)

Configure global settings for all stores.
Should be called once, usually at app startup.

Option	Type	Description
storage	{ get, set, remove }	Custom async storage adapter
log	boolean | function	Enables or overrides logging (default: false)

AppStore.use(namespace, options)

Create or get a store by namespace.

Param	Type	Description
namespace	string	Unique key for store (e.g. "theme", "user")

Returns a SingleStore instance.

SingleStore API

Method	Description
hydrate()	Load stored data and mark as hydrated
subscribe(cb, { fireImmediately? })	Listen for data changes
onHydrated(cb)	Called once when hydration completes
set(data)	Set data
clear()	Clear in-memory data
clearStorage()	Clear both in-memory and persistent storage
value	Current store value
initialized	Whether the store has been hydrated

🪵 Logging

You can pass a logger function or enable default console logging:

AppStore.configure({
  storage: customStorage,
  log: (msg, ...args) => console.debug("[AppStore]", msg, ...args),
});

// or simply:
AppStore.configure({ storage: customStorage, log: true });

All log messages include namespace tags like [theme] hydrated.

🧠 Tips

• Call AppStore.configure() only once globally — all stores share the same storage and logger.
• Each store persists independently using its own namespace key.
• To reset everything quickly:

  AppStore.clearAll();
  await customStorage.remove("theme");
  await customStorage.remove("user");
  

🧪 Unit Testing Example (Jest)

import AppStore from "../src/helpers/AppStore";

describe("AppStore", () => {
  const mockStorage = {
    get: jest.fn(async () => JSON.stringify({ theme: "dark" })),
    set: jest.fn(async () => {}),
    remove: jest.fn(async () => {}),
  };

  beforeAll(() => {
    AppStore.configure({ storage: mockStorage, log: false });
  });

  it("hydrates and sets data", async () => {
    const store = AppStore.use("theme");
    await store.hydrate();
    expect(store.value).toEqual({ theme: "dark" });

    store.set({ theme: "light" });
    expect(store.value.theme).toBe("light");
  });
});

📜 License

MIT © 2025 Chain Platform

💖 Support & Donate

If you find this package helpful, consider supporting the development:

Cryptocurrency	Address
Bitcoin (BTC)	17grbSNSEcEybS1nHh4TGYVodBwT16cWtc
Ethereum (ETH)	0xa2fd119a619908d53928e5848b49bf1cc15689d4
Tron (TRX)	TYL8p2PLCLDfq3CgGBp58WdUvvg9zsJ8pd
DOGE (DOGE)	DDfKN2ys4frNaUkvPKcAdfL6SiVss5Bm19
USDT (SOLANA)	cPUZsb7T9tMfiZFqXbWbRvrUktxgZQXQ2Ni1HiVXgFm

Your contribution helps maintain open-source development under the Chain Platform ecosystem 🚀