@bytecask/worker

Worker-backed OPFS streaming for Bytecask.

Keep synchronous Origin Private File System access handles off the main thread behind an asynchronous, typed Comlink boundary.

pnpm add @bytecask/core @bytecask/worker

Quick Start · Spawn Strategies · API · Browser Support · Documentation

What It Is

@bytecask/worker is the optional OPFS runtime used by @bytecask/core. It owns sync access handles inside a dedicated Web Worker, supports positioned and streamed writes, and exposes an asynchronous main-thread API.

Most applications should install this package beside core and select the OPFS backend rather than importing worker functions directly.

Highlights

• Main-thread isolation: synchronous OPFS handles stay inside a Web Worker.
• Streaming writes: chunks share one held access handle and preserve write order without buffering the complete object.
• Atomic abort: failed streams close the handle and remove partial files.
• Flexible deployment: use an inlined worker, explicit URL, or custom factory to match bundler and CSP requirements.
• Explicit teardown: Comlink proxies, workers, and generated blob URLs are released deterministically.
• Lazy core boundary: worker code is absent from the default IndexedDB and memory paths.

Installation

pnpm add @bytecask/core @bytecask/worker

Quick Start

Select OPFS through the core package:

import { createBlobStore } from '@bytecask/core'

const store = await createBlobStore({
  backend: 'opfs',
  opfs: { rootDir: 'archive-blobs' },
  metadata: { databaseName: 'archive-metadata' },
})

const hash = await store.put(largeBlob)
const bytes = await store.get(hash)

await store.close()

A forced OPFS backend rejects when OPFS, Web Workers, or sync access handles are unavailable. It never silently falls back to a different backend.

Worker Spawn Strategies

The runtime selects the first configured strategy:

1. workerFactory for host-controlled worker construction.
2. workerUrl for a separately deployed worker asset.
3. The default inlined worker for zero-asset setup.

const store = await createBlobStore({
  backend: 'opfs',
  opfs: {
    rootDir: 'archive-blobs',
    workerFactory: () => new Worker(
      new URL('./bytecask-worker.js', import.meta.url),
      { type: 'module' },
    ),
  },
})

Use an explicit factory or URL when a Content Security Policy disallows blob worker URLs.

Direct API

Advanced integrations can use the worker client directly:

import { createOpfsIo } from '@bytecask/worker'

const io = await createOpfsIo({ rootDir: 'archive-blobs' })

await io.write(hash, bytes)
const restored = await io.read(hash)
const present = await io.exists(hash)

await io.dispose()

| Export | Purpose | |---|---| | createOpfsIo(options) | Spawn, probe, and wrap the OPFS worker | | spawnBlobWorker(options) | Construct a worker without the I/O wrapper | | OpfsIo | Typed read, write, stream, list, size, and disposal surface | | BlobWorkerApi | Worker protocol type for advanced hosts |

Call dispose() when using the direct API. Core-managed stores dispose their worker when store.close() runs.

Browser Support

• OPFS worker conformance runs in Chromium and Firefox.
• WebKit currently lacks the required OPFS surface in the tested environment.
• The runtime requires Worker, Blob, URL.createObjectURL, and navigator.storage.getDirectory() for its default path.
• The package is ESM-only and intended for modern browser applications.

Related Packages

| Package | Purpose | |---|---| | @bytecask/core | Storage facade that loads this worker on demand | | @bytecask/react | Optional React provider and hooks |

Documentation

• Project README
• Host contract
• Coverage and browser evidence
• Worker boundary ADR
• Changelog

Security

The worker validates storage behavior, not shard or publisher signatures. Verify untrusted containers before writing their content. Report vulnerabilities through the project's security policy.

License

AGPL-3.0-only. See LICENSE.