Merge pull request #997 from constructive-io/feat/node-type-registry-relation-spatial

feat(node-type-registry): add RelationSpatial node type (v0.13.0)

Author: pyramation

graphql/node-type-registry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-type-registry",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Node type definitions for the Constructive blueprint system. Single source of truth for all Authz*, Data*, Relation*, and View* node types.",
   "author": "Constructive <developers@constructive.io>",
   "main": "index.js",

graphql/node-type-registry/src/blueprint-types.generated.ts

@@ -627,6 +627,23 @@ export interface RelationManyToManyParams {
     [key: string]: unknown;
   };
 }
+/** Declares a spatial predicate between two existing geometry/geography columns. Inserts a metaschema_public.spatial_relation row; the sync_spatial_relation_tags trigger then projects a @spatialRelation smart tag onto the owner column so graphile-postgis' PostgisSpatialRelationsPlugin can expose it as a cross-table filter in GraphQL. Metadata-only: both source_field and target_field must already exist on their tables. Idempotent on (source_table_id, name). One direction per tag — author two RelationSpatial entries if symmetry is desired. */
+export interface RelationSpatialParams {
+  /* Table that owns the relation (the @spatialRelation tag is emitted on the owner column of this table) */
+  source_table_id: string;
+  /* Geometry/geography column on source_table that carries the @spatialRelation smart tag */
+  source_field_id: string;
+  /* Table being referenced by the spatial predicate */
+  target_table_id: string;
+  /* Geometry/geography column on target_table that the predicate is evaluated against */
+  target_field_id: string;
+  /* Relation name (stable, snake_case). Becomes the generated filter field name in GraphQL (e.g. nearby_clinic). Unique per (source_table_id, name) — idempotency key. */
+  name: string;
+  /* PostGIS spatial predicate. One of the 8 whitelisted operators. st_dwithin requires param_name. */
+  operator: "st_contains" | "st_within" | "st_intersects" | "st_covers" | "st_coveredby" | "st_overlaps" | "st_touches" | "st_dwithin";
+  /* Parameter name for parametric operators (currently only st_dwithin, which needs a distance argument). Must be NULL for all other operators. Enforced by table CHECK. */
+  param_name?: string;
+}
 /**
  * ===========================================================================
  * View node type parameters
@@ -1031,7 +1048,13 @@ export type BlueprintRelation = {
   target_table: string;
   source_schema_name?: string;
   target_schema_name?: string;
-} & Partial<RelationManyToManyParams>;
+} & Partial<RelationManyToManyParams> | {
+  $type: "RelationSpatial";
+  source_table: string;
+  target_table: string;
+  source_schema_name?: string;
+  target_schema_name?: string;
+} & Partial<RelationSpatialParams>;
 /**
  * ===========================================================================
  * Blueprint table and definition

graphql/node-type-registry/src/relation/index.ts

@@ -2,3 +2,4 @@ export { RelationBelongsTo } from './relation-belongs-to';
 export { RelationHasOne } from './relation-has-one';
 export { RelationHasMany } from './relation-has-many';
 export { RelationManyToMany } from './relation-many-to-many';
+export { RelationSpatial } from './relation-spatial';

graphql/node-type-registry/src/relation/relation-spatial.ts

@@ -0,0 +1,70 @@
+import type { NodeTypeDefinition } from '../types';
+
+export const RelationSpatial: NodeTypeDefinition = {
+  "name": "RelationSpatial",
+  "slug": "relation_spatial",
+  "category": "relation",
+  "display_name": "Spatial Relation",
+  "description": "Declares a spatial predicate between two existing geometry/geography columns. Inserts a metaschema_public.spatial_relation row; the sync_spatial_relation_tags trigger then projects a @spatialRelation smart tag onto the owner column so graphile-postgis' PostgisSpatialRelationsPlugin can expose it as a cross-table filter in GraphQL. Metadata-only: both source_field and target_field must already exist on their tables. Idempotent on (source_table_id, name). One direction per tag — author two RelationSpatial entries if symmetry is desired.",
+  "parameter_schema": {
+    "type": "object",
+    "properties": {
+      "source_table_id": {
+        "type": "string",
+        "format": "uuid",
+        "description": "Table that owns the relation (the @spatialRelation tag is emitted on the owner column of this table)"
+      },
+      "source_field_id": {
+        "type": "string",
+        "format": "uuid",
+        "description": "Geometry/geography column on source_table that carries the @spatialRelation smart tag"
+      },
+      "target_table_id": {
+        "type": "string",
+        "format": "uuid",
+        "description": "Table being referenced by the spatial predicate"
+      },
+      "target_field_id": {
+        "type": "string",
+        "format": "uuid",
+        "description": "Geometry/geography column on target_table that the predicate is evaluated against"
+      },
+      "name": {
+        "type": "string",
+        "description": "Relation name (stable, snake_case). Becomes the generated filter field name in GraphQL (e.g. nearby_clinic). Unique per (source_table_id, name) — idempotency key."
+      },
+      "operator": {
+        "type": "string",
+        "enum": [
+          "st_contains",
+          "st_within",
+          "st_intersects",
+          "st_covers",
+          "st_coveredby",
+          "st_overlaps",
+          "st_touches",
+          "st_dwithin"
+        ],
+        "description": "PostGIS spatial predicate. One of the 8 whitelisted operators. st_dwithin requires param_name."
+      },
+      "param_name": {
+        "type": "string",
+        "description": "Parameter name for parametric operators (currently only st_dwithin, which needs a distance argument). Must be NULL for all other operators. Enforced by table CHECK."
+      }
+    },
+    "required": [
+      "source_table_id",
+      "source_field_id",
+      "target_table_id",
+      "target_field_id",
+      "name",
+      "operator"
+    ]
+  },
+  "tags": [
+    "relation",
+    "spatial",
+    "postgis",
+    "schema"
+  ]
+};