unstorage
Universal Storage Layer
- Works in all environments (Browser, NodeJS and Workers)
- Asynchronous API
- Unix-style mountable paths (multi driver)
- Default in-memory storage
- Tree-shakable and lightweight core
- Native aware value serialization and deserialization
- Restore initial state (hydration)
- State snapshot
- Driver agnostic watcher
- HTTP Storage server (cli and programmatic)
Table of Contents
Usage
Install unistorage
npm package:
yarn add unistorage
npm i unistorage
import { createStorage } from 'unistorage'
const storage = createStorage()
await storage.getItem('foo:bar')
await storage.getItem('/foo/bar')
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 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 storage.
If value is not string, it will be stringified.
If value is undefined
, it is same as calling removeItem(key)
.
await storage.setItem('foo:bar', 'baz')
storage.setItems(base, items)
Batch update items. Internally calls one-by-one to the driver. Useful to restore/hydrate state.
await storage.setItems('/', { 'foo:bar': 'baz' })
storage.removeItem(key)
Remove a value from storage.
await storage.removeItem('foo:bar')
storage.getKeys(base?)
Get all keys. Returns an array of string
.
If a base is provided, only keys starting with base will be returned also only mounts starting with base will be queried. Keys still have full path.
await storage.getKeys()
storage.clear(base?)
Removes all stored key/values. If a base is provided, only mounts matching base will be cleared.
await storage.clear()
storage.dispose()
Disposes all mounted storages to ensure there are no open-handles left. Call it before exiting process.
Note: Dispose also clears in-memory data.
await storage.dispose()
storage.mount(mountpoint, driver, initialState?)
By default, everything is stored in memory. We can mount additional storage space in a Unix-like fashion.
When operating with a key
that starts with mountpoint, instead of default storage, mounted driver will be called.
If initialState
argument is provided, restores/hydrates state of mountpoint using setItems
.
import { createStorage } from 'unistorage'
import fsDriver from 'unistorage/drivers/fs'
const storage = createStorage()
storage.mount('/output', fsDriver({ dir: './output' }))
await storage.setItem('/output/test', 'works')
await storage.setItem('/foo', 'bar')
storage.unmount(mountpoint, dispose = true)
Unregisters a mountpoint. Has no effect if mountpoint is not found or is root.
await storage.unmount('/output')
storage.watch(callback)
Starts watching on all mountpoints. If driver does not supports watching, only emits even when storage.*
methods are called.
await storage.watch((event, key) => { })
Utils
snapshot(storage, base?)
Snapshot from all keys in specified base into a plain javascript object (string: string). Base is removed from keys.
import { snapshot } from 'unstorage'
const data = await snapshot(storage, '/etc')
Storage Server
We can easily expose unstorage instance to a http server to allow remote connections.
Request url is mapped to key and method/body mapped to function. See below for supported http methods.
🛡️ Security Note: Server is unprotected by default. You need to add your own authentication/security middleware like basic authentication.
Also consider that even with authentication, unstorage should not be exposed to untrusted users since it has no protection for abuse (DDOS, Filesystem escalation, etc)
Programmatic usage:
import { listen } from 'listhen'
import { createStorage } from 'unstorage'
import { createStorageServer } from 'unstorage/server'
const storage = createStorage()
const storageServer = createStorageServer(storage)
await listen(storage.handle)
Using CLI:
npx unstorage .
Supported HTTP Methods:
GET
: Maps to storage.getItem
. Returns list of keys on path if value not found.HEAD
: Maps to storage.hasItem
. Returns 404 if not found.PUT
: Maps to storage.setItem
. Value is read from body and returns OK
if operation succeeded.DELETE
: Maps to storage.removeIterm
. Returns OK
if operation succeeded.
Drivers
fs
(node)
Maps data to real filesystem using directory structure for nested keys. Supports watching using chokidar.
import fsDriver from 'unstorage/drivers/memory'
await storage.mount('/tmp', fsDriver({ base: './tmp' }))
Options:
base
: Base directory to isolate operations on this directoryignore
: Ignore patterns for watch watchOptions
: Additional chokidar options.
localStorage
(browser)
Store data in localStorage.
import lsDriver from 'unstorage/drivers/memory'
await storage.mount('local', lsDriver({ base: 'myapp' }))
Options:
base
: Add ${base}:
to all keys to avoid collisionlocalStorage
: Optionally provide localStorage
objectwindow
: Optionally provide window
object
memory
(universal)
Keeps data in memory using Set.
By default it is mounted to top level so it is unlikely you need to mount it again.
import memoryDriver from 'unstorage/drivers/memory'
storage.mount('/tmp', memory())
http
(universal)
Use a remote HTTP/HTTPS endpoint as data storage. Supports built-in http server methods.
import httpDriver from 'unstorage/drivers/http'
await storage.mount('local', lsDriver({ base: 'http://myapp.com' }))
Options:
Supported HTTP Methods:
getItem
: Maps to http GET
. Returns deserialized value if response is okhasItem
: Maps to http HEAD
. Returns true
if response is ok (200)setItem
: Maps to http PUT
. Sends serialized value using bodyremoveIterm
: Maps to DELETE
clear
: Not supported
Custom drivers
It is possible to extend unstorage by creating custom driver and mounting it.
- Keys are always normalized in
foo:bar
convention - Mount base is removed
- Returning promise or direct value is optional
- You should cleanup any open watcher and handlers in
dispose
- Value returned by
getItem
can be a serializable object or string - Having
watch
method, disables default handler for mountpoint. You are responsible to emit event on getItem
, setItem
and removeItem
.
See src/drivers to inspire how to implement them. Methods can
Example:
import { createStorage, defineDriver } from 'unstorage'
const storage = createStorage()
const myStorageDriver = defineDriver((_opts) => {
return {
async hasItem (key) {},
async getItem (key) {},
async setItem(key, value) {},
async removeItem (key) {},
async getKeys() {},
async clear() {},
async dispose() {},
}
})
await storage.mount('/custom', myStorageDriver())
Contribution
- Clone repository
- Install dependencies with
yarn install
- Use
yarn dev
to start jest watcher verifying changes - Use
yarn test
before push to ensure all tests and lint checks passing
License
MIT