machine-check API ergonomics issues
- Dominant language
- TypeScript
- Stars
- 8
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
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`**
Contributor guide
No contributing guide indexed for this repository
Research direction
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.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust, typescript
- Domain
- api, developer-experience
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100