From append-only logs to files

Pear storage is built from a small set of composable primitives stacked on top of one another:

At the bottom is Hypercore, an append-only log of verified blocks. Everything else in Pear storage ultimately replicates through one or more cores.

Hyperblobs sits on a core when you need opaque objects larger than a single block — it handles chunking and returns stable ids you can store elsewhere.

Hyperdrive is the top layer: path-addressed files and directories, with metadata in a Hyperbee tree and file contents in Hyperblobs.

Understanding that ladder helps you pick the right building block before you reach for a full filesystem API.

Hypercore: append-only blocks

Hypercore is a secure, sparse-replicated append-only log. Each append adds one block; readers verify integrity and optionally decrypt per-block. Hypercore is the foundation for nearly every other Pear data structure.

You can store arbitrary bytes directly in a core:

import Hypercore from 'hypercore'

const core = new Hypercore('./my-core')
await core.ready()

await core.append(Buffer.from('I am a block of data'))

That works for small payloads, but Hypercore blocks have a practical size limit. Storing a large file as one block is inefficient; splitting it manually means tracking chunk order, offsets, and retrieval yourself.

Hyperblobs: large opaque objects

Hyperblobs chunks large data across Hypercore blocks and exposes a simple put/get API. A put returns an id (start, end, length, and related metadata) that you store elsewhere — for example in a Hyperbee key.

import Hypercore from 'hypercore'
import Hyperblobs from 'hyperblobs'

const core = new Hypercore('./blob-core')
const blobs = new Hyperblobs(core)
await blobs.ready()

const id = await blobs.put(Buffer.from('hello world', 'utf-8'))
const data = await blobs.get(id)

Hyperblobs is the right choice when you need object storage — attachments, media, serialized blobs — without file paths or directory semantics. Replication still flows through the underlying Hypercore; peers fetch missing blob blocks like any other core data.

Hyperdrive uses Hyperblobs internally for file contents. You do not need Hyperdrive if all you want is keyed blob storage.

Hyperdrive: paths, metadata, and directories

Hyperdrive combines a Hyperbee metadata tree with a Hyperblobs content store. You get path-based operations — get, put, del, list, existence checks — similar to a filesystem, with the same replication properties as Hypercore.

import Hyperdrive from 'hyperdrive'
import Corestore from 'corestore'

const store = new Corestore('./drive-storage')
const drive = new Hyperdrive(store)
await drive.ready()

await drive.put('/notes/readme.txt', Buffer.from('hello'))
const entry = await drive.get('/notes/readme.txt')

Pear application bundles are Hyperdrives: code, assets, and dependencies staged with pear stage live in a drive that peers replicate. User-facing apps often keep application state in separate cores or drives under Corestore.

Helpers extend the model without changing the stack:

• Localdrive — mirror between a Hyperdrive and a local folder.
• Mirrordrive — copy or sync between two drives.

Choosing a layer

If you do not need path-addressed files shared between peers, prefer Hyperblobs over Hyperdrive. Hyperdrive pays for directory semantics and metadata indexing you may not use.

See also

• Storage and distribution — where cores and drives live on disk in a Pear installation.
• Share append-only databases with Hyperbee — key/value patterns on Hypercore.
• Work with many Hypercores using Corestore — managing multiple cores from one storage root.
• Hypercore reference — append-only log API.
• Hyperdrive reference — filesystem API.
• Hyperbee reference — sorted key/value tree.