feat(): support accessing specific event object in nested event callbacks

[weareoutman]

依赖检查

组件之间的依赖声明，是微服务组件架构下的重要信息，请确保其正确性。

请勾选以下两组选项其中之一：

• 本次 MR 没有使用上游组件（例如框架、后台组件等）的较新版本提供的特性。

或者：

• 本次 MR 使用了上游组件（例如框架、后台组件等）的较新版本提供的特性。
• 在对应的文件中更新了该上游组件的依赖版本（或确认了当前声明的依赖版本已包含本次 MR 使用的新特性）。

提交信息检查

Git 提交信息将决定包的版本发布及自动生成的 CHANGELOG，请检查工作内容与提交信息是否相符，并在以下每组选项中都依次确认。

破坏性变更是针对于下游使用者而言，可以通过本次改动对下游使用者的影响来识别变更类型：

• 下游使用者不做任何改动，仍可以正常工作时，那么它属于普通变更。
• 反之，下游使用者不做改动就无法正常工作时，那么它属于破坏性变更。

例如，构件修改了一个属性名，小产品 Storyboard 中需要使用新属性名才能工作，那么它就是破坏性变更。
又例如，构件还没有任何下游使用者，那么它的任何变更都是普通变更。

破坏性变更：

• ⚠️ 本次 MR 包含破坏性变更的提交，请继续确认以下所有选项：
• 没有更好的兼容方案，必须做破坏性变更。
• 使用了 feat 作为提交类型。
• 标注了 BREAKING CHANGE: 你的变更说明。
• 同时更新了本仓库中所有下游使用者的调用。
• 同时更新了本仓库中所有下游使用者对该子包的依赖为即将发布的 major 版本。
• 同时为其它仓库的 Migrating 做好了准备，例如文档或批量改动的方法。
• 手动验证过破坏性变更在 Migrate 后可以正常工作。
• 破坏性变更所在的提交没有意外携带其它子包的改动。

新特性：

• 本次 MR 包含新特性的提交，且该提交不带有破坏性变更，并使用了 feat 作为提交类型。
• 给新特性添加了单元测试。
• 手动验证过新特性可以正常工作。

问题修复：

• 本次 MR 包含问题修复的提交，且该提交不带有新特性或破坏性变更，并使用了 fix 作为提交类型。
• 给问题修复添加了单元测试。
• 手动验证过问题修复得到解决。

杂项工作：

即所有对下游使用者无任何影响、且没有必要显示在 CHANGELOG 中的改动，例如修改注释、测试用例、开发文档等：

• 本次 MR 包含杂项工作的提交，且该提交不带有问题修复、新特性或破坏性变更，并使用了 chore, docs, test 等作为提交类型。

Summary by CodeRabbit

发布说明

• 新功能

  • 事件处理增强：支持通过键访问和引用事件对象（键值事件访问），使嵌套回调可读取多层事件数据。
  • 公开运行时上下文中可选的事件映射（eventMap），并在事件处理器配置中新增可选 key 字段以传递事件键。

• 测试

  • 更新/新增测试覆盖多层事件引用与嵌套回调的行为验证。

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

引入对键化事件的支持：在 RuntimeContext 中添加可选的 eventMap?: Map<string, Event>，在事件处理器类型中增加可选 key?: string 字段，运行时在绑定监听器时将事件按键映射至本地上下文，并在表达式求值中通过新的 EVENT_BY_KEY 支持读取这些键化事件；相应测试用例已扩展以覆盖嵌套键引用场景。

Changes

内聚组 / 文件(s)	变更摘要
RuntimeContext 接口扩展 etc/runtime.api.md, packages/runtime/src/internal/interfaces.ts	向 RuntimeContext 添加可选属性 eventMap?: Map<string, Event>。
事件处理器类型更新 packages/types/src/manifest.ts	在 BuiltinBrickEventHandler、UseProviderEventHandler、BaseCustomBrickEventHandler、ConditionalEventHandler 中新增可选字段 key?: string，用于携带事件键。
事件绑定逻辑 packages/runtime/src/internal/bindListeners.ts	将 listenerFactory 的第二参数重命名为 _runtimeContext，在处理器为字符串键时复制并扩展本地 runtimeContext，在该次调用中将键映射到当前事件（填充 eventMap），并用扩展后的上下文继续后续处理与递归调用。
表达式求值：按键访问事件 packages/runtime/src/internal/compute/evaluate.ts	为表达式引入 EVENT_BY_KEY 支持；在主评估路径中要求存在 eventMap，并通过只读代理（get 返回 eventMap.get(key)，ownKeys 列出 eventMap 键）将按键访问暴露给求值引擎。
测试：多层键引用与回调参数 packages/runtime/src/internal/bindListeners.spec.ts	扩展 useProvider 回调测试以覆盖多级事件键引用（如 initialEvent、嵌套 timeoutEvent）、回调参数扩展及嵌套 deepCallback 的调用与断言。

Estimated code review effort

🎯 3 (中等复杂度) | ⏱️ ~20–30 分钟

