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

package/dist/protocol.d.ts

@@ -1,4 +1,12 @@
 export type RequestId = number;
+export type HyperDBErrorSource = 'User' | 'System' | 'OverloadRejection';
+export interface HyperDBErrorData {
+    readonly sqlState: string;
+    readonly errorSource: HyperDBErrorSource;
+    readonly message: string;
+    readonly detail: string;
+    readonly hint: string;
+}
 export type EngineRequest = {
     id: RequestId;
     type: 'initialize';
@@ -49,6 +57,12 @@ export type EngineRequest = {
     type: 'startQuery';
     connection: number;
     sql: string;
+    sqlTestMode?: boolean;
+} | {
+    id: RequestId;
+    type: 'startQueryWithInfo';
+    connection: number;
+    sql: string;
 } | {
     id: RequestId;
     type: 'insertArrowIPCFromPath';
@@ -66,6 +80,30 @@ export type EngineRequest = {
     id: RequestId;
     type: 'removeFile';
     path: string;
+} | {
+    id: RequestId;
+    type: 'registerExternalFile';
+    name: string;
+    url: string;
+    size: number;
+} | {
+    id: RequestId;
+    type: 'registerExternalFile';
+    path: string;
+} | {
+    id: RequestId;
+    type: 'registerExternalDirectory';
+    handle: unknown;
+    mode: 'read' | 'readwrite';
+} | {
+    id: RequestId;
+    type: 'registerExternalDirectory';
+    path: string;
+    mode: 'read' | 'readwrite';
+} | {
+    id: RequestId;
+    type: 'removeExternalRegistration';
+    path: string;
 } | {
     id: RequestId;
     type: 'pollQuery';
@@ -78,6 +116,10 @@ export type EngineRequest = {
     id: RequestId;
     type: 'releaseQuery';
     query: number;
+} | {
+    id: RequestId;
+    type: 'releaseQueryWithInfo';
+    query: number;
 };
 export type WasmResult = {
     state: 'ok';
@@ -91,7 +133,7 @@ export type WasmResult = {
     state: 'done';
 } | {
     state: 'error';
-    error: string;
+    error: string | HyperDBErrorData;
 } | {
     state: 'busy';
     error: string;
@@ -124,5 +166,6 @@ export interface WorkerTransport {
     terminate(): void | Promise<unknown>;
 }
 export declare function isWasmResult(value: unknown): value is WasmResult;
+export declare function isHyperDBErrorData(value: unknown): value is HyperDBErrorData;
 export declare function isEngineRequest(value: unknown): value is EngineRequest;
 export declare function isWorkerEvent(message: unknown): message is WorkerEvent;

package/dist/raw.browser.js

@@ -17,12 +17,16 @@ function isWasmResult(value) {
     case "done":
       return hasKeys(value, ["state"]);
     case "error":
+      return hasKeys(value, ["state", "error"]) && (typeof value.error === "string" || isHyperDBErrorData(value.error));
     case "busy":
       return hasKeys(value, ["state", "error"]) && typeof value.error === "string";
     default:
       return false;
   }
 }
+function isHyperDBErrorData(value) {
+  return isRecord(value) && hasKeys(value, ["sqlState", "errorSource", "message", "detail", "hint"]) && typeof value.sqlState === "string" && /^[0-9A-Z]{5}$/.test(value.sqlState) && (value.errorSource === "User" || value.errorSource === "System" || value.errorSource === "OverloadRejection") && typeof value.message === "string" && typeof value.detail === "string" && typeof value.hint === "string";
+}
 function isWorkerEvent(message) {
   if (!isRecord(message) || typeof message.type !== "string") return false;
   switch (message.type) {
@@ -101,8 +105,11 @@ var HyperDBEngineClient = class {
   shutdown() {
     return this.request({ id: this.nextId++, type: "shutdown" });
   }
-  startQuery(connection, sql) {
-    return this.request({ id: this.nextId++, type: "startQuery", connection, sql });
+  startQuery(connection, sql, sqlTestMode = false) {
+    return this.request({ id: this.nextId++, type: "startQuery", connection, sql, ...sqlTestMode && { sqlTestMode } });
+  }
+  startQueryWithInfo(connection, sql) {
+    return this.request({ id: this.nextId++, type: "startQueryWithInfo", connection, sql });
   }
   insertArrowIPCFromPath(connection, path, name, schema, create, internal = false) {
     return this.request({ id: this.nextId++, type: "insertArrowIPCFromPath", connection, path, name, schema, create, internal });
@@ -114,6 +121,15 @@ var HyperDBEngineClient = class {
   removeFile(path) {
     return this.request({ id: this.nextId++, type: "removeFile", path });
   }
+  registerExternalFile(pathOrName, url, size) {
+    return url === void 0 || size === void 0 ? this.request({ id: this.nextId++, type: "registerExternalFile", path: pathOrName }) : this.request({ id: this.nextId++, type: "registerExternalFile", name: pathOrName, url, size });
+  }
+  registerExternalDirectory(source, mode) {
+    return typeof source === "string" ? this.request({ id: this.nextId++, type: "registerExternalDirectory", path: source, mode }) : this.request({ id: this.nextId++, type: "registerExternalDirectory", handle: source, mode });
+  }
+  removeExternalRegistration(path) {
+    return this.request({ id: this.nextId++, type: "removeExternalRegistration", path });
+  }
   pollQuery(query) {
     return this.request({ id: this.nextId++, type: "pollQuery", query });
   }
@@ -123,6 +139,9 @@ var HyperDBEngineClient = class {
   releaseQuery(query) {
     return this.request({ id: this.nextId++, type: "releaseQuery", query });
   }
+  releaseQueryWithInfo(query) {
+    return this.request({ id: this.nextId++, type: "releaseQueryWithInfo", query });
+  }
   async terminate() {
     await this.transport.terminate();
     this.fail(new Error("engine worker terminated"));
@@ -170,7 +189,12 @@ var HyperDBEngineClient = class {
 };
 
 // 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`);
@@ -180,6 +204,33 @@ function validateCString(value, name) {
   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;
@@ -191,13 +242,18 @@ var HyperDBBindings = class {
   checkpointDatabase;
   dropDatabase;
   shutdown;
+  registerExternalFile;
+  registerExternalDirectory;
+  removeExternalRegistration;
   attachDatabase;
   detachDatabase;
   startQuery;
+  startQueryWithInfo;
   insertArrowIPCFromPath;
   pollQuery;
   cancelQuery;
   releaseQuery;
+  releaseQueryWithInfo;
   resultState;
   resultPayloadLength;
   free;
@@ -213,13 +269,18 @@ var HyperDBBindings = class {
     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"]);
@@ -235,8 +296,92 @@ var HyperDBBindings = class {
       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] : [] };
   }
@@ -272,8 +417,20 @@ var HyperDBBindings = class {
         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));
@@ -284,6 +441,8 @@ var HyperDBBindings = class {
         return this.cancelQuery(request.query);
       case "releaseQuery":
         return this.releaseQuery(request.query);
+      case "releaseQueryWithInfo":
+        return this.releaseQueryWithInfo(request.query);
     }
   }
   decodeResult(pointer) {
@@ -313,6 +472,8 @@ var HyperDBBindings = class {
           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);
@@ -324,6 +485,7 @@ var HyperDBBindings = class {
 var memory64Probe = new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0, 5, 3, 1, 4, 1]);
 var threadsProbe = new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0, 5, 4, 1, 3, 1, 1]);
 var exceptionsProbe = new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0, 1, 4, 1, 96, 0, 0, 13, 3, 1, 0, 0]);
+var tailCallsProbe = new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0, 1, 4, 1, 96, 0, 0, 3, 3, 2, 0, 0, 10, 9, 2, 4, 0, 18, 1, 11, 2, 0, 11]);
 function assertBrowserSupport(environment = globalThis) {
   if (typeof environment.WebAssembly?.validate !== "function") {
     throw new Error("HyperDB cannot initialize because this browser does not support WebAssembly");
@@ -331,6 +493,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.");
   }
@@ -340,6 +508,9 @@ function assertBrowserSupport(environment = globalThis) {
   if (!environment.WebAssembly.validate(exceptionsProbe)) {
     throw new Error("HyperDB cannot initialize because this browser does not support WebAssembly exception handling");
   }
+  if (!environment.WebAssembly.validate(tailCallsProbe)) {
+    throw new Error("HyperDB cannot initialize because this browser does not support WebAssembly tail calls");
+  }
   if (typeof environment.Worker !== "function") {
     throw new Error("HyperDB cannot initialize because this browser does not support Web Workers");
   }

package/dist/raw.d.ts

@@ -1,3 +1,3 @@
 export { HyperDBEngineClient } from './client.js';
 export { HyperDBBindings } from './wasm_bindings.js';
-export type { EngineRequest, SetupProgress, WasmResponse, WasmResult, WorkerEvent, WorkerTransport } from './protocol.js';
+export type { EngineRequest, HyperDBErrorData, HyperDBErrorSource, SetupProgress, WasmResponse, WasmResult, WorkerEvent, WorkerTransport } from './protocol.js';