# hyperblobs

> A blob store for Hypercore

Latest version **2.12.1** (published 2026-06-05) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install hyperblobs
pnpm add hyperblobs
yarn add hyperblobs
bun add hyperblobs
```

## Health

**Score 50/100 (C)** — status: active.

Positive: no vulnerabilities; has provenance.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.12.1 |
| Published | 2026-06-05 |
| First published | 2021-01-29 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 8 |
| Unpacked size | 34.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 42 |
| Author | Andrew Osheroff |
| Maintainers | mafintosh |
| Keywords | hypercore, blob, store |

## Links

- npm: https://www.npmjs.com/package/hyperblobs
- Repository: https://github.com/holepunchto/hyperblobs
- Homepage: https://github.com/holepunchto/hyperblobs#readme
- Issues: https://github.com/holepunchto/hyperblobs/issues
- npm.io page: https://npm.io/package/hyperblobs

## Dependencies (8)

- [b4a](https://npm.io/package/b4a.md) ^1.6.1
- [streamx](https://npm.io/package/streamx.md) ^2.13.2
- [mutexify](https://npm.io/package/mutexify.md) ^1.4.0
- [bare-events](https://npm.io/package/bare-events.md) ^2.5.0
- [speedometer](https://npm.io/package/speedometer.md) ^1.1.0
- [compact-encoding](https://npm.io/package/compact-encoding.md) ^3.0.0
- [hypercore-crypto](https://npm.io/package/hypercore-crypto.md) ^3.6.1
- [hypercore-errors](https://npm.io/package/hypercore-errors.md) ^1.1.1

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 2.12.1 (latest) — 2026-06-05
- 2.0.0 (next) — 2022-08-18
- 2.12.0 — 2026-05-05
- 2.11.1 — 2026-03-28
- 2.11.0 — 2026-03-28
- 2.10.0 — 2026-03-28
- 2.9.1 — 2026-03-27
- 2.9.0 — 2026-02-16
- 2.8.0 — 2025-01-06
- 2.7.4 — 2024-12-17
- 2.7.3 — 2024-12-17
- 2.7.2 — 2024-12-17
- 2.7.1 — 2024-12-17
- 2.7.0 — 2024-12-17
- 2.6.0 — 2024-12-17
- … 26 more at https://npm.io/package/hyperblobs/versions

## README

# hyperblobs

A simple blob store for Hypercore.

Each blob is identified by its unique bounds within the Hypercore, e.g. `{ byteOffset: 0, blockOffset: 0, blockLength: 5, byteLength: 327680 }`, which makes them easy to save and retrieve:

```js
const blobs = new Hyperblobs(core)
// ID is { byteOffset: 0, blockOffset: 0, blockLength: 1, byteLength: 11 }
const id = await blobs.put(Buffer.from('hello world', 'utf-8'))
await blobs.get(id) // Buffer.from('hello world', 'utf-8')
```

You can also get from start/end bounds within a single blob:

```js
const blobs = new Hyperblobs(core)
// ID is { byteOffset: 0, blockOffset: 0, blockLength: 1, byteLength: 11 }
const id = await blobs.put(Buffer.from('hello world', 'utf-8'))
await blobs.get(id, { start: 1, length: 2 }) // Buffer.from('el', 'utf-8')
```

If the blob is large, there's a Streams interface (`createReadStream` and `createWriteStream`) too.

## Installation

```
npm i hyperblobs
```

## API

```js
const Hyperblobs = require('hyperblobs')
```

#### `const blobs = new Hyperblobs(core, opts)`

Create a new blob store wrapping a single Hypercore.

Options can include:

```js
{
  blockSize: 64KB // The block size that will be used when storing large blobs.
}
```

#### `const id = await blobs.put(blob, opts)`

Store a new blob. If the blob is large, it will be chunked according to `opts.blockSize` (default 64KB).

Options can include:

```js
{
  blockSize: 64KB, // The block size that will be used when storing large blobs.
  start: 0, // Relative offset to start within the blob
  end: blob.length - 1, // End offset within the blob (inclusive)
  length: blob.length, // Number of bytes to read.
  core // A custom core to write (overrides the default core)
}
```

#### `const content = await blobs.get(id, opts)`

Return a complete blob as a `Buffer`.

`id` is the value returned by `put`

Options can include:

```js
{
  core, // A custom core to read from (overrides the default core)
  wait: true, // Wait for block to be downloaded
  timeout: 0 // Wait at max some milliseconds (0 means no timeout)
}
```

#### `await blobs.clear(id, opts)`

Remove a blob from the core.

`opts` are the same as `Hypercore.clear` method.

#### `const stream = blobs.createReadStream(id, opts)`

Create a Readable stream that will yield the `id` blob.

Options match the `get` options.

#### `const stream = blobs.createWriteStream(opts)`

Create a Writable stream that will save a blob.

The corresponding ID will be set on the stream at `stream.id`.

## License

Apache-2.0

---
_Source: https://npm.io/package/hyperblobs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._