hyperdb-wasm 0.0.26845-dev.wasm.g5b622080 → 0.0.26861-dev.wasm.g004c5a60

package/dist/api.d.ts

@@ -2,28 +2,22 @@ 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(name: string, url: string, size: number): Promise<WasmResult>;
-    removeExternalFile(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>;
-    releaseQuery(query: number): Promise<WasmResult>;
+    finishQuery(query: number): Promise<WasmResult>;
     shutdown(): Promise<WasmResult>;
     terminate(): Promise<void>;
 }
@@ -32,14 +26,16 @@ export interface ArrowInsertOptions {
     readonly schema?: string;
     readonly create?: boolean;
 }
-export interface DatabaseCreateOptions {
-    readonly storage?: 'memory' | '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 interface MountedResource {
+    readonly path: string;
+    close(): Promise<void>;
 }
+export declare function validateMountPath(path: unknown): asserts path is string;
 export type HyperDBSettingValue = string | number | boolean | null | readonly HyperDBSettingValue[] | {
     readonly [key: string]: HyperDBSettingValue;
 };
@@ -48,31 +44,62 @@ export interface HyperDBCreateOptions {
     readonly settings?: HyperDBSettings;
 }
 export type BrowserCreateOptions = BrowserClientOptions & HyperDBCreateOptions;
-export interface DatabaseMetadata {
-    readonly name: string;
-    readonly storage: 'memory' | '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;
+    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(name: string, url: string, size: number): Promise<string>;
-    removeExternalFile(path: string): Promise<void>;
-    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;
-    private runDatabaseOperation;
+    protected runDatabaseOperation<Result>(operation: () => Promise<Result>): Promise<Result>;
+    private unmount;
 }
 export declare class HyperDBConnection {
     private readonly client;
@@ -83,21 +110,19 @@ 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): 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 finishQuery;
     closeForTermination(): Promise<void>;
 }
 export type { HyperDBEngineClient };

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 {};