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

package/dist/api.d.ts

@@ -3,6 +3,7 @@ import type { AsyncRecordBatchStreamReader, TypeMap } from 'apache-arrow';
 import type { HyperDBEngineClient } from './client.js';
 import type { BrowserClientOptions } from './browser.js';
 import type { WasmResult } from './protocol.js';
+import type { HyperDBErrorSource } from './protocol.js';
 export interface HyperDBClient {
     ready(): Promise<void>;
     initialize(settings: string): Promise<WasmResult>;
@@ -16,12 +17,18 @@ export interface HyperDBClient {
     attachDatabase(connection: number, databaseName: string, alias: string): Promise<WasmResult>;
     detachDatabase(connection: number, alias: string): Promise<WasmResult>;
     startQuery(connection: number, sql: string): Promise<WasmResult>;
+    startQueryWithInfo(connection: number, sql: string): Promise<WasmResult>;
     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(path: string): Promise<WasmResult>;
+    registerExternalFile(name: string, url: string, size: number): Promise<WasmResult>;
+    registerExternalDirectory(handle: unknown, mode: 'read' | 'readwrite'): Promise<WasmResult>;
+    removeExternalRegistration(path: string): Promise<WasmResult>;
     pollQuery(query: number): Promise<WasmResult>;
     cancelQuery(query: number): Promise<WasmResult>;
     releaseQuery(query: number): Promise<WasmResult>;
+    releaseQueryWithInfo(query: number): Promise<WasmResult>;
     shutdown(): Promise<WasmResult>;
     terminate(): Promise<void>;
 }
@@ -31,8 +38,20 @@ export interface ArrowInsertOptions {
     readonly create?: boolean;
 }
 export interface DatabaseCreateOptions {
-    readonly storage?: 'memory' | 'persistent';
+    readonly storage?: 'transient' | 'persistent';
 }
+export interface ExternalFileRegistration {
+    readonly name: string;
+    readonly url: string;
+    readonly size: number;
+}
+export type ExternalDirectoryMode = 'read' | 'readwrite';
+export interface ExternalDirectoryRegistrationOptions {
+    readonly mode?: ExternalDirectoryMode;
+}
+type BrowserExternalFileArguments = readonly [name: string, url: string, size: number];
+type NodeExternalFileArguments = readonly [path: string];
+export type ExternalFileArguments = BrowserExternalFileArguments | NodeExternalFileArguments;
 export type HyperDBSettingValue = string | number | boolean | null | readonly HyperDBSettingValue[] | {
     readonly [key: string]: HyperDBSettingValue;
 };
@@ -43,11 +62,50 @@ export interface HyperDBCreateOptions {
 export type BrowserCreateOptions = BrowserClientOptions & HyperDBCreateOptions;
 export interface DatabaseMetadata {
     readonly name: string;
-    readonly storage: 'memory' | 'persistent';
+    readonly storage: 'transient' | 'persistent';
+}
+export type QueryMetricValue = null | boolean | number | string | readonly QueryMetricValue[] | {
+    readonly [key: string]: QueryMetricValue;
+};
+export type QueryMetrics = Readonly<Record<string, QueryMetricValue>>;
+export interface QueryTimings {
+    readonly elapsedSeconds: number | null;
+    readonly parsingSeconds: number | null;
+    readonly compilationSeconds: number | null;
+    readonly executionSeconds: number | null;
+    readonly commitSeconds: number | null;
+    readonly timeToScheduleSeconds: number | null;
+    readonly timeToFirstResultSeconds: number | null;
+    readonly cancellationSeconds: number | null;
+}
+export interface QueryInfo {
+    readonly status: 'succeeded' | 'failed' | 'canceled';
+    readonly started: boolean;
+    readonly statementKind: string | null;
+    readonly producesRows: boolean;
+    readonly rowCount: bigint | null;
+    readonly columnCount: number | null;
+    readonly cancellationRequestedByUser: boolean;
+    readonly queryPlan: Readonly<Record<string, unknown>> | null;
+    readonly dependencies: readonly string[];
+    readonly timings: QueryTimings;
+    readonly preExecutionMetrics: QueryMetrics | null;
+    readonly executionMetrics: QueryMetrics | null;
+}
+export interface QueryResult<Result> {
+    readonly result: Result;
+    readonly info: Promise<QueryInfo>;
+}
+export declare class HyperDBError extends Error {
+    readonly sqlState: string;
+    readonly errorSource: HyperDBErrorSource;
+    readonly detail: string;
+    readonly hint: string;
+    constructor(message: string, sqlState: string, errorSource: HyperDBErrorSource, detail?: string, hint?: string);
 }
 declare function initializeHyperDB(client: HyperDBClient, settings: HyperDBSettings | undefined): Promise<void>;
-export declare class HyperDB {
-    private readonly client;
+export declare class HyperDB<ExternalFileArgs extends ExternalFileArguments = BrowserExternalFileArguments> {
+    protected readonly client: HyperDBClient;
     private terminated;
     private termination;
     private activeDatabaseOperations;
@@ -59,11 +117,14 @@ export declare class HyperDB {
     createDatabase(databaseName: string, options?: DatabaseCreateOptions): Promise<void>;
     openDatabase(databaseName: string): Promise<void>;
     listDatabases(): Promise<DatabaseMetadata[]>;
+    registerExternalFile(...args: ExternalFileArgs): Promise<string>;
+    removeExternalRegistration(path: string): Promise<void>;
+    protected registerExternalDirectorySource(source: unknown, mode: ExternalDirectoryMode): Promise<string>;
     checkpointDatabase(databaseName: string): Promise<void>;
     dropDatabase(databaseName: string): Promise<void>;
     terminate(): Promise<void>;
     private ensureRunning;
-    private runDatabaseOperation;
+    protected runDatabaseOperation<Result>(operation: () => Promise<Result>): Promise<Result>;
 }
 export declare class HyperDBConnection {
     private readonly client;
@@ -76,19 +137,20 @@ export declare class HyperDBConnection {
     close(): Promise<void>;
     attachDatabase(databaseName: string, alias?: string): Promise<void>;
     detachDatabase(alias: string): Promise<void>;
-    sendIPC(sql: string): AsyncIterable<Uint8Array>;
-    queryIPC(sql: string): Promise<Uint8Array>;
+    sendIPC(sql: string): QueryResult<AsyncIterable<Uint8Array>>;
+    queryIPC(sql: string): QueryResult<Promise<Uint8Array>>;
     send<T extends TypeMap = {
         [key: string]: DataType;
-    }>(sql: string): Promise<AsyncRecordBatchStreamReader<T>>;
+    }>(sql: string): QueryResult<Promise<AsyncRecordBatchStreamReader<T>>>;
     query<T extends TypeMap = {
         [key: string]: DataType;
-    }>(sql: string): Promise<Table<T>>;
+    }>(sql: string): QueryResult<Promise<Table<T>>>;
     insertArrowTable(table: Table, options: ArrowInsertOptions): Promise<void>;
     insertArrowIPCFromPath(path: string, options: ArrowInsertOptions): Promise<void>;
     private insertArrowIPCFromPathInternal;
     private ensureAvailable;
     private release;
+    private releaseWithInfo;
     closeForTermination(): Promise<void>;
 }
 export type { HyperDBEngineClient };

package/dist/browser.js

@@ -32,12 +32,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) {
@@ -126,8 +130,11 @@ var init_client = __esm({
       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 });
@@ -139,6 +146,15 @@ var init_client = __esm({
       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 });
       }
@@ -148,6 +164,9 @@ var init_client = __esm({
       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"));
@@ -211,6 +230,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.");
   }
@@ -220,6 +245,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");
   }
@@ -245,7 +273,7 @@ function createBrowserClient(options = {}) {
     options.onSetupProgress
   );
 }
-var memory64Probe, threadsProbe, exceptionsProbe, BrowserWorker;
+var memory64Probe, threadsProbe, exceptionsProbe, tailCallsProbe, BrowserWorker;
 var init_browser = __esm({
   "src/browser.ts"() {
     "use strict";
@@ -253,6 +281,7 @@ var init_browser = __esm({
     memory64Probe = new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0, 5, 3, 1, 4, 1]);
     threadsProbe = new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0, 5, 4, 1, 3, 1, 1]);
     exceptionsProbe = new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0, 1, 4, 1, 96, 0, 0, 13, 3, 1, 0, 0]);
