@urban-toolkit/autk-db 2.0.0

package/dist/raw-BpEIWqGM.js

@@ -0,0 +1,11 @@
+import { t as e } from "./basedecoder-DaTXO39b.js";
+//#region node_modules/geotiff/dist-module/compression/raw.js
+var t = class extends e {
+	decodeBlock(e) {
+		return e;
+	}
+};
+//#endregion
+export { t as default };
+
+//# sourceMappingURL=raw-BpEIWqGM.js.map

package/dist/raw-BpEIWqGM.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-BpEIWqGM.js","names":[],"sources":["../node_modules/geotiff/dist-module/compression/raw.js"],"sourcesContent":["import BaseDecoder from './basedecoder.js';\nexport default class RawDecoder extends BaseDecoder {\n    /** @param {ArrayBuffer} buffer */\n    decodeBlock(buffer) {\n        return buffer;\n    }\n}\n//# sourceMappingURL=raw.js.map"],"x_google_ignoreList":[0],"mappings":";;AACA,IAAqB,IAArB,cAAwC,EAAY;CAEhD,YAAY,GAAQ;AAChB,SAAO"}

package/dist/src/config/duckdb.d.ts

@@ -0,0 +1,8 @@
+import * as duckdb from '@duckdb/duckdb-wasm';
+/**
+ * Loads and instantiates a DuckDB database, with Node.js and browser support.
+ *
+ * @returns An instantiated `AsyncDuckDB` instance ready for connections.
+ * @throws If DuckDB WebAssembly fails to load or instantiate.
+ */
+export declare function loadDb(): Promise<duckdb.AsyncDuckDB>;

package/dist/src/main.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @module AutkDb
+ * Public entry point for the `@urban-toolkit/autk-db` package.
+ *
+ * Re-exports the spatial database class, table types, and OSM tag definitions.
+ */
+export type { LayerType, BoundingBox } from 'autk-core';
+export { PARKS_LEISURE_VALUES, PARKS_LANDUSE_VALUES, PARKS_NATURAL_VALUES, WATER_NATURAL_VALUES, WATER_FEATURE_VALUES, EXCLUDED_HIGHWAY_VALUES as EXCLUDED_ROAD_HIGHWAY_VALUES, EXCLUDED_BUILDING_VALUES, } from './shared/osm-tag-definitions';
+export type { Layer, LoadLayerParams } from './spatial/use-cases/load-layer/interfaces';
+export type { LoadGeoTiffParams } from './spatial/use-cases/load-geotiff';
+export type { CommonTable, Table, OsmTable, LayerTable, CustomLayerTable, CsvTable, JsonTable, AnyTable, GridLayerTable, GeoTiffTable, Column } from './shared/interfaces';
+export type { GetTableDataParams, GetTableDataOutput } from './spatial/use-cases/get-table-data';
+export type { LoadingPhase, OnLoadingProgress, OsmLoadTimings, LayerLoadTimings, LoadOsmParams } from './spatial/use-cases/load-osm-from-overpass-api/interfaces';
+export type { SpatialQueryParams, AggregateFunction } from './spatial/use-cases/spatial-join/interfaces';
+export type { BuildHeatmapParams, HeatmapAggregateFunction } from './spatial/use-cases/build-heatmap/interfaces';
+export type { LoadCsvParams } from './spatial/use-cases/load-csv/interfaces';
+export type { LoadCustomLayerParams } from './spatial/use-cases/load-custom-layer/interfaces';
+export type { LoadGridLayerParams } from './spatial/use-cases/load-grid-layer/LoadGridLayerUseCase';
+export type { LoadJsonParams } from './spatial/use-cases/load-json/interfaces';
+export type { RawQueryParams, RawQueryOutput } from './spatial/use-cases/raw-query/interfaces';
+export type { UpdateTableParams, UpdateStrategy } from './spatial/use-cases/update-table/interfaces';
+export * from './spatial';

