@honua/react 0.0.20-alpha.0

package/contract/tiles.js

@@ -0,0 +1,519 @@
+/**
+ * Dynamic vector/query tile contract primitives.
+ *
+ * The runtime helpers in `src/runtime/query-tiles.ts` use these types to
+ * describe query-backed vector tile sources without tying the contract to
+ * MapLibre. The descriptor is intentionally serializable except for the
+ * optional feature identity hook.
+ *
+ * @module
+ */
+import { trimLeadingSlashes, trimSurroundingSlashes, trimTrailingSlashes } from "../core/path-utils.js";
+import { analyticsSourceId, buildAnalyticsSourceCacheKey, isAnalyticsSourceDescriptor, normalizeAnalyticsSourceDescriptor, } from "./analytics-sources.js";
+export const QUERY_TILE_SERVER_CONTRACT_VERSION = 1;
+export const QUERY_TILE_SERVER_ROUTE_PREFIX = "query-tiles";
+export const QUERY_TILE_SERVER_SOURCE_ROUTE_TEMPLATE = "sources/{sourceId}";
+export const QUERY_TILE_SERVER_TILEJSON_ROUTE_TEMPLATE = `${QUERY_TILE_SERVER_SOURCE_ROUTE_TEMPLATE}/tilejson.json`;
+export const QUERY_TILE_SERVER_TILE_ROUTE_TEMPLATE = `${QUERY_TILE_SERVER_SOURCE_ROUTE_TEMPLATE}/tiles/{z}/{x}/{y}.{format}`;
+export const QUERY_TILE_SERVER_FEATURE_DETAIL_ROUTE_TEMPLATE = `${QUERY_TILE_SERVER_SOURCE_ROUTE_TEMPLATE}/features/{featureId}`;
+export const QUERY_TILE_SERVER_RESPONSE_HEADERS = {
+    cacheControl: "Cache-Control",
+    etag: "ETag",
+    lastModified: "Last-Modified",
+    vary: "Vary",
+    sourceVersion: "X-Honua-Source-Version",
+    featureCount: "X-Honua-Feature-Count",
+    maxFeatures: "X-Honua-Max-Features",
+    degraded: "X-Honua-Degraded",
+};
+/** Build a canonical query-tile server path for TileJSON, MVT tiles, or detail lookup. */
+export function buildQueryTileServerPath(kind, options) {
+    const prefix = normalizeRoutePrefix(options.routePrefix ?? QUERY_TILE_SERVER_ROUTE_PREFIX);
+    const sourcePath = QUERY_TILE_SERVER_SOURCE_ROUTE_TEMPLATE.replace("{sourceId}", encodePathSegment(options.sourceId));
+    const parts = [prefix, sourcePath];
+    if (kind === "tilejson") {
+        parts.push("tilejson.json");
+    }
+    else if (kind === "tile") {
+        const tile = options.tileKey ? normalizeQueryTileKey(options.tileKey) : undefined;
+        parts.push("tiles", tile ? String(tile.z) : "{z}", tile ? String(tile.x) : "{x}", `${tile ? String(tile.y) : "{y}"}.${options.format ?? "mvt"}`);
+    }
+    else {
+        parts.push("features", options.featureId === undefined ? "{featureId}" : encodePathSegment(options.featureId));
+    }
+    return `/${parts.filter((part) => part.length > 0).join("/")}`;
+}
+/** Build a canonical query-tile server URL and serialize supported query parameters. */
+export function buildQueryTileServerUrl(kind, options) {
+    const url = joinRouteUrl(options.baseUrl, buildQueryTileServerPath(kind, options));
+    return appendServerParams(url, queryTileServerRequestParamsFromOptions(options), options.extraParams);
+}
+/** Project a descriptor's query/projection/cache-relevant dimensions into server query params. */
+export function queryTileServerRequestParamsFromDescriptor(descriptor, options = {}) {
+    const normalized = normalizeQueryTileSourceDescriptor(descriptor);
+    return queryTileServerRequestParamsFromOptions({
+        query: options.query ?? normalized.query,
+        projection: options.projection ?? normalized.projection,
+        params: {
+            tileMatrixSet: normalized.tileMatrixSet,
+            ...options.params,
+        },
+    });
+}
+/** Validate and return TileJSON that follows the dynamic query tile contract. */
+export function parseQueryTileJson(value) {
+    const record = expectRecord(value, "TileJSON response");
+    if (record.tilejson !== "3.0.0") {
+        throw new Error('query tile TileJSON response must include tilejson: "3.0.0"');
+    }
+    if (!Array.isArray(record.tiles) || record.tiles.some((tile) => typeof tile !== "string" || tile.length === 0)) {
+        throw new Error("query tile TileJSON response must include non-empty tiles[] strings");
+    }
+    if (record.vector_layers !== undefined) {
+        if (!Array.isArray(record.vector_layers)) {
+            throw new Error("query tile TileJSON vector_layers must be an array when present");
+        }
+        for (const layer of record.vector_layers) {
+            const layerRecord = expectRecord(layer, "query tile vector layer");
+            if (typeof layerRecord.id !== "string" || layerRecord.id.length === 0) {
+                throw new Error("query tile vector layer id is required");
+            }
+        }
+    }
+    const metadata = record["honua:queryTiles"];
+    if (metadata !== undefined) {
+        validateQueryTileServerMetadata(metadata);
+    }
+    return record;
+}
+/** Validate and return the canonical feature-detail lookup response. */
+export function parseQueryTileFeatureDetailResponse(value) {
+    const record = expectRecord(value, "query tile feature detail response");
+    if (typeof record.contractVersion !== "number") {
+        throw new Error("query tile feature detail response contractVersion is required");
+    }
+    const identity = expectRecord(record.identity, "query tile feature detail identity");
+    if (typeof identity.sourceId !== "string" || identity.sourceId.length === 0) {
+        throw new Error("query tile feature detail identity.sourceId is required");
+    }
+    if (!isFeatureId(identity.id)) {
+        throw new Error("query tile feature detail identity.id is required");
+    }
+    if (typeof record.found !== "boolean") {
+        throw new Error("query tile feature detail response found flag is required");
+    }
+    if (record.feature !== null && (record.feature === undefined || typeof record.feature !== "object")) {
+        throw new Error("query tile feature detail response feature must be an object or null");
+    }
+    validateDegradations(record.degraded);
+    return record;
+}
+/** Validate and return the canonical query-tile server error envelope. */
+export function parseQueryTileServerErrorResponse(value) {
+    const record = expectRecord(value, "query tile server error response");
+    if (typeof record.contractVersion !== "number") {
+        throw new Error("query tile server error response contractVersion is required");
+    }
+    const error = expectRecord(record.error, "query tile server error");
+    if (typeof error.code !== "string" || error.code.length === 0) {
+        throw new Error("query tile server error code is required");
+    }
+    if (typeof error.message !== "string" || error.message.length === 0) {
+        throw new Error("query tile server error message is required");
+    }
+    if (error.status !== undefined && typeof error.status !== "number") {
+        throw new Error("query tile server error status must be a number when present");
+    }
+    validateDegradations(error.degraded);
+    return record;
+}
+/** Build a normalized descriptor from a source id, descriptor, or Source handle. */
+export function defineQueryTileSource(options) {
+    const sourceDescriptor = resolveSourceDescriptor(options.source);
+    const analyticsSource = resolveAnalyticsSourceDescriptor(options.source);
+    const sourceId = options.sourceId ??
+        sourceDescriptor?.id ??
+        (analyticsSource ? analyticsSourceId(analyticsSource) : String(options.source));
+    const protocol = options.protocol ?? sourceDescriptor?.protocol;
+    return normalizeQueryTileSourceDescriptor({
+        ...options,
+        kind: "query-vector-tile",
+        id: options.id,
+        sourceId,
+        source: sourceDescriptor,
+        analyticsSource,
+        protocol,
+    });
+}
+/** Normalize defaults and validate the descriptor's stable identity fields. */
+export function normalizeQueryTileSourceDescriptor(descriptor) {
+    if (!descriptor.id || typeof descriptor.id !== "string") {
+        throw new Error("QueryTileSourceDescriptor.id is required");
+    }
+    if (!descriptor.sourceId || typeof descriptor.sourceId !== "string") {
+        throw new Error("QueryTileSourceDescriptor.sourceId is required");
+    }
+    const protocol = descriptor.protocol ?? descriptor.source?.protocol;
+    const analyticsSource = descriptor.analyticsSource
+        ? normalizeAnalyticsSourceDescriptor(descriptor.analyticsSource)
+        : undefined;
+    return {
+        ...descriptor,
+        kind: "query-vector-tile",
+        protocol,
+        ...(analyticsSource ? { analyticsSource } : {}),
+        format: descriptor.format ?? "mvt",
+        scheme: descriptor.scheme ?? "xyz",
+        tileMatrixSet: descriptor.tileMatrixSet ?? descriptor.source?.locator.tileMatrixSetId,
+        attribution: descriptor.attribution ?? descriptor.source?.attribution,
+    };
+}
+/** Normalize XYZ / OGC tile aliases into a canonical, wrapped XYZ key. */
+export function normalizeQueryTileKey(input) {
+    const z = parseInteger(input.z ?? input.tileMatrix, "z");
+    const x = parseInteger(input.x ?? input.tileCol, "x");
+    const y = parseInteger(input.y ?? input.tileRow, "y");
+    if (z < 0)
+        throw new Error("tile z must be >= 0");
+    const tileCount = 2 ** z;
+    const wrappedX = ((x % tileCount) + tileCount) % tileCount;
+    const clampedY = Math.min(tileCount - 1, Math.max(0, y));
+    return { z, x: wrappedX, y: clampedY };
+}
+export function queryTileKeyString(input) {
+    const key = normalizeQueryTileKey(input);
+    return `${key.z}/${key.x}/${key.y}`;
+}
+/**
+ * Build a stable cache key. The key includes tile coordinate, source id,
+ * protocol, tile matrix set, query, projection, style filters, source
+ * version, and authorization scope.
+ */
+export function buildQueryTileCacheKey(descriptor, tileKey, options = {}) {
+    const normalizedDescriptor = normalizeQueryTileSourceDescriptor(descriptor);
+    const key = normalizeQueryTileKey(tileKey);
+    const cacheIdentity = {
+        ...(normalizedDescriptor.cache?.key ?? {}),
+        ...(options.cache ?? {}),
+    };
+    const payload = {
+        v: 1,
+        kind: normalizedDescriptor.kind,
+        descriptorId: normalizedDescriptor.id,
+        sourceId: normalizedDescriptor.sourceId,
+        protocol: normalizedDescriptor.protocol,
+        analyticsSource: normalizedDescriptor.analyticsSource
+            ? buildAnalyticsSourceCacheKey(normalizedDescriptor.analyticsSource, {
+                cache: {
+                    sourceVersion: cacheIdentity.sourceVersion,
+                    authorizationScope: cacheIdentity.authorizationScope,
+                    filters: normalizedDescriptor.query?.where,
+                    indexResolution: typeof cacheIdentity.extra?.indexResolution === "number"
+                        ? cacheIdentity.extra.indexResolution
+                        : undefined,
+                    projection: normalizeProjection(normalizedDescriptor.projection),
+                    styleProjection: cacheIdentity.styleFilters,
+                    extra: cacheIdentity.extra,
+                },
+                operation: "tiles",
+            })
+            : undefined,
+        tileMatrixSet: normalizedDescriptor.tileMatrixSet,
+        format: normalizedDescriptor.format,
+        tile: key,
+        query: normalizeSerializableQuery(normalizedDescriptor.query),
+        projection: normalizeProjection(normalizedDescriptor.projection),
+        styleFilters: cacheIdentity.styleFilters,
+        sourceVersion: cacheIdentity.sourceVersion,
+        authorizationScope: cacheIdentity.authorizationScope,
+        extra: cacheIdentity.extra,
+    };
+    return `${options.prefix ?? "honua-query-tile"}:${stableJson(payload)}`;
+}
+/** Map a rendered tile feature back to canonical source + feature identity. */
+export function mapQueryTileFeatureIdentity(descriptor, feature) {
+    const normalized = normalizeQueryTileSourceDescriptor(descriptor);
+    const properties = featureProperties(feature);
+    const sourceLayer = readStringProperty(properties, normalized.featureIdentity?.sourceLayerProperty) ?? featureSourceLayer(feature);
+    const context = {
+        descriptor: normalized,
+        sourceId: normalized.sourceId,
+        sourceLayer,
+        properties,
+    };
+    const mapped = normalized.featureIdentity?.mapFeature?.(feature, context);
+    if (mapped)
+        return mapped;
+    const sourceId = readStringProperty(properties, normalized.featureIdentity?.sourceIdProperty) ?? normalized.sourceId;
+    const id = readFeatureId(feature, properties, normalized.featureIdentity, sourceLayer);
+    if (id === undefined)
+        return undefined;
+    return {
+        sourceId,
+        id,
+        ...(sourceLayer ? { sourceLayer } : {}),
+        properties,
+        feature,
+    };
+}
+/** Build the canonical Source.query() request for selected-tile-feature detail. */
+export function buildQueryTileFeatureDetailQuery(options) {
+    const idField = options.idField ??
+        firstString(options.descriptor?.featureIdentity?.idProperty) ??
+        firstString(options.descriptor?.featureIdentity?.promoteId);
+    const detailWhere = typeof options.where === "function"
+        ? options.where(options.target)
+        : (options.where ?? (idField ? `${idField} = ${sqlLiteral(options.target.id)}` : undefined));
+    if (!detailWhere) {
+        throw new Error("query tile feature detail requires idField, descriptor.featureIdentity.idProperty, or where");
+    }
+    const base = options.baseQuery ?? {};
+    return {
+        ...base,
+        where: combineWhere(base.where, detailWhere),
+        outFields: options.outFields ?? base.outFields,
+        returnGeometry: options.returnGeometry ?? base.returnGeometry ?? true,
+        pagination: { ...(base.pagination ?? {}), limit: 1 },
+        ...(options.signal ? { signal: options.signal } : {}),
+    };
+}
+/** Load a selected tile feature through the canonical Source detail path. */
+export async function loadQueryTileFeatureDetail(options) {
+    const result = await options.source.query(buildQueryTileFeatureDetailQuery(options));
+    return result.features[0];
+}
+/** Stable JSON for cache keys and diagnostics snapshots. */
+export function stableJson(value) {
+    return JSON.stringify(sortJson(value));
+}
+function resolveSourceDescriptor(source) {
+    if (typeof source === "string")
+        return undefined;
+    if (isAnalyticsSourceDescriptor(source))
+        return undefined;
+    const maybeSource = source;
+    if (maybeSource.descriptor)
+        return maybeSource.descriptor;
+    const maybeDescriptor = source;
+    if (typeof maybeDescriptor.id === "string" && typeof maybeDescriptor.protocol === "string") {
+        return maybeDescriptor;
+    }
+    return undefined;
+}
+function resolveAnalyticsSourceDescriptor(source) {
+    return isAnalyticsSourceDescriptor(source) ? normalizeAnalyticsSourceDescriptor(source) : undefined;
+}
+function queryTileServerRequestParamsFromOptions(options) {
+    return {
+        where: options.query?.where,
+        outFields: options.query?.outFields,
+        returnGeometry: options.query?.returnGeometry,
+        outSr: options.query?.outSr,
+        projection: options.projection?.fields,
+        projectionReturnGeometry: options.projection?.returnGeometry,
+        simplifyTolerance: options.projection?.simplifyTolerance,
+        ...(options.params ?? {}),
+    };
+}
+function normalizeRoutePrefix(prefix) {
+    return trimSurroundingSlashes(prefix);
+}
+function encodePathSegment(value) {
+    return encodeURIComponent(String(value));
+}
+function joinRouteUrl(baseUrl, path) {
+    const [basePath, query = ""] = baseUrl.split("?", 2);
+    const joined = `${trimTrailingSlashes(basePath)}/${trimLeadingSlashes(path)}`;
+    return query ? `${joined}?${query}` : joined;
+}
+function appendServerParams(url, params, extraParams) {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries({ ...params, ...(extraParams ?? {}) })) {
+        const serialized = serverParamValue(value);
+        if (serialized === undefined)
+            continue;
+        searchParams.set(key, serialized);
+    }
+    const query = searchParams.toString();
+    if (!query)
+        return url;
+    return `${url}${url.includes("?") ? "&" : "?"}${query}`;
+}
+function serverParamValue(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (Array.isArray(value))
+        return value.join(",");
+    if (typeof value === "object")
+        return stableJson(value);
+    return String(value);
+}
+function expectRecord(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
+    }
+    return value;
+}
+function validateQueryTileServerMetadata(value) {
+    const metadata = expectRecord(value, "query tile TileJSON honua:queryTiles metadata");
+    if (typeof metadata.contractVersion !== "number") {
+        throw new Error("query tile TileJSON metadata contractVersion is required");
+    }
+    if (typeof metadata.sourceId !== "string" || metadata.sourceId.length === 0) {
+        throw new Error("query tile TileJSON metadata sourceId is required");
+    }
+    if (typeof metadata.tileMatrixSet !== "string" || metadata.tileMatrixSet.length === 0) {
+        throw new Error("query tile TileJSON metadata tileMatrixSet is required");
+    }
+    if (metadata.format !== "mvt" && metadata.format !== "geojson") {
+        throw new Error("query tile TileJSON metadata format must be mvt or geojson");
+    }
+    if (metadata.spatialReference === undefined) {
+        throw new Error("query tile TileJSON metadata spatialReference is required");
+    }
+    const identity = expectRecord(metadata.featureIdentity, "query tile TileJSON featureIdentity");
+    if (typeof identity.sourceId !== "string" || identity.sourceId.length === 0) {
+        throw new Error("query tile TileJSON featureIdentity.sourceId is required");
+    }
+    if (typeof identity.idProperty !== "string" && !Array.isArray(identity.idProperty)) {
+        throw new Error("query tile TileJSON featureIdentity.idProperty is required");
+    }
+    if (typeof metadata.detailUrlTemplate !== "string" || metadata.detailUrlTemplate.length === 0) {
+        throw new Error("query tile TileJSON metadata detailUrlTemplate is required");
+    }
+    validateDegradations(metadata.degraded);
+}
+function validateDegradations(value) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value))
+        throw new Error("query tile degraded must be an array when present");
+    for (const item of value) {
+        const degradation = expectRecord(item, "query tile degradation");
+        if (typeof degradation.code !== "string" || degradation.code.length === 0) {
+            throw new Error("query tile degradation code is required");
+        }
+        if (!["info", "warning", "error"].includes(String(degradation.severity))) {
+            throw new Error("query tile degradation severity must be info, warning, or error");
+        }
+        if (typeof degradation.message !== "string" || degradation.message.length === 0) {
+            throw new Error("query tile degradation message is required");
+        }
+    }
+}
+function normalizeSerializableQuery(query) {
+    if (!query)
+        return undefined;
+    return sortJson(query);
+}
+function normalizeProjection(projection) {
+    if (!projection)
+        return undefined;
+    return {
+        ...projection,
+        fields: projection.fields ? [...projection.fields] : undefined,
+    };
+}
+function parseInteger(value, label) {
+    if (value === undefined || value === null || value === "") {
+        throw new Error(`tile ${label} is required`);
+    }
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isInteger(parsed) || !Number.isFinite(parsed)) {
+        throw new Error(`tile ${label} must be an integer`);
+    }
+    return parsed;
+}
+function sortJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortJson);
+    if (!value || typeof value !== "object")
+        return value;
+    if (value instanceof Date)
+        return value.toISOString();
+    const input = value;
+    const out = {};
+    for (const key of Object.keys(input).sort()) {
+        const next = input[key];
+        if (typeof next === "undefined" || typeof next === "function" || typeof next === "symbol")
+            continue;
+        out[key] = sortJson(next);
+    }
+    return out;
+}
+function featureProperties(feature) {
+    if (!feature || typeof feature !== "object")
+        return {};
+    const properties = feature.properties;
+    if (properties && typeof properties === "object")
+        return properties;
+    const attributes = feature.attributes;
+    if (attributes && typeof attributes === "object")
+        return attributes;
+    return {};
+}
+function featureSourceLayer(feature) {
+    if (!feature || typeof feature !== "object")
+        return undefined;
+    const direct = feature.sourceLayer;
+    if (typeof direct === "string" && direct.length > 0)
+        return direct;
+    const layer = feature.layer;
+    const sourceLayer = layer?.sourceLayer ?? layer?.["source-layer"];
+    return typeof sourceLayer === "string" && sourceLayer.length > 0 ? sourceLayer : undefined;
+}
+function readFeatureId(feature, properties, identity, sourceLayer) {
+    const explicitId = readFeatureIdProperty(properties, identity?.idProperty);
+    if (explicitId !== undefined)
+        return explicitId;
+    const promoted = promoteIdProperty(identity?.promoteId, sourceLayer);
+    const promotedId = readFeatureIdProperty(properties, promoted);
+    if (promotedId !== undefined)
+        return promotedId;
+    if (feature && typeof feature === "object") {
+        const featureId = feature.id;
+        if (isFeatureId(featureId))
+            return featureId;
+    }
+    return readFeatureIdProperty(properties, ["id", "OBJECTID", "objectId", "fid"]);
+}
+function promoteIdProperty(promoteId, sourceLayer) {
+    if (typeof promoteId === "string")
+        return promoteId;
+    if (promoteId && sourceLayer)
+        return promoteId[sourceLayer];
+    return undefined;
+}
+function readFeatureIdProperty(properties, property) {
+    const keys = typeof property === "string" ? [property] : (property ?? []);
+    for (const key of keys) {
+        const value = properties[key];
+        if (isFeatureId(value))
+            return value;
+    }
+    return undefined;
+}
+function readStringProperty(properties, property) {
+    if (!property)
+        return undefined;
+    const value = properties[property];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function isFeatureId(value) {
+    return typeof value === "string" || (typeof value === "number" && Number.isFinite(value));
+}
+function firstString(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return value.find((item) => typeof item === "string" && item.length > 0);
+    return undefined;
+}
+function sqlLiteral(value) {
+    return typeof value === "number" ? String(value) : `'${value.replaceAll("'", "''")}'`;
+}
+function combineWhere(base, detail) {
+    if (!base || base.trim().length === 0)
+        return detail;
+    return `(${base}) AND (${detail})`;
+}