@ happyvertical/ smrt- places (笑) (笑) :
具有地道编码整合和空间查询功能的分级地道管理. 既支持现实世界位置(有坐标),也支持抽象地段(虚拟世界,游戏区).
安装
pnpm add @happyvertical/smrt-places
使用量
查找或创建有机数据库增长的地方
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
在坐标周围发现 PoIs
discoverNearby 编曲 @happyvertical/geo是因为 findPoisNear 与
收藏的一分法 -- -- 持久性逻辑。 提供商退回的每个指令是
或从本地 DB 重用( 由提供者匹配) externalId)或(或)
作为新的 Place 行创建。 重复呼叫同一个区域是有效的
免费 —— 提供者自己的身份成为 Place.externalId进行第二次扫描
不重复任何东西.
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);
}
需要一个执行 findPoisNear。丢出一个明显的错误
否则,呼叫者可以回到 lookupOrCreate (地址级别)或
切换提供者.
沿着 GPS 轨道解析 POIS
对于工作流程,如"这个驱动器/摩托车通过的地方是什么?",
resolveTrackPlaces 移动命令数组点, 崩溃关闭
样品入网格细胞,在请求之间节流供体,以及
返回已复制的 Place 行.
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是主要的成本保护器:在1 Hz GPS 生产20分钟的驱动器
1200个原始样本,但往往只有100-200个显著的50米细胞,因此
提供商只能拨打100-200次. throttleMs 让你进入
超过/诺米纳蒂姆的 1 req/sec 社区限制出框; 将其扔到
薪级为100毫秒等.
拥有资产
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 密码
模型
| 导出 | 说明 |
|---|---|
Place | 具有可选地理字段的等级位置, 启用了 STI |
PlaceType | 基于污名的分类(国家、城市、建筑、区域、房间) |
PlaceAsset | 专用自有资产加入存储于 place_assets 与 relationship 财务报告和审定财务报表 sortOrder |
收款
| 导出 | 说明 |
|---|---|
PlaceCollection | CRUD + 软件 lookupOrCreate(), (中文(简体) ), searchByProximity(), (中文(简体) ), findByCoordinates(), (中文(简体) ), getRootPlaces(), (中文(简体) ), getByType(), (中文(简体) ), findWithGlobals() |
PlaceAssetCollection | 直接进入 place_assets 行外加资产助手包装 |
PlaceTypeCollection | CRUD + 软件 getOrCreate() 用于创建偶能类型 |
类型
| 导出 | 说明 |
|---|---|
GeoData | 地理数据结构 |
LookupOrCreateOptions | 备选方案 lookupOrCreate() |
PlaceHierarchy | 等级倒转结果 |
PlaceOptions | 位置创建选项 |
PlaceTypeOptions | PlaceType 创建选项 |
公用事业
| 导出 | 说明 |
|---|---|
calculateDistance | 两个坐标相距(公里) |
areCoordinatesNear | 检查两个坐标是否在阈值内 |
validateCoordinates | 验证纬度/升值 |
parseCoordinates | 剖析坐标字符串到 lat/ lng |
formatCoordinates | 将lat/ lng 格式化为字符串 |
generateDisplayName | 从地址组件构建显示名称 |
locationToGeoData | 将位置响应转换为 GeoData |
mapLocationTypeToPlaceType | 将地理编码器位置类型映射到 PlaceType sult |
normalizeAddressComponents | 将地理编码器中的地址组件规范化 |
实例方法(地点)
getParent(), (中文(简体) ), getChildren(), (中文(简体) ), getAncestors(), (中文(简体) ), getDescendants(), (中文(简体) ), getHierarchy() - 任何Place实例上的等级.
双方都有自有资产助手 Place 财务报告和审定财务报表 PlaceCollection 通过
getAssets(), (中文(简体) ), addAsset(),以及 removeAsset()共同关系包括:
hero, (中文(简体) ), floorplan, (中文(简体) ), gallery,以及 attachment。 。 。 .
依赖关系
| 软件包 | 目的 |
|---|---|
@happyvertical/smrt-core | 垃圾对象/垃圾分类 |
@happyvertical/smrt-tenancy | 备选租户范围界定 |
@happyvertical/geo | 地理编码提供者( OpenStreetMap, Google Maps) |
@happyvertical/sql | 数据库操作 |
@happyvertical/ai | 大赦国际一体化 |