Events

The Dinghy engine emits events at various stages of its operation. You can provide custom event handlers to modify the data model or perform additional tasks in response to these events as needed.

Event Handler

1. To handle events, create a file named events/on.EVENT_NAME.ts that exports a default function.
2. The function's name can be anything; only the file name and only its default export is required.
3. The function can be asynchronous if your handler needs to perform async work.

For example:

events/on.render.start.ts

export default function onRenderStart(renderOptions: any) {
  console.log('render started with stack based renderOptions', renderOptions)
}

Lifecyle Events

Lifecycle events are emitted as the Dinghy Engine executes commands. Most events have start and finish variants to indicate the beginning and successful completion of a phase. Some events may also have a failed variant, triggered if an error occurs before completion.

You can refer to the relevant source code to see what arguments are passed to each event.

1. engine.start|finish|failed - Wrap around engine command source
2. render.start|finish - Wrap around render operation source
3. tf.* - Events generated by tf-combined-cmds.ts for tf related operations

Format Based Events

These events occur right before the generated data model is written out in the final output format, giving you a last opportunity to make any modifications before the result is saved.

1. tf.generated – Fired after the Terraform tf.json model is produced source
2. drawio.generated – Fired after the DrawIO XML is generated source

Event Handler Arguments

1. generated data model (modifiable)
2. renderOptions used for output generation

Example Sequence

Below is the sequence of events emitted during a dinghy tf diff --debug | grep dinghy:event command execution:

1. engine.start
   1. tf.render.start (the following sequence repeats for each active stack)
      1. render.start
      2. tf.generated
      3. render.finish
   2. tf.render.finish
   3. tf.stacks.start (the following sequence repeats for each active stack)
      1. tf.stack.start
      2. tf.stack.init.start
      3. tf.stack.init.finish
      4. tf.stack.plan.start
      5. tf.stack.plan.finish
      6. tf.stack.changes.detected
      7. tf.stack.finish
   4. tf.stacks.changes.detected
   5. tf.stacks.finish
2. engine.finish