@walkthru-earth/objex-utils 1.2.0 → 1.3.0

package/docs/README.md

@@ -34,6 +34,7 @@ As of v1.2, `yaml` is loaded via dynamic `import()` inside `parseMarkdownDocumen
 | [`geometry.md`](./geometry.md) | WKB parser, GeoArrow table builder, geometry-column detection |
 | [`cog.md`](./cog.md) | Cloud-Optimized GeoTIFF helpers (pipeline selection, band configs, color ramps, bounds clamping) |
 | [`parquet-metadata.md`](./parquet-metadata.md) | `readParquetMetadata` + CRS / bounds / geometry-types extractors |
+| [`stac-geoparquet.md`](./stac-geoparquet.md) | stac-geoparquet detection (`isStacGeoparquetSchema`) and row-to-Item transforms (`stacRowToItem`, `flattenStacBbox`, `pickStacPrimaryAsset`, `resolveStacAssetHref`) |
 | [`storage.md`](./storage.md) | URL parsing (`parseStorageUrl`, `resolveCloudUrl`), provider registry, `StorageAdapter` interface, `UrlAdapter` |
 | [`query-engine.md`](./query-engine.md) | `QueryEngine` interface and associated result/handle types |
 | [`file-types.md`](./file-types.md) | File-type registry (`getFileTypeInfo`, `getViewerKind`, `getDuckDbReadFn`, ...) |

package/docs/cog.md

@@ -1,11 +1,11 @@
 # Cloud-Optimized GeoTIFF (COG) helpers
 
-Pure helpers plus lazy wrappers for rendering Cloud-Optimized GeoTIFFs with [`@developmentseed/deck.gl-geotiff`](https://github.com/developmentseed/deck.gl-geotiff) v0.5 and MapLibre GL.
-
-The "pure" subset (types, safe-math, data-type labels, color ramps) has no native dependencies. The rendering-oriented functions pull in `@developmentseed/geotiff`, `@developmentseed/deck.gl-geotiff`, `maplibre-gl`, `proj4`, and `@developmentseed/proj` — treat all of those as **optional** peers.
+Pure, framework-agnostic helpers for working with Cloud-Optimized GeoTIFF metadata and bounds. No Svelte, MapLibre, deck.gl, or GeoTIFF library dependency.
 
 Source: `src/lib/utils/cog.ts`.
 
+> The render-pipeline helpers (`selectCogPipeline`, `createConfigurableGetTileData`, `normalizeCogGeotiff`, `createEpsgResolver`, `fitCogBounds`, `renderNonTiledBitmap`, etc.) live in the same source file but are **not** re-exported from `@walkthru-earth/objex-utils` because they pull in `@developmentseed/deck.gl-geotiff`, `@developmentseed/geotiff`, `@developmentseed/proj`, `proj4`, and `maplibre-gl`. If you need them, depend on the full Svelte package [`@walkthru-earth/objex`](https://www.npmjs.com/package/@walkthru-earth/objex) (they are re-exported from `src/lib/index.ts`) and install those optional peers yourself.
+
 ## Types
 
 ### `GeoBounds`
@@ -32,33 +32,7 @@ interface CogInfo {
 }
 ```
 
-### `BandConfig`
-
-```ts
-interface BandConfig {
-  mode: 'rgb' | 'single';
-  rBand: number;           // 0-indexed
-  gBand: number;
-  bBand: number;
-  band: number;            // single-band mode selection
-  colorRamp: ColorRampId;
-}
-```
-
-### `RescaleConfig`
-
-```ts
-interface RescaleConfig {
-  min: number;
-  max: number;
-}
-```
-
-### `CogTagInfo` / `ResolvedCogPipeline`
-
-Internal-but-exported descriptors returned by `inspectCogTags` / `selectCogPipeline`. See source for the full field list; the common shape is "metadata about which rendering pipeline should be used and why."
-
-## Pure helpers (no peer deps)
+## Constants
 
 ### `SF_LABELS`
 
