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

package/core/spatial-filter.js

@@ -0,0 +1,153 @@
+/**
+ * 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 function envelope(xmin, ymin, xmax, ymax, spatialReference) {
+    const geometry = { xmin, ymin, xmax, ymax };
+    if (spatialReference)
+        geometry.spatialReference = spatialReference;
+    return {
+        geometry,
+        geometryType: "esriGeometryEnvelope",
+        spatialRel: "esriSpatialRelIntersects",
+    };
+}
+/**
+ * Create a point spatial filter.
+ *
+ * @example
+ * ```ts
+ * const req: QueryFeaturesRequest = {
+ *   serviceId: "svc", layerId: 0,
+ *   ...point(-118.24, 34.05),
+ * };
+ * ```
+ */
+export function point(x, y, spatialReference) {
+    const geometry = { x, y };
+    if (spatialReference)
+        geometry.spatialReference = spatialReference;
+    return {
+        geometry,
+        geometryType: "esriGeometryPoint",
+        spatialRel: "esriSpatialRelIntersects",
+    };
+}
+/**
+ * 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 function polygon(rings, spatialReference) {
+    const geometry = { rings };
+    if (spatialReference)
+        geometry.spatialReference = spatialReference;
+    return {
+        geometry,
+        geometryType: "esriGeometryPolygon",
+        spatialRel: "esriSpatialRelIntersects",
+    };
+}
+/**
+ * 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 function buffer(x, y, distance, spatialReference) {
+    return envelope(x - distance, y - distance, x + distance, y + distance, spatialReference);
+}
+/**
+ * Wrap an existing geometry with `esriSpatialRelIntersects`.
+ *
+ * @example
+ * ```ts
+ * const filter = spatialIntersects({ xmin: -180, ymin: -90, xmax: 180, ymax: 90 });
+ * ```
+ */
+export function spatialIntersects(geometry) {
+    return {
+        geometry,
+        geometryType: detectGeometryType(geometry),
+        spatialRel: "esriSpatialRelIntersects",
+    };
+}
+/**
+ * Wrap an existing geometry with `esriSpatialRelContains`.
+ *
+ * @example
+ * ```ts
+ * const filter = spatialContains({ rings: [[[-118, 34], [-117, 34], [-117, 35], [-118, 35], [-118, 34]]] });
+ * ```
+ */
+export function spatialContains(geometry) {
+    return {
+        geometry,
+        geometryType: detectGeometryType(geometry),
+        spatialRel: "esriSpatialRelContains",
+    };
+}
+/**
+ * Wrap an existing geometry with `esriSpatialRelWithin`.
+ *
+ * @example
+ * ```ts
+ * const filter = spatialWithin({ rings: [[[-118, 34], [-117, 34], [-117, 35], [-118, 35], [-118, 34]]] });
+ * ```
+ */
+export function spatialWithin(geometry) {
+    return {
+        geometry,
+        geometryType: detectGeometryType(geometry),
+        spatialRel: "esriSpatialRelWithin",
+    };
+}
+/**
+ * Detect the Esri geometry type from a plain geometry object by inspecting
+ * its shape (duck-typing).
+ *
+ * @internal
+ */
+function detectGeometryType(geometry) {
+    if ("xmin" in geometry && "ymin" in geometry && "xmax" in geometry && "ymax" in geometry) {
+        return "esriGeometryEnvelope";
+    }
+    if ("rings" in geometry) {
+        return "esriGeometryPolygon";
+    }
+    if ("paths" in geometry) {
+        return "esriGeometryPolyline";
+    }
+    if ("points" in geometry) {
+        return "esriGeometryMultipoint";
+    }
+    if ("x" in geometry && "y" in geometry) {
+        return "esriGeometryPoint";
+    }
+    return "esriGeometryPoint";
+}

package/core/stac.d.ts

@@ -0,0 +1,43 @@
+/**
+ * STAC API search surface. STAC builds on OGC API Features, so this
+ * class wraps the STAC catalog landing, collections listing, items, and
+ * cross-collection search endpoints. The wire calls live on
+ * `HonuaClient`; this class is the request-shaping layer on top.
+ *
+ * @module
+ */
+import type { HonuaClient } from "./client.js";
+import type { HonuaOgcCollectionMetadata, HonuaOgcCollectionsResponse, HonuaStacItemCollectionResponse, HonuaStacItemResponse, HonuaStacLandingResponse, OgcCollectionRequest, OgcMetadataRequest, StacSearchRequest } from "./types.js";
+export interface HonuaStacSearchOptions {
+    client: HonuaClient;
+}
+export interface HonuaStacSearchAllRequest extends StacSearchRequest {
+    /** Maximum number of items to materialize across pages. */
+    pageSize?: number;
+    /** Hard cap on the number of pages to fetch (defaults to 100). */
+    maxPages?: number;
+}
+/**
+ * STAC API entry point. Discovery (`landing`, `collections`,
+ * `collection`) plus search (`search`, `searchAll`, `searchStream`) and
+ * item fetch.
+ */
+export declare class HonuaStacSearch {
+    readonly client: HonuaClient;
+    constructor(options: HonuaStacSearchOptions);
+    landing(request?: OgcMetadataRequest): Promise<HonuaStacLandingResponse>;
+    collections(request?: OgcMetadataRequest): Promise<HonuaOgcCollectionsResponse>;
+    collection(request: OgcCollectionRequest): Promise<HonuaOgcCollectionMetadata>;
+    item(request: {
+        collectionId: string | number;
+        itemId: string | number;
+        signal?: AbortSignal;
+        responseFormat?: string;
+        extraParams?: Record<string, string | number | boolean>;
+    }): Promise<HonuaStacItemResponse>;
+    search(request?: StacSearchRequest): Promise<HonuaStacItemCollectionResponse>;
+    searchAll(request?: HonuaStacSearchAllRequest): Promise<HonuaStacItemResponse[]>;
+    searchStream(request?: HonuaStacSearchAllRequest): AsyncGenerator<HonuaStacItemResponse[], void, undefined>;
+}
+export declare function createHonuaStacSearch(client: HonuaClient): HonuaStacSearch;
+//# sourceMappingURL=stac.d.ts.map

