@honua/react 0.0.20-alpha.0 → 0.1.1-beta.0

package/map/raster-source-strategy.js

@@ -0,0 +1,232 @@
+import { HonuaSdkError, mergeHonuaErrorContext } from "../core/error-envelope.js";
+import { buildWmsRasterSourceSpec, buildWmtsRasterSourceSpec, validateRasterTileSize, } from "./raster-source-spec.js";
+export class HonuaMapLibreRasterStrategyError extends HonuaSdkError {
+    code;
+    detail;
+    constructor(code, message, detail, options = {}) {
+        super(MAPLIBRE_RASTER_ERROR_CODES[code], message, {
+            ...options,
+            context: mergeHonuaErrorContext(detail, options.context),
+        });
+        this.code = code;
+        this.detail = detail;
+        this.name = "HonuaMapLibreRasterStrategyError";
+    }
+}
+const MAPLIBRE_RASTER_ERROR_CODES = {
+    "unsupported-strategy": "map.raster-strategy.unsupported-strategy",
+    "capability-mismatch": "map.raster-strategy.capability-mismatch",
+    "missing-metadata": "map.raster-strategy.missing-metadata",
+    "invalid-option": "map.raster-strategy.invalid-option",
+    "source-conflict": "map.raster-strategy.source-conflict",
+    "layer-conflict": "map.raster-strategy.layer-conflict",
+    "map-mutation-failed": "map.raster-strategy.map-mutation-failed",
+};
+/** Select and project the exact raster strategy implied by source metadata. */
+export function projectRasterSourceToMapLibre(descriptor, options = {}) {
+    validateOptions(options);
+    const strategy = selectStrategy(descriptor);
+    assertCapabilities(descriptor);
+    assertMetadata(descriptor, strategy);
+    const sourceId = options.sourceId ?? `honua-${safeId(descriptor.id)}`;
+    const layerId = options.layerId ?? `${sourceId}-raster`;
+    const source = buildSource(descriptor, strategy, options);
+    const layer = Object.freeze({
+        id: layerId,
+        type: "raster",
+        source: sourceId,
+        ...(options.minzoom !== undefined ? { minzoom: options.minzoom } : {}),
+        ...(options.maxzoom !== undefined ? { maxzoom: options.maxzoom } : {}),
+        ...(options.paint ? { paint: { ...options.paint } } : {}),
+        ...(options.layout ? { layout: { ...options.layout } } : {}),
+        metadata: { "honua:strategy": strategy, "honua:protocol": descriptor.protocol },
+    });
+    const diagnostic = Object.freeze({
+        code: "strategy-selected",
+        severity: "info",
+        stage: "project",
+        fidelity: "exact",
+        sourceId,
+        strategy,
+        message: `Selected exact ${strategy} strategy from source metadata.`,
+        detail: Object.freeze({ protocol: descriptor.protocol }),
+    });
+    return Object.freeze({
+        strategy,
+        sourceId,
+        layerId,
+        source: Object.freeze(source),
+        layer,
+        diagnostics: Object.freeze([diagnostic]),
+        state: "ready",
+    });
+}
+/** Project and transactionally mount a metadata-selected raster source/layer. */
+export function mountRasterSourceToMapLibre(map, descriptor, options = {}) {
+    const projection = projectRasterSourceToMapLibre(descriptor, options);
+    if (map.getSource(projection.sourceId) !== undefined) {
+        throw failure("source-conflict", `MapLibre source "${projection.sourceId}" already exists.`, projection);
+    }
+    if (map.getLayer(projection.layerId) !== undefined) {
+        throw failure("layer-conflict", `MapLibre layer "${projection.layerId}" already exists.`, projection);
+    }
+    try {
+        map.addSource(projection.sourceId, projection.source);
+        map.addLayer(projection.layer, options.beforeId);
+    }
+    catch (cause) {
+        const rollbackErrors = rollbackMount(map, projection);
+        throw failure("map-mutation-failed", `Failed to mount raster source "${projection.sourceId}" transactionally.`, projection, { rollbackErrors }, cause);
+    }
+    let state = "ready";
+    const diagnostics = [...projection.diagnostics];
+    return {
+        strategy: projection.strategy,
+        sourceId: projection.sourceId,
+        layerId: projection.layerId,
+        get state() {
+            return state;
+        },
+        get diagnostics() {
+            return Object.freeze([...diagnostics]);
+        },
+        dispose() {
+            if (state === "disposed")
+                return;
+            const cleanupErrors = [];
+            removeIfPresent(map, "layer", projection.layerId, cleanupErrors);
+            removeIfPresent(map, "source", projection.sourceId, cleanupErrors);
+            if (cleanupErrors.length > 0) {
+                diagnostics.push(Object.freeze({
+                    code: "cleanup-failed",
+                    severity: "warning",
+                    stage: "dispose",
+                    fidelity: "unsupported",
+                    sourceId: projection.sourceId,
+                    strategy: projection.strategy,
+                    message: "Raster mount cleanup did not remove every renderer object.",
+                    detail: Object.freeze({ errors: cleanupErrors }),
+                }));
+            }
+            state = "disposed";
+        },
+    };
+}
+function selectStrategy(descriptor) {
+    switch (descriptor.protocol) {
+        case "maplibre-raster":
+            return "native-raster-tiles";
+        case "wms":
+            return "wms-raster";
+        case "wmts":
+            return "wmts-raster";
+        default:
+            throw new HonuaMapLibreRasterStrategyError("unsupported-strategy", `Protocol "${descriptor.protocol}" has no automatic raster strategy.`, { sourceId: descriptor.id, protocol: descriptor.protocol });
+    }
+}
+function assertCapabilities(descriptor) {
+    const missing = ["render", "tiles"].filter((capability) => !descriptor.capabilities.has(capability));
+    if (missing.length > 0) {
+        throw new HonuaMapLibreRasterStrategyError("capability-mismatch", `Source "${descriptor.id}" cannot use a raster strategy because required capabilities are missing.`, { sourceId: descriptor.id, missingCapabilities: missing });
+    }
+}
+function assertMetadata(descriptor, strategy) {
+    const missing = [];
+    if (!nonEmpty(descriptor.locator.url))
+        missing.push("locator.url");
+    if (strategy === "native-raster-tiles" && !isXyzTemplate(descriptor.locator.url)) {
+        missing.push("locator.url:{z}/{x}/{y}");
+    }
+    if ((strategy === "wms-raster" || strategy === "wmts-raster") && !nonEmpty(descriptor.locator.typeName)) {
+        missing.push("locator.typeName");
+    }
+    if (strategy === "wmts-raster" && !nonEmpty(descriptor.locator.tileMatrixSetId)) {
+        missing.push("locator.tileMatrixSetId");
+    }
+    if (missing.length > 0) {
+        throw new HonuaMapLibreRasterStrategyError("missing-metadata", `Source "${descriptor.id}" lacks metadata required by ${strategy}.`, { sourceId: descriptor.id, strategy, missing });
+    }
+}
+function buildSource(descriptor, strategy, options) {
+    if (strategy === "wms-raster")
+        return buildWmsRasterSourceSpec(descriptor, options);
+    if (strategy === "wmts-raster")
+        return buildWmtsRasterSourceSpec(descriptor, options);
+    return {
+        type: "raster",
+        tiles: [descriptor.locator.url],
+        tileSize: options.tileSize ?? 256,
+        ...(options.minzoom !== undefined ? { minzoom: options.minzoom } : {}),
+        ...(options.maxzoom !== undefined ? { maxzoom: options.maxzoom } : {}),
+        ...(descriptor.attribution ? { attribution: descriptor.attribution } : {}),
+    };
+}
+function validateOptions(options) {
+    if (options.tileSize !== undefined) {
+        try {
+            validateRasterTileSize(options.tileSize);
+        }
+        catch (error) {
+            throw new HonuaMapLibreRasterStrategyError("invalid-option", error instanceof Error ? error.message : "tileSize is invalid.", { option: "tileSize", value: options.tileSize });
+        }
+    }
+    for (const [name, value] of [
+        ["minzoom", options.minzoom],
+        ["maxzoom", options.maxzoom],
+    ]) {
+        if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
+            throw new HonuaMapLibreRasterStrategyError("invalid-option", `${name} must be a non-negative integer.`, {
+                option: name,
+                value,
+            });
+        }
+    }
+    if (options.minzoom !== undefined && options.maxzoom !== undefined && options.minzoom > options.maxzoom) {
+        throw new HonuaMapLibreRasterStrategyError("invalid-option", "minzoom cannot exceed maxzoom.", {
+            minzoom: options.minzoom,
+            maxzoom: options.maxzoom,
+        });
+    }
+}
+function rollbackMount(map, projection) {
+    const errors = [];
+    removeIfPresent(map, "layer", projection.layerId, errors);
+    removeIfPresent(map, "source", projection.sourceId, errors);
+    return errors;
+}
+function removeIfPresent(map, kind, id, errors) {
+    try {
+        const present = kind === "layer" ? map.getLayer(id) : map.getSource(id);
+        if (present !== undefined) {
+            if (kind === "layer")
+                map.removeLayer(id);
+            else
+                map.removeSource(id);
+        }
+    }
+    catch (error) {
+        errors.push(`${kind}:${id}:${errorMessage(error)}`);
+    }
+}
+function failure(code, message, projection, extra = {}, cause) {
+    return new HonuaMapLibreRasterStrategyError(code, message, { sourceId: projection.sourceId, layerId: projection.layerId, strategy: projection.strategy, ...extra }, cause === undefined ? undefined : { cause });
+}
+function safeId(value) {
+    const normalized = value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-");
+    let start = 0;
+    while (start < normalized.length && normalized[start] === "-")
+        start += 1;
+    let end = normalized.length;
+    while (end > start && normalized[end - 1] === "-")
+        end -= 1;
+    return normalized.slice(start, end) || "source";
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isXyzTemplate(value) {
+    return nonEmpty(value) && value.includes("{z}") && value.includes("{x}") && value.includes("{y}");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/map/source-to-maplibre.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Plan-bound canonical Source → MapLibre GeoJSON workflow.
+ *
+ * This module is peer-injected and safe to import in Node/SSR/worker code: it
+ * never imports `maplibre-gl`. The first production slice deliberately covers
+ * exact feature-query plans; tile and realtime strategies remain separate.
+ */
+import type { Result, Source } from "../contract/types.js";
+import { type HonuaErrorOptions, HonuaSdkError } from "../core/error-envelope.js";
+import { type ExecuteQueryPlanOptions, type QueryExecutionPlanV1 } from "../query-planner/types.js";
+import { type MapLibreGeometryKind } from "./geojson-projection.js";
+export type MapLibreSourceStrategy = "geojson-query";
+export type { MapLibreGeometryKind } from "./geojson-projection.js";
+export type MapLibreSourceWorkflowState = "ready" | "empty" | "degraded" | "disposed";
+export type MapLibreSourceDiagnosticCode = "strategy-selected" | "empty-result" | "transfer-limit" | "source-degraded" | "geometry-unsupported" | "geometry-mismatch" | "mixed-geometry" | "incremental-update" | "incremental-update-failed";
+export interface MapLibreSourceDiagnostic {
+    readonly code: MapLibreSourceDiagnosticCode;
+    readonly severity: "info" | "warning";
+    readonly stage: "project" | "execute" | "update";
+    readonly fidelity: "exact" | "equivalent" | "unsupported";
+    readonly sourceId: string;
+    readonly planId: string;
+    readonly message: string;
+    readonly detail?: Readonly<Record<string, unknown>>;
+}
+export type MapLibreSourceAdapterErrorCode = "disposed" | "source-conflict" | "layer-conflict" | "unsupported-plan" | "invalid-option" | "map-mutation-failed";
+/** A stable, machine-readable adapter failure. */
+export declare class HonuaMapLibreSourceAdapterError extends HonuaSdkError {
+    readonly code: MapLibreSourceAdapterErrorCode;
+    readonly detail?: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: MapLibreSourceAdapterErrorCode, message: string, detail?: Readonly<Record<string, unknown>> | undefined, options?: HonuaErrorOptions);
+}
+/** Minimal injected MapLibre map surface. */
+export interface SourceToMapLibreMap {
+    getSource(id: string): unknown;
+    addSource(id: string, source: unknown): void;
+    removeSource(id: string): void;
+    getLayer(id: string): unknown;
+    addLayer(layer: unknown, beforeId?: string): void;
+    removeLayer(id: string): void;
+}
+export interface ProjectSourceToMapLibreOptions {
+    readonly sourceId?: string;
+    readonly layerId?: string;
+    readonly beforeId?: string;
+    readonly geometry?: MapLibreGeometryKind | "auto";
+    readonly cluster?: boolean;
+    readonly clusterRadius?: number;
+    readonly attribution?: string;
+    readonly paint?: Readonly<Record<string, unknown>>;
+    readonly layout?: Readonly<Record<string, unknown>>;
+}
+export interface MapLibreSourceProjection {
+    readonly strategy: MapLibreSourceStrategy;
+    readonly sourceId: string;
+    readonly layerId: string;
+    readonly planId: string;
+    readonly planFingerprint: string;
+    readonly sourceVersion?: string;
+    readonly schemaVersion?: string;
+    readonly authorizationScope: readonly string[];
+    readonly source: Readonly<Record<string, unknown>>;
+    readonly layers: readonly Readonly<Record<string, unknown>>[];
+    readonly diagnostics: readonly MapLibreSourceDiagnostic[];
+    readonly state: Exclude<MapLibreSourceWorkflowState, "disposed">;
+}
+export interface MountSourceToMapLibreOptions extends ProjectSourceToMapLibreOptions, ExecuteQueryPlanOptions {
+}
+export interface MountedMapLibreSource {
+    readonly strategy: MapLibreSourceStrategy;
+    readonly sourceId: string;
+    readonly layerIds: readonly string[];
+    readonly planId: string;
+    readonly planFingerprint: string;
+    readonly state: MapLibreSourceWorkflowState;
+    readonly diagnostics: readonly MapLibreSourceDiagnostic[];
+    refresh(options?: ExecuteQueryPlanOptions): Promise<MapLibreSourceProjection>;
+    dispose(): void;
+}
+/**
+ * Project an already-executed plan result into native MapLibre source/layers.
+ * This function is deterministic and does not mutate a map.
+ */
+export declare function projectSourceToMapLibre<T>(source: Source<T>, plan: QueryExecutionPlanV1, result: Result<T>, options?: ProjectSourceToMapLibreOptions): MapLibreSourceProjection;
+/**
+ * Execute an accepted plan, mount its projection, and return one lifecycle.
+ * Omitted execution bindings inherit the accepted plan; explicit overrides
+ * remain fail-closed when they describe another context.
+ */
+export declare function mountSourceToMapLibre<T>(map: SourceToMapLibreMap, source: Source<T>, plan: QueryExecutionPlanV1, options?: MountSourceToMapLibreOptions): Promise<MountedMapLibreSource>;
+//# sourceMappingURL=source-to-maplibre.d.ts.map

package/map/source-to-maplibre.d.ts.map

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