graphile-postgis 1.1.1 → 2.2.0

package/README.md

@@ -1,61 +1,38 @@
 # graphile-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-postgis">
-    <img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphile%2Fgraphile-postgis%2Fpackage.json"/>
-  </a>
-</p>
-
-**`graphile-postgis`** registers GeoJSON scalars, PostGIS geometry/geography GraphQL types, and convenience fields for common spatial columns in PostGraphile/Graphile schemas.
-
-## 🚀 Installation
-
-```sh
-pnpm add graphile-postgis
-```
-
-## ✨ Features
+PostGIS support for PostGraphile v5.
 
-- Registers GeoJSON scalars and PostGIS `geometry` / `geography` GraphQL types
-- Convenience fields for common spatial column types
-- Works with PostGraphile CLI or library usage
+Automatically generates GraphQL types for PostGIS geometry and geography columns, including GeoJSON scalar types, dimension-aware interfaces, and subtype-specific fields (coordinates, points, rings, etc.).
 
-## 📦 Usage
+## Installation
 
-### CLI
-
-```sh
-postgraphile --append-plugins graphile-postgis
+```bash
+npm install graphile-postgis
 ```
 
-Make sure your database has the `postgis` extension enabled so the plugin can expose the spatial types.
-
-### Library
+## Usage
 
-```ts
-import PostgisPlugin from 'graphile-postgis';
+```typescript
+import { GraphilePostgisPreset } from 'graphile-postgis';
 
-const options = {
-  appendPlugins: [PostgisPlugin]
+const preset = {
+  extends: [GraphilePostgisPreset]
 };
 ```
 
-## 🧪 Testing
+## Features
 
-```sh
-# requires a local Postgres with PostGIS available (defaults to postgres/password@localhost:5432)
-pnpm --filter graphile-postgis test
-```
+- GeoJSON scalar type for input/output
+- GraphQL interfaces for geometry and geography base types
+- Dimension-aware interfaces (XY, XYZ, XYM, XYZM)
+- Concrete types for all geometry subtypes: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection
+- Subtype-specific fields (x/y/z for Points, points for LineStrings, exterior/interiors for Polygons, etc.)
+- Geography-aware field naming (longitude/latitude/height instead of x/y/z)
+- Graceful degradation when PostGIS is not installed
+
+## License
+
+MIT
 
 ---
 

package/constants.d.ts

@@ -10,3 +10,4 @@ export declare enum GisSubtype {
 }
 export declare const SUBTYPE_STRING_BY_SUBTYPE: Record<GisSubtype, string>;
 export declare const GIS_SUBTYPE_NAME: Record<GisSubtype, string>;
+export declare const CONCRETE_SUBTYPES: GisSubtype[];

