README.md

Cache Worker

Browser storage APIs for LVCE workers. @lvce-editor/cache-worker provides Cache Storage, IndexedDB, and Origin Private File System (OPFS) operations through a worker RPC command map.

Commands

Command	Arguments	Result
Cache.getCacheStorageJsonItem	(request, cacheName = 'lvce-cache')	{ value } containing parsed JSON, or null when missing; malformed JSON rejects
Cache.getCacheStorageItem	(request, cacheName = 'lvce-cache')	Structured-cloneable { body: ArrayBuffer, headers: [string, string][], status, statusText } or null when missing
Cache.setCacheStorageJsonItem	(request, value, cacheName = 'lvce-cache')	Existing cache write result; serializes JSON and reports unsupported values as write failures
Cache.setCacheStorageItem	(request, value, cacheName = 'lvce-cache')	undefined; stores a body accepted by the browser Response constructor
Cache.removeCacheStorageItem	(request, cacheName = 'lvce-cache')	boolean indicating whether an item was removed
IndexedDb.addIndexedDbFileHandle	(key, handle, databaseName = 'lvce-cache-worker')	undefined after the write transaction commits
IndexedDb.getIndexedDbFileHandle	(key, databaseName = 'lvce-cache-worker')	Stored handle or null when missing through worker RPC
IndexedDb.removeIndexedDbFileHandle	(key, databaseName = 'lvce-cache-worker')	undefined after the delete transaction commits; deleting a missing key is a no-op
Opfs.readFile	(name)	UTF-8 text; rejects when the file does not exist
Opfs.writeFile	(name, content)	undefined after the writable is closed
Opfs.removeFile	(name)	undefined; rejects when the file does not exist

Missing browser APIs reject with an error that names the unavailable capability. Browser storage quota, security, invalid key, structured-clone, and transaction errors are propagated to the caller. File handles must be structured-cloneable by the browser and writable in the current origin. OPFS filenames are single path components; directory traversal is not supported.

Resolve the worker entry URL with getCacheWorkerUrl and connect it using @lvce-editor/rpc's ModuleWorkerRpcParent:

import { ModuleWorkerRpcParent } from '@lvce-editor/rpc'
import { getCacheWorkerUrl } from '@lvce-editor/cache-worker'

const rpc = await ModuleWorkerRpcParent.create({
  commandMap: {},
  url: getCacheWorkerUrl().href,
})

The worker registers the commands in src/parts/CommandMap/CommandMap.js. Response values are converted to structured-cloneable data before crossing RPC; callers can create a new Response from the returned body and metadata.

Development

This repository uses npm workspaces and a root package-lock.json.

Run npm run dev to build the worker assets and start the development test server.

The cross-browser suite checks Cache Storage and OPFS through worker RPC in Chromium, Firefox, and WebKit. IndexedDB file-handle restoration is covered in Firefox; Chromium checks general structured-clone persistence. WebKit runs in CI as advisory coverage because some e2e tests may not pass there yet.

npm ci
npm test
npm run build
npm run e2e -- --browser=webkit

The browser suite runs against Chromium, Firefox, and WebKit. Install them with npx playwright install --with-deps chromium firefox webkit.

Synchronous cache clients

Opfs.getCacheFileHandle(namespace, name) returns a structured-cloneable FileSystemFileHandle beneath lvce-extension-caches/<namespace>/<name>. Both components must contain 1–80 lowercase ASCII letters, digits or hyphens, starting with a letter or digit. Reopening the same pair preserves its contents; separate namespaces do not share files. This directory avoids the root-level files used by synchronous RPC.

A dedicated worker can call createSyncAccessHandle() on the returned handle. The client owns that handle and must close it, including on failure and disposal. Use the default exclusive lock: concurrent clients that cannot acquire it should fall back to uncached reads. Cache-worker itself opens no access handles. The client remains responsible for size limits, its on-disk format, corruption validation, invalidation and crash recovery. This command does not authenticate extensions or isolate mutually untrusted code within an origin.