Merge pull request #49 from constructive-io/devin/1774221043-geotypes-rename-add-geography

feat(geotypes): rename domains and add geography variants

Author: pyramation

packages/geotypes/README.md

@@ -16,12 +16,14 @@ Geographic data types and spatial functions for PostgreSQL.
 
 ## Overview
 
-`@pgpm/geotypes` provides PostgreSQL domain types for geographic data, built on top of PostGIS geometry types. This package enables type-safe storage and validation of geographic coordinates and polygons with proper SRID (Spatial Reference System Identifier) enforcement.
+`@pgpm/geotypes` provides PostgreSQL domain types for geographic data, built on top of PostGIS geometry and geography types. This package enables type-safe storage and validation of geographic coordinates and polygons with proper SRID (Spatial Reference System Identifier) enforcement.
 
 ## Features
 
-- **geolocation**: A domain type for geographic points (latitude/longitude) using WGS84 (SRID 4326)
-- **geopolygon**: A domain type for geographic polygons using WGS84 (SRID 4326)
+- **geo_point**: A geometry domain for geographic points (latitude/longitude) using WGS84 (SRID 4326) — planar coordinates, fast computation
+- **geo_polygon**: A geometry domain for geographic polygons using WGS84 (SRID 4326) — planar coordinates
+- **geography_point**: A geography domain for geographic points using WGS84 (SRID 4326) — geodetic calculations on the sphere, distances in meters
+- **geography_polygon**: A geography domain for geographic polygons using WGS84 (SRID 4326) — geodetic calculations on the sphere
 - Automatic SRID validation to ensure coordinate system consistency
 - Integration with PostGIS spatial functions
 
@@ -82,30 +84,44 @@ pgpm deploy --createdb --database mydb1
 ### Creating Tables with Geographic Types
 
 ```sql
+-- Geometry (planar) types
 CREATE TABLE places (
   id serial PRIMARY KEY,
-  loc geolocation,
-  area geopolygon
+  loc geo_point,
+  area geo_polygon
+);
+
+-- Geography (spherical) types
+CREATE TABLE places_geo (
+  id serial PRIMARY KEY,
+  loc geography_point,
+  area geography_polygon
 );
 ```
 
 ### Inserting Geographic Data
 
 ```sql
--- Insert a point location (San Francisco)
+-- Insert a geometry point (San Francisco)
 INSERT INTO places (loc)
 VALUES (
   ST_SetSRID(ST_MakePoint(-122.4194, 37.7749), 4326)
 );
 
--- Insert a polygon area
+-- Insert a geometry polygon
 INSERT INTO places (area)
 VALUES (
   ST_SetSRID(
     ST_GeomFromText('POLYGON((-122.5 37.7, -122.4 37.7, -122.4 37.8, -122.5 37.8, -122.5 37.7))'),
     4326
   )
 );
+
+-- Insert a geography point (distances in meters, accounts for curvature)
+INSERT INTO places_geo (loc)
+VALUES (
+  ST_SetSRID(ST_MakePoint(-122.4194, 37.7749), 4326)::geography
+);
 ```
 
 ### SRID Validation
@@ -118,28 +134,48 @@ INSERT INTO places (loc)
 VALUES (
   ST_SetSRID(ST_MakePoint(-122.4194, 37.7749), 3857)
 );
