@honua/react 0.0.20-alpha.0

package/core/ogc-records.js

@@ -0,0 +1,251 @@
+/**
+ * OGC API Records surface. Records are catalog metadata documents about
+ * resources (services, collections, maps, scenes, STAC collections, source
+ * descriptors), not STAC imagery items and not protocol-native service
+ * metadata. The wire calls live on `HonuaClient`; this class is the
+ * request-shaping layer on top.
+ *
+ * @module
+ */
+import { createOgcMetadataParams, mergeHeaders, normalizeCsv, normalizeStringCsv } from "./wire-shared.js";
+const DEFAULT_RECORDS_PAGE_SIZE = 100;
+const DEFAULT_RECORDS_MAX_PAGES = 100;
+/** Top-level OGC API Records handle. */
+export class HonuaOgcRecords {
+    client;
+    constructor(options) {
+        this.client = options.client;
+    }
+    collection(collectionId) {
+        return new HonuaOgcRecordCollection({ client: this.client, collectionId });
+    }
+    async landing(request = {}) {
+        return this.client.getOgcRecordsLanding(request);
+    }
+    async conformance(request = {}) {
+        return this.client.getOgcRecordsConformance(request);
+    }
+    async collections(request = {}) {
+        return this.client.listOgcRecordCollections(request);
+    }
+    async collectionMetadata(request) {
+        return this.client.getOgcRecordCollection(request);
+    }
+    async search(request) {
+        return this.client.searchOgcRecords(request);
+    }
+    async record(request) {
+        return this.client.getOgcRecord(request);
+    }
+    async rawSearch(request) {
+        return this.client.fetchOgcRecordsRaw(request);
+    }
+    async rawRecord(request) {
+        return this.client.fetchOgcRecordRaw(request);
+    }
+    async searchAll(request) {
+        const pageSize = request.pageSize ?? request.limit ?? DEFAULT_RECORDS_PAGE_SIZE;
+        const maxPages = request.maxPages ?? DEFAULT_RECORDS_MAX_PAGES;
+        const records = [];
+        let cursor = { offset: request.offset };
+        for (let page = 0; page < maxPages; page += 1) {
+            const response = await this.client.searchOgcRecords({
+                ...request,
+                limit: pageSize,
+                offset: cursor.offset,
+            });
+            const pageRecords = response.features ?? [];
+            if (pageRecords.length === 0)
+                break;
+            records.push(...pageRecords);
+            cursor = nextRecordsCursor(response.links);
+            // Continuation is driven solely by the next-link cursor (and the
+            // maxPages cap). OGC API Records/Features permits a server to return
+            // fewer than `limit` records on a non-final page while still
+            // advertising a `rel=next` link, so a short page must not stop paging.
+            if (cursor.offset === undefined)
+                break;
+        }
+        return records;
+    }
+    async *searchStream(request) {
+        const pageSize = request.pageSize ?? request.limit ?? DEFAULT_RECORDS_PAGE_SIZE;
+        const maxPages = request.maxPages ?? DEFAULT_RECORDS_MAX_PAGES;
+        let cursor = { offset: request.offset };
+        for (let page = 0; page < maxPages; page += 1) {
+            const response = await this.client.searchOgcRecords({
+                ...request,
+                limit: pageSize,
+                offset: cursor.offset,
+            });
+            const pageRecords = response.features ?? [];
+            if (pageRecords.length === 0)
+                break;
+            yield pageRecords;
+            cursor = nextRecordsCursor(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)
+                break;
+        }
+    }
+}
+/**
+ * Bound handle for one Records catalog (`/collections/{catalogId}`). Drops
+ * the routing discriminator from per-call requests.
+ */
+export class HonuaOgcRecordCollection {
+    client;
+    collectionId;
+    constructor(options) {
+        this.client = options.client;
+        this.collectionId = options.collectionId;
+    }
+    async metadata(request = {}) {
+        return this.client.getOgcRecordCollection({ ...request, collectionId: this.collectionId });
+    }
+    async search(request = {}) {
+        return this.client.searchOgcRecords({ ...request, collectionId: this.collectionId });
+    }
+    async record(request) {
+        return this.client.getOgcRecord({ ...request, collectionId: this.collectionId });
+    }
+    async rawSearch(request = {}) {
+        return this.client.fetchOgcRecordsRaw({ ...request, collectionId: this.collectionId });
+    }
+    async rawRecord(request) {
+        return this.client.fetchOgcRecordRaw({ ...request, collectionId: this.collectionId });
+    }
+    async searchAll(request = {}) {
+        const root = new HonuaOgcRecords({ client: this.client });
+        return root.searchAll({ ...request, collectionId: this.collectionId });
+    }
+    searchStream(request = {}) {
+        const root = new HonuaOgcRecords({ client: this.client });
+        return root.searchStream({ ...request, collectionId: this.collectionId });
+    }
+}
+/**
+ * Query-param names that may carry the next-page start offset on an OGC API
+ * `rel:"next"` link. `offset` is Honua Server's spelling; `startindex` is the
+ * OGC API – Features / Records standard name (servers also vary the casing).
+ */
+const RECORDS_OFFSET_PARAM_NAMES = ["offset", "startindex", "startIndex"];
+function nextRecordsCursor(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");
+            // Standards-conformant servers commonly express the next page with
+            // `startindex` rather than `offset`; honor whichever the server sent so
+            // pagination doesn't silently stop after the first page.
+            const offsetParam = readFirstParam(url.searchParams, RECORDS_OFFSET_PARAM_NAMES);
+            if (offsetParam === null)
+                continue;
+            const offset = Number(offsetParam);
+            if (Number.isFinite(offset))
+                return { offset };
+        }
+        catch {
+            // Ignore unparsable hrefs; keep scanning for a usable next link.
+        }
+    }
+    return {};
+}
+/** Return the first non-null value among `names` from the query string. */
+function readFirstParam(params, names) {
+    for (const name of names) {
+        const value = params.get(name);
+        if (value !== null)
+            return value;
+    }
+    return null;
+}
+export function createHonuaOgcRecords(client) {
+    return new HonuaOgcRecords({ client });
+}
+// ── OGC API Records wire methods ────────────────────────────────
+export async function getOgcRecordsLanding(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-records:landing:${params.toString()}`, `/ogc/records?${params.toString()}`, request);
+}
+export async function getOgcRecordsConformance(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-records:conformance:${params.toString()}`, `/ogc/records/conformance?${params.toString()}`, request);
+}
+export async function listOgcRecordCollections(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-records:collections:${params.toString()}`, `/ogc/records/collections?${params.toString()}`, request);
+}
+export async function getOgcRecordCollection(transport, request) {
+    const params = createOgcMetadataParams(request);
+    const path = `/ogc/records/collections/${encodeURIComponent(String(request.collectionId))}`;
+    return transport.requestCachedMetadataJson(`ogc-records:collection:${request.collectionId}:${params.toString()}`, `${path}?${params.toString()}`, request);
+}
+export async function searchOgcRecords(transport, request) {
+    return transport.requestJson("GET", buildOgcRecordsSearchPath(request), undefined, request.signal);
+}
+export async function getOgcRecord(transport, request) {
+    return transport.requestJson("GET", buildOgcRecordPath(request), undefined, request.signal);
+}
+export async function fetchOgcRecordsRaw(transport, request) {
+    return transport.pipelineFetch("GET", buildOgcRecordsSearchPath(request), {
+        headers: mergeHeaders({ Accept: request.accept ?? "application/geo+json, application/json;q=0.9" }, request.headers),
+    }, request.signal);
+}
+export async function fetchOgcRecordRaw(transport, request) {
+    return transport.pipelineFetch("GET", buildOgcRecordPath(request), {
+        headers: mergeHeaders({ Accept: request.accept ?? "application/geo+json, application/json;q=0.9" }, request.headers),
+    }, request.signal);
+}
+function normalizeRecordsBbox(value) {
+    return Array.isArray(value) ? value.join(",") : String(value);
+}
+function buildOgcRecordsSearchPath(request) {
+    const collection = encodeURIComponent(String(request.collectionId));
+    const params = serializeOgcRecordsSearchParams(request);
+    return `/ogc/records/collections/${collection}/items?${params.toString()}`;
+}
+function buildOgcRecordPath(request) {
+    const collection = encodeURIComponent(String(request.collectionId));
+    const record = encodeURIComponent(String(request.recordId));
+    const params = createOgcMetadataParams(request);
+    if (request.profile !== undefined)
+        params.set("profile", normalizeStringCsv(request.profile));
+    return `/ogc/records/collections/${collection}/items/${record}?${params.toString()}`;
+}
+function serializeOgcRecordsSearchParams(request) {
+    const params = createOgcMetadataParams(request);
+    if (request.limit !== undefined)
+        params.set("limit", String(request.limit));
+    if (request.offset !== undefined)
+        params.set("offset", String(request.offset));
+    if (request.bbox !== undefined)
+        params.set("bbox", normalizeRecordsBbox(request.bbox));
+    if (request.datetime !== undefined)
+        params.set("datetime", request.datetime);
+    if (request.q !== undefined)
+        params.set("q", normalizeStringCsv(request.q));
+    if (request.ids !== undefined)
+        params.set("ids", normalizeCsv(request.ids));
+    if (request.type !== undefined)
+        params.set("type", normalizeStringCsv(request.type));
+    if (request.externalIds !== undefined)
+        params.set("externalIds", normalizeStringCsv(request.externalIds));
+    if (request.filter !== undefined)
+        params.set("filter", request.filter);
+    if (request.filterLang !== undefined)
+        params.set("filter-lang", request.filterLang);
+    if (request.filterCrs !== undefined)
+        params.set("filter-crs", request.filterCrs);
+    if (request.properties !== undefined)
+        params.set("properties", normalizeStringCsv(request.properties));
+    if (request.sortby !== undefined)
+        params.set("sortby", request.sortby);
+    if (request.profile !== undefined)
+        params.set("profile", normalizeStringCsv(request.profile));
+    return params;
+}

package/core/ogc-tiles.d.ts

@@ -0,0 +1,125 @@
+/**
+ * OGC API Tiles surface. Wraps the wire methods on `HonuaClient` with a
+ * tileset-discovery friendly API and a single-tile fetch helper. The
+ * conformance class identifiers are kept internal — callers see
+ * tilesets, tile-matrix-sets, and styled-tile access through the shared
+ * vocabulary, never an `OgcApiTilesPart2DatasetMap` typename.
+ *
+ * @module
+ */
+import type { HonuaMetadataRequestOptions } from "./cache-state.js";
+import type { HonuaClient } from "./client.js";
+import type { HonuaProtocolTransport } from "./protocol-transport.js";
+import type { HonuaOgcConformanceResponse, HonuaOgcLandingResponse, HonuaOgcTileMatrixSet, HonuaOgcTileMatrixSetsResponse, HonuaOgcTileResponse, HonuaOgcTilesetMetadata, HonuaOgcTilesetsResponse, OgcMetadataRequest, OgcTileMatrixSetId, OgcTileRequest, OgcTilesetRequest, OgcTilesetsRequest } from "./types.js";
+/** Default OGC tile-matrix-set used when none is specified (Web Mercator XYZ). */
+export declare const DEFAULT_OGC_TILE_MATRIX_SET: OgcTileMatrixSetId;
+export interface HonuaOgcTilesOptions {
+    client: HonuaClient;
+}
+/**
+ * Structural shape of a MapLibre `VectorSourceSpecification` for tiled
+ * vector data. Declared locally so the SDK does not take a runtime or type
+ * dependency on `maplibre-gl` (a peer); the object is assignable to
+ * MapLibre's `VectorSourceSpecification`.
+ */
+export interface MapLibreVectorSourceSpec {
+    type: "vector";
+    tiles: string[];
+    minzoom?: number;
+    maxzoom?: number;
+    scheme?: "xyz";
+}
+/** Options for {@link HonuaOgcTiles.getMapLibreVectorSource}. */
+export interface HonuaMapLibreVectorSourceOptions {
+    /** Tile-matrix-set to template against. Defaults to `WebMercatorQuad`. */
+    tileMatrixSetId?: OgcTileMatrixSetId;
+    /** Override the `minzoom` of the produced source. */
+    minzoom?: number;
+    /** Override the `maxzoom` of the produced source. */
+    maxzoom?: number;
+}
+/** Result of {@link HonuaOgcTiles.getMapLibreConfig}. */
+export interface HonuaMapLibreTilesConfig {
+    source: MapLibreVectorSourceSpec;
+    sourceLayer: string;
+}
+export interface HonuaOgcTilesetOptions {
+    client: HonuaClient;
+    collectionId: string | number;
+    tileMatrixSetId: string;
+}
+export type HonuaOgcCollectionTilesetRequest = Omit<OgcTilesetRequest, "collectionId" | "tileMatrixSetId">;
+export type HonuaOgcCollectionTilesetsRequest = Omit<OgcTilesetsRequest, "collectionId">;
+export type HonuaOgcCollectionTileRequest = Omit<OgcTileRequest, "collectionId" | "tileMatrixSetId">;
+/**
+ * Top-level OGC API Tiles handle. Mirrors `HonuaOgcFeatures` for the
+ * tiles conformance classes.
+ */
+export declare class HonuaOgcTiles {
+    readonly client: HonuaClient;
+    constructor(options: HonuaOgcTilesOptions);
+    tileset(collectionId: string | number, tileMatrixSetId: string): HonuaOgcTileset;
+    landing(request?: OgcMetadataRequest): Promise<HonuaOgcLandingResponse>;
+    conformance(request?: OgcMetadataRequest): Promise<HonuaOgcConformanceResponse>;
+    tileMatrixSets(request?: OgcMetadataRequest): Promise<HonuaOgcTileMatrixSetsResponse>;
+    tileMatrixSet(tileMatrixSetId: string, request?: OgcMetadataRequest): Promise<HonuaOgcTileMatrixSet>;
+    tilesets(request: OgcTilesetsRequest): Promise<HonuaOgcTilesetsResponse>;
+    tilesetMetadata(request: OgcTilesetRequest): Promise<HonuaOgcTilesetMetadata>;
+    tile(request: OgcTileRequest): Promise<HonuaOgcTileResponse>;
+    /**
+     * Build a MapLibre-ready vector source definition for a tiled collection.
+     *
+     * Produces a `{ type: "vector", tiles: ["…/{z}/{y}/{x}"] }` object whose
+     * tile URL points at the canonical OGC API Tiles collection-tile route on
+     * the SDK's configured `baseUrl`. The MapLibre `{z}/{y}/{x}` placeholders
+     * are kept literal (the braces are not percent-encoded) while the
+     * collection / service identifier is encoded per path segment so
+     * folder-prefixed identifiers like `myFolder/parcels` serialize correctly.
+     *
+     * No network request is made; this is a pure URL-template builder. Pass
+     * `minzoom` / `maxzoom` to constrain the source, otherwise MapLibre's
+     * defaults apply.
+     */
+    getMapLibreVectorSource(serviceId: string, options?: HonuaMapLibreVectorSourceOptions): MapLibreVectorSourceSpec;
+    /**
+     * Resolve the `source-layer` name to use in a MapLibre layer that renders
+     * the collection's vector tiles. The Honua server names the MVT layer after
+     * the collection identifier; for folder-prefixed identifiers the trailing
+     * segment is the layer name (the folder is a routing prefix, not part of
+     * the layer name baked into the tile).
+     */
+    getDefaultSourceLayer(serviceId: string): string;
+    /**
+     * Convenience wrapper returning both the MapLibre vector {@link source}
+     * object and the {@link sourceLayer} name to wire into a layer definition.
+     */
+    getMapLibreConfig(serviceId: string, options?: HonuaMapLibreVectorSourceOptions): HonuaMapLibreTilesConfig;
+}
+/**
+ * Bound handle for one (collection × tile-matrix-set) tileset. Drops the
+ * discovery params from the per-call surface so callers focus on tile
+ * coordinates. Styled-tile access (the OGC `/styles/{styleId}` route) is
+ * not exposed here because the Honua server does not currently implement
+ * that route; the tile path is the canonical collection tile route.
+ */
+export declare class HonuaOgcTileset {
+    readonly client: HonuaClient;
+    readonly collectionId: string | number;
+    readonly tileMatrixSetId: string;
+    constructor(options: HonuaOgcTilesetOptions);
+    metadata(request?: HonuaOgcCollectionTilesetRequest): Promise<HonuaOgcTilesetMetadata>;
+    tile(request: HonuaOgcCollectionTileRequest): Promise<HonuaOgcTileResponse>;
+}
+export declare function createHonuaOgcTiles(client: HonuaClient): HonuaOgcTiles;
+export declare function getOgcTilesLanding(transport: HonuaProtocolTransport, request?: OgcMetadataRequest): Promise<HonuaOgcLandingResponse>;
+export declare function getOgcTilesConformance(transport: HonuaProtocolTransport, request?: OgcMetadataRequest): Promise<HonuaOgcConformanceResponse>;
+export declare function listOgcTileMatrixSets(transport: HonuaProtocolTransport, request?: OgcMetadataRequest): Promise<HonuaOgcTileMatrixSetsResponse>;
+export declare function getOgcTileMatrixSet(transport: HonuaProtocolTransport, request: {
+    tileMatrixSetId: string;
+    responseFormat?: string;
+    extraParams?: Record<string, string | number | boolean>;
+} & HonuaMetadataRequestOptions): Promise<HonuaOgcTileMatrixSet>;
+export declare function listOgcCollectionTilesets(transport: HonuaProtocolTransport, request: OgcTilesetsRequest): Promise<HonuaOgcTilesetsResponse>;
+export declare function getOgcCollectionTileset(transport: HonuaProtocolTransport, request: OgcTilesetRequest): Promise<HonuaOgcTilesetMetadata>;
+export declare function fetchOgcTile(transport: HonuaProtocolTransport, request: OgcTileRequest): Promise<HonuaOgcTileResponse>;
+//# sourceMappingURL=ogc-tiles.d.ts.map

package/core/ogc-tiles.d.ts.map

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

package/core/ogc-tiles.js

@@ -0,0 +1,183 @@
+/**
+ * OGC API Tiles surface. Wraps the wire methods on `HonuaClient` with a
+ * tileset-discovery friendly API and a single-tile fetch helper. The
+ * conformance class identifiers are kept internal — callers see
+ * tilesets, tile-matrix-sets, and styled-tile access through the shared
+ * vocabulary, never an `OgcApiTilesPart2DatasetMap` typename.
+ *
+ * @module
+ */
+import { encodePathSegments, trimTrailingSlashes } from "./path-utils.js";
+import { createOgcMetadataParams } from "./wire-shared.js";
+/** Default OGC tile-matrix-set used when none is specified (Web Mercator XYZ). */
+export const DEFAULT_OGC_TILE_MATRIX_SET = "WebMercatorQuad";
+/**
+ * Top-level OGC API Tiles handle. Mirrors `HonuaOgcFeatures` for the
+ * tiles conformance classes.
+ */
+export class HonuaOgcTiles {
+    client;
+    constructor(options) {
+        this.client = options.client;
+    }
+    tileset(collectionId, tileMatrixSetId) {
+        return new HonuaOgcTileset({
+            client: this.client,
+            collectionId,
+            tileMatrixSetId,
+        });
+    }
+    async landing(request = {}) {
+        return this.client.getOgcTilesLanding(request);
+    }
+    async conformance(request = {}) {
+        return this.client.getOgcTilesConformance(request);
+    }
+    async tileMatrixSets(request = {}) {
+        return this.client.listOgcTileMatrixSets(request);
+    }
+    async tileMatrixSet(tileMatrixSetId, request = {}) {
+        return this.client.getOgcTileMatrixSet({ ...request, tileMatrixSetId });
+    }
+    async tilesets(request) {
+        return this.client.listOgcCollectionTilesets(request);
+    }
+    async tilesetMetadata(request) {
+        return this.client.getOgcCollectionTileset(request);
+    }
+    async tile(request) {
+        return this.client.fetchOgcTile(request);
+    }
+    /**
+     * Build a MapLibre-ready vector source definition for a tiled collection.
+     *
+     * Produces a `{ type: "vector", tiles: ["…/{z}/{y}/{x}"] }` object whose
+     * tile URL points at the canonical OGC API Tiles collection-tile route on
+     * the SDK's configured `baseUrl`. The MapLibre `{z}/{y}/{x}` placeholders
+     * are kept literal (the braces are not percent-encoded) while the
+     * collection / service identifier is encoded per path segment so
+     * folder-prefixed identifiers like `myFolder/parcels` serialize correctly.
+     *
+     * No network request is made; this is a pure URL-template builder. Pass
+     * `minzoom` / `maxzoom` to constrain the source, otherwise MapLibre's
+     * defaults apply.
+     */
+    getMapLibreVectorSource(serviceId, options = {}) {
+        const tileMatrixSetId = options.tileMatrixSetId ?? DEFAULT_OGC_TILE_MATRIX_SET;
+        const baseUrl = trimTrailingSlashes(this.client.serverBaseUrl);
+        const collection = encodePathSegments(serviceId);
+        const matrixSet = encodeURIComponent(tileMatrixSetId);
+        const template = `${baseUrl}/ogc/tiles/collections/${collection}/tiles/${matrixSet}/{z}/{y}/{x}`;
+        const source = {
+            type: "vector",
+            tiles: [template],
+            scheme: "xyz",
+        };
+        if (options.minzoom !== undefined)
+            source.minzoom = options.minzoom;
+        if (options.maxzoom !== undefined)
+            source.maxzoom = options.maxzoom;
+        return source;
+    }
+    /**
+     * Resolve the `source-layer` name to use in a MapLibre layer that renders
+     * the collection's vector tiles. The Honua server names the MVT layer after
+     * the collection identifier; for folder-prefixed identifiers the trailing
+     * segment is the layer name (the folder is a routing prefix, not part of
+     * the layer name baked into the tile).
+     */
+    getDefaultSourceLayer(serviceId) {
+        const segments = serviceId.split("/");
+        return segments[segments.length - 1] ?? serviceId;
+    }
+    /**
+     * Convenience wrapper returning both the MapLibre vector {@link source}
+     * object and the {@link sourceLayer} name to wire into a layer definition.
+     */
+    getMapLibreConfig(serviceId, options = {}) {
+        return {
+            source: this.getMapLibreVectorSource(serviceId, options),
+            sourceLayer: this.getDefaultSourceLayer(serviceId),
+        };
+    }
+}
+/**
+ * Bound handle for one (collection × tile-matrix-set) tileset. Drops the
+ * discovery params from the per-call surface so callers focus on tile
+ * coordinates. Styled-tile access (the OGC `/styles/{styleId}` route) is
+ * not exposed here because the Honua server does not currently implement
+ * that route; the tile path is the canonical collection tile route.
+ */
+export class HonuaOgcTileset {
+    client;
+    collectionId;
+    tileMatrixSetId;
+    constructor(options) {
+        this.client = options.client;
+        this.collectionId = options.collectionId;
+        this.tileMatrixSetId = options.tileMatrixSetId;
+    }
+    async metadata(request = {}) {
+        return this.client.getOgcCollectionTileset({
+            ...request,
+            collectionId: this.collectionId,
+            tileMatrixSetId: this.tileMatrixSetId,
+        });
+    }
+    async tile(request) {
+        return this.client.fetchOgcTile({
+            ...request,
+            collectionId: this.collectionId,
+            tileMatrixSetId: this.tileMatrixSetId,
+        });
+    }
+}
+export function createHonuaOgcTiles(client) {
+    return new HonuaOgcTiles({ client });
+}
+// ── OGC API Tiles wire methods ──────────────────────────────────
+//
+// Concrete URL-building / param-serialization / response-handling for the
+// OGC API Tiles endpoints, invoked against an injected transport. The client
+// exposes thin `get*/list*/fetch*` delegators that call these.
+export async function getOgcTilesLanding(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-tiles:landing:${params.toString()}`, `/ogc/tiles?${params.toString()}`, request);
+}
+export async function getOgcTilesConformance(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-tiles:conformance:${params.toString()}`, `/ogc/tiles/conformance?${params.toString()}`, request);
+}
+export async function listOgcTileMatrixSets(transport, request = {}) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-tiles:tile-matrix-sets:${params.toString()}`, `/ogc/tiles/tileMatrixSets?${params.toString()}`, request);
+}
+export async function getOgcTileMatrixSet(transport, request) {
+    const params = createOgcMetadataParams(request);
+    return transport.requestCachedMetadataJson(`ogc-tiles:tile-matrix-set:${request.tileMatrixSetId}:${params.toString()}`, `/ogc/tiles/tileMatrixSets/${encodeURIComponent(request.tileMatrixSetId)}?${params.toString()}`, request);
+}
+export async function listOgcCollectionTilesets(transport, request) {
+    const params = createOgcMetadataParams(request);
+    const path = `/ogc/tiles/collections/${encodeURIComponent(String(request.collectionId))}/tiles`;
+    return transport.requestCachedMetadataJson(`ogc-tiles:tilesets:${request.collectionId}:${params.toString()}`, `${path}?${params.toString()}`, request);
+}
+export async function getOgcCollectionTileset(transport, request) {
+    const params = createOgcMetadataParams(request);
+    const path = `/ogc/tiles/collections/${encodeURIComponent(String(request.collectionId))}` +
+        `/tiles/${encodeURIComponent(request.tileMatrixSetId)}`;
+    return transport.requestCachedMetadataJson(`ogc-tiles:tileset:${request.collectionId}:${request.tileMatrixSetId}:${params.toString()}`, `${path}?${params.toString()}`, request);
+}
+export async function fetchOgcTile(transport, request) {
+    const params = new URLSearchParams();
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    const collection = encodeURIComponent(String(request.collectionId));
+    const matrixSet = encodeURIComponent(request.tileMatrixSetId);
+    const matrix = encodeURIComponent(String(request.tileMatrix));
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    const path = `/ogc/tiles/collections/${collection}/tiles/${matrixSet}/${matrix}/${request.tileRow}/${request.tileCol}${query}`;
+    return transport.requestBytes("GET", path, request.accept, undefined, request.signal);
+}

