Origin Private File System (OPFS)¶

/** Detects OPFS capabilities. Run it in the context that will do the I/O. */
export async function detectOpfs() {
  const support = { root: false, writable: false, syncHandles: false, move: false, remove: false };
  if (typeof navigator.storage?.getDirectory !== "function") return support;
  try {
    await navigator.storage.getDirectory(); // can reject: SecurityError in restricted contexts
    support.root = true;
  } catch {
    return support;
  }
  if (typeof FileSystemFileHandle !== "undefined") {
    const proto = FileSystemFileHandle.prototype;
    support.writable = "createWritable" in proto; // Safari 26+, Chrome 86+, Firefox 111+
    support.syncHandles = "createSyncAccessHandle" in proto; // true only in dedicated workers
    support.move = "move" in proto; // non-standard; Chromium supports files only
  }
  support.remove = typeof FileSystemHandle !== "undefined" && "remove" in FileSystemHandle.prototype; // Chromium only
  return support;
}

/** Splits "a/b/c.txt" into ["a", "b", "c.txt"], rejecting empty, "." and ".." parts. */
export function splitPath(path) {
  const parts = path.split("/").filter((part) => part !== "");
  if (parts.length === 0 || parts.some((part) => part === "." || part === "..")) {
    throw new TypeError(`Invalid OPFS path: "${path}"`);
  }
  return parts;
}

/** Returns the directory handle for all but the last path component. */
export async function parentDirectory(path, { create = false } = {}) {
  let dir = await navigator.storage.getDirectory();
  for (const part of splitPath(path).slice(0, -1)) {
    dir = await dir.getDirectoryHandle(part, { create });
  }
  return dir;
}

export async function fileHandle(path, { create = false } = {}) {
  const dir = await parentDirectory(path, { create });
  return dir.getFileHandle(splitPath(path).at(-1), { create });
}

/** Deletes a file or directory tree. Resolves false if it didn't exist. */
export async function removePath(path) {
  const dir = await parentDirectory(path);
  try {
    await dir.removeEntry(splitPath(path).at(-1), { recursive: true });
    return true;
  } catch (error) {
    if (error.name === "NotFoundError") return false;
    throw error;
  }
}

/** Recursively yields { path, handle } for every file below `dir`. */
export async function* walk(dir, prefix = "") {
  for await (const [name, handle] of dir.entries()) {
    const path = `${prefix}/${name}`;
    if (handle.kind === "directory") yield* walk(handle, path);
    else yield { path, handle };
  }
}

import { fileHandle } from "./opfs-paths.js";

/** Reads bytes [start, end) without loading the whole file. Works in windows and all workers. */
export async function readRange(path, start, end) {
  const file = await (await fileHandle(path)).getFile();
  return new Uint8Array(await file.slice(start, end).arrayBuffer());
}

/** Streams a file, for example into a Response or a decompression stream. */
export async function streamFile(path) {
  const file = await (await fileHandle(path)).getFile();
  return file.stream();
}

import { fileHandle } from "./opfs-paths.js";

/** Replaces a file's contents atomically. Works in windows and all workers. */
export async function saveFile(path, data) {
  const handle = await fileHandle(path, { create: true });
  const writable = await handle.createWritable(); // empty temporary file
  try {
    await writable.write(data);
    await writable.close(); // swaps the new contents in; readers never see a partial file
  } catch (error) {
    await writable.abort().catch(() => {}); // discard the temporary file
    throw error;
  }
}

/** Streams a download to disk without buffering it in memory. */
export async function downloadToFile(path, url, { signal } = {}) {
  const response = await fetch(url, { signal });
  if (!response.ok || !response.body) throw new Error(`HTTP ${response.status} for ${url}`);
  const handle = await fileHandle(path, { create: true });
  const writable = await handle.createWritable();
  // pipeTo() closes the writable on success and aborts it on error or cancellation,
  // so a failed download leaves the previous contents of the file intact.
  await response.body.pipeTo(writable, { signal });
}

/** Patches a fixed-size header in place, keeping the rest of the file. */
export async function patchHeader(path, headerBytes) {
  const handle = await fileHandle(path);
  const writable = await handle.createWritable({ keepExistingData: true }); // full copy first
  await writable.write({ type: "write", position: 0, data: headerBytes });
  await writable.close();
}

// Dedicated worker: new Worker(new URL("./log-worker.js", import.meta.url), { type: "module" })
const encoder = new TextEncoder();
const decoder = new TextDecoder();
const HEADER_BYTES = 4; // uint32 little-endian payload length

