locus

Location intelligence toolkit for TypeScript.

Documentation

A toolkit for location intelligence: multi-modal geo resolution, spatial primitives, pluggable grid systems, and geohash-indexed administrative-layer lookups for @studnicky packages. See docs/GRID-SYSTEMS-AND-SOURCES.md and docs/DATA-INGEST-ARCHITECTURE.md for the architecture and roadmap.

Packages

Core resolution and primitives

• @studnicky/geo-resolver — Multi-modal geo resolution: address, IP, coordinate, and phone-based location lookup with country/timezone/locale detail. Exposes both a discoverable Geo static surface and granular tree-shakeable primitives.
• @studnicky/spatial — Zero-dependency spatial primitives: point-in-polygon, bounding-box zone index, grid-based nearest-neighbor search, named-feature-collection resolution.
• @studnicky/time-conversion — Allocation-free epoch/ISO date conversion using integer civil-calendar arithmetic.
• @studnicky/grid-schemes — GridSchemeInterface contract plus four implementations: GeohashScheme, H3Scheme, S2Scheme, and MgrsScheme (encode/decode, variable-depth covering(), bbox tiling). Grid systems are swappable, not hardcoded.

Data pipeline

• @studnicky/geo-artifact-codec — Generic N-field binary artifact codec (GAC1 bit-packed cell tables, GACO adaptive-depth override trees) that any per-layer builder can encode/decode against, independent of field count or shape.
• @studnicky/geo-adapters — SourceAdapterInterface and AdministrativeSystemAdapterInterface contracts, plus concrete adapters (Natural Earth, US Census TIGER, country-coder, IANA tzdata) for fetching the source-of-truth data every builder consumes.
• @studnicky/geo-data-builder — Builds the geohash-indexed timezone/country/water-body artifact geo-resolver ships, with adaptive-depth descent and bit-packed encoding options.

Administrative layers

Each layer is an independently-loadable package — install only what you need. Bundled default() artifacts are documented, synthetic placeholders for development/testing; a real production table requires running each package's generate script against live data.

• @studnicky/geo-layer-state — State/province lookup (Natural Earth admin-1, global coverage).
• @studnicky/geo-layer-county — County/parish lookup (US Census TIGER, US-only).
• @studnicky/geo-layer-postal — Postal/ZCTA lookup (US Census TIGER, US-only).
• @studnicky/geo-layer-voting-district — Congressional district lookup (US Census TIGER, US-only).

Requirements

Node 24+.

Install

Packages publish to GitHub Packages. Add the registry to .npmrc:

@studnicky:registry=https://npm.pkg.github.com

Then install any package:

pnpm add @studnicky/geo-resolver

Develop

git clone https://github.com/Studnicky/locus.git
cd locus
pnpm install
pnpm build
pnpm test
pnpm lint
pnpm docs:dev

License

MIT — see LICENSE.