package/dist/src/shared/HttpCache.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Simple HTTP cache using Browser Cache API with TTL support
+ */
+export declare class HttpCache<T = any> {
+    private cache;
+    private readonly cacheName;
+    private readonly ttl;
+    /**
+     * Creates an HTTP cache with the given name and TTL.
+     *
+     * @param cacheName Name of the cache storage.
+     * @param ttl Time to live in milliseconds (default: 24 hours).
+     * @throws Never throws.
+     */
+    constructor(cacheName: string, ttl?: number);
+    /**
+     * Initializes the Cache API storage if available.
+     *
+     * @throws Never throws. Failures leave the cache as `null`.
+     */
+    private init;
+    /**
+     * Returns cached data for a key, or `null` if missing or expired.
+     *
+     * @param key Cache key to look up.
+     * @returns Cached data or `null`.
+     * @throws Never throws. Errors are caught and return `null`.
+     */
+    get(key: string): Promise<T | null>;
+    private toRequest;
+    /**
+     * Stores data in the cache with a current timestamp.
+     *
+     * @param key Cache key to store under.
+     * @param data Value to cache.
+     * @returns Nothing.
+     * @throws Never throws. Errors are silently caught.
+     */
+    set(key: string, data: T): Promise<void>;
+    /**
+     * Deletes a specific key from the cache.
+     *
+     * @param key Cache key to remove.
+     * @returns Nothing.
+     * @throws Never throws. Errors are silently caught.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clears all items from this cache.
+     *
+     * @returns Nothing.
+     * @throws Never throws. Errors are silently caught.
+     */
+    clear(): Promise<void>;
+}

package/dist/src/shared/clusterIntersectingFeatures.d.ts

@@ -0,0 +1,11 @@
+import { Geometry } from 'geojson';
+/**
+ * Computes connected components (clusters) of intersecting geometries and returns
+ * a mapping from feature id to cluster id. The input array must contain an
+ * application-level identifier for each geometry. Cluster ids are stable only
+ * within a single invocation and start at 0.
+ */
+export declare function computeIntersectingClusterIds(items: Array<{
+    id: number | string;
+    geometry: Geometry | null | undefined;
+}>): Map<string, number>;

package/dist/src/shared/consts.d.ts

@@ -0,0 +1,4 @@
+/** Default coordinate reference system used for spatial operations. */
+export declare const DEFALT_COORDINATE_FORMAT = "EPSG:4326";
+/** Default geometry column name for point-based tables. */
+export declare const DEFAULT_GEO_COLUMN_NAME = "geoPoint";

package/dist/src/shared/interfaces.d.ts

@@ -0,0 +1,44 @@
+import { LayerType, BoundingBox } from 'autk-core';
+export type { BoundingBox };
+export { PARKS_LEISURE_VALUES, PARKS_LANDUSE_VALUES, PARKS_NATURAL_VALUES, WATER_NATURAL_VALUES, WATER_FEATURE_VALUES, EXCLUDED_HIGHWAY_VALUES as EXCLUDED_ROAD_HIGHWAY_VALUES, EXCLUDED_BUILDING_VALUES, } from './osm-tag-definitions';
+export type GridLayerTable = CommonTable & {
+    source: 'user';
+    type: LayerType;
+};
+export type GeoTiffTable = CommonTable & {
+    source: 'geotiff';
+    type: 'raster';
+};
+export type Table = OsmTable | LayerTable | CsvTable | JsonTable | CustomLayerTable | GridLayerTable | GeoTiffTable | AnyTable;
+export type OsmTable = CommonTable & {
+    source: 'osm';
+    type: 'pointset';
+};
+export type LayerTable = CommonTable & {
+    source: 'osm';
+    type: LayerType;
+};
+export type CustomLayerTable = CommonTable & {
+    source: 'geojson';
+    type: LayerType;
+};
+export type CsvTable = CommonTable & {
+    source: 'csv';
+    type: 'pointset';
+};
+export type JsonTable = CommonTable & {
+    source: 'json';
+    type: 'pointset';
+};
+export type AnyTable = CommonTable & {
+    source: 'user';
+    type: 'pointset';
+};
+export interface CommonTable {
+    name: string;
+    columns: Column[];
+}
+export interface Column {
+    name: string;
+    type: string;
+}

