@ignfab/geocontext 0.9.5 → 0.9.7

package/dist/helpers/wfs_engine/queryPreparation.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Query preparation helpers for the structured WFS engine.
+ *
+ * This module centralizes:
+ * - compilation of attribute clauses into CQL fragments
+ * - compilation of spatial filters into CQL fragments
+ * - assembly of query parts used by WFS request builders
+ * - a small façade over lower-level helpers reused elsewhere in the engine
+ */
+import type { Collection, CollectionProperty } from "@ignfab/gpf-schema-store";
+import type { GpfWfsGetFeaturesInput } from "./schema.js";
+export { geometryToEwkt } from "./geometry.js";
+export { validateSelectProperty, getGeometryProperty } from "./properties.js";
+export { getSpatialFilter } from "./spatialFilter.js";
+export type ResolvedFeatureGeometryRef = {
+    geometry_ewkt: string;
+};
+export type CompiledQuery = {
+    geometryProperty: CollectionProperty;
+    cqlFilter?: string;
+    propertyName?: string;
+    sortBy?: string;
+};
+/**
+ * Compiles normalized tool input into query fragments ready to be turned into a WFS request.
+ *
+ * @param input Normalized tool input.
+ * @param featureType Feature type definition loaded from the embedded catalog.
+ * @param resolvedGeometryRef Optional resolved reference geometry for `intersects_feature`.
+ * @returns Compiled query parts used by request builders.
+ */
+export declare function compileQueryParts(input: GpfWfsGetFeaturesInput, featureType: Collection, resolvedGeometryRef?: ResolvedFeatureGeometryRef): CompiledQuery;

package/dist/helpers/wfs_engine/queryPreparation.js

