Class: CMDx::Chain

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/cmdx/chain.rb

Overview

Manages a collection of task execution results in a thread-safe manner. Chains provide a way to track related task executions and their outcomes within the same execution context.

Constant Summary collapse

THREAD_KEY = 
:cmdx_chain

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(dry_run: false) ⇒ Chain

Creates a new chain with a unique identifier and empty results collection.



42
43
44
45
46
 
# File 'lib/cmdx/chain.rb', line 42

def initialize(dry_run: false)
  @id = Identifier.generate
  @results = []
  @dry_run = !!dry_run
end

Instance Attribute Details

#id ⇒ String (readonly)

Returns the unique identifier for this chain.

Examples:

chain.id # => "abc123xyz"

Returns:

  • (String) —

    The chain identifier



22
23
24
 
# File 'lib/cmdx/chain.rb', line 22

def id
  @id
end

#results ⇒ Array<Result> (readonly)

Returns the collection of execution results in this chain.

Examples:

chain.results # => [#<Result>, #<Result>]

Returns:

  • (Array<Result>) —

    Array of task results



32
33
34
 
# File 'lib/cmdx/chain.rb', line 32

def results
  @results
end

Class Method Details

.build(result, dry_run: false) ⇒ Chain

Builds or extends the current chain by adding a result. Creates a new chain if none exists, otherwise appends to the current one.

Examples:

result = task.execute
chain = Chain.build(result)
puts "Chain size: #{chain.size}"

Parameters:

  • result (Result) —

    The task execution result to add

Returns:

  • (Chain) —

    The current chain (newly created or existing)

Raises:

  • (TypeError) —

    If result is not a CMDx::Result instance



106
107
108
109
110
111
112
 
# File 'lib/cmdx/chain.rb', line 106

def build(result, dry_run: false)
  raise TypeError, "must be a CMDx::Result" unless result.is_a?(Result)

  self.current ||= new(dry_run:)
  current.results << result
  current
end

.clear ⇒ nil

Clears the current chain for the current thread.

Examples:

Chain.clear

Returns:

  • (nil) —

    Always returns nil



87
88
89
 
# File 'lib/cmdx/chain.rb', line 87

def clear
  Thread.current[THREAD_KEY] = nil
end

.current ⇒ Chain?

Retrieves the current chain for the current thread.

Examples:

chain = Chain.current
if chain
  puts "Current chain: #{chain.id}"
end

Returns:

  • (Chain, nil) —

    The current chain or nil if none exists



61
62
63
 
# File 'lib/cmdx/chain.rb', line 61

def current
  Thread.current[THREAD_KEY]
end

.current=(chain) ⇒ Chain

Sets the current chain for the current thread.

Examples:

Chain.current = my_chain

Parameters:

  • chain (Chain) —

    The chain to set as current

Returns:

  • (Chain) —

    The set chain



75
76
77
 
# File 'lib/cmdx/chain.rb', line 75

def current=(chain)
  Thread.current[THREAD_KEY] = chain
end

Instance Method Details

#dry_run? ⇒ Boolean

Returns whether the chain is running in dry-run mode.

Examples:

chain.dry_run? # => true

Returns:

  • (Boolean) —

    Whether the chain is running in dry-run mode



124
125
126
 
# File 'lib/cmdx/chain.rb', line 124

def dry_run?
  !!@dry_run
end

#to_h ⇒ Hash

Converts the chain to a hash representation.

Examples:

chain_hash = chain.to_h
puts chain_hash[:id]
puts chain_hash[:results].size

Parameters:

  • return (Hash) —

    a customizable set of options

Returns:

  • (Hash) —

    Hash containing chain id and serialized results



141
142
143
144
145
146
147
 
# File 'lib/cmdx/chain.rb', line 141

def to_h
  {
    id:,
    dry_run: dry_run?,
    results: results.map(&:to_h)
  }
end

#to_s ⇒ String

Converts the chain to a string representation.

Examples:

puts chain.to_s

Returns:

  • (String) —

    Formatted string representation of the chain



157
158
159
 
# File 'lib/cmdx/chain.rb', line 157

def to_s
  Utils::Format.to_str(to_h)
end