package/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GIS_SUBTYPE_NAME = exports.SUBTYPE_STRING_BY_SUBTYPE = exports.GisSubtype = void 0;
+exports.CONCRETE_SUBTYPES = exports.GIS_SUBTYPE_NAME = exports.SUBTYPE_STRING_BY_SUBTYPE = exports.GisSubtype = void 0;
 var GisSubtype;
 (function (GisSubtype) {
     GisSubtype[GisSubtype["Geometry"] = 0] = "Geometry";
@@ -32,3 +32,12 @@ exports.GIS_SUBTYPE_NAME = {
     [GisSubtype.MultiPolygon]: 'MultiPolygon',
     [GisSubtype.GeometryCollection]: 'GeometryCollection'
 };
+exports.CONCRETE_SUBTYPES = [
+    GisSubtype.Point,
+    GisSubtype.LineString,
+    GisSubtype.Polygon,
+    GisSubtype.MultiPoint,
+    GisSubtype.MultiLineString,
+    GisSubtype.MultiPolygon,
+    GisSubtype.GeometryCollection
+];

package/esm/constants.d.ts

@@ -0,0 +1,13 @@
+export declare enum GisSubtype {
+    Geometry = 0,
+    Point = 1,
+    LineString = 2,
+    Polygon = 3,
+    MultiPoint = 4,
+    MultiLineString = 5,
+    MultiPolygon = 6,
+    GeometryCollection = 7
+}
+export declare const SUBTYPE_STRING_BY_SUBTYPE: Record<GisSubtype, string>;
+export declare const GIS_SUBTYPE_NAME: Record<GisSubtype, string>;
+export declare const CONCRETE_SUBTYPES: GisSubtype[];

package/esm/constants.js

@@ -29,3 +29,12 @@ export const GIS_SUBTYPE_NAME = {
     [GisSubtype.MultiPolygon]: 'MultiPolygon',
     [GisSubtype.GeometryCollection]: 'GeometryCollection'
 };
+export const CONCRETE_SUBTYPES = [
+    GisSubtype.Point,
+    GisSubtype.LineString,
+    GisSubtype.Polygon,
+    GisSubtype.MultiPoint,
+    GisSubtype.MultiLineString,
+    GisSubtype.MultiPolygon,
+    GisSubtype.GeometryCollection
+];

package/esm/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * PostGraphile v5 PostGIS Plugin
+ *
+ * Provides PostGIS geometry/geography type support for PostGraphile v5.
+ *
+ * @example
+ * ```typescript
+ * import { GraphilePostgisPreset } from 'graphile-postgis';
+ *
+ * const preset = {
+ *   extends: [GraphilePostgisPreset]
+ * };
+ * ```
+ */
+export { GraphilePostgisPreset } from './preset';
+export { PostgisCodecPlugin } from './plugins/codec';
+export { PostgisInflectionPlugin } from './plugins/inflection';
+export { PostgisExtensionDetectionPlugin } from './plugins/detect-extension';
+export { PostgisRegisterTypesPlugin } from './plugins/register-types';
+export { PostgisGeometryFieldsPlugin } from './plugins/geometry-fields';
+export { GisSubtype, SUBTYPE_STRING_BY_SUBTYPE, GIS_SUBTYPE_NAME, CONCRETE_SUBTYPES } from './constants';
+export { getGISTypeDetails, getGISTypeModifier, getGISTypeName } from './utils';
+export type { GisTypeDetails, GisFieldValue } from './types';
+export type { PostgisExtensionInfo } from './plugins/detect-extension';

package/esm/index.js

@@ -1,33 +1,25 @@
-import PostgisExtensionDetectionPlugin from './PostgisExtensionDetectionPlugin';
-import PostgisInflectionPlugin from './PostgisInflectionPlugin';
-import PostgisRegisterTypesPlugin from './PostgisRegisterTypesPlugin';
-import PostgisVersionPlugin from './PostgisVersionPlugin';
-import Postgis_GeometryCollection_GeometriesPlugin from './Postgis_GeometryCollection_GeometriesPlugin';
-import Postgis_LineString_PointsPlugin from './Postgis_LineString_PointsPlugin';
-import Postgis_MultiLineString_LineStringsPlugin from './Postgis_MultiLineString_LineStringsPlugin';
-import Postgis_MultiPoint_PointsPlugin from './Postgis_MultiPoint_PointsPlugin';
-import Postgis_MultiPolygon_PolygonsPlugin from './Postgis_MultiPolygon_PolygonsPlugin';
-import Postgis_Point_LatitudeLongitudePlugin from './Postgis_Point_LatitudeLongitudePlugin';
-import Postgis_Polygon_RingsPlugin from './Postgis_Polygon_RingsPlugin';
-const PostgisPlugin = async (builder, options) => {
-    await PostgisVersionPlugin(builder, options);
-    await PostgisInflectionPlugin(builder, options);
-    await PostgisExtensionDetectionPlugin(builder, options);
-    await PostgisRegisterTypesPlugin(builder, options);
-    // Enhancing the `Point` type:
-    await Postgis_Point_LatitudeLongitudePlugin(builder, options);
-    // Enhancing the `LineString` type:
-    await Postgis_LineString_PointsPlugin(builder, options);
-    // Enhancing the `Polygon` type:
-    await Postgis_Polygon_RingsPlugin(builder, options);
-    // Enhancing the `MultiPoint` type:
-    await Postgis_MultiPoint_PointsPlugin(builder, options);
-    // Enhancing the `MultiLineString` type:
-    await Postgis_MultiLineString_LineStringsPlugin(builder, options);
-    // Enhancing the `MultiPolygon` type:
-    await Postgis_MultiPolygon_PolygonsPlugin(builder, options);
-    // Enhancing the `GeometryCollection` type:
-    await Postgis_GeometryCollection_GeometriesPlugin(builder, options);
-};
-export { PostgisExtensionDetectionPlugin, PostgisInflectionPlugin, PostgisRegisterTypesPlugin, PostgisVersionPlugin, Postgis_GeometryCollection_GeometriesPlugin, Postgis_LineString_PointsPlugin, Postgis_MultiLineString_LineStringsPlugin, Postgis_MultiPoint_PointsPlugin, Postgis_MultiPolygon_PolygonsPlugin, Postgis_Point_LatitudeLongitudePlugin, Postgis_Polygon_RingsPlugin };
-export default PostgisPlugin;
+/**
+ * PostGraphile v5 PostGIS Plugin
+ *
+ * Provides PostGIS geometry/geography type support for PostGraphile v5.
+ *
+ * @example
+ * ```typescript
+ * import { GraphilePostgisPreset } from 'graphile-postgis';
+ *
+ * const preset = {
+ *   extends: [GraphilePostgisPreset]
+ * };
+ * ```
+ */
+// Preset (recommended entry point)
+export { GraphilePostgisPreset } from './preset';
+// Individual plugins
+export { PostgisCodecPlugin } from './plugins/codec';
+export { PostgisInflectionPlugin } from './plugins/inflection';
+export { PostgisExtensionDetectionPlugin } from './plugins/detect-extension';
+export { PostgisRegisterTypesPlugin } from './plugins/register-types';
+export { PostgisGeometryFieldsPlugin } from './plugins/geometry-fields';
+// Constants and utilities
+export { GisSubtype, SUBTYPE_STRING_BY_SUBTYPE, GIS_SUBTYPE_NAME, CONCRETE_SUBTYPES } from './constants';
+export { getGISTypeDetails, getGISTypeModifier, getGISTypeName } from './utils';

package/esm/plugins/codec.d.ts

@@ -0,0 +1,19 @@
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * PostgisCodecPlugin
+ *
+ * Teaches PostGraphile v5 how to handle PostgreSQL's geometry and geography types.
+ *
+ * This plugin:
+ * 1. Creates codecs for geometry/geography via gather.hooks.pgCodecs_findPgCodec
+ * 2. The registered codecs use castFromPg to wrap geometry values in
+ *    json_build_object() with __gisType, __srid, __geojson metadata
+ * 3. fromPg normalizes the geometry type names for resolveType lookups
+ *
+ * Without castFromPg, PostGraphile defaults to `column::text` which returns
+ * WKB hex — unusable for GraphQL. The json_build_object wrapper provides
+ * structured metadata that downstream plugins use for type resolution and
+ * field values (x/y coordinates, GeoJSON, SRID, etc.).
+ */
+export declare const PostgisCodecPlugin: GraphileConfig.Plugin;

package/esm/plugins/codec.js

@@ -0,0 +1,174 @@
+import 'graphile-build-pg';
+import sql from 'pg-sql2';
+/**
+ * Map from PostGIS uppercase geometry type names (from geometrytype()) to
+ * our mixed-case format used by resolveType lookups.
+ *
+ * PostGIS `geometrytype()` returns uppercase: 'POINT', 'POINTZ', 'MULTIPOLYGON', etc.
+ * Our GIS_SUBTYPE_NAME uses mixed case: 'Point', 'LineString', 'MultiPolygon', etc.
+ * The getGISTypeName() utility produces: 'Point', 'PointZ', 'MultiPolygonZM', etc.
+ */
+const GIS_TYPE_NORMALIZE = {
+    POINT: 'Point',
+    POINTZ: 'PointZ',
+    POINTM: 'PointM',
+    POINTZM: 'PointZM',
+    LINESTRING: 'LineString',
+    LINESTRINGZ: 'LineStringZ',
+    LINESTRINGM: 'LineStringM',
+    LINESTRINGZM: 'LineStringZM',
+    POLYGON: 'Polygon',
+    POLYGONZ: 'PolygonZ',
+    POLYGONM: 'PolygonM',
+    POLYGONZM: 'PolygonZM',
+    MULTIPOINT: 'MultiPoint',
+    MULTIPOINTZ: 'MultiPointZ',
+    MULTIPOINTM: 'MultiPointM',
+    MULTIPOINTZM: 'MultiPointZM',
+    MULTILINESTRING: 'MultiLineString',
+    MULTILINESTRINGZ: 'MultiLineStringZ',
+    MULTILINESTRINGM: 'MultiLineStringM',
+    MULTILINESTRINGZM: 'MultiLineStringZM',
+    MULTIPOLYGON: 'MultiPolygon',
+    MULTIPOLYGONZ: 'MultiPolygonZ',
+    MULTIPOLYGONM: 'MultiPolygonM',
+    MULTIPOLYGONZM: 'MultiPolygonZM',
+    GEOMETRYCOLLECTION: 'GeometryCollection',
+    GEOMETRYCOLLECTIONZ: 'GeometryCollectionZ',
+    GEOMETRYCOLLECTIONM: 'GeometryCollectionM',
+    GEOMETRYCOLLECTIONZM: 'GeometryCollectionZM'
+};
+/**
+ * Normalize the __gisType from PostGIS uppercase to our mixed-case format.
+ * Falls back to the raw value if not in the map.
+ */
+function normalizeGisType(raw) {
+    return GIS_TYPE_NORMALIZE[raw] ?? raw;
+}
+/**
+ * Build a codec for a PostGIS geometry or geography type.
+ *
+ * The codec:
+ * - castFromPg: wraps the SQL column in json_build_object() with __gisType,
+ *   __srid, and __geojson fields (using PostGIS functions ST_SRID, ST_AsGeoJSON,
+ *   geometrytype). This replaces the default ::text cast.
+ * - fromPg: parses the JSON text result and normalizes __gisType case.
+ * - toPg: converts GeoJSON input back to a PostGIS-compatible value using
+ *   ST_GeomFromGeoJSON.
+ */
+function buildGisCodec(typeName, schemaName, typeOid, serviceName) {
+    return {
+        name: typeName,
+        sqlType: sql.identifier(schemaName, typeName),
+        /**
+         * castFromPg replaces the default `::text` cast. PostGraphile calls this
+         * to determine the SQL expression for selecting the column value.
+         *
+         * We wrap in json_build_object() so the result contains:
+         * - __gisType: geometry subtype name (e.g. "POINT", "POLYGON")
+         * - __srid: spatial reference ID
+         * - __geojson: the GeoJSON representation
+         *
+         * The result is cast to ::text so PostgreSQL sends it as a string,
+         * which fromPg then JSON.parses.
+         */
+        // NOTE: `fragment` is evaluated 4 times in the SQL. This is acceptable because
+        // PostGraphile v5 always passes simple column references here.
+        // If this changes, consider wrapping in a LATERAL subexpression.
+        castFromPg(fragment) {
+            return sql.fragment `(case when (${fragment}) is null then null else json_build_object(
+        '__gisType', ${sql.identifier(schemaName, 'geometrytype')}(${fragment}),
+        '__srid', ${sql.identifier(schemaName, 'st_srid')}(${fragment}),
+        '__geojson', ${sql.identifier(schemaName, 'st_asgeojson')}(${fragment})::json
+      )::text end)`;
+        },
+        /**
+         * fromPg receives the text value from PostgreSQL (output of castFromPg)
+         * and converts it to a JavaScript object.
+         *
+         * If castFromPg is working correctly, the value is always valid JSON.
+         * We normalize __gisType from PostGIS uppercase to our mixed-case format.
+         */
+        fromPg(value) {
+            let parsed;
+            try {
+                parsed = JSON.parse(value);
+            }
+            catch (e) {
+                throw new Error(`Failed to parse PostGIS geometry value: ${e instanceof Error ? e.message : String(e)}. ` +
+                    `Raw value (first 200 chars): ${String(value).slice(0, 200)}`);
+            }
+            if (parsed && typeof parsed === 'object' && parsed.__gisType) {
+                parsed.__gisType = normalizeGisType(parsed.__gisType);
+            }
+            return parsed;
+        },
+        /**
+         * toPg serializes a JavaScript value for insertion into PostgreSQL.
+         * Accepts GeoJSON objects and converts them to a JSON string that
+         * PostgreSQL can process via ST_GeomFromGeoJSON.
+         */
+        toPg(value) {
+            if (value && typeof value === 'object' && '__geojson' in value) {
+                return JSON.stringify(value.__geojson);
+            }
+            return JSON.stringify(value);
+        },
+        attributes: undefined,
+        executor: undefined,
+        extensions: {
+            oid: typeOid,
+            pg: {
+                serviceName,
+                schemaName,
+                name: typeName
+            }
+        }
+    };
+}
+/**
+ * PostgisCodecPlugin
+ *
+ * Teaches PostGraphile v5 how to handle PostgreSQL's geometry and geography types.
+ *
+ * This plugin:
+ * 1. Creates codecs for geometry/geography via gather.hooks.pgCodecs_findPgCodec
+ * 2. The registered codecs use castFromPg to wrap geometry values in
+ *    json_build_object() with __gisType, __srid, __geojson metadata
+ * 3. fromPg normalizes the geometry type names for resolveType lookups
+ *
+ * Without castFromPg, PostGraphile defaults to `column::text` which returns
+ * WKB hex — unusable for GraphQL. The json_build_object wrapper provides
+ * structured metadata that downstream plugins use for type resolution and
+ * field values (x/y coordinates, GeoJSON, SRID, etc.).
+ */
+export const PostgisCodecPlugin = {
+    name: 'PostgisCodecPlugin',
+    version: '2.0.0',
+    description: 'Registers codecs for PostGIS geometry and geography types',
+    gather: {
+        hooks: {
+            async pgCodecs_findPgCodec(info, event) {
+                if (event.pgCodec) {
+                    return;
+                }
+                const { pgType: type, serviceName } = event;
+                // Find the namespace for this type by its OID
+                const typeNamespace = await info.helpers.pgIntrospection.getNamespace(serviceName, type.typnamespace);
+                if (!typeNamespace) {
+                    return;
+                }
+                // We look for geometry/geography types in any schema (PostGIS can be
+                // installed in different schemas, commonly 'public' or 'postgis')
+                if (type.typname === 'geometry') {
+                    event.pgCodec = buildGisCodec('geometry', typeNamespace.nspname, type._id, serviceName);
+                    return;
+                }
+                if (type.typname === 'geography') {
+                    event.pgCodec = buildGisCodec('geography', typeNamespace.nspname, type._id, serviceName);
+                    return;
+                }
+            }
+        }
+    }
+};

package/esm/plugins/detect-extension.d.ts

@@ -0,0 +1,14 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+export type { PostgisExtensionInfo } from '../types';
+/**
+ * PostgisExtensionDetectionPlugin
+ *
+ * Detects PostGIS presence in the database by searching for geometry/geography
+ * codecs in the pgRegistry. Stores detected info on the build object for
+ * downstream plugins.
+ *
+ * Gracefully degrades if PostGIS is not installed.
+ */
+export declare const PostgisExtensionDetectionPlugin: GraphileConfig.Plugin;

package/esm/plugins/detect-extension.js

@@ -0,0 +1,57 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+/**
+ * PostgisExtensionDetectionPlugin
+ *
+ * Detects PostGIS presence in the database by searching for geometry/geography
+ * codecs in the pgRegistry. Stores detected info on the build object for
+ * downstream plugins.
+ *
+ * Gracefully degrades if PostGIS is not installed.
+ */
+export const PostgisExtensionDetectionPlugin = {
+    name: 'PostgisExtensionDetectionPlugin',
+    version: '2.0.0',
+    description: 'Detects PostGIS extension in the database',
+    schema: {
+        hooks: {
+            build(build) {
+                const pgRegistry = build.input?.pgRegistry;
+                if (!pgRegistry) {
+                    return build;
+                }
+                let geometryCodec = null;
+                let geographyCodec = null;
+                let schemaName = 'public';
+                // Search through codecs for geometry and geography types
+                for (const codec of Object.values(pgRegistry.pgCodecs)) {
+                    const pg = codec?.extensions?.pg;
+                    if (!pg)
+                        continue;
+                    if (pg.name === 'geometry') {
+                        geometryCodec = codec;
+                        schemaName = pg.schemaName || 'public';
+                    }
+                    else if (pg.name === 'geography') {
+                        geographyCodec = codec;
+                    }
+                }
+                // PostGIS requires at least the geometry codec to be present.
+                // Geography is optional — not all databases use geography columns,
+                // so PostGraphile may not introspect the geography type at all.
+                if (!geometryCodec) {
+                    return build;
+                }
+                const postgisInfo = {
+                    schemaName,
+                    geometryCodec,
+                    geographyCodec
+                };
+                return build.extend(build, {
+                    pgGISExtensionInfo: postgisInfo,
+                    pgGISGraphQLTypesByCodecAndSubtype: {}
+                }, 'PostgisExtensionDetectionPlugin adding PostGIS build state');
+            }
+        }
+    }
+};

package/esm/plugins/geometry-fields.d.ts

@@ -0,0 +1,21 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+import '../types';
+/**
+ * PostgisGeometryFieldsPlugin
+ *
+ * Enhances PostGIS geometry object types with subtype-specific fields:
+ *
+ * - Point: x/longitude, y/latitude, optional z/height
+ * - LineString: points array
+ * - Polygon: exterior ring, interiors array
+ * - MultiPoint: points array
+ * - MultiLineString: lines array
+ * - MultiPolygon: polygons array
+ * - GeometryCollection: geometries array (uses dimension interface)
+ *
+ * Uses the GraphQLObjectType_fields hook to add fields based on the
+ * type's scope (isPgGISType, pgGISCodecName, pgGISTypeDetails).
+ */
+export declare const PostgisGeometryFieldsPlugin: GraphileConfig.Plugin;