@@ -0,0 +1,149 @@
+/**
+ * Query preparation helpers for the structured WFS engine.
+ *
+ * This module centralizes:
+ * - compilation of attribute clauses into CQL fragments
+ * - compilation of spatial filters into CQL fragments
+ * - assembly of query parts used by WFS request builders
+ * - a small façade over lower-level helpers reused elsewhere in the engine
+ */
+import { buildSelectList, resolveNonGeometryProperty, getGeometryProperty, } from "./properties.js";
+import { getSpatialFilter } from "./spatialFilter.js";
+import { formatScalarValue, normalizeWhereClause, SCALAR_COMPARISON_OPERATORS, NUMERIC_COMPARISON_OPERATORS, } from "./attributeFilter.js";
+import { compileBboxSpatialFilter, compileDwithinSpatialFilter, compileIntersectsFeatureSpatialFilter, compileIntersectsPointSpatialFilter, } from "./spatialCql.js";
+// --- Re-exports ---
+export { geometryToEwkt } from "./geometry.js";
+export { validateSelectProperty, getGeometryProperty } from "./properties.js";
+export { getSpatialFilter } from "./spatialFilter.js";
+// --- Internal Constants ---
+const ORDER_DIRECTION_TO_WFS = {
+    asc: "A",
+    desc: "D",
+};
+// --- Attribute Compilation ---
+/**
+ * Compiles a normalized scalar comparison (`eq` / `ne`) into a CQL fragment.
+ *
+ * @param property Non-geometric property targeted by the clause.
+ * @param clause Normalized scalar comparison clause.
+ * @returns A CQL predicate fragment.
+ */
+function compileScalarComparisonClause(property, clause) {
+    return `${property.name} ${SCALAR_COMPARISON_OPERATORS[clause.operator]} ${formatScalarValue(clause.value)}`;
+}
+/**
+ * Compiles a normalized ordered comparison (`lt` / `lte` / `gt` / `gte`) into a CQL fragment.
+ *
+ * @param property Non-geometric property targeted by the clause.
+ * @param clause Normalized ordered comparison clause.
+ * @returns A CQL predicate fragment.
+ */
+function compileOrderedComparisonClause(property, clause) {
+    return `${property.name} ${NUMERIC_COMPARISON_OPERATORS[clause.operator]} ${formatScalarValue(clause.value)}`;
+}
+/**
+ * Compiles a normalized `in` clause into a CQL fragment.
+ *
+ * @param property Non-geometric property targeted by the clause.
+ * @param clause Normalized `in` clause.
+ * @returns A CQL predicate fragment.
+ */
+function compileInClause(property, clause) {
+    return `${property.name} IN (${clause.values.map(formatScalarValue).join(", ")})`;
+}
+/**
+ * Compiles a normalized `is_null` clause into a CQL fragment.
+ *
+ * @param property Non-geometric property targeted by the clause.
+ * @returns A CQL predicate fragment.
+ */
+function compileIsNullClause(property) {
+    return `${property.name} IS NULL`;
+}
+/**
+ * Compiles a structured where clause into a CQL fragment.
+ *
+ * @param featureType Feature type definition loaded from the embedded catalog.
+ * @param geometryProperty Geometry property already resolved for the feature type.
+ * @param clause Raw where clause received from the tool input.
+ * @returns A CQL predicate fragment.
+ */
+function compileWhereClause(featureType, geometryProperty, clause) {
+    const property = resolveNonGeometryProperty(featureType, geometryProperty, clause.property, "La propriété '{property}' est géométrique. Utiliser `spatial_operator` et ses paramètres dédiés.");
+    const normalized = normalizeWhereClause(property, clause);
+    switch (normalized.operator) {
+        case "eq":
+        case "ne":
+            return compileScalarComparisonClause(property, normalized);
+        case "lt":
+        case "lte":
+        case "gt":
+        case "gte":
+            return compileOrderedComparisonClause(property, normalized);
+        case "in":
+            return compileInClause(property, normalized);
+        case "is_null":
+            return compileIsNullClause(property);
+    }
+}
+/**
+ * Compiles a structured sort clause into a WFS `sortBy` fragment.
+ *
+ * @param featureType Feature type definition loaded from the embedded catalog.
+ * @param geometryProperty Geometry property already resolved for the feature type.
+ * @param clause Raw order-by clause received from the tool input.
+ * @returns A WFS `sortBy` fragment.
+ */
+function compileOrderByClause(featureType, geometryProperty, clause) {
+    const property = resolveNonGeometryProperty(featureType, geometryProperty, clause.property, "La propriété '{property}' est géométrique. Utiliser une propriété non géométrique pour `order_by`.");
+    return `${property.name} ${ORDER_DIRECTION_TO_WFS[clause.direction]}`;
+}
+// --- Query Compilation ---
+/**
+ * Compiles normalized tool input into query fragments ready to be turned into a WFS request.
+ *
+ * @param input Normalized tool input.
+ * @param featureType Feature type definition loaded from the embedded catalog.
+ * @param resolvedGeometryRef Optional resolved reference geometry for `intersects_feature`.
+ * @returns Compiled query parts used by request builders.
+ */
+export function compileQueryParts(input, featureType, resolvedGeometryRef) {
+    const geometryProperty = getGeometryProperty(featureType);
+    const spatialFilter = getSpatialFilter(input);
+    const fragments = [];
+    // Keep the spatial predicate first: the GeoPlateforme GeoServer is sensitive
+    // to filter ordering and may reject equivalent filters when attributes come first.
+    if (spatialFilter) {
+        switch (spatialFilter.operator) {
+            case "bbox":
+                fragments.push(compileBboxSpatialFilter(geometryProperty, spatialFilter));
+                break;
+            case "intersects_point":
+                fragments.push(compileIntersectsPointSpatialFilter(geometryProperty, spatialFilter));
+                break;
+            case "dwithin_point":
+                fragments.push(compileDwithinSpatialFilter(geometryProperty, spatialFilter));
+                break;
+            case "intersects_feature":
+                if (!resolvedGeometryRef) {
+                    throw new Error("Le filtre spatial `intersects_feature` exige la résolution préalable de la géométrie de référence.");
+                }
+                fragments.push(compileIntersectsFeatureSpatialFilter(geometryProperty, resolvedGeometryRef.geometry_ewkt));
+                break;
+        }
+    }
+    for (const clause of input.where ?? []) {
+        fragments.push(compileWhereClause(featureType, geometryProperty, clause));
+    }
+    const sortBy = input.order_by && input.order_by.length > 0
+        ? input.order_by.map((clause) => compileOrderByClause(featureType, geometryProperty, clause)).join(",")
+        : undefined;
+    const propertyNames = buildSelectList(featureType, geometryProperty, input);
+    return {
+        geometryProperty,
+        cqlFilter: fragments.length > 0 ? fragments.join(" AND ") : undefined,
+        propertyName: propertyNames.length > 0 ? propertyNames.join(",") : undefined,
+        sortBy,
+    };
+}
+//# sourceMappingURL=queryPreparation.js.map

