# @bytecask/core

> Browser-native content-addressed binary blob store — BLAKE3 addressing, tiered storage adapters (OPFS via worker, IndexedDB, memory), dedup, refcount, GC.

Latest version **2026.7.5** (published 2026-07-16) · AGPL-3.0-only license · 0 weekly downloads

## Install

```sh
npm install @bytecask/core
pnpm add @bytecask/core
yarn add @bytecask/core
bun add @bytecask/core
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2026.7.5 |
| Published | 2026-07-16 |
| First published | 2026-07-15 |
| Weekly downloads | 0 |
| License | AGPL-3.0-only |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 1 |
| Unpacked size | 150 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Author | Joseph Magly |
| Maintainers | roctinam |
| Keywords | bytecask, binary-data, blob-storage, blob-store, browser-storage, blake3, cas, content-addressable-storage, content-addressed-storage, deduplication, file-storage, indexeddb, offline-first, opfs, typescript, web-storage |

## Links

- npm: https://www.npmjs.com/package/@bytecask/core
- Repository: https://github.com/jmagly/bytecask
- Homepage: https://bytecask.net
- Issues: https://git.integrolabs.net/roctinam/bytecask/issues
- npm.io page: https://npm.io/package/@bytecask/core

## Dependencies (1)

- [@noble/hashes](https://npm.io/package/@noble/hashes.md) ^1.7.2

## Alternatives

- [@mce/gif](https://npm.io/package/@mce/gif.md) — 2.6K weekly downloads
- [cleanse](https://npm.io/package/cleanse.md) — 173 weekly downloads
- [str](https://npm.io/package/str.md) — 127 weekly downloads
- [naming](https://npm.io/package/naming.md) — 95 weekly downloads
- [tap-telco-api](https://npm.io/package/tap-telco-api.md) — 19 weekly downloads

## Recent versions

- 2026.7.5 (latest) — 2026-07-16
- 2026.7.4 — 2026-07-15
- 2026.7.2 — 2026-07-15

## README

<div align="center">

# @bytecask/core

**Browser-native, content-addressed blob storage.**

Store binary data in IndexedDB, OPFS, or memory behind one typed API with
BLAKE3 addressing, deduplication, lifecycle accounting, and recovery tools.

```bash
pnpm add @bytecask/core
```

[![npm](https://img.shields.io/npm/v/@bytecask/core?style=flat-square)](https://www.npmjs.com/package/@bytecask/core)
[![downloads](https://img.shields.io/npm/dm/@bytecask/core?style=flat-square)](https://www.npmjs.com/package/@bytecask/core)
[![license](https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)

[**Quick Start**](#quick-start) · [**Backends**](#storage-backends) · [**API**](#main-api) · [**Browser Support**](#browser-support) · [**Documentation**](#documentation)

</div>

---

## What It Is

`@bytecask/core` is the framework-neutral Bytecask storage engine. It accepts
`Blob`, `Uint8Array`, or streamed bytes and returns a lowercase BLAKE3 content
hash. Identical content is stored once, while lifecycle metadata determines
whether the object is live, collectible, or missing.

| It provides | It deliberately leaves to the host |
|---|---|
| Content-addressed binary storage | Records and relational data |
| IndexedDB, OPFS, and memory adapters | User authorization and synchronization |
| Deduplication, references, GC, reconciliation | Signing and publisher identity |
| Quota and integrity errors | The only copy of irreplaceable data |
| Portable `blobs/<hash>` packing | Product-specific attachment workflows |

## Highlights

- **BLAKE3 content identity:** stable hashes support deduplication and portable
  manifests.
- **IndexedDB-first persistence:** broad cross-browser storage without a
  database dependency.
- **Optional OPFS streaming:** worker-backed large-file I/O is loaded only when
  selected.
- **Explicit lifecycle models:** use refcounts or reconcile against a canonical
  host manifest.
- **Failure-aware writes:** partial objects are removed after quota, metadata,
  integrity, or streaming failures.
- **ESM and TypeScript:** typed public exports with no top-level browser-global
  access, so importing during SSR is safe.

## Installation

Install the core package for IndexedDB, memory, and automatic backend selection:

```bash
pnpm add @bytecask/core
```

Add the worker package only when using OPFS:

```bash
pnpm add @bytecask/core @bytecask/worker
```

## Quick Start

```ts
import { createBlobStore } from '@bytecask/core'

