unstorage-sync

A synchronous fork of unstorage — same multi-driver, mountable, key-value API, but every operation is sync. No promises, no await.

When to use

Use unstorage-sync when you need a small key-value abstraction over storage backends that are themselves synchronous: in-memory maps, LRU caches, localStorage / sessionStorage, or Node fs.*Sync. The original unstorage is the right choice if you need async backends like Redis, S3, Cloudflare KV, etc.

Features

• Fully synchronous API — getItem/setItem/getKeys/... all return values directly
• Unix-style driver mounting to combine multiple storages under one tree
• Default in-memory storage
• Auto JSON value serialization and deserialization
• Binary and raw value support
• Snapshots and hydration (snapshot / restoreSnapshot)
• Storage watcher
• Tree-shakable utils and tiny core

Install

npm install unstorage-sync
# or
pnpm add unstorage-sync
# or
yarn add unstorage-sync

Usage

import { createSyncStorage } from "unstorage-sync";
import memory from "unstorage-sync/drivers/memory";

const storage = createSyncStorage({ driver: memory() });

storage.setItem("foo:bar", { hello: "world" });

const value = storage.getItem("foo:bar");
// → { hello: "world" }

storage.hasItem("foo:bar"); // → true
storage.getKeys("foo");     // → ["foo:bar"]
storage.removeItem("foo:bar");

Mounting drivers

import { createSyncStorage } from "unstorage-sync";
import memory from "unstorage-sync/drivers/memory";
import fs from "unstorage-sync/drivers/fs";

const storage = createSyncStorage();
storage.mount("/cache", memory());
storage.mount("/data", fs({ base: "./data" }));

storage.setItem("/data/users.json", { name: "Ada" });
storage.setItem("/cache/sessions:abc", "token");

Prefixed storage

import { createSyncStorage, prefixStorage } from "unstorage-sync";

const storage = createSyncStorage();
const userStorage = prefixStorage(storage, "user");

userStorage.setItem("name", "Ada");
storage.getItem("user:name"); // → "Ada"

Snapshots

import { snapshot, restoreSnapshot } from "unstorage-sync";

const data = snapshot(storage, "/data");
restoreSnapshot(otherStorage, data, "/data");

Watching changes

const unwatch = storage.watch((event, key) => {
  console.log(event, key); // "update" | "remove", key
});

storage.setItem("foo", "bar"); // triggers watcher
unwatch();

Built-in drivers

| Driver | Import | Backend | |---|---|---| | memory | unstorage-sync/drivers/memory | In-memory Map (default) | | lru-cache | unstorage-sync/drivers/lru-cache | lru-cache | | localstorage | unstorage-sync/drivers/localstorage | window.localStorage | | session-storage | unstorage-sync/drivers/session-storage | window.sessionStorage | | fs | unstorage-sync/drivers/fs | Node fs (sync), with ignore patterns | | fs-lite | unstorage-sync/drivers/fs-lite | Node fs (sync), minimal | | null | unstorage-sync/drivers/null | No-op | | overlay | unstorage-sync/drivers/overlay | Layered driver over other sync drivers |

Note: unstorage-sync only ships drivers whose backing storage is natively synchronous. For async backends (HTTP, Redis, Cloudflare KV, S3, etc.), use unstorage.

Custom drivers

Any object matching the Driver interface from unstorage-sync can be passed via mount() or createSyncStorage({ driver }). All driver methods must be synchronous.

import type { Driver } from "unstorage-sync";

const myDriver: Driver = {
  name: "custom",
  hasItem(key) { /* ... */ return false; },
  getItem(key) { /* ... */ return null; },
  setItem(key, value) { /* ... */ },
  removeItem(key) { /* ... */ },
  getKeys() { return []; },
};

Differences from upstream unstorage

• createStorage is renamed to createSyncStorage
• Every method on Storage and Driver is synchronous — return types are no longer wrapped in Promise
• Async-only drivers (HTTP, Redis, S3, Azure, Cloudflare, MongoDB, Vercel, Netlify, Deno KV, etc.) are removed
• fs driver loses its chokidar-based watch() (no sync watcher equivalent); use fs.watch directly if needed
• The HTTP server and tracing entrypoints are removed

Credits

This is a fork of unstorage by @pi0 and the unjs contributors, distributed under the same MIT license.

License

MIT