@walkthru-earth/objex-utils 1.2.1 → 1.3.0

package/README.md

@@ -29,6 +29,13 @@ import {
   extractEpsgFromGeoMeta,
   extractBounds,
 
+  // stac-geoparquet (detection + row → STAC Item)
+  isStacGeoparquetSchema,
+  stacRowToItem,
+  flattenStacBbox,
+  pickStacPrimaryAsset,
+  resolveStacAssetHref,
+
   // Storage URLs
   parseStorageUrl,
   resolveCloudUrl,
@@ -67,6 +74,7 @@ Full per-module developer reference lives in [`docs/`](./docs/README.md). Each p
 | [`docs/geometry.md`](./docs/geometry.md) | WKB parser, GeoArrow builder, geometry-column detection |
 | [`docs/cog.md`](./docs/cog.md) | Cloud-Optimized GeoTIFF pipeline helpers, band configs, color ramps |
 | [`docs/parquet-metadata.md`](./docs/parquet-metadata.md) | `readParquetMetadata` + CRS / bounds / geometry-type extractors |
+| [`docs/stac-geoparquet.md`](./docs/stac-geoparquet.md) | stac-geoparquet detection + row → STAC Item transforms |
 | [`docs/storage.md`](./docs/storage.md) | URL parsing, provider registry, `StorageAdapter`, `UrlAdapter` |
 | [`docs/query-engine.md`](./docs/query-engine.md) | `QueryEngine` interface + handle / result types |
 | [`docs/file-types.md`](./docs/file-types.md) | File-type registry: `getFileTypeInfo`, `getViewerKind`, `getDuckDbReadFn`, … |

package/dist/index.cjs

@@ -2477,6 +2477,15 @@ async function readParquetMetadata(url) {
     name: col.name,
     type: mapParquetType(col)
   }));
+  const topLevelColumns = [];
+  const root = metadata.schema[0];
+  const rootChildren = root?.num_children ?? 0;
+  let cursor = 1;
+  for (let i = 0; i < rootChildren && cursor < metadata.schema.length; i++) {
+    const el = metadata.schema[cursor];
+    if (el?.name) topLevelColumns.push(el.name);
+    cursor += countSubtree(metadata.schema, cursor);
+  }
   let geo = null;
   let legacyGeoParquet = false;
   const geoKv = metadata.key_value_metadata?.find((kv) => kv.key === "geo");
@@ -2518,7 +2527,26 @@ async function readParquetMetadata(url) {
       compression = [...codecs].join(", ");
     }
   }