package/core/stac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stac.d.ts","sourceRoot":"","sources":["../../../src/core/stac.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EACV,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,yBAA0B,SAAQ,iBAAiB;IAClE,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,SAAgB,MAAM,EAAE,WAAW,CAAC;gBAEjB,OAAO,EAAE,sBAAsB;IAIrC,OAAO,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAI5E,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAInF,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAI9E,IAAI,CAAC,OAAO,EAAE;QACzB,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;QAC9B,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;KACzD,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIrB,MAAM,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,+BAA+B,CAAC;IAIjF,SAAS,CAAC,OAAO,GAAE,yBAA8B,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAsBnF,YAAY,CACxB,OAAO,GAAE,yBAA8B,GACtC,cAAc,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC;CAmB5D;AAkCD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAE1E"}

package/core/stac.js

@@ -0,0 +1,116 @@
+/**
+ * STAC API search surface. STAC builds on OGC API Features, so this
+ * class wraps the STAC catalog landing, collections listing, items, and
+ * cross-collection search endpoints. The wire calls live on
+ * `HonuaClient`; this class is the request-shaping layer on top.
+ *
+ * @module
+ */
+const DEFAULT_STAC_PAGE_SIZE = 100;
+const DEFAULT_STAC_MAX_PAGES = 100;
+/**
+ * STAC API entry point. Discovery (`landing`, `collections`,
+ * `collection`) plus search (`search`, `searchAll`, `searchStream`) and
+ * item fetch.
+ */
+export class HonuaStacSearch {
+    client;
+    constructor(options) {
+        this.client = options.client;
+    }
+    async landing(request = {}) {
+        return this.client.getStacLanding(request);
+    }
+    async collections(request = {}) {
+        return this.client.listStacCollections(request);
+    }
+    async collection(request) {
+        return this.client.getStacCollection(request);
+    }
+    async item(request) {
+        return this.client.getStacItem(request);
+    }
+    async search(request = {}) {
+        return this.client.searchStac(request);
+    }
+    async searchAll(request = {}) {
+        const pageSize = request.pageSize ?? request.limit ?? DEFAULT_STAC_PAGE_SIZE;
+        const maxPages = request.maxPages ?? DEFAULT_STAC_MAX_PAGES;
+        const items = [];
+        let cursor = { offset: request.offset, next: request.next };
+        for (let page = 0; page < maxPages; page += 1) {
+            const response = await this.client.searchStac({
+                ...request,
+                limit: pageSize,
+                offset: cursor.offset,
+                next: cursor.next,
+            });
+            const pageItems = response.features ?? [];
+            if (pageItems.length === 0)
+                break;
+            items.push(...pageItems);
+            cursor = nextStacCursor(response.links);
+            if (cursor.offset === undefined && cursor.next === undefined)
+                break;
+            if (pageItems.length < pageSize)
+                break;
+        }
+        return items;
+    }
+    async *searchStream(request = {}) {
+        const pageSize = request.pageSize ?? request.limit ?? DEFAULT_STAC_PAGE_SIZE;
+        const maxPages = request.maxPages ?? DEFAULT_STAC_MAX_PAGES;
+        let cursor = { offset: request.offset, next: request.next };
+        for (let page = 0; page < maxPages; page += 1) {
+            const response = await this.client.searchStac({
+                ...request,
+                limit: pageSize,
+                offset: cursor.offset,
+                next: cursor.next,
+            });
+            const pageItems = response.features ?? [];
+            if (pageItems.length === 0)
+                break;
+            yield pageItems;
+            cursor = nextStacCursor(response.links);
+            if (cursor.offset === undefined && cursor.next === undefined)
+                break;
+            if (pageItems.length < pageSize)
+                break;
+        }
+    }
+}
+/**
+ * Resolve the next-page cursor for STAC paging. honua-server emits a
+ * `rel=next` link with `?offset=N` on the href; some non-Honua STAC
+ * servers emit `?next=…` opaque tokens instead. Prefer `offset` when the
+ * link carries it, otherwise fall back to `next`. When the server omits
+ * a usable `rel=next` link, return an empty cursor so the caller stops.
+ */
+function nextStacCursor(links) {
+    if (!links)
+        return {};
+    for (const link of links) {
+        if (link.rel !== "next" || typeof link.href !== "string")
+            continue;
+        try {
+            const url = new URL(link.href, "https://placeholder.test");
+            const offsetParam = url.searchParams.get("offset");
+            if (offsetParam !== null) {
+                const offset = Number(offsetParam);
+                if (Number.isFinite(offset))
+                    return { offset };
+            }
+            const nextParam = url.searchParams.get("next");
+            if (nextParam !== null)
+                return { next: nextParam };
+        }
+        catch {
+            // ignore unparsable hrefs; keep scanning for a usable link
+        }
+    }
+    return {};
+}
+export function createHonuaStacSearch(client) {
+    return new HonuaStacSearch({ client });
+}