graphile-plugin-connection-filter-postgis 2.1.1 → 2.2.1

package/README.md

@@ -1,100 +1,66 @@
 # graphile-plugin-connection-filter-postgis
 
-<p align="center" width="100%">
-  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
-</p>
-
-<p align="center" width="100%">
-  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
-    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
-  </a>
-  <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE">
-    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
-  </a>
-  <a href="https://www.npmjs.com/package/graphile-plugin-connection-filter-postgis">
-    <img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphile%2Fgraphile-plugin-connection-filter-postgis%2Fpackage.json"/>
-  </a>
-</p>
-
-**`graphile-plugin-connection-filter-postgis`** exposes PostGIS-aware operators on the `filter` argument for PostGraphile connections.
-
-## 🚀 Installation
+PostGIS spatial filter operators for `postgraphile-plugin-connection-filter` (PostGraphile v5).
+
+## Installation
 
 ```bash
 npm install graphile-plugin-connection-filter-postgis
 ```
 
-## ✨ Features
-
-- Adds PostGIS functions and operators to `graphile-plugin-connection-filter`
-- Supports both `geometry` and `geography` columns
-- Works with PostGraphile v4 filter inputs
-
-## 📦 Usage
+## Usage
 
-Requires `postgraphile@^4.5.0` and the following plugins appended prior to this plugin:
+```typescript
+import { GraphilePostgisPreset } from 'graphile-postgis';
+import { PostGraphileConnectionFilterPreset } from 'postgraphile-plugin-connection-filter';
+import { PostgisConnectionFilterPreset } from 'graphile-plugin-connection-filter-postgis';
 
-- `graphile-postgis@^0.1.3`
-- `graphile-plugin-connection-filter@^2.0.0`
-
-```ts
-import PostGISFilterPlugin from 'graphile-plugin-connection-filter-postgis';
-import PostGISPlugin from 'graphile-postgis';
-import ConnectionFilterPlugin from 'graphile-plugin-connection-filter';
-
-app.use(
-  postgraphile(pgConfig, schemas, {
-    appendPlugins: [
-      PostGISPlugin,
-      ConnectionFilterPlugin,
-      PostGISFilterPlugin
-    ]
-  })
-);
+const preset = {
+  extends: [
+    GraphilePostgisPreset,
+    PostGraphileConnectionFilterPreset,
+    PostgisConnectionFilterPreset
+  ]
+};
 ```
 
-## 🔎 Operators
-
-| PostGIS function | Types | GraphQL field name |
-| --- | --- | --- |
-| ST_3DIntersects | geometry | intersects3D |
-| ST_Contains | geometry | contains |
-| ST_ContainsProperly | geometry | containsProperly |
-| ST_CoveredBy | geometry, geography | coveredBy |
-| ST_Covers | geometry, geography | covers |
-| ST_Crosses | geometry | crosses |
-| ST_Disjoint | geometry | disjoint |
-| ST_Equals | geometry | equals |
-| ST_Intersects | geometry, geography | intersects |
-| ST_OrderingEquals | geometry | orderingEquals |
-| ST_Overlaps | geometry | overlaps |
-| ST_Touches | geometry | touches |
-| ST_Within | geometry | within |
-
-| PostGIS operator | Types | GraphQL field name |
-| --- | --- | --- |
-| = | geometry, geography | exactlyEquals |
-| && | geometry, geography | bboxIntersects2D |
-| &&& | geometry | bboxIntersectsND |
-| &< | geometry | bboxOverlapsOrLeftOf |
-| &<\| | geometry | bboxOverlapsOrBelow |
-| &> | geometry | bboxOverlapsOrRightOf |
-| \|&> | geometry | bboxOverlapsOrAbove |
-| << | geometry | bboxLeftOf |
-| <<\| | geometry | bboxBelow |
-| >> | geometry | bboxRightOf |
-| \|>> | geometry | bboxAbove |
-| ~ | geometry | bboxContains |
-| ~= | geometry | bboxEquals |
-
-## 🧑‍💻 Development
-
-## 🧪 Testing
-
-```sh
-# requires a local Postgres with PostGIS available (defaults to postgres/password@localhost:5432)
-pnpm --filter graphile-plugin-connection-filter-postgis test
-```
+## Operators
+
+### Function-based operators (geometry)
+
+- `contains` — ST_Contains
+- `containsProperly` — ST_ContainsProperly
+- `crosses` — ST_Crosses
+- `disjoint` — ST_Disjoint
+- `equals` — ST_Equals
+- `intersects` — ST_Intersects
+- `intersects3D` — ST_3DIntersects
+- `orderingEquals` — ST_OrderingEquals
+- `overlaps` — ST_Overlaps
+- `touches` — ST_Touches
+- `within` — ST_Within
+
+### Function-based operators (geometry + geography)
+
+- `coveredBy` — ST_CoveredBy
+- `covers` — ST_Covers
+- `intersects` — ST_Intersects
+
+### Bounding box operators
+
+- `bboxIntersects2D` — `&&`
+- `bboxIntersectsND` — `&&&`
+- `bboxOverlapsOrLeftOf` — `&<`
+- `bboxOverlapsOrBelow` — `&<|`
+- `bboxOverlapsOrRightOf` — `&>`
+- `bboxOverlapsOrAbove` — `|&>`
+- `bboxLeftOf` — `<<`
+- `bboxBelow` — `<<|`
+- `bboxRightOf` — `>>`
+- `bboxAbove` — `|>>`
+- `bboxContains` — `~`
+- `bboxEquals` — `~=`
+- `exactlyEquals` — `=`
 
 ---
 

package/esm/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * PostGIS Connection Filter Plugin for PostGraphile v5
+ *
+ * Adds PostGIS spatial filter operators (ST_Contains, ST_Intersects, etc.)
+ * to postgraphile-plugin-connection-filter.
+ *
+ * @example
+ * ```typescript
+ * import { PostgisConnectionFilterPreset } from 'graphile-plugin-connection-filter-postgis';
+ *
+ * const preset = {
+ *   extends: [PostgisConnectionFilterPreset]
+ * };
+ * ```
+ */
+export { PostgisConnectionFilterPreset } from './preset';
+export { PgConnectionArgFilterPostgisOperatorsPlugin } from './plugin';
+export type { PostgisFilterOperatorSpec, ResolvedFilterSpec } from './types';

package/esm/index.js

@@ -1,24 +1,19 @@
-import { findAndRequirePackageJson } from 'find-and-require-package-json';
-import PostgisOperatorsPlugin from "./PgConnectionArgFilterPostgisOperatorsPlugin";
-const pkg = findAndRequirePackageJson(__dirname);
-const PostGraphileConnectionFilterPostgisPlugin = (builder, options) => {
-    builder.hook("build", (build) => {
-        if (!build.versions) {
-            throw new Error(`Plugin ${pkg.name}@${pkg.version} requires graphile-build@^4.1.0 in order to check dependencies (current version: ${build.graphileBuildVersion})`);
-        }
-        const depends = (name, range) => {
-            if (!build.hasVersion(name, range)) {
-                throw new Error(`Plugin ${pkg.name}@${pkg.version} requires ${name}@${range} (${build.versions[name]
-                    ? `current version: ${build.versions[name]}`
-                    : "not found"})`);
-            }
-        };
-        depends("graphile-build-pg", "^4.5.0");
-        depends("graphile-plugin-connection-filter", "^3.0.0");
-        build.versions = build.extend(build.versions, { [pkg.name]: pkg.version });
-        return build;
-    });
-    PostgisOperatorsPlugin(builder, options);
-};
-export { PostGraphileConnectionFilterPostgisPlugin };
-export default PostGraphileConnectionFilterPostgisPlugin;
+/**
+ * PostGIS Connection Filter Plugin for PostGraphile v5
+ *
+ * Adds PostGIS spatial filter operators (ST_Contains, ST_Intersects, etc.)
+ * to postgraphile-plugin-connection-filter.
+ *
+ * @example
+ * ```typescript
+ * import { PostgisConnectionFilterPreset } from 'graphile-plugin-connection-filter-postgis';
+ *
+ * const preset = {
+ *   extends: [PostgisConnectionFilterPreset]
+ * };
+ * ```
+ */
+// Preset (recommended entry point)
+export { PostgisConnectionFilterPreset } from './preset';
+// Plugin
+export { PgConnectionArgFilterPostgisOperatorsPlugin } from './plugin';

package/esm/plugin.d.ts

@@ -0,0 +1,14 @@
+import 'graphile-build';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * PgConnectionArgFilterPostgisOperatorsPlugin
+ *
+ * Adds PostGIS spatial filter operators to postgraphile-plugin-connection-filter.
+ *
+ * Includes:
+ * - ST_ function-based operators (contains, intersects, within, etc.)
+ * - SQL operator-based operators (&&, =, ~, etc. for bounding box ops)
+ *
+ * Requires graphile-postgis and postgraphile-plugin-connection-filter to be loaded.
+ */
+export declare const PgConnectionArgFilterPostgisOperatorsPlugin: GraphileConfig.Plugin;

package/esm/plugin.js

@@ -0,0 +1,280 @@
+import 'graphile-build';
+import sql from 'pg-sql2';
+import { CONCRETE_SUBTYPES } from 'graphile-postgis';
+const ALLOWED_SQL_OPERATORS = new Set([
+    '=',
+    '&&',
+    '&&&',
+    '&<',
+    '&<|',
+    '&>',
+    '|&>',
+    '<<',
+    '<<|',
+    '>>',
+    '|>>',
+    '~',
+    '~=',
+]);
+/**
+ * PgConnectionArgFilterPostgisOperatorsPlugin
+ *
+ * Adds PostGIS spatial filter operators to postgraphile-plugin-connection-filter.
+ *
+ * Includes:
+ * - ST_ function-based operators (contains, intersects, within, etc.)
+ * - SQL operator-based operators (&&, =, ~, etc. for bounding box ops)
+ *
+ * Requires graphile-postgis and postgraphile-plugin-connection-filter to be loaded.
+ */
+export const PgConnectionArgFilterPostgisOperatorsPlugin = {
+    name: 'PgConnectionArgFilterPostgisOperatorsPlugin',
+    version: '2.0.0',
+    description: 'Adds PostGIS spatial filter operators to connection filter',
+    after: [
+        'PostgisRegisterTypesPlugin',
+        'PostgisExtensionDetectionPlugin',
+        'PostgisInflectionPlugin',
+        'PgConnectionArgFilterPlugin'
+    ],
+    schema: {
+        hooks: {
+            init(_, build) {
+                const postgisInfo = build.pgGISExtensionInfo;
+                if (!postgisInfo) {
+                    return _;
+                }
+                const addConnectionFilterOperator = build.addConnectionFilterOperator;
+                if (typeof addConnectionFilterOperator !== 'function') {
+                    return _;
+                }
+                const { inflection } = build;
+                const { schemaName, geometryCodec, geographyCodec } = postgisInfo;
+                // Collect all GQL type names for geometry and geography
+                const gqlTypeNamesByBase = {
+                    geometry: [],
+                    geography: []
+                };
+                const codecPairs = [['geometry', geometryCodec]];
+                if (geographyCodec) {
+                    codecPairs.push(['geography', geographyCodec]);
+                }
+                for (const [baseKey, codec] of codecPairs) {
+                    const typeName = codec.name;
+                    gqlTypeNamesByBase[baseKey].push(inflection.gisInterfaceName(typeName));
+                    for (const subtype of CONCRETE_SUBTYPES) {
+                        for (const hasZ of [false, true]) {
+                            for (const hasM of [false, true]) {
+                                gqlTypeNamesByBase[baseKey].push(inflection.gisType(typeName, subtype, hasZ, hasM, 0));
+                            }
+                        }
+                    }
+                }
+                // PostGIS function-based operators
+                const functionSpecs = [
+                    [
+                        'ST_3DIntersects',
+                        ['geometry'],
+                        'intersects3D',
+                        'They share any portion of space in 3D.'
+                    ],
+                    [
+                        'ST_Contains',
+                        ['geometry'],
+                        'contains',
+                        'No points of the specified geometry lie in the exterior, and at least one point of the interior of the specified geometry lies in the interior.'
+                    ],
+                    [
+                        'ST_ContainsProperly',
+                        ['geometry'],
+                        'containsProperly',
+                        'The specified geometry intersects the interior but not the boundary (or exterior).'
+                    ],
+                    [
+                        'ST_CoveredBy',
+                        ['geometry', 'geography'],
+                        'coveredBy',
+                        'No point is outside the specified geometry.'
+                    ],
+                    [
+                        'ST_Covers',
+                        ['geometry', 'geography'],
+                        'covers',
+                        'No point in the specified geometry is outside.'
+                    ],
+                    [
+                        'ST_Crosses',
+                        ['geometry'],
+                        'crosses',
+                        'They have some, but not all, interior points in common.'
+                    ],
+                    [
+                        'ST_Disjoint',
+                        ['geometry'],
+                        'disjoint',
+                        'They do not share any space together.'
+                    ],
+                    [
+                        'ST_Equals',
+                        ['geometry'],
+                        'equals',
+                        'They represent the same geometry. Directionality is ignored.'
+                    ],
+                    [
+                        'ST_Intersects',
+                        ['geometry', 'geography'],
+                        'intersects',
+                        'They share any portion of space in 2D.'
+                    ],
+                    [
+                        'ST_OrderingEquals',
+                        ['geometry'],
+                        'orderingEquals',
+                        'They represent the same geometry and points are in the same directional order.'
+                    ],
+                    [
+                        'ST_Overlaps',
+                        ['geometry'],
+                        'overlaps',
+                        'They share space, are of the same dimension, but are not completely contained by each other.'
+                    ],
+                    [
+                        'ST_Touches',
+                        ['geometry'],
+                        'touches',
+                        'They have at least one point in common, but their interiors do not intersect.'
+                    ],
+                    [
+                        'ST_Within',
+                        ['geometry'],
+                        'within',
+                        'Completely inside the specified geometry.'
+                    ]
+                ];
+                // SQL operator-based operators
+                const operatorSpecs = [
+                    [
+                        '=',
+                        ['geometry', 'geography'],
+                        'exactlyEquals',
+                        'Coordinates and coordinate order are the same as specified geometry.'
+                    ],
+                    [
+                        '&&',
+                        ['geometry', 'geography'],
+                        'bboxIntersects2D',
+                        "2D bounding box intersects the specified geometry's 2D bounding box."
+                    ],
+                    [
+                        '&&&',
+                        ['geometry'],
+                        'bboxIntersectsND',
+                        "n-D bounding box intersects the specified geometry's n-D bounding box."
+                    ],
+                    [
+                        '&<',
+                        ['geometry'],
+                        'bboxOverlapsOrLeftOf',
+                        "Bounding box overlaps or is to the left of the specified geometry's bounding box."
+                    ],
+                    [
+                        '&<|',
+                        ['geometry'],
+                        'bboxOverlapsOrBelow',
+                        "Bounding box overlaps or is below the specified geometry's bounding box."
+                    ],
+                    [
+                        '&>',
+                        ['geometry'],
+                        'bboxOverlapsOrRightOf',
+                        "Bounding box overlaps or is to the right of the specified geometry's bounding box."
+                    ],
+                    [
+                        '|&>',
+                        ['geometry'],
+                        'bboxOverlapsOrAbove',
+                        "Bounding box overlaps or is above the specified geometry's bounding box."
+                    ],
+                    [
+                        '<<',
+                        ['geometry'],
+                        'bboxLeftOf',
+                        "Bounding box is strictly to the left of the specified geometry's bounding box."
+                    ],
+                    [
+                        '<<|',
+                        ['geometry'],
+                        'bboxBelow',
+                        "Bounding box is strictly below the specified geometry's bounding box."
+                    ],
+                    [
+                        '>>',
+                        ['geometry'],
+                        'bboxRightOf',
+                        "Bounding box is strictly to the right of the specified geometry's bounding box."
+                    ],
+                    [
+                        '|>>',
+                        ['geometry'],
+                        'bboxAbove',
+                        "Bounding box is strictly above the specified geometry's bounding box."
+                    ],
+                    [
+                        '~',
+                        ['geometry'],
+                        'bboxContains',
+                        "Bounding box contains the specified geometry's bounding box."
+                    ],
+                    [
+                        '~=',
+                        ['geometry'],
+                        'bboxEquals',
+                        "Bounding box is the same as the specified geometry's bounding box."
+                    ]
+                ];
+                const allSpecs = [];
+                // Process function-based operators
+                for (const [fn, baseTypes, operatorName, description] of functionSpecs) {
+                    for (const baseType of baseTypes) {
+                        const sqlGisFunction = sql.identifier(schemaName, fn.toLowerCase());
+                        allSpecs.push({
+                            typeNames: gqlTypeNamesByBase[baseType],
+                            operatorName,
+                            description,
+                            resolve: (i, v) => sql.fragment `${sqlGisFunction}(${i}, ${v})`
+                        });
+                    }
+                }
+                // Process SQL operator-based operators
+                for (const [op, baseTypes, operatorName, description] of operatorSpecs) {
+                    if (!ALLOWED_SQL_OPERATORS.has(op)) {
+                        throw new Error(`Unexpected SQL operator: ${op}`);
+                    }
+                    for (const baseType of baseTypes) {
+                        allSpecs.push({
+                            typeNames: gqlTypeNamesByBase[baseType],
+                            operatorName,
+                            description,
+                            resolve: (i, v) => sql.fragment `${i} ${sql.raw(op)} ${v}`
+                        });
+                    }
+                }
+                // Sort by operator name for deterministic schema output
+                allSpecs.sort((a, b) => a.operatorName.localeCompare(b.operatorName));
+                // Register each operator with the connection filter plugin
+                for (const spec of allSpecs) {
+                    for (const typeName of spec.typeNames) {
+                        addConnectionFilterOperator(typeName, spec.operatorName, {
+                            description: spec.description,
+                            resolveType: (fieldType) => fieldType,
+                            resolve(sqlIdentifier, sqlValue, _input, _$where, _details) {
+                                return spec.resolve(sqlIdentifier, sqlValue);
+                            }
+                        });
+                    }
+                }
+                return _;
+            }
+        }
+    }
+};

package/esm/preset.d.ts

@@ -0,0 +1,23 @@
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * PostGIS Connection Filter Preset
+ *
+ * Adds PostGIS spatial filter operators to postgraphile-plugin-connection-filter.
+ * Requires graphile-postgis and postgraphile-plugin-connection-filter to be loaded.
+ *
+ * @example
+ * ```typescript
+ * import { GraphilePostgisPreset } from 'graphile-postgis';
+ * import { PostGraphileConnectionFilterPreset } from 'postgraphile-plugin-connection-filter';
+ * import { PostgisConnectionFilterPreset } from 'graphile-plugin-connection-filter-postgis';
+ *
+ * const preset = {
+ *   extends: [
+ *     GraphilePostgisPreset,
+ *     PostGraphileConnectionFilterPreset,
+ *     PostgisConnectionFilterPreset
+ *   ]
+ * };
+ * ```
+ */
+export declare const PostgisConnectionFilterPreset: GraphileConfig.Preset;

package/esm/preset.js

@@ -0,0 +1,25 @@
+import { PgConnectionArgFilterPostgisOperatorsPlugin } from './plugin';
+/**
+ * PostGIS Connection Filter Preset
+ *
+ * Adds PostGIS spatial filter operators to postgraphile-plugin-connection-filter.
+ * Requires graphile-postgis and postgraphile-plugin-connection-filter to be loaded.
+ *
+ * @example
+ * ```typescript
+ * import { GraphilePostgisPreset } from 'graphile-postgis';
+ * import { PostGraphileConnectionFilterPreset } from 'postgraphile-plugin-connection-filter';
+ * import { PostgisConnectionFilterPreset } from 'graphile-plugin-connection-filter-postgis';
+ *
+ * const preset = {
+ *   extends: [
+ *     GraphilePostgisPreset,
+ *     PostGraphileConnectionFilterPreset,
+ *     PostgisConnectionFilterPreset
+ *   ]
+ * };
+ * ```
+ */
+export const PostgisConnectionFilterPreset = {
+    plugins: [PgConnectionArgFilterPostgisOperatorsPlugin]
+};

package/esm/types.d.ts

@@ -0,0 +1,23 @@
+import type { SQL } from 'pg-sql2';
+export interface PostgisFilterOperatorSpec {
+    /** PostGIS SQL function name (e.g. 'ST_Contains') */
+    sqlFunction?: string;
+    /** SQL operator (e.g. '&&', '=') — used instead of sqlFunction for operator-based specs */
+    sqlOperator?: string;
+    /** GraphQL filter operator name (e.g. 'contains', 'bboxIntersects2D') */
+    operatorName: string;
+    /** Human-readable description of the operator */
+    description: string;
+    /** Which base types this operator applies to: 'geometry', 'geography', or both */
+    baseTypes: ('geometry' | 'geography')[];
+}
+export interface ResolvedFilterSpec {
+    /** GraphQL type names this operator applies to (interface + all concrete types) */
+    typeNames: string[];
+    /** GraphQL filter operator name */
+    operatorName: string;
+    /** Description */
+    description: string;
+    /** SQL resolve function: (identifier, value) => SQL expression */
+    resolve: (i: SQL, v: SQL) => SQL;
+}

package/esm/types.js

@@ -0,0 +1 @@
+export {};

package/index.d.ts

@@ -1,4 +1,18 @@
-import type { Plugin } from "graphile-build";
-declare const PostGraphileConnectionFilterPostgisPlugin: Plugin;
-export { PostGraphileConnectionFilterPostgisPlugin };
-export default PostGraphileConnectionFilterPostgisPlugin;
+/**
+ * PostGIS Connection Filter Plugin for PostGraphile v5
+ *
+ * Adds PostGIS spatial filter operators (ST_Contains, ST_Intersects, etc.)
+ * to postgraphile-plugin-connection-filter.
+ *
+ * @example
+ * ```typescript
+ * import { PostgisConnectionFilterPreset } from 'graphile-plugin-connection-filter-postgis';
+ *
+ * const preset = {
+ *   extends: [PostgisConnectionFilterPreset]
+ * };
+ * ```
+ */
+export { PostgisConnectionFilterPreset } from './preset';
+export { PgConnectionArgFilterPostgisOperatorsPlugin } from './plugin';
+export type { PostgisFilterOperatorSpec, ResolvedFilterSpec } from './types';