Class: CMDx::Task

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

Overview

Represents a task that can be executed within the CMDx framework. Tasks define attributes, callbacks, and execution logic that can be chained together to form workflows.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(context = {}) ⇒ Task

Returns A new task instance.

Examples:

task = MyTask.new(name: "example", priority: :high)
task = MyTask.new(Context.build(name: "example"))

Parameters:

  • context (Hash, Context) (defaults to: {}) —

    The initial context for the task

Options Hash (context):

  • :* (Object) —

    Any key-value pairs to initialize the context

Raises:

Rbs:

  • (untyped context) -> void



89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/cmdx/task.rb', line 89

def initialize(context = {})
  Deprecator.restrict(self)

  @attributes = {}
  @errors = Errors.new

  @id = Identifier.generate
  @context = Context.build(context)
  @result = Result.new(self)
  @chain = Chain.build(@result, dry_run: @context.delete(:dry_run))
end

Instance Attribute Details

#attributes ⇒ Hash{Symbol => Object} (readonly)

Returns the hash of processed attribute values for this task.

Examples:

task.attributes # => { user_id: 42, user_name: "John" }

Returns:

  • (Hash{Symbol => Object}) —

    Hash of attribute names to their values

Rbs:

  • @attributes: Hash[Symbol, untyped]



19
20
21
 
# File 'lib/cmdx/task.rb', line 19

def attributes
  @attributes
end

#chain ⇒ Chain (readonly)

Returns the execution chain containing all task results.

Examples:

task.chain.results.size # => 3

Returns:

  • (Chain) —

    The chain instance

Rbs:

  • @chain: Chain



71
72
73
 
# File 'lib/cmdx/task.rb', line 71

def chain
  @chain
end

#context ⇒ Context (readonly) Also known as: ctx

Returns the execution context for this task.

Examples:

task.context[:user_id] # => 42

Returns:

  • (Context) —

    The context instance

Rbs:

  • @context: Context



49
50
51
 
# File 'lib/cmdx/task.rb', line 49

def context
  @context
end

#errors ⇒ Errors (readonly)

Returns the collection of validation and execution errors.

Examples:

task.errors.to_h # => { email: ["must be valid"] }

Returns:

  • (Errors) —

    The errors collection

Rbs:

  • @errors: Errors



29
30
31
 
# File 'lib/cmdx/task.rb', line 29

def errors
  @errors
end

#id ⇒ String (readonly)

Returns the unique identifier for this task instance.

Examples:

task.id # => "abc123xyz"

Returns:

  • (String) —

    The task identifier

Rbs:

  • @id: String



39
40
41
 
# File 'lib/cmdx/task.rb', line 39

def id
  @id
end

#result ⇒ Result (readonly) Also known as: res

Returns the execution result for this task.

Examples:

task.result.status # => "success"

Returns:

  • (Result) —

    The result instance

Rbs:

  • @result: Result



60
61
62
 
# File 'lib/cmdx/task.rb', line 60

def result
  @result
end

Class Method Details

.attributes ⇒ Object Also known as: attribute

Examples:

attributes :name, :email
attributes :age, type: Integer, default: 18

Rbs:

  • (*untyped) -> void



187
188
189
 
# File 'lib/cmdx/task.rb', line 187

def attributes(...)
  register(:attribute, Attribute.build(...))
end

.attributes_schema ⇒ Hash

Returns Hash of attribute names to their configurations.

Examples:

MyTask.attributes_schema #=> {
  user_id: { name: :user_id, method_name: :user_id, required: true, types: [:integer], options: {}, children: [] },
  email: { name: :email, method_name: :email, required: false, types: [:string], options: { default: nil }, children: [] },
  profile: { name: :profile, method_name: :profile, required: false, types: [:hash], options: {}, children: [
    { name: :bio, method_name: :bio, required: false, types: [:string], options: {}, children: [] },
    { name: :name, method_name: :name, required: true, types: [:string], options: {}, children: [] }
  ] }
}

Returns:

  • (Hash) —

    Hash of attribute names to their configurations

Rbs:

  • () -> Hash[Symbol, Hash[Symbol, untyped]]



261
262
263
264
265
 
# File 'lib/cmdx/task.rb', line 261

def attributes_schema
  Array(settings[:attributes]).each_with_object({}) do |attr, schema|
    schema[attr.method_name] = attr.to_h
  end
end

.deregister(type, object) ⇒ Object

Examples:

deregister(:attribute, :name)
deregister(:callback, :before, MyCallback)

Parameters:

  • type (Symbol) —

    The type of registry to deregister from

  • object (Object) —

    The object to deregister