package/dist/helpers/wfs_engine/queryPreparation.js.map

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

package/dist/helpers/wfs_engine/request.d.ts

@@ -0,0 +1,94 @@
+/**
+ * WFS request builders used by the structured WFS engine.
+ *
+ * This module centralizes:
+ * - the transport shape shared by compiled requests
+ * - GET/POST request assembly helpers
+ * - the compact request payload exposed by MCP `result_type="request"`
+ */
+import type { GpfWfsGetFeaturesInput } from "./schema.js";
+type WfsRequestTransport = {
+    method: "POST";
+    url: string;
+    query: Record<string, string>;
+    body: string;
+};
+export type CompiledRequest = WfsRequestTransport & {
+    get_url?: string | null;
+};
+export type WfsRequestPayload = WfsRequestTransport & {
+    result_type: "request";
+    get_url: string | null;
+};
+/**
+ * Maps a compiled WFS request to the compact MCP request payload.
+ *
+ * @param request Compiled request ready to be executed against the WFS service.
+ * @returns A normalized request payload exposed by MCP tools.
+ */
+export declare function toWfsRequestPayload(request: CompiledRequest): WfsRequestPayload;
+/**
+ * Builds a portable GET URL variant of the request when it stays below the configured limit.
+ *
+ * This helper is mainly used to populate `get_url` in request payloads
+ * returned by `result_type="request"`.
+ *
+ * @param url Base WFS endpoint URL.
+ * @param query Query-string parameters sent with the request.
+ * @param cqlFilter Optional CQL filter to append to the GET variant.
+ * @returns A derived GET URL, or `null` when it would be too long to expose safely.
+ */
+export declare function buildGetUrl(url: string, query: Record<string, string>, cqlFilter?: string): string | null;
+/**
+ * Builds the main WFS GetFeature request from normalized tool input and compiled query parts.
+ *
+ * @param input Normalized tool input.
+ * @param compiled Compiled query fragments produced from the input and feature type.
+ * @returns A POST request split into base URL, query-string parameters, encoded body, and optional GET variant.
+ */
+export declare function buildMainRequest(input: GpfWfsGetFeaturesInput, compiled: {
+    cqlFilter?: string;
+    propertyName?: string;
+    sortBy?: string;
+}): CompiledRequest;
+/**
+ * Builds the auxiliary request used to fetch the geometry of a reference feature.
+ *
+ * @param typename Typename of the reference layer.
+ * @param featureId Identifier of the reference feature.
+ * @param geometryPropertyName Geometry property to request from the reference layer.
+ * @returns A POST request targeting the reference feature lookup.
+ */
+export declare function buildReferenceGeometryRequest(typename: string, featureId: string, geometryPropertyName: string): CompiledRequest;
+/**
+ * Builds a GetFeature request targeting exactly one feature by its WFS `featureID`.
+ *
+ * @param typename Typename of the target layer.
+ * @param featureId Identifier of the target feature.
+ * @param propertyName Optional comma-separated property list.
+ * @returns A POST request split into base URL, query-string parameters, empty body, and optional GET variant.
+ */
+export declare function buildGetFeatureByIdRequest(typename: string, featureId: string, propertyName?: string): CompiledRequest;
+/**
+ * Input parameters for building a multi-typename WFS request.
+ */
+export type MultiTypenameRequestInput = {
+    /** Fully qualified WFS type names to query. */
+    typenames: string[];
+    /** Pre-compiled CQL filter string, when one shared filter is intentionally reused for all typenames. */
+    cqlFilter?: string;
+    /** Pre-compiled CQL filters aligned with `typenames` (same length, same order). */
+    cqlFilters?: string[];
+};
+/**
+ * Builds a WFS GetFeature request targeting multiple typenames.
+ *
+ * Unlike `buildMainRequest()`, this builder accepts a raw CQL filter
+ * and a list of typenames, making it suitable for domain-oriented modules
+ * that query several layers at once.
+ *
+ * @param input Multi-typename request parameters.
+ * @returns A POST request split into base URL, query-string parameters, encoded body, and optional GET variant.
+ */
+export declare function buildMultiTypenameRequest(input: MultiTypenameRequestInput): CompiledRequest;
+export {};

