lance-ts 1.0.0

package/dist/batch-address.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,70 @@
+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

@@ -0,0 +1 @@
+{"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

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

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

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

package/dist/batch-address.test.js

@@ -0,0 +1,98 @@
+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

@@ -0,0 +1 @@
+{"version":3,"file":"batch-address.test.js","sourceRoot":"","sources":["../src/batch-address.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;IAC5B,MAAM,EAAE,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC,CAAC;AACH,gDAAgD;AAChD,4CAA4C;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,IAAI,QAA8B,CAAC;IACnC,4BAA4B;IAC5B,MAAM,YAAY,GAAG,mBAAmB,CAAC;IACzC,iCAAiC;IACjC,MAAM,SAAS,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;IAC1B,0BAA0B;IAC1B,UAAU,CAAC,GAAG,EAAE;QACd,0CAA0C;QAC1C,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAClC,kCAAkC;QAClC,GAAG,CAAC,KAAK,EAAE,CAAC;QACZ,0BAA0B;QAC1B,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,qBAAqB;QACrB,QAAQ,GAAG,IAAI,oBAAoB,CAAC,EAAE,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,gBAAgB,EAAE,CAAC;QACtB,EAAE,CAAC,aAAa,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,CAC1B,kEAAkE,CACnE,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;QAC9B,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;YACjD,mBAAmB;YACnB,GAAG,CAAC,aAAa,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC;YACrD,6BAA6B;YAC7B,QAAQ,CAAC,aAAa,GAAG,YAAY,CAAC;YACtC,8CAA8C;YAC9C,MAAM,UAAU,GAAG,QAAQ,CAAC,cAAc,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;YACnE,kBAAkB;YAClB,MAAM,CAAC,UAAU,CAAC,CAAC;YACnB,IAAI,UAAU,EAAE,CAAC;gBACf,wBAAwB;gBACxB,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;YACtC,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,iBAAiB,EAAE,KAAK,IAAI,EAAE;QACrC,EAAE,CAAC,8BAA8B,EAAE,KAAK,IAAI,EAAE;YAC5C,mCAAmC;YACnC,MAAM,YAAY,GAAG,eAAe,CAAC;YACrC,GAAG,CAAC,aAAa,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC;YACrD,+BAA+B;YAC/B,QAAQ,CAAC,aAAa,GAAG,YAAY,CAAC;YACtC,qBAAqB;YACrB,MAAM,QAAQ,GAAG,QAAQ,CAAC,eAAe,CACvC,QAAQ,CAAC,aAAa,CACX,CAAC;YACd,8BAA8B;YAC9B,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;YAClD,4BAA4B;YAC5B,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAS,CAAC;YACtD,MAAM,CAAC,SAAS,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;YACvC,sBAAsB;YACtB,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;YAC1C,0BAA0B;YAC1B,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC1C,6BAA6B;YAC7B,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;YACpC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,cAAc,EAAE,KAAK,IAAI,EAAE;QAClC,EAAE,CAAC,qCAAqC,EAAE,KAAK,IAAI,EAAE;YACnD,MAAM,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC3C,mCAAmC;YACnC,GAAG,CAAC,aAAa,CACf,YAAY,EACZ,oCAAoC,CACrC,CAAC;YACF,MAAM,QAAQ,GAAG,IAAI,oBAAoB,CACvC,YAAY,EACZ,iBAAiB,CAClB,CAAC;YACF,MAAM,eAAe,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;YAC3D,yBAAyB;YACzB,SAAS,CAAC,iBAAiB,CAAC;gBAC1B,EAAE,EAAE,IAAI;gBACR,MAAM,EAAE,GAAG;gBACX,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,oCAAoC,CAAC;aAClE,CAAC,CAAC;YACH,MAAM,QAAQ,CAAC,YAAY,EAAE,CAAC;YAC9B,wCAAwC;YACxC,MAAM,CAAC,eAAe,CAAC,CAAC,oBAAoB,EAAE,CAAC;YAC/C,0BAA0B;YAC1B,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU,CAAC;YACpD,oCAAoC;YACpC,MAAM,CAAC,QAAQ,CAAC,CAAC,oBAAoB,EAAE,CAAC;YACxC,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAC3D,oCAAoC,CACrC,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @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

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"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/index.js

@@ -0,0 +1,9 @@
+/**
+ * @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.js.map

package/dist/index.js.map

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

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

@@ -0,0 +1,45 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,64 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

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

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,112 @@
+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

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

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "lance-ts",
+  "version": "1.0.0",
+  "description": "Lat/Lng from Address via National Census Endpoint",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "types": "./dist/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "vitest",
+    "build": "tsc",
+    "prepublishOnly": "pnpm run build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "packageManager": "pnpm@10.30.3",
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@vitest/ui": "4.1.7",
+    "publint": "^0.3.21",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "memfs": "^4.57.2",
+    "vitest": "^4.1.7"
+  }
+}