--- ERROR: value for domain geolocation violates check constraint
+-- ERROR: value for domain geo_point violates check constraint
 ```
 
 ## Domain Types
 
-### geolocation
+### Geometry Domains (Planar)
 
-A PostgreSQL domain based on `geometry(Point, 4326)` that stores geographic point coordinates.
+#### geo_point
+
+A PostgreSQL domain based on `geometry(Point, 4326)` that stores geographic point coordinates using planar (flat) coordinates.
 
 - **Base Type**: `geometry(Point, 4326)`
-- **Use Case**: Storing latitude/longitude coordinates for locations
+- **Use Case**: Storing latitude/longitude coordinates for locations, fast computation
 - **SRID**: 4326 (WGS84 - World Geodetic System 1984)
 
-### geopolygon
+#### geo_polygon
 
-A PostgreSQL domain based on `geometry(Polygon, 4326)` that stores geographic polygon areas.
+A PostgreSQL domain based on `geometry(Polygon, 4326)` that stores geographic polygon areas using planar coordinates.
 
 - **Base Type**: `geometry(Polygon, 4326)`
 - **Use Case**: Storing geographic boundaries, regions, or areas
 - **SRID**: 4326 (WGS84)
 - **Validation**: Ensures valid polygon geometry (closed rings, proper vertex count)
 
+### Geography Domains (Spherical)
+
+#### geography_point
+
+A PostgreSQL domain based on `geography(Point, 4326)` that stores geographic point coordinates using geodetic (spherical) calculations.
+
+- **Base Type**: `geography(Point, 4326)`
+- **Use Case**: Real-world GPS data where distances should be in meters and account for Earth's curvature
+- **SRID**: 4326 (WGS84)
+
+#### geography_polygon
+
+A PostgreSQL domain based on `geography(Polygon, 4326)` that stores geographic polygon areas using geodetic calculations.
+
+- **Base Type**: `geography(Polygon, 4326)`
+- **Use Case**: Real-world geographic boundaries where area/distance calculations need to account for Earth's curvature
+- **SRID**: 4326 (WGS84)
+
 ## Dependencies
 
 - `@pgpm/types`: Core PostgreSQL type definitions
@@ -153,9 +189,10 @@ pnpm test
 ```
 
 The test suite validates:
-- Successful insertion of valid points and polygons
+- Successful insertion of valid geometry and geography points and polygons
 - SRID validation and rejection of incorrect coordinate systems
 - Polygon geometry validation
+- Geography distance calculations return values in meters
 
 ## Related Tooling
 

packages/geotypes/__tests__/geotypes.test.ts

@@ -11,8 +11,16 @@ beforeAll(async () => {
   await pg.any(`
     CREATE TABLE places (
       id serial PRIMARY KEY,
-      loc geolocation,
-      area geopolygon
+      loc geo_point,
+      area geo_polygon
+    );
+  `);
+
+  await pg.any(`
+    CREATE TABLE places_geo (
+      id serial PRIMARY KEY,
+      loc geography_point,
+      area geography_polygon
     );
   `);
 });
@@ -21,9 +29,9 @@ afterAll(async () => {
   await teardown();
 });
 
