@nspot/geo-engine 0.2.1 → 0.4.0

package/README.md

@@ -67,6 +67,15 @@ path. Pass `{ resolveFrom }` to resolve the package name from a directory other
 `process.cwd()`. A pack package must expose `pack.json`; if its `package.json` declares
 an `exports` map, that map must include `"./pack.json"`.
 
+A pack may build on another: a region's `parent` is a slug, found first among the same
+pack's regions and then among any other installed pack's (never among your local regions).
+Links are remade after every install, so packs can be installed in any order, and
+reinstalling a parent pack restores the links its uninstall cut. `exportPack(pool, slug,
+version, { owner, slugPrefix })` exports every region, or only one owner's (`"local"` for
+the regions no pack owns, or a pack's slug) and/or those under a slug prefix; a scoped
+export names only the countries it needs, with no outline, so installing it never
+overwrites one. Both need schema 7 (`@nspot/geo-engine` 0.3.0).
+
 **4. Filter your own query by region.**
 
 ```ts
@@ -111,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 …`,
@@ -146,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/packs.d.ts

@@ -8,7 +8,25 @@ export interface InstallPackOptions {
     /** Directory to resolve a bare package name from; defaults to process.cwd(). */
     resolveFrom?: string;
 }
-export declare function exportPack(db: Queryable, slug: string, version: string): Promise<Pack>;
+export interface ExportPackOptions {
+    /**
+     * Whose regions to export: `"local"` for the regions no pack owns, or an installed pack's
+     * slug for that pack's regions. Omitted, every region is exported.
+     */
+    owner?: string;
+    /** Export only regions whose slug starts with this. */
+    slugPrefix?: string;
+}
+/**
+ * The database's regions as one pack document, named `slug`@`version`.
+ *
+ * Unscoped, it holds every region and every country with its outline. Scoped (`owner` or
+ * `slugPrefix`), it holds the chosen regions and only the countries they and their parents
+ * sit in, with no outline, so installing it never overwrites one. A region's `parent` is its
+ * parent's slug wherever that parent lives; a pack region whose parent is in another pack
+ * gets linked to it when both are installed (schema 7).
+ */
+export declare function exportPack(db: Queryable, slug: string, version: string, opts?: ExportPackOptions): Promise<Pack>;
 /**
  * Install a pack into the database.
  *

package/dist/packs.js

@@ -6,8 +6,22 @@ import { GeoEngineError, run } from "./errors.js";
 import { packSchema } from "./types.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const PACKAGE_NAME_RE = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
-export async function exportPack(db, slug, version) {
-    const rows = await run(db, "SELECT geo.export_pack($1, $2) AS pack", [slug, version]);
+/**
+ * The database's regions as one pack document, named `slug`@`version`.
+ *
+ * Unscoped, it holds every region and every country with its outline. Scoped (`owner` or
+ * `slugPrefix`), it holds the chosen regions and only the countries they and their parents
+ * sit in, with no outline, so installing it never overwrites one. A region's `parent` is its
+ * parent's slug wherever that parent lives; a pack region whose parent is in another pack
+ * gets linked to it when both are installed (schema 7).
+ */
+export async function exportPack(db, slug, version, opts = {}) {
+    const rows = await run(db, "SELECT geo.export_pack($1, $2, $3, $4) AS pack", [
+        slug,
+        version,
+        opts.owner ?? null,
+        opts.slugPrefix ?? null,
+    ]);
     return rows[0].pack;
 }
 /**

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.2.1",
+  "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/007_pack_scope.sql

@@ -0,0 +1,199 @@
+-- ============================================================================
+-- 007 — packs that build on other packs
+--
+-- A pack may name a parent that lives in another pack (a commune pack whose
+-- communes sit in the Romania pack's județ). Every pack region keeps the parent
+-- its pack declared, and the link is made to whichever pack region carries that
+-- slug: the pack's own first (a slug is unique per country, so there is only
+-- one), else another pack's. A local region is never adopted, since a pack
+-- cannot know about it. Links are remade after every install, so the order in
+-- which packs are installed does not matter, and reinstalling a parent pack
+-- restores the links its uninstall cut (ON DELETE SET NULL).
+--
+-- export_pack gains a scope: the regions of one owner (a pack slug, or 'local'
+-- for regions no pack owns) and/or a slug prefix. A scoped pack names only the
+-- countries it needs, with no outline, so installing it never overwrites the
+-- outline another pack or the host set.
+-- ============================================================================
+
+ALTER TABLE geo.regions
+  ADD COLUMN declared_parent         text,
+  ADD COLUMN declared_parent_country text;
+
+COMMENT ON COLUMN geo.regions.declared_parent IS
+  'For a pack region: the parent slug its pack declared, resolved by geo.link_pack_parents()';
+COMMENT ON COLUMN geo.regions.declared_parent_country IS
+  'For a pack region: the country code of its declared parent';
+
+-- Link every pack region to its declared parent among pack regions. Returns how
+-- many links changed.
+CREATE OR REPLACE FUNCTION geo.link_pack_parents() RETURNS int
+LANGUAGE plpgsql AS $$
+DECLARE
+  n int;
+BEGIN
+  UPDATE geo.regions r
+  SET parent_id = par.id
+  FROM geo.countries pc
+  JOIN geo.regions par ON par.country_id = pc.id AND par.pack_id IS NOT NULL
+  WHERE r.pack_id IS NOT NULL
+    AND r.declared_parent IS NOT NULL
+    AND pc.code = r.declared_parent_country
+    AND par.slug = r.declared_parent
+    AND par.id <> r.id
+    AND r.parent_id IS DISTINCT FROM par.id;
+  GET DIAGNOSTICS n = ROW_COUNT;
+  RETURN n;
+END $$;
+
+DROP FUNCTION geo.export_pack(text, text);
+CREATE OR REPLACE FUNCTION geo.export_pack(
+  p_slug        text,
+  p_version     text,
+  p_owner       text DEFAULT NULL,
+  p_slug_prefix text DEFAULT NULL
+) RETURNS jsonb
+LANGUAGE plpgsql STABLE AS $$
+DECLARE
+  owner_id int;
+  scoped   boolean := p_owner IS NOT NULL OR p_slug_prefix IS NOT NULL;
+BEGIN
+  IF p_owner IS NOT NULL AND p_owner <> 'local' THEN
+    SELECT id INTO owner_id FROM geo.packs WHERE slug = p_owner;
+    IF owner_id IS NULL THEN
+      RAISE EXCEPTION 'Unknown pack "%"', p_owner USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+  END IF;
+
+  RETURN (
+    WITH sel AS (
+      SELECT r.*
+      FROM geo.regions r
+      WHERE (p_owner IS NULL
+             OR (p_owner = 'local' AND r.pack_id IS NULL)
+             OR r.pack_id = owner_id)
+        AND (p_slug_prefix IS NULL OR starts_with(r.slug, p_slug_prefix))
+    ),
+    feats AS (
+      SELECT c.code AS country, r.slug, jsonb_build_object(
+        'type', 'Feature',
+        'geometry', ST_AsGeoJSON(r.geom, 6)::jsonb,
+        'properties', jsonb_build_object(
+          'country', c.code, 'slug', r.slug, 'name', r.name, 'type', r.type, 'level', r.level,
+          'parent', coalesce(p.slug, r.declared_parent),
+          'parent_country', CASE WHEN p.id IS NOT NULL THEN pc.code ELSE r.declared_parent_country END,
+          'code', r.code, 'tags', to_jsonb(r.tags), 'properties', r.properties)) AS feature,
+        coalesce(pc.code, r.declared_parent_country) AS parent_country
+      FROM sel r
+      JOIN geo.countries c ON c.id = r.country_id
+      LEFT JOIN geo.regions p ON p.id = r.parent_id
+      LEFT JOIN geo.countries pc ON pc.id = p.country_id
+    ),
+    needed AS (
+      SELECT country AS code FROM feats
+      UNION
+      SELECT parent_country FROM feats WHERE parent_country IS NOT NULL
+    )
+    SELECT jsonb_build_object(
+      'pack', jsonb_build_object(
+        'slug', p_slug, 'version', p_version, 'schema_version', geo.schema_version(),
+        'published_at', to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')),
+      'countries', coalesce((
+        SELECT jsonb_agg(jsonb_build_object(
+          'code', c.code, 'name', c.name,
+          'geometry', CASE WHEN scoped OR c.geom IS NULL THEN NULL ELSE ST_AsGeoJSON(c.geom, 6)::jsonb END
+        ) ORDER BY c.code)
+        FROM geo.countries c
+        WHERE NOT scoped OR c.code IN (SELECT code FROM needed)), '[]'::jsonb),
+      'regions', jsonb_build_object(
+        'type', 'FeatureCollection',
+        'features', coalesce((SELECT jsonb_agg(feature ORDER BY country, slug) FROM feats), '[]'::jsonb)))
+  );
+END $$;
+
+-- install_pack as in 005, except that it records each region's declared parent
+-- and links parents across packs.
+CREATE OR REPLACE FUNCTION geo.install_pack(p_pack jsonb) RETURNS jsonb
+LANGUAGE plpgsql AS $$
+DECLARE
+  hdr         jsonb := p_pack->'pack';
+  feats       jsonb := coalesce(p_pack->'regions'->'features', '[]'::jsonb);
+  pid         int;
+  f           jsonb;
+  n_countries int := 0;
+  n_regions   int := 0;
+  n_members   bigint;
+  code        text;
+BEGIN
+  IF hdr IS NULL OR coalesce(hdr->>'slug', '') = '' OR coalesce(hdr->>'version', '') = '' THEN
+    RAISE EXCEPTION 'Pack header must have slug and version' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  IF coalesce((hdr->>'schema_version')::int, 0) > geo.schema_version() THEN
+    RAISE EXCEPTION 'Pack "%" needs schema version % but this database has %',
+      hdr->>'slug', hdr->>'schema_version', geo.schema_version()
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+
+  INSERT INTO geo.packs (slug, version, schema_version)
+  VALUES (hdr->>'slug', hdr->>'version', coalesce((hdr->>'schema_version')::int, geo.schema_version()))
+  ON CONFLICT (slug) DO UPDATE
+    SET version = EXCLUDED.version, schema_version = EXCLUDED.schema_version, installed_at = now()
+  RETURNING id INTO pid;
+
+  PERFORM set_config('geo.skip_membership_triggers', 'on', true);
+
+  FOR f IN SELECT * FROM jsonb_array_elements(coalesce(p_pack->'countries', '[]'::jsonb)) LOOP
+    PERFORM geo.upsert_country(f->>'code', f->>'name',
+      CASE WHEN jsonb_typeof(f->'geometry') = 'object' THEN f->'geometry' END);
+    n_countries := n_countries + 1;
+  END LOOP;
+
+  FOR f IN SELECT * FROM jsonb_array_elements(feats) LOOP
+    PERFORM geo.upsert_region(
+      f->'properties'->>'country',
+      f->'properties'->>'slug',
+      f->'properties'->>'name',
+      (f->'properties'->>'type')::geo.region_type,
+      (f->'properties'->>'level')::int,
+      NULL,
+      f->'properties'->>'code',
+      ARRAY(SELECT jsonb_array_elements_text(coalesce(f->'properties'->'tags', '[]'::jsonb))),
+      coalesce(f->'properties'->'properties', '{}'::jsonb),
+      f->'geometry',
+      true,
+      pid);
+    n_regions := n_regions + 1;
+  END LOOP;
+
+  -- regions that left the pack
+  DELETE FROM geo.regions r
+  USING geo.countries c
+  WHERE r.pack_id = pid AND c.id = r.country_id
+    AND NOT EXISTS (
+      SELECT 1 FROM jsonb_array_elements(feats) ff
+      WHERE upper(ff->'properties'->>'country') = c.code AND ff->'properties'->>'slug' = r.slug);
+
+  -- the parent each region declares (a slug, in its parent_country or its own)
+  UPDATE geo.regions r
+  SET declared_parent = nullif(ff->'properties'->>'parent', ''),
+      declared_parent_country = CASE WHEN nullif(ff->'properties'->>'parent', '') IS NULL THEN NULL
+        ELSE upper(coalesce(ff->'properties'->>'parent_country', ff->'properties'->>'country')) END
+  FROM jsonb_array_elements(feats) ff
+  JOIN geo.countries c ON c.code = upper(ff->'properties'->>'country')
+  WHERE r.pack_id = pid AND r.country_id = c.id AND r.slug = ff->'properties'->>'slug';
+
+  -- parents among pack regions, this pack's and every other's
+  PERFORM geo.link_pack_parents();
+
+  FOR code IN SELECT c.code FROM geo.countries c WHERE c.geom IS NULL LOOP
+    PERFORM geo.derive_country_geom(code);
+  END LOOP;
+
+  n_members := geo.rebuild_all_memberships();
+  PERFORM set_config('geo.skip_membership_triggers', 'off', true);
+  RETURN jsonb_build_object(
+    'pack', hdr->>'slug', 'version', hdr->>'version',
+    'countries', n_countries, 'regions', n_regions, 'memberships', n_members);
+END $$;
+
+SELECT geo.pin_search_path();

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();