hyperdb-wasm 0.0.26553-dev.wasm.gc7d06744 → 0.0.26773-dev.wasm.g25ca5c66

package/dist/api.d.ts

@@ -19,6 +19,8 @@ export interface HyperDBClient {
     insertArrowIPCFromPath(connection: number, path: string, name: string, schema: string | null, create: boolean, internal?: boolean): Promise<WasmResult>;
     createTemporaryFile(bytes: Uint8Array): Promise<WasmResult>;
     removeFile(path: string): Promise<WasmResult>;
+    registerExternalFile(name: string, url: string, size: number): Promise<WasmResult>;
+    removeExternalFile(path: string): Promise<WasmResult>;
     pollQuery(query: number): Promise<WasmResult>;
     cancelQuery(query: number): Promise<WasmResult>;
     releaseQuery(query: number): Promise<WasmResult>;
@@ -33,6 +35,11 @@ export interface ArrowInsertOptions {
 export interface DatabaseCreateOptions {
     readonly storage?: 'memory' | 'persistent';
 }
+export interface ExternalFileRegistration {
+    readonly name: string;
+    readonly url: string;
+    readonly size: number;
+}
 export type HyperDBSettingValue = string | number | boolean | null | readonly HyperDBSettingValue[] | {
     readonly [key: string]: HyperDBSettingValue;
 };
@@ -59,6 +66,8 @@ export declare class HyperDB {
     createDatabase(databaseName: string, options?: DatabaseCreateOptions): Promise<void>;
     openDatabase(databaseName: string): Promise<void>;
     listDatabases(): Promise<DatabaseMetadata[]>;
+    registerExternalFile(name: string, url: string, size: number): Promise<string>;
+    removeExternalFile(path: string): Promise<void>;
     checkpointDatabase(databaseName: string): Promise<void>;
     dropDatabase(databaseName: string): Promise<void>;
     terminate(): Promise<void>;

package/dist/browser.js

@@ -139,6 +139,12 @@ var init_client = __esm({
       removeFile(path) {
         return this.request({ id: this.nextId++, type: "removeFile", path });
       }
+      registerExternalFile(name, url, size) {
+        return this.request({ id: this.nextId++, type: "registerExternalFile", name, url, size });
+      }
+      removeExternalFile(path) {
+        return this.request({ id: this.nextId++, type: "removeExternalFile", path });
+      }
       pollQuery(query) {
         return this.request({ id: this.nextId++, type: "pollQuery", query });
       }
@@ -211,6 +217,12 @@ function assertBrowserSupport(environment = globalThis) {
   if (!environment.WebAssembly.validate(memory64Probe)) {
     throw new Error("HyperDB cannot initialize because this browser does not yet support WebAssembly memory64. Support for platforms such as iOS is coming soon.");
   }
+  try {
+    const Memory64 = environment.WebAssembly.Memory;
+    new Memory64({ initial: 1n, maximum: 262144n, shared: true, address: "i64" });
+  } catch {
+    throw new Error("HyperDB cannot initialize because this browser does not support a shared 16 GiB WebAssembly memory64 declaration");
+  }
   if (typeof environment.BigInt !== "function") {
     throw new Error("HyperDB cannot initialize because this browser does not yet support WebAssembly BigInt integration. Support for platforms such as iOS is coming soon.");
   }
@@ -12270,6 +12282,34 @@ var HyperDB = class _HyperDB {
   listDatabases() {
     return this.runDatabaseOperation(async () => readDatabasesFromResult(await this.client.listDatabases()));
   }
+  async registerExternalFile(name, url, size) {
+    if (!name) throw new Error("External file name must not be empty");
+    if (name.includes("\0")) throw new Error("External file name must not contain NUL");
+    if (name === "." || name === ".." || name.includes("/") || name.includes("\\")) {
+      throw new Error("External file name must be a basename without path separators");
+    }
+    if (!Number.isSafeInteger(size) || size < 0) throw new Error("External file size must be a nonnegative safe integer");
+    let scheme;
+    try {
+      scheme = new URL(url).protocol;
+    } catch {
+      throw new Error("External file URL must use the blob scheme");
+    }
+    if (scheme !== "blob:") throw new Error("External file URL must use the blob scheme");
+    return this.runDatabaseOperation(async () => {
+      const result = await this.client.registerExternalFile(name, url, size);
+      expectOk(result, "register external file");
+      const path = new TextDecoder("utf-8", { fatal: true }).decode(result.payload);
+      if (!/^\/mnt\/files\/[^/]+\/[^/]+$/.test(path)) throw new Error("register external file returned an invalid path");
+      return path;
+    });
+  }
+  async removeExternalFile(path) {
+    if (!path) throw new Error("External file path must not be empty");
+    await this.runDatabaseOperation(async () => {
+      expectOk(await this.client.removeExternalFile(path), "remove external file");
+    });
+  }
   async checkpointDatabase(databaseName) {
     validateDatabaseName(databaseName);
     await this.runDatabaseOperation(async () => {

package/dist/browser_worker.js

@@ -22,6 +22,8 @@
     checkpointDatabase;
     dropDatabase;
     shutdown;
+    registerExternalFile;
+    removeExternalFile;
     attachDatabase;
     detachDatabase;
     startQuery;
@@ -44,6 +46,8 @@
       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.removeExternalFile = module.cwrap("hyperdb_wasm_remove_external_file", "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"]);
@@ -66,6 +70,9 @@
         this.module.FS.unlink(request.path);
         return { response: { id: request.id, type: "response", result: { state: "ok", payload: new Uint8Array() } }, transfer: [] };
       }
+      if ((request.type === "registerExternalFile" || request.type === "removeExternalFile") && !this.module.externalFileBackendAvailable) {
+        return { response: { id: request.id, type: "response", result: { state: "error", error: "External files are supported only by the browser client" } }, transfer: [] };
+      }
       const pointer = safeInteger(this.invoke(request), "result pointer");
       const result = this.decodeResult(pointer);
       const response = { id: request.id, type: "response", result };
@@ -103,6 +110,13 @@
           return this.detachDatabase(request.connection, request.alias);
         case "shutdown":
           return this.shutdown();
+        case "registerExternalFile":
+          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 "removeExternalFile":
+          validateCString(request.path, "external file path");
+          return this.removeExternalFile(request.path);
         case "startQuery":
           return this.startQuery(request.connection, request.sql);
         case "insertArrowIPCFromPath": {
@@ -190,6 +204,10 @@
         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;
+      case "removeExternalFile":
+        return hasKeys(value, ["id", "type", "path"]) && typeof value.path === "string";
       case "pollQuery":
       case "cancelQuery":
       case "releaseQuery":
@@ -356,6 +374,7 @@
     };
     self.Module = module;
     configureWorker(module, transport, (runtime) => {
+      runtime.externalFileBackendAvailable = true;
       if (!runtime.OPFS) throw new Error("OPFS backend is unavailable");
       runtime.FS.mkdirTree("/opfs");
       runtime.FS.mount(runtime.OPFS, {}, "/opfs");

package/dist/client.d.ts

@@ -26,6 +26,8 @@ export declare class HyperDBEngineClient {
     insertArrowIPCFromPath(connection: number, path: string, name: string, schema: string | null, create: boolean, internal?: boolean): Promise<WasmResult>;
     createTemporaryFile(bytes: Uint8Array): Promise<WasmResult>;
     removeFile(path: string): Promise<WasmResult>;
+    registerExternalFile(name: string, url: string, size: number): Promise<WasmResult>;
+    removeExternalFile(path: string): Promise<WasmResult>;
     pollQuery(query: number): Promise<WasmResult>;
     cancelQuery(query: number): Promise<WasmResult>;
     releaseQuery(query: number): Promise<WasmResult>;