let handle; // FileSystemSyncAccessHandle, held for the worker's lifetime
let size = 0; // logical end of the log (valid records only)

async function open() {
  const root = await navigator.storage.getDirectory();
  const file = await root.getFileHandle("events.log", { create: true });
  handle = await file.createSyncAccessHandle(); // rejects with NoModificationAllowedError if another worker holds it
  size = recover();
}

/** Scans the log and truncates a partially written record left by a crash. */
function recover() {
  const fileSize = handle.getSize();
  const header = new DataView(new ArrayBuffer(HEADER_BYTES));
  let at = 0;
  while (at + HEADER_BYTES <= fileSize) {
    if (handle.read(header, { at }) !== HEADER_BYTES) break;
    const length = header.getUint32(0, true);
    if (at + HEADER_BYTES + length > fileSize) break; // torn record
    at += HEADER_BYTES + length;
  }
  if (at !== fileSize) {
    handle.truncate(at);
    handle.flush();
  }
  return at;
}

function append(record) {
  const payload = encoder.encode(JSON.stringify(record));
  const frame = new Uint8Array(HEADER_BYTES + payload.byteLength);
  new DataView(frame.buffer).setUint32(0, payload.byteLength, true);
  frame.set(payload, HEADER_BYTES);

  let written = 0;
  while (written < frame.byteLength) {
    const n = handle.write(frame.subarray(written), { at: size + written });
    if (n === 0) {
      handle.truncate(size); // roll back the partial frame
      throw new Error("Write made no progress (disk full or I/O error)");
    }
    written += n;
  }
  size += frame.byteLength;
}

function* readAll() {
  const header = new DataView(new ArrayBuffer(HEADER_BYTES));
  let at = 0;
  while (at < size) {
    handle.read(header, { at });
    const length = header.getUint32(0, true);
    const payload = new Uint8Array(length);
    handle.read(payload, { at: at + HEADER_BYTES });
    yield JSON.parse(decoder.decode(payload));
    at += HEADER_BYTES + length;
  }
}

const ready = open();

self.onmessage = async ({ data }) => {
  try {
    await ready;
    if (data.type === "append") {
      for (const record of data.records) append(record);
      handle.flush(); // one flush per batch, not per record
      self.postMessage({ id: data.id, ok: true, size });
    } else if (data.type === "read") {
      self.postMessage({ id: data.id, ok: true, records: [...readAll()] });
    } else if (data.type === "close") {
      handle.flush();
      handle.close(); // release the exclusive lock for other tabs
      self.postMessage({ id: data.id, ok: true });
    }
  } catch (error) {
    self.postMessage({ id: data.id, ok: false, error: { name: error.name, message: error.message } });
  }
};

/**
 * Runs fn while holding an origin-wide lock for `path`. Cooperating tabs and workers
 * queue instead of failing with NoModificationAllowedError.
 */
export function withFileLock(path, fn) {
  return navigator.locks.request(`opfs:${path}`, fn);
}

/**
 * Resolves once this context owns `name`, and keeps it until the context ends.
 * `onWait` is called if another tab owns it first.
 */
export function becomeOwner(name, { onWait } = {}) {
  return new Promise((resolve) => {
    const hold = () => {
      resolve();
      return new Promise(() => {}); // never settles: the lock lives as long as this context
    };
    navigator.locks.request(name, { ifAvailable: true }, (lock) => {
      if (lock) return hold();
      onWait?.();
      navigator.locks.request(name, hold); // queue behind the current owner
      return undefined;
    });
  });
}

// Module worker: new Worker(new URL("./db-worker.js", import.meta.url), { type: "module" })
import sqlite3InitModule from "@sqlite.org/sqlite-wasm";

const DB_PATH = "/app.sqlite3"; // opfs-sahpool paths must be absolute

// Migration i upgrades user_version i to i + 1. Never edit a shipped migration; append.
const MIGRATIONS = [
  `CREATE TABLE notes (
     id TEXT PRIMARY KEY,
     title TEXT NOT NULL,
     body TEXT NOT NULL DEFAULT '',
     updated_at INTEGER NOT NULL
   );
   CREATE INDEX notes_updated_at ON notes(updated_at);`,
  `ALTER TABLE notes ADD COLUMN folder_id TEXT;
   CREATE INDEX notes_folder_updated ON notes(folder_id, updated_at);`,
];

let db;
let pool;

