Utilities

All general utilities are tree-shakable named exports from unstorage.

#Namespaces

prefixStorage(storage, prefix) creates a storage view that automatically prefixes keys. Reads, writes, key listing, batch operations, and watch events are mapped back to the namespace.

import { createStorage, prefixStorage } from "unstorage";

const storage = createStorage();
const assets = prefixStorage(storage, "assets");

await assets.setItem("logo", "logo.svg");
// Equivalent to storage.setItem("assets:logo", "logo.svg")

await assets.getKeys();
// ["logo"]

A namespace is a view over the original storage, not a separate store. Lifecycle methods and mount-inspection methods are still shared with the original instance, so prefixStorage is not a security boundary.

You can also provide a value type:

type Post = { title: string; body: string };

const posts = prefixStorage<Post>(storage, "posts");
const post = await posts.getItem("welcome");
// Post | null

#Snapshots

#snapshot(storage, base)

Reads all values under a base into a plain object. The base is removed from the returned keys.

import { snapshot } from "unstorage";

const data = await snapshot(storage, "settings");
// { theme: "dark", "editor:font": "mono" }

Pass an empty string to snapshot the whole storage:

const data = await snapshot(storage, "");

#restoreSnapshot(storage, data, base?)

Writes a snapshot to a storage instance, optionally under a new base.

import { restoreSnapshot } from "unstorage";

await restoreSnapshot(storage, data, "backup");

#Key helpers

Use the same key normalization rules as unstorage when constructing keys dynamically:

import { joinKeys, normalizeKey } from "unstorage";

normalizeKey("/users//1/profile");
// "users:1:profile"

joinKeys("users", "1", "profile");
// "users:1:profile"

normalizeBaseKey(base) is also exported and returns a normalized base with a trailing colon.

#Node.js tracing

withTracing(storage) wraps storage operations with Node.js diagnostics channels. Import it from the dedicated unstorage/tracing entry to keep Node-specific tracing out of other bundles.

import { createStorage } from "unstorage";
import { withTracing } from "unstorage/tracing";

const storage = withTracing(createStorage());
await storage.getItem("users:1");

Operations publish to tracing channels such as unstorage.getItem, unstorage.setItem, and unstorage.getKeys. Trace context includes normalized keys and, when available, the selected mount and driver. In runtimes without node:diagnostics_channel, withTracing returns the storage unchanged.