@honua/react 0.0.20-alpha.0

package/core/geoservices.js

@@ -0,0 +1,434 @@
+/**
+ * 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 { encodeServiceIdPath } from "./path-utils.js";
+// ── Metadata ────────────────────────────────────────────────────
+export async function listServices(transport, format, options = {}) {
+    const query = new URLSearchParams({ f: format });
+    const path = `/rest/services?${query.toString()}`;
+    return transport.requestCachedMetadataJson(`geoservices:services:${format}`, path, options);
+}
+export async function getLayerMetadata(transport, serviceId, layerId, options = {}) {
+    const query = new URLSearchParams({ f: "json" });
+    const path = `/rest/services/${encodeServiceIdPath(serviceId)}/FeatureServer/${layerId}?${query.toString()}`;
+    return transport.requestCachedMetadataJson(`geoservices-feature:${serviceId}:${layerId}`, path, options);
+}
+export async function getFeatureServiceMetadata(transport, serviceId, options = {}) {
+    const query = new URLSearchParams({ f: "json" });
+    const path = `/rest/services/${encodeServiceIdPath(serviceId)}/FeatureServer?${query.toString()}`;
+    return transport.requestCachedMetadataJson(`geoservices-feature:${serviceId}:service`, path, options);
+}
+export async function getMapServiceMetadata(transport, serviceId, options = {}) {
+    const query = new URLSearchParams({ f: "json" });
+    const path = `/rest/services/${encodeServiceIdPath(serviceId)}/MapServer?${query.toString()}`;
+    return transport.requestCachedMetadataJson(`geoservices-map:${serviceId}:service`, path, options);
+}
+export async function getMapLayerMetadata(transport, serviceId, layerId, options = {}) {
+    const query = new URLSearchParams({ f: "json" });
+    const path = `/rest/services/${encodeServiceIdPath(serviceId)}/MapServer/${layerId}?${query.toString()}`;
+    return transport.requestCachedMetadataJson(`geoservices-map:${serviceId}:${layerId}`, path, options);
+}
+// ── FeatureServer / MapServer operations ────────────────────────
+/**
+ * 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 async function queryFeaturesRest(transport, request, preferBinary) {
+    const method = request.method ?? "GET";
+    const usePbf = preferBinary && method === "GET";
+    const params = new URLSearchParams();
+    params.set("f", usePbf ? "pbf" : "json");
+    params.set("where", request.where ?? "1=1");
+    params.set("outFields", normalizeOutFields(request.outFields));
+    params.set("returnGeometry", String(request.returnGeometry ?? true));
+    serializeQueryParams(params, request);
+    appendQueryExtraParams(params, request);
+    const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/FeatureServer/${request.layerId}/query`;
+    if (usePbf) {
+        return transport.requestBinaryWithJsonFallback("GET", `${path}?${params.toString()}`, params, request.signal);
+    }
+    if (method === "GET") {
+        return transport.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
+    }
+    return transport.requestJson("POST", path, {
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    }, request.signal);
+}
+export async function queryMapLayer(transport, request) {
+    const method = request.method ?? "GET";
+    const params = new URLSearchParams();
+    params.set("f", "json");
+    params.set("where", request.where ?? "1=1");
+    params.set("outFields", normalizeOutFields(request.outFields));
+    params.set("returnGeometry", String(request.returnGeometry ?? true));
+    serializeQueryParams(params, request);
+    appendQueryExtraParams(params, request);
+    const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/MapServer/${request.layerId}/query`;
+    if (method === "GET") {
+        return transport.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
+    }
+    return transport.requestJson("POST", path, {
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    }, request.signal);
+}
+export async function applyEdits(transport, request) {
+    const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/FeatureServer/${request.layerId}/applyEdits`;
+    const params = new URLSearchParams();
+    params.set("f", "json");
+    params.set("rollbackOnFailure", String(request.rollbackOnFailure ?? true));
+    if (request.adds !== undefined) {
+        params.set("adds", encodeFormValue(request.adds));
+    }
+    if (request.updates !== undefined) {
+        params.set("updates", encodeFormValue(request.updates));
+    }
+    if (request.deletes !== undefined) {
+        params.set("deletes", encodeDeletesValue(request.deletes));
+    }
+    return transport.requestJson("POST", path, {
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    }, request.signal);
+}
+export async function queryRelatedRecords(transport, request) {
+    const method = request.method ?? "GET";
+    const params = new URLSearchParams();
+    params.set("f", "json");
+    params.set("relationshipId", String(request.relationshipId));
+    if (request.objectIds !== undefined) {
+        params.set("objectIds", Array.isArray(request.objectIds) ? request.objectIds.join(",") : String(request.objectIds));
+    }
+    params.set("where", request.where ?? "1=1");
+    params.set("outFields", normalizeOutFields(request.outFields));
+    params.set("returnGeometry", String(request.returnGeometry ?? true));
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}` +
+        `/FeatureServer/${request.layerId}/queryRelatedRecords`;
+    if (method === "GET") {
+        return transport.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
+    }
+    return transport.requestJson("POST", path, {
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    }, request.signal);
+}
+export async function queryMapRelatedRecords(transport, request) {
+    const method = request.method ?? "GET";
+    const params = new URLSearchParams();
+    params.set("f", "json");
+    params.set("relationshipId", String(request.relationshipId));
+    if (request.objectIds !== undefined) {
+        params.set("objectIds", Array.isArray(request.objectIds) ? request.objectIds.join(",") : String(request.objectIds));
+    }
+    params.set("where", request.where ?? "1=1");
+    params.set("outFields", normalizeOutFields(request.outFields));
+    params.set("returnGeometry", String(request.returnGeometry ?? true));
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}` + `/MapServer/${request.layerId}/queryRelatedRecords`;
+    if (method === "GET") {
+        return transport.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
+    }
+    return transport.requestJson("POST", path, {
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    }, request.signal);
+}
+export async function exportMap(transport, request) {
+    const method = request.method ?? "GET";
+    const params = new URLSearchParams();
+    params.set("f", request.responseFormat ?? "json");
+    params.set("bbox", normalizeBBox(request.bbox));
+    params.set("size", normalizeSize(request.size));
+    if (request.format !== undefined) {
+        params.set("format", request.format);
+    }
+    if (request.dpi !== undefined) {
+        params.set("dpi", String(request.dpi));
+    }
+    if (request.transparent !== undefined) {
+        params.set("transparent", String(request.transparent));
+    }
+    if (request.layers !== undefined) {
+        params.set("layers", request.layers);
+    }
+    if (request.bboxSr !== undefined) {
+        params.set("bboxSR", String(request.bboxSr));
+    }
+    if (request.imageSr !== undefined) {
+        params.set("imageSR", String(request.imageSr));
+    }
+    if (request.backgroundColor !== undefined) {
+        params.set("backgroundColor", request.backgroundColor);
+    }
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/MapServer/export`;
+    if (method === "GET") {
+        return transport.requestJson("GET", `${path}?${params.toString()}`);
+    }
+    return transport.requestJson("POST", path, {
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    });
+}
+export async function getMapLegend(transport, request) {
+    const params = new URLSearchParams();
+    params.set("f", request.responseFormat ?? "json");
+    if (request.size !== undefined) {
+        params.set("size", normalizeLegendSize(request.size));
+    }
+    if (request.dynamicLayers !== undefined) {
+        params.set("dynamicLayers", request.dynamicLayers);
+    }
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/MapServer/legend`;
+    return transport.requestJson("GET", `${path}?${params.toString()}`);
+}
+export async function identifyMap(transport, request) {
+    const method = request.method ?? "GET";
+    const params = new URLSearchParams();
+    params.set("f", request.responseFormat ?? "json");
+    params.set("geometry", normalizeIdentifyGeometry(request.geometry));
+    params.set("geometryType", request.geometryType ?? "esriGeometryPoint");
+    params.set("mapExtent", normalizeMapExtent(request.mapExtent));
+    params.set("imageDisplay", normalizeImageDisplay(request.imageDisplay));
+    params.set("returnGeometry", String(request.returnGeometry ?? true));
+    params.set("tolerance", String(request.tolerance ?? 3));
+    if (request.sr !== undefined) {
+        params.set("sr", String(request.sr));
+    }
+    if (request.layers !== undefined) {
+        params.set("layers", request.layers);
+    }
+    if (request.maxAllowableOffset !== undefined) {
+        params.set("maxAllowableOffset", String(request.maxAllowableOffset));
+    }
+    if (request.layerDefs !== undefined) {
+        params.set("layerDefs", request.layerDefs);
+    }
+    if (request.dynamicLayers !== undefined) {
+        params.set("dynamicLayers", request.dynamicLayers);
+    }
+    if (request.time !== undefined) {
+        params.set("time", request.time);
+    }
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/MapServer/identify`;
+    if (method === "GET") {
+        return transport.requestJson("GET", `${path}?${params.toString()}`);
+    }
+    return transport.requestJson("POST", path, {
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    });
+}
+export async function findMap(transport, request) {
+    const method = request.method ?? "GET";
+    const params = new URLSearchParams();
+    params.set("f", request.responseFormat ?? "json");
+    params.set("searchText", request.searchText);
+    params.set("contains", String(request.contains ?? true));
+    if (request.searchFields !== undefined) {
+        params.set("searchFields", normalizeSearchFields(request.searchFields));
+    }
+    if (request.layers !== undefined) {
+        params.set("layers", request.layers);
+    }
+    if (request.sr !== undefined) {
+        params.set("sr", String(request.sr));
+    }
+    if (request.layerDefs !== undefined) {
+        params.set("layerDefs", request.layerDefs);
+    }
+    if (request.returnGeometry !== undefined) {
+        params.set("returnGeometry", String(request.returnGeometry));
+    }
+    if (request.maxAllowableOffset !== undefined) {
+        params.set("maxAllowableOffset", String(request.maxAllowableOffset));
+    }
+    if (request.dynamicLayers !== undefined) {
+        params.set("dynamicLayers", request.dynamicLayers);
+    }
+    if (request.returnZ !== undefined) {
+        params.set("returnZ", String(request.returnZ));
+    }
+    if (request.returnM !== undefined) {
+        params.set("returnM", String(request.returnM));
+    }
+    if (request.gdbVersion !== undefined) {
+        params.set("gdbVersion", request.gdbVersion);
+    }
+    if (request.time !== undefined) {
+        params.set("time", request.time);
+    }
+    if (request.relationParam !== undefined) {
+        params.set("relationParam", request.relationParam);
+    }
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    const path = `/rest/services/${encodeServiceIdPath(request.serviceId)}/MapServer/find`;
+    if (method === "GET") {
+        return transport.requestJson("GET", `${path}?${params.toString()}`);
+    }
+    return transport.requestJson("POST", path, {
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    });
+}
+// ── Param serialization helpers ─────────────────────────────────
+function normalizeOutFields(outFields) {
+    if (outFields === undefined) {
+        return "*";
+    }
+    if (Array.isArray(outFields)) {
+        return outFields.length > 0 ? outFields.join(",") : "";
+    }
+    return outFields;
+}
+function encodeFormValue(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return JSON.stringify(value);
+}
+function encodeDeletesValue(value) {
+    if (Array.isArray(value)) {
+        return value.join(",");
+    }
+    return String(value);
+}
+function normalizeBBox(bbox) {
+    return Array.isArray(bbox) ? bbox.join(",") : bbox;
+}
+function normalizeSize(size) {
+    return Array.isArray(size) ? size.join(",") : size;
+}
+function normalizeLegendSize(size) {
+    if (typeof size === "number") {
+        return String(size);
+    }
+    if (Array.isArray(size)) {
+        return size.join(",");
+    }
+    return size;
+}
+function normalizeIdentifyGeometry(geometry) {
+    return typeof geometry === "string" ? geometry : JSON.stringify(geometry);
+}
+function normalizeMapExtent(mapExtent) {
+    return Array.isArray(mapExtent) ? mapExtent.join(",") : mapExtent;
+}
+function normalizeImageDisplay(imageDisplay) {
+    return Array.isArray(imageDisplay) ? imageDisplay.join(",") : imageDisplay;
+}
+function normalizeSearchFields(searchFields) {
+    if (!searchFields) {
+        return "";
+    }
+    return Array.isArray(searchFields) ? searchFields.join(",") : searchFields;
+}
+function serializeQueryParams(params, request) {
+    if (request.outSr !== undefined) {
+        params.set("outSR", typeof request.outSr === "object" && request.outSr !== null
+            ? JSON.stringify(request.outSr)
+            : String(request.outSr));
+    }
+    if (request.orderByFields !== undefined) {
+        params.set("orderByFields", request.orderByFields);
+    }
+    if (request.objectIds !== undefined) {
+        params.set("objectIds", Array.isArray(request.objectIds) ? request.objectIds.join(",") : String(request.objectIds));
+    }
+    if (request.geometry !== undefined) {
+        params.set("geometry", typeof request.geometry === "object" && request.geometry !== null
+            ? JSON.stringify(request.geometry)
+            : String(request.geometry));
+    }
+    if (request.geometryType !== undefined) {
+        params.set("geometryType", request.geometryType);
+    }
+    if (request.spatialRel !== undefined) {
+        params.set("spatialRel", request.spatialRel);
+    }
+    if (request.returnDistinctValues !== undefined) {
+        params.set("returnDistinctValues", String(request.returnDistinctValues));
+    }
+    if (request.returnCentroid !== undefined) {
+        params.set("returnCentroid", String(request.returnCentroid));
+    }
+    if (request.groupByFieldsForStatistics !== undefined) {
+        params.set("groupByFieldsForStatistics", request.groupByFieldsForStatistics);
+    }
+    if (request.outStatistics !== undefined) {
+        params.set("outStatistics", Array.isArray(request.outStatistics) ? JSON.stringify(request.outStatistics) : String(request.outStatistics));
+    }
+    if (request.resultOffset !== undefined) {
+        params.set("resultOffset", String(request.resultOffset));
+    }
+    if (request.resultRecordCount !== undefined) {
+        params.set("resultRecordCount", String(request.resultRecordCount));
+    }
+}
+function appendQueryExtraParams(params, request) {
+    if (!request.extraParams) {
+        return;
+    }
+    for (const [key, value] of Object.entries(request.extraParams)) {
+        if (request.outSr !== undefined && (key === "outSr" || key === "outSR")) {
+            continue;
+        }
+        params.set(key, String(value));
+    }
+}

package/core/grpc-adapter.d.ts

@@ -0,0 +1,23 @@
+import { type FeaturePage, type QueryFeaturesResponse } from "../gen/honua/v1/feature_service_pb.js";
+import type { HonuaCountResponse, HonuaExtentResponse, HonuaFeature, HonuaObjectIdsResponse, HonuaQueryResponse, QueryFeaturesRequest } from "./types.js";
+/**
+ * Converts a SDK QueryFeaturesRequest into a proto QueryFeaturesRequest message.
+ */
+export declare function toProtoQueryRequest(request: QueryFeaturesRequest): import("../gen/honua/v1/feature_service_pb.js").QueryFeaturesRequest;
+/**
+ * Converts a proto QueryFeaturesResponse into the JSON-compatible shape
+ * matching the `f=json` response format.
+ */
+export declare function fromProtoQueryResponse(response: QueryFeaturesResponse): HonuaQueryResponse | HonuaCountResponse | HonuaObjectIdsResponse | HonuaExtentResponse;
+/**
+ * Converts a stream of proto FeaturePages into an async generator
+ * that yields arrays of JSON-compatible features, matching the
+ * existing queryFeaturesStream yield type.
+ */
+export declare function streamProtoPages(stream: AsyncIterable<FeaturePage>): AsyncGenerator<HonuaFeature[], void, undefined>;
+/**
+ * Wraps a ConnectError (or any error from the gRPC transport) in a
+ * HonuaGrpcError for consistent `instanceof` discrimination.
+ */
+export declare function wrapConnectError(error: unknown): Error;
+//# sourceMappingURL=grpc-adapter.d.ts.map

package/core/grpc-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grpc-adapter.d.ts","sourceRoot":"","sources":["../../../src/core/grpc-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,WAAW,EAWhB,KAAK,qBAAqB,EAM3B,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EAEZ,sBAAsB,EACtB,kBAAkB,EAElB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAwFpB;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,wEAoIhE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,qBAAqB,GAC9B,kBAAkB,GAAG,kBAAkB,GAAG,sBAAsB,GAAG,mBAAmB,CAkDxF;AA0UD;;;;GAIG;AACH,wBAAuB,gBAAgB,CACrC,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,GACjC,cAAc,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAiBjD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAYtD"}