unstorage

What is unstorage?

The 'unstorage' npm package is a versatile storage utility that provides a unified API for interacting with various storage backends. It allows developers to easily switch between different storage mechanisms such as local storage, session storage, and even remote storage solutions without changing the core logic of their applications.

What are unstorage's main functionalities?

Local Storage

This feature allows you to interact with local storage using a simple API. You can set, get, and remove items from local storage.

const { createStorage } = require('unstorage');
const localStorage = createStorage();

// Set a value
await localStorage.setItem('key', 'value');

// Get a value
const value = await localStorage.getItem('key');
console.log(value); // Outputs: 'value'

// Remove a value
await localStorage.removeItem('key');

Session Storage

This feature allows you to interact with session storage using the same API as local storage. You can set, get, and remove items from session storage.

const { createStorage } = require('unstorage');
const sessionStorage = createStorage({ driver: 'session' });

// Set a value
await sessionStorage.setItem('key', 'value');

// Get a value
const value = await sessionStorage.getItem('key');
console.log(value); // Outputs: 'value'

// Remove a value
await sessionStorage.removeItem('key');

Remote Storage

This feature allows you to interact with remote storage solutions via HTTP. You can set, get, and remove items from a remote storage backend.

const { createStorage } = require('unstorage');
const remoteStorage = createStorage({ driver: 'http', baseURL: 'https://api.example.com/storage' });

// Set a value
await remoteStorage.setItem('key', 'value');

// Get a value
const value = await remoteStorage.getItem('key');
console.log(value); // Outputs: 'value'

// Remove a value
await remoteStorage.removeItem('key');

Other packages similar to unstorage

localforage

LocalForage is a fast and simple storage library for JavaScript. It improves the offline experience of your web app by using asynchronous storage (IndexedDB or WebSQL) with a simple, localStorage-like API. Compared to unstorage, LocalForage is more focused on client-side storage and does not provide a unified API for different storage backends.

idb-keyval

idb-keyval is a small library that provides a simple key-value store backed by IndexedDB. It is very lightweight and easy to use, making it a good choice for simple storage needs. However, it lacks the flexibility and unified API of unstorage, which supports multiple storage backends.

store2

store2 is a versatile storage library for all JavaScript environments, including Node.js and browsers. It provides a unified API for localStorage, sessionStorage, and memory storage. While it offers similar functionality to unstorage, it does not support remote storage solutions.

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
  • snapshot(storage, base?)
  • restoreSnapshot(storage, data, base?)
  • prefixStorage(storage, data, base?)
• Storage Server
• Drivers
  • fs (node)
  • localStorage (browser)
  • memory (universal)
  • overlay (universal)
  • http (universal)
  • redis
  • cloudflare-kv
• 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$', { flag: 1 })

storage.removeMeta(key)

Remove meta for a specific key by adding a $ suffix.

await storage.removeMeta('foo:bar',)
// Same as storage.removeMeta('foo:bar$')

storage.getKeys(base?)

Get all keys. Returns an array of strings.

Meta keys (ending with $) will be filtered.

If a base is provided, only keys starting with the base will be returned also only mounts starting with base will be queried. Keys still have a 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)

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.

import { createStorage } from 'unstorage'
import fsDriver from 'unstorage/drivers/fs'

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

