@bytecask/core

pnpm add @bytecask/core

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.

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:

pnpm add @bytecask/core

Add the worker package only when using OPFS:

pnpm add @bytecask/core @bytecask/worker

Quick Start

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

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

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

Documentation

• Project README
• Host contract
• Coverage and browser evidence
• Architecture
• Changelog

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, not a public issue.

License

AGPL-3.0-only. See LICENSE.