README
unstorage
🌍 💾 Universal Storage Layer
Why ❓
Typically, we choose one or more data storages based on our use-cases like a filesystem, a database like Redis, Mongo, or LocalStorage for browsers but it will soon start to be lots of trouble for supporting and combining more than one or switching between them. For javascript library authors, this usually means they have to decide how many platforms they support and implement storage for each.
💡 Unstorage solution is a unified and powerful Key-Value (KV) interface that allows combining drivers that are either built-in or can be implemented via a super simple interface and adding conventional features like mounting, watching, and working with metadata.
Comparing to similar solutions like localforage, unstorage core is almost 6x smaller (28.9 kB vs 4.7 kB), using modern ESM/Typescript/Async syntax and many more features to be used universally.
✔️ Works in all environments (Browser, NodeJS, and Workers)
✔️ Multiple built-in drivers (Memory, FS, LocalStorage, HTTP, Redis)
✔️ Asynchronous API
✔️ Unix-style driver mounting to combine storages
✔️ Default in-memory storage
✔️ Tree-shakable utils and tiny core
✔️ Driver native and user provided metadata
✔️ Native aware value serialization and deserialization
✔️ Restore initial state (hydration)
✔️ State snapshot
✔️ Driver agnostic watcher
✔️ HTTP Storage server (cli and programmatic)
✔️ Namespaced storage
🚧 Overlay storage (copy-on-write)
🚧 Virtual `fs` interface
🚧 Cached storage
🚧 More drivers: MongoDB, S3 and IndexedDB
📚 Table of Contents
- Usage
- Storage Interface
storage.hasItem(key)
storage.getItem(key)
storage.setItem(key, value)
storage.removeItem(key, removeMeta = true)
storage.getMeta(key, nativeOnly?)
storage.setMeta(key)
storage.removeMeta(key)
storage.getKeys(base?)
storage.clear(base?)
storage.dispose()
storage.mount(mountpoint, driver)
storage.unmount(mountpoint, dispose = true)
storage.watch(callback)
- Utils
- Storage Server
- Drivers
- Making custom drivers
- Contribution
- License
Usage
Install unstorage
npm package:
yarn add unstorage
# or
npm i unstorage
import { createStorage } from 'unstorage'
const storage = createStorage(/* opts */)
await storage.getItem('foo:bar') // or storage.getItem('/foo/bar')
Options:
driver
: Default driver (using memory if not provided)
Storage Interface
storage.hasItem(key)
Checks if storage contains a key. Resolves to either true
or false
.
await storage.hasItem('foo:bar')
storage.getItem(key)
Gets the value of a key in storage. Resolves to either string
or null
.
await storage.getItem('foo:bar')
storage.setItem(key, value)
Add/Update a value to the storage.
If the value is not a string, it will be stringified.
If value is undefined
, it is same as calling removeItem(key)
.
await storage.setItem('foo:bar', 'baz')
storage.removeItem(key, removeMeta = true)
Remove a value (and it's meta) from storage.
await storage.removeItem('foo:bar')
storage.getMeta(key, nativeOnly?)
Get metadata object for a specific key.
This data is fetched from two sources:
- Driver native meta (like file creation time)
- Custom meta set by
storage.setMeta
(overrides driver native meta)
await storage.getMeta('foo:bar') // For fs driver returns an object like { mtime, atime, size }
storage.setMeta(key)
Set custom meta for a specific key by adding a $
suffix.
await storage.setMeta('foo:bar', { flag: 1 })
// Same as storage.setItem('foo:bar