graphile-postgis 2.10.0 → 2.11.0

package/esm/plugins/spatial-relations.js

@@ -0,0 +1,575 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import 'graphile-connection-filter';
+import sql from 'pg-sql2';
+export const OPERATOR_REGISTRY = {
+    st_contains: {
+        name: 'st_contains',
+        kind: 'function',
+        pgToken: 'st_contains',
+        parametric: false,
+        description: 'Every point of the owner column lies in the interior of the target column (ST_Contains).',
+    },
+    st_within: {
+        name: 'st_within',
+        kind: 'function',
+        pgToken: 'st_within',
+        parametric: false,
+        description: 'Owner column is completely inside the target column (ST_Within).',
+    },
+    st_covers: {
+        name: 'st_covers',
+        kind: 'function',
+        pgToken: 'st_covers',
+        parametric: false,
+        description: 'No point in the target column lies outside the owner column (ST_Covers).',
+    },
+    st_coveredby: {
+        name: 'st_coveredby',
+        kind: 'function',
+        pgToken: 'st_coveredby',
+        parametric: false,
+        description: 'No point in the owner column lies outside the target column (ST_CoveredBy).',
+    },
+    st_intersects: {
+        name: 'st_intersects',
+        kind: 'function',
+        pgToken: 'st_intersects',
+        parametric: false,
+        description: 'Owner and target columns share any portion of space (ST_Intersects).',
+    },
+    st_equals: {
+        name: 'st_equals',
+        kind: 'function',
+        pgToken: 'st_equals',
+        parametric: false,
+        description: 'Owner and target columns represent the same geometry (ST_Equals).',
+    },
+    st_bbox_intersects: {
+        name: 'st_bbox_intersects',
+        kind: 'infix',
+        pgToken: '&&',
+        parametric: false,
+        description: "Owner column's 2D bounding box intersects the target's 2D bounding box (&&).",
+    },
+    st_dwithin: {
+        name: 'st_dwithin',
+        kind: 'function',
+        pgToken: 'st_dwithin',
+        parametric: true,
+        description: 'Owner column is within <distance> of the target column (ST_DWithin). ' +
+            'Distance is in meters for geography, SRID coordinate units for geometry.',
+    },
+};
+/**
+ * Parse a single `@spatialRelation` tag value.
+ *
+ * Accepts a string of the form `<name> <target> <op> [<param>]`.
+ */
+export function parseSpatialRelationTag(raw) {
+    if (typeof raw !== 'string') {
+        return { ok: false, error: `Expected string, got ${typeof raw}` };
+    }
+    const parts = raw.trim().split(/\s+/);
+    if (parts.length < 3 || parts.length > 4) {
+        return {
+            ok: false,
+            error: `Expected 3 or 4 whitespace-separated tokens; got ${parts.length}`,
+        };
+    }
+    const [relationName, targetRef, operator, paramName] = parts;
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(relationName)) {
+        return { ok: false, error: `Invalid relation name '${relationName}'` };
+    }
+    if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(targetRef)) {
+        return { ok: false, error: `Invalid target reference '${targetRef}'` };
+    }
+    const targetParts = targetRef.split('.');
+    if (targetParts.length < 2 || targetParts.length > 3) {
+        return {
+            ok: false,
+            error: `Target must be 'table.col' or 'schema.table.col'; got '${targetRef}'`,
+        };
+    }
+    if (!(operator in OPERATOR_REGISTRY)) {
+        const known = Object.keys(OPERATOR_REGISTRY).sort().join(', ');
+        return {
+            ok: false,
+            error: `Unknown spatial operator '${operator}'. Known ops: ${known}`,
+        };
+    }
+    const op = OPERATOR_REGISTRY[operator];
+    if (op.parametric) {
+        if (!paramName) {
+            return {
+                ok: false,
+                error: `Operator '${operator}' requires a parameter name (e.g. 'distance')`,
+            };
+        }
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(paramName)) {
+            return { ok: false, error: `Invalid param name '${paramName}'` };
+        }
+    }
+    else {
+        if (paramName) {
+            return {
+                ok: false,
+                error: `Operator '${operator}' does not take a parameter; got extra token '${paramName}'`,
+            };
+        }
+    }
+    return {
+        ok: true,
+        relationName,
+        targetRef,
+        operator,
+        paramName: paramName ?? null,
+    };
+}
+/**
+ * Resolve a `<table.col>` or `<schema.table.col>` reference to a
+ * `pgResource` + attribute name.
+ */
+function resolveTargetRef(pgRegistry, ownerResource, targetRef) {
+    const parts = targetRef.split('.');
+    let schemaName = null;
+    let tableName;
+    let columnName;
+    if (parts.length === 2) {
+        [tableName, columnName] = parts;
+    }
+    else {
+        [schemaName, tableName, columnName] = parts;
+    }
+    const ownerPgExt = ownerResource?.codec?.extensions?.pg;
+    const defaultSchema = ownerPgExt?.schemaName ?? 'public';
+    const lookupSchema = schemaName ?? defaultSchema;
+    for (const res of Object.values(pgRegistry.pgResources)) {
+        if (res.parameters)
+            continue;
+        const pg = res?.codec?.extensions?.pg;
+        if (!pg)
+            continue;
+        if (pg.name !== tableName)
+            continue;
+        if (pg.schemaName !== lookupSchema)
+            continue;
+        const attr = res.codec.attributes?.[columnName];
+        if (!attr)
+            return null;
+        return { resource: res, attributeName: columnName };
+    }
+    return null;
+}
+/** Get the PK attribute names for a resource, or null if none discoverable. */
+function getPrimaryKeyAttributes(resource) {
+    const uniques = resource?.uniques;
+    if (!uniques || uniques.length === 0)
+        return null;
+    const primary = uniques.find((u) => u.isPrimary);
+    const chosen = primary ?? uniques[0];
+    if (!chosen?.attributes || chosen.attributes.length === 0)
+        return null;
+    return chosen.attributes;
+}
+/**
+ * Collect tag strings from an attribute, handling the `string | string[]`
+ * normalisation graphile-build-pg does for repeated smart tags.
+ */
+function collectTagStrings(tagValue) {
+    if (tagValue == null)
+        return [];
+    if (Array.isArray(tagValue)) {
+        return tagValue.filter((v) => typeof v === 'string');
+    }
+    if (typeof tagValue === 'string')
+        return [tagValue];
+    return [];
+}
+/**
+ * Build the full set of spatial relations from all resources.
+ * Validates tags and throws (at schema build) on anything malformed.
+ * Returns relations keyed by (owner codec identity, relation name).
+ */
+export function collectSpatialRelations(build) {
+    const pgRegistry = build.input?.pgRegistry;
+    if (!pgRegistry)
+        return [];
+    const relations = [];
+    for (const resource of Object.values(pgRegistry.pgResources)) {
+        if (resource.parameters)
+            continue;
+        const attributes = resource.codec?.attributes;
+        if (!attributes)
+            continue;
+        for (const [ownerAttributeName, attribute] of Object.entries(attributes)) {
+            const tags = attribute?.extensions?.tags;
+            if (!tags)
+                continue;
+            const rawValues = collectTagStrings(tags.spatialRelation);
+            if (rawValues.length === 0)
+                continue;
+            for (const rawValue of rawValues) {
+                const parsed = parseSpatialRelationTag(rawValue);
+                if (parsed.ok !== true) {
+                    throw new Error(`[graphile-postgis] Invalid @spatialRelation tag on ` +
+                        `${resource.codec.name}.${ownerAttributeName}: ${parsed.error}`);
+                }
+                const target = resolveTargetRef(pgRegistry, resource, parsed.targetRef);
+                if (!target) {
+                    throw new Error(`[graphile-postgis] @spatialRelation tag on ` +
+                        `${resource.codec.name}.${ownerAttributeName} references ` +
+                        `'${parsed.targetRef}' which does not resolve to a known column.`);
+                }
+                // Validate geometry/geography codec symmetry.
+                const ownerPgExt = attribute.codec?.extensions?.pg;
+                const targetAttr = target.resource.codec.attributes[target.attributeName];
+                const targetPgExt = targetAttr?.codec?.extensions?.pg;
+                const ownerBase = ownerPgExt?.name;
+                const targetBase = targetPgExt?.name;
+                if ((ownerBase === 'geometry' || ownerBase === 'geography') &&
+                    (targetBase === 'geometry' || targetBase === 'geography') &&
+                    ownerBase !== targetBase) {
+                    throw new Error(`[graphile-postgis] @spatialRelation ${resource.codec.name}.${ownerAttributeName} ` +
+                        `-> ${target.resource.codec.name}.${target.attributeName}: ` +
+                        `codec mismatch (${ownerBase} vs ${targetBase}). Both sides must share a base codec.`);
+                }
+                if (ownerBase !== 'geometry' &&
+                    ownerBase !== 'geography') {
+                    throw new Error(`[graphile-postgis] @spatialRelation requires a geometry or geography column; ` +
+                        `${resource.codec.name}.${ownerAttributeName} is ${ownerBase ?? 'unknown'}.`);
+                }
+                const isSelfRelation = resource === target.resource;
+                const ownerPkAttributes = getPrimaryKeyAttributes(resource);
+                const targetPkAttributes = getPrimaryKeyAttributes(target.resource);
+                if (isSelfRelation && !ownerPkAttributes) {
+                    throw new Error(`[graphile-postgis] @spatialRelation '${parsed.relationName}' on ` +
+                        `${resource.codec.name}.${ownerAttributeName} is a self-relation, but the ` +
+                        `table has no primary key; refusing to register (would match every row against itself).`);
+                }
+                relations.push({
+                    relationName: parsed.relationName,
+                    ownerCodec: resource.codec,
+                    ownerAttributeName,
+                    targetResource: target.resource,
+                    targetAttributeName: target.attributeName,
+                    operator: OPERATOR_REGISTRY[parsed.operator],
+                    paramFieldName: parsed.paramName,
+                    isSelfRelation,
+                    ownerPkAttributes,
+                    targetPkAttributes,
+                });
+            }
+        }
+    }
+    // Detect duplicate (ownerCodec, relationName) pairs — emit a clear error
+    // rather than letting registerInputObjectType throw generic "already exists".
+    const seen = new Map();
+    for (const rel of relations) {
+        const key = `${rel.ownerCodec.name}:${rel.relationName}`;
+        const prior = seen.get(key);
+        if (prior) {
+            throw new Error(`[graphile-postgis] Duplicate @spatialRelation name '${rel.relationName}' on ` +
+                `codec '${rel.ownerCodec.name}'. Each relation name must be unique per owning table.`);
+        }
+        seen.set(key, rel);
+    }
+    return relations;
+}
+/** Name of the per-relation filter type: `<Owner>Spatial<Relation>Filter`. */
+function spatialFilterTypeName(build, rel) {
+    const { inflection } = build;
+    const ownerTypeName = inflection.tableType(rel.ownerCodec);
+    const rel0 = rel.relationName.charAt(0).toUpperCase() + rel.relationName.slice(1);
+    return `${ownerTypeName}Spatial${rel0}Filter`;
+}
+/**
+ * Build the SQL fragment that joins the inner (target) row to the outer
+ * (owner) row using the resolved PostGIS predicate.
+ */
+function buildSpatialJoinFragment(rel, schemaName, outerAlias, innerAlias, distanceValue) {
+    // Tag grammar reads as "<owner_col> <op> <target_col>" (e.g. "location
+    // st_within counties.geom"), so the emitted PostGIS call is always
+    // `ST_<op>(owner_col, target_col)`. For symmetric operators
+    // (st_intersects, st_dwithin, st_equals, &&) the ordering is immaterial;
+    // for directional ones (st_within, st_contains, st_covers, st_coveredby)
+    // reversing the operands inverts the set of matched rows.
+    const ownerExpr = sql `${outerAlias}.${sql.identifier(rel.ownerAttributeName)}`;
+    const targetExpr = sql `${innerAlias}.${sql.identifier(rel.targetAttributeName)}`;
+    if (rel.operator.kind === 'infix') {
+        // Only `&&` today — simple inline (symmetric).
+        return sql `${ownerExpr} && ${targetExpr}`;
+    }
+    const fn = sql.identifier(schemaName, rel.operator.pgToken);
+    if (rel.operator.parametric) {
+        if (!distanceValue) {
+            // The apply() guards this; defensive throw.
+            throw new Error(`[graphile-postgis] Parametric operator '${rel.operator.name}' invoked without ` +
+                `a distance value in spatial relation '${rel.relationName}'.`);
+        }
+        return sql `${fn}(${ownerExpr}, ${targetExpr}, ${distanceValue})`;
+    }
+    return sql `${fn}(${ownerExpr}, ${targetExpr})`;
+}
+/** Build the `other.pk <> self.pk` exclusion predicate for self-relations. */
+function buildSelfExclusionFragment(rel, outerAlias, innerAlias) {
+    if (!rel.isSelfRelation)
+        return null;
+    const pk = rel.ownerPkAttributes;
+    if (!pk || pk.length === 0)
+        return null;
+    if (pk.length === 1) {
+        const c = pk[0];
+        return sql `${innerAlias}.${sql.identifier(c)} <> ${outerAlias}.${sql.identifier(c)}`;
+    }
+    // Composite PK: IS DISTINCT FROM tuple comparison.
+    const left = sql.join(pk.map((c) => sql `${innerAlias}.${sql.identifier(c)}`), ', ');
+    const right = sql.join(pk.map((c) => sql `${outerAlias}.${sql.identifier(c)}`), ', ');
+    return sql `(${left}) IS DISTINCT FROM (${right})`;
+}
+export const PostgisSpatialRelationsPlugin = {
+    name: 'PostgisSpatialRelationsPlugin',
+    version: '1.0.0',
+    description: 'Adds cross-table spatial filtering via @spatialRelation smart tags; ' +
+        'synthesises virtual relations whose EXISTS predicate uses PostGIS ops ' +
+        'instead of column equality.',
+    after: [
+        'PostgisExtensionDetectionPlugin',
+        'PostgisRegisterTypesPlugin',
+        'ConnectionFilterBackwardRelationsPlugin',
+    ],
+    schema: {
+        hooks: {
+            build(build) {
+                const postgisInfo = build.pgGISExtensionInfo;
+                if (!postgisInfo)
+                    return build;
+                const relations = collectSpatialRelations(build);
+                // Emit GIST-index warnings for target columns without a GIST index.
+                // Warnings never block schema build — we defer to the build logger.
+                const warn = build.console?.warn ?? console.warn;
+                for (const rel of relations) {
+                    const targetAttr = rel.targetResource.codec.attributes?.[rel.targetAttributeName];
+                    const indexes = rel.targetResource.extensions?.pg?.indexes;
+                    let hasGist = false;
+                    if (Array.isArray(indexes)) {
+                        hasGist = indexes.some((idx) => idx &&
+                            typeof idx === 'object' &&
+                            idx.method === 'gist' &&
+                            Array.isArray(idx.attributes) &&
+                            idx.attributes.includes(rel.targetAttributeName));
+                    }
+                    // Introspection of indexes through @dataplan/pg isn't universally
+                    // exposed; if we can't tell, stay quiet rather than cry wolf.
+                    const canDiscoverIndexes = Array.isArray(indexes);
+                    const skipCheck = targetAttr?.extensions?.tags?.spatialRelationSkipIndexCheck === true;
+                    if (canDiscoverIndexes && !hasGist && !skipCheck) {
+                        warn(`[graphile-postgis] Spatial relation '${rel.relationName}' ` +
+                            `targets ${rel.targetResource.codec.name}.${rel.targetAttributeName} ` +
+                            `which has no GIST index; expect sequential scans. ` +
+                            `Recommended: CREATE INDEX ON ${rel.targetResource.codec.name} ` +
+                            `USING GIST (${rel.targetAttributeName});`);
+                    }
+                }
+                return build.extend(build, { pgGISSpatialRelations: relations }, 'PostgisSpatialRelationsPlugin adding spatial relation registry');
+            },
+            init(_, build) {
+                if (!build.pgGISExtensionInfo)
+                    return _;
+                const relations = build.pgGISSpatialRelations;
+                if (!relations || relations.length === 0)
+                    return _;
+                for (const rel of relations) {
+                    const typeName = spatialFilterTypeName(build, rel);
+                    if (build.getTypeMetaByName(typeName))
+                        continue;
+                    const targetTypeName = build.inflection.tableType(rel.targetResource.codec);
+                    build.recoverable(null, () => {
+                        build.registerInputObjectType(typeName, {
+                            // NOTE: intentionally NOT setting `isPgConnectionFilterMany`.
+                            // That flag triggers ConnectionFilterBackwardRelationsPlugin
+                            // (and friends) to auto-register `some`/`every`/`none` fields
+                            // with FK-join semantics, which would collide with — and
+                            // semantically differ from — ours. We own those fields here.
+                            foreignTable: rel.targetResource,
+                            isPgGISSpatialFilter: true,
+                            pgGISSpatialRelation: rel,
+                        }, () => ({
+                            name: typeName,
+                            description: `A filter on \`${targetTypeName}\` rows spatially related ` +
+                                `to the current row via \`${rel.operator.name}\`. ` +
+                                `All fields are combined with a logical \u2018and\u2019.`,
+                        }), `PostgisSpatialRelationsPlugin adding '${typeName}' spatial filter type`);
+                    });
+                }
+                return _;
+            },
+            GraphQLInputObjectType_fields(inFields, build, context) {
+                if (!build.pgGISExtensionInfo)
+                    return inFields;
+                const relations = build.pgGISSpatialRelations;
+                if (!relations || relations.length === 0)
+                    return inFields;
+                let fields = inFields;
+                const { extend, inflection, graphql: { GraphQLFloat, GraphQLNonNull }, EXPORTABLE, } = build;
+                const { fieldWithHooks, scope: { pgCodec, isPgConnectionFilter, isPgGISSpatialFilter, pgGISSpatialRelation, }, } = context;
+                const postgisInfo = build.pgGISExtensionInfo;
+                const { schemaName } = postgisInfo;
+                // ── Part 1: inject <relationName> on the owning codec's filter type
+                if (isPgConnectionFilter && pgCodec) {
+                    const ownRelations = relations.filter((r) => r.ownerCodec === pgCodec);
+                    for (const rel of ownRelations) {
+                        const filterTypeName = spatialFilterTypeName(build, rel);
+                        const FilterType = build.getTypeByName(filterTypeName);
+                        if (!FilterType)
+                            continue;
+                        const fieldName = rel.relationName;
+                        // Avoid clobbering fields an upstream plugin may have registered
+                        // (e.g. an FK-derived relation with the same name).
+                        if (fields[fieldName]) {
+                            throw new Error(`[graphile-postgis] @spatialRelation '${rel.relationName}' on ` +
+                                `codec '${rel.ownerCodec.name}' collides with an existing filter ` +
+                                `field of the same name. Rename the spatial relation or the colliding field.`);
+                        }
+                        const targetTypeName = inflection.tableType(rel.targetResource.codec);
+                        const relSnapshot = rel;
+                        fields = extend(fields, {
+                            [fieldName]: fieldWithHooks({
+                                fieldName,
+                                isPgConnectionFilterField: true,
+                                isPgGISSpatialRelationField: true,
+                            }, () => ({
+                                description: `Filter by rows from \`${targetTypeName}\` related to this ` +
+                                    `row via \`${relSnapshot.operator.name}\`.`,
+                                type: FilterType,
+                                apply: EXPORTABLE((relationInfo) => function ($where, value) {
+                                    if (value == null)
+                                        return;
+                                    $where._spatialRelation = relationInfo;
+                                    // Parent apply runs BEFORE child field applies, so
+                                    // read the parametric value here (if any) and stash
+                                    // it on $where for some/every/none to consume. This
+                                    // avoids relying on input-field iteration order.
+                                    if (relationInfo.operator.parametric &&
+                                        relationInfo.paramFieldName) {
+                                        const raw = value[relationInfo.paramFieldName];
+                                        if (typeof raw !== 'number') {
+                                            throw Object.assign(new Error(`Spatial relation '${relationInfo.relationName}' requires ` +
+                                                `a numeric '${relationInfo.paramFieldName}' argument; got ${raw}`), {});
+                                        }
+                                        $where._spatialRelationParam = raw;
+                                    }
+                                    return $where;
+                                }, [relSnapshot]),
+                            })),
+                        }, `PostgisSpatialRelationsPlugin adding '${fieldName}' field to ` +
+                            `${inflection.filterType(inflection.tableType(rel.ownerCodec))}`);
+                    }
+                }
+                // ── Part 2: inject some/every/none (+ optional distance) on the
+                // per-relation filter type.
+                if (isPgGISSpatialFilter && pgGISSpatialRelation) {
+                    const rel = pgGISSpatialRelation;
+                    const targetTypeName = inflection.tableType(rel.targetResource.codec);
+                    const TargetFilterTypeName = inflection.filterType(targetTypeName);
+                    const TargetFilterType = build.getTypeByName(TargetFilterTypeName);
+                    if (!TargetFilterType)
+                        return fields;
+                    const paramFieldName = rel.paramFieldName;
+                    // Parametric: add required <param> field (Float!). The parent
+                    // relation field's apply reads the value from the input object
+                    // directly — this field's apply is a no-op used only so the schema
+                    // validates the input shape.
+                    if (rel.operator.parametric && paramFieldName) {
+                        fields = extend(fields, {
+                            [paramFieldName]: fieldWithHooks({
+                                fieldName: paramFieldName,
+                                isPgConnectionFilterField: true,
+                                isPgGISSpatialParamField: true,
+                            }, () => ({
+                                description: `Parametric argument for ${rel.operator.name} ` +
+                                    `(units: meters for geography, SRID units for geometry).`,
+                                type: new GraphQLNonNull(GraphQLFloat),
+                                apply: EXPORTABLE(() => function (_$where, _value) {
+                                    // No-op; parent apply already stashed the value.
+                                }, []),
+                            })),
+                        }, `PostgisSpatialRelationsPlugin adding '${paramFieldName}' param to ` +
+                            `${spatialFilterTypeName(build, rel)}`);
+                    }
+                    // Build the three apply() closures. `mode` selects the EXISTS
+                    // variant: `'some'` => EXISTS, `'none'` => NOT EXISTS,
+                    // `'every'` => NOT EXISTS (... AND NOT filter) via notPlan().
+                    const buildApply = (mode) => EXPORTABLE((buildJoin, buildExcl, relationInfo, sqlSchemaName, sqlLib, applyMode) => function ($where, value) {
+                        if (value == null)
+                            return;
+                        const foreignTable = relationInfo.targetResource;
+                        const foreignTableExpression = foreignTable.from;
+                        const existsOpts = {
+                            tableExpression: foreignTableExpression,
+                            alias: foreignTable.name,
+                        };
+                        if (applyMode !== 'some') {
+                            existsOpts.equals = false;
+                        }
+                        const $subQuery = $where.existsPlan(existsOpts);
+                        const outerAlias = $where.alias;
+                        const innerAlias = $subQuery.alias;
+                        let distance = null;
+                        if (relationInfo.operator.parametric) {
+                            const raw = $where._spatialRelationParam;
+                            if (raw == null || typeof raw !== 'number') {
+                                throw Object.assign(new Error(`Spatial relation '${relationInfo.relationName}' requires a ` +
+                                    `'${relationInfo.paramFieldName}' value; got ${raw}`), {});
+                            }
+                            distance = sqlLib.value(raw);
+                        }
+                        $subQuery.where(buildJoin(relationInfo, sqlSchemaName, outerAlias, innerAlias, distance));
+                        const exclusion = buildExcl(relationInfo, outerAlias, innerAlias);
+                        if (exclusion) {
+                            $subQuery.where(exclusion);
+                        }
+                        if (applyMode === 'every') {
+                            return $subQuery.notPlan();
+                        }
+                        return $subQuery;
+                    }, [
+                        buildSpatialJoinFragment,
+                        buildSelfExclusionFragment,
+                        rel,
+                        schemaName,
+                        sql,
+                        mode,
+                    ]);
+                    fields = extend(fields, {
+                        some: fieldWithHooks({
+                            fieldName: 'some',
+                            isPgConnectionFilterField: true,
+                        }, () => ({
+                            description: 'Filters to entities where at least one spatially-related entity matches.',
+                            type: TargetFilterType,
+                            apply: buildApply('some'),
+                        })),
+                        every: fieldWithHooks({
+                            fieldName: 'every',
+                            isPgConnectionFilterField: true,
+                        }, () => ({
+                            description: 'Filters to entities where every spatially-related entity matches.',
+                            type: TargetFilterType,
+                            apply: buildApply('every'),
+                        })),
+                        none: fieldWithHooks({
+                            fieldName: 'none',
+                            isPgConnectionFilterField: true,
+                        }, () => ({
+                            description: 'Filters to entities where no spatially-related entity matches.',
+                            type: TargetFilterType,
+                            apply: buildApply('none'),
+                        })),
+                    }, `PostgisSpatialRelationsPlugin adding some/every/none to ${spatialFilterTypeName(build, rel)}`);
+                }
+                return fields;
+            },
+        },
+    },
+};