@@ -71,6 +45,8 @@ const SF_LABELS: Record<number, string> = {
 
 Human labels for the GeoTIFF SampleFormat tag.
 
+## Functions
+
 ### `safeClamp(v, lo, hi, fallback)`
 
 ```ts
@@ -98,206 +74,19 @@ function buildDataTypeLabel(
 
 Combine the GeoTIFF `SampleFormat` tag with `BitsPerSample` into `'uint8'`, `'int16'`, `'float32'`, etc.
 
-### `defaultBandConfig(bandCount, sampleFormat)`
-
-```ts
-function defaultBandConfig(bandCount: number, sampleFormat: number): BandConfig
-```
-
-Sensible initial band config: RGB mode for ≥3 bands, single-band with a terrain ramp for int/float single-band imagery.
-
-### `isDefaultBandConfig(config, bandCount, sampleFormat)`
-
-```ts
-function isDefaultBandConfig(
-  config: BandConfig,
-  bandCount: number,
-  sampleFormat: number
-): boolean
-```
-
-`true` when `config` equals the default for this COG — used to short-circuit custom-pipeline selection.
-
-### Color ramps
-
-```ts
-type ColorRampId = 'grayscale' | 'terrain' | 'viridis' | 'magma' | 'turbo' | 'spectral';
-
-const COLOR_RAMP_STOPS: Record<ColorRampId, [number, number, number][]>;
-
-function interpolateRamp(
-  stops: [number, number, number][],
-  t: number
-): [number, number, number];
-
-function rampToGradientCss(id: ColorRampId): string;
-```
-
-`interpolateRamp(stops, t)` returns an RGB triple for normalized `t ∈ [0, 1]` (clamped). `rampToGradientCss` produces a CSS `linear-gradient(...)` string for UI previews.
-
-## Pipeline helpers (require peer deps)
-
-### `inspectCogTags(geotiff)`
-
-```ts
-function inspectCogTags(geotiff: GeoTIFF): CogTagInfo
-```
-
-Centralized reader for the TIFF tags that determine which render pipeline to use (Photometric.Palette, SampleFormat, ColorMap, etc.).
-
-### `needsCustomPipeline(geotiff)`
-
-```ts
-function needsCustomPipeline(geotiff: GeoTIFF): boolean
-```
-
-`true` when the library's `inferRenderPipeline` can't handle this COG (non-uint sample formats). Triggers the custom JS pipeline.
-
-### `needsCustomPipelineForConfig(geotiff, config)`
-
-```ts
-function needsCustomPipelineForConfig(
-  geotiff: GeoTIFF,
-  config: BandConfig
-): boolean
-```
-
-`true` when `config` deviates from what the library default pipeline supports (non-standard RGB band order, single-band mode, non-uint, non-palette).
-
-### `createCustomGetTileData(geotiff)` / `customRenderTile(data)`
-
-```ts
-function createCustomGetTileData(
-  geotiff: GeoTIFF
-): (image, options) => Promise<CustomTileData>;
-
-function customRenderTile(data: CustomTileData): { image: ImageData };
-```
-
-Band-0-only fallback path for non-uint COGs. Uses GDAL statistics when available, otherwise per-tile adaptive stretch, and applies the `terrain` color ramp.
-
-### `createConfigurableGetTileData(geotiff, config)`
-
-```ts
-function createConfigurableGetTileData(
-  geotiff: GeoTIFF,
-  config: BandConfig
-): (image, options) => Promise<CustomTileData>
-```
-
-Band-selectable variant. Honors `BandConfig.mode` (`'rgb'` vs `'single'`) and `colorRamp`.
-
-### `isRescaleActive(cfg)` / `createRescaledPipeline(geotiff, rescale)`
-
-```ts
-function isRescaleActive(cfg: RescaleConfig): boolean;
-
-function createRescaledPipeline(
-  geotiff: GeoTIFF,
-  rescale: RescaleConfig
-): { getTileData: Function; renderTile: Function };
-```
-
-GPU-side LinearRescale module appended to the library default uint pipeline. Only meaningful for uint COGs whose shape / colormap falls inside the library default — see `selectCogPipeline` for the dispatch rules.
-
-### `selectCogPipeline(geotiff, opts?)`
-
-```ts
-function selectCogPipeline(
-  geotiff: GeoTIFF,
-  opts?: SelectCogPipelineOptions
-): ResolvedCogPipeline
-```
-
-Single entry point that returns the correct `{ getTileData, renderTile }` pair for a given COG + config. Four outcomes in priority order:
-
-1. Custom configurable — band swap or color ramp change is active and the config is non-default.
-2. Custom non-uint — Int/Float COG without an explicit config yet.
-3. Library default + LinearRescale — uint COG with `rescale` active.
-4. Library default — everything else (empty object is returned; `COGLayer` uses its built-ins).
-
-### `normalizeCogGeotiff(geotiff)`
-
-```ts
-function normalizeCogGeotiff(geotiff: GeoTIFF): void
-```
-
-Apply in-place upstream workarounds:
-
-- Drop overview IFDs smaller than one tile (cause proj4 NaN on polar projections).
-- Clamp EPSG:4326 bbox to ±85.051129° latitude (Web Mercator safe range).
-
-Idempotent — safe to call repeatedly.
-
-### `createEpsgResolver()`
-
-```ts
-function createEpsgResolver(): (code: number) => Promise<ProjectionDefinition>
-```
-
-Async factory returning an `epsgResolver` compatible with `@developmentseed/deck.gl-geotiff`'s `COGLayer` prop of the same name. Looks up numeric EPSG codes in the bundled `@developmentseed/epsg` gzipped CSV and parses each WKT with `parseWkt()` from `@developmentseed/proj`. Throws a clear `Error` if the code is not present.
-
-Replaces runtime `epsg.io` fetches — first COG per session pulls the CSV (~200 KB gzipped) once.
-
-### Pixel / CRS helpers
-
-```ts
-function readPixelAtLngLat(
-  geotiff: GeoTIFF,
-  lng: number,
-  lat: number,
-  proj4Def: string | null,
-  pool: any,
-  signal?: AbortSignal
-): Promise<PixelValue | null>;
-
-function resolveProj4Def(
-  crs: number | unknown,
-  signal: AbortSignal
-): Promise<string | null>;
-```
-
-`readPixelAtLngLat` converts `(lng, lat)` into source CRS, then pixel coords, and reads every band. Returns `null` when outside the raster.
-
-`resolveProj4Def` returns a proj4-compatible WKT/ProjJSON string for a CRS identifier, or `null` for WGS84 / unknown.
-
-### MapLibre helpers
-
-```ts
-function getMaxTextureSize(map: maplibregl.Map): number;     // fallback 4096
-
-function fitCogBounds(map: maplibregl.Map, b: GeoBounds): void;
-
-function cleanupNativeBitmap(map: maplibregl.Map): void;    // idempotent
-
-function renderNonTiledBitmap(options: {
-  url: string;
-  map: maplibregl.Map;
-  signal?: AbortSignal;
-  geotiff?: GeoTIFF;
-}): Promise<CogInfo>;
-```
-
-`renderNonTiledBitmap` is the fallback path for non-tiled GeoTIFFs: opens the file, reads band 0, normalizes to grayscale RGBA (terrain ramp for single-band int/float), adds a MapLibre native `image` source. Throws when the raster exceeds 100 M pixels or projection bounds cannot be computed.
-
 ## Usage outline
 
 ```ts
 import {
-  defaultBandConfig,
-  selectCogPipeline,
-  normalizeCogGeotiff,
-  createEpsgResolver,
-  fitCogBounds,
+  buildDataTypeLabel,
   clampBounds,
+  safeClamp,
+  SF_LABELS,
+  type CogInfo,
+  type GeoBounds,
 } from '@walkthru-earth/objex-utils';
 
-normalizeCogGeotiff(geotiff);
-const config = defaultBandConfig(geotiff.bandCount, sampleFormat);
-const pipeline = selectCogPipeline(geotiff, { bandConfig: config });
-const resolver = createEpsgResolver();
-
-// feed into COGLayer({ ...pipeline, epsgResolver: resolver })
-
-fitCogBounds(map, clampBounds(bounds));
+const label = buildDataTypeLabel(sampleFormat, bitsPerSample); // 'float32'
+const safeBounds = clampBounds(bounds);
+const nice = safeClamp(value, 0, 1, 0);
 ```

package/docs/parquet-metadata.md

@@ -36,7 +36,14 @@ interface GeoParquetMeta {
 ```ts
 interface ParquetFileMetadata {
   rowCount: number;
+  /** Leaf columns only — struct parents are flattened into their child paths. */
   schema: { name: string; type: string }[];
+  /**
+   * Top-level column names as written, including struct/group parents
+   * (e.g. `assets`, `bbox`) that `schema` flattens away. Required for
+   * stac-geoparquet detection, which keys on the `assets` struct parent.
+   */
+  topLevelColumns: string[];
   geo: GeoParquetMeta | null;      // null for non-geo Parquet
   legacyGeoParquet: boolean;       // true for pre-1.0 (schema_version without "version" field)
   createdBy: string | null;
@@ -121,7 +128,8 @@ const meta = await readParquetMetadata(
 console.log({
   rows: meta.rowCount,
   compression: meta.compression,
-  schema: meta.schema,
+  schema: meta.schema,             // leaf columns only
+  topLevel: meta.topLevelColumns,  // includes struct parents like `assets`, `bbox`
 });
 
 if (meta.geo) {

package/docs/stac-geoparquet.md

@@ -0,0 +1,198 @@
+# stac-geoparquet
+
+Pure transforms and detection for the [stac-geoparquet](https://github.com/stac-utils/stac-geoparquet) format. Zero Svelte / DuckDB / deck.gl dependencies, framework-agnostic. Decoupled from any single WKB library via a caller-supplied `wkbParser`, so consumers can plug in `parseWKB` from this package, `geoarrow-wasm`, `wkx`, or anything else.
+
+```ts
+import {
+  STAC_GEOPARQUET_REQUIRED_COLUMNS,
+  isStacGeoparquetSchema,
+  flattenStacBbox,
+  resolveStacAssetHref,
+  pickStacPrimaryAsset,
+  stacRowToItem,
+  parseWKB,
+} from '@walkthru-earth/objex-utils';
+```
+
+## Types
+
+### `StacGeoparquetSchemaColumn`
+
+```ts
+interface StacGeoparquetSchemaColumn {
+  name: string;
+  type?: string;
+}
+```
+
+Minimal shape for a column descriptor. Works with hyparquet's leaf array, DuckDB's `DESCRIBE` rows, Arrow `Field`s, or any other source. `type` is optional because detection only keys on `name`.
+
+### `StacBboxStruct`
+
+```ts
+interface StacBboxStruct {
+  xmin: number;
+  ymin: number;
+  xmax: number;
+  ymax: number;
+}
+```
+
+Bbox in struct form, as DuckDB returns it for the recommended `bbox struct(xmin double, ymin double, xmax double, ymax double)` column.
+
+### `StacGeoparquetRow`
+
+```ts
+type StacGeoparquetRow = Record<string, unknown>;
+```
+
+Generic row shape after DuckDB / Arrow / hyparquet decoding. Pass directly into `stacRowToItem`.
+
+### `StacRowToItemOptions`
+
+```ts
+interface StacRowToItemOptions {
+  /** WKB decoder, e.g. `parseWKB` from this package. */
+  wkbParser?: (bytes: Uint8Array) => unknown;
+  /** Column holding the WKB bytes. Default `"geom_wkb"`. */
+  wkbColumn?: string;
+  /** Column holding pre-decoded GeoJSON geometry. Default `"geometry"`. */
+  geometryColumn?: string;
+}
+```
+
+The default `wkbColumn` of `"geom_wkb"` matches the recommended SQL projection `ST_AsWKB(geometry) AS geom_wkb`, which avoids DuckDB's GEOMETRY type hitting Arrow's WASM serializer.
+
+## Constants
+
+### `STAC_GEOPARQUET_REQUIRED_COLUMNS`
+
+```ts
+const STAC_GEOPARQUET_REQUIRED_COLUMNS = [
+  'stac_version',
+  'type',
+  'geometry',
+  'assets',
+] as const;
+```
+
+Columns every stac-geoparquet file MUST carry per the spec. `isStacGeoparquetSchema` checks that all four are present.
+
+## Functions
+
+### `isStacGeoparquetSchema(schema)`
+
+```ts
+function isStacGeoparquetSchema(
+  schema: StacGeoparquetSchemaColumn[]
+): boolean
+```
+
+Returns `true` when every required STAC column is present in `schema`. Type-agnostic on purpose: some pipelines know the column type (DuckDB `DESCRIBE`, Arrow `Field`), others only have the name list (hyparquet schema walk). The set of names is sufficient for routing.
+
+**Important** when used with `readParquetMetadata`: pass `meta.topLevelColumns.map((name) => ({ name }))`, not `meta.schema`. `meta.schema` flattens struct parents away and would hide the `assets` column.
+
+```ts
+import { readParquetMetadata, isStacGeoparquetSchema } from '@walkthru-earth/objex-utils';
+
+const meta = await readParquetMetadata(url);
+const isStac = isStacGeoparquetSchema(
+  meta.topLevelColumns.map((name) => ({ name }))
+);
+```
+
+### `flattenStacBbox(bbox)`
+
+```ts
+function flattenStacBbox(
+  bbox: StacBboxStruct | number[] | null | undefined
+): [number, number, number, number] | null
+```
+
+Normalize 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 inputs that are already arrays. Returns `null` when any component is non-finite or the input is missing.
+
+### `resolveStacAssetHref(href, baseUrl)`
+
+```ts
+function resolveStacAssetHref(href: string, baseUrl: string): string
+```
+
+Resolve a possibly-relative STAC asset href against a base URL. `./foo.tif` and `foo.tif` become absolute against `baseUrl`. URLs that already carry a scheme (`http(s)://`, `s3://`, `gs://`, …) are returned unchanged.
+
+### `pickStacPrimaryAsset(assets, preferredKeys?)`
+
+```ts
+function pickStacPrimaryAsset(
+  assets: Record<string, StacAsset> | null | undefined,
+  preferredKeys?: readonly string[]
+): { key: string; asset: StacAsset } | null
+```
+
+Pick the "primary" asset from a STAC Item's `assets` map. Priority order:
+
+1. The first key listed in `preferredKeys` that exists.
+2. The asset under the conventional `data` key.
+3. The first asset whose `roles` array contains `'data'`.
+4. The first asset.
+
+Returns `null` when the map is empty or the input is not an object.
+
+### `stacRowToItem(row, baseUrl, opts?)`
+
+```ts
+function stacRowToItem(
+  row: StacGeoparquetRow,
+  baseUrl: string,
+  opts?: StacRowToItemOptions
+): StacItem
+```
+
+Convert one stac-geoparquet row into a standard STAC Item JSON object. Handles:
+
+- `assets` named-struct flattening + relative href resolution against `baseUrl`
+- `bbox` struct → `[minX, minY, maxX, maxY]` array via `flattenStacBbox`
+- Optional WKB geometry → GeoJSON via `opts.wkbParser`
+- `datetime` → ISO string (passes through already-string values)
+- Promotes `properties.*` columns (`proj:*`, `raster:*`, `eo:*`, `bands`, `datetime`) onto `item.properties`
+
+Asset hrefs in stac-geoparquet are typically written relative to each item's original `self` URL, **not** the parquet URL. The stactools default layout places each item JSON at `{catalog_dir}/{item.id}/{item.id}.json`, so callers should compute a per-row base of `{parquet_dir}/{item.id}/` and pass that as `baseUrl`. Resolving against the bare parquet URL strips the item-id subfolder and every COG 404s.
+
+## End-to-end example
+
+```ts
+import {
+  isStacGeoparquetSchema,
+  parseWKB,
+  readParquetMetadata,
+  stacRowToItem,
+} from '@walkthru-earth/objex-utils';
+
+const parquetUrl = 'https://example.com/catalog.parquet';
+
+// 1. Detect — use topLevelColumns, not schema, so the `assets` struct parent is visible.
+const meta = await readParquetMetadata(parquetUrl);
+const isStac = isStacGeoparquetSchema(
+  meta.topLevelColumns.map((name) => ({ name }))
+);
+if (!isStac) throw new Error('Not stac-geoparquet');
+
+// 2. Materialize via your DuckDB / Arrow / hyparquet pipeline. Recommended SQL:
+//    SELECT id, type, stac_version, assets, bbox, links, datetime,
+//           ST_AsWKB(geometry) AS geom_wkb
+//    FROM 'catalog.parquet'
+const rows: Record<string, unknown>[] = await runYourQuery();
+
+// 3. Build STAC Items. Per-row base = {parquet_dir}/{item.id}/.
+const parquetDir = parquetUrl.replace(/[^/]*(?:\?.*)?$/, '');
+const items = rows.map((row) => {
+  const id = String(row.id ?? '');
+  const itemBase = id ? `${parquetDir}${id}/` : parquetUrl;
+  return stacRowToItem(row, itemBase, { wkbParser: parseWKB });
+});
+
+const featureCollection = { type: 'FeatureCollection', features: items };
+```
+
+## Peer dependencies
+
+None. The functions are pure and runtime-agnostic. The `wkbParser` option lets callers plug in any WKB decoder, including `parseWKB` from this same package.

package/docs/storage.md

@@ -154,6 +154,7 @@ const PROVIDER_IDS: ProviderId[];
 ```ts
 function getProvider(id: string): ProviderDef;
 function buildEndpointFromTemplate(id: ProviderId, region: string): string;
+function resolveProviderEndpoint(provider: string, region?: string): string;
 function buildProviderBaseUrl(
   provider: ProviderId,
   endpoint: string,
@@ -167,6 +168,7 @@ function isGcsProvider(provider: string, endpoint: string): boolean;
 |----------|-----------|
 | `getProvider` | Unknown IDs fall back to the S3 entry (never throws). |
 | `buildEndpointFromTemplate` | Substitute `{region}` in the provider's template. |
+| `resolveProviderEndpoint` | Same as `buildEndpointFromTemplate` but accepts an untyped `provider` string and falls back to the provider's `defaultRegion` when `region` is omitted. Returns `''` for providers without a template (plain S3, MinIO). |
 | `buildProviderBaseUrl` | Produce the HTTPS base URL for API requests (endpoint + bucket, correctly interleaved for virtual-host vs path-style). |
 | `isGcsProvider` | `true` when the connection uses the GCS JSON API rather than S3 XML — used to pick adapter implementation. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walkthru-earth/objex-utils",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Pure TypeScript utilities from objex — WKB parser, GeoArrow builder, storage URL parser, file type registry",
   "author": "Youssef Harby <yharby@walkthru.earth>",
   "license": "CC-BY-4.0",
@@ -15,9 +15,14 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [