@honua/sdk-esri-compat 0.0.6-alpha.0

package/core/query-builder.js

@@ -0,0 +1,538 @@
+/**
+ * Fluent builder for constructing `QueryFeaturesRequest` objects.
+ *
+ * Create via `QueryBuilder.from(serviceId, layerId)` (standalone) or
+ * `QueryBuilder.for(client, serviceId, layerId)` (bound to a client for `.run()`).
+ *
+ * @example
+ * ```ts
+ * // Standalone — build request object
+ * const req = QueryBuilder.from("myService", 0)
+ *   .where("POP > 1000")
+ *   .outFields("NAME", "POP")
+ *   .limit(100)
+ *   .build();
+ *
+ * const result = await client.queryFeatures(req);
+ *
+ * // Bound — build and execute in one chain
+ * const result = await QueryBuilder.for(client, "myService", 0)
+ *   .where("POP > 1000")
+ *   .outFields("NAME", "POP")
+ *   .limit(100)
+ *   .run();
+ * ```
+ */
+export class QueryBuilder {
+    serviceId;
+    layerId;
+    boundClient;
+    whereClause;
+    fields;
+    geometryFilter;
+    geometryTypeValue;
+    spatialRelValue;
+    returnGeometryValue;
+    orderByFieldsValue;
+    resultOffsetValue;
+    resultRecordCountValue;
+    objectIdsValue;
+    returnDistinctValuesValue;
+    returnCentroidValue;
+    groupByFieldsValue;
+    outStatisticsValue;
+    methodValue;
+    signalValue;
+    extraParamsValue;
+    constructor(serviceId, layerId, client) {
+        this.serviceId = serviceId;
+        this.layerId = layerId;
+        this.boundClient = client;
+    }
+    /** Create a standalone builder (call `.build()` to get the request object). */
+    static from(serviceId, layerId) {
+        return new QueryBuilder(serviceId, layerId);
+    }
+    /** Create a builder bound to a client (enables `.run()` to execute the query). */
+    static for(client, serviceId, layerId) {
+        return new QueryBuilder(serviceId, layerId, client);
+    }
+    /** Set the WHERE clause for filtering features. */
+    where(clause) {
+        this.whereClause = clause;
+        return this;
+    }
+    /** Set the output fields to return. Accepts individual field names. */
+    outFields(...fieldNames) {
+        this.fields = fieldNames;
+        return this;
+    }
+    /** Set a geometry filter. Accepts a geometry object or JSON string. */
+    geometry(geom) {
+        this.geometryFilter = geom;
+        return this;
+    }
+    /** Set the geometry type for the geometry filter. */
+    geometryType(type) {
+        this.geometryTypeValue = type;
+        return this;
+    }
+    /** Set the spatial relationship for the geometry filter. */
+    spatialRel(rel) {
+        this.spatialRelValue = rel;
+        return this;
+    }
+    /** Whether to include geometry in the response. */
+    returnGeometry(value) {
+        this.returnGeometryValue = value;
+        return this;
+    }
+    /** Set the fields to order results by (e.g. `"NAME ASC"`). */
+    orderBy(fields) {
+        this.orderByFieldsValue = fields;
+        return this;
+    }
+    /** Set the maximum number of features to return. */
+    limit(count) {
+        this.resultRecordCountValue = count;
+        return this;
+    }
+    /** Set the number of features to skip (for pagination). */
+    offset(count) {
+        this.resultOffsetValue = count;
+        return this;
+    }
+    /** Filter by specific object IDs. */
+    objectIds(ids) {
+        this.objectIdsValue = ids;
+        return this;
+    }
+    /** Return only distinct values. */
+    distinct(value = true) {
+        this.returnDistinctValuesValue = value;
+        return this;
+    }
+    /** Return centroids instead of full geometries. */
+    returnCentroid(value = true) {
+        this.returnCentroidValue = value;
+        return this;
+    }
+    /** Set group-by fields for statistics queries. */
+    groupBy(fields) {
+        this.groupByFieldsValue = fields;
+        return this;
+    }
+    /** Set output statistics definitions. */
+    outStatistics(stats) {
+        this.outStatisticsValue = stats;
+        return this;
+    }
+    /** Set the HTTP method (GET or POST). */
+    method(m) {
+        this.methodValue = m;
+        return this;
+    }
+    /** Attach an AbortSignal for cancellation. */
+    signal(s) {
+        this.signalValue = s;
+        return this;
+    }
+    /** Set extra query parameters. */
+    extraParams(params) {
+        this.extraParamsValue = params;
+        return this;
+    }
+    /** Build the `QueryFeaturesRequest` object without executing it. */
+    build() {
+        const request = {
+            serviceId: this.serviceId,
+            layerId: this.layerId,
+        };
+        if (this.whereClause !== undefined)
+            request.where = this.whereClause;
+        if (this.fields !== undefined)
+            request.outFields = this.fields;
+        if (this.geometryFilter !== undefined)
+            request.geometry = this.geometryFilter;
+        if (this.geometryTypeValue !== undefined)
+            request.geometryType = this.geometryTypeValue;
+        if (this.spatialRelValue !== undefined)
+            request.spatialRel = this.spatialRelValue;
+        if (this.returnGeometryValue !== undefined)
+            request.returnGeometry = this.returnGeometryValue;
+        if (this.orderByFieldsValue !== undefined)
+            request.orderByFields = this.orderByFieldsValue;
+        if (this.resultOffsetValue !== undefined)
+            request.resultOffset = this.resultOffsetValue;
+        if (this.resultRecordCountValue !== undefined)
+            request.resultRecordCount = this.resultRecordCountValue;
+        if (this.objectIdsValue !== undefined)
+            request.objectIds = this.objectIdsValue;
+        if (this.returnDistinctValuesValue !== undefined)
+            request.returnDistinctValues = this.returnDistinctValuesValue;
+        if (this.returnCentroidValue !== undefined)
+            request.returnCentroid = this.returnCentroidValue;
+        if (this.groupByFieldsValue !== undefined)
+            request.groupByFieldsForStatistics = this.groupByFieldsValue;
+        if (this.outStatisticsValue !== undefined)
+            request.outStatistics = this.outStatisticsValue;
+        if (this.methodValue !== undefined)
+            request.method = this.methodValue;
+        if (this.signalValue !== undefined)
+            request.signal = this.signalValue;
+        if (this.extraParamsValue !== undefined)
+            request.extraParams = this.extraParamsValue;
+        return request;
+    }
+    /**
+     * Build the request and execute it via the bound client.
+     * Throws if the builder was created with `QueryBuilder.from()` (no client).
+     */
+    async run() {
+        if (!this.boundClient) {
+            throw new Error("QueryBuilder.run() requires a bound client. Use QueryBuilder.for(client, ...) or call .build() and pass to client.queryFeatures().");
+        }
+        return this.boundClient.queryFeatures(this.build());
+    }
+}
+/**
+ * Fluent builder for constructing `MapLayerQueryRequest` objects.
+ *
+ * Create via `MapLayerQueryBuilder.from(serviceId, layerId)` (standalone) or
+ * `MapLayerQueryBuilder.for(client, serviceId, layerId)` (bound to a client for `.run()`).
+ *
+ * @example
+ * ```ts
+ * // Standalone — build request object
+ * const req = MapLayerQueryBuilder.from("myService", 0)
+ *   .where("POP > 1000")
+ *   .outFields("NAME", "POP")
+ *   .limit(100)
+ *   .build();
+ *
+ * const result = await client.queryMapLayer(req);
+ *
+ * // Bound — build and execute in one chain
+ * const result = await MapLayerQueryBuilder.for(client, "myService", 0)
+ *   .where("POP > 1000")
+ *   .outFields("NAME", "POP")
+ *   .limit(100)
+ *   .run();
+ * ```
+ */
+export class MapLayerQueryBuilder {
+    serviceId;
+    layerId;
+    boundClient;
+    whereClause;
+    fields;
+    geometryFilter;
+    geometryTypeValue;
+    spatialRelValue;
+    returnGeometryValue;
+    orderByFieldsValue;
+    resultOffsetValue;
+    resultRecordCountValue;
+    objectIdsValue;
+    returnDistinctValuesValue;
+    returnCentroidValue;
+    groupByFieldsValue;
+    outStatisticsValue;
+    methodValue;
+    signalValue;
+    extraParamsValue;
+    constructor(serviceId, layerId, client) {
+        this.serviceId = serviceId;
+        this.layerId = layerId;
+        this.boundClient = client;
+    }
+    /** Create a standalone builder (call `.build()` to get the request object). */
+    static from(serviceId, layerId) {
+        return new MapLayerQueryBuilder(serviceId, layerId);
+    }
+    /** Create a builder bound to a client (enables `.run()` to execute the query). */
+    static for(client, serviceId, layerId) {
+        return new MapLayerQueryBuilder(serviceId, layerId, client);
+    }
+    /** Set the WHERE clause for filtering features. */
+    where(clause) {
+        this.whereClause = clause;
+        return this;
+    }
+    /** Set the output fields to return. Accepts individual field names. */
+    outFields(...fieldNames) {
+        this.fields = fieldNames;
+        return this;
+    }
+    /** Set a geometry filter. Accepts a geometry object or JSON string. */
+    geometry(geom) {
+        this.geometryFilter = geom;
+        return this;
+    }
+    /** Set the geometry type for the geometry filter. */
+    geometryType(type) {
+        this.geometryTypeValue = type;
+        return this;
+    }
+    /** Set the spatial relationship for the geometry filter. */
+    spatialRel(rel) {
+        this.spatialRelValue = rel;
+        return this;
+    }
+    /** Whether to include geometry in the response. */
+    returnGeometry(value) {
+        this.returnGeometryValue = value;
+        return this;
+    }
+    /** Set the fields to order results by (e.g. `"NAME ASC"`). */
+    orderBy(fields) {
+        this.orderByFieldsValue = fields;
+        return this;
+    }
+    /** Set the maximum number of features to return. */
+    limit(count) {
+        this.resultRecordCountValue = count;
+        return this;
+    }
+    /** Set the number of features to skip (for pagination). */
+    offset(count) {
+        this.resultOffsetValue = count;
+        return this;
+    }
+    /** Filter by specific object IDs. */
+    objectIds(ids) {
+        this.objectIdsValue = ids;
+        return this;
+    }
+    /** Return only distinct values. */
+    distinct(value = true) {
+        this.returnDistinctValuesValue = value;
+        return this;
+    }
+    /** Return centroids instead of full geometries. */
+    returnCentroid(value = true) {
+        this.returnCentroidValue = value;
+        return this;
+    }
+    /** Set group-by fields for statistics queries. */
+    groupBy(fields) {
+        this.groupByFieldsValue = fields;
+        return this;
+    }
+    /** Set output statistics definitions. */
+    outStatistics(stats) {
+        this.outStatisticsValue = stats;
+        return this;
+    }
+    /** Set the HTTP method (GET or POST). */
+    method(m) {
+        this.methodValue = m;
+        return this;
+    }
+    /** Attach an AbortSignal for cancellation. */
+    signal(s) {
+        this.signalValue = s;
+        return this;
+    }
+    /** Set extra query parameters. */
+    extraParams(params) {
+        this.extraParamsValue = params;
+        return this;
+    }
+    /** Build the `MapLayerQueryRequest` object without executing it. */
+    build() {
+        const request = {
+            serviceId: this.serviceId,
+            layerId: this.layerId,
+        };
+        if (this.whereClause !== undefined)
+            request.where = this.whereClause;
+        if (this.fields !== undefined)
+            request.outFields = this.fields;
+        if (this.geometryFilter !== undefined)
+            request.geometry = this.geometryFilter;
+        if (this.geometryTypeValue !== undefined)
+            request.geometryType = this.geometryTypeValue;
+        if (this.spatialRelValue !== undefined)
+            request.spatialRel = this.spatialRelValue;
+        if (this.returnGeometryValue !== undefined)
+            request.returnGeometry = this.returnGeometryValue;
+        if (this.orderByFieldsValue !== undefined)
+            request.orderByFields = this.orderByFieldsValue;
+        if (this.resultOffsetValue !== undefined)
+            request.resultOffset = this.resultOffsetValue;
+        if (this.resultRecordCountValue !== undefined)
+            request.resultRecordCount = this.resultRecordCountValue;
+        if (this.objectIdsValue !== undefined)
+            request.objectIds = this.objectIdsValue;
+        if (this.returnDistinctValuesValue !== undefined)
+            request.returnDistinctValues = this.returnDistinctValuesValue;
+        if (this.returnCentroidValue !== undefined)
+            request.returnCentroid = this.returnCentroidValue;
+        if (this.groupByFieldsValue !== undefined)
+            request.groupByFieldsForStatistics = this.groupByFieldsValue;
+        if (this.outStatisticsValue !== undefined)
+            request.outStatistics = this.outStatisticsValue;
+        if (this.methodValue !== undefined)
+            request.method = this.methodValue;
+        if (this.signalValue !== undefined)
+            request.signal = this.signalValue;
+        if (this.extraParamsValue !== undefined)
+            request.extraParams = this.extraParamsValue;
+        return request;
+    }
+    /**
+     * Build the request and execute it via the bound client.
+     * Throws if the builder was created with `MapLayerQueryBuilder.from()` (no client).
+     */
+    async run() {
+        if (!this.boundClient) {
+            throw new Error("MapLayerQueryBuilder.run() requires a bound client. Use MapLayerQueryBuilder.for(client, ...) or call .build() and pass to client.queryMapLayer().");
+        }
+        return this.boundClient.queryMapLayer(this.build());
+    }
+}
+/**
+ * Fluent builder for constructing `OgcItemsRequest` objects.
+ *
+ * Create via `OgcQueryBuilder.from(collectionId)` (standalone) or
+ * `OgcQueryBuilder.for(client, collectionId)` (bound to a client for `.run()`).
+ *
+ * @example
+ * ```ts
+ * // Standalone — build request object
+ * const req = OgcQueryBuilder.from("rivers")
+ *   .limit(50)
+ *   .bbox("-180,-90,180,90")
+ *   .build();
+ *
+ * const result = await client.listOgcItems(req);
+ *
+ * // Bound — build and execute in one chain
+ * const result = await OgcQueryBuilder.for(client, "rivers")
+ *   .limit(50)
+ *   .bbox("-180,-90,180,90")
+ *   .run();
+ * ```
+ */
+export class OgcQueryBuilder {
+    collectionId;
+    boundClient;
+    limitValue;
+    offsetValue;
+    bboxValue;
+    datetimeValue;
+    filterValue;
+    idsValue;
+    propertiesValue;
+    sortbyValue;
+    crsValue;
+    signalValue;
+    responseFormatValue;
+    constructor(collectionId, client) {
+        this.collectionId = collectionId;
+        this.boundClient = client;
+    }
+    /** Create a standalone builder (call `.build()` to get the request object). */
+    static from(collectionId) {
+        return new OgcQueryBuilder(collectionId);
+    }
+    /** Create a builder bound to a client (enables `.run()` to execute the query). */
+    static for(client, collectionId) {
+        return new OgcQueryBuilder(collectionId, client);
+    }
+    /** Set the maximum number of items to return. */
+    limit(n) {
+        this.limitValue = n;
+        return this;
+    }
+    /** Set the number of items to skip (for pagination). */
+    offset(n) {
+        this.offsetValue = n;
+        return this;
+    }
+    /** Set the bounding box filter (e.g. `"-180,-90,180,90"`). */
+    bbox(value) {
+        this.bboxValue = value;
+        return this;
+    }
+    /** Set the datetime filter (e.g. `"2020-01-01T00:00:00Z/.."`). */
+    datetime(value) {
+        this.datetimeValue = value;
+        return this;
+    }
+    /** Set the CQL2 filter expression. */
+    filter(value) {
+        this.filterValue = value;
+        return this;
+    }
+    /** Filter by specific feature IDs. */
+    ids(...idValues) {
+        this.idsValue = idValues;
+        return this;
+    }
+    /** Set the properties to return. */
+    properties(...props) {
+        this.propertiesValue = props;
+        return this;
+    }
+    /** Set the sort order (e.g. `"+name"` or `"-pop"`). */
+    sortby(value) {
+        this.sortbyValue = value;
+        return this;
+    }
+    /** Set the coordinate reference system URI. */
+    crs(value) {
+        this.crsValue = value;
+        return this;
+    }
+    /** Attach an AbortSignal for cancellation. */
+    signal(s) {
+        this.signalValue = s;
+        return this;
+    }
+    /** Set the response format (e.g. `"json"`, `"geojson"`). */
+    responseFormat(fmt) {
+        this.responseFormatValue = fmt;
+        return this;
+    }
+    /** Build the `OgcItemsRequest` object without executing it. */
+    build() {
+        const request = {
+            collectionId: this.collectionId,
+        };
+        if (this.limitValue !== undefined)
+            request.limit = this.limitValue;
+        if (this.offsetValue !== undefined)
+            request.offset = this.offsetValue;
+        if (this.bboxValue !== undefined)
+            request.bbox = this.bboxValue;
+        if (this.datetimeValue !== undefined)
+            request.datetime = this.datetimeValue;
+        if (this.filterValue !== undefined)
+            request.filter = this.filterValue;
+        if (this.idsValue !== undefined)
+            request.ids = this.idsValue;
+        if (this.propertiesValue !== undefined)
+            request.properties = this.propertiesValue;
+        if (this.sortbyValue !== undefined)
+            request.sortby = this.sortbyValue;
+        if (this.crsValue !== undefined)
+            request.crs = this.crsValue;
+        if (this.signalValue !== undefined)
+            request.signal = this.signalValue;
+        if (this.responseFormatValue !== undefined)
+            request.responseFormat = this.responseFormatValue;
+        return request;
+    }
+    /**
+     * Build the request and execute it via the bound client.
+     * Throws if the builder was created with `OgcQueryBuilder.from()` (no client).
+     */
+    async run() {
+        if (!this.boundClient) {
+            throw new Error("OgcQueryBuilder.run() requires a bound client. Use OgcQueryBuilder.for(client, ...) or call .build() and pass to client.listOgcItems().");
+        }
+        return this.boundClient.listOgcItems(this.build());
+    }
+}