package/dist/src/shared/osm-tag-definitions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OSM tag value definitions used across Overpass queries and layer classification.
+ *
+ * Centralized here so both the Overpass query builder and the SQL layer filters
+ * reference the same source of truth.
+ */
+export declare const PARKS_LEISURE_VALUES: readonly ["dog_park", "park", "playground", "recreation_ground"];
+export declare const PARKS_LANDUSE_VALUES: readonly ["wood", "grass", "forest", "orchard", "village_green", "vineyard", "cemetery", "meadow"];
+export declare const PARKS_NATURAL_VALUES: readonly ["wood", "grass", "grassland", "forest", "scrub", "heath", "meadow"];
+export declare const WATER_NATURAL_VALUES: readonly ["water", "wetland", "strait", "spring"];
+export declare const WATER_FEATURE_VALUES: readonly ["pond", "reservoir", "lagoon", "stream_pool", "lake", "pool", "canal", "river"];
+export declare const EXCLUDED_HIGHWAY_VALUES: readonly ["cycleway", "elevator", "footway", "steps", "pedestrian", "proposed", "construction", "abandoned", "platform", "raceway"];
+export declare const EXCLUDED_BUILDING_VALUES: readonly ["shed", "garage", "garages", "carport", "hut", "kiosk", "toilets", "service", "transformer_tower", "sty", "container"];

package/dist/src/spatial/SpatialDb.d.ts

