strata-storage

strata-storage

One storage API across web, iOS and Android — zero runtime dependencies.

Docs · npm · GitHub · Changelog · AI Guide · Support

[!IMPORTANT] In a Capacitor app, run npx cap sync after installing. Without it the native module is never copied into your iOS/Android projects and the native adapters — secure, sqlite, preferences, filesystem — fail silently on device while working fine in the browser.

Strata Storage gives you one get/set/remove/query/subscribe API over every storage backend a cross-platform app touches: localStorage, sessionStorage, IndexedDB, cookies, the Cache API, the page URL, and — through Capacitor — the iOS Keychain, Android EncryptedSharedPreferences, native SQLite and the filesystem. The core is pure TypeScript with no runtime dependencies; React, Vue, Angular, Capacitor and Firebase are optional peers you install only if you use them. Encryption, compression, TTL, cross-tab sync, integrity checksums and mirrored backups are opt-in per call or per instance.

🧭 Table of Contents #

• 💡 Why strata-storage
• ✨ Features
• 📱 Platform Support
• 📋 Requirements
• 📦 Installation
• 🚀 Quick Start
• 🛠️ Usage
• ⚙️ Configuration
• 🔧 API Reference
• 🧩 Types
• 💻 Command Line
• 🧪 Examples
• 🎛️ Advanced Features
• 🚑 Recovery & Troubleshooting
• 🚧 Limitations
• 📚 Documentation
• 🔄 Changelog
• 🤝 Contributing
• 🗂️ Repository
• 💬 Support
• 📄 License
• 👤 Author
• 🔗 Links
• 🏷️ Keywords

💡 Why strata-storage #

Every cross-platform product re-solves the same problem: pick a storage backend per platform, learn each one's quirks, wrap it for your framework, then bolt on encryption, expiry and cross-tab sync by hand. The result is a per-platform layer nobody wants to own. Strata Storage replaces it with one adapter-based API that behaves identically everywhere, and keeps the runtime package dependency-free so it adds nothing to your dependency tree.

Not the right tool when — you only need localStorage in one web app (use it directly); you need a CommonJS build or Node below 24.13 (this package is ESM-only); you need a server-side or multi-user database (this is client-side key-value storage); or you need cryptographic tamper-proofing from the integrity feature specifically — its checksums are non-cryptographic, so use the encryption feature instead.

✨ Features #

• One API, every backend — the same calls whether the value lives in localStorage, IndexedDB, the URL or the iOS Keychain.
• Zero runtime dependencies — the core is pure TypeScript; every framework and platform binding is an optional peer.
• Provider-free by default — create one instance and import it anywhere. No React context, Vue plugin or Angular module is required, though all three styles are still supported.
• Synchronous API alongside the async one — for initial render and event handlers, on the backends that are genuinely synchronous.
• Opt-in encryption and compression — AES-GCM via Web Crypto, size-thresholded compression, both off by default.
• TTL and expiry — absolute or sliding, with expiry inspection and a cleanup sweep.
• Queries and tags — MongoDB-style conditions over stored values and their tags.
• Cross-tab synchronisation — subscribe to changes made in other tabs of the same origin.
• Recovery features — integrity checksums, durable writes, mirrored read-repair, portable snapshots and scheduled backups.
• Native adapters with no plugin dependencies — SQLite is hand-rolled and the filesystem adapter uses the platform's own FileManager / java.io.File.
• Typed end to end — bundled declarations for every entry point, including each framework sub-path.

📱 Platform Support #

📋 Requirements #

📦 Installation #

yarn add strata-storage

Nothing else is needed for web use. Install only the optional peer you actually import:

yarn add react                          # for strata-storage/react
yarn add vue                            # for strata-storage/vue
yarn add @angular/core @angular/forms   # for strata-storage/angular
yarn add @capacitor/core                # for strata-storage/capacitor
yarn add firebase                       # for strata-storage/firebase

Capacitor apps must then sync the native module, or the native adapters will not work on device:

npx cap sync

An optional interactive wizard can scaffold a configuration file for you — see Command Line.

🚀 Quick Start #

The default storage instance registers the standard web adapters and initialises lazily on first use, so importing the package performs no I/O.

import { storage } from 'strata-storage';

await storage.set('user', { id: 123, name: 'Ada Lovelace' });
const user = await storage.get<{ id: number; name: string }>('user');

await storage.remove('user');

