@nspot/geo-engine 0.3.0 → 0.4.0

package/README.md

@@ -120,6 +120,23 @@ from request input — use a literal, or pick from a fixed list in your own code
 additionally checked against a plain-identifier pattern and rejected with
 `GeoEngineError("invalid_input", …)` when it is anything else.
 
+**6. Fit a map to regions.**
+
+```ts
+import { regionsBbox } from "@nspot/geo-engine";
+
+const bbox = await regionsBbox(pool, ["bran-bv", "moieciu-bv"], { country: "RO" });
+// [west, south, east, north], or null when no slug names a region
+```
+
+`regionsBbox` gives the box of the union of the named regions, exact to the coordinate, ready
+for a map's `fitBounds`. Unknown slugs among known ones are ignored. Slugs are unique per
+country, not globally, so without `country` a slug two countries share gives the box of both.
+An empty list, or a string in place of the list, is refused with
+`GeoEngineError("invalid_input", …)` before the database is reached. The `Bbox` type also
+comes from `@nspot/geo-engine/types`, which is safe to import in a browser bundle.
+`regionsBbox` needs schema 8 (`@nspot/geo-engine` 0.4.0).
+
 ## CLI
 
 The package ships a `geo-engine` bin (run it with `npx geo-engine …`, `pnpm dlx geo-engine …`,
@@ -155,6 +172,7 @@ database, and `cause` when it wraps something else (a zod `ZodError`, a fetch fa
 | `invalid_input`  | Postgres rejected a value (`22023`) — e.g. a malformed geometry or invalid enum value |
 | `invalid_input`  | `idType` is not a plain SQL type name (`inRegions` / `notInRegions`), raised before any SQL is built |
 | `invalid_input`  | `filter.regions` is empty in `inRegions` / `ids`, raised before the database is touched |
+| `invalid_input`  | `slugs` is empty, or not an array, in `regionsBbox`, raised before the database is touched |
 | `invalid_input`  | `installPack` could not download, read, resolve or JSON-parse the pack (`cause` is the underlying error) |
 | `invalid_input`  | the pack document failed validation — `Invalid pack document: <path>: <issue>; …`, `cause` is the `ZodError` |
 | `invalid_input`  | `migrate` found a database whose schema is newer than the one this package ships   |

package/dist/query.d.ts

@@ -1,5 +1,5 @@
 import type { Queryable } from "./migrate.js";
-import type { RegionSummary } from "./types.js";
+import type { Bbox, RegionSummary } from "./types.js";
 export interface RegionFilter {
     /** Region slugs or numeric ids; at least one. */
     regions: string[];
@@ -41,3 +41,15 @@ export declare function notInRegions(source: string, regions: string[], opts: Fr
 export declare function ids(db: Queryable, source: string, filter: RegionFilter): Promise<string[]>;
 export declare function regionsOf(db: Queryable, source: string, externalId: string | number): Promise<RegionSummary[]>;
 export declare function regionsAt(db: Queryable, lng: number, lat: number): Promise<RegionSummary[]>;
+export interface RegionsBboxOptions {
+    /** A country's ISO code, in either case: match the slugs in that country only. */
+    country?: string;
+}
+/**
+ * The box holding the named regions, for a map that fits its camera to them: [west, south,
+ * east, north] of the union of their envelopes, exact to the coordinate, or null when no slug
+ * names a region. Unknown slugs among known ones are ignored. Slugs are unique per country,
+ * not globally, so without `country` a slug two countries share gives the box of both.
+ * Needs schema 8 (`geo.regions_bbox`).
+ */
+export declare function regionsBbox(db: Queryable, slugs: readonly string[], opts?: RegionsBboxOptions): Promise<Bbox | null>;

package/dist/query.js

@@ -50,3 +50,18 @@ export async function regionsOf(db, source, externalId) {
 export async function regionsAt(db, lng, lat) {
     return run(db, "SELECT id, slug, name, type, level, parent_id, code FROM geo.regions_at_point($1, $2)", [lng, lat]);
 }
+/**
+ * The box holding the named regions, for a map that fits its camera to them: [west, south,
+ * east, north] of the union of their envelopes, exact to the coordinate, or null when no slug
+ * names a region. Unknown slugs among known ones are ignored. Slugs are unique per country,
+ * not globally, so without `country` a slug two countries share gives the box of both.
+ * Needs schema 8 (`geo.regions_bbox`).
+ */
+export async function regionsBbox(db, slugs, opts = {}) {
+    // a string is not a list: iterated, it would name one-letter slugs and answer null
+    if (!Array.isArray(slugs) || slugs.length === 0) {
+        throw new GeoEngineError("invalid_input", "slugs must name at least one region");
+    }
+    const rows = await run(db, "SELECT geo.regions_bbox($1::text[], $2::text) AS b", [slugs, opts.country ?? null]);
+    return rows[0].b;
+}

package/dist/types.d.ts

@@ -22,9 +22,12 @@ export type MultiPolygonGeometry = {
     coordinates: Position[][][];
 };
 export type AreaGeometry = PolygonGeometry | MultiPolygonGeometry;
+/** [west, south, east, north] in degrees: a GeoJSON `bbox` member, and what a map's fitBounds takes. */
+export type Bbox = [west: number, south: number, east: number, north: number];
 export type Feature<G = AreaGeometry, P = Record<string, unknown>> = {
     type: "Feature";
     id?: string | number;
+    bbox?: Bbox;
     geometry: G;
     properties: P;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nspot/geo-engine",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Region membership for your own PostGIS tables: install the geo schema, register tables, install region packs, query by region.",
   "license": "MIT",
   "type": "module",

package/sql/008_regions_bbox.sql

@@ -0,0 +1,24 @@
+-- ============================================================================
+-- 008 — region bounding boxes
+--
+-- geo.regions_bbox(slugs, country) answers "what box holds these regions?" for a
+-- map that fits its camera to them: [west, south, east, north] of the union of
+-- the named regions' envelopes, as jsonb, exact to the coordinate, or NULL when
+-- no slug names a region. Unknown slugs among known ones are ignored. Slugs are
+-- unique per country, not globally: without p_country a slug two countries share
+-- gives the box of both; with it (an ISO code, either case) that country's only.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION geo.regions_bbox(p_slugs text[], p_country text DEFAULT NULL)
+RETURNS jsonb
+LANGUAGE sql STABLE PARALLEL SAFE AS $$
+  SELECT CASE WHEN count(*) = 0 THEN NULL
+         ELSE jsonb_build_array(min(ST_XMin(r.geom)), min(ST_YMin(r.geom)), max(ST_XMax(r.geom)), max(ST_YMax(r.geom)))
+         END
+  FROM geo.regions r
+  JOIN geo.countries c ON c.id = r.country_id
+  WHERE r.slug = ANY (p_slugs)
+    AND (p_country IS NULL OR c.code = upper(p_country));
+$$;
+
+SELECT geo.pin_search_path();