@walkthru-earth/objex-utils 1.2.1 → 1.3.0

package/dist/index.d.cts

@@ -596,11 +596,17 @@ interface GeoParquetMeta {
 interface ParquetFileMetadata {
     /** Total number of rows across all row groups. */
     rowCount: number;
-    /** Column schema (name + type). */
+    /** Column schema (name + type). Leaf columns only (structs flattened to children). */
     schema: {
         name: string;
         type: string;
     }[];
+    /**
+     * Top-level column names as written. Includes struct/group parents (e.g.
+     * `assets`, `bbox`) that `schema` flattens away. Required for stac-geoparquet
+     * detection, which looks up struct columns by their parent name.
+     */
+    topLevelColumns: string[];
     /** GeoParquet "geo" metadata if present. */
     geo: GeoParquetMeta | null;
     /** True when file has legacy GeoParquet metadata (schema_version 0.x without "version" field). */
@@ -633,6 +639,135 @@ declare function extractGeometryTypes(geo: GeoParquetMeta): GeoArrowGeomType[];
  */
 declare function extractBounds(geo: GeoParquetMeta): [number, number, number, number] | null;
 
+/**
+ * STAC (SpatioTemporal Asset Catalog) detection and parsing.
+ *
+ * Pure TypeScript helpers shared by ViewerRouter, StacMosaicViewer, and
+ * MultiCogViewer. No Svelte dependency, publishable via objex-utils.
+ */
+/** STAC Link (shared by Catalog/Collection/Item). */
+interface StacLink {
+    rel: string;
+    href: string;
+    type?: string;
+    title?: string;
+}
+/** STAC Item (GeoJSON Feature shape with stac_version). */
+interface StacItem {
+    type: 'Feature';
+    stac_version: string;
+    id: string;
+    bbox?: [number, number, number, number];
+    geometry?: unknown;
+    properties?: Record<string, unknown>;
+    assets?: Record<string, StacAsset>;
+    collection?: string;
+    links?: StacLink[];
+}
+/** Single asset entry within a STAC item. */
+interface StacAsset {
+    href: string;
+    type?: string;
+    title?: string;
+    roles?: string[];
+    /** Set when the asset carries `eo:bands`. */
+    'eo:bands'?: {
+        name?: string;
+        common_name?: string;
+    }[];
+}
+
+/**
+ * stac-geoparquet helpers.
+ *
+ * Pure TypeScript, zero Svelte / DuckDB / deck.gl dependencies. Re-exported
+ * through `@walkthru-earth/objex-utils` so other projects can consume the
+ * detection + row-to-Item transforms without pulling the Svelte lib.
+ *
+ * The module is decoupled from WKB decoding: callers pass a `wkbParser`
+ * callback (the objex Svelte lib threads its `parseWKB`; other consumers
+ * can plug in `geoarrow-wasm`, `wkx`, or any other library).
+ */
+
+/** Minimal schema column shape. Works with hyparquet, DuckDB, Arrow. */
+interface StacGeoparquetSchemaColumn {
+    name: string;
+    type?: string;
+}
+/** Bbox in struct shape as produced by DuckDB's `bbox struct(xmin,ymin,xmax,ymax)`. */
+interface StacBboxStruct {
+    xmin: number;
+    ymin: number;
+    xmax: number;
+    ymax: number;
+}
+/** Generic Record shape representing a single stac-geoparquet row after DuckDB decoding. */
+type StacGeoparquetRow = Record<string, unknown>;
+interface StacRowToItemOptions {
+    /**
+     * Decoder for the geometry column. Accepts a Uint8Array of WKB bytes and
+     * returns a GeoJSON geometry object (or null on failure).
+     *
+     * Consumers in the objex Svelte lib should pass `parseWKB` from
+     * `@walkthru-earth/objex-utils`. Other projects can use any WKB library.
+     */
+    wkbParser?: (bytes: Uint8Array) => unknown;
+    /**
+     * Column name holding the WKB bytes. Defaults to `'geom_wkb'` because the
+     * recommended SQL projection is `ST_AsWKB(geometry) AS geom_wkb`.
+     */
+    wkbColumn?: string;
+    /** Override the column holding the pre-decoded GeoJSON geometry, when available. */
+    geometryColumn?: string;
+}
+/** Columns every stac-geoparquet file MUST carry per the stac-geoparquet spec. */
+declare const STAC_GEOPARQUET_REQUIRED_COLUMNS: readonly ["stac_version", "type", "geometry", "assets"];
+/**
+ * Detect stac-geoparquet by presence of the required STAC columns.
+ *
+ * Deliberately type-agnostic: some pipelines know the type (DuckDB DESCRIBE,
+ * Arrow Field), others only have the name list (hyparquet schema walk). The
+ * set of names is sufficient for routing.
+ */
+declare function isStacGeoparquetSchema(schema: StacGeoparquetSchemaColumn[]): boolean;
+/**
+ * Flatten a DuckDB `struct(xmin,ymin,xmax,ymax)` bbox to the `[minX, minY, maxX, maxY]`
+ * array shape that STAC Items and deck.gl-geotiff MosaicLayer expect.
+ *
+ * Pass-through for arrays so callers that already have `[minX,minY,maxX,maxY]`
+ * shape (e.g. from a Feature's `bbox` field) don't need a separate path.
+ */
+declare function flattenStacBbox(bbox: StacBboxStruct | number[] | null | undefined): [number, number, number, number] | null;
+/**
+ * Resolve a possibly-relative STAC asset href against the parquet file URL.
+ *
+ * `./foo.tif` or `foo.tif` → absolute against `baseUrl`. Absolute URLs
+ * (`http(s)://`, `s3://`, `gs://`, etc.) are returned unchanged.
+ */
+declare function resolveStacAssetHref(href: string, baseUrl: string): string;
+/**
+ * Pick the "primary" asset from a STAC Item's `assets` map.
+ *
+ * Priority: caller-specified `preferredKeys` → `data` key → first asset with
+ * `roles` containing `'data'` → first asset. Returns `null` if the map is
+ * empty or not an object.
+ */
+declare function pickStacPrimaryAsset(assets: Record<string, StacAsset> | null | undefined, preferredKeys?: readonly string[]): {
+    key: string;
+    asset: StacAsset;
+} | null;
+/**
+ * Convert one stac-geoparquet row into a standard STAC Item JSON object.
+ *
+ * Handles:
+ *   - `assets` named-struct flattening + relative href resolution
+ *   - `bbox` struct → `[minX, minY, maxX, maxY]` array
+ *   - Optional WKB geometry → GeoJSON via `opts.wkbParser`
+ *   - `datetime` → ISO string (passes through already-string values)
+ *   - Promotes `properties.*` columns (`proj:*`, `datetime`) onto `item.properties`
+ */
+declare function stacRowToItem(row: StacGeoparquetRow, baseUrl: string, opts?: StacRowToItemOptions): StacItem;
+
 /**
  * Universal cloud storage URL / bucket parser.
  *
@@ -742,4 +877,4 @@ declare function findGeoColumnFromRows(rows: Record<string, unknown>[], schema:
     type: string;
 }[]): string | null;
 
-export { type AccessMode, type AccessModeInput, COPY_FEEDBACK_MS, type CogInfo, type Connection, type ConnectionConfig, DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, type Defaults, type DuckDbReadFn, type FileCategory, type FileEntry, type FileTypeInfo, type GeoArrowGeomType, type GeoArrowResult, type GeoBounds, type GeoColumnMeta, type GeoParquetMeta, type GeoType, type HexRow, LAYER_HUE_MULTIPLIER, type ListPage, MAX_QUERY_HISTORY_ENTRIES, type MapQueryHandle, type MapQueryResult, PROVIDERS, PROVIDER_IDS, type ParquetFileMetadata, type ParsedGeometry, type ParsedMarkdownDocument, type ParsedStorageUrl, type ProviderDef, type ProviderId, type ProviderRegion, QueryCancelledError, type QueryEngine, type QueryHandle, type QueryResult, type QuerySource, SF_LABELS, SQL_PREVIEW_LENGTH, STORAGE_KEYS, type SchemaField, type SortConfig, type SortDirection, type SortField, type SqlBlock, type StorageAdapter, type StorageProvider, type Tab, type Theme, type TypeCategory, UrlAdapter, VIEWER_DIR_EXTENSIONS, type ViewerKind, WGS84_CODES, type WriteResult, buildDataTypeLabel, buildDuckDbSource, buildEndpointFromTemplate, buildGeoArrowTables, buildProviderBaseUrl, clampBounds, classifyType, describeParseResult, escapeCsvField, exportToCsv, exportToJson, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, formatDate, formatFileSize, formatValue, generateHexDump, getAccessMode, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getNativeScheme, getProvider, getViewerKind, handleLoadError, interpolateTemplates, isCloudNativeFormat, isGcsProvider, isPubliclyStreamable, isQueryable, jsonReplacerBigInt, loadFromStorage, looksLikeUrl, markSqlBlocks, normalizeGeomType, parseMarkdownDocument, parseStorageUrl, parseWKB, persistToStorage, readParquetMetadata, resolveCloudUrl, resolveProviderEndpoint, safeClamp, safeDecodeURIComponent, serializeToCsv, serializeToJson, sortFileEntries, toBinary, toggleSortField, typeBadgeClass, typeColor, typeLabel };
+export { type AccessMode, type AccessModeInput, COPY_FEEDBACK_MS, type CogInfo, type Connection, type ConnectionConfig, DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, type Defaults, type DuckDbReadFn, type FileCategory, type FileEntry, type FileTypeInfo, type GeoArrowGeomType, type GeoArrowResult, type GeoBounds, type GeoColumnMeta, type GeoParquetMeta, type GeoType, type HexRow, LAYER_HUE_MULTIPLIER, type ListPage, MAX_QUERY_HISTORY_ENTRIES, type MapQueryHandle, type MapQueryResult, PROVIDERS, PROVIDER_IDS, type ParquetFileMetadata, type ParsedGeometry, type ParsedMarkdownDocument, type ParsedStorageUrl, type ProviderDef, type ProviderId, type ProviderRegion, QueryCancelledError, type QueryEngine, type QueryHandle, type QueryResult, type QuerySource, SF_LABELS, SQL_PREVIEW_LENGTH, STAC_GEOPARQUET_REQUIRED_COLUMNS, STORAGE_KEYS, type SchemaField, type SortConfig, type SortDirection, type SortField, type SqlBlock, type StacBboxStruct, type StacGeoparquetRow, type StacGeoparquetSchemaColumn, type StacRowToItemOptions, type StorageAdapter, type StorageProvider, type Tab, type Theme, type TypeCategory, UrlAdapter, VIEWER_DIR_EXTENSIONS, type ViewerKind, WGS84_CODES, type WriteResult, buildDataTypeLabel, buildDuckDbSource, buildEndpointFromTemplate, buildGeoArrowTables, buildProviderBaseUrl, clampBounds, classifyType, describeParseResult, escapeCsvField, exportToCsv, exportToJson, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, flattenStacBbox, formatDate, formatFileSize, formatValue, generateHexDump, getAccessMode, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getNativeScheme, getProvider, getViewerKind, handleLoadError, interpolateTemplates, isCloudNativeFormat, isGcsProvider, isPubliclyStreamable, isQueryable, isStacGeoparquetSchema, jsonReplacerBigInt, loadFromStorage, looksLikeUrl, markSqlBlocks, normalizeGeomType, parseMarkdownDocument, parseStorageUrl, parseWKB, persistToStorage, pickStacPrimaryAsset, readParquetMetadata, resolveCloudUrl, resolveProviderEndpoint, resolveStacAssetHref, safeClamp, safeDecodeURIComponent, serializeToCsv, serializeToJson, sortFileEntries, stacRowToItem, toBinary, toggleSortField, typeBadgeClass, typeColor, typeLabel };

package/dist/index.d.ts

@@ -596,11 +596,17 @@ interface GeoParquetMeta {
 interface ParquetFileMetadata {
     /** Total number of rows across all row groups. */
     rowCount: number;
-    /** Column schema (name + type). */
+    /** Column schema (name + type). Leaf columns only (structs flattened to children). */
     schema: {
         name: string;
         type: string;
     }[];
+    /**
+     * Top-level column names as written. Includes struct/group parents (e.g.
+     * `assets`, `bbox`) that `schema` flattens away. Required for stac-geoparquet
+     * detection, which looks up struct columns by their parent name.
+     */
+    topLevelColumns: string[];
     /** GeoParquet "geo" metadata if present. */
     geo: GeoParquetMeta | null;
     /** True when file has legacy GeoParquet metadata (schema_version 0.x without "version" field). */
@@ -633,6 +639,135 @@ declare function extractGeometryTypes(geo: GeoParquetMeta): GeoArrowGeomType[];
  */
 declare function extractBounds(geo: GeoParquetMeta): [number, number, number, number] | null;
 
+/**
+ * STAC (SpatioTemporal Asset Catalog) detection and parsing.
+ *
+ * Pure TypeScript helpers shared by ViewerRouter, StacMosaicViewer, and
+ * MultiCogViewer. No Svelte dependency, publishable via objex-utils.
+ */
+/** STAC Link (shared by Catalog/Collection/Item). */
+interface StacLink {
+    rel: string;
+    href: string;
+    type?: string;
+    title?: string;
+}
+/** STAC Item (GeoJSON Feature shape with stac_version). */
+interface StacItem {
+    type: 'Feature';
+    stac_version: string;
+    id: string;
+    bbox?: [number, number, number, number];
+    geometry?: unknown;
+    properties?: Record<string, unknown>;
+    assets?: Record<string, StacAsset>;
+    collection?: string;
+    links?: StacLink[];
+}
+/** Single asset entry within a STAC item. */
+interface StacAsset {
+    href: string;
+    type?: string;
+    title?: string;
+    roles?: string[];
+    /** Set when the asset carries `eo:bands`. */
+    'eo:bands'?: {
+        name?: string;
+        common_name?: string;
+    }[];
+}
+
+/**
+ * stac-geoparquet helpers.
+ *
+ * Pure TypeScript, zero Svelte / DuckDB / deck.gl dependencies. Re-exported
+ * through `@walkthru-earth/objex-utils` so other projects can consume the
+ * detection + row-to-Item transforms without pulling the Svelte lib.
+ *
+ * The module is decoupled from WKB decoding: callers pass a `wkbParser`
+ * callback (the objex Svelte lib threads its `parseWKB`; other consumers
+ * can plug in `geoarrow-wasm`, `wkx`, or any other library).
+ */
+
+/** Minimal schema column shape. Works with hyparquet, DuckDB, Arrow. */
+interface StacGeoparquetSchemaColumn {
+    name: string;
+    type?: string;
+}
+/** Bbox in struct shape as produced by DuckDB's `bbox struct(xmin,ymin,xmax,ymax)`. */
+interface StacBboxStruct {
+    xmin: number;
+    ymin: number;
+    xmax: number;
+    ymax: number;
+}
+/** Generic Record shape representing a single stac-geoparquet row after DuckDB decoding. */
+type StacGeoparquetRow = Record<string, unknown>;
+interface StacRowToItemOptions {
+    /**
+     * Decoder for the geometry column. Accepts a Uint8Array of WKB bytes and
+     * returns a GeoJSON geometry object (or null on failure).
+     *
+     * Consumers in the objex Svelte lib should pass `parseWKB` from
+     * `@walkthru-earth/objex-utils`. Other projects can use any WKB library.
+     */
+    wkbParser?: (bytes: Uint8Array) => unknown;
+    /**
+     * Column name holding the WKB bytes. Defaults to `'geom_wkb'` because the
+     * recommended SQL projection is `ST_AsWKB(geometry) AS geom_wkb`.
+     */
+    wkbColumn?: string;
+    /** Override the column holding the pre-decoded GeoJSON geometry, when available. */
+    geometryColumn?: string;
+}
+/** Columns every stac-geoparquet file MUST carry per the stac-geoparquet spec. */
+declare const STAC_GEOPARQUET_REQUIRED_COLUMNS: readonly ["stac_version", "type", "geometry", "assets"];
+/**
+ * Detect stac-geoparquet by presence of the required STAC columns.
+ *
+ * Deliberately type-agnostic: some pipelines know the type (DuckDB DESCRIBE,
+ * Arrow Field), others only have the name list (hyparquet schema walk). The
+ * set of names is sufficient for routing.
+ */
+declare function isStacGeoparquetSchema(schema: StacGeoparquetSchemaColumn[]): boolean;
+/**
+ * Flatten a DuckDB `struct(xmin,ymin,xmax,ymax)` bbox to the `[minX, minY, maxX, maxY]`
+ * array shape that STAC Items and deck.gl-geotiff MosaicLayer expect.
+ *
+ * Pass-through for arrays so callers that already have `[minX,minY,maxX,maxY]`
+ * shape (e.g. from a Feature's `bbox` field) don't need a separate path.
+ */
+declare function flattenStacBbox(bbox: StacBboxStruct | number[] | null | undefined): [number, number, number, number] | null;
+/**
+ * Resolve a possibly-relative STAC asset href against the parquet file URL.
+ *
+ * `./foo.tif` or `foo.tif` → absolute against `baseUrl`. Absolute URLs
+ * (`http(s)://`, `s3://`, `gs://`, etc.) are returned unchanged.
+ */
+declare function resolveStacAssetHref(href: string, baseUrl: string): string;
+/**
+ * Pick the "primary" asset from a STAC Item's `assets` map.
+ *
+ * Priority: caller-specified `preferredKeys` → `data` key → first asset with
+ * `roles` containing `'data'` → first asset. Returns `null` if the map is
+ * empty or not an object.
+ */
+declare function pickStacPrimaryAsset(assets: Record<string, StacAsset> | null | undefined, preferredKeys?: readonly string[]): {
+    key: string;
+    asset: StacAsset;
+} | null;
+/**
+ * Convert one stac-geoparquet row into a standard STAC Item JSON object.
+ *
+ * Handles:
+ *   - `assets` named-struct flattening + relative href resolution
+ *   - `bbox` struct → `[minX, minY, maxX, maxY]` array
+ *   - Optional WKB geometry → GeoJSON via `opts.wkbParser`
+ *   - `datetime` → ISO string (passes through already-string values)
+ *   - Promotes `properties.*` columns (`proj:*`, `datetime`) onto `item.properties`
+ */
+declare function stacRowToItem(row: StacGeoparquetRow, baseUrl: string, opts?: StacRowToItemOptions): StacItem;
+
 /**
  * Universal cloud storage URL / bucket parser.
  *
@@ -742,4 +877,4 @@ declare function findGeoColumnFromRows(rows: Record<string, unknown>[], schema:
     type: string;
 }[]): string | null;
 
-export { type AccessMode, type AccessModeInput, COPY_FEEDBACK_MS, type CogInfo, type Connection, type ConnectionConfig, DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, type Defaults, type DuckDbReadFn, type FileCategory, type FileEntry, type FileTypeInfo, type GeoArrowGeomType, type GeoArrowResult, type GeoBounds, type GeoColumnMeta, type GeoParquetMeta, type GeoType, type HexRow, LAYER_HUE_MULTIPLIER, type ListPage, MAX_QUERY_HISTORY_ENTRIES, type MapQueryHandle, type MapQueryResult, PROVIDERS, PROVIDER_IDS, type ParquetFileMetadata, type ParsedGeometry, type ParsedMarkdownDocument, type ParsedStorageUrl, type ProviderDef, type ProviderId, type ProviderRegion, QueryCancelledError, type QueryEngine, type QueryHandle, type QueryResult, type QuerySource, SF_LABELS, SQL_PREVIEW_LENGTH, STORAGE_KEYS, type SchemaField, type SortConfig, type SortDirection, type SortField, type SqlBlock, type StorageAdapter, type StorageProvider, type Tab, type Theme, type TypeCategory, UrlAdapter, VIEWER_DIR_EXTENSIONS, type ViewerKind, WGS84_CODES, type WriteResult, buildDataTypeLabel, buildDuckDbSource, buildEndpointFromTemplate, buildGeoArrowTables, buildProviderBaseUrl, clampBounds, classifyType, describeParseResult, escapeCsvField, exportToCsv, exportToJson, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, formatDate, formatFileSize, formatValue, generateHexDump, getAccessMode, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getNativeScheme, getProvider, getViewerKind, handleLoadError, interpolateTemplates, isCloudNativeFormat, isGcsProvider, isPubliclyStreamable, isQueryable, jsonReplacerBigInt, loadFromStorage, looksLikeUrl, markSqlBlocks, normalizeGeomType, parseMarkdownDocument, parseStorageUrl, parseWKB, persistToStorage, readParquetMetadata, resolveCloudUrl, resolveProviderEndpoint, safeClamp, safeDecodeURIComponent, serializeToCsv, serializeToJson, sortFileEntries, toBinary, toggleSortField, typeBadgeClass, typeColor, typeLabel };
+export { type AccessMode, type AccessModeInput, COPY_FEEDBACK_MS, type CogInfo, type Connection, type ConnectionConfig, DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, type Defaults, type DuckDbReadFn, type FileCategory, type FileEntry, type FileTypeInfo, type GeoArrowGeomType, type GeoArrowResult, type GeoBounds, type GeoColumnMeta, type GeoParquetMeta, type GeoType, type HexRow, LAYER_HUE_MULTIPLIER, type ListPage, MAX_QUERY_HISTORY_ENTRIES, type MapQueryHandle, type MapQueryResult, PROVIDERS, PROVIDER_IDS, type ParquetFileMetadata, type ParsedGeometry, type ParsedMarkdownDocument, type ParsedStorageUrl, type ProviderDef, type ProviderId, type ProviderRegion, QueryCancelledError, type QueryEngine, type QueryHandle, type QueryResult, type QuerySource, SF_LABELS, SQL_PREVIEW_LENGTH, STAC_GEOPARQUET_REQUIRED_COLUMNS, STORAGE_KEYS, type SchemaField, type SortConfig, type SortDirection, type SortField, type SqlBlock, type StacBboxStruct, type StacGeoparquetRow, type StacGeoparquetSchemaColumn, type StacRowToItemOptions, type StorageAdapter, type StorageProvider, type Tab, type Theme, type TypeCategory, UrlAdapter, VIEWER_DIR_EXTENSIONS, type ViewerKind, WGS84_CODES, type WriteResult, buildDataTypeLabel, buildDuckDbSource, buildEndpointFromTemplate, buildGeoArrowTables, buildProviderBaseUrl, clampBounds, classifyType, describeParseResult, escapeCsvField, exportToCsv, exportToJson, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, flattenStacBbox, formatDate, formatFileSize, formatValue, generateHexDump, getAccessMode, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getNativeScheme, getProvider, getViewerKind, handleLoadError, interpolateTemplates, isCloudNativeFormat, isGcsProvider, isPubliclyStreamable, isQueryable, isStacGeoparquetSchema, jsonReplacerBigInt, loadFromStorage, looksLikeUrl, markSqlBlocks, normalizeGeomType, parseMarkdownDocument, parseStorageUrl, parseWKB, persistToStorage, pickStacPrimaryAsset, readParquetMetadata, resolveCloudUrl, resolveProviderEndpoint, resolveStacAssetHref, safeClamp, safeDecodeURIComponent, serializeToCsv, serializeToJson, sortFileEntries, stacRowToItem, toBinary, toggleSortField, typeBadgeClass, typeColor, typeLabel };