🛠️ Usage #

Your own configured instance

defineStorage() is the same factory the default instance is built from. Create one at module scope and import it anywhere — no provider needed.

import { defineStorage } from 'strata-storage';

export const storage = defineStorage({
  defaultStorages: ['indexedDB', 'localStorage'],
  encryption: { enabled: true, password: process.env.STORAGE_KEY! },
});

await storage.set('token', '…', { encrypt: true });

It registers memory, localStorage, sessionStorage, indexedDB, cookies and cache. Register the URL adapter and the native adapters yourself when you need them.

React

Bind the hooks to an instance once, then use them in any component.

// storage.ts
import { defineStorage } from 'strata-storage';
import { createStrataHooks } from 'strata-storage/react';

export const storage = defineStorage();
export const { useStorage, useStorageQuery, useStorageTTL } = createStrataHooks(storage);

// Settings.tsx
import { useStorage } from './storage';

function Settings() {
  const [theme, setTheme, loading] = useStorage<string>('theme', 'light');
  if (loading) return <p>Loading…</p>;
  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>Theme: {theme}</button>
  );
}

<StrataProvider instance={storage}> still works if you prefer context.

Vue

import { defineStorage } from 'strata-storage';
import { createStrataComposables } from 'strata-storage/vue';

export const storage = defineStorage();
export const { useStorage, useStorageQuery, useStorageTTL } = createStrataComposables(storage);

The classic StrataPlugin remains available, and each built-in composable also accepts an instance as its last argument.

Angular

import { bootstrapApplication } from '@angular/platform-browser';
import { defineStorage } from 'strata-storage';
import { provideStrata } from 'strata-storage/angular';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, { providers: [provideStrata(defineStorage())] });

StrataService is then injectable and returns RxJS Observables. StrataModule.forRoot(config) remains for NgModule applications.

Native adapters (iOS and Android)

import { defineStorage } from 'strata-storage';
import { registerCapacitorAdapters } from 'strata-storage/capacitor';

const storage = defineStorage();
await registerCapacitorAdapters(storage);

await storage.set('token', value, { storage: 'secure' }); // Keychain / EncryptedSharedPreferences

PreferencesAdapter, SecureAdapter, SqliteAdapter and FilesystemAdapter are also exported individually when you need per-adapter configuration. Each SqliteAdapter binds to one (database, table) pair, so separate logical stores map to separate physical files and cannot collide.

The synchronous API

storage.setSync('lastTab', 'inbox');
const tab = storage.getSync<string>('lastTab');
storage.removeSync('lastTab');

Available on memory, localStorage, sessionStorage, cookies and url only, and it cannot encrypt or compress — see Limitations.

The URL adapter

Persists small UI state in the page URL so it survives reloads and shareable links, and emits change events on popstate/hashchange.

import { defineStorage, URLAdapter } from 'strata-storage';

const storage = defineStorage();
storage.registerAdapter(new URLAdapter());

storage.setSync('tab', 'pending', { storage: 'url' });
const tab = storage.getSync<string>('tab', { storage: 'url' });

⚙️ Configuration #

Passed to defineStorage(config) or new Strata(config):

The URLAdapter takes its own options: mode ('query' | 'hash', default 'query'), prefix (default 'strata.'), history ('push' | 'replace', default 'replace') and maxLength (default 2000).

Full reference: Configuration.

🔧 API Reference #

An index of the main surface. Full signatures and behaviour live on the docs site.

🧩 Types #

The types a consumer touches directly. Full definitions: Types.

type StorageType =
  | 'memory' | 'localStorage' | 'sessionStorage' | 'indexedDB' | 'cookies' | 'cache' | 'url'
  | 'preferences' | 'secure' | 'sqlite' | 'filesystem';

interface StorageOptions {
  storage?: StorageType;      // target a specific adapter
  ttl?: number;               // milliseconds
  sliding?: boolean;          // reset the TTL on each read
  tags?: string[];            // for query()
  encrypt?: boolean;          // per-call override (async only)
  compress?: boolean;         // per-call override (async only)
  verify?: boolean;           // integrity check on read
  durable?: boolean;          // read-back-and-retry on write
}

interface StrataConfig {
  defaultStorages?: StorageType[];
  adapters?: { /* per-adapter settings — see Configuration */ };
  encryption?: EncryptionConfig;
  compression?: CompressionConfig;
  sync?: SyncConfig;
  integrity?: boolean;
  durableWrites?: boolean;
  mirror?: StorageType[];
  autoBackup?: { interval: number; storage: StorageType };
  debug?: boolean;
}

