@nspot/geo-engine 0.3.0 → 0.5.0

package/dist/types.js

@@ -26,6 +26,48 @@ export const packVersionSchema = z
     .min(1)
     .max(50)
     .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "letters, digits, dots, dashes and underscores");
+/**
+ * One locality of a pack (schema 9): a named point, keyed by `(country, code)`. Its geometry is
+ * a GeoJSON Point (the label point) or null, and exactly one of a point and a non-empty
+ * `point_gap` (the pack's reason for having none) is given.
+ */
+export const localityFeatureSchema = z
+    .object({
+    type: z.literal("Feature"),
+    geometry: z
+        .object({ type: z.literal("Point"), coordinates: z.array(z.number()).min(2).max(3) })
+        .passthrough()
+        .nullable(),
+    properties: z.object({
+        country: countryCodeSchema,
+        code: z.string().min(1).max(200),
+        name: z.string().min(1).max(200),
+        parent: z.string().nullable().optional(),
+        parent_country: countryCodeSchema.nullable().optional(),
+        point_gap: z.string().nullable().optional(),
+        tags: z.array(z.string()).default([]),
+        properties: z.record(z.unknown()).default({}),
+    }),
+})
+    .refine((f) => (f.geometry !== null) !== Boolean(f.properties.point_gap), {
+    message: "give a point or a point_gap, not both and not neither",
+});
+const localitiesSectionSchema = z
+    .object({ type: z.literal("FeatureCollection"), features: z.array(localityFeatureSchema) })
+    .superRefine((fc, ctx) => {
+    const seen = new Set();
+    fc.features.forEach((f, i) => {
+        const key = `${f.properties.country} ${f.properties.code}`;
+        if (seen.has(key))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["features", i], message: "code given twice" });
+        seen.add(key);
+    });
+});
+/**
+ * A pack document. `regions` may be left out (a pack holding only localities) and reads as an
+ * empty collection. `localities` stays absent when absent: a pack without the key leaves the
+ * localities it installed alone, while an empty section removes them, so no default is given.
+ */
 export const packSchema = z.object({
     pack: z.object({
         slug: packSlugSchema,
@@ -54,5 +96,14 @@ export const packSchema = z.object({
                 properties: z.record(z.unknown()).default({}),
             }),
         })),
-    }),
+    }).default({ type: "FeatureCollection", features: [] }),
+    localities: localitiesSectionSchema.optional(),
+}).superRefine((doc, ctx) => {
+    if (doc.localities !== undefined && doc.pack.schema_version < 9) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["pack", "schema_version"],
+            message: "a pack with localities needs schema_version 9 or more",
+        });
+    }
 });

package/package.json

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