Raises:

  • (RuntimeError) —

    If the registry type is unknown

Rbs:

  • (Symbol type, untyped object, *untyped) -> void



171
172
173
174
175
176
177
178
179
180
 
# File 'lib/cmdx/task.rb', line 171

def deregister(type, object, ...)
  case type
  when :attribute then settings[:attributes].deregister(object, ...)
  when :callback then settings[:callbacks].deregister(object, ...)
  when :coercion then settings[:coercions].deregister(object, ...)
  when :middleware then settings[:middlewares].deregister(object, ...)
  when :validator then settings[:validators].deregister(object, ...)
  else raise "unknown registry type #{type.inspect}"
  end
end

.execute(*args, **kwargs) ⇒ Result

Returns The execution result.

Examples:

result = MyTask.execute(name: "example")
if result.success?
  puts "Task completed successfully"
end

Parameters:

  • args (Array) —

    Arguments to pass to the task constructor

  • kwargs (Hash) —

    Keyword arguments to pass to the task constructor

Options Hash (**kwargs):

  • :* (Object) —

    Any key-value pairs to pass to the task constructor

Returns:

  • (Result) —

    The execution result

Rbs:

  • (*untyped args, **untyped kwargs) ?{ (Result) -> void } -> Result



298
299
300
301
302
 
# File 'lib/cmdx/task.rb', line 298

def execute(*args, **kwargs)
  task = new(*args, **kwargs)
  task.execute(raise: false)
  block_given? ? yield(task.result) : task.result
end

.execute!(*args, **kwargs) ⇒ Result

Returns The execution result.

Examples:

result = MyTask.execute!(name: "example")
# Will raise an exception if execution fails

Parameters:

  • args (Array) —

    Arguments to pass to the task constructor

  • kwargs (Hash) —

    Keyword arguments to pass to the task constructor

Options Hash (**kwargs):

  • :* (Object) —

    Any key-value pairs to pass to the task constructor

Returns:

  • (Result) —

    The execution result

Raises:

  • (ExecutionError) —

    If the task execution fails

Rbs:

  • (*untyped args, **untyped kwargs) ?{ (Result) -> void } -> Result



317
318
319
320
321
 
# File 'lib/cmdx/task.rb', line 317

def execute!(*args, **kwargs)
  task = new(*args, **kwargs)
  task.execute(raise: true)
  block_given? ? yield(task.result) : task.result
end

.optional ⇒ Object

Examples:

optional :description, :notes
optional :priority, type: Symbol, default: :normal

Rbs:

  • (*untyped) -> void



197
198
199
 
# File 'lib/cmdx/task.rb', line 197

def optional(...)
  register(:attribute, Attribute.optional(...))
end

.register(type, object) ⇒ Object

Examples:

register(:attribute, MyAttribute.new)
register(:callback, :before, -> { puts "before" })

Parameters:

  • type (Symbol) —

    The type of registry to register with

  • object (Object) —

    The object to register

Raises:

  • (RuntimeError) —

    If the registry type is unknown

Rbs:

  • (Symbol type, untyped object, *untyped) -> void



150
151
152
153
154
155
156
157
158
159
 
# File 'lib/cmdx/task.rb', line 150

def register(type, object, ...)
  case type
  when :attribute then settings[:attributes].register(object, ...)
  when :callback then settings[:callbacks].register(object, ...)
  when :coercion then settings[:coercions].register(object, ...)
  when :middleware then settings[:middlewares].register(object, ...)
  when :validator then settings[:validators].register(object, ...)
  else raise "unknown registry type #{type.inspect}"
  end
end

.remove_attributes(*names) ⇒ Object Also known as: remove_attribute

Examples:

remove_attributes :old_field, :deprecated_field

Parameters:

  • names (Array<Symbol>) —

    Names of attributes to remove

Rbs:

  • (*Symbol names) -> void



216
217
218
 
# File 'lib/cmdx/task.rb', line 216

def remove_attributes(*names)
  deregister(:attribute, names)
end

.remove_returns(*names) ⇒ Object Also known as: remove_return

Removes declared returns from the task.

Examples:

remove_returns :old_return

Parameters:

  • names (Array<Symbol>) —

    Names of returns to remove

Rbs:

  • (*Symbol names) -> void



243
244
245
 
# File 'lib/cmdx/task.rb', line 243

def remove_returns(*names)
  settings[:returns] -= names.map(&:to_sym)
end

.required ⇒ Object

Examples:

required :name, :email
required :age, type: Integer, min: 0

