@dotdo/postgres 0.1.0

package/dist/extensions/config.js

@@ -0,0 +1,216 @@
+/**
+ * Extension Configuration API
+ *
+ * Provides configuration utilities for enabling and managing PostgreSQL extensions
+ * with support for presets, validation, and merging.
+ */
+/**
+ * Known extension names for validation
+ */
+const KNOWN_EXTENSIONS = new Set([
+    'vector',
+    'pg_trgm',
+    'hstore',
+    'citext',
+    'uuid_ossp',
+    'pgcrypto',
+    'btree_gin',
+    'btree_gist',
+    'fuzzystrmatch',
+    'intarray',
+    'ltree',
+    'tablefunc',
+    'unaccent',
+    'cube',
+    'earthdistance',
+    'isn',
+    'lo',
+    'seg',
+    'tcn',
+    'bloom',
+    'amcheck',
+    'auto_explain',
+    'dict_int',
+    'dict_xsyn',
+    'file_fdw',
+    'pageinspect',
+    'pg_buffercache',
+    'pg_freespacemap',
+    'pg_surgery',
+    'pg_visibility',
+    'pg_walinspect',
+    'tsm_system_rows',
+    'tsm_system_time',
+]);
+/**
+ * Regex for valid extension names
+ */
+const VALID_NAME_REGEX = /^[a-z][a-z0-9_]*$/;
+/**
+ * Create an extension configuration
+ */
+export function createExtensionConfig(extensions) {
+    return {
+        extensions: extensions ?? {},
+    };
+}
+/**
+ * Merge two extension configurations, with the second taking precedence
+ */
+export function mergeExtensionConfigs(base, override) {
+    const baseExtensions = base?.extensions ?? {};
+    const overrideExtensions = override?.extensions ?? {};
+    const merged = { ...baseExtensions };
+    for (const [name, value] of Object.entries(overrideExtensions)) {
+        const baseValue = baseExtensions[name];
+        // If both are objects, merge them
+        if (typeof baseValue === 'object' &&
+            baseValue !== null &&
+            typeof value === 'object' &&
+            value !== null) {
+            merged[name] = { ...baseValue, ...value };
+        }
+        else {
+            merged[name] = value;
+        }
+    }
+    return { extensions: merged };
+}
+/**
+ * Validate an extension configuration
+ */
+export function validateExtensionConfig(config) {
+    const errors = [];
+    const warnings = [];
+    if (!config.extensions) {
+        return { valid: true, errors, warnings };
+    }
+    for (const [name, value] of Object.entries(config.extensions)) {
+        // Check name format
+        if (!VALID_NAME_REGEX.test(name)) {
+            errors.push(`Invalid extension name "${name}": must start with a letter and contain only lowercase letters, numbers, and underscores`);
+        }
+        // Check if known extension
+        if (!KNOWN_EXTENSIONS.has(name) && VALID_NAME_REGEX.test(name)) {
+            warnings.push(`Unknown extension "${name}": this extension may not be available`);
+        }
+        // Validate value
+        if (typeof value === 'object' && value !== null) {
+            if (typeof value.enabled !== 'boolean') {
+                errors.push(`Extension "${name}": "enabled" must be a boolean`);
+            }
+            if (value.autoCreate !== undefined && typeof value.autoCreate !== 'boolean') {
+                errors.push(`Extension "${name}": "autoCreate" must be a boolean`);
+            }
+        }
+        else if (typeof value !== 'boolean') {
+            errors.push(`Extension "${name}": value must be a boolean or options object`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Extension configuration presets for common use cases
+ */
+export const PRESETS = {
+    /**
+     * Minimal preset - no extensions enabled
+     */
+    MINIMAL: createExtensionConfig(),
+    /**
+     * Vector search preset - for AI/ML embeddings
+     */
+    VECTOR_SEARCH: createExtensionConfig({
+        vector: { enabled: true, autoCreate: true },
+    }),
+    /**
+     * Full-text search preset - for text search applications
+     */
+    FULL_TEXT_SEARCH: createExtensionConfig({
+        pg_trgm: { enabled: true, autoCreate: true },
+        fuzzystrmatch: { enabled: true, autoCreate: true },
+        unaccent: { enabled: true, autoCreate: true },
+    }),
+    /**
+     * Common preset - popular extensions for general use
+     */
+    COMMON: createExtensionConfig({
+        uuid_ossp: { enabled: true, autoCreate: true },
+        pgcrypto: { enabled: true, autoCreate: true },
+        citext: { enabled: true, autoCreate: true },
+        hstore: { enabled: true, autoCreate: true },
+    }),
+    /**
+     * Full preset - all commonly used extensions
+     */
+    FULL: createExtensionConfig({
+        vector: { enabled: true, autoCreate: true },
+        pg_trgm: { enabled: true, autoCreate: true },
+        hstore: { enabled: true, autoCreate: true },
+        citext: { enabled: true, autoCreate: true },
+        uuid_ossp: { enabled: true, autoCreate: true },
+        pgcrypto: { enabled: true, autoCreate: true },
+        btree_gin: { enabled: true, autoCreate: true },
+        btree_gist: { enabled: true, autoCreate: true },
+        fuzzystrmatch: { enabled: true, autoCreate: true },
+        intarray: { enabled: true, autoCreate: true },
+        ltree: { enabled: true, autoCreate: true },
+        tablefunc: { enabled: true, autoCreate: true },
+        unaccent: { enabled: true, autoCreate: true },
+    }),
+};
+/**
+ * Helper to check if an extension is enabled in config
+ */
+export function isExtensionEnabled(config, name) {
+    const value = config.extensions?.[name];
+    if (value === undefined)
+        return false;
+    if (typeof value === 'boolean')
+        return value;
+    return value.enabled;
+}
+/**
+ * Helper to check if an extension should be auto-created
+ */
+export function shouldAutoCreate(config, name) {
+    const value = config.extensions?.[name];
+    if (value === undefined)
+        return false;
+    if (typeof value === 'boolean')
+        return false;
+    return value.autoCreate ?? false;
+}
+/**
+ * Get list of enabled extension names from config
+ */
+export function getEnabledExtensions(config) {
+    if (!config.extensions)
+        return [];
+    return Object.entries(config.extensions)
+        .filter(([_, value]) => {
+        if (typeof value === 'boolean')
+            return value;
+        return value.enabled;
+    })
+        .map(([name]) => name);
+}
+/**
+ * Get list of extension names that should be auto-created
+ */
+export function getAutoCreateExtensions(config) {
+    if (!config.extensions)
+        return [];
+    return Object.entries(config.extensions)
+        .filter(([_, value]) => {
+        if (typeof value === 'boolean')
+            return false;
+        return value.enabled && value.autoCreate;
+    })
+        .map(([name]) => name);
+}
+//# sourceMappingURL=config.js.map

package/dist/extensions/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/extensions/config.ts"],"names":[],"mappings":"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"}

package/dist/extensions/geo.d.ts

@@ -0,0 +1,452 @@
+/**
+ * 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';
+/**
+ * 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;
+}
+/** Earth radius in meters (used by earthdistance extension) */
+export declare const EARTH_RADIUS_METERS = 6371000;
+/** Earth radius in kilometers */
+export declare const EARTH_RADIUS_KM = 6371;
+/** Earth radius in miles */
+export declare const EARTH_RADIUS_MILES = 3958.8;
+/** Earth radius in nautical miles */
+export declare const EARTH_RADIUS_NM = 3440.065;
+/**
+ * Conversion factors to meters
+ */
+export declare const DISTANCE_TO_METERS: Record<DistanceUnit, number>;
+/**
+ * Geospatial Extension utilities for PostgreSQL
+ *
+ * Provides SQL generation helpers for earthdistance/cube extensions
+ * and PostgreSQL's native geometric types.
+ */
+export declare const GeoExtension: {
+    name: "geo";
+    displayName: "Geospatial";
+    description: string;
+    /**
+     * Get the extension definitions required for geospatial support
+     */
+    getDefinitions(): ExtensionDefinition[];
+    /**
+     * Generate SQL to create the required extensions
+     * Note: cube must be created before earthdistance
+     */
+    createExtensionsSQL(): string;
+    /**
+     * Generate SQL to create a table with location columns
+     */
+    createLocationTableSQL(tableName: string, options?: LocationTableOptions): string;
+    /**
+     * 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, options?: RadiusSearchOptions): string;
+    /**
+     * 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;
+    /**
+     * Generate SQL to calculate distance between two points
+     */
+    distanceSQL(point1: GeoPoint, point2: GeoPoint, unit?: DistanceUnit): string;
+    /**
+     * Generate SQL expression for distance calculation (for use in queries)
+     */
+    distanceExpression(latColumn: string, lngColumn: string, center: GeoPoint, unit?: DistanceUnit): string;
+    /**
+     * 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;
+    /**
+     * 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): BoundingBox;
+};
+/**
+ * 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 declare const PostgresGeoTypes: {
+    /**
+     * SQL to create a table with native PostgreSQL point column
+     */
+    createPointTableSQL(tableName: string, pointColumn?: string): string;
+    /**
+     * SQL to create a table with native PostgreSQL box column
+     */
+    createBoxTableSQL(tableName: string, boxColumn?: string): string;
+    /**
+     * 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;
+    /**
+     * SQL to find points within a circle using native PostgreSQL operators
+     */
+    pointsWithinCircleSQL(tableName: string, pointColumn: string, center: Point, radius: number): string;
+    /**
+     * SQL to calculate distance between two native PostgreSQL points
+     */
+    pointDistanceSQL(point1: Point, point2: Point): string;
+    /**
+     * SQL expression for point distance (for use in queries)
+     */
+    pointDistanceExpression(pointColumn: string, target: Point): string;
+};
+/**
+ * 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 declare function parsePoint(value: string): Point | null;
+/**
+ * Serialize a Point to PostgreSQL point string
+ *
+ * @param point Point object
+ * @returns PostgreSQL point string like "(x,y)"
+ */
+export declare function serializePoint(point: Point): string;
+/**
+ * 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 declare function parseGeoPoint(value: string): GeoPoint | null;
+/**
+ * Serialize a GeoPoint to PostgreSQL point string
+ *
+ * Note: PostgreSQL points are (x, y) where x = longitude, y = latitude
+ */
+export declare function serializeGeoPoint(geoPoint: GeoPoint): string;
+/**
+ * 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 declare function parseBox(value: string): Box | null;
+/**
+ * Serialize a Box to PostgreSQL box string
+ */
+export declare function serializeBox(box: Box): string;
+/**
+ * Parse a PostgreSQL polygon string to a Polygon object (as GeoPoints)
+ *
+ * @param value PostgreSQL polygon string like "((x1,y1),(x2,y2),(x3,y3))"
+ */
+export declare function parsePolygon(value: string): Polygon | null;
+/**
+ * Serialize a Polygon to PostgreSQL polygon string
+ */
+export declare function serializePolygon(polygon: Polygon): string;
+/**
+ * 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 declare function haversineDistance(point1: GeoPoint, point2: GeoPoint, unit?: DistanceUnit): number;
+/**
+ * Check if a point is within a bounding box
+ */
+export declare function isPointInBoundingBox(point: GeoPoint, bounds: BoundingBox): boolean;
+/**
+ * Check if a point is within a radius of another point
+ */
+export declare function isPointWithinRadius(point: GeoPoint, center: GeoPoint, radius: number, unit?: DistanceUnit): boolean;
+declare const _default: {
+    GeoExtension: {
+        name: "geo";
+        displayName: "Geospatial";
+        description: string;
+        /**
+         * Get the extension definitions required for geospatial support
+         */
+        getDefinitions(): ExtensionDefinition[];
+        /**
+         * Generate SQL to create the required extensions
+         * Note: cube must be created before earthdistance
+         */
+        createExtensionsSQL(): string;
+        /**
+         * Generate SQL to create a table with location columns
+         */
+        createLocationTableSQL(tableName: string, options?: LocationTableOptions): string;
+        /**
+         * 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, options?: RadiusSearchOptions): string;
+        /**
+         * 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;
+        /**
+         * Generate SQL to calculate distance between two points
+         */
+        distanceSQL(point1: GeoPoint, point2: GeoPoint, unit?: DistanceUnit): string;
+        /**
+         * Generate SQL expression for distance calculation (for use in queries)
+         */
+        distanceExpression(latColumn: string, lngColumn: string, center: GeoPoint, unit?: DistanceUnit): string;
+        /**
+         * 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;
+        /**
+         * 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): BoundingBox;
+    };
+    PostgresGeoTypes: {
+        /**
+         * SQL to create a table with native PostgreSQL point column
+         */
+        createPointTableSQL(tableName: string, pointColumn?: string): string;
+        /**
+         * SQL to create a table with native PostgreSQL box column
+         */
+        createBoxTableSQL(tableName: string, boxColumn?: string): string;
+        /**
+         * 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;
+        /**
+         * SQL to find points within a circle using native PostgreSQL operators
+         */
+        pointsWithinCircleSQL(tableName: string, pointColumn: string, center: Point, radius: number): string;
+        /**
+         * SQL to calculate distance between two native PostgreSQL points
+         */
+        pointDistanceSQL(point1: Point, point2: Point): string;
+        /**
+         * SQL expression for point distance (for use in queries)
+         */
+        pointDistanceExpression(pointColumn: string, target: Point): string;
+    };
+    EARTH_RADIUS_METERS: number;
+    EARTH_RADIUS_KM: number;
+    EARTH_RADIUS_MILES: number;
+    EARTH_RADIUS_NM: number;
+    DISTANCE_TO_METERS: Record<DistanceUnit, number>;
+    parsePoint: typeof parsePoint;
+    serializePoint: typeof serializePoint;
+    parseGeoPoint: typeof parseGeoPoint;
+    serializeGeoPoint: typeof serializeGeoPoint;
+    parseBox: typeof parseBox;
+    serializeBox: typeof serializeBox;
+    parsePolygon: typeof parsePolygon;
+    serializePolygon: typeof serializePolygon;
+    haversineDistance: typeof haversineDistance;
+    isPointInBoundingBox: typeof isPointInBoundingBox;
+    isPointWithinRadius: typeof isPointWithinRadius;
+};
+export default _default;
+//# sourceMappingURL=geo.d.ts.map

package/dist/extensions/geo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geo.d.ts","sourceRoot":"","sources":["../../src/extensions/geo.ts"],"names":[],"mappings":"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"}