lance-ts 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,195 @@
+# lance-ts
+
+**Opinionated TypeScript client for the U.S. Census Geocoder API.**
+
+Turn U.S. addresses into latitude/longitude coordinates using the free, no-key-required [Census Bureau Geocoder](https://geocoding.geo.census.gov/geocoder/) — with full TypeScript types and zero external HTTP dependencies.
+
+---
+
+## Use Case:
+
+If you're working with U.S. address data, the Census Geocoder is an extremely viable, completely free API. Backed by the official MAF/TIGER address database, and covering virtually every U.S. address, it has no posted rate limits and no API key. 
+
+### The Issue:
+
+The raw API response is verbose and awkward to work with.
+Below is the simplest possible response; a single one-line address match:
+```json
+{"result": {
+     "input": {
+          "address": {"address": "4600 Silver Hill Rd, Washington, DC 20233"},
+          "benchmark": {
+               "isDefault": true,
+               "benchmarkDescription": "Public Address Ranges - Current Benchmark",
+               "id": "4",
+               "benchmarkName": "Public_AR_Current"
+          }
+     },
+     "addressMatches": [{
+          "tigerLine": {
+               "side": "L",
+               "tigerLineId": "76355984"
+          },
+          "coordinates": {
+               "x": -76.92748724230096,
+               "y": 38.84601622386617
+          },
+          "addressComponents": {
+               "zip": "20233",
+               "streetName": "SILVER HILL",
+               "preType": "",
+               "city": "WASHINGTON",
+               "preDirection": "",
+               "suffixDirection": "",
+               "fromAddress": "4600",
+               "state": "DC",
+               "suffixType": "RD",
+               "toAddress": "4700",
+               "suffixQualifier": "",
+               "preQualifier": ""
+          },
+          "matchedAddress": "4600 SILVER HILL RD, WASHINGTON, DC, 20233"
+     }]
+}}
+```
+For applications that require lightweight & simple coordinate responses, `lance-ts` provides a clean, strongly-typed interface so you can go from address → coordinates in one call.
+
+- 🆓 **Free** — no API key, no account, no rate limits
+- 🏛️ **Official Data** — calls the U.S. Census Bureau Geocoder
+- 📦 **Lightweight** — no HTTP library dependencies; uses node-native `fetch`
+
+---
+
+## Installation
+
+```bash
+# pnpm (recommended)
+pnpm add lance-ts
+
+# npm
+npm install lance-ts
+
+# yarn
+yarn add lance-ts
+```
+
+Requires **Node.js 18+** (for native `fetch`).
+
+---
+
+## Quick Start
+
+```ts
+import { geocode } from "lance-ts";
+
+const result = await geocodeOneLineAddress(
+  "1600 Pennsylvania Avenue NW, Washington, DC 20500"
+);
+
+if (result) {
+  console.log(result.coordinates.x);  // 38.8987...
+  console.log(result.coordinates.y);  // -77.0353...
+  console.log(result.matchedAddress);  // "1600 Pennsylvania..."
+}
+```
+
+---
+
+## API
+
+### `geocode(address: string): Promise<GeocodeResult | null>`
+
+Geocodes a single one-line U.S. address. Returns `null` if no match is found.
+
+```ts
+const result = await geocode("350 Fifth Avenue, New York, NY 10118");
+// → { lat: 40.7484, lng: -73.9856, matchedAddress: "350 5TH AVE, NEW YORK, NY, 10118" }
+```
+
+**Parameters**
+
+| Name      | Type     | Description                              |
+|-----------|----------|------------------------------------------|
+| `address` | `string` | A U.S. address in one-line format        |
+
+**Returns:** `Promise<GeocodeResult | null>`
+
+---
+
+### `GeocodeResult`
+
+```ts
+type GeocodeResult = {
+  lat: number;
+  lng: number;
+  matchedAddress: string;
+};
+```
+
+---
+
+## How It Works
+
+`lance-ts` sends your address to the Census Bureau's public REST endpoint:
+
+```
+https://geocoding.geo.census.gov/geocoder/locations/onelineaddress
+```
+
+The response is parsed and normalized — extracting the matched coordinates and canonical address from the Census Bureau's nested JSON structure — and returned as a clean, typed object.
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Run tests with UI
+pnpm test --ui
+```
+
+### Project Structure
+
+```
+lance-ts/
+├── src/          # TypeScript source
+├── dist/         # Compiled output (generated)
+├── tsconfig.json
+└── package.json
+```
+
+This project uses a strict `tsconfig.json` setup including:
+
+- `strict: true`
+- `noUncheckedIndexedAccess: true`
+- `exactOptionalPropertyTypes: true`
+- `verbatimModuleSyntax: true`
+- `moduleResolution: "nodenext"`
+
+---
+
+## Limitations
+
+- U.S. addresses only
+- Coordinate results are **interpolated** from TIGER address ranges, not rooftop-precise
+- Batch geocoding (up to 10,000 addresses) is not yet implemented
+- Reverse geocoding (coordinates → address) is not yet implemented
+
+---
+
+## Resources
+
+- [Census Geocoder Web Interface](https://geocoding.geo.census.gov/geocoder/)
+- [Census Geocoder API Docs](https://www.census.gov/programs-surveys/geography/technical-documentation/complete-technical-documentation/census-geocoder.html)
+- [MAF/TIGER Database Overview](https://www.census.gov/geographies/mapping-files/time-series/geo/tiger-line-file.html)
+
+---
+
+## License
+
+ISC © [matt-the-thew](https://github.com/matt-the-thew)

package/dist/index.cjs

@@ -0,0 +1,162 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BatchAddressGeocoder: () => BatchAddressGeocoder,
+  geocodeOneLineAddress: () => geocodeOneLineAddress,
+  geocodeOneLineAddressAll: () => geocodeOneLineAddressAll
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/one-line-address.ts
+async function geocodeOneLineAddress(address) {
+  const params = new URLSearchParams({
+    address,
+    benchmark: "Public_AR_Current",
+    format: "json"
+  });
+  const url = `https://geocoding.geo.census.gov/geocoder/locations/onelineaddress?${params}`;
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+  const data = await response.json();
+  const matches = data.result?.addressMatches;
+  if (!matches?.length) {
+    console.log(`No matches found for: ${address}`);
+    return;
+  }
+  if (matches?.length > 1) {
+    console.warn(`Multiple address matches found for ${address}`);
+    for (const match of matches) {
+      console.warn(`[WARNING}: multimple matched addresses for: ${match.matchedAddress}
+      Coordinates:
+      X: ${match.coordinates["x"]}
+      Y: ${match.coordinates["y"]}
+      Consider geocodeOneLineAddressAll()`);
+    }
+  }
+  if (matches[0]) {
+    return {
+      coordinates: matches[0].coordinates,
+      matchedAddress: matches[0].matchedAddress
+    };
+  }
+}
+async function geocodeOneLineAddressAll(address) {
+  const params = new URLSearchParams({
+    address,
+    benchmark: "Public_AR_Current",
+    format: "json"
+  });
+  const url = `https://geocoding.geo.census.gov/geocoder/locations/onelineaddress?${params}`;
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+  const data = await response.json();
+  const matches = data.result?.addressMatches;
+  if (!matches?.length) {
+    console.log(`No matches found for: ${address}`);
+    return;
+  }
+  return matches;
+}
+
+// src/batch-address.ts
+var fs = __toESM(require("fs"), 1);
+var path = __toESM(require("path"), 1);
+var import_meta = {};
+var BatchAddressGeocoder = class {
+  // Set geocoder endpoint
+  url = "https://geocoding.geo.census.gov/geocoder/locations/addressbatch";
+  inputFilePath;
+  outputFilePath = "batch_coordinates.csv";
+  constructor(inputFilePath, outputFilePath) {
+    this.inputFilePath = inputFilePath;
+    if (outputFilePath) this.outputFilePath = outputFilePath;
+  }
+  /**
+   * Finds relative path for a file name
+   * @param {string} localFilePath
+   * @returns {string | undefined} the realtive file path, if exists
+   * @throws {Error} if unable to find relative path
+   */
+  _parseFilePath(localFilePath) {
+    let parsedFilePath;
+    try {
+      parsedFilePath = path.join(import_meta.dirname, localFilePath);
+    } catch (error) {
+      throw new Error(`Error parsing file path: ${error}`);
+    }
+    return parsedFilePath ? parsedFilePath : void 0;
+  }
+  /**
+   * Generates FormData from a file, according to census geocoder specs
+   * @param {string} filePath
+   * @returns {FormData} Formatted form data, converting the file into a {Blob}
+   */
+  _createFormData(filePath) {
+    const fileBuffer = fs.readFileSync(filePath);
+    if (!fileBuffer) throw new Error(`Unable to read file ${filePath}`);
+    const blob = new Blob([fileBuffer], { type: "text/plain" });
+    const formData = new FormData();
+    formData.append("addressFile", blob, path.basename(filePath));
+    formData.append("benchmark", "Public_AR_Current");
+    formData.append("returntype", "location");
+    return formData;
+  }
+  /**
+   * Sends generated FormData from blob-ified {@link inputFilePath} to Census Geocoder endpoint,
+   * and writes response to a local file based on {@link outputFilePath}.
+   * @returns {void}
+   */
+  async geocodeBatch() {
+    const formData = this._createFormData(
+      this.inputFilePath
+    );
+    if (!formData)
+      throw new Error(
+        `Error creating FormData from ${this.inputFilePath}`
+      );
+    const response = await fetch(this.url, {
+      method: "POST",
+      body: formData
+    });
+    if (!response.ok) throw new Error(`HTTP Error: ${response.status}`);
+    const responseText = await response.text();
+    fs.writeFileSync(this.outputFilePath, responseText);
+    console.log(`Saved to ${this.outputFilePath}`);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BatchAddressGeocoder,
+  geocodeOneLineAddress,
+  geocodeOneLineAddressAll
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/one-line-address.ts","../src/batch-address.ts"],"sourcesContent":["/**\n * @file Library entry point for one-line and batch geocoding functions\n * @module lance-ts\n * @author Matthew Morton\n * @see {@link https://github.com/matt-the-thew/lance-ts}\n */\nexport * from \"./one-line-address.js\";\nexport * from \"./batch-address.js\";\n","/**\n * Interface for lat/lng coordinates\n * @interface CensusCoordinates\n */\nexport interface CensusCoordinates {\n  x: number;\n  y: number;\n}\n\n/**\n * Interface for a single coordinate pair as {@type CensusCoordinates}\n * and the associated matched address, as {@type string}\n * @interface OneLineAddressMatch\n */\nexport interface OneLineAddressMatch {\n  coordinates: CensusCoordinates;\n  matchedAddress: string;\n}\n\n/**\n * Interface representing an array of {@type OneLineAddressMatch}\n * @interface OneLineAddressResult\n */\nexport interface OneLineAddressResult {\n  addressMatches: OneLineAddressMatch[];\n}\n\n/**\n * Interface for the optional result, of type {@type OneLineAddressResult}\n */\nexport interface OneLineAddressResponse {\n  result?: OneLineAddressResult;\n}\n\n/**\n * Returns the first result from whatever address matches it receives\n * @param address {string}\n * @returns {OneLineAddressMatch}\n * @throws {Error} if response status is not 200 OK\n */\nexport async function geocodeOneLineAddress(\n  address: string,\n): Promise<OneLineAddressMatch | undefined> {\n  //format parameters to use latest census data\n  const params = new URLSearchParams({\n    address,\n    benchmark: \"Public_AR_Current\",\n    format: \"json\",\n  });\n\n  const url = `https://geocoding.geo.census.gov/geocoder/locations/onelineaddress?${params}`;\n  const response: Response = await fetch(url);\n  if (!response.ok) throw new Error(`HTTP error: ${response.status}`);\n\n  // Retreives array of coordinates and string of matched addresses from API res\n  const data = (await response.json()) as OneLineAddressResponse;\n  const matches = data.result?.addressMatches;\n\n  if (!matches?.length) {\n    console.log(`No matches found for: ${address}`);\n    return;\n  }\n\n  // warns if multiple matched addresses exist for a single address\n  if (matches?.length > 1) {\n    console.warn(`Multiple address matches found for ${address}`);\n    for (const match of matches) {\n      console.warn(`[WARNING}: multimple matched addresses for: ${match.matchedAddress}\n      Coordinates:\n      X: ${match.coordinates[\"x\"]}\n      Y: ${match.coordinates[\"y\"]}\n      Consider geocodeOneLineAddressAll()`);\n    }\n  }\n\n  if (matches[0]) {\n    return {\n      coordinates: matches[0].coordinates,\n      matchedAddress: matches[0].matchedAddress,\n    };\n  }\n}\n\n/**\n * Returns entire array of {@type OneLineAddressMatch}\n * @param {string} address - The address to submit to the census geocoder\n * @returns {OneLineAddressMatch[]} | undefined\n * @throws {Error} if response status is not OK\n */\nexport async function geocodeOneLineAddressAll(\n  address: string,\n): Promise<OneLineAddressMatch[] | undefined> {\n  //format parameters to use latest census data\n  const params = new URLSearchParams({\n    address,\n    benchmark: \"Public_AR_Current\",\n    format: \"json\",\n  });\n\n  const url = `https://geocoding.geo.census.gov/geocoder/locations/onelineaddress?${params}`;\n  const response: Response = await fetch(url);\n  if (!response.ok) throw new Error(`HTTP error: ${response.status}`);\n\n  // Retreives array of coordinates and string of matched addresses from API res\n  const data = (await response.json()) as OneLineAddressResponse;\n  const matches = data.result?.addressMatches;\n\n  if (!matches?.length) {\n    console.log(`No matches found for: ${address}`);\n    return;\n  }\n\n  return matches;\n}\n","import * as fs from \"node:fs\";\nimport * as path from \"path\";\n\n/**\n * Batch geocoder session handler\n * @param {string} inputFilePath\n * @param {string} outputFilePath - @default\n */\nexport class BatchAddressGeocoder {\n  // Set geocoder endpoint\n  url = \"https://geocoding.geo.census.gov/geocoder/locations/addressbatch\";\n\n  inputFilePath: string;\n  outputFilePath: string = \"batch_coordinates.csv\";\n\n  constructor(inputFilePath: string, outputFilePath?: string) {\n    this.inputFilePath = inputFilePath;\n    if (outputFilePath) this.outputFilePath = outputFilePath;\n  }\n\n  /**\n   * Finds relative path for a file name\n   * @param {string} localFilePath\n   * @returns {string | undefined} the realtive file path, if exists\n   * @throws {Error} if unable to find relative path\n   */\n  _parseFilePath(localFilePath: string): string | undefined {\n    // create absolute directory name for fs methods\n    let parsedFilePath: string;\n    try {\n      parsedFilePath = path.join(import.meta.dirname, localFilePath);\n    } catch (error) {\n      throw new Error(`Error parsing file path: ${error}`);\n    }\n\n    return parsedFilePath ? parsedFilePath : undefined;\n  }\n\n  /**\n   * Generates FormData from a file, according to census geocoder specs\n   * @param {string} filePath\n   * @returns {FormData} Formatted form data, converting the file into a {Blob}\n   */\n  _createFormData(filePath: string): FormData | undefined {\n    const fileBuffer = fs.readFileSync(filePath);\n    if (!fileBuffer) throw new Error(`Unable to read file ${filePath}`);\n\n    const blob = new Blob([fileBuffer], { type: \"text/plain\" });\n    const formData = new FormData();\n\n    formData.append(\"addressFile\", blob, path.basename(filePath));\n    formData.append(\"benchmark\", \"Public_AR_Current\");\n    formData.append(\"returntype\", \"location\");\n\n    return formData;\n  }\n\n  /**\n   * Sends generated FormData from blob-ified {@link inputFilePath} to Census Geocoder endpoint,\n   * and writes response to a local file based on {@link outputFilePath}.\n   * @returns {void}\n   */\n  async geocodeBatch(): Promise<void> {\n    const formData: FormData | undefined = this._createFormData(\n      this.inputFilePath,\n    );\n    if (!formData)\n      throw new Error(\n        `Error creating FormData from ${this.inputFilePath}`,\n      );\n    const response = await fetch(this.url, {\n      method: \"POST\",\n      body: formData,\n    });\n    if (!response.ok) throw new Error(`HTTP Error: ${response.status}`);\n    const responseText = await response.text();\n\n    fs.writeFileSync(this.outputFilePath, responseText);\n    console.log(`Saved to ${this.outputFilePath}`);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,77 @@
+/**
+ * Interface for lat/lng coordinates
+ * @interface CensusCoordinates
+ */
+interface CensusCoordinates {
+    x: number;
+    y: number;
+}
+/**
+ * Interface for a single coordinate pair as {@type CensusCoordinates}
+ * and the associated matched address, as {@type string}
+ * @interface OneLineAddressMatch
+ */
+interface OneLineAddressMatch {
+    coordinates: CensusCoordinates;
+    matchedAddress: string;
+}
+/**
+ * Interface representing an array of {@type OneLineAddressMatch}
+ * @interface OneLineAddressResult
+ */
+interface OneLineAddressResult {
+    addressMatches: OneLineAddressMatch[];
+}
+/**
+ * Interface for the optional result, of type {@type OneLineAddressResult}
+ */
+interface OneLineAddressResponse {
+    result?: OneLineAddressResult;
+}
+/**
+ * Returns the first result from whatever address matches it receives
+ * @param address {string}
+ * @returns {OneLineAddressMatch}
+ * @throws {Error} if response status is not 200 OK
+ */
+declare function geocodeOneLineAddress(address: string): Promise<OneLineAddressMatch | undefined>;
+/**
+ * Returns entire array of {@type OneLineAddressMatch}
+ * @param {string} address - The address to submit to the census geocoder
+ * @returns {OneLineAddressMatch[]} | undefined
+ * @throws {Error} if response status is not OK
+ */
+declare function geocodeOneLineAddressAll(address: string): Promise<OneLineAddressMatch[] | undefined>;
+
+/**
+ * Batch geocoder session handler
+ * @param {string} inputFilePath
+ * @param {string} outputFilePath - @default
+ */
+declare class BatchAddressGeocoder {
+    url: string;
+    inputFilePath: string;
+    outputFilePath: string;
+    constructor(inputFilePath: string, outputFilePath?: string);
+    /**
+     * Finds relative path for a file name
+     * @param {string} localFilePath
+     * @returns {string | undefined} the realtive file path, if exists
+     * @throws {Error} if unable to find relative path
+     */
+    _parseFilePath(localFilePath: string): string | undefined;
+    /**
+     * Generates FormData from a file, according to census geocoder specs
+     * @param {string} filePath
+     * @returns {FormData} Formatted form data, converting the file into a {Blob}
+     */
+    _createFormData(filePath: string): FormData | undefined;
+    /**
+     * Sends generated FormData from blob-ified {@link inputFilePath} to Census Geocoder endpoint,
+     * and writes response to a local file based on {@link outputFilePath}.
+     * @returns {void}
+     */
+    geocodeBatch(): Promise<void>;
+}
+
+export { BatchAddressGeocoder, type CensusCoordinates, type OneLineAddressMatch, type OneLineAddressResponse, type OneLineAddressResult, geocodeOneLineAddress, geocodeOneLineAddressAll };

package/dist/index.d.ts

@@ -1,9 +1,77 @@
 /**
- * @file Library entry point for one-line and batch geocoding functions
- * @module lance-ts
- * @author Matthew Morton
- * @see {@link https://github.com/matt-the-thew/lance-ts}
- */
-export * from "./one-line-address.js";
-export * from "./batch-address.js";
-//# sourceMappingURL=index.d.ts.map
+ * Interface for lat/lng coordinates
+ * @interface CensusCoordinates
+ */
+interface CensusCoordinates {
+    x: number;
+    y: number;
+}
+/**
+ * Interface for a single coordinate pair as {@type CensusCoordinates}
+ * and the associated matched address, as {@type string}
+ * @interface OneLineAddressMatch
+ */
+interface OneLineAddressMatch {
+    coordinates: CensusCoordinates;
+    matchedAddress: string;
+}
+/**
+ * Interface representing an array of {@type OneLineAddressMatch}
+ * @interface OneLineAddressResult
+ */
+interface OneLineAddressResult {
+    addressMatches: OneLineAddressMatch[];
+}
+/**
+ * Interface for the optional result, of type {@type OneLineAddressResult}
+ */
+interface OneLineAddressResponse {
+    result?: OneLineAddressResult;
+}
+/**
+ * Returns the first result from whatever address matches it receives
+ * @param address {string}
+ * @returns {OneLineAddressMatch}
+ * @throws {Error} if response status is not 200 OK
+ */
+declare function geocodeOneLineAddress(address: string): Promise<OneLineAddressMatch | undefined>;
+/**
+ * Returns entire array of {@type OneLineAddressMatch}
+ * @param {string} address - The address to submit to the census geocoder
+ * @returns {OneLineAddressMatch[]} | undefined
+ * @throws {Error} if response status is not OK
+ */
+declare function geocodeOneLineAddressAll(address: string): Promise<OneLineAddressMatch[] | undefined>;
+
+/**
+ * Batch geocoder session handler
+ * @param {string} inputFilePath
+ * @param {string} outputFilePath - @default
+ */
+declare class BatchAddressGeocoder {
+    url: string;
+    inputFilePath: string;
+    outputFilePath: string;
+    constructor(inputFilePath: string, outputFilePath?: string);
+    /**
+     * Finds relative path for a file name
+     * @param {string} localFilePath
+     * @returns {string | undefined} the realtive file path, if exists
+     * @throws {Error} if unable to find relative path
+     */
+    _parseFilePath(localFilePath: string): string | undefined;
+    /**
+     * Generates FormData from a file, according to census geocoder specs
+     * @param {string} filePath
+     * @returns {FormData} Formatted form data, converting the file into a {Blob}
+     */
+    _createFormData(filePath: string): FormData | undefined;
+    /**
+     * Sends generated FormData from blob-ified {@link inputFilePath} to Census Geocoder endpoint,
+     * and writes response to a local file based on {@link outputFilePath}.
+     * @returns {void}
+     */
+    geocodeBatch(): Promise<void>;
+}
+
+export { BatchAddressGeocoder, type CensusCoordinates, type OneLineAddressMatch, type OneLineAddressResponse, type OneLineAddressResult, geocodeOneLineAddress, geocodeOneLineAddressAll };

package/dist/index.js

@@ -1,9 +1,122 @@
-/**
- * @file Library entry point for one-line and batch geocoding functions
- * @module lance-ts
- * @author Matthew Morton
- * @see {@link https://github.com/matt-the-thew/lance-ts}
- */
-export * from "./one-line-address.js";
-export * from "./batch-address.js";
+// src/one-line-address.ts
+async function geocodeOneLineAddress(address) {
+  const params = new URLSearchParams({
+    address,
+    benchmark: "Public_AR_Current",
+    format: "json"
+  });
+  const url = `https://geocoding.geo.census.gov/geocoder/locations/onelineaddress?${params}`;
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+  const data = await response.json();
+  const matches = data.result?.addressMatches;
+  if (!matches?.length) {
+    console.log(`No matches found for: ${address}`);
+    return;
+  }
+  if (matches?.length > 1) {
+    console.warn(`Multiple address matches found for ${address}`);
+    for (const match of matches) {
+      console.warn(`[WARNING}: multimple matched addresses for: ${match.matchedAddress}
+      Coordinates:
+      X: ${match.coordinates["x"]}
+      Y: ${match.coordinates["y"]}
+      Consider geocodeOneLineAddressAll()`);
+    }
+  }
+  if (matches[0]) {
+    return {
+      coordinates: matches[0].coordinates,
+      matchedAddress: matches[0].matchedAddress
+    };
+  }
+}
+async function geocodeOneLineAddressAll(address) {
+  const params = new URLSearchParams({
+    address,
+    benchmark: "Public_AR_Current",
+    format: "json"
+  });
+  const url = `https://geocoding.geo.census.gov/geocoder/locations/onelineaddress?${params}`;
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
+  const data = await response.json();
+  const matches = data.result?.addressMatches;
+  if (!matches?.length) {
+    console.log(`No matches found for: ${address}`);
+    return;
+  }
+  return matches;
+}
+
+// src/batch-address.ts
+import * as fs from "fs";
+import * as path from "path";
+var BatchAddressGeocoder = class {
+  // Set geocoder endpoint
+  url = "https://geocoding.geo.census.gov/geocoder/locations/addressbatch";
+  inputFilePath;
+  outputFilePath = "batch_coordinates.csv";
+  constructor(inputFilePath, outputFilePath) {
+    this.inputFilePath = inputFilePath;
+    if (outputFilePath) this.outputFilePath = outputFilePath;
+  }
+  /**
+   * Finds relative path for a file name
+   * @param {string} localFilePath
+   * @returns {string | undefined} the realtive file path, if exists
+   * @throws {Error} if unable to find relative path
+   */
+  _parseFilePath(localFilePath) {
+    let parsedFilePath;
+    try {
+      parsedFilePath = path.join(import.meta.dirname, localFilePath);
+    } catch (error) {
+      throw new Error(`Error parsing file path: ${error}`);
+    }
+    return parsedFilePath ? parsedFilePath : void 0;
+  }
+  /**
+   * Generates FormData from a file, according to census geocoder specs
+   * @param {string} filePath
+   * @returns {FormData} Formatted form data, converting the file into a {Blob}
+   */
+  _createFormData(filePath) {
+    const fileBuffer = fs.readFileSync(filePath);
+    if (!fileBuffer) throw new Error(`Unable to read file ${filePath}`);
+    const blob = new Blob([fileBuffer], { type: "text/plain" });
+    const formData = new FormData();
+    formData.append("addressFile", blob, path.basename(filePath));
+    formData.append("benchmark", "Public_AR_Current");
+    formData.append("returntype", "location");
+    return formData;
+  }
+  /**
+   * Sends generated FormData from blob-ified {@link inputFilePath} to Census Geocoder endpoint,
+   * and writes response to a local file based on {@link outputFilePath}.
+   * @returns {void}
+   */
+  async geocodeBatch() {
+    const formData = this._createFormData(
+      this.inputFilePath
+    );
+    if (!formData)
+      throw new Error(
+        `Error creating FormData from ${this.inputFilePath}`
+      );
+    const response = await fetch(this.url, {
+      method: "POST",
+      body: formData
+    });
+    if (!response.ok) throw new Error(`HTTP Error: ${response.status}`);
+    const responseText = await response.text();
+    fs.writeFileSync(this.outputFilePath, responseText);
+    console.log(`Saved to ${this.outputFilePath}`);
+  }
+};
+export {
+  BatchAddressGeocoder,
+  geocodeOneLineAddress,
+  geocodeOneLineAddressAll
+};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC"}
+{"version":3,"sources":["../src/one-line-address.ts","../src/batch-address.ts"],"sourcesContent":["/**\n * Interface for lat/lng coordinates\n * @interface CensusCoordinates\n */\nexport interface CensusCoordinates {\n  x: number;\n  y: number;\n}\n\n/**\n * Interface for a single coordinate pair as {@type CensusCoordinates}\n * and the associated matched address, as {@type string}\n * @interface OneLineAddressMatch\n */\nexport interface OneLineAddressMatch {\n  coordinates: CensusCoordinates;\n  matchedAddress: string;\n}\n\n/**\n * Interface representing an array of {@type OneLineAddressMatch}\n * @interface OneLineAddressResult\n */\nexport interface OneLineAddressResult {\n  addressMatches: OneLineAddressMatch[];\n}\n\n/**\n * Interface for the optional result, of type {@type OneLineAddressResult}\n */\nexport interface OneLineAddressResponse {\n  result?: OneLineAddressResult;\n}\n\n/**\n * Returns the first result from whatever address matches it receives\n * @param address {string}\n * @returns {OneLineAddressMatch}\n * @throws {Error} if response status is not 200 OK\n */\nexport async function geocodeOneLineAddress(\n  address: string,\n): Promise<OneLineAddressMatch | undefined> {\n  //format parameters to use latest census data\n  const params = new URLSearchParams({\n    address,\n    benchmark: \"Public_AR_Current\",\n    format: \"json\",\n  });\n\n  const url = `https://geocoding.geo.census.gov/geocoder/locations/onelineaddress?${params}`;\n  const response: Response = await fetch(url);\n  if (!response.ok) throw new Error(`HTTP error: ${response.status}`);\n\n  // Retreives array of coordinates and string of matched addresses from API res\n  const data = (await response.json()) as OneLineAddressResponse;\n  const matches = data.result?.addressMatches;\n\n  if (!matches?.length) {\n    console.log(`No matches found for: ${address}`);\n    return;\n  }\n\n  // warns if multiple matched addresses exist for a single address\n  if (matches?.length > 1) {\n    console.warn(`Multiple address matches found for ${address}`);\n    for (const match of matches) {\n      console.warn(`[WARNING}: multimple matched addresses for: ${match.matchedAddress}\n      Coordinates:\n      X: ${match.coordinates[\"x\"]}\n      Y: ${match.coordinates[\"y\"]}\n      Consider geocodeOneLineAddressAll()`);\n    }\n  }\n\n  if (matches[0]) {\n    return {\n      coordinates: matches[0].coordinates,\n      matchedAddress: matches[0].matchedAddress,\n    };\n  }\n}\n\n/**\n * Returns entire array of {@type OneLineAddressMatch}\n * @param {string} address - The address to submit to the census geocoder\n * @returns {OneLineAddressMatch[]} | undefined\n * @throws {Error} if response status is not OK\n */\nexport async function geocodeOneLineAddressAll(\n  address: string,\n): Promise<OneLineAddressMatch[] | undefined> {\n  //format parameters to use latest census data\n  const params = new URLSearchParams({\n    address,\n    benchmark: \"Public_AR_Current\",\n    format: \"json\",\n  });\n\n  const url = `https://geocoding.geo.census.gov/geocoder/locations/onelineaddress?${params}`;\n  const response: Response = await fetch(url);\n  if (!response.ok) throw new Error(`HTTP error: ${response.status}`);\n\n  // Retreives array of coordinates and string of matched addresses from API res\n  const data = (await response.json()) as OneLineAddressResponse;\n  const matches = data.result?.addressMatches;\n\n  if (!matches?.length) {\n    console.log(`No matches found for: ${address}`);\n    return;\n  }\n\n  return matches;\n}\n","import * as fs from \"node:fs\";\nimport * as path from \"path\";\n\n/**\n * Batch geocoder session handler\n * @param {string} inputFilePath\n * @param {string} outputFilePath - @default\n */\nexport class BatchAddressGeocoder {\n  // Set geocoder endpoint\n  url = \"https://geocoding.geo.census.gov/geocoder/locations/addressbatch\";\n\n  inputFilePath: string;\n  outputFilePath: string = \"batch_coordinates.csv\";\n\n  constructor(inputFilePath: string, outputFilePath?: string) {\n    this.inputFilePath = inputFilePath;\n    if (outputFilePath) this.outputFilePath = outputFilePath;\n  }\n\n  /**\n   * Finds relative path for a file name\n   * @param {string} localFilePath\n   * @returns {string | undefined} the realtive file path, if exists\n   * @throws {Error} if unable to find relative path\n   */\n  _parseFilePath(localFilePath: string): string | undefined {\n    // create absolute directory name for fs methods\n    let parsedFilePath: string;\n    try {\n      parsedFilePath = path.join(import.meta.dirname, localFilePath);\n    } catch (error) {\n      throw new Error(`Error parsing file path: ${error}`);\n    }\n\n    return parsedFilePath ? parsedFilePath : undefined;\n  }\n\n  /**\n   * Generates FormData from a file, according to census geocoder specs\n   * @param {string} filePath\n   * @returns {FormData} Formatted form data, converting the file into a {Blob}\n   */\n  _createFormData(filePath: string): FormData | undefined {\n    const fileBuffer = fs.readFileSync(filePath);\n    if (!fileBuffer) throw new Error(`Unable to read file ${filePath}`);\n\n    const blob = new Blob([fileBuffer], { type: \"text/plain\" });\n    const formData = new FormData();\n\n    formData.append(\"addressFile\", blob, path.basename(filePath));\n    formData.append(\"benchmark\", \"Public_AR_Current\");\n    formData.append(\"returntype\", \"location\");\n\n    return formData;\n  }\n\n  /**\n   * Sends generated FormData from blob-ified {@link inputFilePath} to Census Geocoder endpoint,\n   * and writes response to a local file based on {@link outputFilePath}.\n   * @returns {void}\n   */\n  async geocodeBatch(): Promise<void> {\n    const formData: FormData | undefined = this._createFormData(\n      this.inputFilePath,\n    );\n    if (!formData)\n      throw new Error(\n        `Error creating FormData from ${this.inputFilePath}`,\n      );\n    const response = await fetch(this.url, {\n      method: \"POST\",\n      body: formData,\n    });\n    if (!response.ok) throw new Error(`HTTP Error: ${response.status}`);\n    const responseText = await response.text();\n\n    fs.writeFileSync(this.outputFilePath, responseText);\n    console.log(`Saved to ${this.outputFilePath}`);\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,37 +1,44 @@
 {
   "name": "lance-ts",
-  "version": "1.0.0",
-  "description": "Lat/Lng from Address via National Census Endpoint",
+  "version": "1.0.1",
+  "description": "Lat/Long from National Census Endpoint. An opinionated, blazingingly fast geocoding library.",
   "type": "module",
-  "main": "index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/esm/index.js",
-      "types": "./dist/index.js",
-      "require": "./dist/cjs/index.js"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
-  "files": [
-    "dist"
-  ],
   "scripts": {
     "test": "vitest",
-    "build": "tsc",
-    "prepublishOnly": "pnpm run build"
+    "test:ui": "vitest --ui",
+    "type-check": "tsc --noEmit",
+    "build": "tsup",
+    "clean": "rm -rf ./dist"
   },
-  "keywords": [],
-  "author": "",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "geocoding",
+    "gps",
+    "geography",
+    "geospatial",
+    "coordinates"
+  ],
+  "author": "Matthew Morton <mmortondev@gmail.com>",
   "license": "ISC",
-  "packageManager": "pnpm@10.30.3",
+  "packageManager": "pnpm@11.5.2",
   "devDependencies": {
-    "@types/node": "^25.9.1",
-    "@vitest/ui": "4.1.7",
+    "@types/node": "^25.9.2",
+    "@vitest/ui": "4.1.8",
+    "memfs": "^4.57.6",
     "publint": "^0.3.21",
     "tsup": "^8.5.1",
-    "typescript": "^6.0.3"
-  },
-  "dependencies": {
-    "memfs": "^4.57.2",
-    "vitest": "^4.1.7"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
   }
 }

package/dist/batch-address.d.ts

@@ -1,31 +0,0 @@
-/**
- * Batch geocoder session handler
- * @param {string} inputFilePath
- * @param {string} outputFilePath - @default
- */
-export declare class BatchAddressGeocoder {
-    url: string;
-    inputFilePath: string;
-    outputFilePath: string;
-    constructor(inputFilePath: string, outputFilePath?: string);
-    /**
-     * Finds relative path for a file name
-     * @param {string} localFilePath
-     * @returns {string | undefined} the realtive file path, if exists
-     * @throws {Error} if unable to find relative path
-     */
-    _parseFilePath(localFilePath: string): string | undefined;
-    /**
-     * Generates FormData from a file, according to census geocoder specs
-     * @param {string} filePath
-     * @returns {FormData} Formatted form data, converting the file into a {Blob}
-     */
-    _createFormData(filePath: string): FormData | undefined;
-    /**
-     * Sends generated FormData from blob-ified {@link inputFilePath} to Census Geocoder endpoint,
-     * and writes response to a local file based on {@link outputFilePath}.
-     * @returns {void}
-     */
-    geocodeBatch(): Promise<void>;
-}
-//# sourceMappingURL=batch-address.d.ts.map

package/dist/batch-address.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"batch-address.d.ts","sourceRoot":"","sources":["../src/batch-address.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,qBAAa,oBAAoB;IAE/B,GAAG,SAAsE;IAEzE,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAA2B;gBAErC,aAAa,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM;IAK1D;;;;;OAKG;IACH,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAYzD;;;;OAIG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAcvD;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;CAkBpC"}

package/dist/batch-address.js

@@ -1,70 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "path";
-/**
- * Batch geocoder session handler
- * @param {string} inputFilePath
- * @param {string} outputFilePath - @default
- */
-export class BatchAddressGeocoder {
-    constructor(inputFilePath, outputFilePath) {
-        // Set geocoder endpoint
-        this.url = "https://geocoding.geo.census.gov/geocoder/locations/addressbatch";
-        this.outputFilePath = "batch_coordinates.csv";
-        this.inputFilePath = inputFilePath;
-        if (outputFilePath)
-            this.outputFilePath = outputFilePath;
-    }
-    /**
-     * Finds relative path for a file name
-     * @param {string} localFilePath
-     * @returns {string | undefined} the realtive file path, if exists
-     * @throws {Error} if unable to find relative path
-     */
-    _parseFilePath(localFilePath) {
-        // create absolute directory name for fs methods
-        let parsedFilePath;
-        try {
-            parsedFilePath = path.join(import.meta.dirname, localFilePath);
-        }
-        catch (error) {
-            throw new Error(`Error parsing file path: ${error}`);
-        }
-        return parsedFilePath ? parsedFilePath : undefined;
-    }
-    /**
-     * Generates FormData from a file, according to census geocoder specs
-     * @param {string} filePath
-     * @returns {FormData} Formatted form data, converting the file into a {Blob}
-     */
-    _createFormData(filePath) {
-        const fileBuffer = fs.readFileSync(filePath);
-        if (!fileBuffer)
-            throw new Error(`Unable to read file ${filePath}`);
-        const blob = new Blob([fileBuffer], { type: "text/plain" });
-        const formData = new FormData();
-        formData.append("addressFile", blob, path.basename(filePath));
-        formData.append("benchmark", "Public_AR_Current");
-        formData.append("returntype", "location");
-        return formData;
-    }
-    /**
-     * Sends generated FormData from blob-ified {@link inputFilePath} to Census Geocoder endpoint,
-     * and writes response to a local file based on {@link outputFilePath}.
-     * @returns {void}
-     */
-    async geocodeBatch() {
-        const formData = this._createFormData(this.inputFilePath);
-        if (!formData)
-            throw new Error(`Error creating FormData from ${this.inputFilePath}`);
-        const response = await fetch(this.url, {
-            method: "POST",
-            body: formData,
-        });
-        if (!response.ok)
-            throw new Error(`HTTP Error: ${response.status}`);
-        const responseText = await response.text();
-        fs.writeFileSync(this.outputFilePath, responseText);
-        console.log(`Saved to ${this.outputFilePath}`);
-    }
-}
-//# sourceMappingURL=batch-address.js.map

package/dist/batch-address.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"batch-address.js","sourceRoot":"","sources":["../src/batch-address.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAI7B;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IAO/B,YAAY,aAAqB,EAAE,cAAuB;QAN1D,wBAAwB;QACxB,QAAG,GAAG,kEAAkE,CAAC;QAGzE,mBAAc,GAAW,uBAAuB,CAAC;QAG/C,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,cAAc;YAAE,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IAC3D,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,aAAqB;QAClC,gDAAgD;QAChD,IAAI,cAAsB,CAAC;QAC3B,IAAI,CAAC;YACH,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,EAAE,CAAC,CAAC;QACvD,CAAC;QAED,OAAO,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC;IACrD,CAAC;IAED;;;;OAIG;IACH,eAAe,CAAC,QAAgB;QAC9B,MAAM,UAAU,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC7C,IAAI,CAAC,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,QAAQ,EAAE,CAAC,CAAC;QAEpE,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;QAC5D,MAAM,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAC;QAEhC,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC9D,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAC;QAClD,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAE1C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY;QAChB,MAAM,QAAQ,GAAyB,IAAI,CAAC,eAAe,CACzD,IAAI,CAAC,aAAa,CACnB,CAAC;QACF,IAAI,CAAC,QAAQ;YACX,MAAM,IAAI,KAAK,CACb,gCAAgC,IAAI,CAAC,aAAa,EAAE,CACrD,CAAC;QACJ,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE;YACrC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,QAAQ;SACf,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,eAAe,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QACpE,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QAE3C,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;QACpD,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;IACjD,CAAC;CACF"}

package/dist/batch-address.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=batch-address.test.d.ts.map

package/dist/batch-address.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"batch-address.test.d.ts","sourceRoot":"","sources":["../src/batch-address.test.ts"],"names":[],"mappings":""}

package/dist/batch-address.test.js

@@ -1,98 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { fs, vol } from "memfs";
-import * as path from "path";
-vi.mock("node:fs", async () => {
-    const { fs } = await import("memfs");
-    return fs;
-});
-//import BatchAddressGeocoder AFTER fs is mocked
-//so it initializes pointed at mocked module
-import { BatchAddressGeocoder } from "./batch-address.js";
-describe("BatchAddressGeocoder", () => {
-    let geocoder;
-    // set up memfs dir and file
-    const mockFilePath = "/out/mockfile.csv";
-    // mock function to replace fetch
-    const fetchMock = vi.fn();
-    // set test class function
-    beforeEach(() => {
-        // make fetch mock func globally available
-        vi.stubGlobal("fetch", fetchMock);
-        // reset the state of in-memory fs
-        vol.reset();
-        //generate entire filetree
-        vol.mkdirSync("/out", { recursive: true });
-        //initialize geocoder
-        geocoder = new BatchAddressGeocoder("");
-    });
-    afterEach(() => {
-        vi.unstubAllGlobals();
-        vi.resetAllMocks();
-    });
-    it("initializes with the correct endpoint", () => {
-        expect(geocoder.url).toEqual("https://geocoding.geo.census.gov/geocoder/locations/addressbatch");
-    });
-    describe("_parseFilePath", () => {
-        it("correctly parses the absolute file path", () => {
-            //generate mockFile
-            vol.writeFileSync(mockFilePath, "this is some data");
-            //point geocoder at mock file
-            geocoder.inputFilePath = mockFilePath;
-            // get absolute path from BatchAddressGeocoder
-            const parsedPath = geocoder._parseFilePath(geocoder.inputFilePath);
-            // it should exist
-            expect(parsedPath);
-            if (parsedPath) {
-                // it should be absolute
-                expect(path.isAbsolute(parsedPath));
-            }
-        });
-    });
-    describe("_createFormData", async () => {
-        it("generates accurate form data", async () => {
-            //initialize and write to mock file
-            const mockFilePath = "/mockfile.csv";
-            vol.writeFileSync(mockFilePath, "this is some data");
-            //point geocoder at mocked file
-            geocoder.inputFilePath = mockFilePath;
-            // generate form data
-            const formData = geocoder._createFormData(geocoder.inputFilePath);
-            // the file field should exist
-            expect(formData.get("addressFile")).toBeDefined();
-            // it should generate a blob
-            const fileField = formData.get("addressFile");
-            expect(fileField).toBeInstanceOf(Blob);
-            // it should hold data
-            expect(fileField.size).toBeGreaterThan(0);
-            // it should be text/plain
-            expect(fileField.type).toBe("text/plain");
-            // content should be accurate
-            const text = await fileField.text();
-            expect(text).toBe("this is some data");
-        });
-    });
-    describe("geocodeBatch", async () => {
-        it("returns correct data in .csv format", async () => {
-            const fetchSpy = vi.spyOn(global, "fetch");
-            //initialize and write to mock file
-            vol.writeFileSync(mockFilePath, "FIELD 1, FIELD 2, FIELD 3, FIELD 4");
-            const geocoder = new BatchAddressGeocoder(mockFilePath, "/out/output.csv");
-            const geocodeBatchSpy = vi.spyOn(geocoder, "geocodeBatch");
-            //mock file blob response
-            fetchMock.mockResolvedValue({
-                ok: true,
-                status: 200,
-                text: () => Promise.resolve("FIELD 1, FIELD 2, FIELD 3, FIELD 4"),
-            });
-            await geocoder.geocodeBatch();
-            //geocode function should be called once
-            expect(geocodeBatchSpy).toHaveBeenCalledOnce();
-            //output file should exist
-            expect(fs.existsSync("/out/output.csv")).toBeTruthy;
-            //fetch should have been called once
-            expect(fetchSpy).toHaveBeenCalledOnce();
-            expect(fs.readFileSync("/out/output.csv", "utf-8")).toContain("FIELD 1, FIELD 2, FIELD 3, FIELD 4");
-        });
-    });
-});
-//# sourceMappingURL=batch-address.test.js.map

package/dist/batch-address.test.js.map

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

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC"}

package/dist/one-line-address.d.ts

@@ -1,45 +0,0 @@
-/**
- * Interface for lat/lng coordinates
- * @interface CensusCoordinates
- */
-export interface CensusCoordinates {
-    x: number;
-    y: number;
-}
-/**
- * Interface for a single coordinate pair as {@type CensusCoordinates}
- * and the associated matched address, as {@type string}
- * @interface OneLineAddressMatch
- */
-export interface OneLineAddressMatch {
-    coordinates: CensusCoordinates;
-    matchedAddress: string;
-}
-/**
- * Interface representing an array of {@type OneLineAddressMatch}
- * @interface OneLineAddressResult
- */
-export interface OneLineAddressResult {
-    addressMatches: OneLineAddressMatch[];
-}
-/**
- * Interface for the optional result, of type {@type OneLineAddressResult}
- */
-export interface OneLineAddressResponse {
-    result?: OneLineAddressResult;
-}
-/**
- * Returns the first result from whatever address matches it receives
- * @param address {string}
- * @returns {OneLineAddressMatch}
- * @throws {Error} if response status is not OK
- */
-export declare function geocodeOneLineAddress(address: string): Promise<OneLineAddressMatch | undefined>;
-/**
- * Returns entire array of {@type OneLineAddressMatch}
- * @param {string} address - The address to submit to the census geocoder
- * @returns {OneLineAddressMatch[]} | undefined
- * @throws {Error} if response status is not OK
- */
-export declare function geocodeOneLineAddressAll(address: string): Promise<OneLineAddressMatch[] | undefined>;
-//# sourceMappingURL=one-line-address.d.ts.map

package/dist/one-line-address.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"one-line-address.d.ts","sourceRoot":"","sources":["../src/one-line-address.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,mBAAmB,EAAE,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAkC1C;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,EAAE,GAAG,SAAS,CAAC,CAsB5C"}

package/dist/one-line-address.js

@@ -1,64 +0,0 @@
-/**
- * Returns the first result from whatever address matches it receives
- * @param address {string}
- * @returns {OneLineAddressMatch}
- * @throws {Error} if response status is not OK
- */
-export async function geocodeOneLineAddress(address) {
-    //format parameters to use latest census data
-    const params = new URLSearchParams({
-        address,
-        benchmark: "Public_AR_Current",
-        format: "json",
-    });
-    const url = `https://geocoding.geo.census.gov/geocoder/locations/onelineaddress?${params}`;
-    const response = await fetch(url);
-    if (!response.ok)
-        throw new Error(`HTTP error: ${response.status}`);
-    // Retreives array of coordinates and string of matched addresses from API res
-    const data = (await response.json());
-    const matches = data.result?.addressMatches;
-    if (!matches?.length) {
-        console.log(`No matches found for: ${address}`);
-        return;
-    }
-    // warns if multiple matched addresses exist for a single address
-    if (matches?.length > 1) {
-        console.warn(`Multiple address matches found for ${address}`);
-        for (const match of matches) {
-            console.warn(`[WARNING}: multimple matched addresses for: ${match.matchedAddress}
-      Coordinates:
-      X: ${match.coordinates["x"]}
-      Y: ${match.coordinates["y"]}
-      Consider geocodeOneLineAddressAll()`);
-        }
-    }
-    return matches[0];
-}
-/**
- * Returns entire array of {@type OneLineAddressMatch}
- * @param {string} address - The address to submit to the census geocoder
- * @returns {OneLineAddressMatch[]} | undefined
- * @throws {Error} if response status is not OK
- */
-export async function geocodeOneLineAddressAll(address) {
-    //format parameters to use latest census data
-    const params = new URLSearchParams({
-        address,
-        benchmark: "Public_AR_Current",
-        format: "json",
-    });
-    const url = `https://geocoding.geo.census.gov/geocoder/locations/onelineaddress?${params}`;
-    const response = await fetch(url);
-    if (!response.ok)
-        throw new Error(`HTTP error: ${response.status}`);
-    // Retreives array of coordinates and string of matched addresses from API res
-    const data = (await response.json());
-    const matches = data.result?.addressMatches;
-    if (!matches?.length) {
-        console.log(`No matches found for: ${address}`);
-        return;
-    }
-    return matches;
-}
-//# sourceMappingURL=one-line-address.js.map

package/dist/one-line-address.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"one-line-address.js","sourceRoot":"","sources":["../src/one-line-address.ts"],"names":[],"mappings":"AAkCA;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAAe;IAEf,6CAA6C;IAC7C,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;QACjC,OAAO;QACP,SAAS,EAAE,mBAAmB;QAC9B,MAAM,EAAE,MAAM;KACf,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,sEAAsE,MAAM,EAAE,CAAC;IAC3F,MAAM,QAAQ,GAAa,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5C,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,eAAe,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAEpE,8EAA8E;IAC9E,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA2B,CAAC;IAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC;IAE5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;QACrB,OAAO,CAAC,GAAG,CAAC,yBAAyB,OAAO,EAAE,CAAC,CAAC;QAChD,OAAO;IACT,CAAC;IAED,iEAAiE;IACjE,IAAI,OAAO,EAAE,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,IAAI,CAAC,sCAAsC,OAAO,EAAE,CAAC,CAAC;QAC9D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,+CAA+C,KAAK,CAAC,cAAc;;WAE3E,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC;WACtB,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC;0CACS,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,OAAe;IAEf,6CAA6C;IAC7C,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;QACjC,OAAO;QACP,SAAS,EAAE,mBAAmB;QAC9B,MAAM,EAAE,MAAM;KACf,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,sEAAsE,MAAM,EAAE,CAAC;IAC3F,MAAM,QAAQ,GAAa,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5C,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,eAAe,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAEpE,8EAA8E;IAC9E,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA2B,CAAC;IAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC;IAE5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;QACrB,OAAO,CAAC,GAAG,CAAC,yBAAyB,OAAO,EAAE,CAAC,CAAC;QAChD,OAAO;IACT,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/one-line-address.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=one-line-address.test.d.ts.map

package/dist/one-line-address.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"one-line-address.test.d.ts","sourceRoot":"","sources":["../src/one-line-address.test.ts"],"names":[],"mappings":""}

package/dist/one-line-address.test.js

@@ -1,112 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { geocodeOneLineAddress, geocodeOneLineAddressAll, } from "./one-line-address.js";
-// create mocking function
-const fetchMock = vi.fn();
-beforeEach(() => {
-    // substitute mocking function for node "fetch"
-    vi.stubGlobal("fetch", fetchMock);
-});
-afterEach(() => {
-    // reset everything after testing
-    vi.unstubAllGlobals();
-    vi.resetAllMocks();
-});
-describe("geocodeOneLineAddress", () => {
-    it("returns lat/lng coordinates when response includes a match", async () => {
-        fetchMock.mockResolvedValue({
-            ok: true,
-            json: async () => ({
-                result: {
-                    addressMatches: [
-                        {
-                            coordinates: { x: -77.0365, y: 38.8977 },
-                            matchedAddress: "1600 Pennsylvania Ave NW, Washington, DC",
-                        },
-                    ],
-                },
-            }),
-        });
-        const result = await geocodeOneLineAddress("1600 Pennsylvania Ave NW, Washington, DC");
-        //it should exist
-        expect(result).toBeTruthy();
-        //it should have correct data
-        expect(result?.coordinates).toEqual({
-            x: -77.0365,
-            y: 38.8977,
-        });
-        expect(result?.matchedAddress).toEqual("1600 Pennsylvania Ave NW, Washington, DC");
-        //it should call fetch once per response
-        expect(fetchMock).toHaveBeenCalledOnce();
-    });
-    it("warns when multiple address matches exist", async () => {
-        //spy on warn output stream
-        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => { });
-        //set up mocked fetch result with multiple entires
-        fetchMock.mockResolvedValue({
-            ok: true,
-            json: async () => ({
-                result: {
-                    addressMatches: [
-                        {
-                            coordinates: { x: -77.0365, y: 38.8977 },
-                            matchedAddress: "1600 Pennsylvania Ave NW, Washington, DC",
-                        },
-                        {
-                            coordinates: { x: -78.0, y: 40.0 },
-                            matchedAddress: "1602 Pennsylvania Ave NW, Washington, DC",
-                        },
-                    ],
-                },
-            }),
-        });
-        const result = await geocodeOneLineAddress("1600 Pennsylvania Ave NW, Washington, DC");
-        //it should exist
-        expect(result).toBeTruthy;
-        //it should raise a warning
-        expect(warnSpy).toHaveBeenCalled();
-        //it should raise the correct warning
-        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("Consider geocodeOneLineAddressAll()"));
-    });
-});
-describe("geocodeOneLineAddressAll", () => {
-    it("returns array of all matched addresses", async () => {
-        fetchMock.mockResolvedValue({
-            ok: true,
-            json: async () => ({
-                result: {
-                    addressMatches: [
-                        {
-                            coordinates: { x: -77.0365, y: 38.8977 },
-                            matchedAddress: "1600 Pennsylvania Ave NW, Washington, DC",
-                        },
-                        {
-                            coordinates: { x: -78.0, y: 40.0 },
-                            matchedAddress: "1602 Pennsylvania Ave NW, Washington, DC",
-                        },
-                    ],
-                },
-            }),
-        });
-        const result = await geocodeOneLineAddressAll("1600 Pennsylvania Ave NW, Washington, DC");
-        //it should exist
-        expect(result).toBeTruthy;
-        if (!result)
-            return false;
-        //it should be the correct size
-        expect(result?.length).toBe(2);
-        //it should have correct data
-        expect(result[0]?.coordinates).toEqual({
-            x: -77.0365,
-            y: 38.8977,
-        });
-        expect(result[0]?.matchedAddress).toEqual("1600 Pennsylvania Ave NW, Washington, DC");
-        expect(result[1]?.coordinates).toEqual({
-            x: -78.0,
-            y: 40.0,
-        });
-        expect(result[1]?.matchedAddress).toEqual("1602 Pennsylvania Ave NW, Washington, DC");
-        //it should call fetch once per response
-        expect(fetchMock).toHaveBeenCalledOnce();
-    });
-});
-//# sourceMappingURL=one-line-address.test.js.map

package/dist/one-line-address.test.js.map

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