@walkthru-earth/objex-utils 1.4.0 → 1.5.0

package/docs/app-config.md

@@ -178,10 +178,10 @@ function resolveBasemap(
 
 Pick the basemap a map should render. Pick order:
 
-1. **Explicit user pick** -- the basemap whose `id` equals `userId`, but only if it still exists in the configured list (a stale `userId` from local storage is ignored).
-2. **Configured default for the variant** -- the basemap whose `id` equals `config.defaultBasemap[variant]`, when present and still in the list.
-3. **First basemap matching the variant** -- the first entry with `variant` equal to the requested variant.
-4. **First basemap of any variant** -- `config.basemaps[0]`.
+1. **Explicit user pick** - the basemap whose `id` equals `userId`, but only if it still exists in the configured list (a stale `userId` from local storage is ignored).
+2. **Configured default for the variant** - the basemap whose `id` equals `config.defaultBasemap[variant]`, when present and still in the list.
+3. **First basemap matching the variant** - the first entry with `variant` equal to the requested variant.
+4. **First basemap of any variant** - `config.basemaps[0]`.
 
 Returns `undefined` only when no basemaps are configured (`config.basemaps` is empty), signalling the caller to fall back to its own hardcoded default.
 

package/docs/cog-asset.md

@@ -116,9 +116,9 @@ Pick the most natural and most performant default composite for an item.
 
 **Priority** (first match wins):
 
-1. **`'visual-asset'`** -- a 3-band pre-baked visual asset (`bandCount === 3` and either `roles` contains `visual` or `eoCommon` contains all of `red`/`green`/`blue`). All three channels bind to that one asset, using the `eoCommon` index for each color where present and falling back to bands 0/1/2. Single-layer path, one decoder, fastest.
-2. **`'rgb-bands'`** -- separate single-band assets resolvable by common name, where `eoCommon[0]` is `red`, `green`, and `blue` respectively across three distinct assets. Each channel binds to its asset at band 0.
-3. **`'fallback'`** -- the first three raster assets, band 0 each. When fewer than three assets exist, the single remaining asset is reused for all three channels: R at band 0, G at `min(1, last)`, B at `min(2, last)`, where `last = max(0, bandCount - 1)`.
+1. **`'visual-asset'`** - a 3-band pre-baked visual asset (`bandCount === 3` and either `roles` contains `visual` or `eoCommon` contains all of `red`/`green`/`blue`). All three channels bind to that one asset, using the `eoCommon` index for each color where present and falling back to bands 0/1/2. Single-layer path, one decoder, fastest.
+2. **`'rgb-bands'`** - separate single-band assets resolvable by common name, where `eoCommon[0]` is `red`, `green`, and `blue` respectively across three distinct assets. Each channel binds to its asset at band 0.
+3. **`'fallback'`** - the first three raster assets, band 0 each. When fewer than three assets exist, the single remaining asset is reused for all three channels: R at band 0, G at `min(1, last)`, B at `min(2, last)`, where `last = max(0, bandCount - 1)`.
 
 **Returns** `{ composite, source }`, or `null` when `assets` is empty.
 

package/docs/lru.md

@@ -15,8 +15,8 @@ interface LruCacheOptions<K, V> {
 }
 ```
 
-- `max` -- maximum number of entries. Must be `> 0`. The constructor throws `Error('LruCache: max must be > 0')` for any non-positive value.
-- `onEvict` -- optional callback invoked whenever an entry leaves the cache, whether through LRU overflow, an explicit `delete()`, or `clear()`. Use it to release the cached resource (revoke a blob URL, null a GeoTIFF header, etc.).
+- `max` - maximum number of entries. Must be `> 0`. The constructor throws `Error('LruCache: max must be > 0')` for any non-positive value.
+- `onEvict` - optional callback invoked whenever an entry leaves the cache, whether through LRU overflow, an explicit `delete()`, or `clear()`. Use it to release the cached resource (revoke a blob URL, null a GeoTIFF header, etc.).
 
 ## Class
 

package/docs/map-pixel-inspect.md

@@ -54,8 +54,8 @@ interface PixelInspectCallbacks<T> {
 }
 ```
 
-- `onStart()` -- called synchronously when a click is accepted, before the probe is awaited. Use it to set an "inspecting" flag.
-- `onResult(result)` -- called once per accepted click after the probe settles. Receives `null` when the probe returned `null` or threw a non-helper-driven error, including an `AbortError` that did NOT originate from this helper's own controller (for example a viewer-teardown or upstream cancel). It is NOT called when a newer click superseded this one via the helper's own controller.
+- `onStart()` - called synchronously when a click is accepted, before the probe is awaited. Use it to set an "inspecting" flag.
+- `onResult(result)` - called once per accepted click after the probe settles. Receives `null` when the probe returned `null` or threw a non-helper-driven error, including an `AbortError` that did NOT originate from this helper's own controller (for example a viewer-teardown or upstream cancel). It is NOT called when a newer click superseded this one via the helper's own controller.
 
 ### `AttachPixelInspectorOptions<T>`
 

package/docs/stac-hydrate.md

@@ -42,14 +42,14 @@ interface HydrateOptions {
 }
 ```
 
-- `signal` -- required abort signal, threaded into every adapter read and `fetch`.
-- `concurrency` -- max parallel fetches for item links and child walks. Default `12`.
-- `limit` -- hard cap on items, catalogs larger than this are truncated. Default `2000`.
-- `followPagination` -- follow `links[rel=next]` in FeatureCollections. Default `true`.
-- `onBatch` -- called with each newly fetched batch for progressive rendering. Items in a batch already have absolutized asset hrefs.
-- `onProgress` -- called after each emit with the running item count, `totalHinted` is always `undefined` in the current implementation.
-- `urlToKey` -- maps an absolute HTTPS URL to a bucket-relative key when it belongs to the caller's connection. When it returns a non-null string, the fetch routes through `adapter.read` (SigV4) instead of cross-origin `fetch`, so private-bucket catalogs can be walked. Return `null` for foreign origins.
-- `itemsQuery` -- optional native STAC API filters appended to the `rel="items"` endpoint and re-stamped on every `rel="next"` page. See `StacItemsQuery`.
+- `signal` - required abort signal, threaded into every adapter read and `fetch`.
+- `concurrency` - max parallel fetches for item links and child walks. Default `12`.
+- `limit` - hard cap on items, catalogs larger than this are truncated. Default `2000`.
+- `followPagination` - follow `links[rel=next]` in FeatureCollections. Default `true`.
+- `onBatch` - called with each newly fetched batch for progressive rendering. Items in a batch already have absolutized asset hrefs.
+- `onProgress` - called after each emit with the running item count, `totalHinted` is always `undefined` in the current implementation.
+- `urlToKey` - maps an absolute HTTPS URL to a bucket-relative key when it belongs to the caller's connection. When it returns a non-null string, the fetch routes through `adapter.read` (SigV4) instead of cross-origin `fetch`, so private-bucket catalogs can be walked. Return `null` for foreign origins.
+- `itemsQuery` - optional native STAC API filters appended to the `rel="items"` endpoint and re-stamped on every `rel="next"` page. See `StacItemsQuery`.
 
 ### `StacItemsQuery`
 
@@ -64,10 +64,10 @@ interface StacItemsQuery {
 
 Native filters supported by OGC API Features / STAC API on `/items`.
 
-- `bbox` -- WGS84 `[west, south, east, north]`, stamped as `?bbox=w,s,e,n`.
-- `datetime` -- RFC 3339 instant or interval `start/end` (use `..` for open ends).
-- `limit` -- per-page item count hint, floored to an integer, the server may cap it.
-- `filter` -- a CQL2-JSON filter expression (STAC API Filter extension). When set it is appended as `?filter=<json>&filter-lang=cql2-json` and re-stamped onto every `rel="next"` page so cursor URLs cannot strip it.
+- `bbox` - WGS84 `[west, south, east, north]`, stamped as `?bbox=w,s,e,n`.
+- `datetime` - RFC 3339 instant or interval `start/end` (use `..` for open ends).
+- `limit` - per-page item count hint, floored to an integer, the server may cap it.
+- `filter` - a CQL2-JSON filter expression (STAC API Filter extension). When set it is appended as `?filter=<json>&filter-lang=cql2-json` and re-stamped onto every `rel="next"` page so cursor URLs cannot strip it.
 
 Each param is only stamped when the URL does not already carry it, so a server that echoes the original filter on its cursor links is not double-stamped (which would corrupt the JSON). `filter` is `JSON.stringify`-ed, a stringify failure (cyclic input) is swallowed and hydration continues without the filter.
 
@@ -98,16 +98,16 @@ function hydrateStacItems(
 
 Walk `root` into a flat `StacItem[]`.
 
-- `root` -- the classified payload from `classifyStac`. A `kind: 'none'` root yields an empty, non-truncated result.
-- `baseHref` -- the URL `root` was fetched from. All relative hrefs (child links, item links, asset hrefs) resolve against this.
-- `adapter` -- the `StorageAdapter` every fetch routes through (see `urlToKey` for the routing rule).
-- `opts` -- see `HydrateOptions`.
+- `root` - the classified payload from `classifyStac`. A `kind: 'none'` root yields an empty, non-truncated result.
+- `baseHref` - the URL `root` was fetched from. All relative hrefs (child links, item links, asset hrefs) resolve against this.
+- `adapter` - the `StorageAdapter` every fetch routes through (see `urlToKey` for the routing rule).
+- `opts` - see `HydrateOptions`.
 
 Behavior by `root.kind`:
 
-- `item` -- emits the single Item (asset hrefs absolutized against `baseHref`) and returns immediately, never truncated.
-- `item-collection` -- accepts every valid feature, then follows `rel="next"` recursively when `followPagination` and the running count is under `limit`. The `itemsQuery` is re-stamped on each next URL.
-- `collection` / `catalog` -- if the payload has static `rel="item"` links it fetches them with the worker pool. Otherwise, when no static item links exist, it tries the single `rel="items"` endpoint (with `itemsQuery` applied) and consumes it as a paginated FeatureCollection. A Catalog (or an item-link-less Collection) then also recurses into `rel="child"` links with up to `concurrency` workers, each child re-entering `hydrateStacItems` with a `limit` reduced by the count already gathered.
+- `item` - emits the single Item (asset hrefs absolutized against `baseHref`) and returns immediately, never truncated.
+- `item-collection` - accepts every valid feature, then follows `rel="next"` recursively when `followPagination` and the running count is under `limit`. The `itemsQuery` is re-stamped on each next URL.
+- `collection` / `catalog` - if the payload has static `rel="item"` links it fetches them with the worker pool. Otherwise, when no static item links exist, it tries the single `rel="items"` endpoint (with `itemsQuery` applied) and consumes it as a paginated FeatureCollection. A Catalog (or an item-link-less Collection) then also recurses into `rel="child"` links with up to `concurrency` workers, each child re-entering `hydrateStacItems` with a `limit` reduced by the count already gathered.
 
 Aborting via `opts.signal` stops the walk, in-flight reads reject with the adapter's abort behavior. Dead links and unreachable children are skipped, not fatal, so a partial catalog still hydrates. The returned `items` is sliced to `limit`.
 

package/docs/stac-source.md

@@ -59,11 +59,11 @@ interface StacSourceCapabilities {
 
 Read at construction (synchronous) and by the filter UI to decide which controls to disable or badge as "client-side only".
 
-- `label` -- human-readable HUD label, e.g. `"STAC API"`, `"stac-geoparquet"`, `"Static catalog"`.
-- `countAvailable` -- true when a cheap `count(filter, bbox)` exists, so the UI can surface "Y of X".
-- `streaming` -- true when `query()` yields multiple batches before completing.
-- `hivePartitioned` -- true when the source is a hive-partitioned parquet directory (set by the parquet source). Lets the viewer hint at the discovery model without inspecting `kind === 'parquet'` alone, since the same `kind` also covers single-file stac-geoparquet.
-- `pushdown` -- the *ceiling* of what this source kind can push. Exhaustive: every `FacetState` facet has a flag, so adding a new facet is a compile-time error in every consumer until handled. The actual per-request push-down is reported in each batch's `pushedDown`.
+- `label` - human-readable HUD label, e.g. `"STAC API"`, `"stac-geoparquet"`, `"Static catalog"`.
+- `countAvailable` - true when a cheap `count(filter, bbox)` exists, so the UI can surface "Y of X".
+- `streaming` - true when `query()` yields multiple batches before completing.
+- `hivePartitioned` - true when the source is a hive-partitioned parquet directory (set by the parquet source). Lets the viewer hint at the discovery model without inspecting `kind === 'parquet'` alone, since the same `kind` also covers single-file stac-geoparquet.
+- `pushdown` - the *ceiling* of what this source kind can push. Exhaustive: every `FacetState` facet has a flag, so adding a new facet is a compile-time error in every consumer until handled. The actual per-request push-down is reported in each batch's `pushedDown`.
 
 ### `StacSourceRequest`
 
@@ -79,11 +79,11 @@ interface StacSourceRequest {
 
 Per-query inputs.
 
-- `bbox` -- WGS84 viewport `[west, south, east, north]`, required. Sources that cannot push bbox still receive it, they stream the whole set and rely on the caller's residual filter.
-- `filter` -- the active `FacetState` (from `stac-facets`).
-- `limit` -- hard item cap for the request.
-- `pageSize` -- optional per-page hint for paginating sources, the server may ignore it.
-- `signal` -- required. Sources MUST throw `DOMException("Aborted", "AbortError")` on abort, never silently complete.
+- `bbox` - WGS84 viewport `[west, south, east, north]`, required. Sources that cannot push bbox still receive it, they stream the whole set and rely on the caller's residual filter.
+- `filter` - the active `FacetState` (from `stac-facets`).
+- `limit` - hard item cap for the request.
+- `pageSize` - optional per-page hint for paginating sources, the server may ignore it.
+- `signal` - required. Sources MUST throw `DOMException("Aborted", "AbortError")` on abort, never silently complete.
 
 ### `StacSourceBatch`
 
@@ -99,11 +99,11 @@ interface StacSourceBatch {
 
 One yielded batch.
 
-- `items` -- the items in this batch (empty on the terminal `done` batch).
-- `pushedDown` -- the subset of `filter` the source / engine already applied, reported so the UI can show "pushed".
-- `residual` -- the subset the caller must still apply via `applyFacets(views, residual)`.
-- `done` -- true on the final batch. The iterator's own end-of-iteration also signals completion, this flag lets a caller break the loop the moment a single-yield source finishes.
-- `totalHinted` -- best-effort total matching count, when the source knows it.
+- `items` - the items in this batch (empty on the terminal `done` batch).
+- `pushedDown` - the subset of `filter` the source / engine already applied, reported so the UI can show "pushed".
+- `residual` - the subset the caller must still apply via `applyFacets(views, residual)`.
+- `done` - true on the final batch. The iterator's own end-of-iteration also signals completion, this flag lets a caller break the loop the moment a single-yield source finishes.
+- `totalHinted` - best-effort total matching count, when the source knows it.
 
 ### `StacSource`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walkthru-earth/objex-utils",
-  "version": "1.4.0",
+  "version": "1.5.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",