@@ -0,0 +1,264 @@
+import { CsvTable, CustomLayerTable, LayerTable, JsonTable, Table, BoundingBox, GridLayerTable, GeoTiffTable } from '../shared/interfaces';
+import { LoadLayerParams } from './use-cases/load-layer';
+import { LoadCsvParams } from './use-cases/load-csv';
+import { LoadJsonParams } from './use-cases/load-json';
+import { FeatureCollection } from 'geojson';
+import { LoadCustomLayerParams } from './use-cases/load-custom-layer';
+import { SpatialQueryParams } from './use-cases/spatial-join/interfaces';
+import { LoadOsmParams } from './use-cases/load-osm-from-overpass-api';
+import { OsmLoadTimings } from './use-cases/load-osm-from-overpass-api/interfaces';
+import { LoadGridLayerParams } from './use-cases/load-grid-layer/LoadGridLayerUseCase';
+import { LoadGeoTiffParams } from './use-cases/load-geotiff';
+import { RawQueryOutput, RawQueryParams } from './use-cases/raw-query/interfaces';
+import { BuildHeatmapParams } from './use-cases/build-heatmap';
+import { GetTableDataParams, GetTableDataOutput } from './use-cases/get-table-data';
+import { UpdateTableParams } from './use-cases/update-table';
+/**
+ * SpatialDb class provides methods to interact with a DuckDB database for spatial data operations.
+ *
+ * It allows loading OSM data, CSV, JSON, custom layers, and grid layers,
+ * as well as performing spatial joins and raw queries.
+ * DuckDB-backed spatial database for OSM, CSV, JSON, and raster data.
+ *
+ * Supports multiple isolated workspaces, each with its own schema and tables.
+ *
+ * @example
+ * const db = new AutkSpatialDb();
+ * await db.init();
+ * const layer = await db.getLayer('osm_buildings');
+ */
+export declare class AutkSpatialDb {
+    private db?;
+    private conn?;
+    private currentWorkspace;
+    private workspaces;
+    get tables(): Array<Table>;
+    private osmProcessingPipeline?;
+    private loadOsmFromOverpassApiUseCase?;
+    private loadOsmFromPbfUseCase?;
+    private loadCsvUseCase?;
+    private loadLayerUseCase?;
+    private loadCustomLayerUseCase?;
+    private assignBuildingIdsUseCase?;
+    private loadJsonUseCase?;
+    private getLayerGeojsonUseCase?;
+    private spatialJoinUseCase?;
+    private getBoundingBoxFromLayerUseCase?;
+    private dropTableUseCase?;
+    private transformBoundingBoxCoordinatesUseCase?;
+    private loadGridLayerUseCase?;
+    private loadGeoTiffUseCase?;
+    private rawQueryUseCase?;
+    private getBoundingBoxFromOsmUseCase?;
+    private polygonizeSurfaceLayerUseCase?;
+    private buildHeatmapUseCase?;
+    private getTableDataUseCase?;
+    private updateTableUseCase?;
+    /**
+     * Gets the workspace data for the current workspace.
+     * @returns The WorkspaceData for the current workspace.
+     * @private
+     */
+    private getCurrentWorkspaceData;
+    /**
+     * Initializes DuckDB, loads the spatial extension, and creates use-case instances.
+     *
+     * @returns A promise that resolves when initialization is complete.
+     * @throws If DuckDB WebAssembly fails to load or the spatial extension cannot be installed.
+     * @example
+     * await db.init();
+     */
+    init(): Promise<void>;
+    /**
+     * Switches to a workspace, creating it if it doesn't exist.
+     *
+     * @param name The name of the workspace to switch to.
+     * @returns A promise that resolves when the workspace is set.
+     * @throws If the database has not been initialized.
+     */
+    setWorkspace(name: string): Promise<void>;
+    /**
+     * Gets the list of all available workspaces.
+     * @returns An array of workspace names.
+     */
+    getWorkspaces(): string[];
+    /**
+     * Gets the name of the current active workspace.
+     * @returns The current workspace name.
+     */
+    getCurrentWorkspace(): string;
+    /**
+     * Registers a table in the current workspace's tables array. If a table with the same name already exists,
+     * it will be replaced and a warning will be logged to the console.
+     * @param table - The table to register.
+     */
+    private _registerTable;
+    private clipLayerToSurface;
+    /**
+     * Loads OSM data from the Overpass API and optionally loads layers based on the provided parameters.
+     * When autoLoadLayers is enabled, this method will automatically extract and process specific layers
+     * (e.g., buildings, roads, surface) from the OSM data, and optionally polygonize the surface layer.
+     *
+     * @param params - Parameters for loading OSM data and layers.
+     * @returns A promise that resolves when the OSM data and layers are fully loaded.
+     * @throws Error if the database or connection is not initialized.
+     */
+    loadOsm(params: LoadOsmParams): Promise<OsmLoadTimings>;
+    /**
+     * Loads a CSV file into the database and returns the created CsvTable.
+     * @param params - Parameters for loading the CSV file, including file path and table name.
+     * @returns A promise that resolves to the created CsvTable.
+     * @throws Error if the database or connection is not initialized.
+     */
+    loadCsv(params: LoadCsvParams): Promise<CsvTable>;
+    /**
+     * Loads a JSON file into the database and returns the created JsonTable.
+     * @param params - Parameters for loading the JSON file, including file path and table name.
+     * @returns A promise that resolves to the created JsonTable.
+     * @throws Error if the database or connection is not initialized.
+     */
+    loadJson(params: LoadJsonParams): Promise<JsonTable>;
+    /**
+     * Loads a layer from an OSM input table and returns the created LayerTable.
+     * @param params - Parameters for loading the layer.
+     * @returns A promise that resolves to the created LayerTable.
+     * @throws Error if the database or connection is not initialized.
+     * @throws Error if the OSM input table is not found or is not of the correct type.
+     */
+    loadLayer(params: LoadLayerParams): Promise<LayerTable>;
+    /**
+     * Loads a custom layer from a GeoJSON file and returns the created CustomLayerTable.
+     * If OSM bounding box is available, it will be automatically applied to crop the layer.
+     * @param params - Parameters for loading the custom layer, including file path, table name, and layer type.
+     * @returns A promise that resolves to the created CustomLayerTable.
+     * @throws Error if the database or connection is not initialized.
+     */
+    loadCustomLayer(params: LoadCustomLayerParams): Promise<CustomLayerTable>;
+    /**
+     * Loads a grid layer and returns the created GridLayerTable.
+     * If no bounding box is provided in params, the OSM bounding box will be used if available.
+     * @param params - Parameters for loading the grid layer, including grid size, cell size, and optional bounding box.
+     * @returns A promise that resolves to the created GridLayerTable.
+     * @throws Error if the database or connection is not initialized.
+     */
+    loadGridLayer(params: LoadGridLayerParams): Promise<GridLayerTable>;
+    /**
+     * Loads a GeoTIFF raster file into the database.
+     * Uses DuckDB's spatial extension (GDAL-backed ST_Read) to parse the file.
+     * The resulting table has a `geometry` column (cell centroids) and a
+     * `properties` struct column containing one field per raster band.
+     * @param params - Parameters including the file URL or ArrayBuffer, output table name,
+     *   and optional coordinate transformation settings.
+     * @returns A promise that resolves to the created GeoTiffTable.
+     */
+    loadGeoTiff(params: LoadGeoTiffParams): Promise<GeoTiffTable>;
+    /**
+     * Retrieves a loaded GeoTIFF table as a FeatureCollection suitable for rendering with autk-map.
+     *
+     * The returned collection has a single feature whose `properties.raster` is an array of per-pixel
+     * property objects (one per cell, in row-major top-to-bottom order), plus `rasterResX` / `rasterResY`
+     * dimensions and a `bbox`.
+     *
+     * Pass the result directly to `AutkMap.loadRasterCollection()` and supply a `property` callback that
+     * extracts the numeric band value you want to visualise, e.g. `(cell) => cell.band_1 ?? 0`.
+     *
+     * @param tableName - The name of the GeoTiff table (as given to `loadGeoTiff`).
+     * @returns A promise that resolves to a packed raster FeatureCollection.
+     */
+    getGeoTiffLayer(tableName: string): Promise<FeatureCollection<null>>;
+    /**
+     * Retrieves the GeoJSON representation of a layer by its table name.
+     * The returned FeatureCollection will include a bbox property with the layer's bounding box.
+     * @param layerTableName - The name of the layer table to retrieve.
+     * @returns A promise that resolves to the GeoJSON FeatureCollection of the layer with bbox.
+     * @throws Error if the database or connection is not initialized.
+     * @throws Error if the layer table is not found or is not a Layer table.
+     */
+    getLayer(layerTableName: string): Promise<FeatureCollection>;
+    /**
+     * Retrieves the OSM bounding box for the current workspace.
+     *
+     * @returns The bounding box as `[minLon, minLat, maxLon, maxLat]`, or `null` if no OSM data has been loaded.
+     * @throws Never throws.
+     */
+    getOsmBoundingBox(): [number, number, number, number] | null;
+    /**
+     * Returns the OSM bounding box in WGS84 (EPSG:4326) for clipping rasters.
+     *
+     * @returns The bounding box or `null` if no OSM data has been loaded.
+     * @throws Never throws.
+     */
+    getOsmBoundingBoxWgs84(): BoundingBox | null;
+    /**
+     * Retrieves the bounding box of a layer by its table name.
+     * @param layerName - The name of the layer table to retrieve the bounding box from.
+     * @returns A promise that resolves to the bounding box of the layer.
+     * @throws Error if the database or connection is not initialized.
+     * @throws Error if the layer table is not found.
+     * @throws Error if the layer table does not have a geometry column.
+     */
+    getBoundingBoxFromLayer(layerName: string): Promise<BoundingBox>;
+    /**
+     * Retrieves all layer tables from the loaded tables.
+     *
+     * @returns An array of `LayerTable` and `CustomLayerTable` objects.
+     * @throws Never throws.
+     */
+    getLayerTables(): Array<LayerTable | CustomLayerTable>;
+    /**
+     * Retrieves the data from any table as an array of plain JavaScript objects.
+     * This method works with all table types (CSV, JSON, Layer, Grid, etc.).
+     * @param params - Parameters including table name and optional pagination (limit, offset).
+     * @returns A promise that resolves to an array of objects representing the table rows.
+     * @throws Error if the database or connection is not initialized.
+     * @throws Error if the table is not found.
+     */
+    getTableData(params: GetTableDataParams): Promise<GetTableDataOutput>;
+    /**
+     * Updates an existing table with new data.
+     *
+     * For layer tables (OSM, GeoJSON), the input data should be a GeoJSON FeatureCollection.
+     * For non-layer tables (CSV, JSON), the input data should be an array of objects.
+     *
+     * @param params - Parameters for updating the table:
+     *   - tableName: The name of the table to update
+     *   - data: The new data (FeatureCollection for layers, Record<string, unknown>[] for CSV/JSON)
+     *   - strategy: 'replace' (drop and recreate) or 'update' (update existing records by ID)
+     *   - idColumn: Required for 'update' strategy. Supports 'id' or 'properties.attribute_name' format
+     * @returns A promise that resolves to the updated Table with refreshed column metadata.
+     * @throws Error if the database or connection is not initialized.
+     * @throws Error if the table is not found.
+     * @throws Error if idColumn is not provided when using 'update' strategy.
+     */
+    updateTable(params: Omit<UpdateTableParams, 'workspace'>): Promise<Table>;
+    /**
+     * Performs a spatial join between two tables and returns the resulting table.
+     * The method can either create a new table or update an existing one based on the parameters.
+     * @param params - Parameters for the spatial join operation, including source and target tables, join type, and output table name.
+     * @returns A promise that resolves to the resulting table after the spatial join.
+     * @throws Error if the database or connection is not initialized.
+     */
+    spatialQuery(params: SpatialQueryParams): Promise<Table>;
+    /**
+     * Executes a raw SQL query and returns the result.
+     * @param params - Parameters for the raw query, including the SQL query string and output type.
+     * @returns A promise that resolves to a Table if output type is 'CREATE_TABLE', otherwise returns the query result of type T.
+     * @throws Error if the database or connection is not initialized.
+     */
+    rawQuery<T = RawQueryOutput>(params: RawQueryParams): Promise<T | Table>;
+    /**
+     * Drops a table from the database and removes it from the current workspace.
+     * @param tableName - The name of the table to remove.
+     * @returns A promise that resolves when the table has been dropped.
+     * @throws Error if the database or connection is not initialized.
+     */
+    removeLayer(tableName: string): Promise<void>;
+    /**
+     * Builds a heatmap from spatial data by creating a grid and aggregating values.
+     * The heatmap is generated by creating a grid over the bounding box and aggregating values from the source table into each grid cell.
+     * @param params - Parameters for building the heatmap, including source table, grid configuration, and aggregation method.
+     * @returns A promise that resolves to the resulting GridLayerTable containing the heatmap data.
+     * @throws Error if the database or connection is not initialized.
+     */
+    buildHeatmap(params: BuildHeatmapParams): Promise<Table>;
+}

