@walkthru-earth/objex-utils 1.1.0 → 1.2.0

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);
@@ -1438,6 +1448,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 = [
@@ -2289,13 +2321,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);
@@ -3067,15 +3102,18 @@ 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;
@@ -3111,6 +3149,7 @@ exports.parseWKB = parseWKB;
 exports.persistToStorage = persistToStorage;
 exports.readParquetMetadata = readParquetMetadata;
 exports.resolveCloudUrl = resolveCloudUrl;
+exports.safeClamp = safeClamp;
 exports.safeDecodeURIComponent = safeDecodeURIComponent;
 exports.serializeToCsv = serializeToCsv;
 exports.serializeToJson = serializeToJson;