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

package/contract/types.js

@@ -0,0 +1,171 @@
+/**
+ * Shared client contract — canonical nouns that all protocol adapters
+ * (`HonuaFeatureLayer`, `HonuaMapService`, `HonuaOgcFeatureCollection`, plus
+ * future WFS / WMS / OData adapters) must speak. The contract is documented
+ * in `docs/shared-client-contract.md`; capability coverage by protocol is
+ * documented in `docs/protocol-capability-matrix.md`.
+ *
+ * The runtime classes in `src/core/surfaces.ts` are not replaced — they
+ * remain the implementation. The contract here wraps their request /
+ * response shapes (`QueryFeaturesRequest`, `OgcItemsRequest`,
+ * `HonuaTypedQueryResponse`, `HonuaOgcFeatureCollectionResponse`) so that
+ * cross-protocol code can speak one vocabulary without re-litigating the
+ * surface in every downstream ticket.
+ *
+ * @module
+ */
+/** All protocol identifiers, in declaration order. */
+export const PROTOCOLS = [
+    "geoservices-feature-service",
+    "geoservices-map-service",
+    "geoservices-image-service",
+    "geoservices-geometry-service",
+    "geoservices-gp-service",
+    "ogc-features",
+    "ogc-tiles",
+    "ogc-maps",
+    "stac",
+    "wfs",
+    "wms",
+    "wmts",
+    "odata",
+    "maplibre-vector",
+    "maplibre-raster",
+    "maplibre-geojson",
+];
+/** All capability identifiers, in declaration order. */
+export const CAPABILITIES = [
+    "query",
+    "queryAggregate",
+    "spatialAggregate",
+    "queryExtent",
+    "queryObjectIds",
+    "queryRelated",
+    "applyEdits",
+    "attachments",
+    "render",
+    "tiles",
+    "sql",
+    "stream",
+    "pbf",
+    "connect",
+    "image",
+    "geometry",
+    "geoprocess",
+    "processes",
+];
+/**
+ * Build a `Capabilities` set from a readonly array. Provided as a tiny
+ * helper so callers do not need to import `Set` literals at every adapter
+ * site.
+ */
+export function capabilities(values) {
+    return new Set(values);
+}
+/**
+ * Compute the **weakest** (intersected) capability set across one or
+ * more participating sources / descriptors. This is the canonical helper
+ * for cross-protocol capability negotiation in a mixed-source
+ * composition (`#22`): a composition supports a capability only when
+ * **every** participating source supports it.
+ *
+ * Promising a capability the weakest source lacks is the worst possible
+ * mixed-source failure mode (silent wrong result), so consumers should
+ * always intersect before fanning a query out to a heterogeneous set.
+ *
+ * Accepts anything with a `capabilities` field (live `Source` instances
+ * or plain `SourceDescriptor`s). Empty input returns an empty set.
+ *
+ * For per-operation reasoning across a heterogeneous mix, partition
+ * sources first (e.g., feature sources only) and intersect on the
+ * partition; intersecting a render-only source with a feature source
+ * yields the empty set, which is honest but rarely actionable on its
+ * own.
+ */
+export function intersectCapabilities(participants) {
+    if (participants.length === 0)
+        return new Set();
+    const [first, ...rest] = participants;
+    const out = new Set(first.capabilities);
+    for (const next of rest) {
+        for (const cap of out) {
+            if (!next.capabilities.has(cap))
+                out.delete(cap);
+        }
+        if (out.size === 0)
+            return out;
+    }
+    return out;
+}
+/**
+ * Companion of {@link intersectCapabilities}: the union (best-case)
+ * capability set across participants. Useful for documenting what
+ * capability fan-out under `degraded` policy could reach if every
+ * source were queried independently — never use this to gate a single
+ * fan-out call (that needs the intersection).
+ */
+export function unionCapabilities(participants) {
+    const out = new Set();
+    for (const participant of participants) {
+        for (const cap of participant.capabilities)
+            out.add(cap);
+    }
+    return out;
+}
+/**
+ * Default capability sets keyed by protocol. Callers that need a narrower
+ * surface for a specific source must intersect the default set themselves
+ * and pass the result on `SourceDescriptor.capabilities`; the built-in
+ * adapter constructors do not read service metadata today.
+ *
+ * The matrix here mirrors the one in `docs/protocol-capability-matrix.md`.
+ * Update both together.
+ */
+export const PROTOCOL_DEFAULT_CAPABILITIES = {
+    "geoservices-feature-service": capabilities([
+        "query",
+        "queryAggregate",
+        "queryExtent",
+        "queryObjectIds",
+        "queryRelated",
+        "applyEdits",
+        "attachments",
+        "sql",
+        "stream",
+        "pbf",
+        "connect",
+    ]),
+    "geoservices-map-service": capabilities([
+        "query",
+        "queryAggregate",
+        "queryExtent",
+        "queryObjectIds",
+        "queryRelated",
+        "render",
+        "tiles",
+        "sql",
+        "stream",
+    ]),
+    "geoservices-image-service": capabilities([
+        "query",
+        "queryExtent",
+        "queryObjectIds",
+        "image",
+        "render",
+        "tiles",
+        "connect",
+    ]),
+    "geoservices-geometry-service": capabilities(["geometry", "connect"]),
+    "geoservices-gp-service": capabilities(["geoprocess", "connect"]),
+    "ogc-features": capabilities(["query", "queryObjectIds", "applyEdits", "stream"]),
+    "ogc-tiles": capabilities(["render", "tiles"]),
+    "ogc-maps": capabilities(["render"]),
+    stac: capabilities(["query", "queryObjectIds", "stream"]),
+    wfs: capabilities(["query", "queryExtent", "queryObjectIds", "applyEdits", "stream"]),
+    wms: capabilities(["render", "tiles", "query"]),
+    wmts: capabilities(["render", "tiles"]),
+    odata: capabilities(["query", "queryObjectIds", "stream", "applyEdits"]),
+    "maplibre-vector": capabilities(["render", "tiles"]),
+    "maplibre-raster": capabilities(["render", "tiles"]),
+    "maplibre-geojson": capabilities(["render"]),
+};