package/dist/src/spatial/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @module AutkSpatialDb
+ * Spatial database public API.
+ */
+export * from './SpatialDb';

package/dist/src/spatial/shared/use-cases/drop-table/DropTableUseCase.d.ts

@@ -0,0 +1,25 @@
+import { AsyncDuckDBConnection } from '@duckdb/duckdb-wasm';
+export interface DropTableParams {
+    tableName: string;
+    workspace?: string;
+}
+export interface DropTableResult {
+    success: boolean;
+    message: string;
+}
+/**
+ * Drops a table from the current workspace.
+ */
+export declare class DropTableUseCase {
+    private conn;
+    constructor(conn: AsyncDuckDBConnection);
+    /**
+     * Drops the specified table, returning success/failure rather than throwing.
+     *
+     * @param params.tableName Name of the table to drop.
+     * @param params.workspace Optional workspace name (defaults to `main`).
+     * @returns Result indicating success or failure with a message.
+     * @throws Never throws. Errors are caught and returned in the result.
+     */
+    exec(params: DropTableParams): Promise<DropTableResult>;
+}

package/dist/src/spatial/shared/use-cases/get-bounding-box-from-area/GetBoundingBoxFromAreaUseCase.d.ts

@@ -0,0 +1,16 @@
+import { BoundingBox } from '../../../../shared/interfaces';
+import { GetBoundingBoxFromAreaParams } from './interfaces';
+/**
+ * Fetches bounding boxes for named areas from the Overpass API.
+ */
+export declare class GetBoundingBoxFromAreaUseCase {
+    /**
+     * Fetches and merges bounding boxes for multiple named areas.
+     *
+     * @param params.queryArea Geocode scope and area names.
+     * @returns Combined bounding box spanning all areas.
+     * @throws If no bounding box can be determined.
+     */
+    exec(params: GetBoundingBoxFromAreaParams): Promise<BoundingBox>;
+    private fetchBoundingBoxForArea;
+}

