@walkthru-earth/objex-utils 1.1.0 → 1.2.1

package/README.md

@@ -3,51 +3,50 @@
 [![npm](https://img.shields.io/npm/v/@walkthru-earth/objex-utils?color=cb3837)](https://www.npmjs.com/package/@walkthru-earth/objex-utils)
 [![License: CC BY 4.0](https://img.shields.io/badge/license-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)
 
-Pure TypeScript utilities extracted from [objex](https://github.com/walkthru-earth/objex) — zero Svelte dependency. Works with any JS framework or Node.js.
+Pure TypeScript utilities extracted from [objex](https://github.com/walkthru-earth/objex). Zero Svelte dependency. Works with any JS framework or Node 18+.
+
+Built for high-performance geospatial pipelines: WKB parsing, GeoArrow table construction, GeoParquet footer reading via range requests, cloud URL parsing, and a 200+ extension file-type registry.
 
 ## Install
 
 ```bash
 pnpm add @walkthru-earth/objex-utils
+# or
+npm install @walkthru-earth/objex-utils
 ```
 
-## Usage
+## At a glance
 
 ```ts
 import {
-  // WKB / Geometry
+  // WKB / GeoArrow
   parseWKB,
   findGeoColumn,
   buildGeoArrowTables,
 
-  // Storage URLs
-  parseStorageUrl,
-  looksLikeUrl,
-
-  // Parquet metadata
+  // Parquet metadata (hyparquet, range requests)
   readParquetMetadata,
   extractEpsgFromGeoMeta,
   extractBounds,
 
-  // File type registry
+  // Storage URLs
+  parseStorageUrl,
+  resolveCloudUrl,
+  looksLikeUrl,
+
+  // File-type registry
   getFileTypeInfo,
   getViewerKind,
-  getMimeType,
+  getDuckDbReadFn,
   isQueryable,
 
-  // Formatting
+  // Formatting / classification / hex / CSV / JSON
   formatFileSize,
-  formatDate,
   formatValue,
-  jsonReplacerBigInt,
-
-  // Column types
   classifyType,
-  typeColor,
-  typeLabel,
-
-  // Hex dump
   generateHexDump,
+  serializeToCsv,
+  serializeToJson,
 
   // Error handling
   handleLoadError,
@@ -59,33 +58,41 @@ import {
 } from '@walkthru-earth/objex-utils';
 ```
 
-## Exports
+## Documentation
+
+Full per-module developer reference lives in [`docs/`](./docs/README.md). Each page lists the exact TypeScript signature, parameter semantics, return shape, peer-dependency requirements, and non-obvious behavior.
+
+| Page | Covers |
+|------|--------|
+| [`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/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`, … |
+| [`docs/formatting.md`](./docs/formatting.md) | Display formatters, column-type classification, hex dump, CSV/JSON export |
+| [`docs/file-sort.md`](./docs/file-sort.md) | `sortFileEntries`, `toggleSortField` |
+| [`docs/markdown-sql.md`](./docs/markdown-sql.md) | Markdown + SQL block parsing (Evidence-compatible) |
+| [`docs/local-storage.md`](./docs/local-storage.md) | SSR-safe `loadFromStorage` / `persistToStorage` |
+| [`docs/errors.md`](./docs/errors.md) | `handleLoadError` |
+| [`docs/types-constants.md`](./docs/types-constants.md) | `Connection`, `Tab`, `FileEntry`, `WriteResult`, `Theme`, shared constants |
 
-| Export | Description |
-|--------|-------------|
-| `parseWKB()` | Parse WKB binary into coordinates with geometry type classification |
-| `findGeoColumn()` | 5-priority heuristic to detect geometry columns in tabular data |
-| `buildGeoArrowTables()` | Convert WKB arrays to GeoArrow tables for deck.gl rendering |
-| `parseStorageUrl()` | Parse S3/GCS/Azure/R2 URLs into provider, bucket, key |
-| `readParquetMetadata()` | Read Parquet file metadata via HTTP range requests (hyparquet) |
-| `getFileTypeInfo()` | Map file extensions to viewer kind, category, icon, and MIME type |
-| `formatFileSize()` | Human-readable file sizes (1024-based: KB, MB, GB) |
-| `formatValue()` | Format any value for display (handles BigInt, Date, objects, null) |
-| `generateHexDump()` | Generate hex dump rows from binary data |
-| `classifyType()` | Classify SQL/Arrow column types into categories |
-| `handleLoadError()` | Normalize errors, silently skip AbortError |
-| `WGS84_CODES` | Set of EPSG codes considered WGS84 (4326, 4979) |
+## Optional peer dependencies
 
-## Optional Peer Dependencies
+Heavy dependencies are **optional** peers. Install only what you use.
 
-Heavy dependencies are optional — only install what you use:
+| Peer | Required by |
+|------|-------------|
+| `apache-arrow >=14` | `buildGeoArrowTables` |
+| `hyparquet >=1.25` | `readParquetMetadata` and friends |
+| `hyparquet-compressors >=1.1` | SNAPPY / ZSTD / GZIP / LZ4 / BROTLI support in `readParquetMetadata` |
+| `yaml >=2` | `parseMarkdownDocument` (lazy-loaded — only when frontmatter is present) |
 
-- `apache-arrow` — required for `buildGeoArrowTables()`
-- `hyparquet` + `hyparquet-compressors` — required for `readParquetMetadata()`
+As of v1.2 the `yaml` dependency is imported dynamically inside `parseMarkdownDocument`. Consumers who never call that function do not need `yaml` at all. Before v1.2 the bundle failed to load without `yaml` even for unrelated imports.
 
 ## Related
 
-- [`@walkthru-earth/objex`](https://www.npmjs.com/package/@walkthru-earth/objex) — Full Svelte 5 component library with viewers, stores, and query engine
+- [`@walkthru-earth/objex`](https://www.npmjs.com/package/@walkthru-earth/objex) — Full Svelte 5 component library with viewers, stores, and query engine.
 
 ## License
 

package/dist/index.cjs

@@ -1,11 +1,11 @@
 'use strict';
 
+require('@developmentseed/epsg/all');
+require('@developmentseed/epsg/all.csv.gz?url');
+require('@developmentseed/geotiff');
+require('@developmentseed/proj');
+require('proj4');
 var apacheArrow = require('apache-arrow');
-var YAML = require('yaml');
-
-function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
-
-var YAML__default = /*#__PURE__*/_interopDefault(YAML);
 
 // ../../src/lib/constants.ts
 var STORAGE_KEYS = {
@@ -14,7 +14,7 @@ var STORAGE_KEYS = {
   QUERY_HISTORY: "obstore-explore-query-history"
 };
 var WGS84_CODES = /* @__PURE__ */ new Set([4326, 4979]);
-var DEFAULT_TARGET_CRS = "EPSG:4326";
+var DEFAULT_TARGET_CRS = "OGC:CRS84";
 var DUCKDB_INIT_TIMEOUT_MS = 3e4;
 var MAX_QUERY_HISTORY_ENTRIES = 200;
 var SQL_PREVIEW_LENGTH = 120;
@@ -894,6 +894,16 @@ var EXTENSIONS = {
     duckdbReadFn: null,
     mimeType: "application/octet-stream"
   },
+  ".ducklake": {
+    icon: "Database",
+    color: "text-teal-600 dark:text-teal-400",
+    label: "DuckLake",
+    category: "database",
+    viewer: "database",
+    queryable: true,
+    duckdbReadFn: null,
+    mimeType: "application/octet-stream"
+  },
   ".sqlite": {
     icon: "Database",
     color: "text-sky-600 dark:text-sky-400",
@@ -1041,7 +1051,7 @@ function buildDuckDbSource(pathOrExt, url) {
   const readFn = EXTENSIONS[ext]?.duckdbReadFn ?? "read_parquet";
   return `${readFn}('${url}')`;
 }
-var CLOUD_NATIVE_EXTS = /* @__PURE__ */ new Set([".parquet", ".geoparquet", ".gpq", ".gparquet"]);
+var CLOUD_NATIVE_EXTS = /* @__PURE__ */ new Set([".parquet", ".geoparquet", ".gpq", ".gparquet", ".ducklake"]);
 function isCloudNativeFormat(pathOrExt) {
   const ext = pathOrExt.includes(".") ? `.${pathOrExt.split(".").pop().toLowerCase()}` : "";
   return CLOUD_NATIVE_EXTS.has(ext);
@@ -1347,6 +1357,11 @@ function buildEndpointFromTemplate(id, region) {
   if (!def?.endpointTemplate) return "";
   return def.endpointTemplate.replace("{region}", region);
 }
+function resolveProviderEndpoint(provider, region) {
+  const def = PROVIDERS[provider];
+  if (!def?.endpointTemplate) return "";
+  return buildEndpointFromTemplate(provider, region || def.defaultRegion);
+}
 function buildProviderBaseUrl(provider, endpoint, bucket, region) {
   if (endpoint) {
     return `${endpoint.replace(/\/$/, "")}/${bucket}`;
@@ -1361,6 +1376,15 @@ function buildProviderBaseUrl(provider, endpoint, bucket, region) {
 function isGcsProvider(provider, endpoint) {
   return provider === "gcs" || !!endpoint && /storage\.googleapis\.com/i.test(endpoint);
 }
+function getAccessMode(conn) {
+  if (conn.provider === "azure") return "sas-https";
+  if (conn.anonymous) return "public-https";
+  return "signed-s3";
+}
+function isPubliclyStreamable(conn) {
+  const mode = getAccessMode(conn);
+  return mode === "public-https" || mode === "sas-https";
+}
 
 // ../../src/lib/storage/url-adapter.ts
 var UrlAdapter = class {
@@ -1438,6 +1462,28 @@ function resolveCloudUrl(url) {
   }
   return url;
 }
+var SF_LABELS = {
+  1: "uint",
+  2: "int",
+  3: "float",
+  4: "void",
+  5: "complex int",
+  6: "complex float"
+};
+function safeClamp(v, lo, hi, fallback) {
+  return Number.isFinite(v) ? Math.max(lo, Math.min(hi, v)) : fallback;
+}
+function clampBounds(b) {
+  return {
+    west: safeClamp(b.west, -180, 180, -180),
+    south: safeClamp(b.south, -85.051129, 85.051129, -85.051129),
+    east: safeClamp(b.east, -180, 180, 180),
+    north: safeClamp(b.north, -85.051129, 85.051129, 85.051129)
+  };
+}
+function buildDataTypeLabel(sampleFormat, bitsPerSample) {
+  return `${SF_LABELS[sampleFormat] ?? `sf${sampleFormat}`}${bitsPerSample ?? ""}`;
+}
 
 // ../../src/lib/utils/column-types.ts
 var NUMBER_TYPES = [
@@ -1608,6 +1654,17 @@ function formatValue(value) {
 }
 
 // ../../src/lib/utils/export.ts
+function triggerDownload(content, filename, mimeType) {
+  const blob = new Blob([content], { type: mimeType });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+}
 function formatCellValue(value) {
   if (value === null || value === void 0) return "";
   if (value instanceof Date) return value.toISOString();
@@ -1642,6 +1699,20 @@ function serializeToJson(columns, rows) {
   });
   return JSON.stringify(data, jsonReplacerBigInt, 2);
 }
+function exportToCsv(columns, rows, filename) {
+  triggerDownload(
+    serializeToCsv(columns, rows),
+    filename.endsWith(".csv") ? filename : `${filename}.csv`,
+    "text/csv;charset=utf-8;"
+  );
+}
+function exportToJson(columns, rows, filename) {
+  triggerDownload(
+    serializeToJson(columns, rows),
+    filename.endsWith(".json") ? filename : `${filename}.json`,
+    "application/json"
+  );
+}
 
 // ../../src/lib/utils/file-sort.ts
 function sortFileEntries(entries, config) {
@@ -2289,13 +2360,16 @@ function persistToStorage(key, value) {
   } catch {
   }
 }
-function parseMarkdownDocument(markdown) {
+
+// ../../src/lib/utils/markdown-sql.ts
+async function parseMarkdownDocument(markdown) {
   let frontmatter = {};
   let content = markdown;
   const fmMatch = markdown.match(/^---\n([\s\S]*?)\n---\n/);
   if (fmMatch) {
     try {
-      frontmatter = YAML__default.default.parse(fmMatch[1]) || {};
+      const { default: YAML } = await import('yaml');
+      frontmatter = YAML.parse(fmMatch[1]) || {};
     } catch {
     }
     content = markdown.slice(fmMatch[0].length);
@@ -2965,7 +3039,10 @@ var GEO_TYPE_KEYWORDS = [
   "geometrycollection",
   "sdo_geometry"
 ];
-var GEO_NAME_HINTS = ["geom", "geometry", "geo_", "_geo", "wkb", "wkt", "shape", "spatial"];
+var GEO_NAME_HINTS = ["geom", "geometry", "wkb", "wkt", "shape", "spatial", "geo"];
+function tokenizeColumnName(name) {
+  return name.replace(/([a-z])([A-Z])/g, "$1_$2").replace(/([a-z])([0-9])/g, "$1_$2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
 var GEOJSON_TYPES = [
   "Point",
   "LineString",
@@ -2995,14 +3072,14 @@ function findGeoColumn(schema) {
     if (GEO_NAMES.includes(f.name.toLowerCase())) return f.name;
   }
   for (const f of schema) {
-    const n = f.name.toLowerCase();
+    const tokens = tokenizeColumnName(f.name);
     const t = f.type.toLowerCase();
     const isBinary = t.includes("blob") || t.includes("binary") || t.includes("bytea");
-    if (isBinary && GEO_NAME_HINTS.some((hint) => n.includes(hint))) return f.name;
+    if (isBinary && tokens.some((tok) => GEO_NAME_HINTS.includes(tok))) return f.name;
   }
   for (const f of schema) {
-    const n = f.name.toLowerCase();
-    if (GEO_NAME_HINTS.some((hint) => n.includes(hint))) return f.name;
+    const tokens = tokenizeColumnName(f.name);
+    if (tokens.some((tok) => GEO_NAME_HINTS.includes(tok))) return f.name;
   }
   return null;
 }
@@ -3067,18 +3144,23 @@ exports.MAX_QUERY_HISTORY_ENTRIES = MAX_QUERY_HISTORY_ENTRIES;
 exports.PROVIDERS = PROVIDERS;
 exports.PROVIDER_IDS = PROVIDER_IDS;
 exports.QueryCancelledError = QueryCancelledError;
+exports.SF_LABELS = SF_LABELS;
 exports.SQL_PREVIEW_LENGTH = SQL_PREVIEW_LENGTH;
 exports.STORAGE_KEYS = STORAGE_KEYS;
 exports.UrlAdapter = UrlAdapter;
 exports.VIEWER_DIR_EXTENSIONS = VIEWER_DIR_EXTENSIONS;
 exports.WGS84_CODES = WGS84_CODES;
+exports.buildDataTypeLabel = buildDataTypeLabel;
 exports.buildDuckDbSource = buildDuckDbSource;
 exports.buildEndpointFromTemplate = buildEndpointFromTemplate;
 exports.buildGeoArrowTables = buildGeoArrowTables;
 exports.buildProviderBaseUrl = buildProviderBaseUrl;
+exports.clampBounds = clampBounds;
 exports.classifyType = classifyType;
 exports.describeParseResult = describeParseResult;
 exports.escapeCsvField = escapeCsvField;
+exports.exportToCsv = exportToCsv;
+exports.exportToJson = exportToJson;
 exports.extractBounds = extractBounds;
 exports.extractEpsgFromGeoMeta = extractEpsgFromGeoMeta;
 exports.extractGeometryTypes = extractGeometryTypes;
@@ -3088,6 +3170,7 @@ exports.formatDate = formatDate;
 exports.formatFileSize = formatFileSize;
 exports.formatValue = formatValue;
 exports.generateHexDump = generateHexDump;
+exports.getAccessMode = getAccessMode;
 exports.getDuckDbReadFn = getDuckDbReadFn;
 exports.getFileExtension = getFileExtension;
 exports.getFileTypeInfo = getFileTypeInfo;
@@ -3099,6 +3182,7 @@ exports.handleLoadError = handleLoadError;
 exports.interpolateTemplates = interpolateTemplates;
 exports.isCloudNativeFormat = isCloudNativeFormat;
 exports.isGcsProvider = isGcsProvider;
+exports.isPubliclyStreamable = isPubliclyStreamable;
 exports.isQueryable = isQueryable;
 exports.jsonReplacerBigInt = jsonReplacerBigInt;
 exports.loadFromStorage = loadFromStorage;
@@ -3111,6 +3195,8 @@ exports.parseWKB = parseWKB;
 exports.persistToStorage = persistToStorage;
 exports.readParquetMetadata = readParquetMetadata;
 exports.resolveCloudUrl = resolveCloudUrl;
+exports.resolveProviderEndpoint = resolveProviderEndpoint;
+exports.safeClamp = safeClamp;
 exports.safeDecodeURIComponent = safeDecodeURIComponent;
 exports.serializeToCsv = serializeToCsv;
 exports.serializeToJson = serializeToJson;