@happyvertical/smrt-events

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

具有参与者跟踪和SMRT框架支持的分级活动管理

中文使用文档
文档目录14 节
  1. 安装
  2. 使用量
  3. 参与者的分级活动
  4. 全天活动、时区和再现扩展
  5. 拥有资产
  6. API 密码
  7. 模型
  8. 收款
  9. 类型
  10. 公用事业
  11. UI 元数据
  12. 实例方法(活动)
  13. 依赖关系
  14. iCalendar 源代码同步

@ 快乐的垂直/ smrt- 事件

无限去除事件分级 系列,参与者跟踪,和重现模式。 活动可以模拟从有会议的会议到有时期和目标的体育比赛的一切.

安装

pnpm add @happyvertical/smrt-events

使用量

参与者的分级活动

import { EventCollection, EventSeriesCollection, EventParticipantCollection } from '@happyvertical/smrt-events';

const events = await EventCollection.create();

// Create a game with nested periods
const game = await events.create({
  name: 'Lakers vs Warriors',
  slug: 'lakers-warriors-2024-01-20',
  startDate: new Date('2024-01-20T19:30:00'),
  endDate: new Date('2024-01-20T22:00:00'),
  status: 'scheduled',
  placeId: 'arena-id', // plain string FK to smrt-places
});

const quarter = await events.create({
  name: '1st Quarter',
  parentId: game.id, // infinite nesting (via SmrtHierarchical)
  startDate: new Date('2024-01-20T19:30:00'),
});

// Hierarchy traversal
const hierarchy = await quarter.getHierarchy();
console.log(hierarchy.ancestors.map(e => e.name)); // ['Lakers vs Warriors']

// Add participants with roles and placement
const participants = await EventParticipantCollection.create();
await participants.create({
  eventId: game.id,
  profileId: 'lakers-id', // plain string FK to smrt-profiles
  role: 'home',
  placement: 0,
});

// Recurring series
const series = await EventSeriesCollection.create();
await series.create({
  name: 'Weekly Standup',
  slug: 'weekly-standup-2024',
  recurrence: { frequency: 'weekly', interval: 1, byDay: ['MO', 'WE', 'FR'] },
});

全天活动、时区和再现扩展

Event.allDay 标出全天活动(startDate 是当地午夜 第一天,我说, endDate 最后一天之后的午夜)和 Event.timeZone 是事件所安排的 IANA 区域( 空继承) 从系列,地点,或站点.

expandRecurrence(pattern, { start, rangeStart, rangeEnd, timeZone }) 转弯 (单位:千美元) RecurrencePattern (对象或存储的JSON) 发生即时. 它支持 frequency 每天/每周/每月/每年, interval, (中文(简体) ), byDay (每周列表;月度单等) 2TU 或者说 -1FR, (中文(简体) ), byMonthDay (月末负数), byMonth, (中文(简体) ), bySetPos,包容性 until,以及 count (从 start) (中文(简体) ). 开始时间是 保留在 timeZone (默认) pattern.timeZone,然后协调世界时),所以19:00的会议 7: 00停留在全天候节能改变. EventSeries.getOccurrences() 用系列包起来 startDate编号 :endDate。 。 。 .

import { expandRecurrence } from '@happyvertical/smrt-events';

// Council meets the second Tuesday at 19:00 Edmonton time
const october = expandRecurrence(
  { frequency: 'monthly', byDay: ['2TU'] },
  {
    start: new Date('2026-01-14T02:00:00Z'), // Jan 13 19:00 MST
    rangeStart: new Date('2026-10-01T00:00:00Z'),
    rangeEnd: new Date('2026-11-01T00:00:00Z'),
    timeZone: 'America/Edmonton',
  },
);

拥有资产

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

const assets = await AssetCollection.create();
const hero = await assets.create({
  name: 'launch-poster.jpg',
  sourceUri: 'file:///tmp/launch-poster.jpg',
  mimeType: 'image/jpeg',
});

await game.addAsset(hero, 'hero');
await events.addAsset(game.id!, hero, 'gallery', 1);

const heroAssets = await game.getAssets('hero');
const galleryAssets = await events.getAssets(game.id!, 'gallery');

API 密码

模型

