hyperdb-wasm 0.0.26792-dev.wasm.g72cc44c1 → 0.0.26862-dev.wasm.g42f1012b

package/dist/browser_worker.js

@@ -1,7 +1,12 @@
 "use strict";
 (() => {
   // src/wasm_bindings.ts
-  var resultStates = ["ok", "pending", "chunk", "done", "error", "busy"];
+  function completionFor(cleanups) {
+    const pending = cleanups.filter((cleanup) => cleanup !== void 0);
+    return pending.length === 0 ? void 0 : Promise.all(pending).then(() => void 0);
+  }
+  var resultStates = ["ok", "pending", "chunk", "done", "error", "busy", "structuredError"];
+  var structuredErrorMagic = new Uint8Array([72, 68, 66, 69]);
   function safeInteger(value, name) {
     const number = typeof value === "bigint" && value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : value;
     if (typeof number !== "number" || !Number.isSafeInteger(number) || number < 0) throw new Error(`${name} must be a nonnegative safe integer`);
@@ -11,6 +16,33 @@
     if (!value) throw new Error(`${name} must not be empty`);
     if (value.includes("\0")) throw new Error(`${name} must not contain NUL`);
   }
+  function decodeStructuredError(payload) {
+    if (!structuredErrorMagic.every((byte, index) => payload[index] === byte)) throw new Error("structured error has invalid magic");
+    const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+    if (payload.byteLength < 8 || view.getUint32(4, true) !== 1) throw new Error("unsupported structured error version");
+    let offset = 8;
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    const readField = () => {
+      if (offset + 4 > payload.byteLength) throw new Error("truncated structured error field");
+      const length = view.getUint32(offset, true);
+      offset += 4;
+      if (length > payload.byteLength - offset) throw new Error("truncated structured error field");
+      const value = decoder.decode(payload.subarray(offset, offset + length));
+      offset += length;
+      return value;
+    };
+    const sqlState = readField();
+    const errorSource = readField();
+    const message = readField();
+    const detail = readField();
+    const hint = readField();
+    if (offset !== payload.byteLength) throw new Error("structured error has trailing bytes");
+    if (!/^[0-9A-Z]{5}$/.test(sqlState)) throw new Error("structured error has invalid SQLSTATE");
+    if (errorSource !== "User" && errorSource !== "System" && errorSource !== "OverloadRejection") {
+      throw new Error("structured error has invalid source");
+    }
+    return { sqlState, errorSource, message, detail, hint };
+  }
   var HyperDBBindings = class {
     module;
     initialize;
@@ -22,13 +54,18 @@
     checkpointDatabase;
     dropDatabase;
     shutdown;
+    registerExternalFile;
+    registerExternalDirectory;
+    removeExternalRegistration;
     attachDatabase;
     detachDatabase;
     startQuery;
+    startQueryWithInfo;
     insertArrowIPCFromPath;
     pollQuery;
     cancelQuery;
     releaseQuery;
+    releaseQueryWithInfo;
     resultState;
     resultPayloadLength;
     free;
@@ -44,13 +81,18 @@
       this.checkpointDatabase = module.cwrap("hyperdb_wasm_checkpoint_database", "pointer", ["string"]);
       this.dropDatabase = module.cwrap("hyperdb_wasm_drop_database", "pointer", ["string"]);
       this.shutdown = module.cwrap("hyperdb_wasm_shutdown", "pointer", []);
+      this.registerExternalFile = module.cwrap("hyperdb_wasm_register_external_file", "pointer", ["string", "string", "number"]);
+      this.registerExternalDirectory = module.cwrap("hyperdb_wasm_register_external_directory", "pointer", ["string", "string", "number"]);
+      this.removeExternalRegistration = module.cwrap("hyperdb_wasm_remove_external_registration", "pointer", ["string"]);
       this.attachDatabase = module.cwrap("hyperdb_wasm_attach_database", "pointer", ["number", "string", "string"]);
       this.detachDatabase = module.cwrap("hyperdb_wasm_detach_database", "pointer", ["number", "string"]);
-      this.startQuery = module.cwrap("hyperdb_wasm_query_start", "pointer", ["number", "string"]);
+      this.startQuery = module.cwrap("hyperdb_wasm_query_start", "pointer", ["number", "string", "number"]);
+      this.startQueryWithInfo = module.cwrap("hyperdb_wasm_query_start_with_info", "pointer", ["number", "string"]);
       this.insertArrowIPCFromPath = module.cwrap("hyperdb_wasm_arrow_insert_from_path", "pointer", ["number", "string", "string", "string", "number"]);
       this.pollQuery = module.cwrap("hyperdb_wasm_query_poll", "pointer", ["number"]);
       this.cancelQuery = module.cwrap("hyperdb_wasm_query_cancel", "pointer", ["number"]);
       this.releaseQuery = module.cwrap("hyperdb_wasm_query_release", "pointer", ["number"]);
+      this.releaseQueryWithInfo = module.cwrap("hyperdb_wasm_query_release_with_info", "pointer", ["number"]);
       this.resultState = module.cwrap("hyperdb_wasm_result_state", "number", ["number"]);
       this.resultPayloadLength = module.cwrap("hyperdb_wasm_result_payload_len", "number", ["number"]);
       this.free = module.cwrap("hyperdb_wasm_free", null, ["pointer"]);
@@ -66,8 +108,92 @@
         this.module.FS.unlink(request.path);
         return { response: { id: request.id, type: "response", result: { state: "ok", payload: new Uint8Array() } }, transfer: [] };
       }
+      if (request.type === "registerExternalFile" && "path" in request) {
+        if (!this.module.externalFileBackend) {
+          return { response: { id: request.id, type: "response", result: { state: "error", error: "Host external files are supported only by the Node client" } }, transfer: [] };
+        }
+        const registration = this.module.externalFileBackend.register(request.path);
+        try {
+          const pointer2 = safeInteger(this.registerExternalFile(registration.name, registration.locator, registration.size), "result pointer");
+          const result2 = this.decodeResult(pointer2);
+          if (result2.state === "ok") {
+            const path = new TextDecoder("utf-8", { fatal: true }).decode(result2.payload);
+            try {
+              this.module.externalFileBackend.registered(path, registration.locator);
+            } catch (error) {
+              const cleanupPointer = safeInteger(this.removeExternalRegistration(path), "result pointer");
+              this.decodeResult(cleanupPointer);
+              throw error;
+            }
+          } else {
+            this.module.externalFileBackend.removed(registration.locator);
+          }
+          return { response: { id: request.id, type: "response", result: result2 }, transfer: [] };
+        } catch (error) {
+          this.module.externalFileBackend.removed(registration.locator);
+          throw error;
+        }
+      }
+      if (request.type === "registerExternalFile" && !this.module.externalFileBackendAvailable) {
+        return { response: { id: request.id, type: "response", result: { state: "error", error: "Blob external files are supported only by the browser client" } }, transfer: [] };
+      }
+      if (request.type === "registerExternalDirectory") {
+        const backend = this.module.externalDirectoryBackend;
+        if (!backend) {
+          return { response: { id: request.id, type: "response", result: { state: "error", error: "External directories are not supported by this client" } }, transfer: [] };
+        }
+        const registration = backend.register("handle" in request ? request.handle : request.path, request.mode);
+        try {
+          const pointer2 = safeInteger(this.registerExternalDirectory(registration.name, registration.locator, Number(request.mode === "readwrite")), "result pointer");
+          const result2 = this.decodeResult(pointer2);
+          if (result2.state === "ok") {
+            const path = new TextDecoder("utf-8", { fatal: true }).decode(result2.payload);
+            try {
+              backend.registered(path, registration.locator);
+            } catch (error) {
+              const cleanupPointer = safeInteger(this.removeExternalRegistration(path), "result pointer");
+              this.decodeResult(cleanupPointer);
+              throw error;
+            }
+          } else {
+            const completion = completionFor([backend.removed(registration.locator)]);
+            return { response: { id: request.id, type: "response", result: result2 }, transfer: [], ...completion && { completion } };
+          }
+          return { response: { id: request.id, type: "response", result: result2 }, transfer: [] };
+        } catch (error) {
+          void Promise.resolve(backend.removed(registration.locator)).catch(() => void 0);
+          throw error;
+        }
+      }
+      if (request.type === "removeExternalRegistration" && (this.module.externalFileBackend || this.module.externalDirectoryBackend)) {
+        validateCString(request.path, "external registration path");
+        const pointer2 = safeInteger(this.removeExternalRegistration(request.path), "result pointer");
+        const result2 = this.decodeResult(pointer2);
+        if (result2.state === "ok") {
+          const completion = completionFor([
+            this.module.externalFileBackend?.removed(request.path),
+            this.module.externalDirectoryBackend?.removed(request.path)
+          ]);
+          return { response: { id: request.id, type: "response", result: result2 }, transfer: [], ...completion && { completion } };
+        }
+        return { response: { id: request.id, type: "response", result: result2 }, transfer: [] };
+      }
+      if (request.type === "removeExternalRegistration" && !this.module.externalFileBackendAvailable) {
+        return { response: { id: request.id, type: "response", result: { state: "error", error: "External files are not supported by this client" } }, transfer: [] };
+      }
       const pointer = safeInteger(this.invoke(request), "result pointer");
       const result = this.decodeResult(pointer);
+      if (request.type === "shutdown" && result.state === "ok") {
+        const completion = completionFor([
+          this.module.externalFileBackend?.shutdown(),
+          this.module.externalDirectoryBackend?.shutdown()
+        ]);
+        return {
+          response: { id: request.id, type: "response", result },
+          transfer: [],
+          ...completion && { completion }
+        };
+      }
       const response = { id: request.id, type: "response", result };
       return { response, transfer: result.state === "chunk" ? [result.payload.buffer] : [] };
     }
@@ -103,8 +229,20 @@
           return this.detachDatabase(request.connection, request.alias);
         case "shutdown":
           return this.shutdown();
+        case "registerExternalFile":
+          if ("path" in request) throw new Error("host external file request has no backend");
+          validateCString(request.name, "external file name");
+          validateCString(request.url, "external file URL");
+          return this.registerExternalFile(request.name, request.url, safeInteger(request.size, "external file size"));
+        case "registerExternalDirectory":
+          throw new Error("external directory request has no backend");
+        case "removeExternalRegistration":
+          validateCString(request.path, "external registration path");
+          return this.removeExternalRegistration(request.path);
         case "startQuery":
-          return this.startQuery(request.connection, request.sql);
+          return this.startQuery(request.connection, request.sql, Number(request.sqlTestMode ?? false));
+        case "startQueryWithInfo":
+          return this.startQueryWithInfo(request.connection, request.sql);
         case "insertArrowIPCFromPath": {
           const path = request.internal ? request.path : this.module.resolveHyperDBPath?.(request.path) ?? request.path;
           return this.insertArrowIPCFromPath(request.connection, path, request.name, request.schema ?? "", Number(request.create));
@@ -115,6 +253,8 @@
           return this.cancelQuery(request.query);
         case "releaseQuery":
           return this.releaseQuery(request.query);
+        case "releaseQueryWithInfo":
+          return this.releaseQueryWithInfo(request.query);
       }
     }
     decodeResult(pointer) {
@@ -144,6 +284,8 @@
             return { state, error: new TextDecoder().decode(payload) };
           case "busy":
             return { state, error: new TextDecoder().decode(payload) };
+          case "structuredError":
+            return { state: "error", error: decodeStructuredError(payload) };
         }
       } finally {
         this.free(pointer);
@@ -183,6 +325,8 @@
       case "detachDatabase":
         return hasKeys(value, ["id", "type", "connection", "alias"]) && Number.isSafeInteger(value.connection) && typeof value.alias === "string";
       case "startQuery":
+        return (hasKeys(value, ["id", "type", "connection", "sql"]) || hasKeys(value, ["id", "type", "connection", "sql", "sqlTestMode"])) && Number.isSafeInteger(value.connection) && typeof value.sql === "string" && (value.sqlTestMode === void 0 || typeof value.sqlTestMode === "boolean");
+      case "startQueryWithInfo":
         return hasKeys(value, ["id", "type", "connection", "sql"]) && Number.isSafeInteger(value.connection) && typeof value.sql === "string";
       case "insertArrowIPCFromPath":
         return hasKeys(value, ["id", "type", "connection", "path", "name", "schema", "create", "internal"]) && Number.isSafeInteger(value.connection) && typeof value.path === "string" && typeof value.name === "string" && (typeof value.schema === "string" || value.schema === null) && typeof value.create === "boolean" && typeof value.internal === "boolean";
@@ -190,9 +334,16 @@
         return hasKeys(value, ["id", "type", "bytes"]) && value.bytes instanceof Uint8Array;
       case "removeFile":
         return hasKeys(value, ["id", "type", "path"]) && typeof value.path === "string";
+      case "registerExternalFile":
+        return hasKeys(value, ["id", "type", "name", "url", "size"]) && typeof value.name === "string" && typeof value.url === "string" && typeof value.size === "number" && Number.isSafeInteger(value.size) && value.size >= 0 || hasKeys(value, ["id", "type", "path"]) && typeof value.path === "string";
+      case "registerExternalDirectory":
+        return (value.mode === "read" || value.mode === "readwrite") && (hasKeys(value, ["id", "type", "handle", "mode"]) && isRecord(value.handle) && value.handle.kind === "directory" || hasKeys(value, ["id", "type", "path", "mode"]) && typeof value.path === "string" && !!value.path && !value.path.includes("\0"));
+      case "removeExternalRegistration":
+        return hasKeys(value, ["id", "type", "path"]) && typeof value.path === "string";
       case "pollQuery":
       case "cancelQuery":
       case "releaseQuery":
+      case "releaseQueryWithInfo":
         return hasKeys(value, ["id", "type", "query"]) && Number.isSafeInteger(value.query);
       default:
         return false;
@@ -203,6 +354,10 @@
   function errorText(error) {
     return error instanceof Error ? error.message : String(error);
   }
+  function isNotFoundError(error) {
+    if (typeof error !== "object" || error === null) return false;
+    return "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR") || "name" in error && error.name === "NotFoundError";
+  }
   function safePointer(value, name) {
     const pointer = typeof value === "bigint" && value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : value;
     if (typeof pointer !== "number" || !Number.isSafeInteger(pointer) || pointer < 0) throw new Error(`${name} must be a nonnegative safe integer`);
@@ -211,22 +366,48 @@
   function allocate(module, bytes) {
     const pointer = safePointer(module._malloc(bytes.byteLength || 1), "allocation pointer");
     if (pointer === 0) throw new Error("wasm allocation failed");
-    if (pointer + bytes.byteLength > module.HEAPU8.byteLength) throw new Error("allocation exceeds the wasm heap");
-    module.HEAPU8.set(bytes, pointer);
+    module.getValue(pointer, "i8");
+    const heap = module.HEAPU8;
+    if (pointer + bytes.byteLength > heap.byteLength) throw new Error("allocation exceeds the wasm heap");
+    heap.set(bytes, pointer);
     return pointer;
   }
+  function externalDirectoryError(module, error) {
+    return safePointer(module.stringToNewUTF8(errorText(error)), "external directory error pointer");
+  }
+  function completeExternalDirectoryOperation(module, id, complete, operation) {
+    void Promise.resolve().then(operation).then(
+      () => complete(id, 0),
+      (error) => complete(id, externalDirectoryError(module, error))
+    );
+  }
   function installHttpRuntime(module, transport) {
-    module.hyperdbWasmFetchStart = (id, url, offset, length) => {
+    module.hyperdbWasmFetchStart = (id, url, offset, length, expectedSize) => {
+      if (url.startsWith("hyperdb-node-file:") || url.startsWith("hyperdb-node-host-file:") || url.startsWith("hyperdb-node-directory-file:") || url.startsWith("hyperdb-browser-file:")) {
+        const read = module.externalFileBackend?.read(url, offset, length, expectedSize) ?? module.externalDirectoryBackend?.read(url, offset, length, expectedSize);
+        if (!read) {
+          module._hyperdb_wasm_fetch_complete(id, 0, -1);
+          return;
+        }
+        void read.then((bytes) => {
+          module._hyperdb_wasm_fetch_complete(id, allocate(module, bytes), bytes.byteLength);
+        }).catch(() => {
+          module._hyperdb_wasm_fetch_complete(id, 0, -1);
+        });
+        return;
+      }
       const headers = new Headers();
       if (length > 0) headers.set("Range", `bytes=${offset}-${offset + length - 1}`);
       void fetch(url, { headers, redirect: "manual" }).then(async (response) => {
         if (!response.ok || response.type === "opaqueredirect" || (length === 0 ? response.status !== 200 : response.status !== 206)) {
+          void response.body?.cancel().catch(() => void 0);
           module._hyperdb_wasm_fetch_complete(id, 0, -1);
           return;
         }
         if (length > 0) {
           const contentRange = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(response.headers.get("content-range") ?? "");
-          if (!contentRange || contentRange[1] !== String(offset) || contentRange[2] !== String(offset + length - 1)) {
+          if (!contentRange || contentRange[1] !== String(offset) || contentRange[2] !== String(offset + length - 1) || expectedSize >= 0 && contentRange[3] !== String(expectedSize)) {
+            void response.body?.cancel().catch(() => void 0);
             module._hyperdb_wasm_fetch_complete(id, 0, -1);
             return;
           }
@@ -275,6 +456,97 @@
       });
     };
   }
+  function installExternalDirectoryRuntime(module) {
+    const backend = module.externalDirectoryBackend;
+    if (!backend) return;
+    const listComplete = module._hyperdb_wasm_external_directory_list_complete;
+    const openComplete = module._hyperdb_wasm_external_directory_open_complete;
+    if (listComplete) {
+      module.hyperdbWasmExternalDirectoryListStart = (id, locator) => {
+        void backend.list(locator).then((paths) => {
+          listComplete(id, safePointer(module.stringToNewUTF8(JSON.stringify(paths)), "external directory list pointer"), 0);
+        }).catch((error) => {
+          listComplete(id, 0, externalDirectoryError(module, error));
+        });
+      };
+    }
+    if (openComplete) {
+      module.hyperdbWasmExternalDirectoryOpenStart = (id, locator, path) => {
+        void backend.open(locator, path).then((file) => {
+          openComplete(id, safePointer(module.stringToNewUTF8(file.locator), "external file locator pointer"), file.size);
+        }).catch((error) => openComplete(id, 0, isNotFoundError(error) ? -2 : -1));
+      };
+    }
+    const createDirectoriesComplete = module._hyperdb_wasm_external_directory_create_directories_complete;
+    if (createDirectoriesComplete) {
+      module.hyperdbWasmExternalDirectoryCreateDirectoriesStart = (id, locator, path) => {
+        completeExternalDirectoryOperation(module, id, createDirectoriesComplete, () => backend.createDirectories(locator, path));
+      };
+    }
+    const writerWriteComplete = module._hyperdb_wasm_external_directory_writer_write_complete;
+    if (writerWriteComplete) {
+      module.hyperdbWasmExternalDirectoryWriterWriteStart = (writer, id, locator, path, offset, pointerValue, length) => {
+        try {
+          const pointer = safePointer(pointerValue, "external directory write pointer");
+          const safeLength = safePointer(length, "external directory write length");
+          const end = safePointer(pointer + safeLength, "external directory write end");
+          module.getValue(pointer, "i8");
+          if (end > module.HEAPU8.byteLength) throw new Error("external directory write exceeds the wasm heap");
+          const bytes = module.HEAPU8.slice(pointer, end);
+          completeExternalDirectoryOperation(module, id, writerWriteComplete, async () => {
+            await backend.openWriter(writer, locator, path);
+            await backend.write(writer, offset, bytes);
+          });
+        } catch (error) {
+          writerWriteComplete(id, externalDirectoryError(module, error));
+        }
+      };
+    }
+    const writerFinishComplete = module._hyperdb_wasm_external_directory_writer_finish_complete;
+    if (writerFinishComplete) {
+      module.hyperdbWasmExternalDirectoryWriterFinishStart = (writer, id, locator, path, size) => {
+        completeExternalDirectoryOperation(module, id, writerFinishComplete, async () => {
+          await backend.openWriter(writer, locator, path);
+          await backend.finish(writer, size);
+        });
+      };
+    }
+    const writerAbortComplete = module._hyperdb_wasm_external_directory_writer_abort_complete;
+    if (writerAbortComplete) {
+      module.hyperdbWasmExternalDirectoryWriterAbortStart = (writer, id) => {
+        completeExternalDirectoryOperation(module, id, writerAbortComplete, () => backend.abort(writer));
+      };
+    }
+  }
+  function installHostFileRuntime(module) {
+    const complete = module._hyperdb_wasm_host_file_open_complete;
+    if (!complete) return;
+    module.hyperdbWasmHostFileOpenStart = (id, path) => {
+      try {
+        const file = module.externalFileBackend?.openHostFile(path);
+        if (!file) throw new Error("Node host-file backend is unavailable");
+        complete(id, file.id, file.size);
+      } catch (error) {
+        complete(id, 0, isNotFoundError(error) ? -2 : -1);
+      }
+    };
+    module.hyperdbWasmHostFileClose = (id) => module.externalFileBackend?.closeHostFile(id);
+    const listComplete = module._hyperdb_wasm_external_directory_list_complete;
+    if (listComplete) {
+      module.hyperdbWasmHostDirectoryListStart = (id, path) => {
+        const list = module.externalFileBackend?.listHostDirectory(path);
+        if (!list) {
+          listComplete(id, 0, externalDirectoryError(module, new Error("Node host-directory backend is unavailable")));
+          return;
+        }
+        void list.then((paths) => {
+          listComplete(id, safePointer(module.stringToNewUTF8(JSON.stringify(paths)), "host directory list pointer"), 0);
+        }).catch((error) => {
+          listComplete(id, 0, externalDirectoryError(module, error));
+        });
+      };
+    }
+  }
   function configureWorker(module, transport, configureFilesystem = () => void 0) {
     const queuedRequests = [];
     let bindings;
@@ -285,8 +557,14 @@
       }
       try {
         const result = bindings.handle(request);
-        if (request.type === "shutdown" && result.response.result.state === "ok") module.PThread.terminateAllThreads();
-        transport.postMessage(result.response, result.transfer);
+        const complete = () => {
+          if (request.type === "shutdown" && result.response.result.state === "ok") module.PThread.terminateAllThreads();
+          transport.postMessage(result.response, result.transfer);
+        };
+        if (result.completion) void result.completion.then(complete, (error) => {
+          transport.postMessage({ id: request.id, type: "response", result: { state: "error", error: errorText(error) } });
+        });
+        else complete();
       } catch (error) {
         transport.postMessage({ id: request.id, type: "response", result: { state: "error", error: errorText(error) } });
       }
@@ -300,6 +578,8 @@
       try {
         configureFilesystem(module);
         installHttpRuntime(module, transport);
+        installHostFileRuntime(module);
+        installExternalDirectoryRuntime(module);
         bindings = new HyperDBBindings(module);
         transport.postMessage({ type: "ready" });
         for (const request of queuedRequests.splice(0)) handle(request);
@@ -310,6 +590,256 @@
     module.onAbort = (reason) => transport.postMessage({ type: "fatal", error: `engine aborted: ${String(reason)}` });
   }
 
+  // src/browser_external_directory.ts
+  var directoryLocatorPrefix = "hyperdb-browser-directory:";
+  var fileLocatorPrefix = "hyperdb-browser-file:";
+  function opaqueId() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  }
+  function validateSegment(segment) {
+    if (!segment || segment === "." || segment === ".." || segment.includes("/") || segment.includes("\\") || segment.includes("\0")) {
+      throw new Error("External directory entries must have safe relative path segments");
+    }
+  }
+  function relativeSegments(path) {
+    if (!path || path.startsWith("/") || path.endsWith("/") || path.includes("\\") || path.includes("\0")) {
+      throw new Error("External directory file path must be relative");
+    }
+    const segments = path.split("/");
+    for (const segment of segments) validateSegment(segment);
+    return segments;
+  }
+  function directorySegments(path) {
+    return path ? relativeSegments(path) : [];
+  }
+  function nonnegativeSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${name} must be a nonnegative safe integer`);
+  }
+  function asDirectoryHandle(handle) {
+    if (typeof handle !== "object" || handle === null || !("kind" in handle) || handle.kind !== "directory" || !("values" in handle) || typeof handle.values !== "function" || !("getDirectoryHandle" in handle) || typeof handle.getDirectoryHandle !== "function" || !("getFileHandle" in handle) || typeof handle.getFileHandle !== "function") {
+      throw new Error("External directory handle is invalid");
+    }
+    return handle;
+  }
+  var BrowserExternalDirectoryBackend = class {
+    directories = /* @__PURE__ */ new Map();
+    paths = /* @__PURE__ */ new Map();
+    files = /* @__PURE__ */ new Map();
+    writers = /* @__PURE__ */ new Map();
+    register(handle, mode) {
+      const directoryHandle = asDirectoryHandle(handle);
+      validateSegment(directoryHandle.name);
+      const locator = `${directoryLocatorPrefix}${opaqueId()}`;
+      this.directories.set(locator, { handle: directoryHandle, mode, files: /* @__PURE__ */ new Map(), locators: /* @__PURE__ */ new Set() });
+      return { name: directoryHandle.name, locator };
+    }
+    registered(path, locator) {
+      if (!this.directories.has(locator)) throw new Error("External directory registration is unavailable");
+      this.paths.set(path, locator);
+    }
+    removed(pathOrLocator) {
+      const locator = this.paths.get(pathOrLocator) ?? pathOrLocator;
+      const directory = this.directories.get(locator);
+      if (!directory) return;
+      for (const fileLocator of directory.locators) this.files.delete(fileLocator);
+      for (const [writer, state] of this.writers) {
+        if (state.locator === locator) void this.abort(writer).catch(() => void 0);
+      }
+      this.directories.delete(locator);
+      this.paths.delete(pathOrLocator);
+    }
+    async list(locator) {
+      const directory = this.getDirectory(locator);
+      const files = [];
+      const visit = async (handle, prefix) => {
+        for await (const child of handle.values()) {
+          validateSegment(child.name);
+          const path = prefix ? `${prefix}/${child.name}` : child.name;
+          if (child.kind === "file") files.push(path);
+          else if (child.kind === "directory") await visit(child, path);
+          else throw new Error("External directory contains an unsupported entry");
+        }
+      };
+      await visit(directory.handle, "");
+      files.sort();
+      return files;
+    }
+    async open(locator, path) {
+      const directory = this.getDirectory(locator);
+      const cached = directory.files.get(path);
+      if (cached) {
+        const file = await cached;
+        return { locator: file.locator, size: file.file.size };
+      }
+      const segments = relativeSegments(path);
+      const snapshot = (async () => {
+        let parent = directory.handle;
+        for (const segment of segments.slice(0, -1)) {
+          const child = await parent.getDirectoryHandle(segment);
+          if (child.kind !== "directory" || child.name !== segment) throw new Error("External directory returned an unexpected child handle");
+          parent = child;
+        }
+        const name = segments.at(-1);
+        if (!name) throw new Error("External directory file path must not be empty");
+        const fileHandle = await parent.getFileHandle(name);
+        if (fileHandle.kind !== "file" || fileHandle.name !== name) throw new Error("External directory returned an unexpected file handle");
+        const file = await fileHandle.getFile();
+        if (!Number.isSafeInteger(file.size) || file.size < 0) throw new Error("External file size must be a nonnegative safe integer");
+        const fileLocator = `${fileLocatorPrefix}${opaqueId()}`;
+        this.files.set(fileLocator, file);
+        directory.locators.add(fileLocator);
+        return { locator: fileLocator, file };
+      })();
+      directory.files.set(path, snapshot);
+      try {
+        const file = await snapshot;
+        return { locator: file.locator, size: file.file.size };
+      } catch (error) {
+        directory.files.delete(path);
+        throw error;
+      }
+    }
+    read(locator, offset, length, expectedSize) {
+      if (!locator.startsWith(fileLocatorPrefix)) return void 0;
+      const file = this.files.get(locator);
+      if (!file) return Promise.reject(new Error("External directory file registration does not exist"));
+      const end = offset + length;
+      if (expectedSize !== file.size || !Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length < 0 || !Number.isSafeInteger(end) || end > file.size) {
+        return Promise.reject(new Error("External file byte range is invalid"));
+      }
+      return file.slice(offset, end).arrayBuffer().then((buffer) => {
+        const bytes = new Uint8Array(buffer);
+        if (bytes.byteLength !== length) throw new Error("External file ended before the registered size");
+        return bytes;
+      });
+    }
+    async createDirectories(locator, path) {
+      const directory = this.getWritableDirectory(locator);
+      let parent = directory.handle;
+      for (const segment of directorySegments(path)) {
+        const child = await parent.getDirectoryHandle(segment, { create: true });
+        if (child.kind !== "directory" || child.name !== segment) throw new Error("External directory returned an unexpected child handle");
+        parent = child;
+      }
+    }
+    openWriter(writer, locator, path) {
+      nonnegativeSafeInteger(writer, "External directory writer");
+      const directory = this.getWritableDirectory(locator);
+      const segments = relativeSegments(path);
+      const name = segments.at(-1);
+      if (!name) throw new Error("External directory file path must not be empty");
+      const existing = this.writers.get(writer);
+      if (existing) {
+        if (existing.locator !== locator || existing.path !== path) throw new Error("External directory writer was reused for another path");
+        return existing.chain;
+      }
+      const state = { locator, path, name, chain: Promise.resolve(), terminal: false };
+      this.writers.set(writer, state);
+      const opened = this.enqueue(state, async () => {
+        let parent = directory.handle;
+        for (const segment of segments.slice(0, -1)) {
+          const child = await parent.getDirectoryHandle(segment, { create: true });
+          if (child.kind !== "directory" || child.name !== segment) throw new Error("External directory returned an unexpected child handle");
+          parent = child;
+        }
+        let file;
+        try {
+          file = await parent.getFileHandle(name);
+          state.createdTarget = false;
+        } catch (error) {
+          if (!(error instanceof DOMException) || error.name !== "NotFoundError") throw error;
+          file = await parent.getFileHandle(name, { create: true });
+          state.createdTarget = true;
+        }
+        if (file.kind !== "file" || file.name !== name || typeof file.createWritable !== "function") {
+          throw new Error("External directory returned an unexpected file handle");
+        }
+        state.parent = parent;
+        state.stream = await file.createWritable();
+      });
+      return opened;
+    }
+    write(writer, offset, bytes) {
+      nonnegativeSafeInteger(offset, "External directory write offset");
+      nonnegativeSafeInteger(offset + bytes.byteLength, "External directory write end");
+      const state = this.getOpenWriter(writer);
+      return this.enqueue(state, () => {
+        if (!state.stream) throw new Error("External directory writer failed to open");
+        return state.stream.write({ type: "write", position: offset, data: bytes });
+      });
+    }
+    finish(writer, size) {
+      nonnegativeSafeInteger(size, "External directory file size");
+      const state = this.getOpenWriter(writer);
+      state.terminal = true;
+      const operation = this.enqueue(state, async () => {
+        let failure = state.failure;
+        if (failure === void 0 && !state.stream) failure = new Error("External directory writer failed to open");
+        if (failure === void 0) {
+          try {
+            await state.stream?.truncate(size);
+            await state.stream?.close();
+          } catch (error) {
+            failure = error;
+          }
+        }
+        if (failure !== void 0) {
+          await this.cleanupWriter(state).catch(() => void 0);
+          throw failure;
+        }
+        this.getDirectory(state.locator).files.delete(state.path);
+      }, true);
+      return operation.finally(() => this.writers.delete(writer));
+    }
+    abort(writer) {
+      const state = this.getOpenWriter(writer);
+      state.terminal = true;
+      const operation = this.enqueue(state, () => this.cleanupWriter(state), true);
+      return operation.finally(() => this.writers.delete(writer));
+    }
+    shutdown() {
+      for (const writer of this.writers.keys()) void this.abort(writer).catch(() => void 0);
+      this.files.clear();
+      this.paths.clear();
+      this.directories.clear();
+    }
+    getDirectory(locator) {
+      const directory = this.directories.get(locator);
+      if (!directory) throw new Error("External directory registration does not exist");
+      return directory;
+    }
+    getWritableDirectory(locator) {
+      const directory = this.getDirectory(locator);
+      if (directory.mode !== "readwrite") throw new Error("External directory registration is not writable");
+      return directory;
+    }
+    getOpenWriter(writer) {
+      nonnegativeSafeInteger(writer, "External directory writer");
+      const state = this.writers.get(writer);
+      if (!state || state.terminal) throw new Error("External directory writer is not open");
+      return state;
+    }
+    async cleanupWriter(state) {
+      this.directories.get(state.locator)?.files.delete(state.path);
+      try {
+        await state.stream?.abort();
+      } finally {
+        if (state.createdTarget) await state.parent?.removeEntry?.(state.name).catch(() => void 0);
+      }
+    }
+    enqueue(state, operation, afterFailure = false) {
+      const result = state.chain.then(async () => {
+        if (!afterFailure && state.failure !== void 0) throw state.failure;
+        await operation();
+      });
+      state.chain = result.catch((error) => {
+        state.failure ??= error;
+      });
+      return result;
+    }
+  };
+
   // src/browser_worker.ts
   var configuredEngineUrl = new URL(self.location.href).searchParams.get("engineUrl");
   var engineUrl = self.HYPERDB_WASM_ENGINE_URL ?? configuredEngineUrl ?? "hyperdb-wasm.js";
@@ -356,6 +886,8 @@
     };
     self.Module = module;
     configureWorker(module, transport, (runtime) => {
+      runtime.externalFileBackendAvailable = true;
+      runtime.externalDirectoryBackend = new BrowserExternalDirectoryBackend();
       if (!runtime.OPFS) throw new Error("OPFS backend is unavailable");
       runtime.FS.mkdirTree("/opfs");
       runtime.FS.mount(runtime.OPFS, {}, "/opfs");