const ready = (async () => {
  // opfs-sahpool can be installed by only one context per pool directory at a time.
  await becomeOwner("sqlite:opfs-sahpool", () => self.postMessage({ type: "status", status: "waiting-for-other-tab" }));
  const sqlite3 = await sqlite3InitModule();
  pool = await sqlite3.installOpfsSAHPoolVfs(); // default name "opfs-sahpool", directory ".opfs-sahpool"
  await pool.reserveMinimumCapacity(6); // db + journal + temp files, with headroom
  db = new pool.OpfsSAHPoolDb(DB_PATH);
  db.exec("PRAGMA foreign_keys = ON;");
  migrate();
  self.postMessage({ type: "status", status: "ready", sqlite: sqlite3.version.libVersion });
})();

function becomeOwner(name, onWait) {
  return new Promise((resolve) => {
    const hold = () => {
      resolve();
      return new Promise(() => {}); // released automatically when this worker terminates
    };
    navigator.locks.request(name, { ifAvailable: true }, (lock) => {
      if (lock) return hold();
      onWait();
      navigator.locks.request(name, hold);
      return undefined;
    });
  });
}

function migrate() {
  const current = db.selectValue("PRAGMA user_version");
  if (current > MIGRATIONS.length) {
    throw new Error(`Database schema v${current} is newer than this code (v${MIGRATIONS.length}). Reload.`);
  }
  for (let version = current; version < MIGRATIONS.length; version++) {
    db.transaction((tx) => {
      tx.exec(MIGRATIONS[version]);
      tx.exec(`PRAGMA user_version = ${version + 1}`); // committed atomically with the migration
    });
  }
}

const handlers = {
  query: ({ sql, bind }) => db.selectObjects(sql, bind),
  run: ({ sql, bind }) => {
    db.exec({ sql, bind });
    return { changes: db.changes() };
  },
  batch: ({ statements }) =>
    db.transaction(() => {
      for (const { sql, bind } of statements) db.exec({ sql, bind });
      return statements.length;
    }),
  export: () => pool.exportFile(DB_PATH), // Uint8Array snapshot for backups
};

self.onmessage = async ({ data: { id, type, payload } }) => {
  try {
    await ready;
    const handler = handlers[type];
    if (!handler) throw new TypeError(`Unknown request type "${type}"`);
    const result = handler(payload ?? {});
    const transfer = result instanceof Uint8Array ? [result.buffer] : [];
    self.postMessage({ id, ok: true, result }, transfer);
  } catch (error) {
    self.postMessage({ id, ok: false, error: { name: error.name, message: error.message } });
  }
};

const worker = new Worker(new URL("./db-worker.js", import.meta.url), { type: "module" });
const pending = new Map();
let nextId = 1;

worker.onmessage = ({ data }) => {
  if (data.type === "status") {
    dispatchEvent(new CustomEvent("db-status", { detail: data })); // e.g. show "open in another tab"
    return;
  }
  const request = pending.get(data.id);
  if (!request) return;
  pending.delete(data.id);
  if (data.ok) request.resolve(data.result);
  else request.reject(Object.assign(new Error(data.error.message), { name: data.error.name }));
};

worker.onerror = (event) => {
  // The worker failed to load or threw during initialization: fail everything in flight.
  for (const { reject } of pending.values()) reject(new Error(event.message || "Database worker failed"));
  pending.clear();
};

function call(type, payload) {
  const id = nextId++;
  return new Promise((resolve, reject) => {
    pending.set(id, { resolve, reject });
    worker.postMessage({ id, type, payload });
  });
}

export const query = (sql, bind) => call("query", { sql, bind });
export const run = (sql, bind) => call("run", { sql, bind });
export const batch = (statements) => call("batch", { statements });
export const exportDatabase = async () =>
  new Blob([await call("export")], { type: "application/vnd.sqlite3" });

// Usage:
// await run("INSERT INTO notes (id, title, updated_at) VALUES (?, ?, ?)", [crypto.randomUUID(), "Hi", Date.now()]);
// const rows = await query("SELECT * FROM notes WHERE folder_id IS ? ORDER BY updated_at DESC LIMIT 50", [null]);

/** Best-effort check before a large download. Never a guarantee: always handle QuotaExceededError too. */
export async function prepareForLargeWrite(expectedBytes) {
  const persisted = (await navigator.storage.persisted?.()) || (await navigator.storage.persist?.());
  const { usage = 0, quota = 0 } = await navigator.storage.estimate();
  return {
    persisted: Boolean(persisted),
    likelyFits: quota - usage > expectedBytes * 1.1, // leave headroom for metadata and temp files
  };
}

