@dromney/mapthis

Open-source location intelligence toolkit. Parse freeform text, HTML, and URLs into geocoded locations; ship with types and React components for rendering maps.

npm install @dromney/mapthis

Subpath exports

@dromney/mapthis ships a root entry plus focused subpaths so consumers only load what they use.

Subpath	What it contains	Status
@dromney/mapthis	Re-exports types + utils (lightweight only)	0.1
@dromney/mapthis/types	Zod schemas and plain TS domain types (PlaceMap, Place, PlaceGroup, Partner, ParsedLocation, ...)	0.1
@dromney/mapthis/utils	Pure helpers: text, color, numbers, geo, stopwatch	0.1
@dromney/mapthis/scrape	getHtmlFromUrl, htmlToText, getTextFromUrl	0.1
@dromney/mapthis/search	createSearchClient (Google Custom Search)	0.1
@dromney/mapthis/ai	createLocationParser, createOpenAiBackend, summarizeText, prompts	0.1
@dromney/mapthis/geocoding	createGeocoder (Google Maps) with pluggable GeocodingProvider	0.1
@dromney/mapthis/generate	createMapGenerator — composes parser + geocoder into a pure orchestrator	0.1
@dromney/mapthis/react	MapProvider, GoogleMapsViewer, PlaceMarker, autofit, browser autocomplete	0.1

Usage

import { cities } from "@dromney/mapthis/utils"
import { placesFromUrl, type Coordinates } from "@dromney/mapthis/types"

import { createLocationParser } from "@dromney/mapthis/ai"
import { createGeocoder } from "@dromney/mapthis/geocoding"
import { createMapGenerator } from "@dromney/mapthis/generate"

const generator = createMapGenerator({
  parser: createLocationParser({ apiKey: process.env.OPENAI_API_KEY! }),
  geocoder: createGeocoder({ provider: "google", apiKey: process.env.GOOGLE_MAPS_KEY! }),
})

const result = await generator.generateFromSource({
  sourceType: "url",
  source: "https://example.com/best-restaurants-tokyo",
})
// result.title, result.places[].data?.lat, result.usage.inputTokens, ...

Design principles

• No process.env reads. All secrets (OpenAI, Google Maps, Google CSE) are passed to factory functions by the consumer. This keeps the package portable and testable.
• Framework-agnostic. The core modules are pure TypeScript. React components live behind the @dromney/mapthis/react subpath so server-side consumers can skip them.
• Plain domain types. Types are hand-rolled TS (with matching Zod schemas) so consumers are not forced into a particular ORM. Adapter functions between your ORM models and these types stay in your app.
• Optional peer deps for heavy things. openai, js-tiktoken, html-to-text, @googlemaps/google-maps-services-js, react, react-dom, and @vis.gl/react-google-maps are optional peer dependencies. Install only what the subpaths you use need.

License

Apache 2.0 — see LICENSE.