导出说明
Event具有状态生命周期的分级事件, STI 启用 。 通过字符串ID链接序列,类型,位置; 2; allDay 加纳 timeZone 字段
EventSeries具有重现模式的经常性活动组(每日/每周/月/每年)
EventType每类自定义字段的分类
EventParticipant将配置文件与事件连接到角色、位置和组Id
EventAsset专用自有资产加入存储于 event_assets 与 relationship 财务报告和审定财务报表 sortOrder

收款

导出说明
EventCollectionCRUD + 事件分级
EventAssetCollection直接进入 event_assets 行外加资产助手包装
EventSeriesCollection事件系列 CRUD
EventTypeCollection事件类型的 CRUD
EventParticipantCollection参与者 CRUD( 冲突库: 事件- id, profile- id, 角色)

类型

导出说明
EventOptions, (中文(简体) ), EventSeriesOptions, (中文(简体) ), EventTypeOptions, (中文(简体) ), EventParticipantOptions每个模型的创建选项类型
EventStatus'scheduled' | 'in_progress' | 'completed' | 'cancelled' | 'postponed'
ParticipantRole角色价值(演讲者、家、出家、组织者等)
RecurrenceFrequency'daily' | 'weekly' | 'monthly' | 'yearly'
RecurrencePattern重复定义, 以计数, 直到按 Day, 由 Month 过滤器
EventSearchFilters, (中文(简体) ), EventSeriesSearchFilters, (中文(简体) ), ParticipantSearchFilters查询过滤器类型

公用事业

导出说明
formatEventDateRange将开始/结束日期格式化为可读字符串
generateEventSlug从名称 + 日期创建方便 URL swit
checkSchedulingConflict检测重叠的时间范围
calculateDuration两个日期之间的持续时间(毫秒)
formatDuration人可读时间(如"2h 30m")
isEventNow检查当前是否在进行中
getEventStatusFromDates从开始/结束日期自动检测状态
sortEventsByDate按时间顺序排序事件
validateEventStatus允许验证状态过渡
calculateNextOccurrence重现模式的下个日期( 主机- 本地算术; 偏好) expandRecurrence(中文(简体) )
expandRecurrence窗口内模式的时区发生即时
toZonedWallTime 编号 : fromZonedWallTime在 IANA 区域内的瞬间和相接点间转换
isValidTimeZone对照运行时间检查 IANA 区名 Intl 数据
parseRecurrencePattern从字符串或对象分析重现

UI 元数据

导出说明
EVENTS_MODULE_META用于UI注册的模块元数据
EVENTS_UI_SLOTS事件模块的 UI 槽定义

实例方法(活动)

getParent(), (中文(简体) ), getChildren(), (中文(简体) ), getAncestors(), (中文(简体) ), getDescendants(), (中文(简体) ), getRootEvent(), (中文(简体) ), getHierarchy() - 任何事件都存在等级关系.

双方都有自有资产助手 Event 财务报告和审定财务报表 EventCollection 通过 getAssets(), (中文(简体) ), addAsset(),以及 removeAsset()共同关系包括: hero, (中文(简体) ), gallery, (中文(简体) ), attachment,以及 thumbnail。 。 。 .

依赖关系

软件包目的
@happyvertical/smrt-core垃圾对象/垃圾分类
@happyvertical/smrt-tenancy备选租户范围界定
@happyvertical/smrt-places位置引用( 交叉包装字符串 FKs)
@happyvertical/smrt-profiles参与者简介参考文献(跨包字符串 FKs)
@happyvertical/smrt-types共享类型脚本
@happyvertical/sql数据库操作
@happyvertical/ai大赦国际一体化

iCalendar 源代码同步

parseICalendarEvents(source, ics, { floatingTimeZone?, limits? }) 验证 通过已出版的调用程序提供的 RFC 5545 文本 @happyvertical/icalendar 外相为相. expandICalendarEvents(source, ics, options) 添加必要的包容性 rangeStart编号 :rangeEnd 窗口. syncICalendarSource({ db, source, ics, tenantId?, parse?, expansion? }) 记录和返回 created, (中文(简体) ), updated, (中文(简体) ), unchanged,以及 retainedOnOmission: true。需要经常性的饲料 expansion。 。 。 . 解析/扩展不需要数据库或网络;同步支持 SQLite并 PostgreSQL 有迁移的事件/事件计划。 其他方言不是,我说 目前得到支持( o)FK 第3469号事件缺口;运行时-schema适配器在突变前被否决.

