strata_component/port

Typed output ports, input ports, and bindings for Strata components.

A component can expose typed integration surfaces without changing its strata_component.Definition. An OutputPort selects an optional typed payload from a component's output type. An InputPort converts a typed payload into a component's message type. A Binding pairs one output port with one input port, carries a typed codec-backed configuration, and maps between the two payload types.

The package targets Erlang and JavaScript. This module does not add a runtime catalog, a persisted connection graph, or a type-erased binding collection; applications keep an exhaustive sum of supported bindings.

Types

Binding

An opaque typed binding between one output port and one input port.

Carries a typed, codec-backed config and a mapping function from (payload, config) to an optional input value. Build with binding. Do not construct directly.

pub type Binding(a, b, c, d, e)

InputPort

An opaque typed input port.

Converts an input value into a component's message type, or a descriptive error string. Build with input_port. Do not construct directly.

pub type InputPort(a, b)

OutputPort

An opaque typed output port.

Selects an optional payload value from a component's output type. Build with output_port. Do not construct directly.

pub type OutputPort(a, b)

PortError

Errors returned when building or operating on ports and bindings.

Errors carry the component kind, port kind, binding kind, or port key so the host or a future editor can report a specific integration surface.

pub type PortError {
  InvalidPort(component_kind: String, port_kind: String, field: String, message: String)
  InvalidBinding(binding_kind: String, field: String, message: String)
  InvalidBindingConfig(binding_kind: String, message: String)
  MappingFailed(binding_kind: String, message: String)
  InputFailed(component_kind: String, port_key: String, message: String)
}

InvalidPort(component_kind: String, port_kind: String, field: String, message: String)

An output_port or input_port constructor received an invalid metadata field. port_kind is "output" or "input".

InvalidBinding(binding_kind: String, field: String, message: String)

The binding constructor received an invalid metadata field.

InvalidBindingConfig(binding_kind: String, message: String)

A binding's config decoder rejected the supplied value.

MappingFailed(binding_kind: String, message: String)

A binding's payload mapping function rejected a matched output.

InputFailed(component_kind: String, port_key: String, message: String)

A binding's target input port could not convert its input to a message.

Functions

binding

Build a typed binding between one output port and one input port.

Returns Error(InvalidBinding(...)) when kind is empty after trimming whitespace or when version is not a positive integer.

pub fn binding(
  kind: String,
  version: Int,
  output: OutputPort(a, b),
  input: InputPort(c, d),
  config_encoder: fn(e) -> json.Json,
  config_decoder: fn(dynamic.Dynamic) -> Result(e, String),
  map: fn(b, e) -> Result(option.Option(d), String)
) -> Result(Binding(a, c, b, d, e), PortError)

binding_kind

Return a binding's stable kind identifier.

pub fn binding_kind(Binding(a, b, c, d, e)) -> String

binding_version

Return a binding's positive version number.

pub fn binding_version(Binding(a, b, c, d, e)) -> Int

decode_config

Decode a binding's config value from a Dynamic using its config decoder.

Wraps a decode failure in Error(InvalidBindingConfig(...)).

pub fn decode_config(
  Binding(a, b, c, d, e),
  dynamic.Dynamic
) -> Result(e, PortError)

encode_config

Encode a binding's config value to JSON using its config encoder.

pub fn encode_config(
  Binding(a, b, c, d, e),
  e
) -> json.Json

input_component_kind

Return an input port's owning component kind.

pub fn input_component_kind(InputPort(a, b)) -> String

input_key

Return an input port's stable key.

pub fn input_key(InputPort(a, b)) -> String

input_port

Build a typed input port.

Returns Error(InvalidPort(...)) when component_kind or key is empty after trimming whitespace, or when version is not a positive integer.

pub fn input_port(
  component_kind: String,
  key: String,
  version: Int,
  to_message: fn(a) -> Result(b, String)
) -> Result(InputPort(b, a), PortError)

input_version

Return an input port's positive version number.

pub fn input_version(InputPort(a, b)) -> Int

output_component_kind

Return an output port's owning component kind.

pub fn output_component_kind(OutputPort(a, b)) -> String

output_key

Return an output port's stable key.

pub fn output_key(OutputPort(a, b)) -> String

output_port

Build a typed output port.

Returns Error(InvalidPort(...)) when component_kind or key is empty after trimming whitespace, or when version is not a positive integer.

pub fn output_port(
  component_kind: String,
  key: String,
  version: Int,
  select: fn(a) -> option.Option(b)
) -> Result(OutputPort(a, b), PortError)

output_version

Return an output port's positive version number.

pub fn output_version(OutputPort(a, b)) -> Int

route

Route a component output through a binding's output port and mapping.

Returns Ok(None) when output does not match the binding's output port. Returns Ok(Some(message)) when the selector, mapping, and input conversion all succeed. Returns Error(MappingFailed(...)) when the mapping function rejects the matched payload, and Error(InputFailed(...)) when the input port cannot convert the mapped input into a message.

pub fn route(
  Binding(a, b, c, d, e),
  e,
  a
) -> Result(option.Option(b), PortError)