Configuration.branch()

Description

Appends a branch filter to the current pipeline layout.

A branch filter selects a pipeline layout from a number of candidates based on condition callbacks, and then creates a sub-pipeline from the selected pipeline layout before streaming events through it.

INPUT - Any types of Events to stream into the selected sub-pipeline.
OUTPUT - Events streaming out from the selected sub-pipeline.
SUB-INPUT - Events streaming into the branch filter.
SUB-OUTPUT - Any types of Events.

Select from several sub-pipeline layouts

The branch filter can be given more than one sub-pipeline layouts, each corresponding to a condition. As the first event arrives at the filter, it evaluates each condition in order to find the first one that is met, and creates a sub-pipeline based on its corresponding sub-pipeline layout.

Once a pipeline layout is selected, it won't change throughout the whole lifetime of the current stream, even when the conditions may change afterwards.

If no conditions are met, the last pipeline layout without a set condition is selected.

pipy({
  _condition: undefined,
})

  .pipeline()
  .branch(
    () => _condition === 'cond1', (
      $=>$.dump('branch1')
    ),
    () => _condition === 'cond2', (
      $=>$.dump('branch1')
    ),
    (
      $=>$.dump('default branch')
    )
  )

Block up events until a condition is met

If all sub-pipeline layout options have conditions but none of them are met, branch filter will block the stream until a condition is met. This can be used to buffer up events while waiting for a certain situation.

pipy({
  _targetDetected: false,
})

  .pipeline()
  .branch(
    () => _targetDetected, (
      $=>$.dump()
    )
  )

The condition the filter is waiting for is only checked every time there's an input event to the filter. To check the condition whenever any state in the context has changed, regardless of any input events, use wait() instead.

Static branch

If none of the condition arguments are functions, the branch filter will be static, in which case there will not be a branch filter being appended to the current pipeline configuration. Instead, all conditions will be evaluated at configuration time to find a branch. The function for that branch will then be executed with one single argument for the current Configuration, giving your script a chance to selectively insert or bypass filters from the very beginning.

((
  dumpEnabled = false,
) => pipy()

.listen(8080)
.branch(
  dumpEnabled, (
    $=>$.dump()
  )
)
.dummy()

)()

Syntax

pipy()
  .pipeline()
  .branch(
    () => isConditionAMet(), pipelineLayoutA,
    () => isConditionBMet(), pipelineLayoutB,
    // ...
    fallbackPipelineLayout,
  )

pipy()
  .pipeline()
  .branch(
    () => isConditionAMet(), pipelineLayoutA,
    () => isConditionBMet(), pipelineLayoutB,
    // ...
  )

Parameters

branch(condition, pipelineLayout, ...restBranches)

condition

A function that returns true to select the sub-pipeline layout coming after

pipelineLayout

The name of a sub-pipeline layout, or a function that receives a Configuration object for configuring an anonymous sub-pipeline layout.

...restBranches

Other condition/pipelineLayout pairs to select from, with an optional single pipelineLayout at the end for the fallback branch.

Return Value

The same Configuration object.