geolookup-plugin 0.1.0

package/config.yaml

@@ -0,0 +1,26 @@
+# yaml-language-server: $schema=./node_modules/harperdb/config-app.schema.json
+
+# This is the configuration file for the application.
+# It specifies built-in Harper components that will load the specified feature and files.
+# For more information, see https://docs.harperdb.io/docs/reference/components/built-in-extensions
+
+# Load Environment Variables from the specified file
+# loadEnv:
+#   files: '.env'
+
+# This provides the HTTP REST interface for all exported resources
+#rest: true
+
+pluginModule: 'src/index.ts'
+
+# These reads GraphQL schemas to define the schema of database/tables/attributes.
+graphqlSchema:
+  files: 'schemas/*.graphql'
+
+# Loads JavaScript modules such that their exports are exported as resources
+#jsResource:
+#  files: 'src/resources/*.ts'
+
+# Load seed data from JSON files into tables
+#dataLoader:
+#  files: 'data/**/*.json'

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { Geolookup } from './resources/Geolookup.ts';
+import { DataLoad } from './resources/DataLoad.ts';
+import { Scope } from 'harperdb';
+export { Geolookup, DataLoad };
+/**
+ * Plugin entry point called by Harper during startup.
+ *
+ * Reads configuration options from the consuming app's config.yaml and
+ * conditionally registers resource endpoints. Services are only exposed
+ * when their corresponding "expose" flag is set — this allows consuming
+ * apps to use the Geolookup and DataLoad classes programmatically without
+ * necessarily exposing them as REST endpoints.
+ *
+ * @param scope - Harper scope providing access to options and resource registration
+ */
+export declare function handleApplication(scope: Scope): void;

package/dist/index.js

