@dotdo/postgres 0.1.0

package/src/extensions/geo.ts

@@ -0,0 +1,858 @@
+/**
+ * Geospatial Extension Utilities
+ *
+ * Provides helpers for working with PostgreSQL's native geographic types
+ * and the earthdistance + cube extensions for location-based queries.
+ *
+ * Since PostGIS is not available in PGLite, this module provides alternatives:
+ * - earthdistance: Calculate great circle distances between lat/long coordinates
+ * - cube: Multi-dimensional data type required by earthdistance
+ * - Native PostgreSQL geometric types: point, box, polygon, circle, path, line, lseg
+ *
+ * @example
+ * ```typescript
+ * import { GeoExtension, GeoPoint, parsePoint, serializePoint } from '@dotdo/postgres/extensions'
+ *
+ * // Create a table for locations with a point column
+ * const sql = GeoExtension.createLocationTableSQL('locations', { idColumn: 'uuid' })
+ *
+ * // Find locations within 10km of a coordinate
+ * const searchSQL = GeoExtension.findWithinRadiusSQL(
+ *   'locations',
+ *   { lat: 37.7749, lng: -122.4194 },
+ *   10,
+ *   'km'
+ * )
+ *
+ * // Parse PostgreSQL point string
+ * const point = parsePoint('(37.7749,-122.4194)')
+ * // { lat: 37.7749, lng: -122.4194 }
+ * ```
+ *
+ * @module extensions/geo
+ */
+
+import type { ExtensionDefinition } from './registry'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Geographic point with latitude and longitude
+ */
+export interface GeoPoint {
+  /** Latitude in degrees (-90 to 90) */
+  lat: number
+  /** Longitude in degrees (-180 to 180) */
+  lng: number
+}
+
+/**
+ * PostgreSQL native point type (x, y)
+ *
+ * Note: PostgreSQL's point type uses (x, y) coordinates.
+ * For geographic data, x = longitude, y = latitude (reversed from GeoPoint).
+ */
+export interface Point {
+  x: number
+  y: number
+}
+
+/**
+ * Bounding box defined by two corners
+ */
+export interface BoundingBox {
+  /** Southwest corner (min lat/lng) */
+  sw: GeoPoint
+  /** Northeast corner (max lat/lng) */
+  ne: GeoPoint
+}
+
+/**
+ * PostgreSQL native box type (upper right, lower left corners)
+ */
+export interface Box {
+  high: Point
+  low: Point
+}
+
+/**
+ * Polygon defined by a list of vertices
+ */
+export interface Polygon {
+  vertices: GeoPoint[]
+}
+
+/**
+ * Circle defined by center point and radius
+ */
+export interface Circle {
+  center: GeoPoint
+  /** Radius in the specified unit */
+  radius: number
+}
+
+/**
+ * Distance units supported by earthdistance calculations
+ */
+export type DistanceUnit = 'meters' | 'm' | 'kilometers' | 'km' | 'miles' | 'mi' | 'nautical_miles' | 'nm'
+
+/**
+ * Options for creating location tables
+ */
+export interface LocationTableOptions {
+  /** Additional columns to include */
+  additionalColumns?: string
+  /** Primary key column type: 'serial' | 'uuid' | 'bigserial' */
+  idColumn?: 'serial' | 'uuid' | 'bigserial'
+  /** Name column for the location */
+  includeNameColumn?: boolean
+  /** Description column */
+  includeDescriptionColumn?: boolean
+  /** Created/updated timestamps */
+  includeTimestamps?: boolean
+}
+
+/**
+ * Options for radius search queries
+ */
+export interface RadiusSearchOptions {
+  /** Column name for latitude (default: 'latitude') */
+  latColumn?: string
+  /** Column name for longitude (default: 'longitude') */
+  lngColumn?: string
+  /** Columns to select (default: '*') */
+  select?: string | string[]
+  /** Additional WHERE conditions */
+  where?: string
+  /** ORDER BY clause (default: distance ascending) */
+  orderBy?: string
+  /** Maximum results to return */
+  limit?: number
+  /** Include distance in results */
+  includeDistance?: boolean
+  /** Alias for distance column (default: 'distance') */
+  distanceAlias?: string
+}
+
+/**
+ * Options for bounding box search queries
+ */
+export interface BoundingBoxSearchOptions {
+  /** Column name for latitude (default: 'latitude') */
+  latColumn?: string
+  /** Column name for longitude (default: 'longitude') */
+  lngColumn?: string
+  /** Columns to select (default: '*') */
+  select?: string | string[]
+  /** Additional WHERE conditions */
+  where?: string
+  /** ORDER BY clause */
+  orderBy?: string
+  /** Maximum results to return */
+  limit?: number
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Earth radius in meters (used by earthdistance extension) */
+export const EARTH_RADIUS_METERS = 6371000
+
+/** Earth radius in kilometers */
+export const EARTH_RADIUS_KM = 6371
+
+/** Earth radius in miles */
+export const EARTH_RADIUS_MILES = 3958.8
+
+/** Earth radius in nautical miles */
+export const EARTH_RADIUS_NM = 3440.065
+
+/**
+ * Conversion factors to meters
+ */
+export const DISTANCE_TO_METERS: Record<DistanceUnit, number> = {
+  meters: 1,
+  m: 1,
+  kilometers: 1000,
+  km: 1000,
+  miles: 1609.344,
+  mi: 1609.344,
+  nautical_miles: 1852,
+  nm: 1852,
+}
+
+// ============================================================================
+// GeoExtension Object
+// ============================================================================
+
+/**
+ * Geospatial Extension utilities for PostgreSQL
+ *
+ * Provides SQL generation helpers for earthdistance/cube extensions
+ * and PostgreSQL's native geometric types.
+ */
+export const GeoExtension = {
+  name: 'geo' as const,
+  displayName: 'Geospatial' as const,
+  description: 'Geospatial utilities using earthdistance, cube, and native PostgreSQL types',
+
+  /**
+   * Get the extension definitions required for geospatial support
+   */
+  getDefinitions(): ExtensionDefinition[] {
+    return [
+      {
+        name: 'cube',
+        displayName: 'cube',
+        description: 'Multi-dimensional cube data type',
+        bundlePath: '../../pglite/release/cube.tar.gz',
+      },
+      {
+        name: 'earthdistance',
+        displayName: 'earthdistance',
+        description: 'Earth distance calculations using great circle math',
+        bundlePath: '../../pglite/release/earthdistance.tar.gz',
+        dependencies: ['cube'],
+      },
+    ]
+  },
+
+  /**
+   * Generate SQL to create the required extensions
+   * Note: cube must be created before earthdistance
+   */
+  createExtensionsSQL(): string {
+    return `-- Create cube extension (required by earthdistance)
+CREATE EXTENSION IF NOT EXISTS cube;
+
+-- Create earthdistance extension
+CREATE EXTENSION IF NOT EXISTS earthdistance;`
+  },
+
+  /**
+   * Generate SQL to create a table with location columns
+   */
+  createLocationTableSQL(tableName: string, options: LocationTableOptions = {}): string {
+    const {
+      additionalColumns,
+      idColumn = 'serial',
+      includeNameColumn = true,
+      includeDescriptionColumn = false,
+      includeTimestamps = true,
+    } = options
+
+    const columns: string[] = []
+
+    // Primary key
+    switch (idColumn) {
+      case 'uuid':
+        columns.push('id UUID PRIMARY KEY DEFAULT gen_random_uuid()')
+        break
+      case 'bigserial':
+        columns.push('id BIGSERIAL PRIMARY KEY')
+        break
+      default:
+        columns.push('id SERIAL PRIMARY KEY')
+    }
+
+    // Name column
+    if (includeNameColumn) {
+      columns.push('name VARCHAR(255) NOT NULL')
+    }
+
+    // Description column
+    if (includeDescriptionColumn) {
+      columns.push('description TEXT')
+    }
+
+    // Location columns
+    columns.push('latitude DOUBLE PRECISION NOT NULL')
+    columns.push('longitude DOUBLE PRECISION NOT NULL')
+
+    // Additional columns
+    if (additionalColumns) {
+      columns.push(additionalColumns)
+    }
+
+    // Timestamps
+    if (includeTimestamps) {
+      columns.push('created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()')
+      columns.push('updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()')
+    }
+
+    return `CREATE TABLE IF NOT EXISTS ${tableName} (
+  ${columns.join(',\n  ')}
+);
+
+-- Create index for faster distance queries using cube
+CREATE INDEX IF NOT EXISTS idx_${tableName}_location ON ${tableName}
+USING gist (ll_to_earth(latitude, longitude));`
+  },
+
+  /**
+   * Generate SQL to find locations within a radius
+   *
+   * Uses the earthdistance extension's earth_distance function
+   * which calculates great circle distance between two points.
+   *
+   * @param tableName Table to search
+   * @param center Center point for the search
+   * @param radius Search radius
+   * @param unit Distance unit (default: meters)
+   * @param options Additional search options
+   */
+  findWithinRadiusSQL(
+    tableName: string,
+    center: GeoPoint,
+    radius: number,
+    unit: DistanceUnit = 'meters',
+    options: RadiusSearchOptions = {}
+  ): string {
+    const {
+      latColumn = 'latitude',
+      lngColumn = 'longitude',
+      select = '*',
+      where,
+      orderBy,
+      limit,
+      includeDistance = true,
+      distanceAlias = 'distance',
+    } = options
+
+    const radiusMeters = radius * DISTANCE_TO_METERS[unit]
+    const selectClause = Array.isArray(select) ? select.join(', ') : select
+
+    // Build the distance expression
+    const distanceExpr = `earth_distance(
+    ll_to_earth(${latColumn}, ${lngColumn}),
+    ll_to_earth(${center.lat}, ${center.lng})
+  )`
+
+    // Build select with optional distance
+    const finalSelect = includeDistance
+      ? `${selectClause}, ${distanceExpr} AS ${distanceAlias}`
+      : selectClause
+
+    // Build WHERE clause
+    const whereConditions = [`${distanceExpr} <= ${radiusMeters}`]
+    if (where) {
+      whereConditions.push(`(${where})`)
+    }
+
+    // Build ORDER BY
+    const orderByClause = orderBy || `${distanceAlias} ASC`
+
+    // Build full query
+    let sql = `SELECT ${finalSelect}
+FROM ${tableName}
+WHERE ${whereConditions.join(' AND ')}
+ORDER BY ${orderByClause}`
+
+    if (limit) {
+      sql += `\nLIMIT ${limit}`
+    }
+
+    return sql + ';'
+  },
+
+  /**
+   * Generate SQL to find locations within a bounding box
+   *
+   * More efficient for initial filtering before applying
+   * precise distance calculations.
+   */
+  findWithinBoundingBoxSQL(
+    tableName: string,
+    bounds: BoundingBox,
+    options: BoundingBoxSearchOptions = {}
+  ): string {
+    const {
+      latColumn = 'latitude',
+      lngColumn = 'longitude',
+      select = '*',
+      where,
+      orderBy,
+      limit,
+    } = options
+
+    const selectClause = Array.isArray(select) ? select.join(', ') : select
+
+    // Build WHERE clause
+    const whereConditions = [
+      `${latColumn} BETWEEN ${bounds.sw.lat} AND ${bounds.ne.lat}`,
+      `${lngColumn} BETWEEN ${bounds.sw.lng} AND ${bounds.ne.lng}`,
+    ]
+    if (where) {
+      whereConditions.push(`(${where})`)
+    }
+
+    let sql = `SELECT ${selectClause}
+FROM ${tableName}
+WHERE ${whereConditions.join(' AND ')}`
+
+    if (orderBy) {
+      sql += `\nORDER BY ${orderBy}`
+    }
+
+    if (limit) {
+      sql += `\nLIMIT ${limit}`
+    }
+
+    return sql + ';'
+  },
+
+  /**
+   * Generate SQL to calculate distance between two points
+   */
+  distanceSQL(point1: GeoPoint, point2: GeoPoint, unit: DistanceUnit = 'meters'): string {
+    const divisor = DISTANCE_TO_METERS[unit]
+    return `SELECT earth_distance(
+  ll_to_earth(${point1.lat}, ${point1.lng}),
+  ll_to_earth(${point2.lat}, ${point2.lng})
+) / ${divisor} AS distance;`
+  },
+
+  /**
+   * Generate SQL expression for distance calculation (for use in queries)
+   */
+  distanceExpression(
+    latColumn: string,
+    lngColumn: string,
+    center: GeoPoint,
+    unit: DistanceUnit = 'meters'
+  ): string {
+    const divisor = DISTANCE_TO_METERS[unit]
+    return `earth_distance(ll_to_earth(${latColumn}, ${lngColumn}), ll_to_earth(${center.lat}, ${center.lng})) / ${divisor}`
+  },
+
+  /**
+   * Generate SQL to find K nearest neighbors
+   *
+   * @param tableName Table to search
+   * @param center Reference point
+   * @param k Number of nearest neighbors to find
+   * @param options Search options
+   */
+  findKNearestSQL(
+    tableName: string,
+    center: GeoPoint,
+    k: number,
+    options: RadiusSearchOptions = {}
+  ): string {
+    const {
+      latColumn = 'latitude',
+      lngColumn = 'longitude',
+      select = '*',
+      where,
+      includeDistance = true,
+      distanceAlias = 'distance',
+    } = options
+
+    const selectClause = Array.isArray(select) ? select.join(', ') : select
+
+    // Build the distance expression
+    const distanceExpr = `earth_distance(
+    ll_to_earth(${latColumn}, ${lngColumn}),
+    ll_to_earth(${center.lat}, ${center.lng})
+  )`
+
+    // Build select with optional distance
+    const finalSelect = includeDistance
+      ? `${selectClause}, ${distanceExpr} AS ${distanceAlias}`
+      : selectClause
+
+    // Build WHERE clause
+    const whereClause = where ? `WHERE ${where}\n` : ''
+
+    return `SELECT ${finalSelect}
+FROM ${tableName}
+${whereClause}ORDER BY ${distanceExpr} ASC
+LIMIT ${k};`
+  },
+
+  /**
+   * Calculate a bounding box for a given center point and radius
+   *
+   * Useful for creating efficient queries that first filter by bounding box
+   * before applying precise distance calculations.
+   */
+  calculateBoundingBox(center: GeoPoint, radius: number, unit: DistanceUnit = 'meters'): BoundingBox {
+    const radiusKm = (radius * DISTANCE_TO_METERS[unit]) / 1000
+
+    // Approximate degrees per km at the equator
+    const kmPerDegreeLat = 111.32
+    const kmPerDegreeLng = 111.32 * Math.cos((center.lat * Math.PI) / 180)
+
+    const latDelta = radiusKm / kmPerDegreeLat
+    const lngDelta = radiusKm / kmPerDegreeLng
+
+    return {
+      sw: {
+        lat: center.lat - latDelta,
+        lng: center.lng - lngDelta,
+      },
+      ne: {
+        lat: center.lat + latDelta,
+        lng: center.lng + lngDelta,
+      },
+    }
+  },
+}
+
+// ============================================================================
+// PostgreSQL Native Geometric Types
+// ============================================================================
+
+/**
+ * PostgreSQL Native Geometric Types
+ *
+ * PostgreSQL includes several built-in geometric types that work without
+ * any extensions. These are useful for simple geometric operations.
+ *
+ * Types:
+ * - point: A point in 2D space (x, y)
+ * - box: A rectangular box defined by two corner points
+ * - circle: A circle defined by center point and radius
+ * - polygon: A closed path defined by a list of points
+ * - path: Open or closed path of connected line segments
+ * - line: Infinite line (Ax + By + C = 0)
+ * - lseg: Line segment defined by two points
+ */
+export const PostgresGeoTypes = {
+  /**
+   * SQL to create a table with native PostgreSQL point column
+   */
+  createPointTableSQL(tableName: string, pointColumn: string = 'location'): string {
+    return `CREATE TABLE IF NOT EXISTS ${tableName} (
+  id SERIAL PRIMARY KEY,
+  ${pointColumn} POINT NOT NULL
+);
+
+-- Create GiST index for spatial queries on point column
+CREATE INDEX IF NOT EXISTS idx_${tableName}_${pointColumn} ON ${tableName}
+USING gist (${pointColumn});`
+  },
+
+  /**
+   * SQL to create a table with native PostgreSQL box column
+   */
+  createBoxTableSQL(tableName: string, boxColumn: string = 'bounds'): string {
+    return `CREATE TABLE IF NOT EXISTS ${tableName} (
+  id SERIAL PRIMARY KEY,
+  ${boxColumn} BOX NOT NULL
+);
+
+-- Create GiST index for spatial queries on box column
+CREATE INDEX IF NOT EXISTS idx_${tableName}_${boxColumn} ON ${tableName}
+USING gist (${boxColumn});`
+  },
+
+  /**
+   * SQL to find points within a box using native PostgreSQL operators
+   *
+   * @param tableName Table to search
+   * @param pointColumn Column containing point data
+   * @param box Bounding box to search within
+   */
+  pointsWithinBoxSQL(tableName: string, pointColumn: string, box: Box): string {
+    const boxStr = `'(${box.high.x},${box.high.y}),(${box.low.x},${box.low.y})'::box`
+    return `SELECT * FROM ${tableName}
+WHERE ${pointColumn} <@ ${boxStr};`
+  },
+
+  /**
+   * SQL to find points within a circle using native PostgreSQL operators
+   */
+  pointsWithinCircleSQL(
+    tableName: string,
+    pointColumn: string,
+    center: Point,
+    radius: number
+  ): string {
+    const circleStr = `'<(${center.x},${center.y}),${radius}>'::circle`
+    return `SELECT * FROM ${tableName}
+WHERE ${pointColumn} <@ ${circleStr};`
+  },
+
+  /**
+   * SQL to calculate distance between two native PostgreSQL points
+   */
+  pointDistanceSQL(point1: Point, point2: Point): string {
+    return `SELECT '(${point1.x},${point1.y})'::point <-> '(${point2.x},${point2.y})'::point AS distance;`
+  },
+
+  /**
+   * SQL expression for point distance (for use in queries)
+   */
+  pointDistanceExpression(pointColumn: string, target: Point): string {
+    return `${pointColumn} <-> '(${target.x},${target.y})'::point`
+  },
+}
+
+// ============================================================================
+// Parsing and Serialization Functions
+// ============================================================================
+
+/**
+ * Parse a PostgreSQL point string to a Point object
+ *
+ * @param value PostgreSQL point string like "(x,y)"
+ * @returns Point object or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const point = parsePoint('(1.5,2.5)')
+ * // { x: 1.5, y: 2.5 }
+ * ```
+ */
+export function parsePoint(value: string): Point | null {
+  if (!value || typeof value !== 'string') {
+    return null
+  }
+
+  const trimmed = value.trim()
+  if (!trimmed.startsWith('(') || !trimmed.endsWith(')')) {
+    return null
+  }
+
+  const inner = trimmed.slice(1, -1)
+  const parts = inner.split(',')
+
+  if (parts.length !== 2) {
+    return null
+  }
+
+  const part0 = parts[0]
+  const part1 = parts[1]
+  if (part0 === undefined || part1 === undefined) {
+    return null
+  }
+
+  const x = parseFloat(part0.trim())
+  const y = parseFloat(part1.trim())
+
+  if (isNaN(x) || isNaN(y)) {
+    return null
+  }
+
+  return { x, y }
+}
+
+/**
+ * Serialize a Point to PostgreSQL point string
+ *
+ * @param point Point object
+ * @returns PostgreSQL point string like "(x,y)"
+ */
+export function serializePoint(point: Point): string {
+  return `(${point.x},${point.y})`
+}
+
+/**
+ * Parse a PostgreSQL point string to a GeoPoint (lat/lng)
+ *
+ * Note: PostgreSQL points are (x, y) where x = longitude, y = latitude
+ *
+ * @param value PostgreSQL point string
+ * @returns GeoPoint or null if invalid
+ */
+export function parseGeoPoint(value: string): GeoPoint | null {
+  const point = parsePoint(value)
+  if (!point) return null
+
+  return {
+    lat: point.y,  // y = latitude
+    lng: point.x,  // x = longitude
+  }
+}
+
+/**
+ * Serialize a GeoPoint to PostgreSQL point string
+ *
+ * Note: PostgreSQL points are (x, y) where x = longitude, y = latitude
+ */
+export function serializeGeoPoint(geoPoint: GeoPoint): string {
+  return `(${geoPoint.lng},${geoPoint.lat})`  // (x=lng, y=lat)
+}
+
+/**
+ * Parse a PostgreSQL box string to a Box object
+ *
+ * @param value PostgreSQL box string like "(x1,y1),(x2,y2)"
+ * @returns Box object or null if invalid
+ */
+export function parseBox(value: string): Box | null {
+  if (!value || typeof value !== 'string') {
+    return null
+  }
+
+  // Remove outer parens if present
+  let trimmed = value.trim()
+
+  // Box format can be "(x1,y1),(x2,y2)" or "((x1,y1),(x2,y2))"
+  if (trimmed.startsWith('(') && trimmed.endsWith(')') && trimmed.includes('),(')) {
+    // Find the two point strings
+    const midIndex = trimmed.indexOf('),(')
+    const point1Str = trimmed.slice(0, midIndex + 1)
+    const point2Str = trimmed.slice(midIndex + 2)
+
+    const point1 = parsePoint(point1Str)
+    const point2 = parsePoint(point2Str)
+
+    if (!point1 || !point2) return null
+
+    return {
+      high: point1,
+      low: point2,
+    }
+  }
+
+  return null
+}
+
+/**
+ * Serialize a Box to PostgreSQL box string
+ */
+export function serializeBox(box: Box): string {
+  return `(${box.high.x},${box.high.y}),(${box.low.x},${box.low.y})`
+}
+
+/**
+ * Parse a PostgreSQL polygon string to a Polygon object (as GeoPoints)
+ *
+ * @param value PostgreSQL polygon string like "((x1,y1),(x2,y2),(x3,y3))"
+ */
+export function parsePolygon(value: string): Polygon | null {
+  if (!value || typeof value !== 'string') {
+    return null
+  }
+
+  // Polygon format: ((x1,y1),(x2,y2),...)
+  let trimmed = value.trim()
+  if (!trimmed.startsWith('((') || !trimmed.endsWith('))')) {
+    return null
+  }
+
+  // Remove outer parens
+  const inner = trimmed.slice(1, -1)
+
+  // Split by "),(" to get individual points
+  const pointStrs = inner.split('),(')
+  const vertices: GeoPoint[] = []
+
+  for (let i = 0; i < pointStrs.length; i++) {
+    let pStr = pointStrs[i]
+    if (pStr === undefined) continue
+    // Add back parens that were removed by split
+    if (!pStr.startsWith('(')) pStr = '(' + pStr
+    if (!pStr.endsWith(')')) pStr = pStr + ')'
+
+    const point = parseGeoPoint(pStr)
+    if (!point) return null
+    vertices.push(point)
+  }
+
+  return { vertices }
+}
+
+/**
+ * Serialize a Polygon to PostgreSQL polygon string
+ */
+export function serializePolygon(polygon: Polygon): string {
+  const pointStrs = polygon.vertices.map(v => `(${v.lng},${v.lat})`)
+  return `(${pointStrs.join(',')})`
+}
+
+// ============================================================================
+// Distance Calculation Utilities (JavaScript)
+// ============================================================================
+
+/**
+ * Calculate the Haversine distance between two points in JavaScript
+ *
+ * Useful for client-side distance calculations without hitting the database.
+ *
+ * @param point1 First point
+ * @param point2 Second point
+ * @param unit Distance unit (default: meters)
+ * @returns Distance in the specified unit
+ */
+export function haversineDistance(
+  point1: GeoPoint,
+  point2: GeoPoint,
+  unit: DistanceUnit = 'meters'
+): number {
+  const toRadians = (deg: number) => (deg * Math.PI) / 180
+
+  const lat1 = toRadians(point1.lat)
+  const lat2 = toRadians(point2.lat)
+  const deltaLat = toRadians(point2.lat - point1.lat)
+  const deltaLng = toRadians(point2.lng - point1.lng)
+
+  // Haversine formula: 'haversineA' is the square of half the chord length between the points
+  const haversineA =
+    Math.sin(deltaLat / 2) * Math.sin(deltaLat / 2) +
+    Math.cos(lat1) * Math.cos(lat2) * Math.sin(deltaLng / 2) * Math.sin(deltaLng / 2)
+
+  // Angular distance in radians
+  const angularDistance = 2 * Math.atan2(Math.sqrt(haversineA), Math.sqrt(1 - haversineA))
+
+  const distanceMeters = EARTH_RADIUS_METERS * angularDistance
+
+  return distanceMeters / DISTANCE_TO_METERS[unit]
+}
+
+/**
+ * Check if a point is within a bounding box
+ */
+export function isPointInBoundingBox(point: GeoPoint, bounds: BoundingBox): boolean {
+  return (
+    point.lat >= bounds.sw.lat &&
+    point.lat <= bounds.ne.lat &&
+    point.lng >= bounds.sw.lng &&
+    point.lng <= bounds.ne.lng
+  )
+}
+
+/**
+ * Check if a point is within a radius of another point
+ */
+export function isPointWithinRadius(
+  point: GeoPoint,
+  center: GeoPoint,
+  radius: number,
+  unit: DistanceUnit = 'meters'
+): boolean {
+  return haversineDistance(point, center, unit) <= radius
+}
+
+// ============================================================================
+// Default Export
+// ============================================================================
+
+export default {
+  GeoExtension,
+  PostgresGeoTypes,
+  // Constants
+  EARTH_RADIUS_METERS,
+  EARTH_RADIUS_KM,
+  EARTH_RADIUS_MILES,
+  EARTH_RADIUS_NM,
+  DISTANCE_TO_METERS,
+  // Parsing functions
+  parsePoint,
+  serializePoint,
+  parseGeoPoint,
+  serializeGeoPoint,
+  parseBox,
+  serializeBox,
+  parsePolygon,
+  serializePolygon,
+  // Distance utilities
+  haversineDistance,
+  isPointInBoundingBox,
+  isPointWithinRadius,
+}