-describe('places table (geotypes)', () => {
+describe('geometry domains (geo_point, geo_polygon)', () => {
   it('inserts valid point and polygon', async () => {
-        await expect(pg.any(`
+    await expect(pg.any(`
       INSERT INTO places (loc, area)
       VALUES (
         ST_SetSRID(ST_MakePoint(-122.4194, 37.7749), 4326),
@@ -36,7 +44,7 @@ describe('places table (geotypes)', () => {
   });
 
   it('fails if point SRID is incorrect', async () => {
-        await expect(pg.any(`
+    await expect(pg.any(`
       INSERT INTO places (loc)
       VALUES (
         ST_SetSRID(ST_MakePoint(-122.4194, 37.7749), 3857)
@@ -45,11 +53,44 @@ describe('places table (geotypes)', () => {
   });
 
   it('fails if polygon is invalid', async () => {
-        await expect(pg.any(`
+    await expect(pg.any(`
       INSERT INTO places (area)
       VALUES (
         ST_SetSRID(ST_GeomFromText('POLYGON((0 0, 1 1, 2 2))'), 4326)
       );
     `)).rejects.toThrow();
   });
 });
+
+describe('geography domains (geography_point, geography_polygon)', () => {
+  it('inserts valid geography point and polygon', async () => {
+    await expect(pg.any(`
+      INSERT INTO places_geo (loc, area)
+      VALUES (
+        ST_SetSRID(ST_MakePoint(-122.4194, 37.7749), 4326)::geography,
+        ST_GeogFromText('POLYGON((-122.5 37.7, -122.4 37.7, -122.4 37.8, -122.5 37.8, -122.5 37.7))')
+      );
+    `)).resolves.not.toThrow();
+  });
+
+  it('computes distance in meters for geography_point', async () => {
+    const result = await pg.one(`
+      SELECT ST_Distance(
+        ST_SetSRID(ST_MakePoint(-122.4194, 37.7749), 4326)::geography,
+        ST_SetSRID(ST_MakePoint(-73.9857, 40.7484), 4326)::geography
+      ) AS dist_meters;
+    `);
+    // SF to NYC is approximately 4,000 km
+    expect(result.dist_meters).toBeGreaterThan(4000000);
+    expect(result.dist_meters).toBeLessThan(5000000);
+  });
+
+  it('fails if geography point SRID is incorrect', async () => {
+    await expect(pg.any(`
+      INSERT INTO places_geo (loc)
+      VALUES (
+        ST_SetSRID(ST_MakePoint(-122.4194, 37.7749), 3857)::geography
+      );
+    `)).rejects.toThrow();
+  });
+});

packages/geotypes/deploy/schemas/public/domains/geo_point.sql

@@ -0,0 +1,10 @@
+-- Deploy schemas/public/domains/geo_point to pg
+
+-- requires: schemas/public/schema
+
+BEGIN;
+
+CREATE DOMAIN geo_point AS geometry (Point, 4326);
+COMMENT ON DOMAIN geo_point IS E'@name pgpmInternalTypeGeoPoint';
+
+COMMIT;

packages/geotypes/deploy/schemas/public/domains/geo_polygon.sql

@@ -0,0 +1,10 @@
+-- Deploy schemas/public/domains/geo_polygon to pg
+
+-- requires: schemas/public/schema
+
+BEGIN;
+
+CREATE DOMAIN geo_polygon AS geometry (Polygon, 4326);
+COMMENT ON DOMAIN geo_polygon IS E'@name pgpmInternalTypeGeoPolygon';
+
+COMMIT;

packages/geotypes/deploy/schemas/public/domains/geography_point.sql

@@ -0,0 +1,10 @@
+-- Deploy schemas/public/domains/geography_point to pg
+
+-- requires: schemas/public/schema
+
+BEGIN;
+
+CREATE DOMAIN geography_point AS geography (Point, 4326);
+COMMENT ON DOMAIN geography_point IS E'@name pgpmInternalTypeGeographyPoint';
+
+COMMIT;

packages/geotypes/deploy/schemas/public/domains/geography_polygon.sql

@@ -0,0 +1,10 @@
+-- Deploy schemas/public/domains/geography_polygon to pg
+
+-- requires: schemas/public/schema
+
+BEGIN;
+
+CREATE DOMAIN geography_polygon AS geography (Polygon, 4326);
+COMMENT ON DOMAIN geography_polygon IS E'@name pgpmInternalTypeGeographyPolygon';
+
+COMMIT;

packages/geotypes/deploy/schemas/public/domains/geolocation.sql

@@ -3,5 +3,7 @@
 %uri=pgpm-geo-types
 
 schemas/public/schema 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/public/schema
-schemas/public/domains/geolocation [schemas/public/schema] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/public/domains/geolocation
-schemas/public/domains/geopolygon [schemas/public/schema] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/public/domains/geopolygon
+schemas/public/domains/geo_point [schemas/public/schema] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/public/domains/geo_point
+schemas/public/domains/geo_polygon [schemas/public/schema] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/public/domains/geo_polygon
+schemas/public/domains/geography_point [schemas/public/schema] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/public/domains/geography_point
+schemas/public/domains/geography_polygon [schemas/public/schema] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/public/domains/geography_polygon

packages/geotypes/deploy/schemas/public/domains/geopolygon.sql

@@ -0,0 +1,7 @@
+-- Revert schemas/public/domains/geo_point from pg
+
+BEGIN;
+
+DROP TYPE public.geo_point;
+
+COMMIT;