// Dedicated module worker that owns every write under /media in OPFS.
// Created by media-store.js: new Worker(new URL("./media-worker.js", import.meta.url), { type: "module" })
const FLUSH_EVERY = 8 * 1024 * 1024; // bytes between flushes: bounds what a crash can cost
const PROGRESS_EVERY_MS = 250;
const encoder = new TextEncoder();
const jobs = new Map(); // request id -> { key, controller } for downloads in this worker

// Platform errors mapped to stable reasons the page can switch on.
const REASONS = {
  QuotaExceededError: "quota",
  NoModificationAllowedError: "locked", // a handle held by code outside our Web Locks
  AbortError: "aborted",
  TypeError: "network", // fetch() and stream reads reject with TypeError on network failure
  SecurityError: "unavailable", // no storage access in this context
};

const fail = (reason, message) => Object.assign(new Error(message), { reason });

async function mediaDir() {
  const root = await navigator.storage.getDirectory();
  return root.getDirectoryHandle("media", { create: true });
}

/** SHA-256 of the URL in hex: fixed length and always a valid file name. */
async function keyFor(url) {
  const digest = await crypto.subtle.digest("SHA-256", encoder.encode(url));
  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
}

/** write() may transfer fewer bytes than requested, so loop until everything is written. */
function writeAll(access, bytes, at) {
  for (let done = 0; done < bytes.byteLength; ) {
    const n = access.write(bytes.subarray(done), { at: at + done });
    if (n === 0) throw new Error("Write made no progress");
    done += n;
  }
}

/** Rewrites the sidecar in place. A torn write fails JSON.parse() and reads as "not stored". */
function writeMeta(access, meta) {
  const bytes = encoder.encode(JSON.stringify(meta));
  access.truncate(0);
  writeAll(access, bytes, 0);
  access.flush();
}

async function readMeta(dir, key) {
  try {
    const file = await (await dir.getFileHandle(`${key}.json`)).getFile();
    return JSON.parse(await file.text());
  } catch {
    return null; // missing, torn or being rewritten
  }
}

/** Deletes the sidecar first, so the service worker stops serving before the bytes go. */
async function removeFiles(dir, key) {
  let removed = false;
  for (const name of [`${key}.json`, `${key}.bin`]) {
    try {
      await dir.removeEntry(name);
      removed = true;
    } catch (error) {
      if (error.name !== "NotFoundError") throw error; // e.g. NoModificationAllowedError: open elsewhere
    }
  }
  return removed;
}

/** Best-effort pre-flight. Estimates are coarse, so write errors are handled as well. */
async function checkQuota(bytesNeeded) {
  if (bytesNeeded === null || typeof navigator.storage.estimate !== "function") return; // unknown, or Safari < 17
  const { usage = 0, quota = Infinity } = await navigator.storage.estimate();
  if (quota - usage < bytesNeeded * 1.1) {
    throw fail("quota", `Needs ${bytesNeeded} bytes, about ${Math.max(quota - usage, 0)} available`);
  }
}

/** Total size from Content-Range (206) or Content-Length (200), or null when unknown. */
function expectedSize(response, offset) {
  if (response.status === 206) {
    const match = /^bytes (\d+)-\d+\/(\d+|\*)$/.exec(response.headers.get("Content-Range") ?? "");
    if (!match || Number(match[1]) !== offset) throw fail("network", "Unexpected Content-Range");
    return match[2] === "*" ? null : Number(match[2]);
  }
  const length = response.headers.get("Content-Length");
  return length === null ? null : Number(length);
}

async function download({ url, type }, id) {
  const controller = new AbortController();
  const job = { key: null, controller };
  jobs.set(id, job); // before the first await, so an abort message that follows isn't lost
  try {
    job.key = await keyFor(url);
    // One download per item across all tabs: another tab's worker queues here instead of
    // failing with NoModificationAllowedError in createSyncAccessHandle().
    return await navigator.locks.request(`media:${job.key}`, { signal: controller.signal }, () =>
      downloadLocked(url, type, job.key, id, controller.signal),
    );
  } finally {
    jobs.delete(id);
  }
}