package/dist/src/spatial/shared/use-cases/get-bounding-box-from-area/interfaces.d.ts

@@ -0,0 +1,6 @@
+export interface GetBoundingBoxFromAreaParams {
+    queryArea: {
+        geocodeArea: string;
+        areas: string[];
+    };
+}

package/dist/src/spatial/shared/use-cases/get-bounding-box-from-layer/GetBoundingBoxFromLayerUseCase.d.ts

@@ -0,0 +1,19 @@
+import { AsyncDuckDBConnection } from '@duckdb/duckdb-wasm';
+import { GetBoundingBoxFromLayerParams } from './interfaces';
+import { BoundingBox } from '../../../../shared/interfaces';
+/**
+ * Computes the geographic bounding box of a layer table.
+ */
+export declare class GetBoundingBoxFromLayerUseCase {
+    private conn;
+    constructor(conn: AsyncDuckDBConnection);
+    /**
+     * Queries the spatial extent of a layer's geometry column.
+     *
+     * @param params.layerTableName Name of the layer table.
+     * @param params.workspace Optional workspace name (defaults to `main`).
+     * @returns Named bounding box with `minLon`, `minLat`, `maxLon`, `maxLat`.
+     * @throws If the table has no geometries or invalid coordinates.
+     */
+    exec(params: GetBoundingBoxFromLayerParams): Promise<BoundingBox>;
+}