-  return { rowCount, schema, geo, legacyGeoParquet, createdBy, numRowGroups, compression };
+  return {
+    rowCount,
+    schema,
+    topLevelColumns,
+    geo,
+    legacyGeoParquet,
+    createdBy,
+    numRowGroups,
+    compression
+  };
+}
+function countSubtree(schema, start) {
+  const el = schema[start];
+  if (!el) return 0;
+  const n = el.num_children ?? 0;
+  let cursor = start + 1;
+  for (let i = 0; i < n; i++) {
+    cursor += countSubtree(schema, cursor);
+  }
+  return cursor - start;
 }
 function extractEpsgFromGeoMeta(geo) {
   const primaryCol = geo.columns[geo.primaryColumn];
@@ -2557,6 +2585,144 @@ function extractBounds(geo) {
   return [primaryCol.bbox[0], primaryCol.bbox[1], primaryCol.bbox[2], primaryCol.bbox[3]];
 }
 
+// ../../src/lib/utils/stac-geoparquet.ts
+var STAC_GEOPARQUET_REQUIRED_COLUMNS = [
+  "stac_version",
+  "type",
+  "geometry",
+  "assets"
+];
+function isStacGeoparquetSchema(schema) {
+  if (!Array.isArray(schema) || schema.length === 0) return false;
+  const names = new Set(schema.map((c) => c.name));
+  return STAC_GEOPARQUET_REQUIRED_COLUMNS.every((c) => names.has(c));
+}
+function flattenStacBbox(bbox) {
+  if (!bbox) return null;
+  if (Array.isArray(bbox)) {
+    if (bbox.length < 4) return null;
+    const [minX, minY, maxX, maxY] = bbox;
+    if (![minX, minY, maxX, maxY].every((v) => Number.isFinite(v))) return null;
+    return [minX, minY, maxX, maxY];
+  }
+  if (typeof bbox === "object") {
+    const { xmin, ymin, xmax, ymax } = bbox;
+    if (![xmin, ymin, xmax, ymax].every((v) => Number.isFinite(v))) return null;
+    return [xmin, ymin, xmax, ymax];
+  }
+  return null;
+}
+function resolveStacAssetHref(href, baseUrl) {
+  if (!href) return href;
+  if (/^[a-z][a-z0-9+\-.]*:\/\//i.test(href)) return href;
+  try {
+    return new URL(href, baseUrl).toString();
+  } catch {
+    return href;
+  }
+}
+function pickStacPrimaryAsset(assets, preferredKeys) {
+  if (!assets || typeof assets !== "object") return null;
+  const entries = Object.entries(assets).filter(
+    ([, a]) => a && typeof a === "object" && typeof a.href === "string"
+  );
+  if (entries.length === 0) return null;
+  if (preferredKeys) {
+    for (const key of preferredKeys) {
+      const match = entries.find(([k]) => k === key);
+      if (match) return { key: match[0], asset: match[1] };
+    }
+  }
+  const data = entries.find(([k]) => k === "data");
+  if (data) return { key: data[0], asset: data[1] };
+  const byRole = entries.find(([, a]) => Array.isArray(a.roles) && a.roles.includes("data"));
+  if (byRole) return { key: byRole[0], asset: byRole[1] };
+  return { key: entries[0][0], asset: entries[0][1] };
+}
+function normalizeAssetsField(value, baseUrl) {
+  if (!value || typeof value !== "object") return void 0;
+  const out = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (!raw || typeof raw !== "object") continue;
+    const asset = raw;
+    if (typeof asset.href !== "string" || !asset.href) continue;
+    out[key] = {
+      ...asset,
+      href: resolveStacAssetHref(asset.href, baseUrl)
+    };
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function normalizeLinksField(value, baseUrl) {
+  if (!Array.isArray(value)) return void 0;
+  const links = [];
+  for (const raw of value) {
+    if (!raw || typeof raw !== "object") continue;
+    const link = raw;
+    if (typeof link.href !== "string" || typeof link.rel !== "string") continue;
+    links.push({ ...link, href: resolveStacAssetHref(link.href, baseUrl) });
+  }
+  return links.length > 0 ? links : void 0;
+}
+function stacRowToItem(row, baseUrl, opts = {}) {
+  const { wkbParser, wkbColumn = "geom_wkb", geometryColumn = "geometry" } = opts;
+  let geometry = row[geometryColumn];
+  if (!geometry) {
+    const wkb = row[wkbColumn];
+    if (wkb && wkbParser) {
+      const bytes = wkb instanceof Uint8Array ? wkb : toUint8Array(wkb);
+      if (bytes) {
+        try {
+          geometry = wkbParser(bytes) ?? void 0;
+        } catch {
+          geometry = void 0;
+        }
+      }
+    }
+  }
+  const bbox = flattenStacBbox(row.bbox) ?? void 0;
+  const assets = normalizeAssetsField(row.assets, baseUrl);
+  const links = normalizeLinksField(row.links, baseUrl);
+  const properties = {};
+  for (const [key, value] of Object.entries(row)) {
+    if (value === null || value === void 0) continue;
+    if (key.startsWith("proj:") || key.startsWith("raster:") || key.startsWith("eo:")) {
+      properties[key] = value;
+    }
+    if (key === "datetime") {
+      properties.datetime = value instanceof Date ? value.toISOString() : String(value);
+    }
+    if (key === "bands") {
+      properties.bands = value;
+    }
+  }
+  const item = {
+    type: "Feature",
+    stac_version: typeof row.stac_version === "string" ? row.stac_version : "1.0.0",
+    id: typeof row.id === "string" ? row.id : String(row.id ?? ""),
+    properties
+  };
+  if (typeof row.collection === "string") item.collection = row.collection;
+  if (Array.isArray(row.stac_extensions)) {
+    item.stac_extensions = row.stac_extensions;
+  }
+  if (bbox) item.bbox = bbox;
+  if (geometry) item.geometry = geometry;
+  if (assets) item.assets = assets;
+  if (links) item.links = links;
+  return item;
+}
+function toUint8Array(value) {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) {
+    const view = value;
+    return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+  }
+  if (Array.isArray(value)) return new Uint8Array(value);
+  return null;
+}
+
 // ../../src/lib/utils/storage-url.ts
 function buildSchemeMap() {
   const map = {};
@@ -2570,6 +2736,32 @@ function buildSchemeMap() {
   return map;
 }
 var SCHEME_MAP = buildSchemeMap();
+var AWS_VHOST_RE = /^(.+)\.s3[.-]([a-z0-9-]+)\.amazonaws\.com$/;
+var AWS_PATH_RE = /^s3[.-]([a-z0-9-]+)\.amazonaws\.com$/;
+var AWS_GLOBAL_HOST = "s3.amazonaws.com";
+var R2_RE = /^([a-z0-9]+)\.r2\.cloudflarestorage\.com$/;
+var GCS_GLOBAL_HOST = "storage.googleapis.com";
+var GCS_VHOST_RE = /^(.+)\.storage\.googleapis\.com$/;
+var DO_VHOST_RE = /^(.+)\.([a-z0-9-]+)\.digitaloceanspaces\.com$/;
+var DO_PATH_RE = /^([a-z0-9-]+)\.digitaloceanspaces\.com$/;
+var WASABI_RE = /^s3\.([a-z0-9-]+)\.wasabisys\.com$/;
+var B2_S3_RE = /^(.+)\.s3\.([a-z0-9-]+)\.backblazeb2\.com$/;
+var B2_NATIVE_RE = /^f[a-z0-9]+\.backblazeb2\.com$/;
+var OSS_RE = /^(.+)\.(oss-[a-z0-9-]+)\.aliyuncs\.com$/;
+var COS_RE = /^(.+)\.cos\.([a-z0-9-]+)\.myqcloud\.com$/;
+var YANDEX_HOST = "storage.yandexcloud.net";
+var CONTABO_RE = /^([a-z0-9]+)\.contabostorage\.com$/;
+var HETZNER_RE = /^([a-z0-9]+)\.your-objectstorage\.com$/;
+var LINODE_VHOST_RE = /^(.+)\.([a-z0-9-]+)\.linodeobjects\.com$/;
+var LINODE_PATH_RE = /^([a-z0-9-]+)\.linodeobjects\.com$/;
+var OVH_RE = /^s3\.([a-z0-9-]+)\.io\.cloud\.ovh\.(?:net|us)$/;
+var AZURE_BLOB_RE = /^([a-z0-9]+)\.blob\.core\.windows\.net$/;
+var STORJ_GATEWAY_RE = /^gateway\.(?:([a-z0-9]+)\.)?storjshare\.io$/;
+var STORJ_LINK_RE = /^link\.(?:([a-z0-9]+)\.)?storjshare\.io$/;
+function isMinioLikeHost(host) {
+  return host.includes("minio") || host === "localhost" || host === "127.0.0.1" || host.startsWith("192.168.") || host.startsWith("10.");
+}
+var STAC_API_PATH_RE = /\/(collections|items|catalogs|search)(\/|\?|$)/i;
 function defaultResult(defaults) {
   return {
     bucket: "",
@@ -2610,7 +2802,7 @@ function parseStorageUrl(input, defaults = {}) {
       const url = new URL(trimmed);
       const host = url.hostname;
       const pathParts = url.pathname.replace(/^\//, "").split("/").filter(Boolean);
-      const awsVhost = host.match(/^(.+)\.s3[.-]([a-z0-9-]+)\.amazonaws\.com$/);
+      const awsVhost = host.match(AWS_VHOST_RE);
       if (awsVhost) {
         return {
           bucket: awsVhost[1],
@@ -2620,7 +2812,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.join("/")
         };
       }
-      const awsPath = host.match(/^s3[.-]([a-z0-9-]+)\.amazonaws\.com$/);
+      const awsPath = host.match(AWS_PATH_RE);
       if (awsPath && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
@@ -2630,7 +2822,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      if (host === "s3.amazonaws.com" && pathParts.length > 0) {
+      if (host === AWS_GLOBAL_HOST && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
           region: defaults.region || "us-east-1",
@@ -2639,7 +2831,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      const r2Match = host.match(/^([a-z0-9]+)\.r2\.cloudflarestorage\.com$/);
+      const r2Match = host.match(R2_RE);
       if (r2Match && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
@@ -2649,7 +2841,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      if (host === "storage.googleapis.com" && pathParts.length > 0) {
+      if (host === GCS_GLOBAL_HOST && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
           region: defaults.region || "us",
@@ -2658,7 +2850,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      const gcsVhost = host.match(/^(.+)\.storage\.googleapis\.com$/);
+      const gcsVhost = host.match(GCS_VHOST_RE);
       if (gcsVhost) {
         return {
           bucket: gcsVhost[1],
@@ -2668,7 +2860,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.join("/")
         };
       }
-      const doVhost = host.match(/^(.+)\.([a-z0-9-]+)\.digitaloceanspaces\.com$/);
+      const doVhost = host.match(DO_VHOST_RE);
       if (doVhost) {
         return {
           bucket: doVhost[1],
@@ -2678,7 +2870,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.join("/")
         };
       }
-      const doPath = host.match(/^([a-z0-9-]+)\.digitaloceanspaces\.com$/);
+      const doPath = host.match(DO_PATH_RE);
       if (doPath && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
@@ -2688,7 +2880,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      const wasabiMatch = host.match(/^s3\.([a-z0-9-]+)\.wasabisys\.com$/);
+      const wasabiMatch = host.match(WASABI_RE);
       if (wasabiMatch && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
@@ -2698,7 +2890,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      const b2S3 = host.match(/^(.+)\.s3\.([a-z0-9-]+)\.backblazeb2\.com$/);
+      const b2S3 = host.match(B2_S3_RE);
       if (b2S3) {
         return {
           bucket: b2S3[1],
@@ -2708,7 +2900,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.join("/")
         };
       }
-      const b2Native = host.match(/^f[a-z0-9]+\.backblazeb2\.com$/);
+      const b2Native = host.match(B2_NATIVE_RE);
       if (b2Native && pathParts[0] === "file" && pathParts.length > 1) {
         return {
           bucket: pathParts[1],
@@ -2718,7 +2910,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(2).join("/")
         };
       }
-      const ossMatch = host.match(/^(.+)\.(oss-[a-z0-9-]+)\.aliyuncs\.com$/);
+      const ossMatch = host.match(OSS_RE);
       if (ossMatch) {
         return {
           bucket: ossMatch[1],
@@ -2728,7 +2920,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.join("/")
         };
       }
-      const cosMatch = host.match(/^(.+)\.cos\.([a-z0-9-]+)\.myqcloud\.com$/);
+      const cosMatch = host.match(COS_RE);
       if (cosMatch) {
         return {
           bucket: cosMatch[1],
@@ -2738,7 +2930,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.join("/")
         };
       }
-      if (host === "storage.yandexcloud.net" && pathParts.length > 0) {
+      if (host === YANDEX_HOST && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
           region: defaults.region || "ru-central1",
@@ -2747,7 +2939,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      const contaboMatch = host.match(/^([a-z0-9]+)\.contabostorage\.com$/);
+      const contaboMatch = host.match(CONTABO_RE);
       if (contaboMatch && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
@@ -2757,7 +2949,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      const hetznerMatch = host.match(/^([a-z0-9]+)\.your-objectstorage\.com$/);
+      const hetznerMatch = host.match(HETZNER_RE);
       if (hetznerMatch && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
@@ -2767,7 +2959,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      const linodeVhost = host.match(/^(.+)\.([a-z0-9-]+)\.linodeobjects\.com$/);
+      const linodeVhost = host.match(LINODE_VHOST_RE);
       if (linodeVhost) {
         return {
           bucket: linodeVhost[1],
@@ -2777,7 +2969,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.join("/")
         };
       }
-      const linodePath = host.match(/^([a-z0-9-]+)\.linodeobjects\.com$/);
+      const linodePath = host.match(LINODE_PATH_RE);
       if (linodePath && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
@@ -2787,7 +2979,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      const ovhMatch = host.match(/^s3\.([a-z0-9-]+)\.io\.cloud\.ovh\.(?:net|us)$/);
+      const ovhMatch = host.match(OVH_RE);
       if (ovhMatch && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
@@ -2797,8 +2989,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      const isMinioLike = host.includes("minio") || host === "localhost" || host === "127.0.0.1" || host.startsWith("192.168.") || host.startsWith("10.");
-      if (isMinioLike && pathParts.length > 0) {
+      if (isMinioLikeHost(host) && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
           region: defaults.region || "us-east-1",
@@ -2807,7 +2998,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      const azureBlob = host.match(/^([a-z0-9]+)\.blob\.core\.windows\.net$/);
+      const azureBlob = host.match(AZURE_BLOB_RE);
       if (azureBlob && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
@@ -2817,7 +3008,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      const storjGateway = host.match(/^gateway\.(?:([a-z0-9]+)\.)?storjshare\.io$/);
+      const storjGateway = host.match(STORJ_GATEWAY_RE);
       if (storjGateway && pathParts.length > 0) {
         return {
           bucket: pathParts[0],
@@ -2827,7 +3018,7 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(1).join("/")
         };
       }
-      const storjLink = host.match(/^link\.(?:([a-z0-9]+)\.)?storjshare\.io$/);
+      const storjLink = host.match(STORJ_LINK_RE);
       if (storjLink && pathParts.length >= 3 && (pathParts[0] === "raw" || pathParts[0] === "s")) {
         return {
           bucket: pathParts[2],
@@ -2837,6 +3028,12 @@ function parseStorageUrl(input, defaults = {}) {
           prefix: pathParts.slice(3).join("/")
         };
       }
+      if (STAC_API_PATH_RE.test(url.pathname)) {
+        return {
+          ...defaultResult(defaults),
+          endpoint: `${url.protocol}//${url.host}`
+        };
+      }
       if (pathParts.length > 0) {
         const endpoint = `${url.protocol}//${url.host}`;
         return {
@@ -3146,6 +3343,7 @@ exports.PROVIDER_IDS = PROVIDER_IDS;
 exports.QueryCancelledError = QueryCancelledError;
 exports.SF_LABELS = SF_LABELS;
 exports.SQL_PREVIEW_LENGTH = SQL_PREVIEW_LENGTH;
+exports.STAC_GEOPARQUET_REQUIRED_COLUMNS = STAC_GEOPARQUET_REQUIRED_COLUMNS;
 exports.STORAGE_KEYS = STORAGE_KEYS;
 exports.UrlAdapter = UrlAdapter;
 exports.VIEWER_DIR_EXTENSIONS = VIEWER_DIR_EXTENSIONS;
@@ -3166,6 +3364,7 @@ exports.extractEpsgFromGeoMeta = extractEpsgFromGeoMeta;
 exports.extractGeometryTypes = extractGeometryTypes;
 exports.findGeoColumn = findGeoColumn;
 exports.findGeoColumnFromRows = findGeoColumnFromRows;
+exports.flattenStacBbox = flattenStacBbox;
 exports.formatDate = formatDate;
 exports.formatFileSize = formatFileSize;
 exports.formatValue = formatValue;
@@ -3184,6 +3383,7 @@ exports.isCloudNativeFormat = isCloudNativeFormat;
 exports.isGcsProvider = isGcsProvider;
 exports.isPubliclyStreamable = isPubliclyStreamable;
 exports.isQueryable = isQueryable;
+exports.isStacGeoparquetSchema = isStacGeoparquetSchema;
 exports.jsonReplacerBigInt = jsonReplacerBigInt;
 exports.loadFromStorage = loadFromStorage;
 exports.looksLikeUrl = looksLikeUrl;
@@ -3193,14 +3393,17 @@ exports.parseMarkdownDocument = parseMarkdownDocument;
 exports.parseStorageUrl = parseStorageUrl;
 exports.parseWKB = parseWKB;
 exports.persistToStorage = persistToStorage;
+exports.pickStacPrimaryAsset = pickStacPrimaryAsset;
 exports.readParquetMetadata = readParquetMetadata;
 exports.resolveCloudUrl = resolveCloudUrl;
 exports.resolveProviderEndpoint = resolveProviderEndpoint;
+exports.resolveStacAssetHref = resolveStacAssetHref;
 exports.safeClamp = safeClamp;
 exports.safeDecodeURIComponent = safeDecodeURIComponent;
 exports.serializeToCsv = serializeToCsv;
 exports.serializeToJson = serializeToJson;
 exports.sortFileEntries = sortFileEntries;
+exports.stacRowToItem = stacRowToItem;
 exports.toBinary = toBinary;
 exports.toggleSortField = toggleSortField;
 exports.typeBadgeClass = typeBadgeClass;