Skip to main content

Creating Composite Actions

Sometimes a single user event should trigger multiple actions — possibly across different machines.
Retomus supports this via createCompositeAction().

🧩 Basic Example​

const composite = retomus.createCompositeAction({
  id: 'tripleIncrement',
  actions: {
    type: 'sequence',
    actions: [
      { type: 'action', machineId: 'counter', actionName: 'increment' },
      { type: 'action', machineId: 'counter', actionName: 'increment' },
      { type: 'action', machineId: 'counter', actionName: 'increment' },
    ],
  },
  options: {
    concurrency: 3, // allows up to 3 concurrent executions of this composite
  },
});

This defines a composite action that will call the increment action 3 times in order, and allows up to 3 concurrent invocations of the composite itself.

⚙️ Execution Pattern​

The structure of actions defines whether the composite runs in:

PatternDescription
sequenceActions run in order, one after another
parallelActions fire at the same time
nestingComposite can contain other composites

⚠️ Note: This pattern affects action ordering, not concurrency.

⚙️ Controlling Concurrency​

Use options.concurrency to limit how many times this composite can run simultaneously.

options: {
  concurrency: 1; // prevents double-click or reentry
}

🚀 Using in React​

const [compositeAction] = composite.use();

<Button onClick={() => compositeAction()}>Do All</Button>;

The hook returned by use() works like any other action hook.

📎 Advanced Features​

  • Each step can target different machines
  • Composites can be nested
  • Safe to reuse across screens/components

⚠️ Notes​

  • Composite actions are global — not tied to a single machine
  • Ensure all referenced machine IDs exist before use

🔗 Related​