package/core/path-utils.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Linear-time string trimming helpers used for URL and path normalization.
+ *
+ * These intentionally avoid regular expressions such as `\/+$` or `^\/+`.
+ * Anchored quantifier regexes over repeated characters can exhibit
+ * super-linear (polynomial) matching on adversarial input, so the helpers
+ * below scan from the relevant end with simple index arithmetic, which is
+ * always O(n) regardless of input shape.
+ */
+/** Remove every trailing `/` character from `value`. */
+export declare function trimTrailingSlashes(value: string): string;
+/** Remove every leading `/` character from `value`. */
+export declare function trimLeadingSlashes(value: string): string;
+/** Remove every leading and trailing `/` character from `value`. */
+export declare function trimSurroundingSlashes(value: string): string;
+/**
+ * Remove leading and trailing runs of `char` from `value`.
+ *
+ * `char` must be a single-character string; only its first code unit is
+ * considered. Used for slug/identifier normalization (e.g. stripping `-`
+ * or `_` padding) without anchored `^x+|x+$` regexes.
+ */
+export declare function trimChar(value: string, char: string): string;
+/**
+ * Return `value` with any `?query` and `#fragment` suffix removed.
+ *
+ * Equivalent to `value.replace(/[?#].*$/, "")` but uses `indexOf` slicing
+ * so it stays linear and cannot backtrack.
+ */
+export declare function stripQueryAndFragment(value: string): string;
+/**
+ * Return `value` with any `?query` suffix removed (the fragment, if present,
+ * is preserved). Equivalent to `value.replace(/\?.*$/, "")`.
+ */
+export declare function stripQuery(value: string): string;
+/**
+ * Encode an Esri-style `serviceId` for use as a URL path segment, preserving
+ * folder structure.
+ *
+ * Esri/GeoServices services may be folder-organized, e.g.
+ * `MyFolder/MyService`. Naively passing the whole id through
+ * `encodeURIComponent` percent-encodes the `/` separator (`%2F`), collapsing
+ * the folder and service into a single path segment that the server cannot
+ * route. This helper splits on `/`, encodes each non-empty segment
+ * individually, and rejoins with `/` so the folder path is preserved while
+ * special characters within a segment (spaces, `&`, etc.) are still encoded.
+ *
+ * A plain `serviceId` without slashes behaves exactly like
+ * `encodeURIComponent(serviceId)`. Empty segments produced by leading,
+ * trailing, or doubled slashes are dropped so the result never contains
+ * stray `/` runs. Use {@link encodePathSegments} instead when empty segments
+ * must be preserved verbatim.
+ */
+export declare function encodeServiceIdPath(serviceId: string): string;
+/**
+ * Percent-encode a path that may contain `/` separators, encoding each
+ * segment independently so the separators survive.
+ *
+ * `encodeURIComponent("a/b")` returns `a%2Fb`, which is wrong for
+ * folder-prefixed identifiers such as `myFolder/parcels` that must serialize
+ * as `myFolder/parcels` on the wire. Splitting on `/` and encoding each
+ * segment keeps the separators literal while still escaping reserved
+ * characters inside each segment. Empty segments (leading/trailing/double
+ * slashes) are preserved verbatim so callers retain full control over the
+ * resulting path shape. Use {@link encodeServiceIdPath} when empty segments
+ * should instead be dropped (e.g. routable Esri service ids).
+ */
+export declare function encodePathSegments(value: string): string;
+//# sourceMappingURL=path-utils.d.ts.map

package/core/path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../../../src/core/path-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,wDAAwD;AACxD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAW5D;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAU3D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAS7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQxD"}