package/dist/helpers/wfs_engine/request.js

@@ -0,0 +1,197 @@
+/**
+ * WFS request builders used by the structured WFS engine.
+ *
+ * This module centralizes:
+ * - the transport shape shared by compiled requests
+ * - GET/POST request assembly helpers
+ * - the compact request payload exposed by MCP `result_type="request"`
+ */
+import { GPF_WFS_URL } from "../../gpf/wfs-schema-catalog.js";
+import { REQUEST_GET_URL_MAX_LENGTH } from "./schema.js";
+// --- Request Payload Mapping ---
+/**
+ * Maps a compiled WFS request to the compact MCP request payload.
+ *
+ * @param request Compiled request ready to be executed against the WFS service.
+ * @returns A normalized request payload exposed by MCP tools.
+ */
+export function toWfsRequestPayload(request) {
+    return {
+        result_type: "request",
+        method: request.method,
+        url: request.url,
+        query: request.query,
+        body: request.body,
+        get_url: request.get_url ?? null,
+    };
+}
+// --- Request Assembly Helpers ---
+/**
+ * Encodes the optional CQL filter as an `application/x-www-form-urlencoded` POST body.
+ *
+ * @param cqlFilter Compiled CQL filter, when the request needs one.
+ * @returns The encoded POST body, or an empty string when no filter is present.
+ */
+function buildBody(cqlFilter) {
+    if (!cqlFilter) {
+        return "";
+    }
+    return new URLSearchParams({ cql_filter: cqlFilter }).toString();
+}
+/**
+ * Builds a portable GET URL variant of the request when it stays below the configured limit.
+ *
+ * This helper is mainly used to populate `get_url` in request payloads
+ * returned by `result_type="request"`.
+ *
+ * @param url Base WFS endpoint URL.
+ * @param query Query-string parameters sent with the request.
+ * @param cqlFilter Optional CQL filter to append to the GET variant.
+ * @returns A derived GET URL, or `null` when it would be too long to expose safely.
+ */
+export function buildGetUrl(url, query, cqlFilter) {
+    const params = new URLSearchParams(query);
+    if (cqlFilter) {
+        params.set("cql_filter", cqlFilter);
+    }
+    const getUrl = `${url}?${params.toString()}`;
+    if (getUrl.length > REQUEST_GET_URL_MAX_LENGTH) {
+        return null;
+    }
+    return getUrl;
+}
+// --- Public Builders ---
+/**
+ * Builds the main WFS GetFeature request from normalized tool input and compiled query parts.
+ *
+ * @param input Normalized tool input.
+ * @param compiled Compiled query fragments produced from the input and feature type.
+ * @returns A POST request split into base URL, query-string parameters, encoded body, and optional GET variant.
+ */
+export function buildMainRequest(input, compiled) {
+    const query = {
+        service: "WFS",
+        version: "2.0.0",
+        request: "GetFeature",
+        typeNames: input.typename,
+        outputFormat: "application/json",
+        exceptions: "application/json",
+        count: input.result_type === "hits" ? "1" : String(input.limit),
+    };
+    if (compiled.propertyName && input.result_type !== "hits") {
+        query.propertyName = compiled.propertyName;
+    }
+    if (compiled.sortBy) {
+        query.sortBy = compiled.sortBy;
+    }
+    const body = buildBody(compiled.cqlFilter);
+    return {
+        method: "POST",
+        url: GPF_WFS_URL,
+        query,
+        body,
+        get_url: buildGetUrl(GPF_WFS_URL, query, compiled.cqlFilter),
+    };
+}
+/**
+ * Builds the auxiliary request used to fetch the geometry of a reference feature.
+ *
+ * @param typename Typename of the reference layer.
+ * @param featureId Identifier of the reference feature.
+ * @param geometryPropertyName Geometry property to request from the reference layer.
+ * @returns A POST request targeting the reference feature lookup.
+ */
+export function buildReferenceGeometryRequest(typename, featureId, geometryPropertyName) {
+    const query = {
+        service: "WFS",
+        version: "2.0.0",
+        request: "GetFeature",
+        typeNames: typename,
+        outputFormat: "application/json",
+        exceptions: "application/json",
+        featureID: featureId,
+        propertyName: geometryPropertyName,
+        count: "1",
+    };
+    return {
+        method: "POST",
+        url: GPF_WFS_URL,
+        query,
+        body: "",
+        get_url: buildGetUrl(GPF_WFS_URL, query),
+    };
+}
+/**
+ * Builds a GetFeature request targeting exactly one feature by its WFS `featureID`.
+ *
+ * @param typename Typename of the target layer.
+ * @param featureId Identifier of the target feature.
+ * @param propertyName Optional comma-separated property list.
+ * @returns A POST request split into base URL, query-string parameters, empty body, and optional GET variant.
+ */
+export function buildGetFeatureByIdRequest(typename, featureId, propertyName) {
+    const query = {
+        service: "WFS",
+        version: "2.0.0",
+        request: "GetFeature",
+        typeNames: typename,
+        outputFormat: "application/json",
+        exceptions: "application/json",
+        featureID: featureId,
+        count: "2",
+    };
+    if (propertyName) {
+        query.propertyName = propertyName;
+    }
+    return {
+        method: "POST",
+        url: GPF_WFS_URL,
+        query,
+        body: "",
+        get_url: buildGetUrl(GPF_WFS_URL, query),
+    };
+}
+/**
+ * Builds a WFS GetFeature request targeting multiple typenames.
+ *
+ * Unlike `buildMainRequest()`, this builder accepts a raw CQL filter
+ * and a list of typenames, making it suitable for domain-oriented modules
+ * that query several layers at once.
+ *
+ * @param input Multi-typename request parameters.
+ * @returns A POST request split into base URL, query-string parameters, encoded body, and optional GET variant.
+ */
+export function buildMultiTypenameRequest(input) {
+    if (input.cqlFilter && input.cqlFilters) {
+        throw new Error("`cqlFilter` et `cqlFilters` ne peuvent pas être utilisés ensemble.");
+    }
+    if (input.cqlFilters && input.cqlFilters.length !== input.typenames.length) {
+        throw new Error(`Le nombre de filtres CQL (${input.cqlFilters.length}) doit correspondre au nombre de typenames (${input.typenames.length}).`);
+    }
+    const encodedTypeNames = input.typenames.map((typename) => `(${typename})`).join("");
+    const expandedCqlFilter = input.cqlFilters
+        ? input.cqlFilters.join(";")
+        : input.cqlFilter
+            ? input.typenames.map(() => input.cqlFilter).join(";")
+            : undefined;
+    const query = {
+        service: "WFS",
+        version: "2.0.0",
+        request: "GetFeature",
+        typeNames: encodedTypeNames,
+        outputFormat: "application/json",
+        exceptions: "application/json",
+        srsName: "EPSG:4326",
+    };
+    const body = expandedCqlFilter
+        ? new URLSearchParams({ cql_filter: expandedCqlFilter }).toString()
+        : "";
+    return {
+        method: "POST",
+        url: GPF_WFS_URL,
+        query,
+        body,
+        get_url: buildGetUrl(GPF_WFS_URL, query, expandedCqlFilter),
+    };
+}
+//# sourceMappingURL=request.js.map

