@honua/react 0.0.20-alpha.0 → 0.1.1-beta.0

package/core/spatial-filter.js

@@ -1,3 +1,4 @@
+import { HonuaGeometryError } from "./errors.js";
 /**
  * Create an envelope (bounding box) spatial filter.
  *
@@ -62,8 +63,12 @@ export function polygon(rings, spatialReference) {
     };
 }
 /**
- * Create an envelope spatial filter centered on a point, approximating a
- * circular buffer as a bounding box.
+ * Create an axis-aligned envelope spatial filter centered on a point.
+ *
+ * This is a planar expansion in the input coordinate system's units. It is an
+ * envelope approximation, not a circular, geodesic, or topological geometry
+ * buffer. Use `buffer` from `@honua/sdk-js/geometry` when a true geometry
+ * buffer is required.
  *
  * @param x - Center x coordinate
  * @param y - Center y coordinate
@@ -75,12 +80,25 @@ export function polygon(rings, spatialReference) {
  * // 0.5-degree bounding box around a point
  * const req: QueryFeaturesRequest = {
  *   serviceId: "svc", layerId: 0,
- *   ...buffer(-118.24, 34.05, 0.5),
+ *   ...bufferEnvelope(-118.24, 34.05, 0.5),
  * };
  * ```
  */
