@honua/react 0.0.20-alpha.0

package/core/stac.js

@@ -0,0 +1,229 @@
+/**
+ * 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 { createOgcMetadataParams, mergeHeaders } from "./wire-shared.js";
+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);
+            // Continuation is driven solely by the next-link cursor (and the
+            // maxPages cap). STAC permits a server to return fewer than `limit`
+            // items on a non-final page while still advertising a `rel=next` link,
+            // so a short page must not stop paging.
+            if (cursor.offset === undefined && cursor.next === undefined)
+                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);
+            // See searchAll: a short page is not a termination signal; rely on the
+            // next-link cursor and the maxPages cap.
+            if (cursor.offset === undefined && cursor.next === undefined)
+                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 });
+}
+// ── STAC API wire methods ───────────────────────────────────────
+export async function getStacLanding(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`stac:landing:${params.toString()}`, `/stac?${params.toString()}`, request);
+}
+export async function listStacCollections(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`stac:collections:${params.toString()}`, `/stac/collections?${params.toString()}`, request);
+}
+export async function getStacCollection(transport, request) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`stac:collection:${request.collectionId}:${params.toString()}`, `/stac/collections/${encodeURIComponent(String(request.collectionId))}?${params.toString()}`, request);
+}
+export async function getStacItem(transport, request) {
+    const params = createOgcMetadataParams(request);
+    const path = `/stac/collections/${encodeURIComponent(String(request.collectionId))}` +
+        `/items/${encodeURIComponent(String(request.itemId))}`;
+    return transport.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
+}
+export async function searchStac(transport, request = {}) {
+    if (request.usePost) {
+        return transport.requestJson("POST", "/stac/search", {
+            headers: mergeHeaders({ "Content-Type": "application/json", Accept: "application/json" }),
+            body: JSON.stringify(stacSearchBody(request)),
+        }, request.signal);
+    }
+    const params = serializeStacSearchParams(request);
+    return transport.requestJson("GET", `/stac/search?${params.toString()}`, undefined, request.signal);
+}
+function serializeStacSearchParams(request) {
+    const params = new URLSearchParams();
+    if (request.bbox !== undefined)
+        params.set("bbox", request.bbox.join(","));
+    if (request.datetime !== undefined)
+        params.set("datetime", request.datetime);
+    if (request.ids !== undefined && request.ids.length > 0)
+        params.set("ids", request.ids.join(","));
+    if (request.collections !== undefined && request.collections.length > 0) {
+        params.set("collections", request.collections.join(","));
+    }
+    // honua-server accepts `intersects` on GET as a JSON-encoded geometry
+    // and `fields` as a CSV with `-` prefix marking excludes (matches
+    // STAC Item Search GET conventions and the server's parser).
+    if (request.intersects !== undefined)
+        params.set("intersects", JSON.stringify(request.intersects));
+    const fields = stacFieldsCsv(request.fields);
+    if (fields !== undefined)
+        params.set("fields", fields);
+    if (request.filter !== undefined)
+        params.set("filter", request.filter);
+    if (request.filterLang !== undefined)
+        params.set("filter-lang", request.filterLang);
+    if (request.limit !== undefined)
+        params.set("limit", String(request.limit));
+    // honua-server uses numeric `offset` paging on GET. `next` is kept as
+    // optional support for STAC servers that advertise an opaque token.
+    if (request.offset !== undefined)
+        params.set("offset", String(request.offset));
+    if (request.next !== undefined)
+        params.set("next", request.next);
+    if (request.sortby !== undefined)
+        params.set("sortby", request.sortby);
+    return params;
+}
+function stacSearchBody(request) {
+    const out = {};
+    if (request.bbox !== undefined)
+        out.bbox = request.bbox;
+    if (request.datetime !== undefined)
+        out.datetime = request.datetime;
+    if (request.intersects !== undefined)
+        out.intersects = request.intersects;
+    if (request.ids !== undefined)
+        out.ids = request.ids;
+    if (request.collections !== undefined)
+        out.collections = request.collections;
+    if (request.filter !== undefined)
+        out.filter = request.filter;
+    if (request.filterLang !== undefined)
+        out["filter-lang"] = request.filterLang;
+    if (request.limit !== undefined)
+        out.limit = request.limit;
+    if (request.offset !== undefined)
+        out.offset = request.offset;
+    if (request.next !== undefined)
+        out.next = request.next;
+    if (request.sortby !== undefined)
+        out.sortby = request.sortby;
+    if (request.fields !== undefined)
+        out.fields = request.fields;
+    return out;
+}
+function stacFieldsCsv(fields) {
+    if (!fields)
+        return undefined;
+    const parts = [];
+    if (fields.include) {
+        for (const f of fields.include) {
+            if (typeof f === "string" && f.length > 0)
+                parts.push(f);
+        }
+    }
+    if (fields.exclude) {
+        for (const f of fields.exclude) {
+            if (typeof f === "string" && f.length > 0)
+                parts.push(`-${f}`);
+        }
+    }
+    return parts.length > 0 ? parts.join(",") : undefined;
+}