Class: FlowNodes::BaseNode

Inherits:
Object
  • Object
show all
Defined in:
lib/flow_nodes/base_node.rb

Overview

Base class for all nodes in a flow. Defines the core API for connecting nodes and executing logic.

Direct Known Subclasses

Flow, Node

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ BaseNode

Returns a new instance of BaseNode.



13
14
15
16
 
# File 'lib/flow_nodes/base_node.rb', line 13

def initialize
  @params = {}
  @successors = {}
end

Instance Attribute Details

#params ⇒ Hash

Returns parameters passed to the node during execution.

Returns:

  • (Hash) —

    parameters passed to the node during execution.



8
9
10
 
# File 'lib/flow_nodes/base_node.rb', line 8

def params
  @params
end

#successors ⇒ Hash<String, BaseNode>

Returns a hash mapping action names to successor nodes.

Returns:

  • (Hash<String, BaseNode>) —

    a hash mapping action names to successor nodes.



11
12
13
 
# File 'lib/flow_nodes/base_node.rb', line 11

def successors
  @successors
end

Instance Method Details

#-(other) ⇒ ConditionalTransition

Creates a conditional transition to a successor node.

Parameters:

  • action (String, Symbol) —

    The action that triggers this transition.

Returns:

Raises:

  • (TypeError) 


60
61
62
63
64
 
# File 'lib/flow_nodes/base_node.rb', line 60

def -(other)
  raise TypeError, "Action must be a String or Symbol" unless other.is_a?(String) || other.is_a?(Symbol)

  ConditionalTransition.new(self, other.to_s)
end

#>>(other) ⇒ Object

Defines the default transition to the next node.

Parameters:

  • other (BaseNode) —

    The node to transition to.



53
54
55
 
# File 'lib/flow_nodes/base_node.rb', line 53

def >>(other)
  nxt(other)
end

#exec(_p) ⇒ String, ...

Executes the main logic of the node. This is intended to be overridden by subclasses.

Parameters:

  • _p (Hash) —

    The parameters for execution.

Returns:

  • (String, Symbol, nil) —

    The result action to determine the next node in a flow.



71
72
73
 
# File 'lib/flow_nodes/base_node.rb', line 71

def exec(_p)
  nil
end

#initialize_copy(other) ⇒ Object

Creates a deep copy of the node. This is critical for ensuring that each execution of a flow operates on its own isolated set of node instances, preventing state bleed.

Parameters:

  • other (BaseNode) —

    The original node being duplicated.



23
24
25
26
27
28
29
 
# File 'lib/flow_nodes/base_node.rb', line 23

def initialize_copy(other)
  super
  @params = Marshal.load(Marshal.dump(other.params))
  # Successors are other nodes. The orchestration loop handles duplicating them
  # as they are traversed. A shallow copy of the hash is sufficient here.
  @successors = other.successors.dup
end

#nxt(node, action = "default") ⇒ BaseNode Also known as: next

Connects this node to a successor for a given action.

Parameters:

  • node (BaseNode) —

    The successor node.

  • action (String) (defaults to: "default") —

    The action name that triggers the transition.

Returns:



44
45
46
47
48
 
# File 'lib/flow_nodes/base_node.rb', line 44

def nxt(node, action = "default")
  warn("Overwriting successor for action '#{action}'") if @successors.key?(action)
  @successors[action] = node
  node
end

#run(state) ⇒ Object

Runs the full lifecycle of the node: prep, exec, and post. If not part of a Flow, successors will not be executed.

Parameters:

  • state (Object) —

    An optional shared state object passed through the flow.



79
80
81
82
 
# File 'lib/flow_nodes/base_node.rb', line 79

def run(state)
  warn("Node won't run successors. Use Flow.") unless @successors.empty?
  _run(state)
end

#set_params(p) ⇒ Object

Sets the parameters for the node. To ensure thread safety and prevent state bleed, the parameters are deep-copied.

Parameters:

  • p (Hash) —

    The parameters to set.



35
36
37
 
# File 'lib/flow_nodes/base_node.rb', line 35

def set_params(p)
  @params = Marshal.load(Marshal.dump(p || {}))
end