@nspot/geo-engine 0.4.0 → 0.5.0

package/README.md

@@ -137,6 +137,59 @@ An empty list, or a string in place of the list, is refused with
 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).
 
+## Localities
+
+A locality is a named point: a village, a town, a city. Packs at schema 9 may carry a
+`localities` section beside `regions`, and your own code may write local ones. Each is keyed
+by `(country, code)` (for Romania, the SIRUTA code, bare: `40642`), which is the same in every
+database, so your own tables reference it with a foreign key:
+
+```sql
+ALTER TABLE public.hotels ADD COLUMN locality_country char(2), ADD COLUMN locality_code text,
+  ADD FOREIGN KEY (locality_country, locality_code) REFERENCES geo.localities (country, code);
+```
+
+Every read answers `LocalitySummary` objects:
+
+```ts
+interface LocalitySummary {
+  country: string; code: string; name: string;
+  point: [number, number] | null;   // the label point, [lng, lat]
+  point_gap: string | null;         // why there is no point, when there is none
+  parent: { slug: string; name: string } | null;
+  tags: string[]; properties: Record<string, unknown>;
+  pack: string | null;              // the owning pack's slug; null for a local locality
+  distance_m?: number;              // localitiesNear only
+}
+```
+
+```ts
+import { localitiesByCode, localitiesIn, localitiesNear, searchLocalities } from "@nspot/geo-engine";
+
+await localitiesByCode(pool, ["40642"], { country: "RO" }); // in the order given; unknown codes absent
+await localitiesIn(pool, ["sibiu"]);                         // by parent, through every level below
+await localitiesIn(pool, ["bran-moeciu"], { via: "point" }); // by point, for a region that is nobody's parent
+await searchLocalities(pool, "saliste", { within: ["sibiu"], limit: 20 }); // case and diacritics folded
+await localitiesNear(pool, 23.98, 45.79, { limit: 10, maxMeters: 5000 });  // nearest first, with distance_m
+```
+
+`upsertLocality(pool, { country, code, name, parent?, parentCountry?, point?, pointGap?, tags?,
+properties? })` writes a local locality (give exactly one of `point`, a GeoJSON Point, and
+`pointGap`) and answers its summary; `deleteLocality(pool, country, code)` answers whether one
+was deleted. Both refuse a pack's locality with `conflict`.
+
+A list argument must be a non-empty array: a string in its place (`"40642"`, which iterated
+would name one-digit codes) is refused with `invalid_input` before the database is reached.
+
+**`in_use`.** While one of your rows references a locality, nothing removes it:
+`deleteLocality`, `uninstallPack`, and an `installPack` upgrade that drops the code all reject
+with `GeoEngineError("in_use", …)` (`sqlState` `23503`), change nothing, and name the
+localities in the message; `detail` carries Postgres's own key and table. Remap your rows,
+then retry.
+
+`exportPack`'s `include` option (`"all"`, the default, `"regions"` or `"localities"`) picks
+the sections, and `listPacks` gives each pack's `locality_count`. Localities need schema 9. In 0.5.0, `listPacks` and `exportPack` need schema 9 too, so run `migrate` after upgrading.
+
 ## CLI
 
 The package ships a `geo-engine` bin (run it with `npx geo-engine …`, `pnpm dlx geo-engine …`,
@@ -177,7 +230,9 @@ database, and `cause` when it wraps something else (a zod `ZodError`, a fetch fa
 | `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   |
 | `unknown_source` | the request named a source that isn't registered                                  |
-| `conflict`       | a unique-key violation (`23505`) — e.g. registering a name or pack slug that already exists |
+| `invalid_input`  | a list argument of a locality read is empty or not an array, or a search query is blank, raised before the database is touched |
+| `conflict`       | a unique-key violation (`23505`) — e.g. registering a name or pack slug that already exists, or writing a pack's locality |
+| `in_use`         | a host row still references a locality that would be removed (`23503`); nothing changed |
 | `invalid_source` | the registered table or column doesn't exist (`42P01` / `42703`)                  |
 | `database`       | any other Postgres error                                                          |
 

package/dist/cli.js

@@ -94,7 +94,7 @@ async function run() {
             if (sub === "install") {
                 const source = positionals[2] ?? usageError("usage: geo-engine pack install <url|file|package>");
                 const r = await installPack(pool, source);
-                console.log(`installed ${r.pack}@${r.version}: ${r.regions} regions, ${r.countries} countries, ${r.memberships} memberships`);
+                console.log(`installed ${r.pack}@${r.version}: ${r.regions} regions, ${r.countries} countries, ${r.memberships} memberships${r.localities !== undefined ? `, ${r.localities} localities` : ""}`);
             }
             else if (sub === "list") {
                 const packs = await listPacks(pool);
@@ -102,7 +102,7 @@ async function run() {
                     console.log("no packs installed");
                 else
                     for (const p of packs)
-                        console.log(`${p.slug}  ${p.version}  ${p.region_count} regions  ${p.installed_at}`);
+                        console.log(`${p.slug}  ${p.version}  ${p.region_count} regions  ${p.locality_count} localities  ${p.installed_at}`);
             }
             else if (sub === "uninstall") {
                 const slug = positionals[2] ?? usageError("usage: geo-engine pack uninstall <slug>");

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 import type { Queryable } from "./migrate.js";
-export type GeoEngineErrorCode = "invalid_input" | "unknown_source" | "conflict" | "invalid_source" | "database";
+export type GeoEngineErrorCode = "invalid_input" | "unknown_source" | "conflict" | "in_use" | "invalid_source" | "database";
 /** Every failure raised by this package. `sqlState` is the Postgres error code when there was one. */
 export declare class GeoEngineError extends Error {
     name: string;

package/dist/errors.js

@@ -27,6 +27,10 @@ export function wrapPgError(err) {
     let code = (sqlState && BY_STATE[sqlState]) || "database";
     if (code === "invalid_input" && /^Unknown source/.test(message))
         code = "unknown_source";
+    // geo raises 23503 for other things too (upsert_region's unknown country): only the wording of
+    // delete_pack_localities and delete_locality means a host row still references a locality
+    if (sqlState === "23503" && message.includes("a host still references"))
+        code = "in_use";
     return new GeoEngineError(code, message, { sqlState, detail, cause: err });
 }
 /** Run one parameterised statement and return its rows, translating failures. */

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from "./sources.js";
 export * from "./packs.js";
 export * from "./errors.js";
 export * from "./query.js";
+export * from "./localities.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export * from "./sources.js";
 export * from "./packs.js";
 export * from "./errors.js";
 export * from "./query.js";
+export * from "./localities.js";

package/dist/localities.d.ts

@@ -0,0 +1,71 @@
+import type { Queryable } from "./migrate.js";
+import type { LocalitySummary, PointGeometry } from "./types.js";
+export interface LocalitiesByCodeOptions {
+    /** A country's ISO code, in either case: only that country's localities. */
+    country?: string;
+}
+/**
+ * The localities with these codes, in the order given; an unknown code is absent, and a code
+ * given twice answers once. Without `country`, a code two countries share answers both.
+ */
+export declare function localitiesByCode(db: Queryable, codes: readonly string[], opts?: LocalitiesByCodeOptions): Promise<LocalitySummary[]>;
+export interface LocalitiesInOptions {
+    /**
+     * `"parent"` (the default): localities whose parent is one of the regions or below one, gaps
+     * included. `"point"`: localities whose point lies in one of the regions, gaps left out, for a
+     * region that is nobody's parent.
+     */
+    via?: "parent" | "point";
+}
+/** The localities in the regions (slugs or ids), ordered by name. An unknown region is `invalid_input`. */
+export declare function localitiesIn(db: Queryable, regions: readonly string[], opts?: LocalitiesInOptions): Promise<LocalitySummary[]>;
+export interface SearchLocalitiesOptions {
+    /** Only localities whose parent chain reaches one of these regions (slugs or ids). */
+    within?: readonly string[];
+    /** 1 to 1000; defaults to 20. */
+    limit?: number;
+}
+/**
+ * Localities by name. Case, diacritics (ş and ș alike), hyphens and spaces are folded on both
+ * sides; an equal name ranks first, a prefix second, a substring third, then by name and code.
+ */
+export declare function searchLocalities(db: Queryable, query: string, opts?: SearchLocalitiesOptions): Promise<LocalitySummary[]>;
+export interface LocalitiesNearOptions {
+    /** 1 to 1000; defaults to 10. */
+    limit?: number;
+    /** Leave out any locality further than this many metres (geodesic). */
+    maxMeters?: number;
+}
+/**
+ * The localities nearest a point, nearest first, each with `distance_m` (geodesic metres, to
+ * 0.1 m). Localities with a `point_gap` have no point and never answer.
+ */
+export declare function localitiesNear(db: Queryable, lng: number, lat: number, opts?: LocalitiesNearOptions): Promise<(LocalitySummary & {
+    distance_m: number;
+})[]>;
+export interface UpsertLocalityInput {
+    /** A country's ISO code, in either case; the country must exist. */
+    country: string;
+    code: string;
+    name: string;
+    /** A region slug, resolved now to any region, local or a pack's. */
+    parent?: string | null;
+    /** The parent's country, when it is not `country`. */
+    parentCountry?: string | null;
+    /** The label point. Give exactly one of `point` and `pointGap`. */
+    point?: PointGeometry | null;
+    /** Why there is no point. */
+    pointGap?: string | null;
+    tags?: string[];
+    properties?: Record<string, unknown>;
+}
+/**
+ * Insert or update a local locality (one no pack owns) and return its summary. A pack's
+ * locality is refused with `conflict`; update or uninstall the pack instead.
+ */
+export declare function upsertLocality(db: Queryable, input: UpsertLocalityInput): Promise<LocalitySummary>;
+/**
+ * Delete a local locality; true when one was deleted, false when there was none. A pack's
+ * locality is refused with `conflict`, and one a host row still references with `in_use`.
+ */
+export declare function deleteLocality(db: Queryable, country: string, code: string): Promise<boolean>;

package/dist/localities.js

@@ -0,0 +1,87 @@
+import { GeoEngineError, run } from "./errors.js";
+// Localities (schema 9): named points, keyed by (country, code), that a host's own tables
+// reference with a foreign key. Every read answers LocalitySummary rows, one per row of the
+// SQL function it wraps.
+/**
+ * A list argument must be a non-empty array. A string is not a list: iterated, "40642" would
+ * name five one-digit codes and answer nothing, so it is refused before any query.
+ */
+function requireList(value, message) {
+    if (!Array.isArray(value) || value.length === 0)
+        throw new GeoEngineError("invalid_input", message);
+}
+/**
+ * The localities with these codes, in the order given; an unknown code is absent, and a code
+ * given twice answers once. Without `country`, a code two countries share answers both.
+ */
+export async function localitiesByCode(db, codes, opts = {}) {
+    requireList(codes, "codes must be a list naming at least one code");
+    const rows = await run(db, "SELECT t.s FROM geo.localities_by_code($1::text[], $2::text) AS t(s)", [
+        codes,
+        opts.country ?? null,
+    ]);
+    return rows.map((r) => r.s);
+}
+/** The localities in the regions (slugs or ids), ordered by name. An unknown region is `invalid_input`. */
+export async function localitiesIn(db, regions, opts = {}) {
+    requireList(regions, "regions must be a list naming at least one region");
+    const rows = await run(db, "SELECT t.s FROM geo.localities_in($1::text[], $2::text) AS t(s)", [
+        regions,
+        opts.via ?? "parent",
+    ]);
+    return rows.map((r) => r.s);
+}
+/**
+ * Localities by name. Case, diacritics (ş and ș alike), hyphens and spaces are folded on both
+ * sides; an equal name ranks first, a prefix second, a substring third, then by name and code.
+ */
+export async function searchLocalities(db, query, opts = {}) {
+    if (typeof query !== "string" || query.trim() === "") {
+        throw new GeoEngineError("invalid_input", "query must be a non-empty string");
+    }
+    if (opts.within !== undefined)
+        requireList(opts.within, "within must be a list naming at least one region, or left out");
+    const rows = await run(db, "SELECT t.s FROM geo.search_localities($1, $2::text[], $3) AS t(s)", [
+        query,
+        opts.within ?? null,
+        opts.limit ?? 20,
+    ]);
+    return rows.map((r) => r.s);
+}
+/**
+ * The localities nearest a point, nearest first, each with `distance_m` (geodesic metres, to
+ * 0.1 m). Localities with a `point_gap` have no point and never answer.
+ */
+export async function localitiesNear(db, lng, lat, opts = {}) {
+    const rows = await run(db, "SELECT t.s FROM geo.localities_near($1, $2, $3, $4) AS t(s)", [lng, lat, opts.limit ?? 10, opts.maxMeters ?? null]);
+    return rows.map((r) => r.s);
+}
+/**
+ * Insert or update a local locality (one no pack owns) and return its summary. A pack's
+ * locality is refused with `conflict`; update or uninstall the pack instead.
+ */
+export async function upsertLocality(db, input) {
+    if (input.tags !== undefined && !Array.isArray(input.tags)) {
+        throw new GeoEngineError("invalid_input", "tags must be a list of strings");
+    }
+    const rows = await run(db, "SELECT geo.upsert_locality($1, $2, $3, $4, $5, $6::jsonb, $7, $8::text[], $9::jsonb) AS s", [
+        input.country,
+        input.code,
+        input.name,
+        input.parent ?? null,
+        input.parentCountry ?? null,
+        input.point ? JSON.stringify(input.point) : null,
+        input.pointGap ?? null,
+        input.tags ?? [],
+        JSON.stringify(input.properties ?? {}),
+    ]);
+    return rows[0].s;
+}
+/**
+ * Delete a local locality; true when one was deleted, false when there was none. A pack's
+ * locality is refused with `conflict`, and one a host row still references with `in_use`.
+ */
+export async function deleteLocality(db, country, code) {
+    const rows = await run(db, "SELECT geo.delete_locality($1, $2) AS d", [country, code]);
+    return rows[0].d;
+}

package/dist/packs.d.ts

@@ -14,8 +14,15 @@ export interface ExportPackOptions {
      * slug for that pack's regions. Omitted, every region is exported.
      */
     owner?: string;
-    /** Export only regions whose slug starts with this. */
+    /** Export only regions whose slug starts with this, and the localities whose parent it selects. */
     slugPrefix?: string;
+    /**
+     * What to export (schema 9). `"all"` (the default): the regions, and a `localities` section
+     * only when there are localities to write, so a pack without them exports as before.
+     * `"regions"`: no `localities` section. `"localities"`: no regions, and the section always
+     * written, even empty (installing an empty section removes the pack's localities).
+     */
+    include?: "all" | "regions" | "localities";
 }
 /**
  * The database's regions as one pack document, named `slug`@`version`.
@@ -42,6 +49,11 @@ export declare function exportPack(db: Queryable, slug: string, version: string,
  * - **an `http(s)` URL**, downloaded with a timeout (`opts.timeoutMs`, default 30s).
  */
 export declare function installPack(db: Queryable, source: Pack | string, opts?: InstallPackOptions): Promise<InstallPackResult>;
-/** Removes the pack's regions and the pack row; returns how many regions were removed. */
+/**
+ * Removes the pack's regions, its localities and the pack row; returns how many regions were
+ * removed. Rejects with `in_use`, removing nothing, while a host row still references one of
+ * its localities. (`installPack` does the same for an upgrade that drops such a locality.)
+ */
 export declare function uninstallPack(db: Queryable, slug: string): Promise<number>;
+/** The installed packs by slug, each with how many regions and localities it holds. */
 export declare function listPacks(db: Queryable): Promise<PackInfo[]>;

package/dist/packs.js

@@ -16,11 +16,12 @@ const PACKAGE_NAME_RE = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/
  * 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", [
+    const rows = await run(db, "SELECT geo.export_pack($1, $2, $3, $4, $5) AS pack", [
         slug,
         version,
         opts.owner ?? null,
         opts.slugPrefix ?? null,
+        opts.include ?? "all",
     ]);
     return rows[0].pack;
 }
@@ -123,15 +124,21 @@ function isFile(p) {
         return false;
     }
 }
-/** Removes the pack's regions and the pack row; returns how many regions were removed. */
+/**
+ * Removes the pack's regions, its localities and the pack row; returns how many regions were
+ * removed. Rejects with `in_use`, removing nothing, while a host row still references one of
+ * its localities. (`installPack` does the same for an upgrade that drops such a locality.)
+ */
 export async function uninstallPack(db, slug) {
     const rows = await run(db, "SELECT geo.uninstall_pack($1) AS n", [slug]);
     return rows[0].n;
 }
+/** The installed packs by slug, each with how many regions and localities it holds. */
 export async function listPacks(db) {
     const rows = await run(db, `
     SELECT p.id, p.slug, p.version, p.schema_version, p.installed_at,
-           (SELECT count(*) FROM geo.regions r WHERE r.pack_id = p.id)::int AS region_count
+           (SELECT count(*) FROM geo.regions r WHERE r.pack_id = p.id)::int AS region_count,
+           (SELECT count(*) FROM geo.localities l WHERE l.pack_id = p.id)::int AS locality_count
     FROM geo.packs p ORDER BY p.slug`);
     // pg hands back a Date for timestamptz; PackInfo.installed_at is an ISO string
     return rows.map((row) => ({ ...row, installed_at: new Date(row.installed_at).toISOString() }));