@nspot/geo-engine 0.1.0

package/dist/paths.js

@@ -0,0 +1,7 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const here = path.dirname(fileURLToPath(import.meta.url));
+/** Package root: works both from src/ (tsx) and dist/ (compiled). */
+export const PACKAGE_ROOT = path.resolve(here, "..");
+/** The migration files shipped with this package (a copy of packages/db/sql). */
+export const SQL_DIR = path.join(PACKAGE_ROOT, "sql");

package/dist/query.d.ts

@@ -0,0 +1,43 @@
+import type { Queryable } from "./migrate.js";
+import type { RegionSummary } from "./types.js";
+export interface RegionFilter {
+    /** Region slugs or numeric ids; at least one. */
+    regions: string[];
+    /** any (default): in at least one; all: in every listed region. */
+    match?: "any" | "all";
+    exclude?: string[];
+}
+export interface FragmentOptions {
+    /**
+     * The host's id column as it appears in the statement, e.g. "h.id".
+     *
+     * **Trust model**: this string is interpolated into the fragment's SQL verbatim — it is
+     * raw SQL authored by you, not a value. Never build it from request input (a query
+     * parameter, a request body, a URL segment); use a literal or a value chosen from a
+     * fixed list in your own code. The same holds for `idType`, which is additionally
+     * checked against a plain-identifier pattern.
+     */
+    column: string;
+    /** SQL type of that column; defaults to text. */
+    idType?: string;
+    /** Number of placeholders already used in the statement; the fragment's start at offset + 1. */
+    offset?: number;
+}
+export interface SqlFragment {
+    text: string;
+    values: unknown[];
+}
+/** `<column> IN (SELECT … geo.ids_in(...))` for rows inside the given regions. */
+export declare function inRegions(source: string, filter: RegionFilter, opts: FragmentOptions): SqlFragment;
+/**
+ * `<column> NOT IN (...)`: rows inside none of the regions, including rows in no region at all.
+ *
+ * SQL `NOT IN` is null-propagating: if `opts.column` can be NULL (a LEFT JOINed id, for
+ * example) the predicate is NULL rather than true for that row, so the row does not come
+ * back. Add an explicit `OR <column> IS NULL` (in parentheses with the fragment) if you want those rows.
+ */
+export declare function notInRegions(source: string, regions: string[], opts: FragmentOptions): SqlFragment;
+/** External ids (as text) of the source's rows matching the filter. */
+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[]>;

package/dist/query.js

@@ -0,0 +1,52 @@
+import { GeoEngineError, run } from "./errors.js";
+const IDENT = /^[A-Za-z_][A-Za-z0-9_$]*(\[\])?$/;
+function idType(opts) {
+    const t = opts.idType ?? "text";
+    if (!IDENT.test(t))
+        throw new GeoEngineError("invalid_input", `idType must be a plain SQL type name, got "${t}"`);
+    return t;
+}
+/** `geo.ids_in` rejects an empty region list; fail before spending a round trip. */
+function requireRegions(regions) {
+    if (!regions || regions.length === 0) {
+        throw new GeoEngineError("invalid_input", "regions must name at least one region");
+    }
+}
+/** `<column> IN (SELECT … geo.ids_in(...))` for rows inside the given regions. */
+export function inRegions(source, filter, opts) {
+    requireRegions(filter.regions);
+    const o = opts.offset ?? 0;
+    return {
+        text: `${opts.column} IN (SELECT t.id::${idType(opts)} FROM geo.ids_in($${o + 1}, $${o + 2}::text[], $${o + 3}, $${o + 4}::text[]) AS t(id))`,
+        values: [source, filter.regions, filter.match ?? "any", filter.exclude ?? null],
+    };
+}
+/**
+ * `<column> NOT IN (...)`: rows inside none of the regions, including rows in no region at all.
+ *
+ * SQL `NOT IN` is null-propagating: if `opts.column` can be NULL (a LEFT JOINed id, for
+ * example) the predicate is NULL rather than true for that row, so the row does not come
+ * back. Add an explicit `OR <column> IS NULL` (in parentheses with the fragment) if you want those rows.
+ */
+export function notInRegions(source, regions, opts) {
+    const o = opts.offset ?? 0;
+    return {
+        text: `${opts.column} NOT IN (SELECT t.id::${idType(opts)} FROM geo.ids_in($${o + 1}, $${o + 2}::text[]) AS t(id))`,
+        values: [source, regions],
+    };
+}
+/** External ids (as text) of the source's rows matching the filter. */
+export async function ids(db, source, filter) {
+    requireRegions(filter.regions);
+    const rows = await run(db, "SELECT t.id FROM geo.ids_in($1, $2::text[], $3, $4::text[]) AS t(id)", [
+        source, filter.regions, filter.match ?? "any", filter.exclude ?? null,
+    ]);
+    return rows.map((r) => r.id);
+}
+export async function regionsOf(db, source, externalId) {
+    const rows = await run(db, "SELECT geo.regions_of($1, $2::text) AS r", [source, String(externalId)]);
+    return rows[0].r;
+}
+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]);
+}

