Holster API
The Holster API is returned by calling Holster(). It's the same in Node.js, Deno, Bun and the browser:
import Holster from "@mblaney/holster/src/holster.js"
const holster = Holster()See Options for what can be passed to Holster().
Chaining requests
Every request starts with get(), which is given a top level key. From there, next() resolves a nested key and can be repeated as many times as needed. The chain then ends in one of:
a callback passed to
get()ornext(), orawaiton the chain, to read the dataput()to write data
await holster.get("app").next("settings").next("theme").put("dark")
holster.get("app").next("settings").on(console.log)Callbacks or await
Every function that returns data accepts an optional callback. Leave it out and the request can be awaited instead:
// With a callback.
holster.get("app").next("settings", console.log)
// With await.
const settings = await holster.get("app").next("settings")A read that fails, or finds nothing, returns null. Errors are logged to the console rather than returned. put() is the exception: its callback receives an error message, and an awaited put() rejects with an Error.
on() always needs a callback, since it can be called many times. A request with a lex query ends the chain, so it can't be followed by other functions.
Nested data
Objects can be nested to any depth. Each object is stored as its own node in the graph, and the Holster API handles that for you: it creates nodes when you write objects, and follows the references between them when you read.
await holster.get("posts").put({
"2026-10-01-hello-world": {
title: "Hello world",
author: {name: "Alice", url: "https://alice.example"},
},
})
const name = await holster
.get("posts")
.next("2026-10-01-hello-world")
.next("author")
.next("name")
console.log(name) // "Alice"
const post = await holster.get("posts").next("2026-10-01-hello-world")
console.log(post)
// {title: "Hello world", author: {name: "Alice", url: "https://alice.example"}}Writing an object merges it with the data already there, rather than replacing it, so properties you don't include are left as they are. Data can't be fully deleted in a distributed database, since other devices may still have a copy. Instead, set a property to null: this tombstone replaces the value everywhere it syncs to. Its key stays in the node with a null value, so skip null values when you iterate over a node's entries.
Arrays
Arrays can't be stored directly, but a list of unique strings, such as tags or URLs, can be stored as an object with a key for each value. These helpers convert between the two:
// ["a", "b"] becomes {a: true, b: true}.
const toObject = array => Object.fromEntries(array.map(value => [value, true]))
// Keeps only the keys whose value is true.
const toArray = object =>
Object.entries(object ?? {})
.filter(([, keep]) => keep === true)
.map(([value]) => value)Since writing an object merges it with what's already stored, leaving a value out of a later write doesn't remove it. Set its key to false instead:
await holster
.get("posts")
.next("2026-10-01-hello-world")
.next("tags")
.put(toObject(["news", "local"]))
// Remove one value.
await holster
.get("posts")
.next("2026-10-01-hello-world")
.next("tags")
.next("local")
.put(false)
const tags = toArray(
await holster.get("posts").next("2026-10-01-hello-world").next("tags"),
)
console.log(tags) // ["news"]Order isn't kept, so sort the array after reading it if order matters. Holster reserves "_" for each node's metadata, so it can't be one of the keys created by toObject(). For values that aren't unique strings, such as objects, see Sets.
Public space
Data written with the Holster API is in "public space", available to every client to read and update. Use it for testing or private applications, and use user space for anything else.
User space
Data written with the User API is in "user space", stored under the public key of the account that wrote it. Every update is signed by that account and verified before it's stored, so only the owner can change their data. A relay started with the secure option only accepts signed data, so nothing can be written in public space at all.
Signing controls who can change data, not who can read it. Data in user space can be read by every client, the same as public space. To keep data private, encrypt it before writing it, see Encrypting data.