unstorage

Universal key-value Storage

• 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
• Abstract watcher

WIP:

• Key expiration
• Storage server

Table of Contents

• Drivers
• Usage
• Storage Interface
  • storage.hasItem(key)
  • storage.getItem(key)
  • storage.setItem(key, value)
  • storage.setItems(base, items)
  • storage.removeItem(key)
  • storage.getKeys(base?)
  • storage.clear(base?)
  • storage.dispose()
  • storage.mount(mountpoint, driver, initialState?)
  • storage.unmount(mountpoint, dispose = true)
  • storage.watch(callback)
• Utils
  • snapshot(storage, base?)
• Drivers
  • fs (node)
  • localStorage (browser)
  • memory (universal)
• Contribution
• License

Drivers

• Memory (Universal)
• Filesystem (NodeJS)
• LocalStorage (Browser)
• HTTP (Universal)
• Cookies (Browser)
• Location params (Browser)
• S3 (Universal)
• Cloudflare KV (Workers and Universal)
• Github (Universal)

Usage

Install unistorage npm package:

yarn add unistorage
# or
npm i unistorage

import { createStorage } from 'unistorage'

// Create a storage container with default memory storage
const storage = createStorage()

await storage.getItem('foo:bar')
// or
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'

// Create a storage container with default memory storage
const storage = createStorage()

storage.mount('/output', fsDriver({ dir: './output' }))

//  Writes to ./output/test file
await storage.setItem('/output/test', 'works')

// Adds value to in-memory storage
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')

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 directory
• ignore: 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 collision
• localStorage: Optionally provide localStorage object
• window: 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())

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