Actyx / Actyx/machines

machine-check API ergonomics issues

Open
#63 1 comment 0 reactions 0 assignees View on GitHub
duplicate
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.