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

package/dist/api.d.ts

@@ -2,7 +2,7 @@ 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>;
@@ -13,10 +13,8 @@ export interface HyperDBClient {
     insertArrowIPCFromPath(connection: number, path: string, name: string, schema: string | null, create: boolean, internal?: boolean): Promise<WasmResult>;
     createTemporaryFile(bytes: Uint8Array): Promise<WasmResult>;
     removeFile(path: string): Promise<WasmResult>;
-    registerExternalFile(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>;
@@ -28,18 +26,16 @@ export interface ArrowInsertOptions {
     readonly schema?: string;
     readonly create?: boolean;
 }
-export interface ExternalFileRegistration {
-    readonly name: string;
-    readonly url: string;
-    readonly size: number;
+export type MountAccessMode = 'read' | 'readwrite';
+export interface MountOptions {
+    readonly path: string;
+    readonly mode?: MountAccessMode;
 }
-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;
 };
@@ -88,22 +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>;
-    registerExternalFile(...args: ExternalFileArgs): Promise<string>;
-    removeExternalRegistration(path: string): Promise<void>;
-    protected registerExternalDirectorySource(source: unknown, mode: ExternalDirectoryMode): Promise<string>;
+    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;

package/dist/browser.js

@@ -122,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 });
+      mount(source, path, mode) {
+        return this.request({ id: this.nextId++, type: "mount", source, path, mode });
       }
-      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 });
+      unmount(path) {
+        return this.request({ id: this.nextId++, type: "unmount", path });
       }
       pollQuery(query) {
         return this.request({ id: this.nextId++, type: "pollQuery", query });
@@ -12126,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;
@@ -12238,6 +12244,43 @@ async function initializeHyperDB(client, settings) {
 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;
@@ -12247,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);
@@ -12274,55 +12318,15 @@ var HyperDB = class _HyperDB {
     this.connections.add(result);
     return result;
   }
-  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;
+      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() {
@@ -12342,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;
@@ -12366,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) {
@@ -12590,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;