@tmlmobilidade/go-interfaces-locationsdb 20261001.1824.22

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './interface.js';
+export * from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './interface.js';
+export * from './types.js';

package/dist/interface.d.ts

@@ -0,0 +1,40 @@
+import { type QueryResult, type QueryResultRow } from '@tmlmobilidade/go-clients-postgres';
+import { CountryCode, type Location, type LocationWithGeojson } from './types.js';
+declare class LocationsDbClass {
+    private static _instance;
+    private readonly postgresClient;
+    private constructor();
+    /**
+     * Establishes a connection to the PostGIS / PostgreSQL database.
+     * @throws Error if required LOCATIONSDB_* environment variables are missing or if the connection fails.
+     */
+    static getInstance(): Promise<LocationsDbClass>;
+    /**
+     * Finds the administrative locations whose geometry covers a WGS84 point (typically country,
+     * district, municipality, parish), plus the nearest `place=locality` point within the given
+     * radius, returned with `admin_level = "neighbourhood"`.
+     * @param localityMaxDistanceMeters Search radius for the locality point.
+     */
+    findLocationsAtPoint(longitude: number, latitude: number, localityMaxDistanceMeters: number): Promise<Location[]>;
+    /**
+     * Lists locations for a given OSM admin_level inside a country, sorted by name, without geometry.
+     * @param countryCode ISO 3166-1 alpha-2 country code.
+     * @param adminLevel OSM admin_level (e.g. `"7"` for Portuguese municipalities).
+     */
+    findLocationsByCountryAndAdminLevel(countryCode: CountryCode, adminLevel: number | string): Promise<Location[]>;
+    /**
+     * Lists locations for a given OSM admin_level inside a country, including GeoJSON geometry.
+     * @param countryCode ISO 3166-1 alpha-2 country code.
+     * @param adminLevel OSM admin_level (e.g. `"7"` for Portuguese municipalities).
+     */
+    findLocationsWithGeojsonByCountryAndAdminLevel(countryCode: CountryCode, adminLevel: number | string): Promise<LocationWithGeojson[]>;
+    /**
+     * Executes a SQL query against the locations database.
+     * @param text The SQL query text (supports `$1`, `$2`, … placeholders).
+     * @param params Optional positional query parameters.
+     * @returns The query result rows typed as `T`.
+     */
+    query<T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]): Promise<QueryResult<T>>;
+}
+export declare const locationsDb: LocationsDbClass;
+export {};

package/dist/interface.js

@@ -0,0 +1,63 @@
+/* * */
+import { PostgresDatabaseClient } from '@tmlmobilidade/go-clients-postgres';
+import { asyncSingletonProxy } from '@tmlmobilidade/go-utils-exec';
+import { FIND_LOCATIONS_AT_POINT, FIND_LOCATIONS_BY_COUNTRY_AND_ADMIN_LEVEL, FIND_LOCATIONS_WITH_GEOJSON_BY_COUNTRY_AND_ADMIN_LEVEL } from './queries.js';
+/* * */
+class LocationsDbClass {
+    //
+    static _instance;
+    postgresClient;
+    constructor(postgresClient) {
+        this.postgresClient = postgresClient;
+    }
+    /**
+     * Establishes a connection to the PostGIS / PostgreSQL database.
+     * @throws Error if required LOCATIONSDB_* environment variables are missing or if the connection fails.
+     */
+    static async getInstance() {
+        if (!LocationsDbClass._instance) {
+            const postgresClient = await PostgresDatabaseClient.getClient({ prefix: 'LOCATIONSDB', tunnelType: 'GO' });
+            LocationsDbClass._instance = new LocationsDbClass(postgresClient);
+        }
+        return LocationsDbClass._instance;
+    }
+    /**
+     * Finds the administrative locations whose geometry covers a WGS84 point (typically country,
+     * district, municipality, parish), plus the nearest `place=locality` point within the given
+     * radius, returned with `admin_level = "neighbourhood"`.
+     * @param localityMaxDistanceMeters Search radius for the locality point.
+     */
+    async findLocationsAtPoint(longitude, latitude, localityMaxDistanceMeters) {
+        const result = await this.postgresClient.query(FIND_LOCATIONS_AT_POINT, [longitude, latitude, localityMaxDistanceMeters]);
+        return result.rows;
+    }
+    /**
+     * Lists locations for a given OSM admin_level inside a country, sorted by name, without geometry.
+     * @param countryCode ISO 3166-1 alpha-2 country code.
+     * @param adminLevel OSM admin_level (e.g. `"7"` for Portuguese municipalities).
+     */
+    async findLocationsByCountryAndAdminLevel(countryCode, adminLevel) {
+        const result = await this.postgresClient.query(FIND_LOCATIONS_BY_COUNTRY_AND_ADMIN_LEVEL, [String(adminLevel), countryCode]);
+        return result.rows;
+    }
+    /**
+     * Lists locations for a given OSM admin_level inside a country, including GeoJSON geometry.
+     * @param countryCode ISO 3166-1 alpha-2 country code.
+     * @param adminLevel OSM admin_level (e.g. `"7"` for Portuguese municipalities).
+     */
+    async findLocationsWithGeojsonByCountryAndAdminLevel(countryCode, adminLevel) {
+        const result = await this.postgresClient.query(FIND_LOCATIONS_WITH_GEOJSON_BY_COUNTRY_AND_ADMIN_LEVEL, [String(adminLevel), countryCode]);
+        return result.rows;
+    }
+    /**
+     * Executes a SQL query against the locations database.
+     * @param text The SQL query text (supports `$1`, `$2`, … placeholders).
+     * @param params Optional positional query parameters.
+     * @returns The query result rows typed as `T`.
+     */
+    async query(text, params) {
+        return await this.postgresClient.query(text, params);
+    }
+}
+/* * */
+export const locationsDb = asyncSingletonProxy(LocationsDbClass);

