hyperdb-wasm 0.0.27356-dev.wasm.ga5fd9868 → 0.0.27367-dev.wasm.g50457039

package/dist/api.d.ts

@@ -5,6 +5,7 @@ import type { BrowserClientOptions } from './browser.js';
 import type { MountSource, WasmResult } from './protocol.js';
 import type { HyperDBErrorSource } from './protocol.js';
 export interface HyperDBClient {
+    readonly failure?: Error | undefined;
     ready(): Promise<void>;
     initialize(settings: HyperDBSettings): Promise<WasmResult>;
     connect(settings?: ConnectionSettings): Promise<WasmResult>;
@@ -125,6 +126,7 @@ export declare class HyperDBConnection {
     execute(sql: string, options?: QueryOptions): QueryPromise<bigint | null>;
     private ensureAvailable;
     closeForTermination(): Promise<void>;
+    releaseAfterShutdown(): void;
 }
 export type { HyperDBEngineClient };
 export { initializeHyperDB as initializeHyperDBInternal };

package/dist/browser.d.ts

@@ -14,6 +14,8 @@ export interface BrowserClientOptions {
     /** OPFS-relative directory mounted as the durable filesystem root. */
     readonly storagePath?: string;
     readonly onSetupProgress?: (progress: SetupProgress) => void;
+    /** Receives engine output; omitted callbacks discard output, and callback exceptions are ignored */
+    readonly onLog?: (stream: 'stdout' | 'stderr', text: string) => void;
 }
 type BrowserEnvironment = {
     readonly WebAssembly?: typeof WebAssembly;

package/dist/browser.js

@@ -52,7 +52,7 @@ function isWorkerEvent(message) {
     case "fatal":
       return hasKeys(message, ["type", "error"]) && typeof message.error === "string";
     case "log":
-      return hasKeys(message, ["type", "text"]) && typeof message.text === "string";
+      return hasKeys(message, ["type", "stream", "text"]) && (message.stream === "stdout" || message.stream === "stderr") && typeof message.text === "string";
     case "response":
       return hasKeys(message, ["id", "type", "result"]) && Number.isSafeInteger(message.id) && isWasmResult(message.result);
     default:
@@ -72,8 +72,9 @@ var init_client = __esm({
     "use strict";
     init_protocol();
     HyperDBEngineClient = class {
-      constructor(transport, onSetupProgress) {
+      constructor(transport, onSetupProgress, onLog) {
         this.onSetupProgress = onSetupProgress;
+        this.onLog = onLog;
         this.transport = transport;
         this.readyPromise = new Promise((resolve, reject) => {
           this.resolveReady = resolve;
@@ -81,11 +82,12 @@ var init_client = __esm({
         });
         this.unsubscribe = [
           transport.onMessage((message) => this.onMessage(message)),
-          transport.onError((error) => this.fail(error)),
+          transport.onError((error) => this.failAndTerminate(error)),
           transport.onClose((error) => this.fail(error))
         ];
       }
       onSetupProgress;
+      onLog;
       transport;
       pending = /* @__PURE__ */ new Map();
       readyPromise;
@@ -93,10 +95,14 @@ var init_client = __esm({
       rejectReady;
       nextId = 1;
       failed;
+      termination;
       unsubscribe;
       ready() {
         return this.readyPromise;
       }
+      get failure() {
+        return this.failed;
+      }
       initialize(settings) {
         return this.request({ id: this.nextId++, type: "initialize", settings });
       }
@@ -131,8 +137,15 @@ var init_client = __esm({
         return this.request({ id: this.nextId++, type: "finishQuery", query });
       }
       async terminate() {
-        await this.transport.terminate();
-        this.fail(new Error("engine worker terminated"));
+        if (!this.termination) {
+          this.termination = Promise.resolve().then(() => this.transport.terminate()).then(() => {
+            this.fail(new Error("engine worker terminated"));
+          }, (error) => {
+            this.termination = void 0;
+            throw error;
+          });
+        }
+        await this.termination;
       }
       request(request, transfer = []) {
         if (this.failed) return Promise.reject(this.failed);
@@ -156,8 +169,15 @@ var init_client = __esm({
           this.onSetupProgress?.({ bytesLoaded: message.bytesLoaded, bytesTotal: message.bytesTotal });
           return;
         }
+        if (message.type === "log") {
+          try {
+            this.onLog?.(message.stream, message.text);
+          } catch {
+          }
+          return;
+        }
         if (message.type === "fatal") {
-          this.fail(new Error(message.error || "engine aborted"));
+          this.failAndTerminate(new Error(message.error || "engine aborted"));
           return;
         }
         if (message.type !== "response") return;
@@ -166,6 +186,10 @@ var init_client = __esm({
         this.pending.delete(message.id);
         pending.resolve(message.result);
       }
+      failAndTerminate(error) {
+        this.fail(error);
+        void this.terminate().catch(() => void 0);
+      }
       fail(error) {
         if (this.failed) return;
         this.failed = error;
@@ -234,7 +258,8 @@ function createBrowserClient(options = {}) {
   const engineUrl = options.engineUrl ?? new URL("./hyperdb-wasm.js", import.meta.url);
   return new HyperDBEngineClient(
     new BrowserWorker(new Worker(resolveBrowserWorkerUrl(workerUrl, engineUrl, options.wasmUrl, options.storagePath), { type: "classic" })),
-    options.onSetupProgress
+    options.onSetupProgress,
+    options.onLog
   );
 }
 var memory64Probe, threadsProbe, exceptionsProbe, tailCallsProbe, BrowserWorker;
@@ -591,25 +616,23 @@ var HyperDB = class _HyperDB {
   }
   async terminate() {
     if (this.terminated) return;
-    if (this.activeDatabaseOperations !== 0) throw new Error("database has an active operation");
+    if (this.activeDatabaseOperations !== 0 && !this.client.failure) throw new Error("database has an active operation");
     if (!this.termination) {
       this.termination = (async () => {
         try {
-          await Promise.all([...this.connections].map(async (connection) => connection.closeForTermination()));
-        } catch (error) {
-          this.termination = void 0;
-          throw error;
-        }
-        try {
-          expectOk(await this.client.shutdown(), "shutdown");
-        } catch (error) {
-          this.termination = void 0;
-          throw error;
-        }
-        for (const resource of this.mountedResources) resource.releaseAfterShutdown();
-        this.mountedResources.clear();
-        try {
+          if (!this.client.failure) {
+            try {
+              await Promise.all([...this.connections].map(async (connection) => connection.closeForTermination()));
+              expectOk(await this.client.shutdown(), "shutdown");
+            } catch (error) {
+              if (!this.client.failure) throw error;
+            }
+          }
           await this.client.terminate();
+          for (const connection of this.connections) connection.releaseAfterShutdown();
+          this.connections.clear();
+          for (const resource of this.mountedResources) resource.releaseAfterShutdown();
+          this.mountedResources.clear();
           this.terminated = true;
         } catch (error) {
           this.termination = void 0;
@@ -742,12 +765,17 @@ var HyperDBConnection = class {
     const result = {
       [Symbol.asyncIterator]() {
         return {
-          next() {
-            if (operation.aborted && !abortDelivered) {
-              abortDelivered = true;
-              return Promise.reject(operation.abortReason);
+          async next() {
+            try {
+              if (operation.aborted && !abortDelivered) {
+                abortDelivered = true;
+                throw operation.abortReason;
+              }
+              return await operation.interrupt(generator.next());
+            } catch (error) {
+              await generator.return(void 0);
+              throw error;
             }
-            return operation.interrupt(generator.next());
           },
           return(value) {
             return generator.return(value);
@@ -791,12 +819,14 @@ var HyperDBConnection = class {
     return queryPromise(result, stream.info);
   }
   query(sql, options = {}) {
-    const stream = this.queryStream(sql, options);
+    const stream = this.queryStreamIPC(sql, options);
     const result = (async () => {
-      const reader = await stream;
+      const reader = await RecordBatchReader.from(stream);
+      await reader.open();
+      const schema = reader.schema;
       const batches = [];
       for await (const batch of reader) batches.push(batch);
-      return new Table(reader.schema, batches);
+      return schema ? new Table(schema, batches) : new Table();
     })();
     return queryPromise(result, stream.info);
   }
@@ -821,6 +851,10 @@ var HyperDBConnection = class {
     if (this.active) throw new Error("cannot terminate while a connection has an active operation");
     await this.close();
   }
+  releaseAfterShutdown() {
+    this.closed = true;
+    this.onClose();
+  }
 };
 
 // src/index.ts

package/dist/browser_database_locks.d.ts

@@ -0,0 +1,11 @@
+import type { DatabaseLockBackend } from './database_locks.js';
+/** Paths must include the full OPFS path below /mnt/fs, including the configured storage directory */
+export declare class BrowserDatabaseLockBackend implements DatabaseLockBackend {
+    private readonly locks;
+    private readonly requests;
+    private nextToken;
+    private closed;
+    acquire(path: string, shared: boolean): Promise<number>;
+    release(token: number): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/browser_worker.js

@@ -145,20 +145,25 @@
       const pointer = safeInteger(this.invoke(request), "result pointer");
       const result = this.decodeResult(pointer);
       if (request.type === "shutdown" && result.state === "ok") {
-        this.mountedPaths.clear();
-        this.mountedDirectoryPaths.clear();
-        const completion = completionFor([
-          this.module.externalFileBackend?.shutdown(),
-          this.module.externalDirectoryBackend?.shutdown()
-        ]);
+        const completion2 = (async () => {
+          await this.module.hyperdbWasmDatabaseLocksDrain?.();
+          await this.module.databaseLockBackend?.close();
+          await Promise.all([
+            this.module.externalFileBackend?.shutdown(),
+            this.module.externalDirectoryBackend?.shutdown()
+          ]);
+          this.mountedPaths.clear();
+          this.mountedDirectoryPaths.clear();
+        })();
         return {
           response: { id: request.id, type: "response", result },
           transfer: [],
-          ...completion && { completion }
+          completion: completion2
         };
       }
       const response = { id: request.id, type: "response", result };
-      return { response, transfer: result.state === "chunk" ? [result.payload.buffer] : [] };
+      const completion = request.type === "disconnect" || request.type === "finishQuery" || request.type === "shutdown" ? this.module.hyperdbWasmDatabaseLocksDrain?.() : void 0;
+      return { response, transfer: result.state === "chunk" ? [result.payload.buffer] : [], ...completion && { completion } };
     }
     invoke(request) {
       switch (request.type) {
@@ -378,6 +383,29 @@
     }
   }
 
+  // src/database_locks.ts
+  var DatabaseLockConflictError = class extends Error {
+    constructor(path, options) {
+      super(`Database lock is already held: ${path}`, options);
+      this.name = "DatabaseLockConflictError";
+    }
+  };
+  function normalizeDatabaseLockPath(path) {
+    if (!path.startsWith("/") || path.endsWith("/") || path.includes("\0") || path.includes("\\")) {
+      throw new Error("Database lock path must be an absolute file path below /mnt/fs");
+    }
+    const segments = [];
+    for (const segment of path.split("/")) {
+      if (!segment || segment === ".") continue;
+      if (segment === "..") segments.pop();
+      else segments.push(segment);
+    }
+    if (segments[0] !== "mnt" || segments[1] !== "fs" || segments.length < 3) {
+      throw new Error("Database lock path must be an absolute file path below /mnt/fs");
+    }
+    return `/${segments.join("/")}`;
+  }
+
   // src/worker_setup.ts
   function errorText(error) {
     return error instanceof Error ? error.message : String(error);
@@ -455,11 +483,11 @@
         try {
           completeFetch(id, allocate(module, bytes), bytes.byteLength);
         } catch (error) {
-          transport.postMessage({ type: "log", text: `fetch failed: ${errorText(error)}` });
+          transport.postMessage({ type: "log", stream: "stderr", text: `fetch failed: ${errorText(error)}` });
           completeFetch(id, 0, -1);
         }
       }).catch(() => {
-        transport.postMessage({ type: "log", text: "fetch failed" });
+        transport.postMessage({ type: "log", stream: "stderr", text: "fetch failed" });
         completeFetch(id, 0, -1);
       });
     };
@@ -470,7 +498,7 @@
     if (!backend) return;
     module.hyperdbWasmExternalDirectoryReleaseGeneration = (locator, generation) => {
       void Promise.resolve().then(() => backend.releaseGeneration(locator, generation)).catch(() => {
-        transport.postMessage({ type: "log", text: "External directory generation cleanup failed; mount removal will retry" });
+        transport.postMessage({ type: "log", stream: "stderr", text: "External directory generation cleanup failed; mount removal will retry" });
       });
     };
     const listComplete = module._hyperdb_wasm_external_directory_list_complete;
@@ -603,10 +631,50 @@
       }).catch(() => complete(id, 0, -1));
     };
   }
+  function installDatabaseLockRuntime(module, fatal) {
+    const releases = /* @__PURE__ */ new Set();
+    const complete = (id, token, error) => {
+      if (!module._hyperdb_wasm_database_lock_complete) throw new Error("Database lock completion export is unavailable");
+      const status = error === void 0 ? 0 : error instanceof DatabaseLockConflictError ? 1 : 2;
+      const pointer = error === void 0 ? 0 : safePointer(module.stringToNewUTF8(errorText(error)), "database lock error pointer");
+      if (error !== void 0 && pointer === 0) throw new Error("Database lock error allocation failed");
+      module._hyperdb_wasm_database_lock_complete(id, token, status, pointer);
+    };
+    module.hyperdbWasmDatabaseLockAcquireStart = (id, path, shared) => {
+      void Promise.resolve().then(() => {
+        if (!module.databaseLockBackend) throw new Error("Host database locking is unavailable");
+        return module.databaseLockBackend.acquire(path, shared);
+      }).then((token) => complete(id, token), (error) => complete(id, 0, error)).catch((error) => fatal(`Database lock completion failed: ${errorText(error)}`));
+    };
+    module.hyperdbWasmDatabaseLockReleaseStart = (id, token) => {
+      const release = Promise.resolve().then(() => {
+        if (!module.databaseLockBackend) throw new Error("Host database locking is unavailable");
+        return module.databaseLockBackend.release(token);
+      }).then(() => {
+        if (id !== 0) complete(id, 0);
+      });
+      releases.add(release);
+      void release.then(() => releases.delete(release), (error) => fatal(`Database lock release failed: ${errorText(error)}`));
+    };
+    module.hyperdbWasmDatabaseLocksDrain = async () => {
+      while (releases.size) await Promise.all([...releases]);
+    };
+  }
   function configureWorker(module, transport, configureFilesystem = () => void 0) {
     const queuedRequests = [];
     let bindings;
+    let failed = false;
+    const fatal = (error) => {
+      if (failed) return;
+      failed = true;
+      try {
+        module.PThread?.terminateAllThreads();
+      } catch {
+      }
+      transport.postMessage({ type: "fatal", error });
+    };
     const handle = (request) => {
+      if (failed) return;
       if (!bindings) {
         queuedRequests.push(request);
         return;
@@ -614,37 +682,48 @@
       try {
         const result = bindings.handle(request);
         const complete = () => {
+          if (failed) return;
           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) } });
+        if (result.completion) void result.completion.then(complete).catch((error) => {
+          if (failed) return;
+          if (request.type === "shutdown" || request.type === "disconnect" || request.type === "finishQuery") {
+            fatal(`engine cleanup failed: ${errorText(error)}`);
+          } else {
+            transport.postMessage({ id: request.id, type: "response", result: { state: "error", error: errorText(error) } });
+          }
         });
         else complete();
       } catch (error) {
+        if (failed) return;
         transport.postMessage({ id: request.id, type: "response", result: { state: "error", error: errorText(error) } });
       }
     };
     transport.onMessage((message) => {
       if (isEngineRequest(message)) handle(message);
     });
-    module.print = (text) => transport.postMessage({ type: "log", text });
-    module.printErr = (text) => transport.postMessage({ type: "log", text });
+    module.print = (text) => transport.postMessage({ type: "log", stream: "stdout", text });
+    module.printErr = (text) => transport.postMessage({ type: "log", stream: "stderr", text });
     module.onRuntimeInitialized = () => {
+      if (failed) return;
       try {
         configureFilesystem(module);
         installHttpRuntime(module, transport);
         installHostFileRuntime(module);
         installExternalDirectoryRuntime(module, transport);
         installFilesystemProjectionRuntime(module);
+        installDatabaseLockRuntime(module, fatal);
         bindings = new HyperDBBindings(module);
         transport.postMessage({ type: "ready" });
         for (const request of queuedRequests.splice(0)) handle(request);
       } catch (error) {
-        transport.postMessage({ type: "fatal", error: `engine initialization failed: ${errorText(error)}` });
+        fatal(`engine initialization failed: ${errorText(error)}`);
       }
     };
-    module.onAbort = (reason) => transport.postMessage({ type: "fatal", error: `engine aborted: ${String(reason)}` });
+    module.onAbort = (reason) => {
+      fatal(`engine aborted: ${String(reason)}`);
+    };
   }
 
   // src/browser_external_directory.ts
@@ -960,6 +1039,64 @@
     }
   };
 
+  // src/browser_database_locks.ts
+  var BrowserDatabaseLockBackend = class {
+    locks = /* @__PURE__ */ new Map();
+    requests = /* @__PURE__ */ new Set();
+    nextToken = 1;
+    closed = false;
+    async acquire(path, shared) {
+      if (this.closed) throw new Error("Database lock backend is closed");
+      const normalized = normalizeDatabaseLockPath(path);
+      const manager = globalThis.navigator?.locks;
+      if (!manager || typeof manager.request !== "function") throw new Error("Database locking requires Web Locks");
+      if (this.nextToken > Number.MAX_SAFE_INTEGER) throw new Error("Database lock tokens exhausted");
+      const token = this.nextToken++;
+      return new Promise((resolve, reject) => {
+        let unlock;
+        const held = new Promise((resolveHeld) => {
+          unlock = resolveHeld;
+        });
+        const completion = manager.request(`hyperdb-wasm-database:${normalized}`, {
+          mode: shared ? "shared" : "exclusive",
+          ifAvailable: true
+        }, async (lock) => {
+          if (!lock) throw new DatabaseLockConflictError(normalized);
+          if (this.closed) throw new Error("Database lock backend is closed");
+          this.locks.set(token, { unlock, completion, releasing: false });
+          resolve(token);
+          await held;
+        });
+        this.requests.add(completion);
+        void completion.then(() => {
+          this.requests.delete(completion);
+        }, (error) => {
+          this.requests.delete(completion);
+          reject(error);
+        });
+      });
+    }
+    async release(token) {
+      const lock = this.locks.get(token);
+      if (!lock || lock.releasing) throw new Error("Unknown database lock token");
+      lock.releasing = true;
+      lock.unlock();
+      try {
+        await lock.completion;
+      } finally {
+        this.locks.delete(token);
+      }
+    }
+    async close() {
+      this.closed = true;
+      const releases = [...this.locks].map(([token, lock]) => lock.releasing ? lock.completion : this.release(token));
+      const results = await Promise.allSettled(releases);
+      await Promise.allSettled([...this.requests]);
+      const failures = results.filter((result) => result.status === "rejected").map((result) => result.reason);
+      if (failures.length) throw new AggregateError(failures, "Database lock cleanup failed");
+    }
+  };
+
   // 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";
@@ -1020,6 +1157,7 @@
     };
     self.Module = module;
     configureWorker(module, transport, (runtime) => {
+      runtime.databaseLockBackend = new BrowserDatabaseLockBackend();
       runtime.externalDirectoryBackend = new BrowserExternalDirectoryBackend();
       if (!runtime.OPFS) throw new Error("OPFS backend is unavailable");
       runtime.FS.mkdirTree("/mnt/fs");

package/dist/client.d.ts

@@ -2,6 +2,7 @@ import type { ConnectionSettings, HyperDBSettings, MountAccessMode } from './api
 import type { MountSource, SetupProgress, WasmResult, WorkerTransport } from './protocol.js';
 export declare class HyperDBEngineClient {
     private readonly onSetupProgress?;
+    private readonly onLog?;
     private readonly transport;
     private readonly pending;
     private readonly readyPromise;
@@ -9,9 +10,11 @@ export declare class HyperDBEngineClient {
     private rejectReady;
     private nextId;
     private failed;
+    private termination;
     private readonly unsubscribe;
-    constructor(transport: WorkerTransport, onSetupProgress?: ((progress: SetupProgress) => void) | undefined);
+    constructor(transport: WorkerTransport, onSetupProgress?: ((progress: SetupProgress) => void) | undefined, onLog?: ((stream: "stdout" | "stderr", text: string) => void) | undefined);
     ready(): Promise<void>;
+    get failure(): Error | undefined;
     initialize(settings: HyperDBSettings): Promise<WasmResult>;
     connect(settings?: ConnectionSettings): Promise<WasmResult>;
     disconnect(connection: number): Promise<WasmResult>;
@@ -26,5 +29,6 @@ export declare class HyperDBEngineClient {
     terminate(): Promise<void>;
     private request;
     private onMessage;
+    private failAndTerminate;
     private fail;
 }

package/dist/database_locks.d.ts

@@ -0,0 +1,15 @@
+/** Host ownership interface; browser workers coordinate, while Node callers provide exclusive access */
+export interface DatabaseLockBackend {
+    /** Returns a never-reused positive safe-integer token or rejects with DatabaseLockConflictError on contention */
+    acquire(path: string, shared: boolean): Promise<number>;
+    /** Releases a positive, backend-local token and waits for host ownership to end */
+    release(token: number): Promise<void>;
+    /** Stops acquisitions and releases all held locks; repeated closes are allowed */
+    close(): Promise<void>;
+}
+/** Identifies contention separately from host or filesystem failures */
+export declare class DatabaseLockConflictError extends Error {
+    constructor(path: string, options?: ErrorOptions);
+}
+/** Normalizes an absolute durable file path */
+export declare function normalizeDatabaseLockPath(path: string): string;