Rbs:

  • (*untyped) -> void



206
207
208
 
# File 'lib/cmdx/task.rb', line 206

def required(...)
  register(:attribute, Attribute.required(...))
end

.returns(*names) ⇒ Object

Declares expected context returns that must be set after task execution. If any declared return is missing from the context after #work completes successfully, the task will fail with a validation error.

Examples:

returns :user, :token

Parameters:

  • names (Array<Symbol, String>) —

    Names of expected return keys in the context

Rbs:

  • (*untyped names) -> void



231
232
233
 
# File 'lib/cmdx/task.rb', line 231

def returns(*names)
  settings[:returns] |= names.map(&:to_sym)
end

.settings(**options) ⇒ Hash

Returns The merged settings hash.

Examples:

class MyTask < Task
  settings deprecate: true, tags: [:experimental]
end

Parameters:

  • options (Hash) —

    Configuration options to merge with existing settings

Options Hash (**options):

  • :* (Object) —

    Any configuration option key-value pairs

Returns:

  • (Hash) —

    The merged settings hash

Rbs:

  • (**untyped options) -> Hash[Symbol, untyped]



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/cmdx/task.rb', line 114

def settings(**options)
  @settings ||= begin
    hash =
      if superclass.respond_to?(:settings)
        parent = superclass.settings
        parent
          .except(:backtrace_cleaner, :exception_handler, :logger, :deprecate)
          .transform_values!(&:dup)
          .merge!(
            backtrace_cleaner: parent[:backtrace_cleaner] || CMDx.configuration.backtrace_cleaner,
            exception_handler: parent[:exception_handler] || CMDx.configuration.exception_handler,
            logger: parent[:logger] || CMDx.configuration.logger,
            deprecate: parent[:deprecate]
          )
      else
        CMDx.configuration.to_h
      end

    hash[:attributes] ||= AttributeRegistry.new
    hash[:returns] ||= []
    hash[:tags] ||= []

    hash.merge!(options)
  end
end

Instance Method Details

#execute(raise: false) ⇒ Result

Returns The execution result.

Examples:

result = task.execute
result = task.execute(raise: true)

Parameters:

  • raise (Boolean) (defaults to: false) —

    Whether to raise exceptions on failure

Returns:

  • (Result) —

    The execution result

Rbs:

  • (raise: bool) ?{ (Result) -> void } -> Result



334
335
336
337
 
# File 'lib/cmdx/task.rb', line 334

def execute(raise: false)
  Executor.execute(self, raise:)
  block_given? ? yield(result) : result
end

#logger ⇒ Logger

Returns The logger instance for this task.

Examples:

logger.info "Starting task execution"
logger.error "Task failed", error: exception

Returns:

  • (Logger) —

    The logger instance for this task

Rbs:

  • () -> Logger



361
362
363
364
365
366
367
368
 
# File 'lib/cmdx/task.rb', line 361

def logger
  @logger ||= begin
    logger = self.class.settings[:logger] || CMDx.configuration.logger
    logger.level = self.class.settings[:log_level] || logger.level
    logger.formatter = self.class.settings[:log_formatter] || logger.formatter
    logger
  end
end

#to_h ⇒ Hash

Returns A hash representation of the task.

Examples:

task_hash = task.to_h
puts "Task type: #{task_hash[:type]}"
puts "Task tags: #{task_hash[:tags].join(', ')}"

Parameters:

  • return (Hash) —

    a customizable set of options

Returns:

  • (Hash) —

    A hash representation of the task

Rbs:

  • () -> Hash[Symbol, untyped]



385
386
387
388
389
390
391
392
393
394
395
 
# File 'lib/cmdx/task.rb', line 385

def to_h
  {
    index: result.index,
    chain_id: chain.id,
    type: self.class.include?(Workflow) ? "Workflow" : "Task",
    tags: self.class.settings[:tags],
    class: self.class.name,
    dry_run: dry_run?,
    id:
  }
end

#to_s ⇒ String

Returns A string representation of the task.

Examples:

puts task.to_s
# Output: "Task[MyTask] tags: [:important] id: abc123"

Returns:

  • (String) —

    A string representation of the task

Rbs:

  • () -> String



404
405
406
 
# File 'lib/cmdx/task.rb', line 404

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

#work ⇒ Object

Examples:

class MyTask < Task
  def work
    # Custom work logic here
    puts "Performing work..."
  end
end

Raises:

Rbs:

  • () -> void



350
351
352
 
# File 'lib/cmdx/task.rb', line 350

def work
  raise UndefinedMethodError, "undefined method #{self.class.name}#work"
end