@cereusdb/standard 0.2.0 → 0.3.0

package/README.md

@@ -10,11 +10,15 @@ This package includes browser object stores for ranged remote Parquet reads and
 npm install @cereusdb/standard
 ```
 
+## Parquet support
+
+Parquet files compressed with Snappy, Gzip, Brotli, LZ4, or ZSTD can be registered.
+
 ## SQL function availability
 
 Current runtime surface:
 
-- `131` runtime `ST_*` names
+- `151` runtime `ST_*` names
 - `0` runtime `RS_*` names
 
 Included function families:
@@ -37,6 +41,20 @@ Not included in this package:
 
 Browser object stores are included in `@cereusdb/standard`. Use `registerObjectStores()` to configure `http`, `s3`, `gcs`, or `azure` providers, then `registerParquetTable()` to register an exact Parquet object or provider-backed prefix.
 
+## Loading the WASM module
+
+The wasm binary ships as a separate file, `dist/wasm/cereusdb_bg.wasm`. The default entry finds it automatically, and bundlers emit it as an asset.
+
+If you host the wasm yourself, or your bundler inlines assets into large `data:application/wasm;base64,...` strings, use the `external` entry. It has no built-in wasm reference and requires `wasmUrl` or `wasmSource`:
+
+```ts
+import { CereusDB } from '@cereusdb/standard/external';
+
+const db = await CereusDB.create({ wasmUrl: '/wasm/cereusdb_bg.wasm' });
+```
+
+Copy `node_modules/@cereusdb/standard/dist/wasm/cereusdb_bg.wasm` to your static assets, or import its URL with Vite: `import wasmUrl from '@cereusdb/standard/wasm?url'`. See the [WASM loading guide](https://github.com/tobilg/cereusdb/blob/main/packages/documentation/guides/wasm-loading.md) for details.
+
 ## JS / TS API
 
 Exports:

package/dist/external.d.ts

@@ -0,0 +1,98 @@
+export interface QueryResult {
+    /** Raw JSON data parsed from query */
+    data: Record<string, unknown>[];
+    /** Number of rows */
+    numRows: number;
+    /** Raw Arrow IPC bytes */
+    toIPC(): Uint8Array;
+    /** Convert to array of plain JS objects */
+    toJSON(): Record<string, unknown>[];
+}
+export interface CereusDBOptions {
+    /** Custom WASM module URL (for CDN hosting) */
+    wasmUrl?: string;
+    /** Preloaded WASM bytes/module for Node or custom loaders. */
+    wasmSource?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module | Promise<Response>;
+    /** Browser-backed object stores to register at startup. */
+    objectStores?: ObjectStoreRegistryConfig;
+}
+export type RasterFormat = 'geotiff' | 'tiff';
+export type ObjectStoreProvider = 'http' | 's3' | 'gcs' | 'azure';
+export interface ObjectStoreRegistryConfig {
+    /** Maximum concurrent browser fetches used by object_store. */
+    maxConcurrency?: number;
+    /** Stores registered by URL prefix. */
+    stores: ObjectStoreConfig[];
+}
+export interface ObjectStoreConfig {
+    /** Optional diagnostic name. */
+    name?: string;
+    /** Backing provider. */
+    provider: ObjectStoreProvider;
+    /** URL prefix, for example https://host, s3://bucket, gs://bucket. */
+    url: string;
+    /** Upstream object_store option keys and primitive values. */
+    options?: Record<string, string | number | boolean>;
+}
+export interface RegisterParquetTableOptions {
+    /** File extension used during listing discovery. Defaults to .parquet. */
+    fileExtension?: string;
+    /** Optional DataFusion target partition count. */
+    targetPartitions?: number;
+}
+export declare class CereusDB {
+    private inner;
+    private constructor();
+    /**
+     * Create and initialize a new CereusDB instance.
+     * This loads the WASM module and initializes the query engine.
+     */
+    static create(options?: CereusDBOptions): Promise<CereusDB>;
+    /**
+     * Execute a SQL query and return results as Arrow IPC bytes.
+     */
+    sql(query: string): Promise<Uint8Array>;
+    /**
+     * Execute a SQL query and return results as JSON.
+     */
+    sqlJSON(query: string): Promise<Record<string, unknown>[]>;
+    /**
+     * Register a remote Parquet file as a table.
+     * The server must support CORS.
+     */
+    registerRemoteParquet(name: string, url: string): Promise<void>;
+    /**
+     * Register browser-backed object stores for ranged and listing reads.
+     */
+    registerObjectStores(config: ObjectStoreRegistryConfig): void;
+    /**
+     * Register a remote Parquet object or prefix through DataFusion's listing table path.
+     */
+    registerParquetTable(name: string, url: string, options?: RegisterParquetTableOptions): Promise<void>;
+    /**
+     * Register a local file (from File API / drag-and-drop) as a table.
+     * Currently supports Parquet, GeoJSON, and GeoTIFF rasters.
+     */
+    registerFile(name: string, file: File): Promise<void>;
+    /**
+     * Register a GeoJSON object or string as a table.
+     */
+    registerGeoJSON(name: string, geojson: string | object): void;
+    /**
+     * Register a raster buffer as a single-column raster table.
+     * Requires the full GDAL-enabled package build.
+     */
+    registerRaster(name: string, data: BufferSource, format: RasterFormat): void;
+    /**
+     * Register a GeoTIFF buffer as a single-column raster table.
+     * Requires the full GDAL-enabled package build.
+     */
+    registerGeoTIFF(name: string, data: BufferSource): void;
+    /** Drop a table. */
+    dropTable(name: string): void;
+    /** List registered tables. */
+    tables(): string[];
+    /** Version string. */
+    version(): string;
+    private objectStoreApi;
+}

package/dist/external.js

@@ -0,0 +1,132 @@
+import init, { CereusDB as WasmCereusDB } from './wasm/cereusdb-external.js';
+function toUint8Array(data) {
+    if (ArrayBuffer.isView(data)) {
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    }
+    return new Uint8Array(data);
+}
+function normalizeRasterFormat(format) {
+    const normalized = format.trim().toLowerCase();
+    if (normalized === 'geotiff' || normalized === 'tiff') {
+        return normalized;
+    }
+    throw new Error(`Unsupported raster format: ${format}`);
+}
+export class CereusDB {
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /**
+     * Create and initialize a new CereusDB instance.
+     * This loads the WASM module and initializes the query engine.
+     */
+    static async create(options) {
+        const source = options?.wasmSource ?? options?.wasmUrl;
+        if (source === undefined) {
+            await init();
+        }
+        else {
+            await init({ module_or_path: source });
+        }
+        const inner = WasmCereusDB.create();
+        const db = new CereusDB(inner);
+        if (options?.objectStores !== undefined) {
+            db.registerObjectStores(options.objectStores);
+        }
+        return db;
+    }
+    /**
+     * Execute a SQL query and return results as Arrow IPC bytes.
+     */
+    async sql(query) {
+        return await this.inner.sql(query);
+    }
+    /**
+     * Execute a SQL query and return results as JSON.
+     */
+    async sqlJSON(query) {
+        const json = await this.inner.sql_json(query);
+        return JSON.parse(json);
+    }
+    /**
+     * Register a remote Parquet file as a table.
+     * The server must support CORS.
+     */
+    async registerRemoteParquet(name, url) {
+        await this.inner.register_remote_parquet(name, url);
+    }
+    /**
+     * Register browser-backed object stores for ranged and listing reads.
+     */
+    registerObjectStores(config) {
+        this.objectStoreApi().register_object_stores(config);
+    }
+    /**
+     * Register a remote Parquet object or prefix through DataFusion's listing table path.
+     */
+    async registerParquetTable(name, url, options = {}) {
+        await this.objectStoreApi().register_parquet_table(name, url, options);
+    }
+    /**
+     * Register a local file (from File API / drag-and-drop) as a table.
+     * Currently supports Parquet, GeoJSON, and GeoTIFF rasters.
+     */
+    async registerFile(name, file) {
+        const buffer = new Uint8Array(await file.arrayBuffer());
+        const ext = file.name.split('.').pop()?.toLowerCase();
+        if (ext === 'parquet' || ext === 'geoparquet') {
+            await this.inner.register_parquet_buffer(name, buffer);
+        }
+        else if (ext === 'geojson' || ext === 'json') {
+            const text = new TextDecoder().decode(buffer);
+            this.inner.register_geojson(name, text);
+        }
+        else if (ext === 'tif' || ext === 'tiff') {
+            this.registerRaster(name, buffer, 'geotiff');
+        }
+        else {
+            throw new Error(`Unsupported file format: .${ext}`);
+        }
+    }
+    /**
+     * Register a GeoJSON object or string as a table.
+     */
+    registerGeoJSON(name, geojson) {
+        const str = typeof geojson === 'string' ? geojson : JSON.stringify(geojson);
+        this.inner.register_geojson(name, str);
+    }
+    /**
+     * Register a raster buffer as a single-column raster table.
+     * Requires the full GDAL-enabled package build.
+     */
+    registerRaster(name, data, format) {
+        this.inner.register_raster_buffer(name, normalizeRasterFormat(format), toUint8Array(data));
+    }
+    /**
+     * Register a GeoTIFF buffer as a single-column raster table.
+     * Requires the full GDAL-enabled package build.
+     */
+    registerGeoTIFF(name, data) {
+        this.registerRaster(name, data, 'geotiff');
+    }
+    /** Drop a table. */
+    dropTable(name) {
+        this.inner.drop_table(name);
+    }
+    /** List registered tables. */
+    tables() {
+        return this.inner.tables();
+    }
+    /** Version string. */
+    version() {
+        return this.inner.version();
+    }
+    objectStoreApi() {
+        const api = this.inner;
+        if (typeof api.register_object_stores !== 'function' ||
+            typeof api.register_parquet_table !== 'function') {
+            throw new Error('Browser object stores are not available in this CereusDB build');
+        }
+        return api;
+    }
+}

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

@@ -0,0 +1,153 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Main CereusDB instance for browser use.
+ * Wraps a DataFusion SessionContext with spatial extensions registered.
+ */
+export class CereusDB {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Create a new CereusDB instance.
+     * Initializes DataFusion context and registers all spatial functions.
+     */
+    static create(): CereusDB;
+    /**
+     * Drop a registered table.
+     */
+    drop_table(table_name: string): void;
+    /**
+     * Register a GeoJSON string as a named table.
+     */
+    register_geojson(table_name: string, geojson: string): void;
+    /**
+     * Register a GeoTIFF buffer as a single-column raster table.
+     * Requires the full GDAL-enabled build.
+     */
+    register_geotiff_buffer(table_name: string, data: Uint8Array): void;
+    /**
+     * Register browser-backed object stores for ranged/listing reads.
+     */
+    register_object_stores(config: any): void;
+    /**
+     * Register a Uint8Array containing Parquet data as a named table.
+     * Use for files obtained via the browser File API.
+     */
+    register_parquet_buffer(table_name: string, data: Uint8Array): Promise<void>;
+    /**
+     * Register a remote Parquet object or prefix as a DataFusion listing table.
+     */
+    register_parquet_table(table_name: string, table_url: string, options: any): Promise<void>;
+    /**
+     * Register a raster buffer as a single-column raster table.
+     * Requires the full GDAL-enabled build.
+     */
+    register_raster_buffer(table_name: string, format: string, data: Uint8Array): void;
+    /**
+     * Register a remote Parquet file URL as a named table.
+     * Pre-fetches the entire file via HTTP, then loads into memory.
+     * The server must support CORS.
+     */
+    register_remote_parquet(table_name: string, url: string): Promise<void>;
+    /**
+     * Execute a SQL query.
+     * Returns results as Arrow IPC bytes (Uint8Array).
+     * The caller can decode this with the apache-arrow JS library.
+     */
+    sql(query: string): Promise<Uint8Array>;
+    /**
+     * Execute a SQL query and return results as a JSON string.
+     * Convenience method for simple use cases.
+     */
+    sql_json(query: string): Promise<string>;
+    /**
+     * List all registered table names.
+     */
+    tables(): any;
+    /**
+     * Get version information.
+     *
+     * Release builds set `CEREUSDB_VERSION` to the full npm version, including
+     * prerelease suffixes; other builds fall back to the crate version.
+     */
+    version(): string;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wasm_call_ctors: () => void;
+    readonly __libc_calloc: (a: number, b: number) => number;
+    readonly calloc: (a: number, b: number) => number;
+    readonly __libc_free: (a: number) => void;
+    readonly free: (a: number) => void;
+    readonly __libc_malloc: (a: number) => number;
+    readonly malloc: (a: number) => number;
+    readonly __wbg_cereusdb_free: (a: number, b: number) => void;
+    readonly _abort_js: () => void;
+    readonly cereusdb_create: () => [number, number, number];
+    readonly cereusdb_drop_table: (a: number, b: number, c: number) => [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];
+    readonly cereusdb_register_parquet_buffer: (a: number, b: number, c: number, d: number, e: number) => any;
+    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_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];
+    readonly cereusdb_version: (a: number) => [number, number];
+    readonly emscripten_builtin_malloc_usable_size: (a: number) => number;
+    readonly malloc_usable_size: (a: number) => number;
+    readonly emscripten_builtin_memalign: (a: number, b: number) => number;
+    readonly posix_memalign: (a: number, b: number, c: number) => number;
+    readonly realloc: (a: number, b: number) => number;
+    readonly abort: () => void;
+    readonly emscripten_builtin_free: (a: number) => void;
+    readonly emscripten_builtin_malloc: (a: number) => number;
+    readonly rust_zstd_wasm_shim_calloc: (a: number, b: number) => number;
+    readonly rust_zstd_wasm_shim_free: (a: number) => void;
+    readonly rust_zstd_wasm_shim_malloc: (a: number) => number;
+    readonly rust_zstd_wasm_shim_memcmp: (a: number, b: number, c: number) => number;
+    readonly rust_zstd_wasm_shim_memcpy: (a: number, b: number, c: number) => number;
+    readonly rust_zstd_wasm_shim_memmove: (a: number, b: number, c: number) => number;
+    readonly rust_zstd_wasm_shim_memset: (a: number, b: number, c: number) => number;
+    readonly rust_zstd_wasm_shim_qsort: (a: number, b: number, c: number, d: number) => void;
+    readonly __cpp_exception: WebAssembly.Tag;
+    readonly wasm_bindgen__closure__destroy__h8db467765ce434ac: (a: number, b: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h7573a8a64f443504: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h3bcc27440de746c0: (a: number, b: number, c: any, d: any) => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;