Skip to content

Latest commit

 

History

History
413 lines (312 loc) · 10.8 KB

README.md

File metadata and controls

413 lines (312 loc) · 10.8 KB
Raw

PostGIS for Node.js

This Node.js class provides methods for interacting with a PostgreSQL/PostGIS database. It abstracts common spatial operations and queries, allowing you to easily perform spatial operations on your PostGIS-enabled PostgreSQL database.

Table of Contents

Installation

  1. Install the required packages using npm:

    npm install pg

  2. Install the postgis package:

    npm install postgis

Usage

To use the Postgis class, first initialize it with a PostgreSQL client instance from the pg package:

const { Client } = require('pg');
const Postgis = require('postgis');

const client = new Client({
    connectionString: 'your_connection_string'
});

client.connect();

const postgis = new Postgis(client);

// Example usage
async function run() {
    try {
        const tables = await postgis.list_tables({ filter: 'table_type = \'BASE TABLE\'' });
        console.log('Tables:', tables);

        const columns = await postgis.list_columns('your_table');
        console.log('Columns:', columns);

        const features = await postgis.query_table('your_table', {
            columns: 'name, geom',
            filter: `"column_name" = 'value'`,
            sort: 'name ASC',
            limit: 50
        });
        console.log('Features:', features);
    } catch (err) {
        console.error('Error:', err);
    } finally {
        await client.end();
    }
}

run();

API Reference

list_tables(options)

Lists all tables in the database. Optionally, you can filter by schema or other parameters.

Parameters:

  • options (optional): JSON object with the following properties:
    • filter (optional): A SQL WHERE clause filter.

Returns: A list of tables with their metadata.

Example:

const tables = await postgis.list_tables({ filter: 'table_type = \'BASE TABLE\'' });

list_columns(table)

Lists all columns in a given table.

Parameters:

  • table: The name of the table.

Returns: A list of columns in the table.

Example:

const columns = await postgis.list_columns('your_table');

query_table(table, options)

Queries a table with optional parameters for columns, filtering, grouping, sorting, and limiting the results.

Parameters:

  • table: The name of the table.
  • options (optional): JSON object with the following properties:
    • columns (optional): Columns to retrieve, defaults to '*'.
    • filter (optional): A SQL WHERE clause filter.
    • group (optional): Columns to group by.
    • sort (optional): Sorting order.
    • limit (optional): Limit the number of results, defaults to 100.

Returns: A list of rows from the query.

Example:

const features = await postgis.query_table('your_table', {
    columns: 'name, geom',
    filter: `"column_name" = 'value'`,
    sort: 'name ASC',
    limit: 50
});

bbox(table, options)

Calculates the bounding box (extent) for a given table based on a specified geometry column.

Parameters:

  • table: The name of the table.
  • options (optional): JSON object with the following properties:
    • geom_column (optional): The geometry column, defaults to 'geom'.
    • srid (optional): The SRID for the bounding box, defaults to 4326.
    • filter (optional): A SQL WHERE clause filter.

Returns: An object representing the bounding box with coordinates.

Example:

const bbox = await postgis.bbox('your_table', {
    geom_column: 'geom',
    srid: 4326,
    filter: `"some_column" = 'some_value'`
});

centroid(table, options)

Calculates the centroid of geometries in a given table.

Parameters:

  • table: The name of the table.
  • options (optional): JSON object with the following properties:
    • force_on_surface (optional): Whether to force the centroid to be on the surface, defaults to false.
    • geom_column (optional): The geometry column, defaults to 'geom'.
    • srid (optional): The SRID, defaults to '4326'.
    • filter (optional): A SQL WHERE clause filter.

Returns: A list of centroids.

Example:

const centroids = await postgis.centroid('your_table', {
    force_on_surface: true,
    geom_column: 'geom',
    srid: 4326,
    filter: `"column_name" = 'value'`
});

intersect_feature(table_from, table_to, options)

Finds intersections between features in two tables.

Parameters:

  • table_from: The first table.
  • table_to: The second table.
  • options (optional): JSON object with the following properties:
    • columns (optional): Columns to retrieve, defaults to '*'.
    • distance (optional): Distance for the intersection, defaults to '0'.
    • geom_column_from (optional): The geometry column for the first table, defaults to 'geom'.
    • geom_column_to (optional): The geometry column for the second table, defaults to 'geom'.
    • filter (optional): A SQL WHERE clause filter.
    • sort (optional): Sorting order.
    • limit (optional): Limit the number of results.

Returns: A list of intersecting features.

Example:

const intersections = await postgis.intersect_feature('table1', 'table2', {
    columns: 'name, geom',
    distance: '10',
    filter: `"some_column" = 'some_value'`,
    sort: 'name ASC',
    limit: 50
});