💻 Command Line #

npx strata-storage <command>

The CLI is optional — everything it produces can be written by hand.

🧪 Examples #

🎛️ Advanced Features #

• Encryption — AES-GCM through Web Crypto, per instance or per call. →
• Compression — applied above a byte threshold you set. →
• TTL and expiry — absolute or sliding, with a cleanup sweep. →
• Queries — MongoDB-style conditions over values and tags. →
• Cross-tab sync — change notifications across tabs of one origin. →
• Integrity, durable writes, mirroring, snapshots — the opt-in recovery set, all off by default. →
• Migrations — an experimental adapter-level utility for reshaping stored data. →
• Firebase sync — mirror values to Firestore or the Realtime Database. →

🚑 Recovery & Troubleshooting #

More: Troubleshooting · FAQ.

🚧 Limitations #

• ESM only. There is no CommonJS build. engines.node is >=24.13.0, where Node can require() an ESM graph; on older Node a require('strata-storage') will fail.
• No automated test suite. This is a deliberate project decision — yarn typecheck, yarn lint and yarn build are the gates, in local development and in CI. There is no unit or integration coverage to point at.
• Native behaviour cannot be verified from web or Node. The iOS and Android adapters depend on your Capacitor project's own configuration, so verify them on a real device using the device-verification guide.
• Integrity checksums are not cryptographic. They are FNV-1a: they cheaply catch accidental corruption such as truncated writes, and they do not resist deliberate tampering. Use encryption for that.
• The synchronous API is genuinely limited. It works only on memory, localStorage, sessionStorage, cookies and url, and it cannot encrypt or compress.
• The URL adapter is not durable storage. URLs have practical length limits around 2,000 characters, and in 'query' mode the data is sent to the server and appears in its logs. Use 'hash' mode to keep it client-side.
• Node support is minimal. Only the memory adapter is available outside a browser, so values do not persist across processes.
• Web adapters share their storage area, and identify their own data by shape. localStorage, sessionStorage and cookies are shared with every other script on the origin. An adapter treats a key as its own only when the stored value is a StorageValue envelope, so keys(), the TTL sweep and clear() never touch another application's data, and a value we cannot read is skipped at debug rather than reported as an error. The consequence to know about: a key written to the same area by something other than this library is invisible to keys() by design. Call setLogLevel('debug') to see what is being skipped and why.
• Keys are prefixed strata: since 3.0.0, and that is a breaking change. Existing data migrates itself on read, so most consumers do nothing. 🔴 But if anything outside this library reads a physical key directly — a pre-paint theme script, a logger reading its own level — set defineStorage({ keyPrefix: false }). Migration keeps the data reachable through this library; it cannot fix a hard-coded reader. See Changelog.
• Firebase adapter names are not in the StorageType union. 'firestore' and 'realtime' are runtime names, so strict TypeScript may need a cast on the options object.

📚 Documentation #

🔄 Changelog #

Latest release: 2.8.5 — documentation only: the at-a-glance table above reported the previous version, because it is a static duplicate of package.json. Full history in the changelog.

Full history: CHANGELOG.md.

🤝 Contributing #

Fork and open a pull request — see CONTRIBUTING.md for setup, standards, and how to request collaborator access. main is protected: every change lands through a reviewed pull request.

🗂️ Repository #

src/            TypeScript source — core, adapters, features, framework integrations
dist/           build output (published)
ios/            native iOS plugin sources (published, for Capacitor)
android/        native Android plugin sources (published, for Capacitor)
scripts/        build script and the npx CLI (published)
docs/           internal project records — NOT the docs site
example-apps/   runnable demo application

The documentation site lives in its own repository: aoneahsan/strata-storage-docs.

💬 Support #

Questions and bugs: open an issue.

If this package saves you time, you can support its maintenance at aoneahsan.com/payment.

📄 License #

MIT © Ahsan Mahmood — see LICENSE.

👤 Author #

Ahsan Mahmood — aoneahsan.com · GitHub · LinkedIn · aoneahsan@gmail.com

🔗 Links #

🏷️ Keywords #

storage · capacitor · localstorage · indexeddb · sqlite · keychain · cross-platform · zero-dependencies · react · vue · angular · typescript