package/dist/sources.d.ts

@@ -0,0 +1,30 @@
+import type { Queryable } from "./migrate.js";
+export interface Source {
+    id: number;
+    name: string;
+    table_schema: string;
+    table_name: string;
+    id_column: string;
+    id_type: string;
+    geom_expr: string;
+    registered_at: string;
+}
+export interface RegisterSourceOptions {
+    /** Name used in queries, e.g. "hotels". */
+    name: string;
+    /** "hotels" or "public.hotels". */
+    table: string;
+    idColumn: string;
+    /** A geometry column name, or the lng / lat column names to build a point from. */
+    geometry: string | {
+        lng: string;
+        lat: string;
+    };
+}
+/** SQL expression over a row alias `r` that yields the row's geometry in SRID 4326. */
+export declare function geometryExpression(geometry: RegisterSourceOptions["geometry"]): string;
+export declare function registerSource(db: Queryable, opts: RegisterSourceOptions): Promise<Source>;
+export declare function unregisterSource(db: Queryable, name: string): Promise<void>;
+/** Recompute memberships for one source, or for every source when no name is given. */
+export declare function rebuildMemberships(db: Queryable, name?: string): Promise<number>;
+export declare function listSources(db: Queryable): Promise<Source[]>;

package/dist/sources.js

@@ -0,0 +1,32 @@
+import { run } from "./errors.js";
+const quoteIdent = (s) => `"${s.replace(/"/g, '""')}"`;
+/** SQL expression over a row alias `r` that yields the row's geometry in SRID 4326. */
+export function geometryExpression(geometry) {
+    if (typeof geometry === "string")
+        return quoteIdent(geometry);
+    return `ST_SetSRID(ST_MakePoint(${quoteIdent(geometry.lng)}, ${quoteIdent(geometry.lat)}), 4326)`;
+}
+export async function registerSource(db, opts) {
+    const [schema, table] = opts.table.includes(".") ? opts.table.split(".", 2) : ["public", opts.table];
+    const rows = await run(db, "SELECT * FROM geo.register_source($1, $2, $3, $4, $5)", [
+        opts.name,
+        schema,
+        table,
+        opts.idColumn,
+        geometryExpression(opts.geometry),
+    ]);
+    return rows[0];
+}
+export async function unregisterSource(db, name) {
+    await run(db, "SELECT geo.unregister_source($1)", [name]);
+}
+/** Recompute memberships for one source, or for every source when no name is given. */
+export async function rebuildMemberships(db, name) {
+    const rows = name
+        ? await run(db, "SELECT geo.rebuild_memberships($1)::text AS n", [name])
+        : await run(db, "SELECT geo.rebuild_all_memberships()::text AS n");
+    return Number(rows[0].n);
+}
+export async function listSources(db) {
+    return run(db, "SELECT * FROM geo.sources ORDER BY id");
+}

package/dist/types.d.ts