package/core/batch.d.ts

@@ -0,0 +1,37 @@
+import type { HonuaClient } from "./client.js";
+import type { HonuaQueryResponse, MapLayerQueryRequest, QueryFeaturesRequest } from "./types.js";
+/** A single query item in a batch. */
+export interface BatchQueryItem {
+    /** When `"map-layer"`, calls `client.queryMapLayer()`; default is `"feature"`. */
+    type?: "feature" | "map-layer";
+    /** The query request payload. */
+    request: QueryFeaturesRequest | MapLayerQueryRequest;
+    /** Optional label to identify this query in the results. */
+    label?: string;
+}
+/** The result of a single query within a batch. */
+export interface BatchQueryResult {
+    /** The label from the corresponding `BatchQueryItem`, if provided. */
+    label?: string;
+    /** The successful query response, or `undefined` if the query failed. */
+    response?: HonuaQueryResponse;
+    /** The error thrown by the query, or `undefined` if the query succeeded. */
+    error?: Error;
+}
+/** Options for controlling batch query execution. */
+export interface BatchQueryOptions {
+    /** Maximum number of concurrent queries. Default: `5`. */
+    concurrency?: number;
+    /** An `AbortSignal` that, when aborted, skips all remaining unstarted queries. */
+    signal?: AbortSignal;
+}
+/**
+ * Execute multiple queries in parallel with bounded concurrency.
+ *
+ * Results are returned in the same order as the input `items`.
+ * Each result contains either a `response` (on success) or an `error` (on failure).
+ * If an `AbortSignal` is provided and aborted, remaining unstarted queries are
+ * skipped and their results will have an `error` set to an `AbortError`.
+ */
+export declare function batchQuery(client: HonuaClient, items: readonly BatchQueryItem[], options?: BatchQueryOptions): Promise<BatchQueryResult[]>;
+//# sourceMappingURL=batch.d.ts.map

package/core/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../src/core/batch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEjG,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,IAAI,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IAC/B,iCAAiC;IACjC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IACrD,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiF7B"}

package/core/batch.js