storage.mount('/output', fsDriver({ base: './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')

restoreSnapshot(storage, data, base?)

Restore snapshot created by snapshot().

await restoreSnapshot(storage, { 'foo:bar': 'baz' }, '/etc2')

prefixStorage(storage, data, base?)

Create a namespaced instance of main storage.

All operations are virtually prefixed. Useful to create shorcuts and limit access.

import { createStorage, prefixStorage } from 'unstorage'

const storage = createStorage()
const assetsStorage = prefixStorage(storage, 'assets')

// Same as storage.setItem('assets:x', 'hello!')
await assetsStorage.setItem('x', 'hello!')

Storage Server

We can easily expose unstorage instance to an 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)

// Alternatively we can use `storage.handle` as a middleware
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 the real filesystem using directory structure for nested keys. Supports watching using chokidar.

This driver implements meta for each key including mtime (last modified time), atime (last access time), and size (file size) using fs.stat.

import { createStorage } from 'unstorage'
import fsDriver from 'unstorage/drivers/fs'

const storage = createStorage({
  driver: 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 { createStorage } from 'unstorage'
import localStorageDriver from 'unstorage/drivers/localstorage'

const storage = createStorage({
  driver: localStorageDriver({ base: 'app:' })
})

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 { createStorage } from 'unstorage'
import memoryDriver from 'unstorage/drivers/memory'

const storage = createStorage({
  driver: memoryDriver()
})

overlay (universal)

This is a special driver that creates a multi-layer overlay driver.

All write operations happen on the top level layer while values are read from all layers.

When removing a key, a special value __OVERLAY_REMOVED__ will be set on the top level layer internally.

In the example below, we create an in-memory overlay on top of fs. No changes will be actually written to the disk.

import { createStorage } from 'unstorage'
import overlay from 'unstorage/drivers/memory'
import memory from 'unstorage/drivers/memory'
import fs from 'unstorage/drivers/fs'

const storage = createStorage({
  driver: overlay({
    layers: [
      memory(),
      fs({ base: './data' })
    ]
  })
})

http (universal)

Use a remote HTTP/HTTPS endpoint as data storage. Supports built-in http server methods.

This driver implements meta for each key including mtime (last modified time) and status from HTTP headers by making a HEAD request.

import { createStorage } from 'unstorage'
import httpDriver from 'unstorage/drivers/http'

const storage = createStorage({
  driver: httpDriver({ base: 'http://cdn.com' })
})

Options:

• base: Base URL for urls

Supported HTTP Methods:

• getItem: Maps to http GET. Returns deserialized value if response is ok
• hasItem: Maps to http HEAD. Returns true if response is ok (200)
• setItem: Maps to http PUT. Sends serialized value using body
• removeIterm: Maps to DELETE
• clear: Not supported

redis

Store data in a redis storage using ioredis.

import { createStorage } from 'unstorage'
import redisDriver from 'unstorage/drivers/redis'

const storage = createStorage({
  driver: redisDriver({
     base: 'storage:'
  })
})

Options:

• base: Prefix all keys with base
• url: (optional) connection string

See ioredis for all available options.

lazyConnect option is enabled by default so that connection happens on first redis operation.

cloudflare-kv

Store data in Cloudflare KV.

You need to create and assign a KV. See KV Bindings for more information.

import { createStorage } from 'unstorage'
import cloudflareKVDriver from 'unstorage/drivers/cloudflare-kv'

// Using binding name to be picked from globalThis
const storage = createStorage({
  driver: cloudflareKVDriver({ binding: 'STORAGE' })
})

// Directly setting binding
const storage = createStorage({
  driver: cloudflareKVDriver({ binding: globalThis.STORAGE })
})

// Using from Durable Objects and Workers using Modules Syntax
const storage = createStorage({
  driver: cloudflareKVDriver({ binding: this.env.STORAGE })
})

// Using outside of Cloudflare Workers (like Node.js)
// Not supported Yet!

Options:

• binding: KV binding or name of namespace. Default is STORAGE.

Making custom drivers

It is possible to extend unstorage by creating custom drives.

• 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 myStorageDriver = defineDriver((_opts) => {
  return {
    async hasItem (key) {},
    async getItem (key) {},
    async setItem(key, value) {},
    async removeItem (key) {},
    async getKeys() {},
    async clear() {},
    async dispose() {},
    // async watch(callback) {}
  }
})

const storage = createStorage({
  driver: myStorageDriver()
})

Contribution

• Clone repository
• Install dependencies with yarn install
• Use yarn dev to start jest watcher verifying changes
• Use yarn test before pushing to ensure all tests and lint checks passing

License

MIT

Changelog

0.4.1 (2022-05-04)

Features

• expose key utils normalizeKey, joinKeys and normalizeBaseKey (be81fa8)