@honua/react 0.0.20-alpha.0

package/core/wfs.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Runtime classes for the WFS 2.0 adapter. Three layers:
+ *
+ *   - `HonuaWfs` — root handle bound to a WFS endpoint URL. Owns the
+ *     capabilities cache and exposes feature-type / stored-query factories.
+ *   - `HonuaWfsFeatureType` — bound to a single namespace-qualified type
+ *     name. Implements GetFeature / GetPropertyValue / Transaction; routed
+ *     from `Source.protocol("wfs")`.
+ *   - `HonuaWfsStoredQuery` — bound to a stored-query identifier. Used by
+ *     `Source.protocol("wfs").storedQuery(id)`.
+ *
+ * All wire calls go through `HonuaClient.requestText`, so the existing
+ * interceptor / retry / timeout pipeline applies.
+ *
+ * Canonical translation (KVP and FES emission, GeoJSON ↔ canonical
+ * envelope, etc.) lives in `src/contract/source.ts`'s `wfsSource` factory;
+ * this module only carries the wire-level surface.
+ *
+ * @module
+ */
+import type { HonuaClient } from "./client.js";
+import { type WfsCapabilitiesSnapshot, type WfsTransactionSummary } from "./wfs-capabilities.js";
+/**
+ * Negotiated output-format preference for a WFS GetFeature call. `format` is
+ * the wire value to send back (the original case the server advertised); the
+ * categorical kind is what the canonical surface acts on.
+ */
+export interface OutputFormatChoice {
+    kind: "json" | "gml";
+    format: string;
+}
+/**
+ * Construction options for `HonuaWfs`. The adapter is endpoint-bound: one
+ * `HonuaWfs` per server URL.
+ */
+export interface HonuaWfsOptions {
+    client: HonuaClient;
+    /** Fully qualified or relative WFS endpoint URL (e.g. `/wfs`). */
+    endpointUrl: string;
+    /** WFS version to request. Default `2.0.0`. */
+    version?: string;
+}
+/**
+ * Root WFS handle. Holds the capabilities cache and exposes feature-type /
+ * stored-query factories.
+ */
+export declare class HonuaWfs {
+    readonly client: HonuaClient;
+    readonly endpointUrl: string;
+    readonly version: string;
+    /** Counter exposed for tests / diagnostics: how many times capabilities was fetched. */
+    capabilitiesFetches: number;
+    private capabilitiesPromise;
+    private rawCapabilitiesXml;
+    constructor(options: HonuaWfsOptions);
+    /**
+     * Fetch and cache the GetCapabilities document. Subsequent calls reuse the
+     * parsed snapshot. Throws `HonuaWfsExceptionError` on `<ows:ExceptionReport>`.
+     */
+    capabilities(options?: {
+        signal?: AbortSignal;
+    }): Promise<WfsCapabilitiesSnapshot>;
+    /** Discard the cached capabilities snapshot so the next call re-fetches. */
+    refresh(): void;
+    /** Last raw capabilities XML payload (populated after the first fetch). */
+    rawCapabilities(): string | undefined;
+    /** Bind a feature-type handle. Does not network. */
+    featureType(typeName: string): HonuaWfsFeatureType;
+    /**
+     * Discover stored queries through the `ListStoredQueries` operation. Returns
+     * the bare list of identifier strings; per-query metadata is exposed via
+     * `storedQuery(id).describe()`.
+     */
+    storedQueries(options?: {
+        signal?: AbortSignal;
+    }): Promise<readonly string[]>;
+    storedQuery(id: string): HonuaWfsStoredQuery;
+    /** Internal helper used by feature-type / stored-query handles. */
+    requestText(method: "GET" | "POST", path: string, options: {
+        accept: string;
+        contentType?: string;
+        body?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        text: string;
+        contentType: string;
+        status: number;
+    }>;
+    /** Negotiate an output format for the GetFeature call. */
+    negotiateOutputFormat(snapshot: WfsCapabilitiesSnapshot): OutputFormatChoice | undefined;
+    private fetchCapabilities;
+}
+interface HonuaWfsFeatureTypeOptions {
+    root: HonuaWfs;
+    typeName: string;
+}
+/**
+ * Per-feature-type WFS surface. Implements the wire methods that the
+ * canonical `wfsSource` translates onto, and the protocol escape-hatch
+ * methods that ship raw XML payloads back to callers.
+ */
+export declare class HonuaWfsFeatureType {
+    readonly root: HonuaWfs;
+    readonly typeName: string;
+    constructor(options: HonuaWfsFeatureTypeOptions);
+    /** Convenience: capabilities snapshot from the bound root. */
+    capabilities(options?: {
+        signal?: AbortSignal;
+    }): Promise<WfsCapabilitiesSnapshot>;
+    /**
+     * Issue a GetFeature request. Returns parsed JSON when the negotiated
+     * output format is JSON; otherwise returns the raw body as a string for
+     * downstream callers (the canonical surface throws in that case).
+     */
+    getFeature(params: {
+        filter?: string;
+        bbox?: string;
+        propertyName?: string[];
+        sortBy?: string;
+        count?: number;
+        startIndex?: number;
+        resultType?: "results" | "hits";
+        srsName?: string;
+        outputFormat?: string;
+        method?: "GET" | "POST";
+        body?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        kind: "json";
+        data: unknown;
+        contentType: string;
+    } | {
+        kind: "raw";
+        text: string;
+        contentType: string;
+    }>;
+    /**
+     * Issue a `GetPropertyValue` request. WFS-specific (returns raw XML), so
+     * the canonical surface only reaches it via `protocol("wfs")`.
+     */
+    getPropertyValue(params: {
+        valueReference: string;
+        filter?: string;
+        count?: number;
+        startIndex?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        text: string;
+        contentType: string;
+    }>;
+    /**
+     * Submit a `<wfs:Transaction>` POST body. Returns the parsed transaction
+     * summary; throws `HonuaWfsExceptionError` on `<ows:ExceptionReport>`.
+     */
+    transaction(params: {
+        body: string;
+        signal?: AbortSignal;
+    }): Promise<WfsTransactionSummary>;
+    /** Build (but do not send) the URL the GET GetFeature request would use. */
+    buildGetFeatureUrl(params: {
+        filter?: string;
+        bbox?: string;
+        count?: number;
+        startIndex?: number;
+        outputFormat?: string;
+    }): string;
+}
+interface HonuaWfsStoredQueryOptions {
+    root: HonuaWfs;
+    id: string;
+}
+/**
+ * Bound stored-query handle. `execute(params)` runs `GetFeature?storedquery_id=…`.
+ */
+export declare class HonuaWfsStoredQuery {
+    readonly root: HonuaWfs;
+    readonly id: string;
+    constructor(options: HonuaWfsStoredQueryOptions);
+    /** Run `DescribeStoredQueries` for this stored query. Returns the raw XML. */
+    describe(options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        text: string;
+        contentType: string;
+    }>;
+    /**
+     * Execute the stored query against `GetFeature`. Caller passes the
+     * stored-query parameter map; values are coerced to strings via
+     * `String(value)`. Returns parsed JSON when the server replies with a
+     * JSON output format, raw text otherwise.
+     */
+    execute(params: {
+        parameters?: Record<string, string | number | boolean>;
+        outputFormat?: string;
+        count?: number;
+        startIndex?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        kind: "json";
+        data: unknown;
+        contentType: string;
+    } | {
+        kind: "raw";
+        text: string;
+        contentType: string;
+    }>;
+}
+export declare function appendQuery(url: string, params: URLSearchParams): string;
+export declare function looksLikeJson(contentType: string | undefined, text: string): boolean;
+export declare function looksLikeXml(contentType: string | undefined, text: string): boolean;
+/**
+ * If the underlying client failure carries a WFS ExceptionReport in its
+ * body, re-throw as `HonuaWfsExceptionError`; otherwise leave the original
+ * error in place. The body is wrapped by `parseResponseBody` as
+ * `{ raw: text, contentType? }` for non-JSON responses.
+ */
+export declare function rethrowAsWfsExceptionIfPossible(err: unknown): unknown;
+export {};
+//# sourceMappingURL=wfs.d.ts.map

package/core/wfs.d.ts.map

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

package/core/wfs.js

@@ -0,0 +1,406 @@
+/**
+ * Runtime classes for the WFS 2.0 adapter. Three layers:
+ *
+ *   - `HonuaWfs` — root handle bound to a WFS endpoint URL. Owns the
+ *     capabilities cache and exposes feature-type / stored-query factories.
+ *   - `HonuaWfsFeatureType` — bound to a single namespace-qualified type
+ *     name. Implements GetFeature / GetPropertyValue / Transaction; routed
+ *     from `Source.protocol("wfs")`.
+ *   - `HonuaWfsStoredQuery` — bound to a stored-query identifier. Used by
+ *     `Source.protocol("wfs").storedQuery(id)`.
+ *
+ * All wire calls go through `HonuaClient.requestText`, so the existing
+ * interceptor / retry / timeout pipeline applies.
+ *
+ * Canonical translation (KVP and FES emission, GeoJSON ↔ canonical
+ * envelope, etc.) lives in `src/contract/source.ts`'s `wfsSource` factory;
+ * this module only carries the wire-level surface.
+ *
+ * @module
+ */
+import { HonuaHttpError, HonuaWfsExceptionError } from "./errors.js";
+import { parseListStoredQueriesResponse, parseWfsCapabilities, parseWfsExceptionReport, parseWfsTransactionResponse, } from "./wfs-capabilities.js";
+const DEFAULT_VERSION = "2.0.0";
+const SERVICE_PARAM = "WFS";
+/** Output formats (lower-cased) the canonical adapter treats as JSON. */
+const JSON_OUTPUT_FORMATS = new Set([
+    "application/json",
+    "application/geo+json",
+    "application/vnd.geo+json",
+    "json",
+    "geojson",
+]);
+/** Output formats (lower-cased) the canonical adapter treats as GML. */
+const GML_OUTPUT_FORMATS = new Set([
+    "application/gml+xml; version=3.2",
+    "application/gml+xml;version=3.2",
+    "application/gml+xml",
+    "gml3.2",
+    "gml32",
+    "text/xml; subtype=gml/3.2",
+    "text/xml;subtype=gml/3.2",
+    "text/xml; subtype=gml/3.2.1",
+    "text/xml;subtype=gml/3.2.1",
+]);
+/**
+ * Root WFS handle. Holds the capabilities cache and exposes feature-type /
+ * stored-query factories.
+ */
+export class HonuaWfs {
+    client;
+    endpointUrl;
+    version;
+    /** Counter exposed for tests / diagnostics: how many times capabilities was fetched. */
+    capabilitiesFetches = 0;
+    capabilitiesPromise;
+    rawCapabilitiesXml;
+    constructor(options) {
+        this.client = options.client;
+        this.endpointUrl = options.endpointUrl;
+        this.version = options.version ?? DEFAULT_VERSION;
+    }
+    /**
+     * Fetch and cache the GetCapabilities document. Subsequent calls reuse the
+     * parsed snapshot. Throws `HonuaWfsExceptionError` on `<ows:ExceptionReport>`.
+     */
+    capabilities(options) {
+        if (!this.capabilitiesPromise) {
+            this.capabilitiesPromise = this.fetchCapabilities(options).catch((err) => {
+                // Allow retry after a transient failure.
+                this.capabilitiesPromise = undefined;
+                throw err;
+            });
+        }
+        return this.capabilitiesPromise;
+    }
+    /** Discard the cached capabilities snapshot so the next call re-fetches. */
+    refresh() {
+        this.capabilitiesPromise = undefined;
+        this.rawCapabilitiesXml = undefined;
+    }
+    /** Last raw capabilities XML payload (populated after the first fetch). */
+    rawCapabilities() {
+        return this.rawCapabilitiesXml;
+    }
+    /** Bind a feature-type handle. Does not network. */
+    featureType(typeName) {
+        return new HonuaWfsFeatureType({ root: this, typeName });
+    }
+    /**
+     * Discover stored queries through the `ListStoredQueries` operation. Returns
+     * the bare list of identifier strings; per-query metadata is exposed via
+     * `storedQuery(id).describe()`.
+     */
+    async storedQueries(options) {
+        const params = new URLSearchParams({
+            service: SERVICE_PARAM,
+            version: this.version,
+            request: "ListStoredQueries",
+        });
+        const requestOptions = { accept: "application/xml, text/xml" };
+        if (options?.signal)
+            requestOptions.signal = options.signal;
+        const { text } = await this.requestText("GET", appendQuery(this.endpointUrl, params), requestOptions);
+        return parseListStoredQueriesResponse(text);
+    }
+    storedQuery(id) {
+        return new HonuaWfsStoredQuery({ root: this, id });
+    }
+    /** Internal helper used by feature-type / stored-query handles. */
+    async requestText(method, path, options) {
+        try {
+            const requestOptions = {
+                accept: options.accept,
+            };
+            if (options.contentType !== undefined)
+                requestOptions.contentType = options.contentType;
+            if (options.body !== undefined)
+                requestOptions.body = options.body;
+            if (options.signal !== undefined)
+                requestOptions.signal = options.signal;
+            return await this.client.requestText(method, path, requestOptions);
+        }
+        catch (err) {
+            throw rethrowAsWfsExceptionIfPossible(err);
+        }
+    }
+    /** Negotiate an output format for the GetFeature call. */
+    negotiateOutputFormat(snapshot) {
+        const formats = snapshot.outputFormatsByOp.get("GetFeature") ?? [];
+        for (const format of formats) {
+            if (JSON_OUTPUT_FORMATS.has(format))
+                return { kind: "json", format };
+        }
+        for (const format of formats) {
+            if (GML_OUTPUT_FORMATS.has(format))
+                return { kind: "gml", format };
+        }
+        if (formats.length === 0) {
+            // Honua Server advertises GeoJSON in OperationsMetadata; absence is
+            // treated as "JSON unknown" — fall back to GeoJSON optimistically. The
+            // first request will surface the actual server behaviour through an
+            // ExceptionReport.
+            return { kind: "json", format: "application/geo+json" };
+        }
+        // Server advertises an output format the canonical adapter does not
+        // recognise — let the caller decide whether to throw or escape-hatch.
+        return { kind: "gml", format: formats[0] };
+    }
+    async fetchCapabilities(options) {
+        this.capabilitiesFetches += 1;
+        const params = new URLSearchParams({
+            service: SERVICE_PARAM,
+            version: this.version,
+            request: "GetCapabilities",
+        });
+        const requestOptions = { accept: "application/xml, text/xml" };
+        if (options?.signal)
+            requestOptions.signal = options.signal;
+        const { text } = await this.requestText("GET", appendQuery(this.endpointUrl, params), requestOptions);
+        this.rawCapabilitiesXml = text;
+        return parseWfsCapabilities(text);
+    }
+}
+/**
+ * Per-feature-type WFS surface. Implements the wire methods that the
+ * canonical `wfsSource` translates onto, and the protocol escape-hatch
+ * methods that ship raw XML payloads back to callers.
+ */
+export class HonuaWfsFeatureType {
+    root;
+    typeName;
+    constructor(options) {
+        this.root = options.root;
+        this.typeName = options.typeName;
+    }
+    /** Convenience: capabilities snapshot from the bound root. */
+    capabilities(options) {
+        return this.root.capabilities(options);
+    }
+    /**
+     * Issue a GetFeature request. Returns parsed JSON when the negotiated
+     * output format is JSON; otherwise returns the raw body as a string for
+     * downstream callers (the canonical surface throws in that case).
+     */
+    async getFeature(params) {
+        const method = params.method ?? "GET";
+        const accept = params.outputFormat ?? "application/geo+json, application/json;q=0.9, application/xml;q=0.5";
+        const requestOptions = { accept };
+        if (params.signal)
+            requestOptions.signal = params.signal;
+        let response;
+        if (method === "POST" && params.body !== undefined) {
+            requestOptions.contentType = "application/xml";
+            requestOptions.body = params.body;
+            response = await this.root.requestText("POST", this.root.endpointUrl, requestOptions);
+        }
+        else {
+            const search = new URLSearchParams({
+                service: SERVICE_PARAM,
+                version: this.root.version,
+                request: "GetFeature",
+                typeNames: this.typeName,
+            });
+            if (params.filter !== undefined)
+                search.set("filter", params.filter);
+            if (params.bbox !== undefined)
+                search.set("bbox", params.bbox);
+            if (params.propertyName && params.propertyName.length > 0) {
+                search.set("propertyName", params.propertyName.join(","));
+            }
+            if (params.sortBy !== undefined)
+                search.set("sortBy", params.sortBy);
+            if (typeof params.count === "number")
+                search.set("count", String(params.count));
+            if (typeof params.startIndex === "number")
+                search.set("startIndex", String(params.startIndex));
+            if (params.resultType !== undefined)
+                search.set("resultType", params.resultType);
+            if (params.srsName !== undefined)
+                search.set("srsName", params.srsName);
+            if (params.outputFormat !== undefined)
+                search.set("outputFormat", params.outputFormat);
+            response = await this.root.requestText("GET", appendQuery(this.root.endpointUrl, search), requestOptions);
+        }
+        if (looksLikeJson(response.contentType, response.text)) {
+            return { kind: "json", data: parseJsonOrThrow(response.text), contentType: response.contentType };
+        }
+        if (looksLikeXml(response.contentType, response.text) && /ExceptionReport/i.test(response.text)) {
+            const report = parseWfsExceptionReport(response.text);
+            throw new HonuaWfsExceptionError(report.exceptionCode, report.message, report.locator);
+        }
+        return { kind: "raw", text: response.text, contentType: response.contentType };
+    }
+    /**
+     * Issue a `GetPropertyValue` request. WFS-specific (returns raw XML), so
+     * the canonical surface only reaches it via `protocol("wfs")`.
+     */
+    async getPropertyValue(params) {
+        const search = new URLSearchParams({
+            service: SERVICE_PARAM,
+            version: this.root.version,
+            request: "GetPropertyValue",
+            typeNames: this.typeName,
+            valueReference: params.valueReference,
+        });
+        if (params.filter !== undefined)
+            search.set("filter", params.filter);
+        if (typeof params.count === "number")
+            search.set("count", String(params.count));
+        if (typeof params.startIndex === "number")
+            search.set("startIndex", String(params.startIndex));
+        const requestOptions = { accept: "application/xml, text/xml" };
+        if (params.signal)
+            requestOptions.signal = params.signal;
+        const { text, contentType } = await this.root.requestText("GET", appendQuery(this.root.endpointUrl, search), requestOptions);
+        return { text, contentType };
+    }
+    /**
+     * Submit a `<wfs:Transaction>` POST body. Returns the parsed transaction
+     * summary; throws `HonuaWfsExceptionError` on `<ows:ExceptionReport>`.
+     */
+    async transaction(params) {
+        const requestOptions = {
+            accept: "application/xml, text/xml",
+            contentType: "application/xml",
+            body: params.body,
+        };
+        if (params.signal)
+            requestOptions.signal = params.signal;
+        const { text } = await this.root.requestText("POST", this.root.endpointUrl, requestOptions);
+        return parseWfsTransactionResponse(text);
+    }
+    /** Build (but do not send) the URL the GET GetFeature request would use. */
+    buildGetFeatureUrl(params) {
+        const search = new URLSearchParams({
+            service: SERVICE_PARAM,
+            version: this.root.version,
+            request: "GetFeature",
+            typeNames: this.typeName,
+        });
+        if (params.filter !== undefined)
+            search.set("filter", params.filter);
+        if (params.bbox !== undefined)
+            search.set("bbox", params.bbox);
+        if (typeof params.count === "number")
+            search.set("count", String(params.count));
+        if (typeof params.startIndex === "number")
+            search.set("startIndex", String(params.startIndex));
+        if (params.outputFormat !== undefined)
+            search.set("outputFormat", params.outputFormat);
+        return appendQuery(this.root.endpointUrl, search);
+    }
+}
+/**
+ * Bound stored-query handle. `execute(params)` runs `GetFeature?storedquery_id=…`.
+ */
+export class HonuaWfsStoredQuery {
+    root;
+    id;
+    constructor(options) {
+        this.root = options.root;
+        this.id = options.id;
+    }
+    /** Run `DescribeStoredQueries` for this stored query. Returns the raw XML. */
+    async describe(options) {
+        const search = new URLSearchParams({
+            service: SERVICE_PARAM,
+            version: this.root.version,
+            request: "DescribeStoredQueries",
+            storedQuery_Id: this.id,
+        });
+        const requestOptions = { accept: "application/xml, text/xml" };
+        if (options?.signal)
+            requestOptions.signal = options.signal;
+        const { text, contentType } = await this.root.requestText("GET", appendQuery(this.root.endpointUrl, search), requestOptions);
+        return { text, contentType };
+    }
+    /**
+     * Execute the stored query against `GetFeature`. Caller passes the
+     * stored-query parameter map; values are coerced to strings via
+     * `String(value)`. Returns parsed JSON when the server replies with a
+     * JSON output format, raw text otherwise.
+     */
+    async execute(params) {
+        const search = new URLSearchParams({
+            service: SERVICE_PARAM,
+            version: this.root.version,
+            request: "GetFeature",
+            storedquery_id: this.id,
+        });
+        if (typeof params.count === "number")
+            search.set("count", String(params.count));
+        if (typeof params.startIndex === "number")
+            search.set("startIndex", String(params.startIndex));
+        if (params.outputFormat !== undefined)
+            search.set("outputFormat", params.outputFormat);
+        if (params.parameters) {
+            for (const [key, value] of Object.entries(params.parameters)) {
+                search.set(key, String(value));
+            }
+        }
+        const accept = params.outputFormat ?? "application/geo+json, application/json;q=0.9, application/xml;q=0.5";
+        const requestOptions = { accept };
+        if (params.signal)
+            requestOptions.signal = params.signal;
+        const { text, contentType } = await this.root.requestText("GET", appendQuery(this.root.endpointUrl, search), requestOptions);
+        if (looksLikeJson(contentType, text)) {
+            return { kind: "json", data: parseJsonOrThrow(text), contentType };
+        }
+        if (looksLikeXml(contentType, text) && /ExceptionReport/i.test(text)) {
+            const report = parseWfsExceptionReport(text);
+            throw new HonuaWfsExceptionError(report.exceptionCode, report.message, report.locator);
+        }
+        return { kind: "raw", text, contentType };
+    }
+}
+// ── Helpers ───────────────────────────────────────────────────
+export function appendQuery(url, params) {
+    // Preserve any pre-existing query string on the endpoint URL (some servers
+    // sit behind URL signatures that include their own params).
+    const sep = url.includes("?") ? "&" : "?";
+    return `${url}${sep}${params.toString()}`;
+}
+export function looksLikeJson(contentType, text) {
+    if (contentType && /json/i.test(contentType))
+        return true;
+    const trimmed = text.trimStart();
+    return trimmed.startsWith("{") || trimmed.startsWith("[");
+}
+export function looksLikeXml(contentType, text) {
+    if (contentType && /xml/i.test(contentType))
+        return true;
+    return text.trimStart().startsWith("<");
+}
+function parseJsonOrThrow(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`WFS GetFeature returned non-JSON output despite Accept negotiation: ${message}`);
+    }
+}
+/**
+ * If the underlying client failure carries a WFS ExceptionReport in its
+ * body, re-throw as `HonuaWfsExceptionError`; otherwise leave the original
+ * error in place. The body is wrapped by `parseResponseBody` as
+ * `{ raw: text, contentType? }` for non-JSON responses.
+ */
+export function rethrowAsWfsExceptionIfPossible(err) {
+    if (!(err instanceof HonuaHttpError))
+        return err;
+    const body = err.body;
+    if (!body || typeof body !== "object" || typeof body.raw !== "string")
+        return err;
+    const raw = body.raw;
+    if (!/ExceptionReport/i.test(raw))
+        return err;
+    try {
+        const report = parseWfsExceptionReport(raw);
+        return new HonuaWfsExceptionError(report.exceptionCode, report.message, report.locator);
+    }
+    catch {
+        return err;
+    }
+}

package/core/wire-shared.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Helpers shared across the per-protocol wire modules and the client's
+ * transport core: header merging and the common OGC metadata query-param
+ * builder plus CSV normalizers. Kept transport-agnostic so both
+ * `HonuaClient` and the protocol modules can import them without a cycle.
+ *
+ * @module
+ */
+import type { OgcMetadataRequest } from "./types.js";
+/**
+ * Merge any number of `HeadersInit` values into a plain `Record<string,string>`,
+ * with later entries overriding earlier ones. Accepts `Headers`, tuple arrays,
+ * and plain objects; `undefined`/`null` object values are skipped.
+ */
+export declare function mergeHeaders(...headersList: Array<HeadersInit | undefined>): Record<string, string>;
+/** Build the shared OGC metadata query params (`f` + caller `extraParams`). */
+export declare function createOgcMetadataParams(request: OgcMetadataRequest): URLSearchParams;
+/** Normalize a string-or-(string|number)-array value to a CSV string. */
+export declare function normalizeCsv(value: string | readonly (string | number)[]): string;
+/** Normalize a string-or-string-array value to a CSV string. */
+export declare function normalizeStringCsv(value: string | readonly string[]): string;
+/**
+ * True when a GeoServices/FeatureServer response advertises more pages via
+ * `exceededTransferLimit`. GeoServices servers clamp `resultRecordCount` to
+ * their `maxRecordCount` and set this flag when more rows remain, so
+ * offset-paginated fetch-all loops must keep paging while it is set — advancing
+ * by the actual returned row count, never a fixed `page * pageSize` stride that
+ * would skip the rows the server capped off — rather than stopping on the first
+ * page that comes back shorter than the requested `pageSize`.
+ */
+export declare function responseExceededTransferLimit(response: unknown): boolean;
+//# sourceMappingURL=wire-shared.d.ts.map

package/core/wire-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-shared.d.ts","sourceRoot":"","sources":["../../../src/core/wire-shared.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,WAAW,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA6BnG;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG,eAAe,CASpF;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,MAAM,CAKjF;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,MAAM,CAE5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAMxE"}