@@ -0,0 +1,78 @@
+/**
+ * Execute multiple queries in parallel with bounded concurrency.
+ *
+ * Results are returned in the same order as the input `items`.
+ * Each result contains either a `response` (on success) or an `error` (on failure).
+ * If an `AbortSignal` is provided and aborted, remaining unstarted queries are
+ * skipped and their results will have an `error` set to an `AbortError`.
+ */
+export async function batchQuery(client, items, options) {
+    const concurrency = Math.max(1, options?.concurrency ?? 5);
+    const signal = options?.signal;
+    const results = new Array(items.length);
+    // Simple semaphore: track how many queries are currently in-flight.
+    let running = 0;
+    const queue = [];
+    function release() {
+        running--;
+        const next = queue.shift();
+        if (next) {
+            next();
+        }
+    }
+    function acquire() {
+        if (running < concurrency) {
+            running++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            queue.push(() => {
+                running++;
+                resolve();
+            });
+        });
+    }
+    const promises = [];
+    for (let i = 0; i < items.length; i++) {
+        const index = i;
+        const item = items[index];
+        const task = async () => {
+            // Check abort before acquiring a semaphore slot.
+            if (signal?.aborted) {
+                results[index] = {
+                    label: item.label,
+                    error: new DOMException("The operation was aborted.", "AbortError"),
+                };
+                return;
+            }
+            await acquire();
+            // Check abort again after acquiring the slot.
+            if (signal?.aborted) {
+                release();
+                results[index] = {
+                    label: item.label,
+                    error: new DOMException("The operation was aborted.", "AbortError"),
+                };
+                return;
+            }
+            try {
+                const response = item.type === "map-layer"
+                    ? await client.queryMapLayer(item.request)
+                    : await client.queryFeatures(item.request);
+                results[index] = { label: item.label, response };
+            }
+            catch (err) {
+                results[index] = {
+                    label: item.label,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                };
+            }
+            finally {
+                release();
+            }
+        };
+        promises.push(task());
+    }
+    await Promise.all(promises);
+    return results;
+}

package/core/cache-state.d.ts

@@ -0,0 +1,76 @@
+export type HonuaCacheScope = "metadata" | "materialized-result";
+export type HonuaCacheStatus = "hit" | "miss" | "stale" | "refreshed" | "bypass";
+export type HonuaCacheReadMode = "default" | "bypass";
+export interface HonuaCacheValidator {
+    readonly etag?: string;
+    readonly lastModified?: string;
+}
+export interface HonuaCacheState {
+    readonly scope: HonuaCacheScope;
+    readonly status: HonuaCacheStatus;
+    readonly keyFingerprint: string;
+    readonly ageMs?: number;
+    readonly ttlMs?: number;
+    readonly staleIfErrorMs?: number;
+    readonly revalidatedAt?: string;
+    readonly sourceUpdatedAt?: string;
+    readonly validator?: HonuaCacheValidator;
+    readonly invalidationReason?: string;
+    readonly refreshErrorId?: string;
+}
+export interface HonuaMetadataRequestOptions {
+    readonly signal?: AbortSignal;
+    /**
+     * Revalidate even when an SDK-local metadata entry is present. Adapters send
+     * conditional validators when available and report `refreshed` on success.
+     */
+    readonly refresh?: boolean;
+    /**
+     * `default` reads and writes the adapter metadata cache. `bypass` skips cache
+     * lookup and write-through for endpoints that support SDK-local caching.
+     */
+    readonly cache?: HonuaCacheReadMode;
+    /**
+     * Allow a cached metadata entry to be returned as `stale` when refresh fails.
+     * Defaults to `true`; ignored when no cached metadata entry exists.
+     */
+    readonly staleIfError?: boolean;
+    /** Optional freshness budget surfaced to callers in `HonuaCacheState`. */
+    readonly ttlMs?: number;
+    /** Optional stale fallback window surfaced to callers in `HonuaCacheState`. */
+    readonly staleIfErrorMs?: number;
+}
+export interface NormalizedHonuaMetadataRequestOptions {
+    readonly signal?: AbortSignal;
+    readonly refresh: boolean;
+    readonly cache: HonuaCacheReadMode;
+    readonly staleIfError: boolean;
+    readonly ttlMs?: number;
+    readonly staleIfErrorMs?: number;
+}
+export interface HonuaCacheStateInit {
+    readonly scope: HonuaCacheScope;
+    readonly status: HonuaCacheStatus;
+    readonly keyFingerprint: string;
+    readonly ageMs?: number;
+    readonly ttlMs?: number;
+    readonly staleIfErrorMs?: number;
+    readonly revalidatedAt?: string;
+    readonly sourceUpdatedAt?: string;
+    readonly validator?: HonuaCacheValidator;
+    readonly invalidationReason?: string;
+    readonly refreshErrorId?: string;
+}
+export declare function createHonuaCacheState(init: HonuaCacheStateInit): HonuaCacheState;
+export declare function normalizeHonuaMetadataRequestOptions(options?: HonuaMetadataRequestOptions): NormalizedHonuaMetadataRequestOptions;
+export declare function isHonuaCacheStatus(value: unknown): value is HonuaCacheStatus;
+export declare function honuaCacheValidatorFromHeaders(headers: Headers): HonuaCacheValidator | undefined;
+export declare function honuaMetadataRequestHeaders(options: {
+    readonly accept?: string;
+    readonly refresh?: boolean;
+    readonly bypass?: boolean;
+    readonly validator?: HonuaCacheValidator;
+}): Record<string, string>;
+export declare function withHonuaCacheState<T>(value: T, cache: HonuaCacheState): T;
+export declare function withoutHonuaCacheState<T>(value: T): T;
+//# sourceMappingURL=cache-state.d.ts.map

