Usage

Discover how to use unstorage in your project.

Installation

Install unstorage npm package:

npm install unstorage

yarn add unstorage

pnpm add unstorage

Usage

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

Interface

hasItem(key, opts?)

Checks if storage contains a key. Resolves to either true or false.

await storage.hasItem("foo:bar");

getItem(key, opts?)

Gets the value of a key in storage. Resolves to either a javascript primitive value or undefined.

await storage.getItem("foo:bar");

getItemRaw(key, opts?)

Note: This is an experimental feature. Please check unjs/unstorage#142 for more information.

Gets the value of a key in storage in raw format.

// Value can be a Buffer, Array or Driver's raw format
const value = await storage.getItemRaw("foo:bar.bin");

setItem(key, value, opts?)

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");

setItemRaw(key, value, opts?)

Note: This is an experimental feature. Please check unjs/unstorage#142 for more information.

Add/Update a value to the storage in raw format.

If value is undefined, it is same as calling removeItem(key).

await storage.setItemRaw("data/test.bin", new Uint8Array([1, 2, 3]));

removeItem(key, opts = { removeMeta = true })

Remove a value (and it's meta) from storage.

await storage.removeItem("foo:bar");

getMeta(key, opts = { 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 }

setMeta(key, opts?)

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 })

removeMeta(key, opts?)

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

await storage.removeMeta("foo:bar");
// Same as storage.removeItem('foo:bar$')

getKeys(base?, opts?)

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();

clear(base?, opts?)

Removes all stored key/values. If a base is provided, only mounts matching base will be cleared.

await storage.clear();

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();

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.

In addition to base, you can set readOnly and noClear to disable write and clear operations.

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");

unmount(mountpoint, dispose = true)

Unregisters a mountpoint. Has no effect if mountpoint is not found or is root.

await storage.unmount("/output");

watch(callback)

Starts watching on all mountpoints. If driver does not supports watching, only emits even when storage.* methods are called.

const unwatch = await storage.watch((event, key) => {});
// to stop this watcher
await unwatch();

unwatch()

Stop all watchers on all mountpoints.

await storage.unwatch();

getMount(key)

Gets the mount point (dirver and base) for a specific key in storage.

storage.mount("cache" /* ... */);
storage.mount("cache:routes" /* ... */);

storage.getMount("cache:routes:foo:bar");
// => { base: "cache:routes:", driver: "..." }

getMounts(base?, { parents: boolean }?)

Gets the mount points on a specific base.

storage.mount("cache" /* ... */);
storage.mount("cache:sub" /* ... */);

storage.getMounts("cache:sub");
// => [{ base: "cache:sub", driver }]

storage.getMounts("cache:");
// => [{ base: "cache:sub", driver }, { base: "cache:", driver }]

storage.getMounts("");
storage.getMounts("cache:sub", { parents: true });
// => [{ base: "cache:sub", driver }, { base: "cache:", driver }, { base: "", driver }]