• 需重点审查：
  • packages/runtime/src/internal/bindListeners.ts 中对 _runtimeContext 的局部复制与 eventMap 扩充逻辑，特别是递归/条件分支下的上下文隔离与污染风险。
  • packages/runtime/src/internal/compute/evaluate.ts 中 EVENT_BY_KEY 的只读代理实现，检查与现有 EVENT 语义的一致性及潜在异常处理（例如缺失键时的行为）。
  • 类型扩展 packages/types/src/manifest.ts 对外暴露的 key?: string，确认所有使用处已同步适配并不会破坏现有类型兼容性。
  • packages/runtime/src/internal/bindListeners.spec.ts 新增测试的断言是否充分、是否覆盖边界情况（无键、键冲突、多次触发等）。

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	PR描述仅包含模板内容，未填写任何实质性信息如变更说明、测试验证或关键确认项的勾选状态。	请补充完整的PR描述，包括：简要说明具体做了什么工作、确认是否为新特性并勾选对应的检查项（测试、手动验证等）、确认依赖检查项的结果。
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	标题准确地反映了PR的主要功能：支持在嵌套事件回调中访问特定的事件对象。这与代码变更中添加eventMap属性和key字段的核心目标相符。

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch steve/v3-event-by-key

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

📥 Commits

Reviewing files that changed from the base of the PR and between 0aeed99 and dff7e21.

📒 Files selected for processing (6)

• etc/runtime.api.md (1 hunks)
• packages/runtime/src/internal/bindListeners.spec.ts (2 hunks)
• packages/runtime/src/internal/bindListeners.ts (1 hunks)
• packages/runtime/src/internal/compute/evaluate.ts (3 hunks)
• packages/runtime/src/internal/interfaces.ts (1 hunks)
• packages/types/src/manifest.ts (4 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

• etc/runtime.api.md
• packages/types/src/manifest.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: build (20.x)
• GitHub Check: Analyze (javascript-typescript)

🔇 Additional comments (2)

packages/runtime/src/internal/bindListeners.ts (1)

131-140: 键控事件上下文复制逻辑清晰。
通过在命中 handler.key 时构造新的 eventMap 并向下传递，嵌套回调现在能够可靠读取对应的事件对象，满足本次需求。

packages/runtime/src/internal/compute/evaluate.ts (1)

308-376: EVENT_BY_KEY 代理实现合理。
getDynamicReadOnlyProxy 结合 eventMap?.get 与 ownKeys 的实现，让表达式求值时既安全又保持懒访问语义。

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull Request Overview

This PR adds support for accessing specific event objects in nested event callbacks by introducing a key property on event handlers and a new EVENT_BY_KEY global variable. This allows developers to reference events from outer scopes when handling deeply nested callbacks.

• Adds optional key property to all event handler interfaces
• Implements EVENT_BY_KEY global variable for accessing keyed events via a dynamic proxy
• Propagates event maps through nested handler contexts

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/types/src/manifest.ts	Adds key?: string property to BuiltinBrickEventHandler, UseProviderEventHandler, BaseCustomBrickEventHandler, and ConditionalEventHandler interfaces
packages/runtime/src/internal/interfaces.ts	Adds optional eventMap property to RuntimeContext interface for storing keyed events
packages/runtime/src/internal/compute/evaluate.ts	Implements EVENT_BY_KEY global variable with dynamic proxy for accessing events by key
packages/runtime/src/internal/bindListeners.ts	Creates and propagates eventMap when handlers have a key property
packages/runtime/src/internal/bindListeners.spec.ts	Adds comprehensive test coverage for nested event key access

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.19%. Comparing base (468441d) to head (dff7e21).
⚠️ Report is 3 commits behind head on v3.

Additional details and impacted files

@@           Coverage Diff           @@
##               v3    #4822   +/-   ##
=======================================
  Coverage   95.19%   95.19%           
=======================================
  Files         212      212           
  Lines        9336     9343    +7     
  Branches     1798     1799    +1     
=======================================
+ Hits         8887     8894    +7     
  Misses        330      330           
  Partials      119      119           

Files with missing lines	Coverage Δ
packages/runtime/src/internal/bindListeners.ts	91.30% <100.00%> (+0.09%)	⬆️
packages/runtime/src/internal/compute/evaluate.ts	97.53% <100.00%> (+0.04%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cypress]

next-core    Run #11814

Run Properties:   Passed #11814  •  817001651d ℹ️: Merge dff7e21d50ea39ddf74ced57789b2835ed3df6c4 into 468441de96cb5b06d367cfe743fc...

Project	next-core
Branch Review	steve/v3-event-by-key
Run status	Passed #11814
Run duration	00m 24s
Commit	817001651d ℹ️: Merge dff7e21d50ea39ddf74ced57789b2835ed3df6c4 into 468441de96cb5b06d367cfe743fc...
Committer	Shenwei Wang
View all properties for this run ↗︎

---

Test results
Failures	0
Flaky	0
Pending	0
Skipped	0
Passing	17
View all changes introduced in this branch ↗︎