Nodes & Providers

Declaring a node

A node is instantiated with a name and a kind:

Log(console/log)

Log is the identifier used for this instance throughout the flow; console/log is the kind of node — its namespace and name — which the provider resolves to a node definition. Multiple nodes can be declared on one line, separated by commas:

Commands(object/keys), CommandsPicker(data/pick)

Node declarations can appear anywhere a link could start a chain, so a node is often declared right where it first connects:

Request(superagent/api)
'http://example.com' -> url Request

Flow meta

Lines at the top of the file set flow metadata:

title: Example flow
ns: myns

title is the display name, ns sets the default namespace, and name/id give the flow an identity (used when a flow is used as a node itself).

The provider line

The provider line is mandatory. It says how to resolve the node definitions the flow uses — either from local files or from a remote registry:

provider ./{ns}.{name}.yml
provider https://api.fbpx.io/v1/nodes/{user}/{ns}/{name}

Both forms contain the template tokens {ns} and {name}, which are replaced for each node kind. When the parser compiles a flow, the @-named provider in the output model records this line — convert shows it:

$ fbpx convert hello.fbp --yaml
providers:
  '@':
    path: './{ns}.{name}.yml'

A provider without an as alias is the default @ provider. The parser injects a default remote provider when the flow file does not match one.

Aliases and subgraph-as-a-node

A provider line can register a named alias, and the target of the alias can be another .fbp graph:

provider ./graphs/{ns}/{name}.fbp as x

Now x is a resolvable provider namespace:

GraphCommands(x:models/model)

This instantiates the flow graphs/models/model.fbp as a single node. The subgraph's export declarations become the external ports of the node — so a flow is a component, and flows compose. This is how FBPX does both composition and recursion.

Node definition files

A node kind resolves to a node definition — a YAML file (or a JSON object served by a registry) that declares the node's identity, its ports, and the code that runs when data arrives:

title: My Console Log Node
ns: console
name: log
ports:
  input:
    msg:
      type: string
fn: "console.log($.msg)"

The ns and name pair must match what the provider resolved. The ports describe what input (and output) the node expects. fn contains the function body, evaluated in the injected namespace ($, output, cb, on, state).

Nodes can also be classes when orchestration between ports matters, or streaming nodes when they process a stream of packets. Both are covered in the API section and the streaming reference.