lance-ts 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +15 -56
  2. package/package.json +11 -4
package/README.md CHANGED
@@ -1,8 +1,10 @@
1
- # lance-ts
1
+ # Lance-TS
2
2
 
3
3
  **Opinionated TypeScript client for the U.S. Census Geocoder API.**
4
4
 
5
- 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.
5
+ Turn U.S. addresses into latitude/longitude coordinates using the free [Census Bureau Geocoder](https://geocoding.geo.census.gov/geocoder/). Strongly-typed, totally node-native.
6
+
7
+ [Read the docs](https://matt-the-thew.github.io/lance-ts/)
6
8
 
7
9
  ---
8
10
 
@@ -12,7 +14,7 @@ If you're working with U.S. address data, the Census Geocoder is an extremely vi
12
14
 
13
15
  ### The Issue:
14
16
 
15
- The raw API response is verbose and awkward to work with.
17
+ The raw Census Geocoder API response is verbose and awkward to work with.
16
18
  Below is the simplest possible response; a single one-line address match:
17
19
  ```json
18
20
  {"result": {
@@ -80,7 +82,7 @@ Requires **Node.js 18+** (for native `fetch`).
80
82
  ## Quick Start
81
83
 
82
84
  ```ts
83
- import { geocode } from "lance-ts";
85
+ import { geocodeOneLineAddress } from "lance-ts";
84
86
 
85
87
  const result = await geocodeOneLineAddress(
86
88
  "1600 Pennsylvania Avenue NW, Washington, DC 20500"
@@ -95,39 +97,6 @@ if (result) {
95
97
 
96
98
  ---
97
99
 
98
- ## API
99
-
100
- ### `geocode(address: string): Promise<GeocodeResult | null>`
101
-
102
- Geocodes a single one-line U.S. address. Returns `null` if no match is found.
103
-
104
- ```ts
105
- const result = await geocode("350 Fifth Avenue, New York, NY 10118");
106
- // → { lat: 40.7484, lng: -73.9856, matchedAddress: "350 5TH AVE, NEW YORK, NY, 10118" }
107
- ```
108
-
109
- **Parameters**
110
-
111
- | Name | Type | Description |
112
- |-----------|----------|------------------------------------------|
113
- | `address` | `string` | A U.S. address in one-line format |
114
-
115
- **Returns:** `Promise<GeocodeResult | null>`
116
-
117
- ---
118
-
119
- ### `GeocodeResult`
120
-
121
- ```ts
122
- type GeocodeResult = {
123
- lat: number;
124
- lng: number;
125
- matchedAddress: string;
126
- };
127
- ```
128
-
129
- ---
130
-
131
100
  ## How It Works
132
101
 
133
102
  `lance-ts` sends your address to the Census Bureau's public REST endpoint:
@@ -136,11 +105,11 @@ type GeocodeResult = {
136
105
  https://geocoding.geo.census.gov/geocoder/locations/onelineaddress
137
106
  ```
138
107
 
139
- 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.
108
+ 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.
140
109
 
141
110
  ---
142
111
 
143
- ## Development
112
+ ## Getting Started
144
113
 
145
114
  ```bash
146
115
  # Install dependencies
@@ -155,30 +124,20 @@ pnpm test --ui
155
124
 
156
125
  ### Project Structure
157
126
 
158
- ```
127
+ ```bash
159
128
  lance-ts/
160
- ├── src/ # TypeScript source
161
- ├── dist/ # Compiled output (generated)
162
- ├── tsconfig.json
163
- └── package.json
129
+ |--src/ # TypeScript source
130
+ |--dist/ # Compiled output (generated)
131
+ |--tsconfig.json
132
+ |--package.json
164
133
  ```
165
-
166
- This project uses a strict `tsconfig.json` setup including:
167
-
168
- - `strict: true`
169
- - `noUncheckedIndexedAccess: true`
170
- - `exactOptionalPropertyTypes: true`
171
- - `verbatimModuleSyntax: true`
172
- - `moduleResolution: "nodenext"`
173
-
174
134
  ---
175
135
 
176
136
  ## Limitations
177
137
 
178
138
  - U.S. addresses only
179
- - Coordinate results are **interpolated** from TIGER address ranges, not rooftop-precise
180
- - Batch geocoding (up to 10,000 addresses) is not yet implemented
181
- - Reverse geocoding (coordinates → address) is not yet implemented
139
+ - Coordinate results are **interpolated** from TIGER address ranges. Very small error margin, but not always rooftop-precise.
140
+ - Reverse geocoding (coordinates -> address) is not yet implemented. *Coming soon!*
182
141
 
183
142
  ---
184
143
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lance-ts",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "Lat/Long from National Census Endpoint. An opinionated, blazingingly fast geocoding library.",
5
5
  "type": "module",
6
6
  "module": "./dist/index.mjs",
@@ -17,7 +17,11 @@
17
17
  "test:ui": "vitest --ui",
18
18
  "type-check": "tsc --noEmit",
19
19
  "build": "tsup",
20
- "clean": "rm -rf ./dist"
20
+ "clean": "rm -rf ./dist",
21
+ "docs:clean": "rm -rf ./site",
22
+ "docs:build": "typedoc",
23
+ "docs:gen_site": "mkdocs build",
24
+ "docs:dev": "typedoc && mkdocs build && mkdocs serve"
21
25
  },
22
26
  "files": [
23
27
  "dist"
@@ -26,8 +30,7 @@
26
30
  "geocoding",
27
31
  "gps",
28
32
  "geography",
29
- "geospatial",
30
- "coordinates"
33
+ "geospatial"
31
34
  ],
32
35
  "author": "Matthew Morton <mmortondev@gmail.com>",
33
36
  "license": "ISC",
@@ -38,6 +41,10 @@
38
41
  "memfs": "^4.57.6",
39
42
  "publint": "^0.3.21",
40
43
  "tsup": "^8.5.1",
44
+ "typedoc": "^0.28.19",
45
+ "typedoc-plugin-coverage": "^4.0.3",
46
+ "typedoc-plugin-file-overview": "^0.2.0",
47
+ "typedoc-plugin-markdown": "^4.12.0",
41
48
  "typescript": "^6.0.3",
42
49
  "vitest": "^4.1.8"
43
50
  }