machine-check API ergonomics issues
- 主要语言
- TypeScript
- 星标
- 8
- 派生
- 2
- PR 合并指标
- 30 天内没有已合并 PR
描述
When writing API for `machine-check`, there are some concerns regarding the ergonomics:
### Repeated arbitrary string
Arbitrary strings in the `SwarmTypeProtocol` transition properties are prone to error, especially typos.
While `target` and `source` states cannot be non-arbitrary strings without any significant change, writing a `role` and `cmd` can be omitted.
_sidenote: This, however, would be a non-problem if eventually `machine-check` codes will be autogenerated._
### `cmd` name must match the implemented `MachineProtocol`
There does not seem to be any point in ensuring that `cmd` name matches the implemented `MachineProtocol`.
`cmd` name is neither persisted in Actyx nor used in any transition calculation.
It is used only for function naming purposes, which should be irrelevant to the well-formed ness of a machine-runner `MachineProtocol`,
## Possible Solution
### Replace `role` field with MachineProtocol
`machine-check` understands the types exposed by `machine-runner`.
Therefore `machine-check` knows how to extract `createJSONForAnalysis` and subsequently the subscriptions of each machines.
This solves **repeated arbitrary string** issue for `role`.
### Use builder pattern to collect events and define states before defining the transitions
```typescript
SwarmProtocolInteractionDesign
.build(ProtocolEvents.All, [
"Initial",
"Docking",
"DockedAndWaitingForWater",
"WaterDrawn"
])
.transition(
"Initial",
pump.machine,
[ProtocolEvents.DockAvailable.type],
"Docking"
)
.transition(
"Docking",
robot.machine,
[ProtocolEvents.RobotIsDocked.type],
"DockedAndWaitingForWater"
)
.transition(
"DockedAndWaitingForWater",
pump.machine,
[ProtocolEvents.WaterSupplied.type],
"WaterDrawn"
)
.transition(
"WaterDrawn",
robot.machine,
[ProtocolEvents.RobotIsUndocked.type],
"Undocked"
)
.roleInitial(robot.machine, robot._1_WaitingForDock)
.roleInitial(pump.machine, pump._1_Initial)
.finish()
.test()
// at this point:
// 1. all roles have initials figured out
// 2. test suite can figure out the subscriptions
// 3. test suite can test each role's projections
```
### Remove `cmd` checking in the rust code
This solves **`cmd` name must match the implemented `MachineProtocol`**
贡献指南
这个仓库没有索引到贡献指南
调研方向
Start with the machine-check definitions of SwarmTypeProtocol and MachineProtocol, then trace how createJSONForAnalysis and the proposed SwarmProtocolInteractionDesign entry point are used. Compare the TypeScript API proposal with the Rust cmd validation path. Done means role information comes from MachineProtocol, transitions can be built with declared events and states, and unnecessary cmd checking is removed without breaking analysis.
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- rust, typescript
- 领域
- api, developer-experience
- Issue 类型
- 功能
- 难度
- 5/5
- 预计耗时
- 一周以上
- 活跃度
- 停滞
- 描述清晰度
- 基本清楚
- 新手友好度
- 25/100