@honua/react 0.0.20-alpha.0

package/core/esri-geojson.js

@@ -0,0 +1,363 @@
+/**
+ * Convert Esri-JSON geometry (as returned by `queryFeatures` and contract
+ * {@link HonuaFeature} results) into standard GeoJSON geometry.
+ *
+ * Esri encodes geometry as `{ x, y }` points, `{ paths }` polylines,
+ * `{ rings }` polygons, `{ points }` multipoints, and `{ xmin, ymin, xmax,
+ * ymax }` envelopes. GeoJSON consumers (MapLibre, Leaflet, turf, etc.) expect
+ * `Point` / `LineString` / `Polygon` and their `Multi*` variants. This module
+ * provides that translation as a first-class, dependency-free utility.
+ *
+ * Polygon rings are grouped following the Esri convention where clockwise
+ * rings are exterior and counter-clockwise rings are holes, producing `Polygon`
+ * for a single exterior ring and `MultiPolygon` when several exterior rings are
+ * present. The emitted rings are rewound to the GeoJSON RFC 7946 right-hand rule
+ * (counter-clockwise exterior, clockwise holes) so conformant consumers do not
+ * interpret polygons inside-out.
+ *
+ * @module
+ */
+function isFinitePosition(value) {
+    return (Array.isArray(value) &&
+        value.length >= 2 &&
+        typeof value[0] === "number" &&
+        Number.isFinite(value[0]) &&
+        typeof value[1] === "number" &&
+        Number.isFinite(value[1]));
+}
+function collectFinitePositions(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter(isFinitePosition);
+}
+function collectPositionSets(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((entry) => collectFinitePositions(entry)).filter((entry) => entry.length > 0);
+}
+function computeRingSignedArea(ring) {
+    if (ring.length < 3) {
+        return 0;
+    }
+    let area = 0;
+    for (let index = 0; index < ring.length; index += 1) {
+        const current = ring[index];
+        const next = ring[(index + 1) % ring.length];
+        if (!current || !next) {
+            continue;
+        }
+        area += current[0] * next[1] - next[0] * current[1];
+    }
+    return area / 2;
+}
+/**
+ * Esri uses clockwise (negative signed area in screen/standard math
+ * orientation) rings for exterior boundaries and counter-clockwise rings for
+ * holes.
+ */
+function isExteriorRing(ring) {
+    return computeRingSignedArea(ring) < 0;
+}
+function isPointOnSegment(point, segmentStart, segmentEnd) {
+    const epsilon = 1e-9;
+    const crossProduct = (point[0] - segmentStart[0]) * (segmentEnd[1] - segmentStart[1]) -
+        (point[1] - segmentStart[1]) * (segmentEnd[0] - segmentStart[0]);
+    if (Math.abs(crossProduct) > epsilon) {
+        return false;
+    }
+    const dotProduct = (point[0] - segmentStart[0]) * (segmentEnd[0] - segmentStart[0]) +
+        (point[1] - segmentStart[1]) * (segmentEnd[1] - segmentStart[1]);
+    if (dotProduct < -epsilon) {
+        return false;
+    }
+    const segmentLengthSquared = (segmentEnd[0] - segmentStart[0]) * (segmentEnd[0] - segmentStart[0]) +
+        (segmentEnd[1] - segmentStart[1]) * (segmentEnd[1] - segmentStart[1]);
+    return dotProduct - segmentLengthSquared <= epsilon;
+}
+function isPointInsideRing(point, ring) {
+    if (ring.length < 3) {
+        return false;
+    }
+    let isInside = false;
+    for (let index = 0, previousIndex = ring.length - 1; index < ring.length; previousIndex = index, index += 1) {
+        const current = ring[index];
+        const previous = ring[previousIndex];
+        if (!current || !previous) {
+            continue;
+        }
+        if (isPointOnSegment(point, previous, current)) {
+            return true;
+        }
+        const intersects = current[1] > point[1] !== previous[1] > point[1] &&
+            point[0] < ((previous[0] - current[0]) * (point[1] - current[1])) / (previous[1] - current[1]) + current[0];
+        if (intersects) {
+            isInside = !isInside;
+        }
+    }
+    return isInside;
+}
+function findContainingPolygonIndex(polygons, outerAreas, ring) {
+    const samplePoint = ring[0];
+    if (!samplePoint) {
+        return -1;
+    }
+    let containingPolygonIndex = -1;
+    let smallestContainingArea = Number.POSITIVE_INFINITY;
+    for (let index = 0; index < polygons.length; index += 1) {
+        const polygon = polygons[index];
+        const outerRing = polygon?.[0];
+        const outerArea = outerAreas[index];
+        if (!outerRing || outerArea === undefined || !isPointInsideRing(samplePoint, outerRing)) {
+            continue;
+        }
+        if (outerArea < smallestContainingArea) {
+            smallestContainingArea = outerArea;
+            containingPolygonIndex = index;
+        }
+    }
+    return containingPolygonIndex;
+}
+/**
+ * Rewind a ring to the GeoJSON RFC 7946 §3.1.6 right-hand rule: exterior rings
+ * counter-clockwise (positive signed area), interior rings (holes) clockwise
+ * (negative signed area). Esri uses the opposite convention (clockwise
+ * exterior), so emitting Esri rings verbatim produces GeoJSON that
+ * RFC 7946-conformant consumers (and the S2 spherical winding used by some
+ * renderers) interpret inside-out.
+ */
+function rewindRingForGeoJson(ring, exterior) {
+    const copy = ring.map((position) => [...position]);
+    const area = computeRingSignedArea(copy);
+    if (area === 0) {
+        return copy;
+    }
+    const correctlyWound = exterior ? area > 0 : area < 0;
+    return correctlyWound ? copy : copy.reverse();
+}
+function rewindPolygonForGeoJson(polygon) {
+    return polygon.map((ring, index) => rewindRingForGeoJson(ring, index === 0));
+}
+function convertPolygonRings(rings) {
+    const polygons = [];
+    const outerAreas = [];
+    const interiorRings = [];
+    for (const ring of rings) {
+        if (isExteriorRing(ring)) {
+            polygons.push([ring]);
+            outerAreas.push(Math.abs(computeRingSignedArea(ring)));
+            continue;
+        }
+        interiorRings.push(ring);
+    }
+    for (const ring of interiorRings) {
+        const containingPolygonIndex = findContainingPolygonIndex(polygons, outerAreas, ring);
+        if (containingPolygonIndex < 0) {
+            polygons.push([ring]);
+            outerAreas.push(Math.abs(computeRingSignedArea(ring)));
+            continue;
+        }
+        polygons[containingPolygonIndex]?.push(ring);
+    }
+    return polygons.length === 1
+        ? {
+            type: "Polygon",
+            coordinates: rewindPolygonForGeoJson(polygons[0] ?? []),
+        }
+        : {
+            type: "MultiPolygon",
+            coordinates: polygons.map(rewindPolygonForGeoJson),
+        };
+}
+function hasNumber(geometry, key) {
+    return typeof geometry[key] === "number" && Number.isFinite(geometry[key]);
+}
+/**
+ * Convert a single Esri-JSON geometry into a GeoJSON geometry.
+ *
+ * Supports Esri point (`{ x, y }`), multipoint (`{ points }`), polyline
+ * (`{ paths }`), polygon (`{ rings }`), and envelope (`{ xmin, ymin, xmax,
+ * ymax }`) shapes. Returns `null` for `null`/`undefined` input and for
+ * geometries that contain no finite coordinates (e.g. empty `rings`/`paths`).
+ *
+ * @param geometry Esri geometry, the `geometry` field of a {@link HonuaFeature},
+ *   or `null`/`undefined`.
+ * @returns The equivalent GeoJSON geometry, or `null` when the input is empty
+ *   or unrecognized.
+ */
+export function esriGeometryToGeoJSON(geometry) {
+    if (!geometry || typeof geometry !== "object") {
+        return null;
+    }
+    const candidate = geometry;
+    if (hasNumber(candidate, "x") && hasNumber(candidate, "y")) {
+        return {
+            type: "Point",
+            coordinates: [candidate.x, candidate.y],
+        };
+    }
+    if (Array.isArray(candidate.points)) {
+        const coordinates = collectFinitePositions(candidate.points);
+        if (coordinates.length < 1) {
+            return null;
+        }
+        return {
+            type: "MultiPoint",
+            coordinates,
+        };
+    }
+    if (Array.isArray(candidate.paths)) {
+        const coordinates = collectPositionSets(candidate.paths);
+        if (coordinates.length < 1) {
+            return null;
+        }
+        return coordinates.length === 1
+            ? {
+                type: "LineString",
+                coordinates: coordinates[0] ?? [],
+            }
+            : {
+                type: "MultiLineString",
+                coordinates,
+            };
+    }
+    if (Array.isArray(candidate.rings)) {
+        const coordinates = collectPositionSets(candidate.rings);
+        if (coordinates.length < 1) {
+            return null;
+        }
+        return convertPolygonRings(coordinates);
+    }
+    if (hasNumber(candidate, "xmin") &&
+        hasNumber(candidate, "ymin") &&
+        hasNumber(candidate, "xmax") &&
+        hasNumber(candidate, "ymax")) {
+        const xmin = candidate.xmin;
+        const ymin = candidate.ymin;
+        const xmax = candidate.xmax;
+        const ymax = candidate.ymax;
+        return {
+            type: "Polygon",
+            coordinates: [
+                [
+                    [xmin, ymin],
+                    [xmax, ymin],
+                    [xmax, ymax],
+                    [xmin, ymax],
+                    [xmin, ymin],
+                ],
+            ],
+        };
+    }
+    return null;
+}
+function readFeatureId(feature) {
+    const attributes = feature.attributes ?? {};
+    const candidates = [attributes.OBJECTID, attributes.objectid, attributes.id, attributes.ID, attributes.FID];
+    for (const value of candidates) {
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return value;
+        }
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Convert a contract {@link HonuaFeature} (Esri attributes + geometry) into a
+ * GeoJSON `Feature`.
+ *
+ * The feature `id` is derived from common Esri identifier attributes
+ * (`OBJECTID`, `objectid`, `id`, `ID`, `FID`) when present, and the geometry is
+ * converted with {@link esriGeometryToGeoJSON} (yielding `null` for missing or
+ * empty geometry).
+ *
+ * @param feature A contract feature with Esri-shaped `attributes` and
+ *   `geometry`.
+ * @returns The equivalent GeoJSON feature.
+ */
+export function esriFeatureToGeoJSON(feature) {
+    const id = readFeatureId(feature);
+    return {
+        type: "Feature",
+        ...(id === undefined ? {} : { id }),
+        geometry: esriGeometryToGeoJSON(feature.geometry),
+        properties: feature.attributes ?? {},
+    };
+}
+// ── GeoJSON → Esri (reverse of esriGeometryToGeoJSON) ─────────────
+//
+// The forward converter rewinds rings to the GeoJSON RFC 7946 right-hand rule
+// (counter-clockwise exterior). Esri uses the opposite convention (clockwise
+// exterior, counter-clockwise holes), so this reverse converter rewinds each
+// ring back to the Esri orientation before emitting `{ rings }`.
+function rewindRingForEsri(ring, exterior) {
+    const copy = ring.map((position) => [...position]);
+    const area = computeRingSignedArea(copy);
+    if (area === 0) {
+        return copy;
+    }
+    // Esri: exterior rings are clockwise (negative signed area), holes are
+    // counter-clockwise (positive signed area).
+    const correctlyWound = exterior ? area < 0 : area > 0;
+    return correctlyWound ? copy : copy.reverse();
+}
+function esriRingsFromPolygon(coordinates) {
+    return coordinates.map((ring, index) => rewindRingForEsri(ring, index === 0));
+}
+/**
+ * Convert a standard GeoJSON geometry back into Esri-JSON geometry, the inverse
+ * of {@link esriGeometryToGeoJSON}. `GeometryCollection` is not representable as
+ * a single Esri geometry and yields `null`.
+ *
+ * Polygon/MultiPolygon rings are rewound to the Esri winding convention
+ * (clockwise exterior, counter-clockwise holes) and MultiPolygons are flattened
+ * into a single `{ rings }` list, matching how Esri encodes multi-part polygons.
+ *
+ * @param geometry A GeoJSON geometry, or `null`/`undefined`.
+ * @param spatialReference Optional spatial reference stamped onto the emitted
+ *   Esri geometry (Esri geometries are CRS-tagged; GeoJSON is implicitly WGS84).
+ * @returns The equivalent Esri geometry, or `null` when the input is empty or
+ *   unrepresentable.
+ */
+export function geoJsonToEsriGeometry(geometry, spatialReference) {
+    if (!geometry || typeof geometry !== "object") {
+        return null;
+    }
+    const sr = spatialReference ? { spatialReference } : {};
+    switch (geometry.type) {
+        case "Point": {
+            const [x, y] = geometry.coordinates;
+            if (typeof x !== "number" || typeof y !== "number") {
+                return null;
+            }
+            return { x, y, ...sr };
+        }
+        case "MultiPoint": {
+            return { points: geometry.coordinates.map((position) => [...position]), ...sr };
+        }
+        case "LineString": {
+            return { paths: [geometry.coordinates.map((position) => [...position])], ...sr };
+        }
+        case "MultiLineString": {
+            return {
+                paths: geometry.coordinates.map((line) => line.map((position) => [...position])),
+                ...sr,
+            };
+        }
+        case "Polygon": {
+            return { rings: esriRingsFromPolygon(geometry.coordinates), ...sr };
+        }
+        case "MultiPolygon": {
+            const rings = [];
+            for (const polygon of geometry.coordinates) {
+                rings.push(...esriRingsFromPolygon(polygon));
+            }
+            return { rings, ...sr };
+        }
+        default:
+            return null;
+    }
+}

package/core/geoservices.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Esri GeoServices wire methods: service/layer metadata plus the
+ * FeatureServer / MapServer operation endpoints (query, applyEdits,
+ * related-records, export, legend, identify, find). Concrete URL-building
+ * and param serialization invoked against an injected
+ * {@link HonuaProtocolTransport}. The `HonuaClient` facade delegates here;
+ * the gRPC-web fast path for `queryFeatures` is orchestrated by the client.
+ *
+ * @module
+ */
+import type { HonuaMetadataRequestOptions } from "./cache-state.js";
+import type { HonuaProtocolTransport } from "./protocol-transport.js";
+import type { ApplyEditsRequest, ExportMapRequest, HonuaApplyEditsResponse, HonuaExportMapResponse, HonuaFindResponse, HonuaIdentifyResponse, HonuaLayerMetadata, HonuaLegendResponse, HonuaQueryResponse, HonuaRelatedRecordsResponse, HonuaServiceMetadata, HonuaServicesResponse, MapFindRequest, MapIdentifyRequest, MapLayerQueryRequest, MapLegendRequest, MapRelatedRecordsRequest, QueryFeaturesRequest, QueryRelatedRecordsRequest } from "./types.js";
+export declare function listServices(transport: HonuaProtocolTransport, format: "json" | "pjson", options?: HonuaMetadataRequestOptions): Promise<HonuaServicesResponse>;
+export declare function getLayerMetadata(transport: HonuaProtocolTransport, serviceId: string, layerId: number, options?: HonuaMetadataRequestOptions): Promise<HonuaLayerMetadata>;
+export declare function getFeatureServiceMetadata(transport: HonuaProtocolTransport, serviceId: string, options?: HonuaMetadataRequestOptions): Promise<HonuaServiceMetadata>;
+export declare function getMapServiceMetadata(transport: HonuaProtocolTransport, serviceId: string, options?: HonuaMetadataRequestOptions): Promise<HonuaServiceMetadata>;
+export declare function getMapLayerMetadata(transport: HonuaProtocolTransport, serviceId: string, layerId: number, options?: HonuaMetadataRequestOptions): Promise<HonuaLayerMetadata>;
+/**
+ * REST portion of `client.queryFeatures` (the gRPC-web fast path is
+ * orchestrated by the client). Maps directly to the FeatureServer `query`
+ * endpoint, optionally negotiating a PBF response on `GET` when
+ * `preferBinary` is set.
+ */
+export declare function queryFeaturesRest(transport: HonuaProtocolTransport, request: QueryFeaturesRequest, preferBinary: boolean): Promise<HonuaQueryResponse>;
+export declare function queryMapLayer(transport: HonuaProtocolTransport, request: MapLayerQueryRequest): Promise<HonuaQueryResponse>;
+export declare function applyEdits(transport: HonuaProtocolTransport, request: ApplyEditsRequest): Promise<HonuaApplyEditsResponse>;
+export declare function queryRelatedRecords(transport: HonuaProtocolTransport, request: QueryRelatedRecordsRequest): Promise<HonuaRelatedRecordsResponse>;
+export declare function queryMapRelatedRecords(transport: HonuaProtocolTransport, request: MapRelatedRecordsRequest): Promise<HonuaRelatedRecordsResponse>;
+export declare function exportMap(transport: HonuaProtocolTransport, request: ExportMapRequest): Promise<HonuaExportMapResponse>;
+export declare function getMapLegend(transport: HonuaProtocolTransport, request: MapLegendRequest): Promise<HonuaLegendResponse>;
+export declare function identifyMap(transport: HonuaProtocolTransport, request: MapIdentifyRequest): Promise<HonuaIdentifyResponse>;
+export declare function findMap(transport: HonuaProtocolTransport, request: MapFindRequest): Promise<HonuaFindResponse>;
+//# sourceMappingURL=geoservices.d.ts.map

package/core/geoservices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geoservices.d.ts","sourceRoot":"","sources":["../../../src/core/geoservices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAEpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,2BAA2B,EAC3B,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EAEpB,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAIpB,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,MAAM,GAAG,OAAO,EACxB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,qBAAqB,CAAC,CAIhC;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAED,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,sBAAsB,EACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAID;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,EAC7B,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,kBAAkB,CAAC,CAsC7B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CA2B7B;AAED,wBAAsB,UAAU,CAC9B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CA0BlC;AAED,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,2BAA2B,CAAC,CAyCtC;AAED,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,2BAA2B,CAAC,CAwCtC;AAED,wBAAsB,SAAS,CAC7B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,sBAAsB,CAAC,CA6CjC;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAiB9B;AAED,wBAAsB,WAAW,CAC/B,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CA8ChC;AAED,wBAAsB,OAAO,CAAC,SAAS,EAAE,sBAAsB,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2DpH"}