package/dist/queries.d.ts

@@ -0,0 +1,13 @@
+/** List locations at a given admin_level ($1) inside a country ($2), without geometry. */
+export declare const FIND_LOCATIONS_BY_COUNTRY_AND_ADMIN_LEVEL = "\nSELECT\n\tabs(p.osm_id) AS id,\n\tCOALESCE(p.tags->>'int_name', p.name) AS name,\n\tp.admin_level,\n\tp.tags->>'ref:ine' AS code,\n\tp.tags\nFROM planet_osm_polygon p\nWHERE p.boundary = 'administrative'\n\tAND p.admin_level = $1\n\tAND p.way && (\n\tSELECT c.way\n\tFROM planet_osm_polygon c\n\tWHERE c.boundary = 'administrative'\n\t\tAND c.admin_level = '2'\n\t\tAND c.tags->>'ISO3166-1' = $2\n\tLIMIT 1\n)\n\tAND ST_Within(p.way, (\n\tSELECT c.way\n\tFROM planet_osm_polygon c\n\tWHERE c.boundary = 'administrative'\n\t\tAND c.admin_level = '2'\n\t\tAND c.tags->>'ISO3166-1' = $2\n\tLIMIT 1\n))\nORDER BY name;\n";
+/** List locations at a given admin_level ($1) inside a country ($2), with GeoJSON geometry. */
+export declare const FIND_LOCATIONS_WITH_GEOJSON_BY_COUNTRY_AND_ADMIN_LEVEL = "\nSELECT\n\tabs(p.osm_id) AS id,\n\tCOALESCE(p.tags->>'int_name', p.name) AS name,\n\tp.admin_level,\n\tp.tags->>'ref:ine' AS code,\n\tp.tags,\n\tjson_build_object(\n\t\t'type', 'FeatureCollection',\n\t\t'features', json_agg(\n\t\t\tjson_build_object(\n\t\t\t\t'type', 'Feature',\n\t\t\t\t'id', abs(osm_id),\n\t\t\t\t'properties', json_build_object(\n\t\t\t\t\t'name', name,\n\t\t\t\t\t'admin_level', admin_level,\n\t\t\t\t\t'code', tags->>'ref:ine',\n\t\t\t\t\t'tags', tags\n\t\t\t\t),\n\t\t\t\t'geometry', ST_AsGeoJSON(\n\t\t\t\t\tST_Transform(way, 4326)\n\t\t\t\t)::json\n\t\t\t)\n\t\t)\n\t) AS geojson\nFROM planet_osm_polygon p\nWHERE p.boundary = 'administrative'\n\tAND p.admin_level = $1\n\tAND p.way && (\n\tSELECT c.way\n\tFROM planet_osm_polygon c\n\tWHERE c.boundary = 'administrative'\n\t\tAND c.admin_level = '2'\n\t\tAND c.tags->>'ISO3166-1' = $2\n\tLIMIT 1\n)\n\tAND ST_Within(p.way, (\n\tSELECT c.way\n\tFROM planet_osm_polygon c\n\tWHERE c.boundary = 'administrative'\n\t\tAND c.admin_level = '2'\n\t\tAND c.tags->>'ISO3166-1' = $2\n\tLIMIT 1\n))\nGROUP BY id, name, admin_level, code, tags;\n";
+/**
+ * Find the administrative locations that cover a WGS84 point ($1 lon, $2 lat), plus the nearest
+ * `place=locality` point within $3 metres (returned with `admin_level = 'neighbourhood'`), in one round-trip.
+ * `way` is WGS84 geometry (SRID 4326). Prefilter neighbourhoods with the geometry index
+ * before applying the exact geography distance. The conservative degree radius uses less
+ * than the minimum metres per latitude degree and the most extreme latitude in the cap.
+ * Caps crossing the antimeridian or a pole use worldwide bounds to avoid dropping matches.
+ */
+export declare const FIND_LOCATIONS_AT_POINT = "\nWITH point AS (\n\tSELECT ST_SetSRID(ST_MakePoint($1, $2), 4326) AS way,\n\t\t$3::double precision / (\n\t\t\t100000 * GREATEST(cos(radians(LEAST(90, abs($2) + $3::double precision / 100000))), 0.000001)\n\t\t) AS degree_radius\n), pt AS (\n\tSELECT way,\n\t\tCASE WHEN abs($1) + degree_radius >= 180 OR abs($2) + degree_radius >= 90\n\t\t\tTHEN ST_MakeEnvelope(-180, -90, 180, 90, 4326)\n\t\t\tELSE ST_Expand(way, degree_radius)\n\t\tEND AS bounds\n\tFROM point\n)\nSELECT\n\tabs(p.osm_id) AS id,\n\tCOALESCE(p.tags->>'int_name', p.name) AS name,\n\tp.admin_level,\n\tp.tags->>'ref:ine' AS code,\n\tp.tags\nFROM planet_osm_polygon p, pt\nWHERE p.boundary = 'administrative'\n\tAND ST_Covers(p.way, pt.way)\nUNION ALL\n(\n\tSELECT\n\t\tabs(p.osm_id),\n\t\tCOALESCE(p.tags->>'int_name', p.name),\n\t\t'neighbourhood',\n\t\tNULL,\n\t\tp.tags\n\tFROM planet_osm_point p, pt\n\tWHERE p.place = 'neighbourhood'\n\t\tAND p.name IS NOT NULL\n\t\tAND p.way && pt.bounds\n\t\tAND ST_DWithin(p.way::geography, pt.way::geography, $3)\n\tORDER BY p.way::geography <-> pt.way::geography\n\tLIMIT 1\n);\n";