package/core/spatial-filter.d.ts

@@ -0,0 +1,93 @@
+import type { EsriGeometryType, EsriSpatialRel, HonuaSpatialReference } from "./types.js";
+/**
+ * A spatial filter fragment that can be spread into a `QueryFeaturesRequest`
+ * or applied via `QueryBuilder.geometry()` / `.geometryType()` / `.spatialRel()`.
+ */
+export interface SpatialFilter {
+    geometry: Record<string, unknown>;
+    geometryType: EsriGeometryType;
+    spatialRel?: EsriSpatialRel;
+}
+/**
+ * Create an envelope (bounding box) spatial filter.
+ *
+ * @example
+ * ```ts
+ * const req: QueryFeaturesRequest = {
+ *   serviceId: "svc", layerId: 0,
+ *   ...envelope(-118.5, 33.7, -117.5, 34.2),
+ * };
+ * ```
+ */
+export declare function envelope(xmin: number, ymin: number, xmax: number, ymax: number, spatialReference?: HonuaSpatialReference): SpatialFilter;
+/**
+ * Create a point spatial filter.
+ *
+ * @example
+ * ```ts
+ * const req: QueryFeaturesRequest = {
+ *   serviceId: "svc", layerId: 0,
+ *   ...point(-118.24, 34.05),
+ * };
+ * ```
+ */
+export declare function point(x: number, y: number, spatialReference?: HonuaSpatialReference): SpatialFilter;
+/**
+ * Create a polygon spatial filter from an array of rings.
+ *
+ * @example
+ * ```ts
+ * const req: QueryFeaturesRequest = {
+ *   serviceId: "svc", layerId: 0,
+ *   ...polygon([[[-118, 34], [-117, 34], [-117, 35], [-118, 35], [-118, 34]]]),
+ * };
+ * ```
+ */
+export declare function polygon(rings: number[][][], spatialReference?: HonuaSpatialReference): SpatialFilter;
+/**
+ * Create an envelope spatial filter centered on a point, approximating a
+ * circular buffer as a bounding box.
+ *
+ * @param x - Center x coordinate
+ * @param y - Center y coordinate
+ * @param distance - Half-width of the envelope in coordinate units
+ * @param spatialReference - Optional spatial reference
+ *
+ * @example
+ * ```ts
+ * // 0.5-degree bounding box around a point
+ * const req: QueryFeaturesRequest = {
+ *   serviceId: "svc", layerId: 0,
+ *   ...buffer(-118.24, 34.05, 0.5),
+ * };
+ * ```
+ */
+export declare function buffer(x: number, y: number, distance: number, spatialReference?: HonuaSpatialReference): SpatialFilter;
+/**
+ * Wrap an existing geometry with `esriSpatialRelIntersects`.
+ *
+ * @example
+ * ```ts
+ * const filter = spatialIntersects({ xmin: -180, ymin: -90, xmax: 180, ymax: 90 });
+ * ```
+ */
+export declare function spatialIntersects(geometry: Record<string, unknown>): SpatialFilter;
+/**
+ * Wrap an existing geometry with `esriSpatialRelContains`.
+ *
+ * @example
+ * ```ts
+ * const filter = spatialContains({ rings: [[[-118, 34], [-117, 34], [-117, 35], [-118, 35], [-118, 34]]] });
+ * ```
+ */
+export declare function spatialContains(geometry: Record<string, unknown>): SpatialFilter;
+/**
+ * Wrap an existing geometry with `esriSpatialRelWithin`.
+ *
+ * @example
+ * ```ts
+ * const filter = spatialWithin({ rings: [[[-118, 34], [-117, 34], [-117, 35], [-118, 35], [-118, 34]]] });
+ * ```
+ */
+export declare function spatialWithin(geometry: Record<string, unknown>): SpatialFilter;
+//# sourceMappingURL=spatial-filter.d.ts.map

package/core/spatial-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial-filter.d.ts","sourceRoot":"","sources":["../../../src/core/spatial-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE1F;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,YAAY,EAAE,gBAAgB,CAAC;IAC/B,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,gBAAgB,CAAC,EAAE,qBAAqB,GACvC,aAAa,CAQf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,qBAAqB,GAAG,aAAa,CAQnG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,gBAAgB,CAAC,EAAE,qBAAqB,GAAG,aAAa,CAQpG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CACpB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,QAAQ,EAAE,MAAM,EAChB,gBAAgB,CAAC,EAAE,qBAAqB,GACvC,aAAa,CAEf;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,CAMlF;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,CAMhF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,CAM9E"}