Locspan

Rule-based location-like span extraction from plain text: prepositional phrases, quoted strings, title-case runs, numbered streets, and US postal-style lines (street, city, state, optional ZIP; suite/unit before or after the street; comma or newline separators). No geocoding and no LLM—only regex/heuristics and refiners.

Source: DelMonteAJ/Locspan. Forked from the chrono date-parser architecture (parser + refiner pipeline).

Version

Current release: 3.1.0 (US full-address parsing, refinements, and CLI helper below).

Install

After the package is published to npm (from this repo’s CI):

npm install locspan

Usage

import { parse, Locspan, casual } from "locspan";

parse("Meet me in Paris tomorrow");
// [{ index, text, confidence, tags() }, ...]

const engine = new Locspan();
engine.parse('She said "London" and left.');

English helpers live under locspan/locales/en (same API shape: casual, strict, parse).

Try parsing from the terminal

After a build (dist/ must exist), run any input string through the parser and print JSON (index, text, confidence, tags):

npm run build
npm run try -- "201 York Street, Unit 403, Monroeville, AL 36460"

From stdin:

echo 'Ship to 400 Broad St, San Diego, CA.' | npm run try

If the package is installed (locally or from npm), you can use the locspan-parse binary:

npx locspan-parse "Meet me in Paris tomorrow"

Development

dist/ is not committed; it is produced by npm run build (and automatically before npm publish).

npm install
npm test
npm run build

CI

GitHub Actions runs npm ci, build, and tests on pushes and pull requests that target master (the default branch). You can also run it manually (Actions → CI → Run workflow).

Publish to npm

The tarball published to npm includes only the built output (dist/, README.md, LICENSE.txt); see the files field in package.json.

1. Create an npm account and an Automation (or Publish) token under Access Tokens.
2. In GitHub: Settings → Secrets and variables → Actions → New repository secret → name NPM_TOKEN, paste the token.
3. Bump the version field in package.json (npm rejects duplicate versions).
4. Push your commit to master, then either:
   • Open Actions → Publish to npm → Run workflow, or
   • Publish a GitHub Release (the workflow also runs when a release is published).

If the unscoped name locspan is already taken on npm, switch to a scoped name (for example @your-org/locspan), update name in package.json, and keep "publishConfig": { "access": "public" } for a public scoped package.

License

MIT