@nspot/geo-engine 0.2.1 → 0.3.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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nspot/geo-engine",
-  "version": "0.2.1",
+  "version": "0.3.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();