@pgpm/geotypes 0.19.0 → 0.19.1

package/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,23 +84,31 @@ 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(
@@ -106,6 +116,12 @@ VALUES (
     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
 

package/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;

package/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;

package/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;

package/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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpm/geotypes",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Geographic data types and spatial functions for PostgreSQL",
   "author": "Dan Lynch <pyramation@gmail.com>",
   "contributors": [
@@ -21,8 +21,8 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@pgpm/types": "0.19.0",
-    "@pgpm/verify": "0.19.0"
+    "@pgpm/types": "0.19.1",
+    "@pgpm/verify": "0.19.1"
   },
   "devDependencies": {
     "pgpm": "^4.2.3"
@@ -35,5 +35,5 @@
   "bugs": {
     "url": "https://github.com/constructive-io/pgpm-modules/issues"
   },
-  "gitHead": "83be2dd4b07831c8c4f903437d20d350a673d19b"
+  "gitHead": "874490c55094ce0232bf230c613ee58685f369dc"
 }

package/pgpm-geo-types.control

@@ -1,6 +1,6 @@
 # pgpm-geo-types extension
 comment = 'pgpm-geo-types extension'
-default_version = '0.15.3'
+default_version = '0.15.5'
 module_pathname = '$libdir/pgpm-geo-types'
 requires = 'plpgsql,citext,postgis,pgpm-types,pgpm-verify'
 relocatable = false

package/pgpm.plan

@@ -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

package/revert/schemas/public/domains/geo_point.sql

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

package/revert/schemas/public/domains/geo_polygon.sql

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

package/revert/schemas/public/domains/geography_point.sql

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

package/revert/schemas/public/domains/geography_polygon.sql

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

package/sql/pgpm-geo-types--0.15.3.sql

@@ -1,8 +1,16 @@
 \echo Use "CREATE EXTENSION pgpm-geo-types" to load this file. \quit
-CREATE DOMAIN geolocation AS geometry(point, 4326);
+CREATE DOMAIN geo_point AS geometry(point, 4326);
 
-COMMENT ON DOMAIN geolocation IS '@name pgpmInternalTypeGeoLocation';
+COMMENT ON DOMAIN geo_point IS '@name pgpmInternalTypeGeoPoint';
 
-CREATE DOMAIN geopolygon AS geometry(polygon, 4326);
+CREATE DOMAIN geo_polygon AS geometry(polygon, 4326);
 
-COMMENT ON DOMAIN geopolygon IS '@name pgpmInternalTypeGeoPolygon';
+COMMENT ON DOMAIN geo_polygon IS '@name pgpmInternalTypeGeoPolygon';
+
+CREATE DOMAIN geography_point AS geography(point, 4326);
+
+COMMENT ON DOMAIN geography_point IS '@name pgpmInternalTypeGeographyPoint';
+
+CREATE DOMAIN geography_polygon AS geography(polygon, 4326);
+
+COMMENT ON DOMAIN geography_polygon IS '@name pgpmInternalTypeGeographyPolygon';

package/verify/schemas/public/domains/geo_point.sql

@@ -0,0 +1,7 @@
+-- Verify schemas/public/domains/geo_point on pg
+
+BEGIN;
+
+SELECT verify_domain ('public.geo_point');
+
+ROLLBACK;

package/verify/schemas/public/domains/geo_polygon.sql

@@ -0,0 +1,7 @@
+-- Verify schemas/public/domains/geo_polygon on pg
+
+BEGIN;
+
+SELECT verify_domain ('public.geo_polygon');
+
+ROLLBACK;

package/verify/schemas/public/domains/geography_point.sql

@@ -0,0 +1,7 @@
+-- Verify schemas/public/domains/geography_point on pg
+
+BEGIN;
+
+SELECT verify_domain ('public.geography_point');
+
+ROLLBACK;

package/verify/schemas/public/domains/geography_polygon.sql

@@ -0,0 +1,7 @@
+-- Verify schemas/public/domains/geography_polygon on pg
+
+BEGIN;
+
+SELECT verify_domain ('public.geography_polygon');
+
+ROLLBACK;

package/deploy/schemas/public/domains/geolocation.sql

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

package/deploy/schemas/public/domains/geopolygon.sql

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

package/revert/schemas/public/domains/geolocation.sql

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

package/revert/schemas/public/domains/geopolygon.sql

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

package/verify/schemas/public/domains/geolocation.sql

@@ -1,7 +0,0 @@
--- Verify schemas/public/domains/geolocation on pg
-
-BEGIN;
-
-SELECT verify_domain ('public.geolocation');
-
-ROLLBACK;

package/verify/schemas/public/domains/geopolygon.sql

@@ -1,7 +0,0 @@
--- Verify schemas/public/domains/geopolygon on pg
-
-BEGIN;
-
-SELECT verify_domain ('public.geopolygon');
-
-ROLLBACK;