@happyvertical/smrt-places

Hierarchical place management with geocoding integration and spatial queries. Supports both real-world locations (with coordinates) and abstract places (virtual worlds, game zones).

Installation

pnpm add @happyvertical/smrt-places

Usage

Lookup or create places with organic database growth

import { PlaceCollection, PlaceTypeCollection } from '@happyvertical/smrt-places';

const places = await PlaceCollection.create();
const types = await PlaceTypeCollection.create();

// DB-first lookup, geocodes and creates if not found
const place = await places.lookupOrCreate('1600 Amphitheatre Parkway, Mountain View, CA');

if (place) {
  console.log(`${place.name}: ${place.latitude}, ${place.longitude}`);
  console.log(`Source: ${place.source}`); // 'openstreetmap' or 'google'
}

// Build hierarchy: Country > State > City
const country = await places.create({
  typeId: (await types.getOrCreate('country')).id,
  name: 'United States',
  countryCode: 'US',
});

const city = await places.create({
  typeId: (await types.getOrCreate('city')).id,
  parentId: country.id,
  name: 'San Francisco',
  latitude: 37.7749,
  longitude: -122.4194,
});

// Hierarchy traversal
const hierarchy = await city.getHierarchy();
console.log(hierarchy.ancestors.map(p => p.name)); // ['United States']

// Proximity search (Haversine distance, sorted nearest-first)
const nearby = await places.searchByProximity(37.7749, -122.4194, 10); // 10km radius

Discover POIs around a coordinate

discoverNearby composes @happyvertical/geo's findPoisNear with the collection's idempotent-persist logic. Each POI returned by the provider is either reused from the local DB (matched by provider externalId) or created as a fresh Place row. Repeat calls for the same area are effectively free — the provider's own id becomes Place.externalId, so a second scan doesn't duplicate anything.

const pois = await places.discoverNearby(53.5461, -113.4938, 250, {
  geoProvider: 'openstreetmap', // default
  types: ['cafe'], // optional filter — passed through to the provider
  limit: 10,
});

for (const poi of pois) {
  console.log(poi.name, poi.externalId);
}

Requires a geo provider that implements findPoisNear. Throws a clear error otherwise so callers can fall back to lookupOrCreate (address-level) or switch providers.

Resolve POIs along a GPS track

For workflows like "what places does this drive/hike pass through?", resolveTrackPlaces walks an ordered array of points, collapses close samples into grid cells, throttles the provider between requests, and returns the deduplicated Place rows.

const track = [
  { lat: 53.5461, lng: -113.4938 },
  { lat: 53.5465, lng: -113.4942 },
  { lat: 53.5470, lng: -113.4950 },
  // ...hundreds more along a route
];

const result = await places.resolveTrackPlaces(track, {
  radiusMeters: 50,       // per-point POI search radius
  bucketMeters: 50,       // collapse points within this distance into one request
  throttleMs: 1100,       // ≥1s is safe for public Overpass/Nominatim
  types: ['cafe', 'restaurant'],
});

console.log(`Hit ${result.requestCount} buckets, ${result.cacheHitCount} cached, ${result.places.length} distinct places`);

Bucketing is the main cost-saver: a 20-minute drive at 1 Hz GPS produces 1200 raw samples but often only 100–200 distinct 50 m cells, so the provider only gets called 100–200 times. throttleMs keeps you within Overpass/Nominatim's 1 req/sec community limit out of the box; drop it to 100 ms or so on paid tiers.

Owned assets

import { AssetCollection } from '@happyvertical/smrt-assets';

const assets = await AssetCollection.create();
const floorplan = await assets.create({
  name: 'main-hall-floorplan.png',
  sourceUri: 'file:///tmp/main-hall-floorplan.png',
  mimeType: 'image/png',
});

await place.addAsset(floorplan, 'floorplan');
await places.addAsset(place.id!, floorplan, 'gallery', 1);

const floorplans = await place.getAssets('floorplan');
const galleryAssets = await places.getAssets(place.id!, 'gallery');

API

Models

| Export | Description | |--------|------------| | Place | Hierarchical place with optional geo fields, STI enabled | | PlaceType | Slug-based classification (country, city, building, zone, room) | | PlaceAsset | Dedicated owned-asset join stored in place_assets with relationship and sortOrder |

Collections

| Export | Description | |--------|------------| | PlaceCollection | CRUD + lookupOrCreate(), searchByProximity(), findByCoordinates(), getRootPlaces(), getByType(), findWithGlobals() | | PlaceAssetCollection | Direct access to place_assets rows plus asset helper wrappers | | PlaceTypeCollection | CRUD + getOrCreate() for idempotent type creation |

Types

| Export | Description | |--------|------------| | GeoData | Geographic data structure | | LookupOrCreateOptions | Options for lookupOrCreate() | | PlaceHierarchy | Hierarchy traversal result | | PlaceOptions | Place creation options | | PlaceTypeOptions | PlaceType creation options |

Utilities

| Export | Description | |--------|------------| | calculateDistance | Haversine distance between two coordinates (km) | | areCoordinatesNear | Check if two coordinates are within threshold | | validateCoordinates | Validate lat/lng values | | parseCoordinates | Parse coordinate string to lat/lng | | formatCoordinates | Format lat/lng as string | | generateDisplayName | Build display name from address components | | locationToGeoData | Convert location response to GeoData | | mapLocationTypeToPlaceType | Map geocoder location type to PlaceType slug | | normalizeAddressComponents | Normalize address components from geocoder |

Instance Methods (Place)

getParent(), getChildren(), getAncestors(), getDescendants(), getHierarchy() -- hierarchy traversal on any Place instance.

Owned asset helpers are available on both Place and PlaceCollection via getAssets(), addAsset(), and removeAsset(). Common relationships include hero, floorplan, gallery, and attachment.

Dependencies

| Package | Purpose | |---------|---------| | @happyvertical/smrt-core | SmrtObject/SmrtCollection base classes | | @happyvertical/smrt-tenancy | Optional tenant scoping | | @happyvertical/geo | Geocoding providers (OpenStreetMap, Google Maps) | | @happyvertical/sql | Database operations | | @happyvertical/ai | AI integration |