@honua/sdk-js/geoparquet — a GeoParquet / DuckDB-WASM–backed Source.
The same protocol-neutral Query that runs against a FeatureServer or
an OGC API Features collection compiles here to DuckDB SQL over
read_parquet(...), with spatial predicate pushdown, and returns the same
Result envelope (GeoJSON features + schema). Overture's monthly
GeoParquet drops, single files, and hive-partitioned theme prefixes are all
addressable.
Why a separate entrypoint
The DuckDB WASM engine (@duckdb/duckdb-wasm, an optional peer) is multiple
megabytes and must never enter the static graph of /contract or /honua.
This module is that graph boundary: it is reached either by importing
@honua/sdk-js/geoparquet directly, or by handing geoparquetResolver
to createDataset({ resolveSource }). The @duckdb/duckdb-wasm peer itself
is only ever loaded through a dynamic import() inside the driver, so even
this entrypoint carries no static dependency edge to it.
Lifecycle & memory ceiling
A GeoparquetRuntime owns exactly one DuckDB instance and one Web
Worker, created lazily on first query and shared across every source it
backs. Call GeoparquetRuntime.dispose (or the dispose() on the
value returned by geoparquetResolver) when the owning client is torn
down to terminate the worker. DuckDB-WASM runs inside a single WASM linear
memory whose ceiling is ~4 GiB (32-bit addressing); in practice keep the
working set (scanned columns × matched rows, plus the spatial index) well
under ~2 GiB. Parquet footers / row-group metadata are cached per source-URL
set within the runtime; there is no on-disk persistence.
This entrypoint is not yet covered by the SDK's semver contract
— the surface may change in any minor release prior to 1.0.0.
@honua/sdk-js/geoparquet— a GeoParquet / DuckDB-WASM–backedSource.The same protocol-neutral Query that runs against a FeatureServer or an OGC API Features collection compiles here to DuckDB SQL over
read_parquet(...), with spatial predicate pushdown, and returns the same Result envelope (GeoJSON features + schema). Overture's monthly GeoParquet drops, single files, and hive-partitioned theme prefixes are all addressable.Why a separate entrypoint
The DuckDB WASM engine (
@duckdb/duckdb-wasm, an optional peer) is multiple megabytes and must never enter the static graph of/contractor/honua. This module is that graph boundary: it is reached either by importing@honua/sdk-js/geoparquetdirectly, or by handing geoparquetResolver tocreateDataset({ resolveSource }). The@duckdb/duckdb-wasmpeer itself is only ever loaded through a dynamicimport()inside the driver, so even this entrypoint carries no static dependency edge to it.Lifecycle & memory ceiling
A GeoparquetRuntime owns exactly one DuckDB instance and one Web Worker, created lazily on first query and shared across every source it backs. Call GeoparquetRuntime.dispose (or the
dispose()on the value returned by geoparquetResolver) when the owning client is torn down to terminate the worker. DuckDB-WASM runs inside a single WASM linear memory whose ceiling is ~4 GiB (32-bit addressing); in practice keep the working set (scanned columns × matched rows, plus the spatial index) well under ~2 GiB. Parquet footers / row-group metadata are cached per source-URL set within the runtime; there is no on-disk persistence.This entrypoint is not yet covered by the SDK's semver contract — the surface may change in any minor release prior to
1.0.0.