async function downloadLocked(url, type, key, id, signal) {
  const dir = await mediaDir();
  const previous = await readMeta(dir, key);
  if (previous?.complete) return { key, ...previous }; // stored earlier, possibly by another tab

  const data = await (await dir.getFileHandle(`${key}.bin`, { create: true })).createSyncAccessHandle();
  let metaAccess = null;
  let discard = false;
  try {
    metaAccess = await (await dir.getFileHandle(`${key}.json`, { create: true })).createSyncAccessHandle();
    // Resume only from bytes that were flushed and recorded before the interruption.
    let offset = previous?.url === url ? Math.min(previous.durable ?? 0, data.getSize()) : 0;
    const headers = {};
    if (offset) {
      headers.Range = `bytes=${offset}-`;
      // Only strong validators are allowed in If-Range. A changed file then comes back as a full 200.
      if (previous.etag && !previous.etag.startsWith("W/")) headers["If-Range"] = previous.etag;
    }
    let response = await fetch(url, { signal, headers });
    // 416: the flushed prefix is already the whole file, or the file shrank. A 206 without a readable
    // Content-Range (cross-origin, not exposed) can't be verified. Either way, start over.
    if (offset && (response.status === 416 || (response.status === 206 && !response.headers.has("Content-Range")))) {
      await response.body?.cancel();
      offset = 0;
      response = await fetch(url, { signal });
    }
    if (!response.ok || !response.body) throw fail("network", `HTTP ${response.status} for ${url}`);
    if (response.status !== 206) offset = 0; // a full response: Range was ignored or If-Range failed
    const size = expectedSize(response, offset);
    await checkQuota(size === null ? null : size - offset);

    const meta = {
      url,
      type: type || response.headers.get("Content-Type") || "application/octet-stream",
      etag: response.headers.get("ETag"),
      size,
      durable: offset,
      complete: false,
    };
    data.truncate(offset); // drop bytes past the resume point: they may never have reached the disk
    writeMeta(metaAccess, meta);

    const reader = response.body.getReader();
    let lastProgress = 0;
    for (;;) {
      const { done, value } = await reader.read(); // rejects with AbortError when aborted
      if (done) break;
      writeAll(data, value, offset); // throws QuotaExceededError when the bucket is full
      offset += value.byteLength;
      if (offset - meta.durable >= FLUSH_EVERY) {
        data.flush();
        meta.durable = offset; // recorded only after the flush
        writeMeta(metaAccess, meta);
      }
      if (performance.now() - lastProgress >= PROGRESS_EVERY_MS) {
        lastProgress = performance.now();
        self.postMessage({ id, type: "progress", received: offset, total: size });
      }
    }
    if (size !== null && offset !== size) throw fail("network", `Body ended at ${offset} of ${size} bytes`);

    data.flush();
    Object.assign(meta, { size: offset, durable: offset, complete: true, savedAt: Date.now() });
    writeMeta(metaAccess, meta); // the commit: from now on the service worker serves the file
    return { key, ...meta };
  } catch (error) {
    // Out of space: a partial file only adds to the pressure. Other failures keep it for resume.
    discard = error.name === "QuotaExceededError" || error.reason === "quota";
    throw error;
  } finally {
    metaAccess?.close();
    data.close(); // release the exclusive locks
    if (discard) await removeFiles(dir, key).catch(() => {});
  }
}

async function remove({ url }) {
  const key = await keyFor(url);
  for (const job of jobs.values()) if (job.key === key) job.controller.abort(); // stop our own download
  // Waits for a download of the same item in another tab to finish or fail.
  return navigator.locks.request(`media:${key}`, async () => removeFiles(await mediaDir(), key));
}

async function get({ url }) {
  const key = await keyFor(url);
  const meta = await readMeta(await mediaDir(), key);
  return meta ? { key, ...meta } : null;
}

async function list() {
  const dir = await mediaDir();
  const items = [];
  for await (const [name, handle] of dir.entries()) {
    if (handle.kind !== "file" || !name.endsWith(".json")) continue;
    const key = name.slice(0, -".json".length);
    const meta = await readMeta(dir, key);
    if (meta?.complete) items.push({ key, ...meta });
  }
  return items;
}

const handlers = { download, remove, get, list };

self.onmessage = async ({ data: { id, type, payload = {} } }) => {
  if (type === "abort") {
    jobs.get(payload.id)?.controller.abort(); // the download then rejects with reason "aborted"
    return;
  }
  try {
    if (!Object.hasOwn(handlers, type)) throw fail("failed", `Unknown request type "${type}"`);
    self.postMessage({ id, ok: true, result: await handlers[type](payload, id) });
  } catch (error) {
    const reason = error.reason ?? REASONS[error.name] ?? "failed";
    self.postMessage({ id, ok: false, error: { name: error.name, message: error.message, reason } });
  }
};