+    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]);
     BrowserWorker = class {
       constructor(worker) {
         this.worker = worker;
@@ -12123,7 +12152,72 @@ RecordBatchFileWriter["throughDOM"] = recordBatchWriterThroughDOMStream;
 RecordBatchStreamWriter["throughDOM"] = recordBatchWriterThroughDOMStream;
 
 // src/api.ts
+var HyperDBError = class extends Error {
+  sqlState;
+  errorSource;
+  detail;
+  hint;
+  constructor(message, sqlState, errorSource, detail = "", hint = "") {
+    super(message);
+    this.name = "HyperDBError";
+    this.sqlState = sqlState;
+    this.errorSource = errorSource;
+    this.detail = detail;
+    this.hint = hint;
+  }
+};
 var maxPersistentDatabaseNameLength = 200;
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  void promise.catch(() => void 0);
+  return { promise, resolve, reject };
+}
+function queryResult(result, info) {
+  return { result, info };
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function decodeQueryInfo(payload) {
+  const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(payload));
+  if (!isRecord2(value) || value.version !== 1) throw new Error("query information has an unsupported version");
+  if (value.status !== "succeeded" && value.status !== "failed" && value.status !== "canceled") throw new Error("query information has an invalid status");
+  if (typeof value.started !== "boolean" || typeof value.producesRows !== "boolean" || typeof value.cancellationRequestedByUser !== "boolean") {
+    throw new Error("query information has invalid flags");
+  }
+  if (value.statementKind !== null && typeof value.statementKind !== "string") throw new Error("query information has an invalid statement kind");
+  if (value.rowCount !== null && (typeof value.rowCount !== "string" || !/^\d+$/.test(value.rowCount))) throw new Error("query information has an invalid row count");
+  if (value.columnCount !== null && (!Number.isSafeInteger(value.columnCount) || value.columnCount < 0)) throw new Error("query information has an invalid column count");
+  if (value.queryPlan !== null && !isRecord2(value.queryPlan)) throw new Error("query information has an invalid query plan");
+  if (!Array.isArray(value.dependencies) || value.dependencies.some((dependency) => typeof dependency !== "string")) throw new Error("query information has invalid dependencies");
+  if (!isRecord2(value.timings)) throw new Error("query information has invalid timings");
+  const timingNames = ["elapsedSeconds", "parsingSeconds", "compilationSeconds", "executionSeconds", "commitSeconds", "timeToScheduleSeconds", "timeToFirstResultSeconds", "cancellationSeconds"];
+  for (const name of timingNames) {
+    const timing = value.timings[name];
+    if (timing !== null && (typeof timing !== "number" || !Number.isFinite(timing) || timing < 0)) throw new Error(`query information has an invalid ${name}`);
+  }
+  if (value.preExecutionMetrics !== null && !isRecord2(value.preExecutionMetrics)) throw new Error("query information has invalid pre-execution metrics");
+  if (value.executionMetrics !== null && !isRecord2(value.executionMetrics)) throw new Error("query information has invalid execution metrics");
+  return {
+    status: value.status,
+    started: value.started,
+    statementKind: value.statementKind,
+    producesRows: value.producesRows,
+    rowCount: value.rowCount === null ? null : BigInt(value.rowCount),
+    columnCount: value.columnCount,
+    cancellationRequestedByUser: value.cancellationRequestedByUser,
+    queryPlan: value.queryPlan,
+    dependencies: value.dependencies,
+    timings: value.timings,
+    preExecutionMetrics: value.preExecutionMetrics,
+    executionMetrics: value.executionMetrics
+  };
+}
 function normalizeArrowInsertOptions(options) {
   if (!options.name) throw new Error("Arrow insert table name must not be empty");
   return { name: options.name, schema: options.schema ?? null, create: options.create ?? true };
@@ -12172,7 +12266,11 @@ function readHandleFromResult(result, operation) {
   return new DataView(result.payload.buffer, result.payload.byteOffset, result.payload.byteLength).getUint32(0, true);
 }
 function readErrorFromResult(result, operation) {
-  if (result.state === "error" || result.state === "busy") return new Error(result.error);
+  if (result.state === "error") {
+    if (typeof result.error === "string") return new Error(result.error);
+    return new HyperDBError(result.error.message, result.error.sqlState, result.error.errorSource, result.error.detail, result.error.hint);
+  }
+  if (result.state === "busy") return new Error(result.error);
   return new Error(`${operation} returned unexpected state ${result.state}`);
 }
 function expectOk(result, operation) {
@@ -12206,7 +12304,7 @@ function readDatabasesFromResult(result) {
       throw invalidResult();
     }
     if (!name || name.includes("\0") || rawStorage !== 0 && rawStorage !== 1) throw invalidResult();
-    databases.push({ name, storage: rawStorage === 0 ? "memory" : "persistent" });
+    databases.push({ name, storage: rawStorage === 0 ? "transient" : "persistent" });
     offset += nameLength;
   }
   if (offset !== result.payload.byteLength) throw invalidResult();
@@ -12253,7 +12351,7 @@ var HyperDB = class _HyperDB {
   }
   async createDatabase(databaseName, options = {}) {
     validateDatabaseName(databaseName);
-    if (options.storage !== void 0 && options.storage !== "memory" && options.storage !== "persistent") {
+    if (options.storage !== void 0 && options.storage !== "transient" && options.storage !== "persistent") {
       throw new Error(`Unsupported database storage: ${String(options.storage)}`);
     }
     if (options.storage === "persistent") validatePersistentDatabaseName(databaseName);
@@ -12270,6 +12368,57 @@ var HyperDB = class _HyperDB {
   listDatabases() {
     return this.runDatabaseOperation(async () => readDatabasesFromResult(await this.client.listDatabases()));
   }
+  async registerExternalFile(...args) {
+    if (args.length === 1) {
+      const [sourcePath] = args;
+      if (!sourcePath) throw new Error("External file path must not be empty");
+      if (sourcePath.includes("\0")) throw new Error("External file path must not contain NUL");
+      return this.runDatabaseOperation(async () => {
+        const result = await this.client.registerExternalFile(sourcePath);
+        expectOk(result, "register external file");
+        const path = new TextDecoder("utf-8", { fatal: true }).decode(result.payload);
+        if (!/^\/mnt\/external\/[^/]+\/[^/]+$/.test(path)) throw new Error("register external file returned an invalid path");
+        return path;
+      });
+    }
+    const [name, url, size] = args;
+    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\/external\/[^/]+\/[^/]+$/.test(path)) throw new Error("register external file returned an invalid path");
+      return path;
+    });
+  }
+  async removeExternalRegistration(path) {
+    if (!path) throw new Error("External registration path must not be empty");
+    if (path.includes("\0")) throw new Error("External registration path must not contain null bytes");
+    await this.runDatabaseOperation(async () => {
+      expectOk(await this.client.removeExternalRegistration(path), "remove external registration");
+    });
+  }
+  registerExternalDirectorySource(source, mode) {
+    return this.runDatabaseOperation(async () => {
+      const result = await this.client.registerExternalDirectory(source, mode);
+      expectOk(result, "register external directory");
+      const path = new TextDecoder("utf-8", { fatal: true }).decode(result.payload);
+      if (!/^\/mnt\/external\/[^/]+\/[^/]+$/.test(path)) throw new Error("register external directory returned an invalid path");
+      return path;
+    });
+  }
   async checkpointDatabase(databaseName) {
     validateDatabaseName(databaseName);
     await this.runDatabaseOperation(async () => {
@@ -12374,89 +12523,111 @@ var HyperDBConnection = class {
   }
   sendIPC(sql) {
     const connection = this;
-    return {
-      async *[Symbol.asyncIterator]() {
+    const queryInfo = deferred();
+    const result = (async function* () {
+      let query;
+      let terminal = false;
+      let prefetched;
+      let acquired = false;
+      try {
         connection.ensureAvailable();
-        let query;
-        let terminal = false;
-        let prefetched;
-        try {
-          query = readHandleFromResult(await connection.client.startQuery(connection.connection, sql), "start query");
-          for (; ; ) {
-            let result = prefetched ? await prefetched : await connection.client.pollQuery(query);
-            prefetched = void 0;
-            while (result.state === "pending") {
-              await yieldToEventLoop();
-              result = await connection.client.pollQuery(query);
-            }
-            if (result.state === "chunk") {
-              prefetched = connection.client.pollQuery(query);
-              void prefetched.catch(() => void 0);
-              yield result.payload;
-              continue;
-            }
-            terminal = true;
-            if (result.state === "done") return;
-            throw readErrorFromResult(result, "poll query");
+        acquired = true;
+        query = readHandleFromResult(await connection.client.startQueryWithInfo(connection.connection, sql), "start query");
+        for (; ; ) {
+          let result2 = prefetched ? await prefetched : await connection.client.pollQuery(query);
+          prefetched = void 0;
+          while (result2.state === "pending") {
+            await yieldToEventLoop();
+            result2 = await connection.client.pollQuery(query);
           }
-        } finally {
-          try {
-            if (query !== void 0) {
-              let cleanupError;
-              if (prefetched) {
-                try {
-                  await prefetched;
-                } catch (error) {
-                  cleanupError = error;
-                }
-                prefetched = void 0;
-              }
-              if (!terminal) {
-                try {
-                  expectOk(await connection.client.cancelQuery(query), "cancel query");
-                } catch (error) {
-                  cleanupError ??= error;
-                }
+          if (result2.state === "chunk") {
+            prefetched = connection.client.pollQuery(query);
+            void prefetched.catch(() => void 0);
+            yield result2.payload;
+            continue;
+          }
+          terminal = true;
+          if (result2.state === "done") return;
+          throw readErrorFromResult(result2, "poll query");
+        }
+      } catch (error) {
+        if (query === void 0 || !terminal) queryInfo.reject(error);
+        throw error;
+      } finally {
+        try {
+          if (query !== void 0) {
+            let cleanupError;
+            let info;
+            if (prefetched) {
+              try {
+                await prefetched;
+              } catch (error) {
+                cleanupError = error;
               }
+              prefetched = void 0;
+            }
+            if (!terminal) {
               try {
-                await connection.release(query);
+                expectOk(await connection.client.cancelQuery(query), "cancel query");
               } catch (error) {
                 cleanupError ??= error;
               }
-              if (cleanupError) throw cleanupError;
             }
-          } finally {
-            connection.active = false;
+            try {
+              info = await connection.releaseWithInfo(query);
+            } catch (error) {
+              cleanupError ??= error;
+            }
+            if (cleanupError) {
+              queryInfo.reject(cleanupError);
+              throw cleanupError;
+            }
+            queryInfo.resolve(info);
           }
+        } finally {
+          if (acquired) connection.active = false;
         }
       }
-    };
-  }
-  async queryIPC(sql) {
-    const chunks = [];
-    let length = 0;
-    for await (const chunk of this.sendIPC(sql)) {
-      chunks.push(chunk);
-      length += chunk.byteLength;
-    }
-    const result = new Uint8Array(length);
-    let offset = 0;
-    for (const chunk of chunks) {
-      result.set(chunk, offset);
-      offset += chunk.byteLength;
-    }
-    return result;
-  }
-  async send(sql) {
-    const reader = await RecordBatchReader.from(this.sendIPC(sql));
-    if (!reader.isAsync() || !reader.isStream()) throw new Error("query did not produce an Arrow async stream");
-    return reader;
-  }
-  async query(sql) {
-    const reader = await this.send(sql);
-    const batches = [];
-    for await (const batch of reader) batches.push(batch);
-    return new Table(reader.schema, batches);
+    })();
+    return queryResult(result, queryInfo.promise);
+  }
+  queryIPC(sql) {
+    const stream = this.sendIPC(sql);
+    const result = (async () => {
+      const chunks = [];
+      let length = 0;
+      for await (const chunk of stream.result) {
+        chunks.push(chunk);
+        length += chunk.byteLength;
+      }
+      const bytes = new Uint8Array(length);
+      let offset = 0;
+      for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      return bytes;
+    })();
+    return queryResult(result, stream.info);
+  }
+  send(sql) {
+    const stream = this.sendIPC(sql);
+    const result = (async () => {
+      const reader = await RecordBatchReader.from(stream.result);
+      if (!reader.isAsync() || !reader.isStream()) throw new Error("query did not produce an Arrow async stream");
+      return reader;
+    })();
+    return queryResult(result, stream.info);
+  }
+  query(sql) {
+    const stream = this.send(sql);
+    const result = (async () => {
+      const reader = await stream.result;
+      const batches = [];
+      for await (const batch of reader) batches.push(batch);
+      return new Table(reader.schema, batches);
+    })();
+    return queryResult(result, stream.info);
   }
   async insertArrowTable(table, options) {
     this.ensureAvailable();
@@ -12520,12 +12691,54 @@ var HyperDBConnection = class {
       delay = Math.min(delay * 2, 32);
     }
   }
+  async releaseWithInfo(query) {
+    let delay = 1;
+    for (; ; ) {
+      const result = await this.client.releaseQueryWithInfo(query);
+      if (result.state === "ok") return decodeQueryInfo(result.payload);
+      if (result.state !== "pending") throw readErrorFromResult(result, "release query");
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      delay = Math.min(delay * 2, 32);
+    }
+  }
   async closeForTermination() {
     if (this.active) throw new Error("cannot terminate while a connection has an active operation");
     await this.close();
   }
 };
+
+// src/index.ts
+init_browser();
+var HyperDB2 = class _HyperDB extends HyperDB {
+  static async create(options = {}) {
+    const client = createBrowserClient(options);
+    const database = new _HyperDB(client);
+    try {
+      await database.ready();
+      await initializeHyperDB(client, options.settings);
+      return database;
+    } catch (error) {
+      try {
+        await client.terminate();
+      } catch {
+      }
+      throw error;
+    }
+  }
+  async registerExternalDirectory(handle, options = {}) {
+    const mode = options.mode ?? "read";
+    if (mode !== "read" && mode !== "readwrite") throw new Error(`Unsupported external directory mode: ${String(mode)}`);
+    if (!handle || handle.kind !== "directory" || typeof handle.queryPermission !== "function" || typeof handle.requestPermission !== "function") {
+      throw new Error("External directory handle must be a FileSystemDirectoryHandle");
+    }
+    let permission = await handle.queryPermission({ mode });
+    if (permission !== "granted") permission = await handle.requestPermission({ mode });
+    if (permission !== "granted") throw new Error(`External directory ${mode} permission was not granted`);
+    return this.registerExternalDirectorySource(handle, mode);
+  }
+};
 export {
-  HyperDB,
-  HyperDBConnection
+  HyperDB2 as HyperDB,
+  HyperDBConnection,
+  HyperDBError
 };

package/dist/browser_external_directory.d.ts

@@ -0,0 +1,30 @@
+import type { ExternalDirectoryBackend } from './wasm_bindings.js';
+export declare class BrowserExternalDirectoryBackend implements ExternalDirectoryBackend {
+    private readonly directories;
+    private readonly paths;
+    private readonly files;
+    private readonly writers;
+    register(handle: unknown, mode: 'read' | 'readwrite'): {
+        readonly name: string;
+        readonly locator: string;
+    };
+    registered(path: string, locator: string): void;
+    removed(pathOrLocator: string): void;
+    list(locator: string): Promise<readonly string[]>;
+    open(locator: string, path: string): Promise<{
+        readonly locator: string;
+        readonly size: number;
+    }>;
+    read(locator: string, offset: number, length: number, expectedSize: number): Promise<Uint8Array> | undefined;
+    createDirectories(locator: string, path: string): Promise<void>;
+    openWriter(writer: number, locator: string, path: string): Promise<void>;
+    write(writer: number, offset: number, bytes: Uint8Array): Promise<void>;
+    finish(writer: number, size: number): Promise<void>;
+    abort(writer: number): Promise<void>;
+    shutdown(): void;
+    private getDirectory;
+    private getWritableDirectory;
+    private getOpenWriter;
+    private cleanupWriter;
+    private enqueue;
+}