graphile-postgis 2.10.0 → 2.11.0

package/plugins/connection-filter-operators.js

@@ -213,6 +213,8 @@ function createPostgisOperatorFactory() {
         }
         const { inflection } = build;
         const { schemaName, geometryCodec, geographyCodec } = postgisInfo;
+        const sqlGeomFromGeoJSON = pg_sql2_1.default.identifier(schemaName, 'st_geomfromgeojson');
+        const sqlGeographyType = pg_sql2_1.default.identifier(schemaName, 'geography');
         // Collect all GQL type names for geometry and geography
         const gqlTypeNamesByBase = {
             geometry: [],
@@ -245,6 +247,7 @@ function createPostgisOperatorFactory() {
                     typeNames: gqlTypeNamesByBase[baseType],
                     operatorName,
                     description,
+                    baseType: baseType,
                     resolve: (i, v) => pg_sql2_1.default.fragment `${sqlGisFunction}(${i}, ${v})`
                 });
             }
@@ -258,6 +261,7 @@ function createPostgisOperatorFactory() {
                     typeNames: gqlTypeNamesByBase[baseType],
                     operatorName,
                     description,
+                    baseType: baseType,
                     resolve: (i, v) => buildOperatorExpr(capturedOp, i, v)
                 });
             }
@@ -267,8 +271,21 @@ function createPostgisOperatorFactory() {
         // Convert to ConnectionFilterOperatorRegistration format.
         // Each InternalSpec may target multiple type names; we expand each
         // into individual registrations keyed by typeName.
+        //
+        // The default operatorApply pipeline binds the filter value as a raw
+        // text parameter cast to the column codec's sqlType (geometry /
+        // geography). PostgreSQL's geometry_in / geography_in parsers reject
+        // GeoJSON text, so we must wrap the input with ST_GeomFromGeoJSON
+        // ourselves — see within-distance-operator.ts for the pattern.
+        //
+        // We disable the default bind via `resolveSqlValue: () => sql.null`
+        // and construct the geometry value from `input` inside resolve(),
+        // mirroring the ST_DWithin implementation.
         const registrations = [];
         for (const spec of allSpecs) {
+            const geographyCast = spec.baseType === 'geography'
+                ? pg_sql2_1.default.fragment `::${sqlGeographyType}`
+                : pg_sql2_1.default.fragment ``;
             for (const typeName of spec.typeNames) {
                 registrations.push({
                     typeNames: typeName,
@@ -276,8 +293,11 @@ function createPostgisOperatorFactory() {
                     spec: {
                         description: spec.description,
                         resolveType: (fieldType) => fieldType,
-                        resolve(sqlIdentifier, sqlValue, _input, _$where, _details) {
-                            return spec.resolve(sqlIdentifier, sqlValue);
+                        resolveSqlValue: () => pg_sql2_1.default.null,
+                        resolve(sqlIdentifier, _sqlValue, input, _$where, _details) {
+                            const geoJsonStr = pg_sql2_1.default.value(JSON.stringify(input));
+                            const geomSql = pg_sql2_1.default.fragment `${sqlGeomFromGeoJSON}(${geoJsonStr}::text)${geographyCast}`;
+                            return spec.resolve(sqlIdentifier, geomSql);
                         }
                     },
                 });

package/plugins/spatial-relations.d.ts

@@ -0,0 +1,130 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import 'graphile-connection-filter';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * PostgisSpatialRelationsPlugin
+ *
+ * Adds cross-table spatial filtering to `graphile-connection-filter` by
+ * reading a `@spatialRelation` smart tag on geometry/geography columns and
+ * synthesising a virtual relation + filter field that emits an EXISTS
+ * subquery joined by a PostGIS predicate (e.g. `ST_Contains`, `ST_DWithin`).
+ *
+ * The regular `ConnectionFilterBackwardRelationsPlugin` is FK-driven — it
+ * joins on column equality. Spatial relationships are not backed by FKs, so
+ * this plugin hooks the same `pgCodec`-scoped filter input types and injects
+ * its own fields whose `apply()` emits `ST_<op>(...)` instead of `a = b`.
+ *
+ * Tag grammar:
+ *
+ * ```sql
+ * COMMENT ON COLUMN <owner_table>.<owner_col> IS
+ *   E'@spatialRelation <relation_name> <target_ref> <operator> [<param_name>]';
+ * ```
+ *
+ * - `target_ref` — `schema.table.col` or `table.col` (same schema as owner).
+ * - `operator` — one of the PG-native snake_case ops in OPERATOR_REGISTRY.
+ * - `param_name` — required iff the operator is parametric (currently
+ *   only `st_dwithin`, which needs a distance).
+ *
+ * Examples:
+ *
+ * ```sql
+ * -- Point in polygon
+ * COMMENT ON COLUMN telemedicine_clinics.location IS
+ *   E'@spatialRelation county counties.geom st_contains';
+ *
+ * -- Self-referential radius search
+ * COMMENT ON COLUMN telemedicine_clinics.location IS
+ *   E'@spatialRelation nearbyClinic telemedicine_clinics.location st_dwithin distance';
+ * ```
+ *
+ * Generated GraphQL (for the `st_dwithin` case):
+ *
+ * ```graphql
+ * telemedicineClinics(where: {
+ *   nearbyClinic: {
+ *     distance: 5000,
+ *     some: { specialty: { eq: "pediatrics" } }
+ *   }
+ * })
+ * ```
+ *
+ * The generated SQL uses the same EXISTS pattern as backward relations but
+ * substitutes `ST_<op>(...)` for column equality:
+ *
+ * ```sql
+ * WHERE EXISTS (
+ *   SELECT 1 FROM <target_table> other
+ *   WHERE ST_<op>(other.<target_col>, self.<owner_col>[, distance])
+ *     AND other.<pk> <> self.<pk>  -- self-relations only
+ *     AND <nested filter conditions>
+ * )
+ * ```
+ */
+export interface SpatialOperatorRegistration {
+    /** Tag-facing op name (PG-native snake_case). */
+    name: string;
+    /** Kind of PG-level operator. */
+    kind: 'function' | 'infix';
+    /**
+     * For `kind: 'function'`, the PG function name (snake_case) resolved
+     * against the PostGIS schema at SQL-emit time. For `kind: 'infix'`,
+     * the PG binary operator token (e.g. `&&`).
+     */
+    pgToken: string;
+    /** Whether this op takes an extra numeric parameter (e.g. `st_dwithin`). */
+    parametric: boolean;
+    description: string;
+}
+export declare const OPERATOR_REGISTRY: Record<string, SpatialOperatorRegistration>;
+export interface SpatialRelationInfo {
+    /** GraphQL-facing relation name, derived from the tag. */
+    relationName: string;
+    /** The codec that owns the tag (outer side of the EXISTS). */
+    ownerCodec: any;
+    /** The owning attribute name (column). */
+    ownerAttributeName: string;
+    /** Qualified target resource (inner side of the EXISTS). */
+    targetResource: any;
+    /** Column name on the target resource. */
+    targetAttributeName: string;
+    /** Resolved operator. */
+    operator: SpatialOperatorRegistration;
+    /** Field name for the parametric argument, if any. */
+    paramFieldName: string | null;
+    /** Whether owner === target (self-relation needs row exclusion). */
+    isSelfRelation: boolean;
+    /**
+     * Cached primary-key attribute names for the owner+target codecs. Used
+     * to synthesise the self-exclusion predicate (`other.<pk> <> self.<pk>`).
+     * `null` if the codec has no discoverable PK.
+     */
+    ownerPkAttributes: string[] | null;
+    targetPkAttributes: string[] | null;
+}
+interface TagParseResult {
+    ok: true;
+    relationName: string;
+    targetRef: string;
+    operator: string;
+    paramName: string | null;
+}
+interface TagParseError {
+    ok: false;
+    error: string;
+}
+/**
+ * Parse a single `@spatialRelation` tag value.
+ *
+ * Accepts a string of the form `<name> <target> <op> [<param>]`.
+ */
+export declare function parseSpatialRelationTag(raw: string): TagParseResult | TagParseError;
+/**
+ * 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 declare function collectSpatialRelations(build: any): SpatialRelationInfo[];
+export declare const PostgisSpatialRelationsPlugin: GraphileConfig.Plugin;
+export {};