package/dist/src/spatial/shared/use-cases/get-bounding-box-from-layer/interfaces.d.ts

@@ -0,0 +1,6 @@
+import { BoundingBox } from '../../../../shared/interfaces';
+export interface GetBoundingBoxFromLayerParams {
+    layerTableName: string;
+    workspace?: string;
+}
+export type { BoundingBox };

package/dist/src/spatial/shared/use-cases/get-bounding-box-from-layer/queries.d.ts

@@ -0,0 +1 @@
+export declare const GET_BOUNDING_BOX_FROM_LAYER_QUERY: (layerTableName: string, workspace: string) => string;

package/dist/src/spatial/shared/use-cases/get-bounding-box-from-osm/GetBoundingBoxFromOsmUseCase.d.ts

@@ -0,0 +1,19 @@
+import { AsyncDuckDBConnection } from '@duckdb/duckdb-wasm';
+import { BoundingBox } from '../../../../shared/interfaces';
+import { GetBoundingBoxFromOsmParams } from './interfaces';
+/**
+ * Computes the geographic bounding box of an OSM boundary table.
+ */
+export declare class GetBoundingBoxFromOsmUseCase {
+    private conn;
+    constructor(conn: AsyncDuckDBConnection);
+    /**
+     * Queries the spatial extent of boundary way geometries in an OSM table.
+     *
+     * @param params.osmTableName Name of the OSM boundaries table.
+     * @param params.workspace Optional workspace name (defaults to `main`).
+     * @returns Named bounding box.
+     * @throws If the table has no coordinates or invalid values.
+     */
+    exec(params: GetBoundingBoxFromOsmParams): Promise<BoundingBox>;
+}

package/dist/src/spatial/shared/use-cases/get-bounding-box-from-osm/interfaces.d.ts