package/dist/helpers/wfs_engine/request.js.map

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

package/dist/helpers/wfs_engine/response.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Structured WFS response layer used by the MCP WFS tools and domain-oriented modules.
+ *
+ * This module provides:
+ * - FeatureCollection-preserving transformations for the MCP WFS tools
+ * - Flat item mapping for domain-oriented modules (`src/gpf/*`)
+ */
+type GenericFeature = {
+    id?: unknown;
+    geometry?: unknown;
+    geometry_name?: string;
+    bbox?: unknown;
+    properties?: unknown;
+    [key: string]: unknown;
+};
+type GenericFeatureCollection = {
+    features?: GenericFeature[];
+    [key: string]: unknown;
+};
+type FeatureRef = {
+    typename: string | null;
+    feature_id: string;
+};
+type TransformedFeature = Record<string, unknown> & {
+    feature_ref?: FeatureRef;
+};
+type TransformedFeatureCollection = Record<string, unknown> & {
+    features?: TransformedFeature[];
+};
+/**
+ * A flattened WFS feature with properties spread at the top level.
+ *
+ * This is the output format used by domain-oriented modules (`src/gpf/*`)
+ * as opposed to the FeatureCollection-preserving format used by the MCP WFS tools.
+ */
+export type FlatItem = Record<string, unknown> & {
+    type: string;
+    id: string;
+    bbox?: number[];
+    feature_ref?: {
+        typename: string;
+        feature_id: string;
+    };
+};
+/**
+ * Removes raw geometry payloads from a FeatureCollection, keeps GeoJSON validity by forcing
+ * `geometry: null`, and exposes lightweight `feature_ref` objects reusable by follow-up requests.
+ *
+ * @param featureCollection Raw FeatureCollection returned by the WFS endpoint.
+ * @returns A transformed FeatureCollection with raw geometry fields removed, `geometry: null`, and optional `feature_ref` metadata.
+ */
+export declare function transformFeatureCollectionResponse(featureCollection: GenericFeatureCollection): TransformedFeatureCollection;
+/**
+ * Transforms a FeatureCollection and injects the exact queried typename into each `feature_ref`.
+ *
+ * @param featureCollection Raw FeatureCollection returned by the WFS endpoint.
+ * @param typename Typename of the queried layer.
+ * @returns A transformed FeatureCollection whose `feature_ref` objects carry the exact typename.
+ */
+export declare function attachFeatureRefs(featureCollection: GenericFeatureCollection, typename: string): TransformedFeatureCollection;
+/**
+ * Maps a FeatureCollection to an array of flat items without preserving geometry.
+ *
+ * @param featureCollection Raw FeatureCollection returned by the WFS endpoint.
+ * @param knownTypeNames Fully qualified typenames used for `feature_ref` resolution.
+ * @returns An array of flat items with spread properties and `feature_ref`.
+ */
+export declare function mapToFlatItems(featureCollection: GenericFeatureCollection, knownTypeNames: string[]): FlatItem[];
+/**
+ * Maps a FeatureCollection to an array of flat items preserving raw geometry
+ * in a temporary `_rawGeometry` field for downstream distance calculations.
+ *
+ * Callers should strip `_rawGeometry` from the final output.
+ *
+ * @param featureCollection Raw FeatureCollection returned by the WFS endpoint.
+ * @param knownTypeNames Fully qualified typenames used for `feature_ref` resolution.
+ * @returns An array of flat items with `_rawGeometry` preserved.
+ */
+export declare function mapToFlatItemsWithGeometry(featureCollection: GenericFeatureCollection, knownTypeNames: string[]): FlatItem[];
+export {};