const store = await createBlobStore({ backend: 'idb' })
const hash = await store.put(new Blob(['hello, Bytecask']))

console.log(hash) // lowercase BLAKE3 hex

const blob = await store.getBlob(hash)
const bytes = await store.get(hash)

await store.close()
```

Automatic selection tries IndexedDB, then OPFS, then memory and exposes the
result as `store.backend`. Force a persistent backend for archives that must
never degrade to session memory.

## Storage Backends

| Backend | Selection | Persistence | Best fit |
|---|---|---|---|
| IndexedDB | Default persistent tier | Browser-managed, evictable | General files and attachments |
| OPFS | Explicit or automatic fallback | Browser-managed, evictable | Streaming and large binary objects |
| Memory | Explicit or final fallback | Session only | Tests, previews, and ephemeral data |

```ts
const store = await createBlobStore({
  backend: 'idb',
  idb: { databaseName: 'archive-blobs' },
  metadata: { databaseName: 'archive-metadata' },
  verifyOnRead: true,
})

const persistenceGranted = await store.requestPersistence()
const report = await store.reconcile(liveAttachmentHashes)
```

A forced backend rejects when unavailable. It never silently changes the
requested durability model.

## Lifecycle Models

Choose one authority per store:

1. **Store-managed:** `put()` creates a reference; balance ownership with
   `ref()` and `unref()`, then collect with `gc()`.
2. **Host-managed:** retain hashes in a canonical manifest and call
   `reconcile(liveHashes)` to repair metadata and identify missing or
   unreferenced bytes.

Do not maintain independent refcount systems for the same archive.

## Main API

| Export | Purpose |
|---|---|
| `createBlobStore(options)` | Select or force a storage backend |
| `put`, `get`, `getBlob`, `has`, `delete` | Store and retrieve bytes by hash |
| `ref`, `unref`, `gc` | Store-managed lifecycle accounting |
| `reconcile(liveHashes)` | Repair state from a host-authoritative manifest |
| `subscribe(listener)` | Observe local byte-store mutation outcomes |
| `estimate`, `requestPersistence` | Observe browser storage and persistence |
| `packBlobs`, `unpackBlobs` | Move portable `blobs/<hash>` entries |
| `BytecaskError`, `QuotaError`, `IntegrityError` | Handle typed storage failures |

```ts
const unsubscribe = store.subscribe((event) => {
  if (event.type === 'put') {
    console.log(event.hash, event.refcount)
  }
})
```

The change feed is store-level and local to the `BlobStore` instance. It emits
Bytecask byte/lifecycle outcomes, not host record semantics or cross-tab sync
messages.

## Browser Support

- IndexedDB behavior is tested in Chromium, Firefox, and Playwright WebKit.
- OPFS worker behavior is tested in Chromium and Firefox.
- Memory storage works in browser and JavaScript test environments.
- The package is ESM-only and targets modern browsers.

Playwright WebKit is an engine proxy, not Apple's shipping Safari binary.
Treat browser storage as a rebuildable local copy because persistence requests
reduce eviction risk but cannot eliminate it.

## Related Packages

| Package | Purpose |
|---|---|
| [`@bytecask/worker`](https://www.npmjs.com/package/@bytecask/worker) | Optional OPFS worker and streaming I/O |
| [`@bytecask/react`](https://www.npmjs.com/package/@bytecask/react) | Optional React provider and hooks |

## Documentation

- [Project README](https://github.com/jmagly/bytecask#readme)
- [Host contract](https://github.com/jmagly/bytecask/blob/main/docs/host-contract.md)
- [Coverage and browser evidence](https://github.com/jmagly/bytecask/blob/main/docs/test-coverage.md)
- [Architecture](https://github.com/jmagly/bytecask/blob/main/.aiwg/architecture/ARCHITECTURE.md)
- [Changelog](https://github.com/jmagly/bytecask/blob/main/packages/core/CHANGELOG.md)

## Security

Bytecask verifies content identity, not publisher identity. Verify signed
containers or shards before hydrating untrusted bytes. Report vulnerabilities
through the project's [security policy](https://github.com/jmagly/bytecask/blob/main/SECURITY.md),
not a public issue.

## License

AGPL-3.0-only. See [LICENSE](LICENSE).

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