graphile-postgis 1.1.1 → 2.2.0

package/esm/preset.js

@@ -0,0 +1,30 @@
+import { PostgisCodecPlugin } from './plugins/codec';
+import { PostgisInflectionPlugin } from './plugins/inflection';
+import { PostgisExtensionDetectionPlugin } from './plugins/detect-extension';
+import { PostgisRegisterTypesPlugin } from './plugins/register-types';
+import { PostgisGeometryFieldsPlugin } from './plugins/geometry-fields';
+/**
+ * GraphilePostgisPreset
+ *
+ * A preset that includes all PostGIS plugins for PostGraphile v5.
+ * Use this as the recommended way to add PostGIS support.
+ *
+ * @example
+ * ```typescript
+ * import { GraphilePostgisPreset } from 'graphile-postgis';
+ *
+ * const preset = {
+ *   extends: [GraphilePostgisPreset]
+ * };
+ * ```
+ */
+export const GraphilePostgisPreset = {
+    plugins: [
+        PostgisCodecPlugin,
+        PostgisInflectionPlugin,
+        PostgisExtensionDetectionPlugin,
+        PostgisRegisterTypesPlugin,
+        PostgisGeometryFieldsPlugin
+    ]
+};
+export default GraphilePostgisPreset;

package/esm/types.d.ts

@@ -0,0 +1,84 @@
+import type { PgCodec } from '@dataplan/pg';
+import type { Geometry } from 'geojson';
+import type { GraphQLInterfaceType, GraphQLObjectType } from 'graphql';
+import type { SQL } from 'pg-sql2';
+import type { GisSubtype } from './constants';
+export interface GisTypeDetails {
+    subtype: GisSubtype;
+    hasZ: boolean;
+    hasM: boolean;
+    srid: number;
+}
+export interface GisFieldValue {
+    __gisType: string;
+    __srid: number;
+    __geojson: Geometry;
+}
+/**
+ * PostGIS extension detection result stored on the build object.
+ */
+export interface PostgisExtensionInfo {
+    /** The schema name where PostGIS is installed (e.g. 'public') */
+    schemaName: string;
+    /** The geometry codec from the registry */
+    geometryCodec: PgCodec;
+    /** The geography codec from the registry (optional — not all databases use geography columns) */
+    geographyCodec: PgCodec | null;
+}
+/**
+ * Module augmentations for PostGraphile v5 types.
+ *
+ * These declare the custom properties that our PostGIS plugins add to the
+ * build object, inflection, and scope interfaces. This allows downstream
+ * code (including our own plugins) to use these properties without `any` casts.
+ */
+declare global {
+    namespace GraphileBuild {
+        interface Build {
+            /** PostGIS extension info (set by PostgisExtensionDetectionPlugin) */
+            pgGISExtensionInfo?: PostgisExtensionInfo;
+            /** Map of codec name -> gisTypeKey -> GraphQL type name (for resolveType) */
+            pgGISGraphQLTypesByCodecAndSubtype?: Record<string, Record<string | number, string>>;
+            /** Gets a registered PostGIS GraphQL type by geometry type, subtype, and dimension */
+            getPostgisTypeByGeometryType?(gisCodecName: string, subtype: GisSubtype, hasZ?: boolean, hasM?: boolean, srid?: number): GraphQLObjectType | GraphQLInterfaceType | undefined;
+            /** Wraps a geometry/geography SQL expression in json_build_object() with metadata */
+            pgGISWrapExpression?(fragment: SQL): SQL;
+            /** Creates an SQL fragment to convert GeoJSON input to a geometry value */
+            pgGISFromGeoJSON?(value: Record<string, unknown>, codecName: string): SQL;
+        }
+        interface Inflection {
+            /** Generate GraphQL type name for a PostGIS concrete type */
+            gisType(typeName: string, subtype: GisSubtype, hasZ: boolean, hasM: boolean, srid?: number): string;
+            /** Generate interface name for a PostGIS base type (e.g. GeometryInterface) */
+            gisInterfaceName(typeName: string): string;
+            /** Generate dimension interface name (e.g. GeometryGeometryZ) */
+            gisDimensionInterfaceName(typeName: string, hasZ: boolean, hasM: boolean): string;
+            /** Generate GeoJSON field name */
+            geojsonFieldName(): string;
+            /** Generate X coordinate field name */
+            gisXFieldName(typeName: string): string;
+            /** Generate Y coordinate field name */
+            gisYFieldName(typeName: string): string;
+            /** Generate Z coordinate field name */
+            gisZFieldName(typeName: string): string;
+        }
+        interface ScopeObject {
+            /** Whether this is a PostGIS concrete type */
+            isPgGISType?: boolean;
+            /** The codec name (geometry/geography) this type belongs to */
+            pgGISCodecName?: string;
+            /** The type details (subtype, hasZ, hasM, srid) */
+            pgGISTypeDetails?: GisTypeDetails;
+        }
+        interface ScopeInterface {
+            /** Whether this is a PostGIS base interface */
+            isPgGISInterface?: boolean;
+            /** Whether this is a PostGIS dimension interface */
+            isPgGISDimensionInterface?: boolean;
+            /** The codec name (geometry/geography) this interface belongs to */
+            pgGISCodecName?: string;
+            /** The ZM flag (-1 for base, 0-3 for dimension) */
+            pgGISZMFlag?: number;
+        }
+    }
+}