@@ -0,0 +1,24 @@
+import { Geolookup } from "./resources/Geolookup.js";
+import { DataLoad } from "./resources/DataLoad.js";
+export { Geolookup, DataLoad };
+/**
+ * Plugin entry point called by Harper during startup.
+ *
+ * Reads configuration options from the consuming app's config.yaml and
+ * conditionally registers resource endpoints. Services are only exposed
+ * when their corresponding "expose" flag is set — this allows consuming
+ * apps to use the Geolookup and DataLoad classes programmatically without
+ * necessarily exposing them as REST endpoints.
+ *
+ * @param scope - Harper scope providing access to options and resource registration
+ */
+export function handleApplication(scope) {
+    const options = (scope.options.getAll() || {});
+    if (options.exposeGeoService) {
+        scope.resources.set(options.geoServiceName, Geolookup);
+    }
+    if (options.exposeDataLoadService) {
+        scope.resources.set(options.dataLoadServiceName, DataLoad);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAC,MAAM,0BAA0B,CAAC;AACnD,OAAO,EAAC,QAAQ,EAAC,MAAM,yBAAyB,CAAC;AAGjD,OAAO,EAAC,SAAS,EAAE,QAAQ,EAAC,CAAC;AAE7B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAY;IAC1C,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,CAAoB,CAAC;IAElE,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;QAC3B,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,OAAO,CAAC,qBAAqB,EAAE,CAAC;QAChC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC;IAC/D,CAAC;AACL,CAAC"}

package/dist/resources/DataLoad.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Async bulk loading endpoint for populating Location and Cell tables from
+ * pre-packaged state data files. Validates the request, creates a DataLoadJob
+ * record for tracking, and returns the job ID immediately. The actual data
+ * extraction and loading runs in the background — callers poll the DataLoadJob
+ * table to check progress.
+ */
+export declare class DataLoad extends Resource {
+    /**
+     * Handles GET requests to initiate a data load job.
+     *
+     * Validates the state parameter, checks that the corresponding .tar.gz file
+     * exists, creates a DataLoadJob record, and kicks off background processing.
+     * Returns the job ID immediately so the caller can poll for progress.
+     *
+     * @param target - Harper request target containing query parameters
+     * @returns Object with jobId on success, or an error object on validation failure
+     */
+    get(target: any): Promise<{
+        error: string;
+        jobId?: undefined;
+    } | {
+        jobId: `${string}-${string}-${string}-${string}-${string}`;
+        error?: undefined;
+    }>;
+}

package/dist/resources/DataLoad.js

@@ -0,0 +1,141 @@
+import { databases } from 'harperdb';
+import { execFileSync } from 'node:child_process';
+import { readFileSync, readdirSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+const { Location, Cell, DataLoadJob } = databases.geolookup;
+const DATA_DIR = new URL('../data/', import.meta.url).pathname;
+/**
+ * Reads all JSON files from a directory and loads each file's records into the
+ * given Harper table within a transaction. Each JSON file is expected to contain
+ * an array of records. After each file is loaded, the DataLoadJob record is
+ * updated with the running count.
+ *
+ * @param dir - Absolute path to the directory containing JSON files
+ * @param table - Harper table instance to load records into
+ * @param idField - Name of the field to use as the record's primary key
+ * @param jobId - UUID of the DataLoadJob record to update with progress
+ * @param countField - Name of the count field to update on the job (e.g. 'location_count')
+ * @returns Total number of records loaded across all files
+ */
+async function loadTableFiles(dir, table, idField, jobId, countField) {
+    let count = 0;
+    if (!existsSync(dir))
+        return count;
+    const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+    for (const file of files) {
+        const records = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
+        await transaction(async (txn) => {
+            for (const record of records) {
+                await table.put(record[idField], record, txn);
+                count++;
+            }
+        });
+        await DataLoadJob.patch(jobId, { [countField]: count });
+    }
+    return count;
+}
+/**
+ * Runs data extraction and loading in the background. Updates the DataLoadJob
+ * record as it progresses through each step:
+ *   extracting → loading_locations → loading_cells → completed (or error)
+ *
+ * On success, marks the job as completed with final counts and duration.
+ * On error, marks the job with status "error" and captures the error message.
+ * The extracted state folder is always cleaned up, even on failure.
+ *
+ * Locations are loaded before Cells because Cell records reference Location IDs
+ * via their tier_1/tier_2/tier_3 foreign keys.
+ *
+ * @param jobId - UUID of the DataLoadJob record to update
+ * @param state - Lowercase state name (matches the extracted directory name)
+ * @param tarPath - Absolute path to the .tar.gz archive
+ */
+async function processDataLoad(jobId, state, tarPath) {
+    const startTime = Date.now();
+    let locationCount = 0;
+    let cellCount = 0;
+    try {
+        // Uses execFileSync (no shell) to avoid injection risks
+        await DataLoadJob.patch(jobId, { status: 'extracting' });
+        execFileSync('tar', ['-xzf', tarPath, '-C', DATA_DIR]);
+        const stateDir = join(DATA_DIR, state);
+        if (!existsSync(stateDir)) {
+            throw new Error(`Expected directory ${state} not found after extraction`);
+        }
+        try {
+            await DataLoadJob.patch(jobId, { status: 'loading_locations' });
+            locationCount = await loadTableFiles(join(stateDir, 'Location'), Location, 'id', jobId, 'location_count');
+            await DataLoadJob.patch(jobId, { status: 'loading_cells' });
+            cellCount = await loadTableFiles(join(stateDir, 'Cell'), Cell, 'h3_index', jobId, 'cell_count');
+        }
+        finally {
+            // Always clean up the extracted folder, even if loading fails partway through
+            rmSync(stateDir, { recursive: true, force: true });
+        }
+        const durationMs = Date.now() - startTime;
+        await DataLoadJob.patch(jobId, {
+            status: 'completed',
+            location_count: locationCount,
+            cell_count: cellCount,
+            completed_at: new Date().toISOString(),
+            duration_ms: durationMs,
+        });
+    }
+    catch (err) {
+        const durationMs = Date.now() - startTime;
+        await DataLoadJob.patch(jobId, {
+            status: 'error',
+            error_message: err.message,
+            location_count: locationCount,
+            cell_count: cellCount,
+            completed_at: new Date().toISOString(),
+            duration_ms: durationMs,
+        });
+    }
+}
+/**
+ * Async bulk loading endpoint for populating Location and Cell tables from
+ * pre-packaged state data files. Validates the request, creates a DataLoadJob
+ * record for tracking, and returns the job ID immediately. The actual data
+ * extraction and loading runs in the background — callers poll the DataLoadJob
+ * table to check progress.
+ */
+export class DataLoad extends Resource {
+    /**
+     * Handles GET requests to initiate a data load job.
+     *
+     * Validates the state parameter, checks that the corresponding .tar.gz file
+     * exists, creates a DataLoadJob record, and kicks off background processing.
+     * Returns the job ID immediately so the caller can poll for progress.
+     *
+     * @param target - Harper request target containing query parameters
+     * @returns Object with jobId on success, or an error object on validation failure
+     */
+    async get(target) {
+        const state = target.get('state');
+        if (!state) {
+            return { error: 'state query parameter is required' };
+        }
+        // Normalize to lowercase to match the tar.gz filenames in the data directory
+        const stateLower = state.toLowerCase();
+        const tarPath = join(DATA_DIR, `${stateLower}.tar.gz`);
+        if (!existsSync(tarPath)) {
+            return { error: `No data file found for state: ${stateLower}` };
+        }
+        // Create the job record and return the ID to the caller immediately
+        const jobId = randomUUID();
+        await DataLoadJob.put(jobId, {
+            state: stateLower,
+            status: 'pending',
+            location_count: 0,
+            cell_count: 0,
+            started_at: new Date().toISOString(),
+        });
+        // Fire and forget — errors are captured in the job record, .catch() prevents
+        // unhandled rejection if the DataLoadJob.patch itself fails in the catch block
+        processDataLoad(jobId, stateLower, tarPath).catch(() => { });
+        return { jobId };
+    }
+}
+//# sourceMappingURL=DataLoad.js.map

package/dist/resources/DataLoad.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataLoad.js","sourceRoot":"","sources":["../../src/resources/DataLoad.ts"],"names":[],"mappings":"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"}

package/dist/resources/Geolookup.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Parses the "tiers" query param into a set of tier strings.
+ * Accepts comma-separated values ("1,3"), "all", or undefined (defaults to all tiers).
+ *
+ * @param tiersParam - Raw tiers query parameter value
+ * @returns A Set of valid tier strings, or an error object if any requested tier is invalid
+ */
+export declare function parseTiers(tiersParam: string | undefined): Set<string> | {
+    error: string;
+};
+/**
+ * Reverse geocoding resource. Given a lat/lon coordinate, finds the best matching
+ * Location at each requested tier by searching H3 cells across multiple resolutions.
+ */
+export declare class Geolookup extends Resource {
+    /**
+     * Handles GET requests. Validates lat/lon/tiers query params, then delegates
+     * to _lookup for the actual H3-based spatial search.
+     *
+     * @param target - Harper request target containing query parameters
+     * @returns Lookup results keyed by tier name, or an error object
+     */
+    get(target: any): {
+        error: string;
+    } | Promise<Record<string, any>>;
+    /**
+     * Core reverse geocoding logic.
+     *
+     * 1. Converts lat/lon to an H3 cell at the finest resolution (9).
+     * 2. Builds a candidate set of H3 indexes: the resolution-9 cell plus its parent
+     *    at each coarser resolution (8 down to 2). This is necessary because cells
+     *    are stored in compact form — a match could be at any resolution level.
+     * 3. Searches the Cell table for any matching H3 index (OR across all candidates).
+     *    Only joins to Location records for the tiers the caller requested.
+     * 4. Collects the first Location found for each requested tier. Stops early once
+     *    all requested tiers have a match.
+     *
+     * @param lat - Latitude in decimal degrees
+     * @param lon - Longitude in decimal degrees
+     * @param tiers - Set of tier strings to search for ("1", "2", "3")
+     * @returns Object keyed by tier name (place, county_subdivision, county) with matched Locations
+     */
+    _lookup(lat: number, lon: number, tiers: Set<string>): Promise<Record<string, any>>;
+}

package/dist/resources/Geolookup.js

@@ -0,0 +1,105 @@
+import { latLngToCell, cellToParent } from 'h3-js';
+import { databases } from 'harperdb';
+const { Location, Cell } = databases.geolookup;
+// Tiers map to US administrative hierarchy levels:
+//   '1' = place (city/town), '2' = county_subdivision (township/MCD), '3' = county
+const VALID_TIERS = new Set(['1', '2', '3']);
+// Fields returned for each matched Location in the lookup response
+const LOCATION_SELECT = ['id', 'tier', 'name', 'name_full', 'state_name', 'state_abbrev', 'h3_index', 'country_code', 'county_name'];
+/**
+ * Parses the "tiers" query param into a set of tier strings.
+ * Accepts comma-separated values ("1,3"), "all", or undefined (defaults to all tiers).
+ *
+ * @param tiersParam - Raw tiers query parameter value
+ * @returns A Set of valid tier strings, or an error object if any requested tier is invalid
+ */
+export function parseTiers(tiersParam) {
+    if (!tiersParam || tiersParam === 'all') {
+        return new Set(VALID_TIERS);
+    }
+    const requested = tiersParam.split(',').map(t => t.trim());
+    const invalid = requested.filter(t => !VALID_TIERS.has(t));
+    if (invalid.length > 0) {
+        return { error: `Invalid tier(s): ${invalid.join(', ')}. Valid values are 1, 2, 3, or all.` };
+    }
+    return new Set(requested);
+}
+/**
+ * Reverse geocoding resource. Given a lat/lon coordinate, finds the best matching
+ * Location at each requested tier by searching H3 cells across multiple resolutions.
+ */
+export class Geolookup extends Resource {
+    /**
+     * Handles GET requests. Validates lat/lon/tiers query params, then delegates
+     * to _lookup for the actual H3-based spatial search.
+     *
+     * @param target - Harper request target containing query parameters
+     * @returns Lookup results keyed by tier name, or an error object
+     */
+    get(target) {
+        const lat = parseFloat(target.get('lat'));
+        const lon = parseFloat(target.get('lon'));
+        if (isNaN(lat) || isNaN(lon)) {
+            return { error: 'lat and lon query parameters are required' };
+        }
+        const tiers = parseTiers(target.get('tiers'));
+        if ('error' in tiers) {
+            return tiers;
+        }
+        return this._lookup(lat, lon, tiers);
+    }
+    /**
+     * Core reverse geocoding logic.
+     *
+     * 1. Converts lat/lon to an H3 cell at the finest resolution (9).
+     * 2. Builds a candidate set of H3 indexes: the resolution-9 cell plus its parent
+     *    at each coarser resolution (8 down to 2). This is necessary because cells
+     *    are stored in compact form — a match could be at any resolution level.
+     * 3. Searches the Cell table for any matching H3 index (OR across all candidates).
+     *    Only joins to Location records for the tiers the caller requested.
+     * 4. Collects the first Location found for each requested tier. Stops early once
+     *    all requested tiers have a match.
+     *
+     * @param lat - Latitude in decimal degrees
+     * @param lon - Longitude in decimal degrees
+     * @param tiers - Set of tier strings to search for ("1", "2", "3")
+     * @returns Object keyed by tier name (place, county_subdivision, county) with matched Locations
+     */
+    async _lookup(lat, lon, tiers) {
+        const h3Index = latLngToCell(lat, lon, 9);
+        const conditions = [{ attribute: 'h3_index', value: h3Index }];
+        for (let res = 8; res >= 2; res--) {
+            conditions.push({ attribute: 'h3_index', value: cellToParent(h3Index, res) });
+        }
+        // Only select relationship joins for the tiers we care about
+        const select = ['h3_index'];
+        if (tiers.has('1'))
+            select.push({ name: 'place', select: LOCATION_SELECT });
+        if (tiers.has('2'))
+            select.push({ name: 'county_subdivision', select: LOCATION_SELECT });
+        if (tiers.has('3'))
+            select.push({ name: 'county', select: LOCATION_SELECT });
+        const result = {};
+        for await (const cell of Cell.search({
+            select,
+            conditions,
+            operator: 'or',
+        })) {
+            if (tiers.has('1') && cell.place && !result.place) {
+                result.place = cell.place;
+            }
+            if (tiers.has('2') && cell.county_subdivision && !result.county_subdivision) {
+                result.county_subdivision = cell.county_subdivision;
+            }
+            if (tiers.has('3') && cell.county && !result.county) {
+                result.county = cell.county;
+            }
+            // Early exit: stop scanning once every requested tier has been found
+            if (Object.keys(result).length === tiers.size) {
+                break;
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=Geolookup.js.map

package/dist/resources/Geolookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Geolookup.js","sourceRoot":"","sources":["../../src/resources/Geolookup.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+/** Configuration options for the Geolookup plugin, provided via `config.yaml` in the consuming application. */
+export interface GeolookupConfig {
+    /** When truthy, registers the Geolookup resource as a REST endpoint at the path specified by `geoServiceName`. Defaults to `false`. */
+    exposeGeoService?: boolean;
+    /** The URL path segment for the Geolookup endpoint (e.g. `"geo"` exposes it at `/geo`). Required when `exposeGeoService` is `true`. */
+    geoServiceName?: string;
+    /** When truthy, registers the DataLoad resource as a REST endpoint at the path specified by `dataLoadServiceName`. Defaults to `false`. */
+    exposeDataLoadService?: boolean;
+    /** The URL path segment for the DataLoad endpoint (e.g. `"dataload"` exposes it at `/dataload`). Required when `exposeDataLoadService` is `true`. */
+    dataLoadServiceName?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "geolookup-plugin",
+	"version": "0.1.0",
+	"description": "A Harper plugin for fast, tier-based reverse geocoding of US coordinates using H3 spatial indexing.",
+	"license": "Apache-2.0",
+	"type": "module",
+	"keywords": [
+		"geocoding",
+		"h3",
+		"harper",
+		"reverse-geocoding",
+		"geolookup"
+	],
+	"author": {
+		"name": "Kyle Bernhardy"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kylebernhardy/geolookup.git"
+	},
+	"engines": {
+		"node": ">=24.0.0",
+		"harperdb": ">=4.7.0"
+	},
+	"files": [
+		"dist/",
+		"schemas/",
+		"data/",
+		"config.yaml",
+		"LICENSE",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsc || true",
+		"agent:run": "npx -y @harperfast/agent@latest",
+		"agent:skills:update": "npx -y skills@latest add harperfast/skills --all --yes",
+		"start": "harperdb run .",
+		"dev": "harperdb dev .",
+		"lint": "eslint .",
+		"format": "prettier --write .",
+		"test": "node --test test/*.test.js",
+		"test:watch": "node --watch --test test/*.test.js",
+		"deploy": "dotenv -- npm run deploy:component",
+		"deploy:component": "harperdb deploy_component . restart=rolling replicated=true"
+	},
+	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"dotenv-cli": "^11.0.0",
+		"eslint": "^10.0.2",
+		"globals": "^17.4.0",
+		"harperdb": "^4.7.20",
+		"prettier": "^3.8.1"
+	},
+	"dependencies": {
+		"h3-js": "^4.4.0"
+	}
+}