package/esm/preset.js

@@ -6,6 +6,7 @@ import { PostgisGeometryFieldsPlugin } from './plugins/geometry-fields';
 import { PostgisMeasurementFieldsPlugin } from './plugins/measurement-fields';
 import { PostgisTransformationFieldsPlugin } from './plugins/transformation-functions';
 import { PostgisAggregatePlugin } from './plugins/aggregate-functions';
+import { PostgisSpatialRelationsPlugin } from './plugins/spatial-relations';
 import { createPostgisOperatorFactory } from './plugins/connection-filter-operators';
 import { createWithinDistanceOperatorFactory } from './plugins/within-distance-operator';
 /**
@@ -42,7 +43,8 @@ export const GraphilePostgisPreset = {
         PostgisGeometryFieldsPlugin,
         PostgisMeasurementFieldsPlugin,
         PostgisTransformationFieldsPlugin,
-        PostgisAggregatePlugin
+        PostgisAggregatePlugin,
+        PostgisSpatialRelationsPlugin,
     ],
     schema: {
         // connectionFilterOperatorFactories is augmented by graphile-connection-filter

package/index.d.ts

@@ -21,6 +21,8 @@ export { PostgisGeometryFieldsPlugin } from './plugins/geometry-fields';
 export { PostgisMeasurementFieldsPlugin } from './plugins/measurement-fields';
 export { PostgisTransformationFieldsPlugin } from './plugins/transformation-functions';
 export { PostgisAggregatePlugin } from './plugins/aggregate-functions';
+export { PostgisSpatialRelationsPlugin, OPERATOR_REGISTRY, parseSpatialRelationTag, collectSpatialRelations, } from './plugins/spatial-relations';
+export type { SpatialOperatorRegistration, SpatialRelationInfo, } from './plugins/spatial-relations';
 export { createPostgisOperatorFactory } from './plugins/connection-filter-operators';
 export { createWithinDistanceOperatorFactory } from './plugins/within-distance-operator';
 export { GisSubtype, SUBTYPE_STRING_BY_SUBTYPE, GIS_SUBTYPE_NAME, CONCRETE_SUBTYPES } from './constants';

package/index.js

@@ -14,7 +14,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getGISTypeName = exports.getGISTypeModifier = exports.getGISTypeDetails = exports.CONCRETE_SUBTYPES = exports.GIS_SUBTYPE_NAME = exports.SUBTYPE_STRING_BY_SUBTYPE = exports.GisSubtype = exports.createWithinDistanceOperatorFactory = exports.createPostgisOperatorFactory = exports.PostgisAggregatePlugin = exports.PostgisTransformationFieldsPlugin = exports.PostgisMeasurementFieldsPlugin = exports.PostgisGeometryFieldsPlugin = exports.PostgisRegisterTypesPlugin = exports.PostgisExtensionDetectionPlugin = exports.PostgisInflectionPlugin = exports.PostgisCodecPlugin = exports.GraphilePostgisPreset = void 0;
+exports.getGISTypeName = exports.getGISTypeModifier = exports.getGISTypeDetails = exports.CONCRETE_SUBTYPES = exports.GIS_SUBTYPE_NAME = exports.SUBTYPE_STRING_BY_SUBTYPE = exports.GisSubtype = exports.createWithinDistanceOperatorFactory = exports.createPostgisOperatorFactory = exports.collectSpatialRelations = exports.parseSpatialRelationTag = exports.OPERATOR_REGISTRY = exports.PostgisSpatialRelationsPlugin = exports.PostgisAggregatePlugin = exports.PostgisTransformationFieldsPlugin = exports.PostgisMeasurementFieldsPlugin = exports.PostgisGeometryFieldsPlugin = exports.PostgisRegisterTypesPlugin = exports.PostgisExtensionDetectionPlugin = exports.PostgisInflectionPlugin = exports.PostgisCodecPlugin = exports.GraphilePostgisPreset = void 0;
 // Preset (recommended entry point)
 var preset_1 = require("./preset");
 Object.defineProperty(exports, "GraphilePostgisPreset", { enumerable: true, get: function () { return preset_1.GraphilePostgisPreset; } });
@@ -35,6 +35,11 @@ var transformation_functions_1 = require("./plugins/transformation-functions");
 Object.defineProperty(exports, "PostgisTransformationFieldsPlugin", { enumerable: true, get: function () { return transformation_functions_1.PostgisTransformationFieldsPlugin; } });
 var aggregate_functions_1 = require("./plugins/aggregate-functions");
 Object.defineProperty(exports, "PostgisAggregatePlugin", { enumerable: true, get: function () { return aggregate_functions_1.PostgisAggregatePlugin; } });
+var spatial_relations_1 = require("./plugins/spatial-relations");
+Object.defineProperty(exports, "PostgisSpatialRelationsPlugin", { enumerable: true, get: function () { return spatial_relations_1.PostgisSpatialRelationsPlugin; } });
+Object.defineProperty(exports, "OPERATOR_REGISTRY", { enumerable: true, get: function () { return spatial_relations_1.OPERATOR_REGISTRY; } });
+Object.defineProperty(exports, "parseSpatialRelationTag", { enumerable: true, get: function () { return spatial_relations_1.parseSpatialRelationTag; } });
+Object.defineProperty(exports, "collectSpatialRelations", { enumerable: true, get: function () { return spatial_relations_1.collectSpatialRelations; } });
 // Connection filter operator factories (spatial operators for graphile-connection-filter)
 var connection_filter_operators_1 = require("./plugins/connection-filter-operators");
 Object.defineProperty(exports, "createPostgisOperatorFactory", { enumerable: true, get: function () { return connection_filter_operators_1.createPostgisOperatorFactory; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-postgis",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "PostGIS support for PostGraphile v5",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -46,7 +46,7 @@
     "graphile-build": "5.0.0",
     "graphile-build-pg": "5.0.0",
     "graphile-config": "1.0.0",
-    "graphile-connection-filter": "^1.4.0",
+    "graphile-connection-filter": "^1.5.0",
     "graphql": "16.13.0",
     "pg-sql2": "5.0.0",
     "postgraphile": "5.0.0"
@@ -59,9 +59,9 @@
   "devDependencies": {
     "@types/geojson": "^7946.0.14",
     "@types/node": "^22.19.11",
-    "graphile-test": "^4.8.0",
+    "graphile-test": "^4.9.0",
     "makage": "^0.3.0",
-    "pgsql-test": "^4.8.0"
+    "pgsql-test": "^4.9.0"
   },
-  "gitHead": "3bf7c522cf9f9d2595750ac7cea81d470b3e6c30"
+  "gitHead": "1b3af3c5189b9ca2e765b9239a4b287099e64a03"
 }