package/dist/queries.js

@@ -0,0 +1,106 @@
+/* * */
+/** The admin_level 2 polygon of a country, by ISO 3166-1 alpha-2 code ($2). */
+const COUNTRY_WAY = `
+	SELECT c.way
+	FROM planet_osm_polygon c
+	WHERE c.boundary = 'administrative'
+		AND c.admin_level = '2'
+		AND c.tags->>'ISO3166-1' = $2
+	LIMIT 1
+`;
+/** List locations at a given admin_level ($1) inside a country ($2), without geometry. */
+export const FIND_LOCATIONS_BY_COUNTRY_AND_ADMIN_LEVEL = `
+SELECT
+	abs(p.osm_id) AS id,
+	COALESCE(p.tags->>'int_name', p.name) AS name,
+	p.admin_level,
+	p.tags->>'ref:ine' AS code,
+	p.tags
+FROM planet_osm_polygon p
+WHERE p.boundary = 'administrative'
+	AND p.admin_level = $1
+	AND p.way && (${COUNTRY_WAY})
+	AND ST_Within(p.way, (${COUNTRY_WAY}))
+ORDER BY name;
+`;
+/** List locations at a given admin_level ($1) inside a country ($2), with GeoJSON geometry. */
+export const FIND_LOCATIONS_WITH_GEOJSON_BY_COUNTRY_AND_ADMIN_LEVEL = `
+SELECT
+	abs(p.osm_id) AS id,
+	COALESCE(p.tags->>'int_name', p.name) AS name,
+	p.admin_level,
+	p.tags->>'ref:ine' AS code,
+	p.tags,
+	json_build_object(
+		'type', 'FeatureCollection',
+		'features', json_agg(
+			json_build_object(
+				'type', 'Feature',
+				'id', abs(osm_id),
+				'properties', json_build_object(
+					'name', name,
+					'admin_level', admin_level,
+					'code', tags->>'ref:ine',
+					'tags', tags
+				),
+				'geometry', ST_AsGeoJSON(
+					ST_Transform(way, 4326)
+				)::json
+			)
+		)
+	) AS geojson
+FROM planet_osm_polygon p
+WHERE p.boundary = 'administrative'
+	AND p.admin_level = $1
+	AND p.way && (${COUNTRY_WAY})
+	AND ST_Within(p.way, (${COUNTRY_WAY}))
+GROUP BY id, name, admin_level, code, tags;
+`;
+/**
+ * Find the administrative locations that cover a WGS84 point ($1 lon, $2 lat), plus the nearest
+ * `place=locality` point within $3 metres (returned with `admin_level = 'neighbourhood'`), in one round-trip.
+ * `way` is WGS84 geometry (SRID 4326). Prefilter neighbourhoods with the geometry index
+ * before applying the exact geography distance. The conservative degree radius uses less
+ * than the minimum metres per latitude degree and the most extreme latitude in the cap.
+ * Caps crossing the antimeridian or a pole use worldwide bounds to avoid dropping matches.
+ */
+export const FIND_LOCATIONS_AT_POINT = `
+WITH point AS (
+	SELECT ST_SetSRID(ST_MakePoint($1, $2), 4326) AS way,
+		$3::double precision / (
+			100000 * GREATEST(cos(radians(LEAST(90, abs($2) + $3::double precision / 100000))), 0.000001)
+		) AS degree_radius
+), pt AS (
+	SELECT way,
+		CASE WHEN abs($1) + degree_radius >= 180 OR abs($2) + degree_radius >= 90
+			THEN ST_MakeEnvelope(-180, -90, 180, 90, 4326)
+			ELSE ST_Expand(way, degree_radius)
+		END AS bounds
+	FROM point
+)
+SELECT
+	abs(p.osm_id) AS id,
+	COALESCE(p.tags->>'int_name', p.name) AS name,
+	p.admin_level,
+	p.tags->>'ref:ine' AS code,
+	p.tags
+FROM planet_osm_polygon p, pt
+WHERE p.boundary = 'administrative'
+	AND ST_Covers(p.way, pt.way)
+UNION ALL
+(
+	SELECT
+		abs(p.osm_id),
+		COALESCE(p.tags->>'int_name', p.name),
+		'neighbourhood',
+		NULL,
+		p.tags
+	FROM planet_osm_point p, pt
+	WHERE p.place = 'neighbourhood'
+		AND p.name IS NOT NULL
+		AND p.way && pt.bounds
+		AND ST_DWithin(p.way::geography, pt.way::geography, $3)
+	ORDER BY p.way::geography <-> pt.way::geography
+	LIMIT 1
+);
+`;

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+import { type FeatureCollection, type Geometry } from 'geojson';
+/** OSM tag bag stored as jsonb on planet_osm_polygon. */
+export type OsmTags = Record<string, string>;
+/** Properties embedded in each GeoJSON Feature of a location. */
+export interface LocationProperties {
+    admin_level: null | string;
+    code: null | string;
+    name: null | string;
+    tags: OsmTags;
+}
+/** Location row from planet_osm_polygon. */
+export interface Location extends LocationProperties {
+    id: string;
+}
+/** Location row including a GeoJSON FeatureCollection of its geometry. */
+export interface LocationWithGeojson extends Location {
+    geojson: FeatureCollection<Geometry, LocationProperties>;
+}
+/** ISO 3166-1 alpha-2 country code. */
+export type CountryCode = 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AN' | 'AO' | 'AQ' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BN' | 'BO' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VC' | 'VC' | 'VE' | 'VE' | 'VG' | 'VI' | 'VN' | 'VN' | 'VU' | 'WF' | 'WS' | 'XK' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW';

package/dist/types.js

@@ -0,0 +1,2 @@
+/* * */
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@tmlmobilidade/go-interfaces-locationsdb",
+	"version": "20261001.1824.22",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://go.tmlmobilidade.pt",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"go"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src/ && tsc --noEmit",
+		"lint:fix": "eslint ./src/ --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"dependencies": {
+		"@tmlmobilidade/go-clients-postgres": "*",
+		"@tmlmobilidade/go-utils-exec": "*"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/go-utils-tsconfig": "*",
+		"@types/geojson": "7946.0.16",
+		"@types/node": "26.4.0",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.1",
+		"typescript": "6.0.3"
+	}
+}