@@ -0,0 +1,323 @@
+import { z } from "zod";
+/**
+ * admin    – official administrative units (județ, department, state…)
+ * cultural – ethnographic / historical areas (Mărginimea Sibiului, Țara Oltului)
+ * natural  – landscape units (Delta Dunării, Carpații Meridionali)
+ * custom   – anything you define for your own product (a marketing zone, a tour area)
+ */
+export declare const REGION_TYPES: readonly ["admin", "cultural", "natural", "custom"];
+export type RegionType = (typeof REGION_TYPES)[number];
+export declare const regionTypeSchema: z.ZodEnum<["admin", "cultural", "natural", "custom"]>;
+export type Position = [number, number] | [number, number, number];
+export type PointGeometry = {
+    type: "Point";
+    coordinates: Position;
+};
+export type PolygonGeometry = {
+    type: "Polygon";
+    coordinates: Position[][];
+};
+export type MultiPolygonGeometry = {
+    type: "MultiPolygon";
+    coordinates: Position[][][];
+};
+export type AreaGeometry = PolygonGeometry | MultiPolygonGeometry;
+export type Feature<G = AreaGeometry, P = Record<string, unknown>> = {
+    type: "Feature";
+    id?: string | number;
+    geometry: G;
+    properties: P;
+};
+export type FeatureCollection<G = AreaGeometry, P = Record<string, unknown>> = {
+    type: "FeatureCollection";
+    features: Feature<G, P>[];
+};
+export declare const geoJsonAnySchema: z.ZodObject<{
+    type: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    type: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    type: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+export interface RegionSummary {
+    id: number;
+    slug: string;
+    name: string;
+    type: RegionType;
+    level: number | null;
+    parent_id: number | null;
+    code: string | null;
+}
+export interface Region extends RegionSummary {
+    country_code: string;
+    tags: string[];
+    properties: Record<string, unknown>;
+    pack_id?: number | null;
+    location_count?: number;
+    geometry?: AreaGeometry;
+    created_at?: string;
+    updated_at?: string;
+}
+export declare const countryCodeSchema: z.ZodEffects<z.ZodString, string, string>;
+export declare const packSlugSchema: z.ZodString;
+export declare const packVersionSchema: z.ZodString;
+export declare const packSchema: z.ZodObject<{
+    pack: z.ZodObject<{
+        slug: z.ZodString;
+        version: z.ZodString;
+        schema_version: z.ZodNumber;
+        published_at: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        slug: string;
+        version: string;
+        schema_version: number;
+        published_at?: string | undefined;
+    }, {
+        slug: string;
+        version: string;
+        schema_version: number;
+        published_at?: string | undefined;
+    }>;
+    countries: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        code: z.ZodEffects<z.ZodString, string, string>;
+        name: z.ZodString;
+        geometry: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            type: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>>>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        name: string;
+        geometry?: z.objectOutputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | null | undefined;
+    }, {
+        code: string;
+        name: string;
+        geometry?: z.objectInputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | null | undefined;
+    }>, "many">>;
+    regions: z.ZodObject<{
+        type: z.ZodLiteral<"FeatureCollection">;
+        features: z.ZodArray<z.ZodObject<{
+            type: z.ZodLiteral<"Feature">;
+            geometry: z.ZodObject<{
+                type: z.ZodString;
+            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+                type: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+                type: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">>;
+            properties: z.ZodObject<{
+                country: z.ZodEffects<z.ZodString, string, string>;
+                slug: z.ZodString;
+                name: z.ZodString;
+                type: z.ZodEnum<["admin", "cultural", "natural", "custom"]>;
+                level: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                parent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                parent_country: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
+                code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+                properties: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            }, "strip", z.ZodTypeAny, {
+                type: "admin" | "cultural" | "natural" | "custom";
+                slug: string;
+                name: string;
+                properties: Record<string, unknown>;
+                country: string;
+                tags: string[];
+                code?: string | null | undefined;
+                level?: number | null | undefined;
+                parent?: string | null | undefined;
+                parent_country?: string | null | undefined;
+            }, {
+                type: "admin" | "cultural" | "natural" | "custom";
+                slug: string;
+                name: string;
+                country: string;
+                code?: string | null | undefined;
+                properties?: Record<string, unknown> | undefined;
+                level?: number | null | undefined;
+                parent?: string | null | undefined;
+                parent_country?: string | null | undefined;
+                tags?: string[] | undefined;
+            }>;
+        }, "strip", z.ZodTypeAny, {
+            type: "Feature";
+            geometry: {
+                type: string;
+            } & {
+                [k: string]: unknown;
+            };
+            properties: {
+                type: "admin" | "cultural" | "natural" | "custom";
+                slug: string;
+                name: string;
+                properties: Record<string, unknown>;
+                country: string;
+                tags: string[];
+                code?: string | null | undefined;
+                level?: number | null | undefined;
+                parent?: string | null | undefined;
+                parent_country?: string | null | undefined;
+            };
+        }, {
+            type: "Feature";
+            geometry: {
+                type: string;
+            } & {
+                [k: string]: unknown;
+            };
+            properties: {
+                type: "admin" | "cultural" | "natural" | "custom";
+                slug: string;
+                name: string;
+                country: string;
+                code?: string | null | undefined;
+                properties?: Record<string, unknown> | undefined;
+                level?: number | null | undefined;
+                parent?: string | null | undefined;
+                parent_country?: string | null | undefined;
+                tags?: string[] | undefined;
+            };
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "FeatureCollection";
+        features: {
+            type: "Feature";
+            geometry: {
+                type: string;
+            } & {
+                [k: string]: unknown;
+            };
+            properties: {
+                type: "admin" | "cultural" | "natural" | "custom";
+                slug: string;
+                name: string;
+                properties: Record<string, unknown>;
+                country: string;
+                tags: string[];
+                code?: string | null | undefined;
+                level?: number | null | undefined;
+                parent?: string | null | undefined;
+                parent_country?: string | null | undefined;
+            };
+        }[];
+    }, {
+        type: "FeatureCollection";
+        features: {
+            type: "Feature";
+            geometry: {
+                type: string;
+            } & {
+                [k: string]: unknown;
+            };
+            properties: {
+                type: "admin" | "cultural" | "natural" | "custom";
+                slug: string;
+                name: string;
+                country: string;
+                code?: string | null | undefined;
+                properties?: Record<string, unknown> | undefined;
+                level?: number | null | undefined;
+                parent?: string | null | undefined;
+                parent_country?: string | null | undefined;
+                tags?: string[] | undefined;
+            };
+        }[];
+    }>;
+}, "strip", z.ZodTypeAny, {
+    pack: {
+        slug: string;
+        version: string;
+        schema_version: number;
+        published_at?: string | undefined;
+    };
+    countries: {
+        code: string;
+        name: string;
+        geometry?: z.objectOutputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | null | undefined;
+    }[];
+    regions: {
+        type: "FeatureCollection";
+        features: {
+            type: "Feature";
+            geometry: {
+                type: string;
+            } & {
+                [k: string]: unknown;
+            };
+            properties: {
+                type: "admin" | "cultural" | "natural" | "custom";
+                slug: string;
+                name: string;
+                properties: Record<string, unknown>;
+                country: string;
+                tags: string[];
+                code?: string | null | undefined;
+                level?: number | null | undefined;
+                parent?: string | null | undefined;
+                parent_country?: string | null | undefined;
+            };
+        }[];
+    };
+}, {
+    pack: {
+        slug: string;
+        version: string;
+        schema_version: number;
+        published_at?: string | undefined;
+    };
+    regions: {
+        type: "FeatureCollection";
+        features: {
+            type: "Feature";
+            geometry: {
+                type: string;
+            } & {
+                [k: string]: unknown;
+            };
+            properties: {
+                type: "admin" | "cultural" | "natural" | "custom";
+                slug: string;
+                name: string;
+                country: string;
+                code?: string | null | undefined;
+                properties?: Record<string, unknown> | undefined;
+                level?: number | null | undefined;
+                parent?: string | null | undefined;
+                parent_country?: string | null | undefined;
+                tags?: string[] | undefined;
+            };
+        }[];
+    };
+    countries?: {
+        code: string;
+        name: string;
+        geometry?: z.objectInputType<{
+            type: z.ZodString;
+        }, z.ZodTypeAny, "passthrough"> | null | undefined;
+    }[] | undefined;
+}>;
+export type Pack = z.infer<typeof packSchema>;
+export interface PackInfo {
+    id: number;
+    slug: string;
+    version: string;
+    schema_version: number;
+    installed_at: string;
+    region_count: number;
+}
+export interface InstallPackResult {
+    pack: string;
+    version: string;
+    countries: number;
+    regions: number;
+    memberships: number;
+}

package/dist/types.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Region taxonomy
+// ---------------------------------------------------------------------------
+/**
+ * admin    – official administrative units (județ, department, state…)
+ * cultural – ethnographic / historical areas (Mărginimea Sibiului, Țara Oltului)
+ * natural  – landscape units (Delta Dunării, Carpații Meridionali)
+ * custom   – anything you define for your own product (a marketing zone, a tour area)
+ */
+export const REGION_TYPES = ["admin", "cultural", "natural", "custom"];
+export const regionTypeSchema = z.enum(REGION_TYPES);
+export const geoJsonAnySchema = z
+    .object({ type: z.string() })
+    .passthrough();
+export const countryCodeSchema = z
+    .string()
+    .length(2)
+    .transform((s) => s.toUpperCase());
+// ---------------------------------------------------------------------------
+// Region packs — one JSON document moving regions between databases
+// ---------------------------------------------------------------------------
+export const packSlugSchema = z.string().min(1).max(100).regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters, digits and dashes");
+export const packVersionSchema = z
+    .string()
+    .min(1)
+    .max(50)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "letters, digits, dots, dashes and underscores");
+export const packSchema = z.object({
+    pack: z.object({
+        slug: packSlugSchema,
+        version: z.string().min(1).max(50),
+        schema_version: z.number().int().positive(),
+        published_at: z.string().optional(),
+    }),
+    countries: z
+        .array(z.object({ code: countryCodeSchema, name: z.string().min(1), geometry: geoJsonAnySchema.nullable().optional() }))
+        .default([]),
+    regions: z.object({
+        type: z.literal("FeatureCollection"),
+        features: z.array(z.object({
+            type: z.literal("Feature"),
+            geometry: geoJsonAnySchema,
+            properties: z.object({
+                country: countryCodeSchema,
+                slug: z.string().min(1).max(200),
+                name: z.string().min(1).max(200),
+                type: regionTypeSchema,
+                level: z.number().int().nullable().optional(),
+                parent: z.string().nullable().optional(),
+                parent_country: countryCodeSchema.nullable().optional(),
+                code: z.string().nullable().optional(),
+                tags: z.array(z.string()).default([]),
+                properties: z.record(z.unknown()).default({}),
+            }),
+        })),
+    }),
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nspot/geo-engine",
+  "version": "0.1.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",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./types": { "types": "./dist/types.d.ts", "import": "./dist/types.js" }
+  },
+  "bin": { "geo-engine": "./dist/cli.js" },
+  "files": ["dist", "sql", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NSpot-Games/geo-engine.git",
+    "directory": "packages/sdk-node"
+  },
+  "homepage": "https://github.com/NSpot-Games/geo-engine/tree/main/packages/sdk-node#readme",
+  "bugs": "https://github.com/NSpot-Games/geo-engine/issues",
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "sync-sql": "node scripts/sync-sql.mjs",
+    "prepack": "node scripts/sync-sql.mjs && tsc -p tsconfig.json",
+    "build": "node scripts/sync-sql.mjs && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@types/pg": "^8.11.10",
+    "pg": "^8.13.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.11"
+  }
+}