@@ -0,0 +1,4 @@
+export interface GetBoundingBoxFromOsmParams {
+    osmTableName: string;
+    workspace?: string;
+}

package/dist/src/spatial/shared/use-cases/get-bounding-box-from-osm/queries.d.ts

@@ -0,0 +1 @@
+export declare const GET_BOUNDING_BOX_FROM_OSM_QUERY: (osmTableName: string, workspace: string) => string;

package/dist/src/spatial/shared/use-cases/transform-bounding-box-coordinates/TransformBoundingBoxCoordinatesUseCase.d.ts

@@ -0,0 +1,20 @@
+import { AsyncDuckDBConnection } from '@duckdb/duckdb-wasm';
+import { TransformBoundingBoxCoordinatesParams } from './interfaces';
+import { BoundingBox } from '../../../../shared/interfaces';
+/**
+ * Transforms a bounding box between coordinate reference systems.
+ */
+export declare class TransformBoundingBoxCoordinatesUseCase {
+    private conn;
+    constructor(conn: AsyncDuckDBConnection);
+    /**
+     * Transforms bounding box coordinates using DuckDB's `ST_Transform`.
+     * EPSG:4326 inputs are returned unchanged.
+     *
+     * @param params.boundingBox Source bounding box to transform.
+     * @param params.coordinateFormat Target CRS (e.g. `EPSG:3857`).
+     * @returns Transformed bounding box.
+     * @throws If the coordinate transformation fails.
+     */
+    exec(params: TransformBoundingBoxCoordinatesParams): Promise<BoundingBox>;
+}

package/dist/src/spatial/shared/use-cases/transform-bounding-box-coordinates/interfaces.d.ts

@@ -0,0 +1,9 @@
+export interface TransformBoundingBoxCoordinatesParams {
+    boundingBox: {
+        minLat: number;
+        maxLat: number;
+        minLon: number;
+        maxLon: number;
+    };
+    coordinateFormat: string;
+}

package/dist/src/spatial/shared/use-cases/transform-bounding-box-coordinates/queries.d.ts

@@ -0,0 +1,11 @@
+type Params = {
+    boundingBox: {
+        minLat: number;
+        maxLat: number;
+        minLon: number;
+        maxLon: number;
+    };
+    coordinateFormat: string;
+};
+export declare const TRANSFORM_BOUNDING_BOX_COORDINATES_QUERY: ({ boundingBox, coordinateFormat }: Params) => string;
+export {};

package/dist/src/spatial/shared/utils.d.ts

@@ -0,0 +1,20 @@
+import { Column } from '../../shared/interfaces';
+type DuckDbTableDescriptionColumn = {
+    column_name: string;
+    column_type: string;
+};
+/**
+ * Converts DuckDB `DESCRIBE` output rows into `Column` metadata objects.
+ *
+ * @param tableDescribeResponse Array of `{ column_name, column_type }` rows from DuckDB.
+ * @returns Array of `{ name, type }` column descriptors.
+ * @throws Never throws.
+ */
+export declare function getColumnsFromDuckDbTableDescribe(tableDescribeResponse: Array<DuckDbTableDescriptionColumn>): Array<Column>;
+/**
+ * Recursively converts values returned by DuckDB-Wasm / Apache Arrow into
+ * plain JavaScript values so they can be safely logged or serialised. It
+ * handles nested arrays, structs and any object exposing a `toJSON()` method.
+ */
+export declare function toPlain<T = unknown>(value: T): T;
+export {};

package/dist/src/spatial/use-cases/aggregate-building-layer/AggregateBuildingLayerUseCase.d.ts

@@ -0,0 +1,12 @@
+import { AsyncDuckDBConnection } from '@duckdb/duckdb-wasm';
+/**
+ * Aggregates building geometries by `building_id` into union geometries.
+ */
+export declare class AggregateBuildingLayerUseCase {
+    private conn;
+    constructor(conn: AsyncDuckDBConnection);
+    exec(params: {
+        inputTableName: string;
+        workspace?: string;
+    }): Promise<void>;
+}