intersect_point(table, point, options)

Finds features in a table that intersect with a given point.

Parameters:

  • table: The name of the table.
  • point: The point to intersect with.
  • options (optional): JSON object with the following properties:
    • columns (optional): Columns to retrieve, defaults to '*'.
    • distance (optional): Distance for the intersection, defaults to '0'.
    • geom_column (optional): The geometry column, defaults to 'geom'.
    • filter (optional): A SQL WHERE clause filter.
    • sort (optional): Sorting order.
    • limit (optional): Limit the number of results.

Returns: A list of features intersecting with the point.

Example:

const features = await postgis.intersect_point('your_table', '1,1,4326', {
    columns: 'name, geom',
    distance: '5',
    filter: `"some_column" = 'some_value'`,
    sort: 'name ASC',
    limit: 10
});

geojson(table, options)

Converts features from a table to GeoJSON format.

Parameters:

  • table: The name of the table.
  • options (optional): JSON object with the following properties:
    • bounds (optional): Bounding box for the results.
    • id_column (optional): Column to use as the feature ID.
    • precision (optional): Precision for coordinates, defaults to 9.
    • geom_column (optional): The geometry column, defaults to 'geom'.
    • columns (optional): Columns to retrieve.
    • filter (optional): A SQL WHERE clause filter.

Returns: A GeoJSON FeatureCollection.

Example:

const geojson = await postgis.geojson('your_table', {
    bounds: 'xmin ymin, xmax ymax',
    id_column: 'id',
    precision: 6,
    geom_column: 'geom',
    columns: 'name, geom',
    filter: `"some_column" = 'some_value'`
});

geobuf(table, options)

Converts features from a table to Geobuf format.

Parameters:

  • table: The name of the table.
  • options (optional): JSON object with the following properties:
    • bounds (optional): Bounding box for the results.
    • geom_column (optional): The geometry column, defaults to 'geom'.
    • columns (optional): Columns to retrieve.
    • filter (optional): A SQL WHERE clause filter.

Returns: A Geobuf binary encoded string.

Example:

const geobuf = await postgis.geobuf('your_table', {
    bounds: 'xmin ymin, xmax ymax',
    geom_column: 'geom',
    columns: 'name, geom',
    filter: `"some_column" = 'some_value'`
});

mvt(table, x, y, z, options)

Generates a Mapbox Vector Tile (MVT) for a given tile coordinate.

Parameters:

  • table: The name of the table.
  • x: The x-coordinate of the tile.
  • y: The y-coordinate of the tile.
  • z: The zoom level.
  • options (optional): JSON object with the following properties:
    • columns (optional): Columns to retrieve.
    • id_column (optional): Column to use as the feature ID.
    • geom_column (optional): The geometry column, defaults to 'geom'.
    • filter (optional): A SQL WHERE clause filter.

Returns: A Mapbox Vector Tile.

Example:

const mvt = await postgis.mvt('your_table', 1, 2, 3, {
    columns: 'name, geom',
    id_column: 'id',
    filter: `"some_column" = 'some_value'`
});

nearest(table, point, options)

Finds the nearest features to a given point.

Parameters:

  • table: The name of the table.
  • point: The point to find the nearest features to.
  • options (optional): JSON object with the following properties:
    • columns (optional): Columns to retrieve, defaults to '*'.
    • geom_column (optional): The geometry column, defaults to 'geom'.
    • filter (optional): A SQL WHERE clause filter.
    • limit (optional): Limit the number of results, defaults to 10.

Returns: A list of the nearest features.

Example:

const nearest = await postgis.nearest('your_table', '1,1,4326', {
    columns: 'name, geom',
    filter: `"some_column" = 'some_value'`,
    limit: 5
});

transform_point(point, options)

Transforms a point from one SRID to another.

Parameters:

  • point: The point to transform.
  • options (optional): JSON object with the following properties:
    • srid (optional): The target SRID, defaults to 4326.

Returns: The transformed point.

Example:

const transformed = await postgis.transform_point('1,1,4326', { srid: 3857 });

Error Handling

All methods throw an error if the query execution fails. Ensure proper error handling in your application to manage these errors.

try {
    const result = await postgis.someMethod();
    console.log(result);
} catch (err) {
    console.error('Error:', err);
}

Version Compatibility

  • PostgreSQL: Compatible with PostgreSQL 12 and higher.
  • PostGIS: Compatible with PostGIS 3.0 and higher.
  • Node.js: Compatible with Node.js 14.x and higher.
  • pg (node-postgres): Version 8.x and higher.

Testing

If you create a pull request, tests better pass :)

npm install
npm test

License

This project is licensed under the MIT License. See the LICENSE file for details.