package/esm/utils.d.ts

@@ -0,0 +1,21 @@
+import { GisSubtype } from './constants';
+import type { GisTypeDetails } from './types';
+/**
+ * Decodes a PostGIS type modifier into its component parts.
+ *
+ * Implements the C macro bit layout from liblwgeom.h:
+ * - SRID: bits 8-28
+ * - Subtype: bits 2-7
+ * - hasZ: bit 1
+ * - hasM: bit 0
+ */
+export declare const getGISTypeDetails: (modifier: number) => GisTypeDetails;
+/**
+ * Encodes PostGIS type details into a type modifier integer.
+ */
+export declare const getGISTypeModifier: (subtype: GisSubtype, hasZ: boolean, hasM: boolean, srid: number) => number;
+/**
+ * Returns the GIS type name string for a given subtype and Z/M flags.
+ * E.g. "PointZ", "MultiPolygonZM", "LineString"
+ */
+export declare const getGISTypeName: (subtype: GisSubtype, hasZ: boolean, hasM: boolean) => string;

package/esm/utils.js

@@ -1,4 +1,13 @@
-import { GIS_SUBTYPE_NAME, GisSubtype } from './constants';
+import { GisSubtype, GIS_SUBTYPE_NAME } from './constants';
+/**
+ * Decodes a PostGIS type modifier into its component parts.
+ *
+ * Implements the C macro bit layout from liblwgeom.h:
+ * - SRID: bits 8-28
+ * - Subtype: bits 2-7
+ * - hasZ: bit 1
+ * - hasM: bit 0
+ */
 export const getGISTypeDetails = (modifier) => {
     const allZeroesHopefully = modifier >> 24;
     if (allZeroesHopefully !== 0) {
@@ -24,13 +33,11 @@ export const getGISTypeDetails = (modifier) => {
         throw new Error(`Unsupported PostGIS modifier, expected 0-7, received ${subtypeNumeric} (${modifier})`);
     }
     const subtype = subtypeNumeric;
-    return {
-        subtype,
-        hasZ,
-        hasM,
-        srid
-    };
+    return { subtype, hasZ, hasM, srid };
 };
+/**
+ * Encodes PostGIS type details into a type modifier integer.
+ */
 export const getGISTypeModifier = (subtype, hasZ, hasM, srid) => {
     // Ref: https://github.com/postgis/postgis/blob/2.5.2/liblwgeom/liblwgeom.h.in#L156-L173
     // #define TYPMOD_SET_SRID(typmod, srid) ((typmod) = (((typmod) & 0xE00000FF) | ((srid & 0x001FFFFF)<<8)))
@@ -42,6 +49,10 @@ export const getGISTypeModifier = (subtype, hasZ, hasM, srid) => {
         (hasZ ? 0x00000002 : 0) +
         (hasM ? 0x00000001 : 0));
 };
+/**
+ * Returns the GIS type name string for a given subtype and Z/M flags.
+ * E.g. "PointZ", "MultiPolygonZM", "LineString"
+ */
 export const getGISTypeName = (subtype, hasZ, hasM) => {
     return `${GIS_SUBTYPE_NAME[subtype]}${hasZ ? 'Z' : ''}${hasM ? 'M' : ''}`;
 };

package/index.d.ts

@@ -1,15 +1,24 @@
-import type { Plugin } from 'graphile-build';
-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';
-declare const PostgisPlugin: Plugin;
-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]
+ * };
+ * ```
+ */
+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/index.js

@@ -1,49 +1,41 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
+/**
+ * PostGraphile v5 PostGIS Plugin
+ *
+ * Provides PostGIS geometry/geography type support for PostGraphile v5.
+ *
+ * @example
+ * ```typescript
+ * import { GraphilePostgisPreset } from 'graphile-postgis';
+ *
+ * const preset = {
+ *   extends: [GraphilePostgisPreset]
+ * };
+ * ```
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Postgis_Polygon_RingsPlugin = exports.Postgis_Point_LatitudeLongitudePlugin = exports.Postgis_MultiPolygon_PolygonsPlugin = exports.Postgis_MultiPoint_PointsPlugin = exports.Postgis_MultiLineString_LineStringsPlugin = exports.Postgis_LineString_PointsPlugin = exports.Postgis_GeometryCollection_GeometriesPlugin = exports.PostgisVersionPlugin = exports.PostgisRegisterTypesPlugin = exports.PostgisInflectionPlugin = exports.PostgisExtensionDetectionPlugin = void 0;
-const PostgisExtensionDetectionPlugin_1 = __importDefault(require("./PostgisExtensionDetectionPlugin"));
-exports.PostgisExtensionDetectionPlugin = PostgisExtensionDetectionPlugin_1.default;
-const PostgisInflectionPlugin_1 = __importDefault(require("./PostgisInflectionPlugin"));
-exports.PostgisInflectionPlugin = PostgisInflectionPlugin_1.default;
-const PostgisRegisterTypesPlugin_1 = __importDefault(require("./PostgisRegisterTypesPlugin"));
-exports.PostgisRegisterTypesPlugin = PostgisRegisterTypesPlugin_1.default;
-const PostgisVersionPlugin_1 = __importDefault(require("./PostgisVersionPlugin"));
-exports.PostgisVersionPlugin = PostgisVersionPlugin_1.default;
-const Postgis_GeometryCollection_GeometriesPlugin_1 = __importDefault(require("./Postgis_GeometryCollection_GeometriesPlugin"));
-exports.Postgis_GeometryCollection_GeometriesPlugin = Postgis_GeometryCollection_GeometriesPlugin_1.default;
-const Postgis_LineString_PointsPlugin_1 = __importDefault(require("./Postgis_LineString_PointsPlugin"));
-exports.Postgis_LineString_PointsPlugin = Postgis_LineString_PointsPlugin_1.default;
-const Postgis_MultiLineString_LineStringsPlugin_1 = __importDefault(require("./Postgis_MultiLineString_LineStringsPlugin"));
-exports.Postgis_MultiLineString_LineStringsPlugin = Postgis_MultiLineString_LineStringsPlugin_1.default;
-const Postgis_MultiPoint_PointsPlugin_1 = __importDefault(require("./Postgis_MultiPoint_PointsPlugin"));
-exports.Postgis_MultiPoint_PointsPlugin = Postgis_MultiPoint_PointsPlugin_1.default;
-const Postgis_MultiPolygon_PolygonsPlugin_1 = __importDefault(require("./Postgis_MultiPolygon_PolygonsPlugin"));
-exports.Postgis_MultiPolygon_PolygonsPlugin = Postgis_MultiPolygon_PolygonsPlugin_1.default;
-const Postgis_Point_LatitudeLongitudePlugin_1 = __importDefault(require("./Postgis_Point_LatitudeLongitudePlugin"));
-exports.Postgis_Point_LatitudeLongitudePlugin = Postgis_Point_LatitudeLongitudePlugin_1.default;
-const Postgis_Polygon_RingsPlugin_1 = __importDefault(require("./Postgis_Polygon_RingsPlugin"));
-exports.Postgis_Polygon_RingsPlugin = Postgis_Polygon_RingsPlugin_1.default;
-const PostgisPlugin = async (builder, options) => {
-    await (0, PostgisVersionPlugin_1.default)(builder, options);
-    await (0, PostgisInflectionPlugin_1.default)(builder, options);
-    await (0, PostgisExtensionDetectionPlugin_1.default)(builder, options);
-    await (0, PostgisRegisterTypesPlugin_1.default)(builder, options);
-    // Enhancing the `Point` type:
-    await (0, Postgis_Point_LatitudeLongitudePlugin_1.default)(builder, options);
-    // Enhancing the `LineString` type:
-    await (0, Postgis_LineString_PointsPlugin_1.default)(builder, options);
-    // Enhancing the `Polygon` type:
-    await (0, Postgis_Polygon_RingsPlugin_1.default)(builder, options);
-    // Enhancing the `MultiPoint` type:
-    await (0, Postgis_MultiPoint_PointsPlugin_1.default)(builder, options);
-    // Enhancing the `MultiLineString` type:
-    await (0, Postgis_MultiLineString_LineStringsPlugin_1.default)(builder, options);
-    // Enhancing the `MultiPolygon` type:
-    await (0, Postgis_MultiPolygon_PolygonsPlugin_1.default)(builder, options);
-    // Enhancing the `GeometryCollection` type:
-    await (0, Postgis_GeometryCollection_GeometriesPlugin_1.default)(builder, options);
-};
-exports.default = PostgisPlugin;
+exports.getGISTypeName = exports.getGISTypeModifier = exports.getGISTypeDetails = exports.CONCRETE_SUBTYPES = exports.GIS_SUBTYPE_NAME = exports.SUBTYPE_STRING_BY_SUBTYPE = exports.GisSubtype = 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; } });
+// Individual plugins
+var codec_1 = require("./plugins/codec");
+Object.defineProperty(exports, "PostgisCodecPlugin", { enumerable: true, get: function () { return codec_1.PostgisCodecPlugin; } });
+var inflection_1 = require("./plugins/inflection");
+Object.defineProperty(exports, "PostgisInflectionPlugin", { enumerable: true, get: function () { return inflection_1.PostgisInflectionPlugin; } });
+var detect_extension_1 = require("./plugins/detect-extension");
+Object.defineProperty(exports, "PostgisExtensionDetectionPlugin", { enumerable: true, get: function () { return detect_extension_1.PostgisExtensionDetectionPlugin; } });
+var register_types_1 = require("./plugins/register-types");
+Object.defineProperty(exports, "PostgisRegisterTypesPlugin", { enumerable: true, get: function () { return register_types_1.PostgisRegisterTypesPlugin; } });
+var geometry_fields_1 = require("./plugins/geometry-fields");
+Object.defineProperty(exports, "PostgisGeometryFieldsPlugin", { enumerable: true, get: function () { return geometry_fields_1.PostgisGeometryFieldsPlugin; } });
+// Constants and utilities
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "GisSubtype", { enumerable: true, get: function () { return constants_1.GisSubtype; } });
+Object.defineProperty(exports, "SUBTYPE_STRING_BY_SUBTYPE", { enumerable: true, get: function () { return constants_1.SUBTYPE_STRING_BY_SUBTYPE; } });
+Object.defineProperty(exports, "GIS_SUBTYPE_NAME", { enumerable: true, get: function () { return constants_1.GIS_SUBTYPE_NAME; } });
+Object.defineProperty(exports, "CONCRETE_SUBTYPES", { enumerable: true, get: function () { return constants_1.CONCRETE_SUBTYPES; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "getGISTypeDetails", { enumerable: true, get: function () { return utils_1.getGISTypeDetails; } });
+Object.defineProperty(exports, "getGISTypeModifier", { enumerable: true, get: function () { return utils_1.getGISTypeModifier; } });
+Object.defineProperty(exports, "getGISTypeName", { enumerable: true, get: function () { return utils_1.getGISTypeName; } });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "graphile-postgis",
-  "version": "1.1.1",
-  "description": "Graphile/PostGraphile PostGIS integration plugin",
+  "version": "2.2.0",
+  "description": "PostGIS support for PostGraphile v5",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
   "license": "MIT",
@@ -10,12 +10,11 @@
   "types": "index.d.ts",
   "scripts": {
     "clean": "makage clean",
-    "copy": "makage assets",
-    "prepack": "pnpm run build",
+    "prepack": "npm run build",
     "build": "makage build",
     "build:dev": "makage build --dev",
     "lint": "eslint . --fix",
-    "test": "jest --passWithNoTests",
+    "test": "jest",
     "test:watch": "jest --watch"
   },
   "publishConfig": {
@@ -33,24 +32,30 @@
     "postgres",
     "graphql",
     "constructive",
-    "pgpm"
+    "pgpm",
+    "geojson",
+    "geometry",
+    "geography"
   ],
   "bugs": {
     "url": "https://github.com/constructive-io/constructive/issues"
   },
+  "peerDependencies": {
+    "@dataplan/pg": "^1.0.0-rc.5",
+    "grafast": "^1.0.0-rc.7",
+    "graphile-build": "^5.0.0-rc.4",
+    "graphile-build-pg": "^5.0.0-rc.5",
+    "graphile-config": "^1.0.0-rc.5",
+    "graphql": "^16.9.0",
+    "pg-sql2": "^5.0.0-rc.4",
+    "postgraphile": "^5.0.0-rc.4"
+  },
   "devDependencies": {
     "@types/geojson": "^7946.0.14",
-    "graphile-test": "^3.1.1",
-    "makage": "^0.1.12",
-    "pgsql-test": "^3.1.1"
-  },
-  "dependencies": {
-    "find-and-require-package-json": "^0.9.0",
-    "graphile-build": "^4.14.1",
-    "graphile-build-pg": "^4.14.1",
-    "graphile-utils": "^4.14.1",
-    "graphql": "15.10.1",
-    "pg": "^8.17.1"
+    "@types/node": "^22.19.1",
+    "graphile-test": "^4.2.0",
+    "makage": "^0.1.10",
+    "pgsql-test": "^4.2.0"
   },
-  "gitHead": "49049ad3ddd762d35625f657cb42fa0862b829a0"
+  "gitHead": "b758178b808ce0bf451e86c0bd7e92079155db7c"
 }

package/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/plugins/codec.js

@@ -0,0 +1,180 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgisCodecPlugin = void 0;
+require("graphile-build-pg");
+const pg_sql2_1 = __importDefault(require("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: pg_sql2_1.default.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 pg_sql2_1.default.fragment `(case when (${fragment}) is null then null else json_build_object(
+        '__gisType', ${pg_sql2_1.default.identifier(schemaName, 'geometrytype')}(${fragment}),
+        '__srid', ${pg_sql2_1.default.identifier(schemaName, 'st_srid')}(${fragment}),
+        '__geojson', ${pg_sql2_1.default.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.).
+ */
+exports.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/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;