@cereusdb/minimal 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# @cereusdb/minimal
+
+Smallest public CereusDB browser package. Includes the shared browser API, GEOS-backed spatial SQL, relation joins, distance joins, and `ST_KNN` in the current in-memory browser MVP.
+
+## Install
+
+```bash
+npm install @cereusdb/minimal
+```
+
+## SQL function availability
+
+Current runtime surface:
+
+- `130` runtime `ST_*` names
+- `0` runtime `RS_*` names
+
+Included function families:
+
+- Core SedonaDB scalar and aggregate functions from the pure-Rust runtime: constructors, WKT/WKB/EWKT/EWKB parsing, serializers, coordinate accessors, bounding-box helpers, SRID/CRS helpers, geometry properties, component access, affine transforms, and aggregates such as `ST_Collect_Agg`.
+- `geo` functions such as `ST_Area`, `ST_Length`, `ST_Perimeter`, `ST_Distance`, `ST_DWithin`, `ST_Buffer`, `ST_Centroid`, `ST_Intersects`, `ST_LineInterpolatePoint`, `ST_AsGeoJSON`, `ST_Intersection_Agg`, and `ST_Union_Agg`.
+- GEOS-backed predicates and operations such as `ST_Contains`, `ST_Within`, `ST_Covers`, `ST_CoveredBy`, `ST_Crosses`, `ST_Touches`, `ST_Overlaps`, `ST_Disjoint`, `ST_Equals`, `ST_Relate`, `ST_Intersection`, `ST_Union`, `ST_Difference`, `ST_SymDifference`, `ST_ConvexHull`, `ST_ConcaveHull`, `ST_Simplify`, `ST_Boundary`, `ST_UnaryUnion`, `ST_LineMerge`, `ST_Polygonize`, `ST_Snap`, `ST_MakeValid`, `ST_IsValid`, and `ST_IsValidReason`.
+- Spatial join MVP support for relation joins, distance joins, and `ST_KNN`.
+
+Not included in this package:
+
+- `ST_Transform`
+- S2 geography kernels
+- Raster `RS_*` functions
+
+## JS / TS API
+
+Exports:
+
+- `CereusDB`
+- `CereusDBOptions`
+- `RasterFormat`
+- `QueryResult`
+
+Main types:
+
+```ts
+type RasterFormat = 'geotiff' | 'tiff';
+
+interface CereusDBOptions {
+  wasmUrl?: string;
+  wasmSource?:
+    | RequestInfo
+    | URL
+    | Response
+    | BufferSource
+    | WebAssembly.Module
+    | Promise<Response>;
+}
+```
+
+Main API:
+
+```ts
+class CereusDB {
+  static create(options?: CereusDBOptions): Promise<CereusDB>;
+  sql(query: string): Promise<Uint8Array>;
+  sqlJSON(query: string): Promise<Record<string, unknown>[]>;
+  registerRemoteParquet(name: string, url: string): Promise<void>;
+  registerFile(name: string, file: File): Promise<void>;
+  registerGeoJSON(name: string, geojson: string | object): void;
+  registerRaster(name: string, data: BufferSource, format: RasterFormat): void;
+  registerGeoTIFF(name: string, data: BufferSource): void;
+  dropTable(name: string): void;
+  tables(): string[];
+  version(): string;
+}
+```
+
+API notes:
+
+- `sql()` returns Arrow IPC bytes as `Uint8Array`.
+- `sqlJSON()` returns parsed JSON rows.
+- `registerFile()` supports `.parquet`, `.geoparquet`, `.geojson`, and `.json` in this package.
+- `registerRaster()` and `registerGeoTIFF()` are part of the shared wrapper, but raster registration requires `@cereusdb/full`.
+
+## Example
+
+```ts
+import { CereusDB } from '@cereusdb/minimal';
+
+const db = await CereusDB.create();
+
+const rows = await db.sqlJSON(`
+  SELECT ST_AsText(ST_Buffer(ST_Point(0, 0), 1.0)) AS geom
+`);
+
+console.log(rows);
+```

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+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>;
+}
+export type RasterFormat = 'geotiff' | 'tiff';
+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 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;
+}

package/dist/index.js

@@ -0,0 +1,108 @@
+import init, { CereusDB as WasmCereusDB } from './wasm/cereusdb.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();
+        return new CereusDB(inner);
+    }
+    /**
+     * 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 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();
+    }
+}

package/dist/wasm/cereusdb.d.ts

@@ -0,0 +1,132 @@
+/* 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 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 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.
+     */
+    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_parquet_buffer: (a: number, b: number, c: number, d: number, e: number) => 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 __cpp_exception: WebAssembly.Tag;
+    readonly wasm_bindgen__closure__destroy__he74b42d6a982a3c3: (a: number, b: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__hf2284274f3d5489c: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h34d4f60983fa9e41: (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>;