-export function buffer(x, y, distance, spatialReference) {
-    return envelope(x - distance, y - distance, x + distance, y + distance, spatialReference);
+export function bufferEnvelope(x, y, distance, spatialReference) {
+    if (![x, y, distance].every(isFiniteNumber) || distance < 0) {
+        throw new HonuaGeometryError("malformed-geometry", "Cannot create a buffer envelope: x, y, and distance must be finite numbers and distance must be non-negative", {
+            operation: "buffer-envelope",
+            reason: "invalid-coordinate-or-distance",
+        });
+    }
+    const bounds = [x - distance, y - distance, x + distance, y + distance];
+    if (!bounds.every(isFiniteNumber)) {
+        throw new HonuaGeometryError("malformed-geometry", "Cannot create a buffer envelope: computed bounds must be finite", {
+            operation: "buffer-envelope",
+            reason: "computed-bounds-not-finite",
+        });
+    }
+    return envelope(...bounds, spatialReference);
 }
 /**
  * Wrap an existing geometry with `esriSpatialRelIntersects`.
@@ -131,23 +149,195 @@ export function spatialWithin(geometry) {
  * Detect the Esri geometry type from a plain geometry object by inspecting
  * its shape (duck-typing).
  *
+ * @see https://developers.arcgis.com/rest/services-reference/enterprise/geometry-objects/
  * @internal
  */
 function detectGeometryType(geometry) {
-    if ("xmin" in geometry && "ymin" in geometry && "xmax" in geometry && "ymax" in geometry) {
-        return "esriGeometryEnvelope";
+    if (!isGeometryRecord(geometry)) {
+        throw new HonuaGeometryError("malformed-geometry", "Unable to classify geometry: geometry must be a non-null object", {
+            operation: "classify",
+            reason: "geometry-must-be-object",
+            keys: [],
+        });
+    }
+    const keys = Object.keys(geometry).sort();
+    const candidates = [
+        hasAnyOwn(geometry, ["xmin", "ymin", "xmax", "ymax"]) ? "envelope" : undefined,
+        hasOwn(geometry, "rings") ? "polygon" : undefined,
+        hasOwn(geometry, "paths") ? "polyline" : undefined,
+        hasOwn(geometry, "points") ? "multipoint" : undefined,
+        hasAnyOwn(geometry, ["x", "y"]) ? "point" : undefined,
+    ].filter((candidate) => candidate !== undefined);
+    if (candidates.length === 0) {
+        throw geometryClassificationError("unknown-geometry", "no supported Esri geometry shape was found", keys);
+    }
+    if (candidates.length > 1) {
+        throw geometryClassificationError("malformed-geometry", `geometry contains conflicting shape discriminators: ${candidates.join(", ")}`, keys);
+    }
+    const candidate = candidates[0];
+    switch (candidate) {
+        case "envelope":
+            assertEnvelope(geometry, keys);
+            return "esriGeometryEnvelope";
+        case "polygon":
+            assertParts(geometry, "rings", "polygon", 4, true, keys);
+            return "esriGeometryPolygon";
+        case "polyline":
+            assertParts(geometry, "paths", "polyline", 2, false, keys);
+            return "esriGeometryPolyline";
+        case "multipoint":
+            assertPositions(geometry, keys);
+            return "esriGeometryMultipoint";
+        case "point":
+            assertPoint(geometry, keys);
+            return "esriGeometryPoint";
+    }
+}
+function isGeometryRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function hasAnyOwn(value, keys) {
+    return keys.some((key) => hasOwn(value, key));
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function assertPoint(geometry, keys) {
+    if (hasOwn(geometry, "x") && geometry.x === null) {
+        assertEmptyMembers(geometry, ["y", "z", "m", "id"], "point", keys);
+        return;
     }
-    if ("rings" in geometry) {
-        return "esriGeometryPolygon";
+    if (!isFiniteNumber(geometry.x) || !isFiniteNumber(geometry.y)) {
+        throw geometryClassificationError("malformed-geometry", "point requires finite numeric x and y coordinates", keys, "point");
+    }
+    assertOptionalFiniteMember(geometry, "z", "point", keys);
+    assertOptionalFiniteMember(geometry, "m", "point", keys, true);
+    assertOptionalFiniteMember(geometry, "id", "point", keys);
+}
+function assertEnvelope(geometry, keys) {
+    if (hasOwn(geometry, "xmin") && geometry.xmin === null) {
+        assertEmptyMembers(geometry, ["ymin", "xmax", "ymax", "zmin", "zmax", "mmin", "mmax", "idmin", "idmax"], "envelope", keys);
+        return;
     }
-    if ("paths" in geometry) {
-        return "esriGeometryPolyline";
+    const { xmin, ymin, xmax, ymax } = geometry;
+    if (![xmin, ymin, xmax, ymax].every(isFiniteNumber)) {
+        throw geometryClassificationError("malformed-geometry", "envelope requires finite numeric xmin, ymin, xmax, and ymax coordinates", keys, "envelope");
     }
-    if ("points" in geometry) {
-        return "esriGeometryMultipoint";
+    if (xmin > xmax || ymin > ymax) {
+        throw geometryClassificationError("malformed-geometry", "envelope minimum coordinates must not exceed maximum coordinates", keys, "envelope");
     }
-    if ("x" in geometry && "y" in geometry) {
-        return "esriGeometryPoint";
+    assertOptionalBounds(geometry, "zmin", "zmax", "envelope", keys);
+    assertOptionalBounds(geometry, "mmin", "mmax", "envelope", keys);
+    assertOptionalBounds(geometry, "idmin", "idmax", "envelope", keys);
+}
+function assertPositions(geometry, keys) {
+    const value = geometry.points;
+    if (!Array.isArray(value)) {
+        throw geometryClassificationError("malformed-geometry", "multipoint points must be an array of coordinate positions", keys, "multipoint");
+    }
+    const dimensions = geometryDimensions(geometry, "multipoint", keys);
+    for (const position of value) {
+        // ArcGIS permits empty point slots in multipoints and ignores them during
+        // spatial evaluation. Preserve that wire-compatible behavior while still
+        // rejecting every non-empty malformed position.
+        if (Array.isArray(position) && position.length === 0)
+            continue;
+        assertPosition(position, dimensions, "multipoint", keys);
+    }
+}
+function assertParts(geometry, property, shape, minimumPositions, requireClosure, keys) {
+    const value = geometry[property];
+    if (!Array.isArray(value)) {
+        throw geometryClassificationError("malformed-geometry", `${shape} ${property} must be an array of coordinate arrays`, keys, shape);
     }
-    return "esriGeometryPoint";
+    const dimensions = geometryDimensions(geometry, shape, keys);
+    for (const part of value) {
+        if (!Array.isArray(part)) {
+            throw geometryClassificationError("malformed-geometry", `${shape} ${property} must contain coordinate arrays`, keys, shape);
+        }
+        // The REST empty sentinel is an empty outer paths/rings array. Empty inner
+        // parts are not canonical and cannot be mixed with populated parts.
+        if (part.length < minimumPositions) {
+            throw geometryClassificationError("malformed-geometry", `${shape} ${property} parts require at least ${minimumPositions} positions`, keys, shape);
+        }
+        for (const position of part)
+            assertPosition(position, dimensions, shape, keys);
+        if (requireClosure) {
+            const first = part[0];
+            const last = part[part.length - 1];
+            if (first[0] !== last[0] || first[1] !== last[1]) {
+                throw geometryClassificationError("malformed-geometry", `${shape} ${property} parts must be closed`, keys, shape);
+            }
+        }
+    }
+}
+function geometryDimensions(geometry, shape, keys) {
+    return {
+        hasZ: geometryBooleanFlag(geometry, "hasZ", shape, keys),
+        hasM: geometryBooleanFlag(geometry, "hasM", shape, keys),
+    };
+}
+function geometryBooleanFlag(geometry, property, shape, keys) {
+    if (!hasOwn(geometry, property))
+        return false;
+    if (typeof geometry[property] !== "boolean") {
+        throw geometryClassificationError("malformed-geometry", `${shape} ${property} must be a boolean when present`, keys, shape);
+    }
+    return geometry[property];
+}
+function assertPosition(value, dimensions, shape, keys) {
+    const minimumArity = dimensions.hasZ ? 3 : 2;
+    const maximumArity = minimumArity + (dimensions.hasM ? 1 : 0);
+    if (!Array.isArray(value) || value.length < minimumArity || value.length > maximumArity || value.length > 4) {
+        throw geometryClassificationError("malformed-geometry", `${shape} positions must match declared hasZ/hasM dimensions and contain at most four ordinates`, keys, shape);
+    }
+    if (!isFiniteNumber(value[0]) || !isFiniteNumber(value[1])) {
+        throw geometryClassificationError("malformed-geometry", `${shape} positions require finite numeric x and y ordinates`, keys, shape);
+    }
+    if (dimensions.hasZ && !isFiniteNumber(value[2])) {
+        throw geometryClassificationError("malformed-geometry", `${shape} positions require a finite z ordinate when hasZ is true`, keys, shape);
+    }
+    if (dimensions.hasM && value.length === maximumArity) {
+        const measure = value[maximumArity - 1];
+        if (measure !== null && !isFiniteNumber(measure)) {
+            throw geometryClassificationError("malformed-geometry", `${shape} m ordinates must be finite numbers, null, or omitted`, keys, shape);
+        }
+    }
+}
+function assertEmptyMembers(geometry, members, shape, keys) {
+    const contradictory = members.filter((member) => hasOwn(geometry, member) && geometry[member] !== null);
+    if (contradictory.length > 0) {
+        throw geometryClassificationError("malformed-geometry", `${shape} empty sentinel conflicts with non-null members: ${contradictory.join(", ")}`, keys, shape);
+    }
+}
+function assertOptionalFiniteMember(geometry, property, shape, keys, allowNull = false) {
+    if (!hasOwn(geometry, property))
+        return;
+    const value = geometry[property];
+    if ((allowNull && value === null) || isFiniteNumber(value))
+        return;
+    const expectation = allowNull ? "a finite number or null" : "a finite number";
+    throw geometryClassificationError("malformed-geometry", `${shape} ${property} must be ${expectation} when present`, keys, shape);
+}
+function assertOptionalBounds(geometry, minimumProperty, maximumProperty, shape, keys) {
+    const hasMinimum = hasOwn(geometry, minimumProperty);
+    const hasMaximum = hasOwn(geometry, maximumProperty);
+    if (!hasMinimum && !hasMaximum)
+        return;
+    const minimum = geometry[minimumProperty];
+    const maximum = geometry[maximumProperty];
+    if (!hasMinimum || !hasMaximum || !isFiniteNumber(minimum) || !isFiniteNumber(maximum) || minimum > maximum) {
+        throw geometryClassificationError("malformed-geometry", `envelope ${minimumProperty}/${maximumProperty} must be a complete ordered pair of finite numbers`, keys, shape);
+    }
+}
+function geometryClassificationError(code, reason, keys, shape) {
+    return new HonuaGeometryError(code, `Unable to classify geometry: ${reason}`, {
+        operation: "classify",
+        reason,
+        keys,
+        ...(shape === undefined ? {} : { shape }),
+    });
 }

package/core/stac-static.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Static STAC catalog reader.
+ *
+ * A large share of public STAC catalogs are not API servers — they are
+ * static `catalog.json` / `collection.json` / item trees served from object
+ * storage, with no `/search` endpoint. This reader walks such a tree the
+ * spec-driven way: it follows `rel="child"` links to descend catalogs /
+ * collections and `rel="item"` links to reach STAC Items, resolving every
+ * href against the document it was found in (STAC best-practice relative
+ * links). Filtering (`collections` / `bbox` / `datetime` / `limit`) is
+ * applied client-side and the result is projected onto the same
+ * {@link HonuaStacItemCollectionResponse} envelope the STAC API search path
+ * returns, so the canonical `Source` surface is identical across both
+ * layouts.
+ *
+ * @module
+ */
+import type { SourceLocator } from "../contract/types.js";
+import type { HonuaClient } from "./client.js";
+import type { HonuaStacItemCollectionResponse } from "./types.js";
+/** Bounded search parameters for a static catalog traversal. */
+export interface StacStaticSearchParams {
+    collections?: readonly string[];
+    bbox?: readonly [number, number, number, number];
+    datetime?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Reader bound to the URL of a static STAC catalog / collection root. The
+ * URL is the client baseUrl (the transport resolves same-origin absolute
+ * child/item hrefs directly), so `rootUrl` is normally `""` (the baseUrl
+ * itself) but may be an absolute `catalog.json` URL.
+ */
+export declare class HonuaStacStaticCatalog {
+    readonly client: HonuaClient;
+    private readonly rootUrl;
+    private readonly policy;
+    constructor(client: HonuaClient, rootUrl?: string, policy?: SourceLocator["stacStatic"]);
+    /**
+     * Traverse the catalog tree, collect matching items, and return them in
+     * the STAC search envelope shape.
+     */
+    search(params?: StacStaticSearchParams): Promise<HonuaStacItemCollectionResponse>;
+    private fetchDoc;
+    /**
+     * Breadth-first walk collecting item documents. Descends `rel="child"`
+     * links; a `collections` filter prunes Collection subtrees whose `id`
+     * is not requested. Every attempted document, traversal depth, per-document
+     * link list, response body, redirect, and origin is bounded by the locator's
+     * admitted policy.
+     */
+    private collectItems;
+}
+//# sourceMappingURL=stac-static.d.ts.map

package/core/stac-static.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stac-static.d.ts","sourceRoot":"","sources":["../../../src/core/stac-static.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,EAAE,+BAA+B,EAAyB,MAAM,YAAY,CAAC;AAEzF,gEAAgE;AAChE,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AA6CD;;;;;GAKG;AACH,qBAAa,sBAAsB;IACjC,SAAgB,MAAM,EAAE,WAAW,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;gBAE7B,MAAM,EAAE,WAAW,EAAE,OAAO,SAAK,EAAE,MAAM,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC;IAM1F;;;OAGG;IACU,MAAM,CAAC,MAAM,GAAE,sBAA2B,GAAG,OAAO,CAAC,+BAA+B,CAAC;YAcpF,QAAQ;IA0BtB;;;;;;OAMG;YACW,YAAY;CAkE3B"}