@cereusdb/minimal 0.3.0 → 0.4.0

package/dist/storage.js

@@ -0,0 +1,211 @@
+function splitPath(path) {
+    return path.split('/').filter((segment) => segment.length > 0);
+}
+function isNotFound(error) {
+    const name = error?.name;
+    return name === 'NotFoundError' || name === 'TypeMismatchError';
+}
+/**
+ * Keeps files in memory. Useful for tests, Node.js, and environments without
+ * OPFS. Share one instance between CereusDB instances to simulate a reload.
+ */
+export class MemoryStorageBackend {
+    constructor() {
+        this.files = new Map();
+        this.locks = new Set();
+    }
+    async readFile(path) {
+        const data = this.files.get(splitPath(path).join('/'));
+        return data ? data.slice() : null;
+    }
+    async writeFile(path, data) {
+        this.files.set(splitPath(path).join('/'), data.slice());
+    }
+    async remove(path) {
+        const key = splitPath(path).join('/');
+        for (const existing of [...this.files.keys()]) {
+            if (key === '' || existing === key || existing.startsWith(`${key}/`)) {
+                this.files.delete(existing);
+            }
+        }
+    }
+    async list(path) {
+        const prefix = splitPath(path).join('/');
+        const entries = new Set();
+        for (const key of this.files.keys()) {
+            if (prefix !== '' && !key.startsWith(`${prefix}/`)) {
+                continue;
+            }
+            const rest = prefix === '' ? key : key.slice(prefix.length + 1);
+            const [head, ...tail] = rest.split('/');
+            entries.add(tail.length > 0 ? `${head}/` : head);
+        }
+        return [...entries].sort();
+    }
+    async lock(name) {
+        if (this.locks.has(name)) {
+            throw new Error('it is already open in another CereusDB instance');
+        }
+        this.locks.add(name);
+    }
+    async unlock(name) {
+        this.locks.delete(name);
+    }
+    /** All stored file paths (for inspection and tests). */
+    paths() {
+        return [...this.files.keys()].sort();
+    }
+}
+/**
+ * Stores databases in the Origin Private File System (OPFS). Used for
+ * `opfs://` locations by default when the browser supports OPFS.
+ *
+ * Opening a database takes a Web Lock, so a database can be open in only one
+ * tab or worker at a time.
+ */
+export class OPFSStorageBackend {
+    constructor(options = {}) {
+        this.releases = new Map();
+        this.directory = options.directory ?? 'cereusdb';
+    }
+    /** Whether OPFS is available in the current environment. */
+    static isSupported() {
+        return (typeof navigator !== 'undefined' &&
+            typeof navigator.storage?.getDirectory === 'function');
+    }
+    root() {
+        this.rootPromise ?? (this.rootPromise = navigator.storage
+            .getDirectory()
+            .then((root) => root.getDirectoryHandle(this.directory, { create: true })));
+        return this.rootPromise;
+    }
+    async directoryHandle(segments, create) {
+        let directory = await this.root();
+        for (const segment of segments) {
+            try {
+                directory = await directory.getDirectoryHandle(segment, { create });
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+        }
+        return directory;
+    }
+    async readFile(path) {
+        const segments = splitPath(path);
+        const name = segments.pop();
+        if (name === undefined) {
+            return null;
+        }
+        const directory = await this.directoryHandle(segments, false);
+        if (directory === null) {
+            return null;
+        }
+        try {
+            const file = await (await directory.getFileHandle(name)).getFile();
+            return new Uint8Array(await file.arrayBuffer());
+        }
+        catch (error) {
+            if (isNotFound(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async writeFile(path, data) {
+        const segments = splitPath(path);
+        const name = segments.pop();
+        if (name === undefined) {
+            throw new Error('writeFile requires a file path');
+        }
+        const directory = await this.directoryHandle(segments, true);
+        if (directory === null) {
+            throw new Error(`cannot create directory for ${path}`);
+        }
+        const handle = await directory.getFileHandle(name, { create: true });
+        if (typeof handle.createWritable === 'function') {
+            // Writes go to a swap file that replaces the original on close().
+            const writable = await handle.createWritable();
+            try {
+                await writable.write(data);
+                await writable.close();
+            }
+            catch (error) {
+                await writable.abort().catch(() => undefined);
+                throw error;
+            }
+            return;
+        }
+        // Older Safari only supports synchronous access handles (in workers).
+        const createSyncAccessHandle = handle.createSyncAccessHandle;
+        if (typeof createSyncAccessHandle !== 'function') {
+            throw new Error('this browser cannot write OPFS files outside a worker');
+        }
+        const access = await createSyncAccessHandle.call(handle);
+        try {
+            access.truncate(0);
+            access.write(data, { at: 0 });
+            access.flush();
+        }
+        finally {
+            access.close();
+        }
+    }
+    async remove(path) {
+        const segments = splitPath(path);
+        const name = segments.pop();
+        if (name === undefined) {
+            throw new Error('remove requires a path');
+        }
+        const directory = await this.directoryHandle(segments, false);
+        if (directory === null) {
+            return;
+        }
+        try {
+            await directory.removeEntry(name, { recursive: true });
+        }
+        catch (error) {
+            if (!isNotFound(error)) {
+                throw error;
+            }
+        }
+    }
+    async list(path) {
+        const directory = await this.directoryHandle(splitPath(path), false);
+        if (directory === null) {
+            return [];
+        }
+        const entries = [];
+        const iterable = directory;
+        for await (const [name, handle] of iterable.entries()) {
+            entries.push(handle.kind === 'directory' ? `${name}/` : name);
+        }
+        return entries.sort();
+    }
+    async lock(name) {
+        if (typeof navigator === 'undefined' || navigator.locks === undefined) {
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            navigator.locks
+                .request(name, { ifAvailable: true }, (lock) => {
+                if (lock === null) {
+                    reject(new Error('it is open in another tab or worker'));
+                    return undefined;
+                }
+                resolve();
+                // Hold the lock until unlock() resolves this promise.
+                return new Promise((release) => this.releases.set(name, release));
+            })
+                .catch(reject);
+        });
+    }
+    async unlock(name) {
+        const release = this.releases.get(name);
+        this.releases.delete(name);
+        release?.();
+    }
+}

package/dist/wasm/cereusdb-external.d.ts

@@ -9,15 +9,65 @@ export class CereusDB {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Create (`create = true`) or attach a persistent database. Returns the
+     * database (catalog) name.
+     */
+    attach_database(location: string, name: string | null | undefined, create: boolean, if_not_exists: boolean): Promise<string>;
+    /**
+     * Describe all databases, schemas, tables and views as a JSON string.
+     */
+    catalog_json(): Promise<string>;
+    /**
+     * Rewrite every table of a persistent database into a single segment.
+     */
+    compact_database(name: string): Promise<void>;
     /**
      * Create a new CereusDB instance.
      * Initializes DataFusion context and registers all spatial functions.
      */
     static create(): CereusDB;
     /**
-     * Drop a registered table.
+     * Detach a persistent database after writing pending changes.
+     */
+    detach_database(name: string, if_exists: boolean): Promise<void>;
+    /**
+     * Drop a database by name or location URL. Persistent databases are
+     * deleted from storage.
+     */
+    drop_database(target: string, if_exists: boolean): Promise<void>;
+    /**
+     * Drop a registered table. Call `flush()` to write the change when the
+     * table belongs to a persistent database.
      */
     drop_table(table_name: string): void;
+    /**
+     * Run a query and encode the result as GeoParquet. `options` may set
+     * `compression` and `rowGroupSize`.
+     */
+    export_geoparquet(query: string, options: any): Promise<Uint8Array>;
+    /**
+     * Write all pending changes of attached persistent databases.
+     */
+    flush(): Promise<void>;
+    /**
+     * Insert Arrow IPC data (stream or file format) into a table, matching
+     * columns by name. Returns the number of inserted rows.
+     */
+    insert_arrow(table_name: string, data: Uint8Array): Promise<number>;
+    /**
+     * Database locations stored in the backend for `scheme`, attached or not.
+     */
+    list_database_locations(scheme: string): Promise<any>;
+    /**
+     * List all tables and views as `catalog.schema.table`.
+     */
+    qualified_tables(): any;
+    /**
+     * Set the function `(filename, bytes, mimeType)` that receives files
+     * written by `COPY ... TO`. `null` removes it.
+     */
+    register_export_handler(handler: any): void;
     /**
      * Register a GeoJSON string as a named table.
      */
@@ -51,6 +101,11 @@ export class CereusDB {
      * The server must support CORS.
      */
     register_remote_parquet(table_name: string, url: string): Promise<void>;
+    /**
+     * Register the storage backend used for database locations with the given
+     * URL scheme (for example `opfs`).
+     */
+    register_storage_backend(scheme: string, backend: any): void;
     /**
      * Execute a SQL query.
      * Returns results as Arrow IPC bytes (Uint8Array).
@@ -88,8 +143,19 @@ export interface InitOutput {
     readonly malloc: (a: number) => number;
     readonly __wbg_cereusdb_free: (a: number, b: number) => void;
     readonly _abort_js: () => void;
+    readonly cereusdb_attach_database: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => any;
+    readonly cereusdb_catalog_json: (a: number) => any;
+    readonly cereusdb_compact_database: (a: number, b: number, c: number) => any;
     readonly cereusdb_create: () => [number, number, number];
+    readonly cereusdb_detach_database: (a: number, b: number, c: number, d: number) => any;
+    readonly cereusdb_drop_database: (a: number, b: number, c: number, d: number) => any;
     readonly cereusdb_drop_table: (a: number, b: number, c: number) => [number, number];
+    readonly cereusdb_export_geoparquet: (a: number, b: number, c: number, d: any) => any;
+    readonly cereusdb_flush: (a: number) => any;
+    readonly cereusdb_insert_arrow: (a: number, b: number, c: number, d: number, e: number) => any;
+    readonly cereusdb_list_database_locations: (a: number, b: number, c: number) => any;
+    readonly cereusdb_qualified_tables: (a: number) => [number, number, number];
+    readonly cereusdb_register_export_handler: (a: number, b: any) => [number, number];
     readonly cereusdb_register_geojson: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly cereusdb_register_geotiff_buffer: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly cereusdb_register_object_stores: (a: number, b: any) => [number, number];
@@ -97,6 +163,7 @@ export interface InitOutput {
     readonly cereusdb_register_parquet_table: (a: number, b: number, c: number, d: number, e: number, f: any) => any;
     readonly cereusdb_register_raster_buffer: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
     readonly cereusdb_register_remote_parquet: (a: number, b: number, c: number, d: number, e: number) => any;
+    readonly cereusdb_register_storage_backend: (a: number, b: number, c: number, d: any) => [number, number];
     readonly cereusdb_sql: (a: number, b: number, c: number) => any;
     readonly cereusdb_sql_json: (a: number, b: number, c: number) => any;
     readonly cereusdb_tables: (a: number) => [number, number, number];