hyperdb-wasm 0.0.26862-dev.wasm.g8c0876f6 → 0.0.27000-dev.wasm.g0bde3882

package/dist/api.d.ts

@@ -2,28 +2,19 @@ import { DataType, Table } from 'apache-arrow';
 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 { MountSource, WasmResult } from './protocol.js';
 import type { HyperDBErrorSource } from './protocol.js';
 export interface HyperDBClient {
     ready(): Promise<void>;
     initialize(settings: string): Promise<WasmResult>;
     connect(): Promise<WasmResult>;
     disconnect(connection: number): Promise<WasmResult>;
-    createDatabase(databaseName: string, persistent: boolean): Promise<WasmResult>;
-    openDatabase(databaseName: string): Promise<WasmResult>;
-    listDatabases(): Promise<WasmResult>;
-    checkpointDatabase(databaseName: string): Promise<WasmResult>;
-    dropDatabase(databaseName: string): Promise<WasmResult>;
-    attachDatabase(connection: number, databaseName: string, alias: string): Promise<WasmResult>;
-    detachDatabase(connection: number, alias: string): Promise<WasmResult>;
     startQuery(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>;
+    mount(source: MountSource, path: string, mode: MountAccessMode): Promise<WasmResult>;
+    unmount(path: string): Promise<WasmResult>;
     pollQuery(query: number): Promise<WasmResult>;
     cancelQuery(query: number): Promise<WasmResult>;
     finishQuery(query: number): Promise<WasmResult>;
@@ -35,21 +26,16 @@ export interface ArrowInsertOptions {
     readonly schema?: string;
     readonly create?: boolean;
 }
-export interface DatabaseCreateOptions {
-    readonly storage?: 'transient' | 'persistent';
+export type MountAccessMode = 'read' | 'readwrite';
+export interface MountOptions {
+    readonly path: string;
+    readonly mode?: MountAccessMode;
 }
-export interface ExternalFileRegistration {
-    readonly name: string;
-    readonly url: string;
-    readonly size: number;
-}
-export type ExternalDirectoryMode = 'read' | 'readwrite';
-export interface ExternalDirectoryRegistrationOptions {
-    readonly mode?: ExternalDirectoryMode;
+export interface MountedResource {
+    readonly path: string;
+    close(): Promise<void>;
 }
-type BrowserExternalFileArguments = readonly [name: string, url: string, size: number];
-type NodeExternalFileArguments = readonly [path: string];
-export type ExternalFileArguments = BrowserExternalFileArguments | NodeExternalFileArguments;
+export declare function validateMountPath(path: unknown): asserts path is string;
 export type HyperDBSettingValue = string | number | boolean | null | readonly HyperDBSettingValue[] | {
     readonly [key: string]: HyperDBSettingValue;
 };
@@ -58,10 +44,6 @@ export interface HyperDBCreateOptions {
     readonly settings?: HyperDBSettings;
 }
 export type BrowserCreateOptions = BrowserClientOptions & HyperDBCreateOptions;
-export interface DatabaseMetadata {
-    readonly name: string;
-    readonly storage: 'transient' | 'persistent';
-}
 export type QueryMetricValue = null | boolean | number | string | readonly QueryMetricValue[] | {
     readonly [key: string]: QueryMetricValue;
 };
@@ -102,27 +84,22 @@ export declare class HyperDBError extends Error {
     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<ExternalFileArgs extends ExternalFileArguments = BrowserExternalFileArguments> {
+export declare class HyperDB {
     protected readonly client: HyperDBClient;
     private terminated;
     private termination;
     private activeDatabaseOperations;
     private readonly connections;
+    private readonly mountedResources;
     constructor(client: HyperDBClient);
     static create(options?: BrowserCreateOptions): Promise<HyperDB>;
     ready(): Promise<void>;
     connect(): Promise<HyperDBConnection>;
-    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>;
+    protected mountSource(source: MountSource, path: string, mode: MountAccessMode, cleanup?: () => void): Promise<MountedResource>;
     terminate(): Promise<void>;
     private ensureRunning;
     protected runDatabaseOperation<Result>(operation: () => Promise<Result>): Promise<Result>;
+    private unmount;
 }
 export declare class HyperDBConnection {
     private readonly client;
@@ -133,8 +110,6 @@ export declare class HyperDBConnection {
     private closing;
     constructor(client: HyperDBClient, connection: number, onClose?: () => void);
     close(): Promise<void>;
-    attachDatabase(databaseName: string, alias?: string): Promise<void>;
-    detachDatabase(alias: string): Promise<void>;
     sendIPC(sql: string): QueryResult<AsyncIterable<Uint8Array>>;
     queryIPC(sql: string): QueryResult<Promise<Uint8Array>>;
     send<T extends TypeMap = {

package/dist/browser.d.ts

@@ -11,6 +11,8 @@ export interface BrowserClientOptions {
     readonly workerUrl?: string | URL;
     readonly engineUrl?: string | URL;
     readonly wasmUrl?: string | URL;
+    /** OPFS-relative directory mounted as the durable filesystem root. */
+    readonly storagePath?: string;
     readonly onSetupProgress?: (progress: SetupProgress) => void;
 }
 type BrowserEnvironment = {
@@ -36,6 +38,6 @@ export declare class BrowserWorker implements WorkerTransport {
     onClose(): () => void;
     terminate(): void;
 }
-export declare function resolveBrowserWorkerUrl(workerUrl: string | URL, engineUrl: string | URL, wasmUrl?: string | URL): URL;
+export declare function resolveBrowserWorkerUrl(workerUrl: string | URL, engineUrl: string | URL, wasmUrl?: string | URL, storagePath?: string): URL;
 export declare function createBrowserClient(options?: BrowserClientOptions): HyperDBEngineClient;
 export {};

package/dist/browser.js

@@ -106,27 +106,6 @@ var init_client = __esm({
       disconnect(connection) {
         return this.request({ id: this.nextId++, type: "disconnect", connection });
       }
-      createDatabase(databaseName, persistent) {
-        return this.request({ id: this.nextId++, type: "createDatabase", databaseName, persistent });
-      }
-      openDatabase(databaseName) {
-        return this.request({ id: this.nextId++, type: "openDatabase", databaseName });
-      }
-      listDatabases() {
-        return this.request({ id: this.nextId++, type: "listDatabases" });
-      }
-      checkpointDatabase(databaseName) {
-        return this.request({ id: this.nextId++, type: "checkpointDatabase", databaseName });
-      }
-      dropDatabase(databaseName) {
-        return this.request({ id: this.nextId++, type: "dropDatabase", databaseName });
-      }
-      attachDatabase(connection, databaseName, alias) {
-        return this.request({ id: this.nextId++, type: "attachDatabase", connection, databaseName, alias });
-      }
-      detachDatabase(connection, alias) {
-        return this.request({ id: this.nextId++, type: "detachDatabase", connection, alias });
-      }
       shutdown() {
         return this.request({ id: this.nextId++, type: "shutdown" });
       }
@@ -143,14 +122,11 @@ 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 });
+      mount(source, path, mode) {
+        return this.request({ id: this.nextId++, type: "mount", source, path, mode });
       }
-      removeExternalRegistration(path) {
-        return this.request({ id: this.nextId++, type: "removeExternalRegistration", path });
+      unmount(path) {
+        return this.request({ id: this.nextId++, type: "unmount", path });
       }
       pollQuery(query) {
         return this.request({ id: this.nextId++, type: "pollQuery", query });
@@ -252,10 +228,11 @@ function assertBrowserSupport(environment = globalThis) {
     throw new Error("HyperDB cannot initialize because this browser does not support the origin-private file system");
   }
 }
-function resolveBrowserWorkerUrl(workerUrl, engineUrl, wasmUrl) {
+function resolveBrowserWorkerUrl(workerUrl, engineUrl, wasmUrl, storagePath) {
   const resolved = new URL(workerUrl);
   resolved.searchParams.set("engineUrl", new URL(engineUrl).href);
   if (wasmUrl != null) resolved.searchParams.set("wasmUrl", new URL(wasmUrl).href);
+  if (storagePath != null) resolved.searchParams.set("storagePath", storagePath);
   return resolved;
 }
 function createBrowserClient(options = {}) {
@@ -263,7 +240,7 @@ function createBrowserClient(options = {}) {
   const workerUrl = options.workerUrl ?? new URL("./browser_worker.js", import.meta.url);
   const engineUrl = options.engineUrl ?? new URL("./hyperdb-wasm.js", import.meta.url);
   return new HyperDBEngineClient(
-    new BrowserWorker(new Worker(resolveBrowserWorkerUrl(workerUrl, engineUrl, options.wasmUrl), { type: "classic" })),
+    new BrowserWorker(new Worker(resolveBrowserWorkerUrl(workerUrl, engineUrl, options.wasmUrl, options.storagePath), { type: "classic" })),
     options.onSetupProgress
   );
 }
@@ -12146,6 +12123,15 @@ RecordBatchFileWriter["throughDOM"] = recordBatchWriterThroughDOMStream;
 RecordBatchStreamWriter["throughDOM"] = recordBatchWriterThroughDOMStream;
 
 // src/api.ts
+function validateMountPath(path) {
+  if (typeof path !== "string" || !path.startsWith("/mnt/external/")) {
+    throw new Error("Mount path must be an absolute path below /mnt/external");
+  }
+  const relativePath = path.slice("/mnt/external/".length);
+  if (new TextEncoder().encode(relativePath).byteLength === 0 || new TextEncoder().encode(relativePath).byteLength > 200 || relativePath.split("/").some((component) => !component || component === "." || component === ".." || !/^[A-Za-z0-9._-]+$/.test(component))) {
+    throw new Error("Mount path below /mnt/external must be 1-200 bytes of slash-separated components containing ASCII letters, digits, '.', '-', or '_'");
+  }
+}
 var HyperDBError = class extends Error {
   sqlState;
   errorSource;
@@ -12160,7 +12146,6 @@ var HyperDBError = class extends Error {
     this.hint = hint;
   }
 };
-var maxPersistentDatabaseNameLength = 200;
 function deferred() {
   let resolve;
   let reject;
@@ -12216,26 +12201,6 @@ 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 };
 }
-function validateDatabaseName(databaseName) {
-  if (!databaseName) throw new Error("Database name must not be empty");
-  if (databaseName.includes("\0")) throw new Error("Database name must not contain NUL");
-}
-function validatePersistentDatabaseName(databaseName) {
-  validateDatabaseName(databaseName);
-  if (databaseName.length > maxPersistentDatabaseNameLength) {
-    throw new Error(`Persistent database name must be at most ${maxPersistentDatabaseNameLength} characters`);
-  }
-  if (!/^[a-z0-9][a-z0-9_-]*$/.test(databaseName)) {
-    throw new Error("Persistent database name must start with a lowercase ASCII letter or digit and contain only lowercase ASCII letters, digits, hyphens, and underscores");
-  }
-  if (/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/.test(databaseName)) {
-    throw new Error("Persistent database name is reserved by Windows");
-  }
-}
-function validateDatabaseAlias(alias) {
-  if (!alias) throw new Error("Database alias must not be empty");
-  if (alias.includes("\0")) throw new Error("Database alias must not contain NUL");
-}
 function materializeDictionaryColumns(table) {
   const dictionaryColumns = table.schema.fields.map((field, index) => DataType.isDictionary(field.type) ? index : -1).filter((index) => index !== -1);
   if (dictionaryColumns.length === 0) return table;
@@ -12276,37 +12241,46 @@ async function initializeHyperDB(client, settings) {
   if (serialized === void 0) throw new Error("HyperDB settings must be JSON-serializable");
   expectOk(await client.initialize(serialized), "initialize HyperDB settings");
 }
-function readDatabasesFromResult(result) {
-  expectOk(result, "list databases");
-  const invalidResult = () => new Error("list databases returned invalid metadata");
-  if (result.payload.byteLength < 4) throw invalidResult();
-  const view = new DataView(result.payload.buffer, result.payload.byteOffset, result.payload.byteLength);
-  const count = view.getUint32(0, true);
-  let offset = 4;
-  const databases = [];
-  const decoder2 = new TextDecoder("utf-8", { fatal: true });
-  for (let index = 0; index < count; ++index) {
-    if (offset + 8 > result.payload.byteLength) throw invalidResult();
-    const rawStorage = view.getUint32(offset, true);
-    const nameLength = view.getUint32(offset + 4, true);
-    offset += 8;
-    if (nameLength > result.payload.byteLength - offset) throw invalidResult();
-    let name;
-    try {
-      name = decoder2.decode(result.payload.subarray(offset, offset + nameLength));
-    } catch {
-      throw invalidResult();
-    }
-    if (!name || name.includes("\0") || rawStorage !== 0 && rawStorage !== 1) throw invalidResult();
-    databases.push({ name, storage: rawStorage === 0 ? "transient" : "persistent" });
-    offset += nameLength;
-  }
-  if (offset !== result.payload.byteLength) throw invalidResult();
-  return databases;
-}
 function yieldToEventLoop() {
   return new Promise((resolve) => setTimeout(resolve, 0));
 }
+var MountedResourceImpl = class {
+  constructor(path, unmount, cleanup) {
+    this.path = path;
+    this.unmount = unmount;
+    this.cleanup = cleanup;
+  }
+  path;
+  unmount;
+  cleanup;
+  closed = false;
+  closing;
+  cleaned = false;
+  async close() {
+    if (this.closed) return;
+    if (!this.closing) {
+      this.closing = (async () => {
+        try {
+          await this.unmount(this);
+        } catch (error) {
+          this.closing = void 0;
+          throw error;
+        }
+        this.release();
+      })();
+    }
+    await this.closing;
+  }
+  releaseAfterShutdown() {
+    this.release();
+  }
+  release() {
+    this.closed = true;
+    if (this.cleaned) return;
+    this.cleaned = true;
+    this.cleanup();
+  }
+};
 var HyperDB = class _HyperDB {
   constructor(client) {
     this.client = client;
@@ -12316,6 +12290,7 @@ var HyperDB = class _HyperDB {
   termination;
   activeDatabaseOperations = 0;
   connections = /* @__PURE__ */ new Set();
+  mountedResources = /* @__PURE__ */ new Set();
   static async create(options = {}) {
     const { createBrowserClient: createBrowserClient2 } = await Promise.resolve().then(() => (init_browser(), browser_exports));
     const client = createBrowserClient2(options);
@@ -12343,86 +12318,15 @@ var HyperDB = class _HyperDB {
     this.connections.add(result);
     return result;
   }
-  async createDatabase(databaseName, options = {}) {
-    validateDatabaseName(databaseName);
-    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);
-    await this.runDatabaseOperation(async () => {
-      expectOk(await this.client.createDatabase(databaseName, options.storage === "persistent"), "create database");
-    });
-  }
-  async openDatabase(databaseName) {
-    validatePersistentDatabaseName(databaseName);
-    await this.runDatabaseOperation(async () => {
-      expectOk(await this.client.openDatabase(databaseName), "open database");
-    });
-  }
-  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");
+  mountSource(source, path, mode, cleanup = () => void 0) {
     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 () => {
-      expectOk(await this.client.checkpointDatabase(databaseName), "checkpoint database");
-    });
-  }
-  async dropDatabase(databaseName) {
-    validateDatabaseName(databaseName);
-    await this.runDatabaseOperation(async () => {
-      expectOk(await this.client.dropDatabase(databaseName), "drop database");
+      const result = await this.client.mount(source, path, mode);
+      expectOk(result, "mount");
+      const mountedPath = new TextDecoder("utf-8", { fatal: true }).decode(result.payload);
+      if (mountedPath !== path) throw new Error("mount returned an invalid path");
+      const resource = new MountedResourceImpl(mountedPath, (mounted) => this.unmount(mounted), cleanup);
+      this.mountedResources.add(resource);
+      return resource;
     });
   }
   async terminate() {
@@ -12442,6 +12346,8 @@ var HyperDB = class _HyperDB {
           this.termination = void 0;
           throw error;
         }
+        for (const resource of this.mountedResources) resource.releaseAfterShutdown();
+        this.mountedResources.clear();
         try {
           await this.client.terminate();
           this.terminated = true;
@@ -12466,6 +12372,12 @@ var HyperDB = class _HyperDB {
       --this.activeDatabaseOperations;
     }
   }
+  async unmount(resource) {
+    await this.runDatabaseOperation(async () => {
+      expectOk(await this.client.unmount(resource.path), "unmount");
+      this.mountedResources.delete(resource);
+    });
+  }
 };
 var HyperDBConnection = class {
   constructor(client, connection, onClose = () => void 0) {
@@ -12496,25 +12408,6 @@ var HyperDBConnection = class {
     }
     await this.closing;
   }
-  async attachDatabase(databaseName, alias = databaseName) {
-    validateDatabaseName(databaseName);
-    validateDatabaseAlias(alias);
-    this.ensureAvailable();
-    try {
-      expectOk(await this.client.attachDatabase(this.connection, databaseName, alias), "attach database");
-    } finally {
-      this.active = false;
-    }
-  }
-  async detachDatabase(alias) {
-    validateDatabaseAlias(alias);
-    this.ensureAvailable();
-    try {
-      expectOk(await this.client.detachDatabase(this.connection, alias), "detach database");
-    } finally {
-      this.active = false;
-    }
-  }
   sendIPC(sql) {
     const connection = this;
     const queryInfo = deferred();
@@ -12709,16 +12602,35 @@ var HyperDB2 = class _HyperDB extends HyperDB {
       throw error;
     }
   }
-  async registerExternalDirectory(handle, options = {}) {
+  async mount(source, options) {
+    const path = options?.path;
+    validateMountPath(path);
+    if (typeof File !== "undefined" && source instanceof File) {
+      if (options.mode !== void 0 && options.mode !== "read") throw new Error("File mounts are always read-only");
+      if (!source.name) throw new Error("Mounted file name must not be empty");
+      if (source.name.includes("\0")) throw new Error("Mounted file name must not contain NUL");
+      if (source.name === "." || source.name === ".." || source.name.includes("/") || source.name.includes("\\")) {
+        throw new Error("Mounted file name must be a basename without path separators");
+      }
+      if (!Number.isSafeInteger(source.size) || source.size < 0) throw new Error("Mounted file size must be a nonnegative safe integer");
+      const url = URL.createObjectURL(source);
+      try {
+        return await this.mountSource({ kind: "browser-file", name: source.name, url, size: source.size }, path, "read", () => URL.revokeObjectURL(url));
+      } catch (error) {
+        URL.revokeObjectURL(url);
+        throw error;
+      }
+    }
+    const handle = source;
     const mode = options.mode ?? "read";
-    if (mode !== "read" && mode !== "readwrite") throw new Error(`Unsupported external directory mode: ${String(mode)}`);
+    if (mode !== "read" && mode !== "readwrite") throw new Error(`Unsupported mount 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");
+      throw new Error("Mount source must be a File or 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);
+    if (permission !== "granted") throw new Error(`Directory ${mode} permission was not granted`);
+    return this.mountSource({ kind: "browser-directory", handle }, path, mode);
   }
 };
 export {

package/dist/browser_external_directory.d.ts

@@ -1,4 +1,8 @@
 import type { ExternalDirectoryBackend } from './wasm_bindings.js';
+export type BrowserDirectoryEntry = {
+    readonly name: string;
+    readonly kind: 'file' | 'directory';
+};
 export declare class BrowserExternalDirectoryBackend implements ExternalDirectoryBackend {
     private readonly directories;
     private readonly paths;
@@ -11,6 +15,14 @@ export declare class BrowserExternalDirectoryBackend implements ExternalDirector
     registered(path: string, locator: string): void;
     removed(pathOrLocator: string): void;
     list(locator: string): Promise<readonly string[]>;
+    listEntries(locator: string, path: string): Promise<readonly BrowserDirectoryEntry[]>;
+    lookup(locator: string, path: string): Promise<{
+        readonly kind: 'directory';
+    } | {
+        readonly kind: 'file';
+        readonly locator: string;
+        readonly size: number;
+    } | undefined>;
     open(locator: string, path: string): Promise<{
         readonly locator: string;
         readonly size: number;
@@ -24,6 +36,7 @@ export declare class BrowserExternalDirectoryBackend implements ExternalDirector
     shutdown(): void;
     private getDirectory;
     private getWritableDirectory;
+    private openDirectory;
     private getOpenWriter;
     private cleanupWriter;
     private enqueue;