一个租户,消息来源和UID确定一个系列. 它的扩展出点使用 原始RECURENCE-ID(用于定时事件的UTC ISO即时,日历日期 因此,移动实例保留了它的ID。 非经常性记录的使用 UID 不发生后缀 。 反复出现的大师以系列/证明形式生活; 它们在第一次发生时不是重复的事件行。 RDATE是,我们是 正常使用每个RDATE财产自己的时区并与RRULE结合, 重复即时倒塌, 并持续 EXDATE 插槽为 已取消的事件。 已调试的记录超过其原档,包括 移动到请求的窗口。 复制 VEVENT 身份拒绝种子 .

每天、每周、每月和每年的RRULA使用SDK的公共再现引擎. 所支持的受限子集是每天没有BY过滤器;每周没有BYDAY (b) 每月一次,每星期一次,每星期一次 月/月BBY周一时。 其他组合拒绝而不是冒无限制的风险 在重现引擎内搜索。 东帝汶过渡时期理事会、东帝汶过渡时期办事处和过渡期间国际小组一直适用. 扩展时拒绝而不是截断 limit (默认为 1 000; 10 000人上限)或 maxIterations (默认 10,000;最大 10万,包括 窗口前的插槽). 不支持的频率, 未知的重现属性, 多个RRULE, ExULE, DARINT, RDATE 期间和RANGE 拒绝. SDK解析器资源限制仍然有效. 扩展靠近 序列启动;非常老化或密集的种子可能需要经过深思熟虑的更高的扫描预算.

IANA区域使用运行时段数据库和框架的墙上时间 转换: DST 漏洞向前移动,重叠选择第一瞬间. 世界协调时 数值保持世界协调时。 需要浮动时间值 parse.floatingTimeZone (或 直接在剖析/扩展时使用相同的选项; 不推断主机区 。 全天日期 使用此策略或 UTC, 并带有专属 DTEND 和默认的下一天结束 。 时间 没有 DTEND 的事件没有持续时间。 时间重现保持准确的过去 dTSTART 到 DTEND 的持续时间; 全天重现保持日历日的持续时间 穿过DST。 只有日期的重现仍然只有日期.

一个更高的安全性 或者说 更新的 DTSTAMP 接受更新; 等/等旧版本 不变。 失踪的SEQUENCE是0,失踪的DTSTAMP是最古老的 邮票。 生产者在没有两种版本标记的情况下改变有效载荷是故意的 被忽略 。 每个系列保留权威主机的 SDK 序列化文档 和版本,包括当请求的窗口没有出现时。 再见 当所提供主控器为 stale 或 等值时,窗口扩展保留文档, 因此,无法从旧的有效载荷或重现规则中创建出隐形槽. 这个 主文档与事件更新在同一交易中被写入。 这个 扩展要求也适用于保留的文件: 取消解决重现主机需要窗口 。 没有一个人, 同步拒绝并滚回所有写入; 重试 . 取消是更新,更新的预定记录可以恢复. 最小主取消( UID/ STATUS/ 版本不包含 DTSTART) 取消已知 一系列事件和存储 一系列的墓碑 阻碍更古老的复活. 没有种子省略删除事件: 外部窗口记录仍然存在; 省略脱去 例外保持权威,直到该分离身份重新出现 较新的版本。 更新主机删除 EXDATE 恢复生成槽 .

每一次同步解析其数据库配置, 并完成全部写入 一个交易执行器,包括系列创建。 传播失败和 倒卷;呼叫者可能重试相同的种子. 已存在的 SQLite/ PostgreSQL 交易通过适配器保存点连接,保留调用器回滚. 呼叫者必须授权租户/源码访问并串行同步 用于同一租户/来源;该API不执行调度或锁定. 主动租户提供漏掉的租户,拒绝冲突 明确租户,包括要求全局行。 系统背景可能 明确输入租户或全球来源.

获取源(包括有条件请求、不可用信息检测和 (重试排程) 仍为呼叫者所有. 只通过成功获取的种子; 在省略保留的情况下,部分饲料是安全的。 同步不执行起草或 出版物。 事件元数据记录 UID, 发生ID, 版本标记, RRULE/EXDATE/RDATE以及记录是否脱落.

版本与发布记录

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

版本发布日期距今
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-events 的常见问题

@happyvertical/smrt-events 是什么?

具有参与者跟踪和SMRT框架支持的分级活动管理

如何安装 @happyvertical/smrt-events?

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

@happyvertical/smrt-events 支持 TypeScript 吗?

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

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

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

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

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

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

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

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

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