@happyvertical/smrt-places

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.5万

具有地理整合和SMRT框架支持的分级地点管理

中文使用文档
文档目录13 节
  1. 安装
  2. 使用量
  3. 查找或创建有机数据库增长的地方
  4. 在坐标周围发现 PoIs
  5. 沿着 GPS 轨道解析 POIS
  6. 拥有资产
  7. API 密码
  8. 模型
  9. 收款
  10. 类型
  11. 公用事业
  12. 实例方法(地点)
  13. 依赖关系

@ 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

收款

导出说明
PlaceCollectionCRUD + 软件 lookupOrCreate(), (中文(简体) ), searchByProximity(), (中文(简体) ), findByCoordinates(), (中文(简体) ), getRootPlaces(), (中文(简体) ), getByType(), (中文(简体) ), findWithGlobals()
PlaceAssetCollection直接进入 place_assets 行外加资产助手包装
PlaceTypeCollectionCRUD + 软件 getOrCreate() 用于创建偶能类型

类型

导出说明
GeoData地理数据结构
LookupOrCreateOptions备选方案 lookupOrCreate()
PlaceHierarchy等级倒转结果
PlaceOptions位置创建选项
PlaceTypeOptionsPlaceType 创建选项

公用事业

导出说明
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大赦国际一体化

版本与发布记录

@happyvertical/smrt-places 共发布 365 个版本,首次发布于 2026/06/23;过去 12 个月发布了 365 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-places 的常见问题

@happyvertical/smrt-places 是什么?

具有地理整合和SMRT框架支持的分级地点管理

如何安装 @happyvertical/smrt-places?

在项目目录运行 npm install @happyvertical/smrt-places,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-places 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-places 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-places 可以商用吗?

@happyvertical/smrt-places 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-places 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-places 在 2026/10/17 – 2026/11/15 这 30 天内被下载 14,876 次,日均约 496 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-places 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 365 个版本,其中过去 12 个月发布了 365 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。