package/core/cache-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-state.d.ts","sourceRoot":"","sources":["../../../src/core/cache-state.ts"],"names":[],"mappings":"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"}

package/core/cache-state.js

@@ -0,0 +1,84 @@
+export function createHonuaCacheState(init) {
+    return {
+        scope: init.scope,
+        status: init.status,
+        keyFingerprint: init.keyFingerprint,
+        ...(init.ageMs !== undefined ? { ageMs: Math.max(0, Math.trunc(init.ageMs)) } : {}),
+        ...(init.ttlMs !== undefined ? { ttlMs: Math.max(0, Math.trunc(init.ttlMs)) } : {}),
+        ...(init.staleIfErrorMs !== undefined ? { staleIfErrorMs: Math.max(0, Math.trunc(init.staleIfErrorMs)) } : {}),
+        ...(init.revalidatedAt ? { revalidatedAt: init.revalidatedAt } : {}),
+        ...(init.sourceUpdatedAt ? { sourceUpdatedAt: init.sourceUpdatedAt } : {}),
+        ...(hasHonuaCacheValidator(init.validator) ? { validator: init.validator } : {}),
+        ...(init.invalidationReason ? { invalidationReason: init.invalidationReason } : {}),
+        ...(init.refreshErrorId ? { refreshErrorId: init.refreshErrorId } : {}),
+    };
+}
+export function normalizeHonuaMetadataRequestOptions(options = {}) {
+    return {
+        ...(options.signal ? { signal: options.signal } : {}),
+        refresh: options.refresh === true,
+        cache: options.cache === "bypass" ? "bypass" : "default",
+        staleIfError: options.staleIfError !== false,
+        ...(normalizeNonNegativeInteger(options.ttlMs) !== undefined
+            ? { ttlMs: normalizeNonNegativeInteger(options.ttlMs) }
+            : {}),
+        ...(normalizeNonNegativeInteger(options.staleIfErrorMs) !== undefined
+            ? { staleIfErrorMs: normalizeNonNegativeInteger(options.staleIfErrorMs) }
+            : {}),
+    };
+}
+export function isHonuaCacheStatus(value) {
+    return value === "hit" || value === "miss" || value === "stale" || value === "refreshed" || value === "bypass";
+}
+export function honuaCacheValidatorFromHeaders(headers) {
+    const etag = headers.get("etag") ?? undefined;
+    const lastModified = headers.get("last-modified") ?? undefined;
+    return hasHonuaCacheValidator({ etag, lastModified })
+        ? { ...(etag ? { etag } : {}), ...(lastModified ? { lastModified } : {}) }
+        : undefined;
+}
+export function honuaMetadataRequestHeaders(options) {
+    const headers = {
+        Accept: options.accept ?? "application/json",
+    };
+    if (options.bypass) {
+        headers["Cache-Control"] = "no-store";
+        headers.Pragma = "no-cache";
+        return headers;
+    }
+    if (options.refresh) {
+        headers["Cache-Control"] = "no-cache";
+        if (options.validator?.etag) {
+            headers["If-None-Match"] = options.validator.etag;
+        }
+        if (options.validator?.lastModified) {
+            headers["If-Modified-Since"] = options.validator.lastModified;
+        }
+    }
+    return headers;
+}
+export function withHonuaCacheState(value, cache) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return value;
+    }
+    return {
+        ...value,
+        cache,
+    };
+}
+export function withoutHonuaCacheState(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return value;
+    }
+    const { cache: _cache, ...rest } = value;
+    return rest;
+}
+function hasHonuaCacheValidator(value) {
+    return Boolean(value?.etag || value?.lastModified);
+}
+function normalizeNonNegativeInteger(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return undefined;
+    }
+    return Math.max(0, Math.trunc(value));
+}