unadlib/localspace: A library that unifies the APIs of IndexedDB, localStorage and other storage into a consistent API

A library that unifies the APIs of IndexedDB, localStorage and other storage into a consistent API - unadlib/localspace

Summary

localspace is a Promise-first TypeScript library that unifies IndexedDB, localStorage, in-memory storage, and React Native AsyncStorage behind a single key-value facade. It adds explicit driver capability reporting, scoped transactions, and a plugin pipeline for TTL, compression, and AES-GCM encryption. The package is MIT-licensed and ships ESM, CommonJS, and UMD builds with TypeScript declarations.

What it is useful for

localspace is useful when one application needs a consistent storage interface across web and React Native without picking drivers per platform. It fits offline-capable apps, multi-instance apps that need isolated namespaces through createInstance, and projects that want a promise-only successor to localForage (the README is explicit that it is not a callback-compatible drop-in). The capabilities() method returns a frozen snapshot of what the selected driver supports, so code can detect transactions, atomic batches, persistent storage, and Storage Buckets before relying on them. The plugin pipeline covers cross-driver concerns such as expiring cached values and encrypting at rest without re-implementing those flows in every consumer.

How engineers can use it

Install with pnpm add localspace (or npm install localspace) and import the default export. The minimal path is await localspace.setItem('user', { name: 'Ada' }) followed by await localspace.getItem('user'). For isolated state, create a dedicated instance:

const cache = localspace.createInstance({ name: 'my-app', storeName: 'cache' });

For atomic multi-key updates, call runTransaction('readwrite', async (tx) => { ... }); this is supported on IndexedDB and the memory driver and rejected with UNSUPPORTED_OPERATION on localStorage and AsyncStorage. Plugins like ttlPlugin, compressionPlugin, and encryptionPlugin are passed in the constructor or added with use() before the first storage call, after which registration rejects with CONFIG_LOCKED. React Native requires localspace/react-native and an explicit AsyncStorage adapter; runtime auto-detection was removed in 3.0.

Documented constraints: the value contract rejects Date, Map, Set, bigint, Blob, DataView, and class instances with SERIALIZATION_FAILED, and the memory driver is not an automatic fallback when persistent storage fails. WebSQL and legacy prefixed IndexedDB are not supported.