cmdx 2.0.1 → 2.1.0

data/lib/generators/cmdx/templates/install.rb

@@ -1,40 +1,54 @@
 # frozen_string_literal: true
 
 CMDx.configure do |config|
+  # Full configuration reference:
+  # https://drexed.github.io/cmdx/configuration
+
   # ===========================================================================
-  # Locale
+  # Default locale
+  # https://drexed.github.io/cmdx/configuration/#default-locale
   # ===========================================================================
-  # Fallback locale for built-in messages (validation, coercion, etc.) when
-  # the I18n gem is not present. With I18n loaded, CMDx follows `I18n.locale`.
+  # The language CMDx uses for its built-in messages (validation errors,
+  # coercion errors, etc.) when the `I18n` gem isn't around. If `I18n` IS
+  # loaded, CMDx follows `I18n.locale` and ignores this setting.
   #
   # config.default_locale = "en"
 
   # ===========================================================================
   # Strict context
+  # https://drexed.github.io/cmdx/configuration/#strict-context
   # ===========================================================================
-  # When true, dynamic reads on `context` raise `NoMethodError` for unknown
-  # keys instead of returning `nil` (`[]`, `fetch`, `dig`, and `?` predicates
-  # stay lenient). Override per-task via `settings(strict_context: true)`.
+  # Catches typos early. With strict mode on, `context.usr_id` (instead of
+  # `context.user_id`) raises `CMDx::UnknownAccessorError` instead of silently
+  # returning `nil`. Hash-style reads (`[]`, `fetch`, `dig`, `?` predicates)
+  # stay forgiving. Flip it per task with `settings(strict_context: true)`.
   #
   # config.strict_context = true
 
   # ===========================================================================
   # Correlation ID (xid)
+  # https://drexed.github.io/cmdx/configuration/#correlation-id-xid
   # ===========================================================================
-  # Resolves an external correlation id (e.g. Rails `request_id`) once per
-  # root execution. The value is stored on the Chain and surfaces on every
-  # Result (`result.xid`, `result.to_h[:xid]`) and Telemetry::Event (`event.xid`),
-  # so all tasks within the same request can be filtered together in logs.
+  # Stamps every task in a run with the same id so you can grep your logs by
+  # request. The callable runs ONCE per root execution; every nested task
+  # inherits the value. Surfaces as `result.xid`, `result.to_h[:xid]`, and
+  # `event.xid` on telemetry events.
   #
   # config.correlation_id = -> { Current.request_id }
 
   # ===========================================================================
   # Logging
+  # https://drexed.github.io/cmdx/configuration/#logging
   # ===========================================================================
-  # In Rails, the Railtie already wires `config.logger = Rails.logger` and a
-  # backtrace cleaner — override here only if you need something different.
+  # Pick where logs go, how they look, and what to hide. In Rails, the Railtie
+  # already points `logger` at `Rails.logger` and wires a backtrace cleaner —
+  # only override here if you want something different.
+  #
+  # Built-in formatters (under `CMDx::LogFormatters`):
+  #   Line (default), JSON, KeyValue, Logstash, Raw
   #
-  # Formatters: Line (default), Json, KeyValue, Logstash, Raw
+  # `log_exclusions` only strips keys from the LOG LINE — the in-memory
+  # `Result` and telemetry payloads stay complete.
   #
   # config.backtrace_cleaner = ->(bt) { Rails.backtrace_cleaner.clean(bt) }
   # config.log_exclusions = [:context]
@@ -44,8 +58,12 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Middlewares
+  # https://drexed.github.io/cmdx/configuration/#middlewares
   # ===========================================================================
-  # Wrap every task's execution. Must respond to `call(task) { ... }`.
+  # Wrap every task with shared behavior (auth, locale, timing, you name it).
+  # A middleware is anything that responds to `call(task) { ... }` and MUST
+  # yield (or call `next_link.call` from a proc) — forgetting to do so raises
+  # `CMDx::MiddlewareError` so tasks never silently disappear.
   #
   # Example — run each task under the current user's locale:
   #
@@ -59,9 +77,13 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Callbacks
+  # https://drexed.github.io/cmdx/configuration/#callbacks
   # ===========================================================================
-  # Events:
-  #   :before_validation, :before_execution,
+  # Hook into a task's lifecycle. Each callback receives the task instance.
+  #
+  # Available events:
+  #   :before_execution, :before_validation,
+  #   :around_execution, :after_execution,
   #   :on_complete, :on_interrupted,
   #   :on_success, :on_skipped, :on_failed,
   #   :on_ok, :on_ko
@@ -72,16 +94,20 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Telemetry
+  # https://drexed.github.io/cmdx/configuration/#telemetry
   # ===========================================================================
-  # Events and payloads:
-  #   :task_started      payload: {}
-  #   :task_deprecated   payload: {}
-  #   :task_retried      payload: { attempt: Integer }
-  #   :task_rolled_back  payload: {}
-  #   :task_executed     payload: { result: CMDx::Result }
+  # A tiny pub/sub bus for runtime events. Subscribe with a callable; nothing
+  # fires if nobody's listening, so unused events cost nothing.
+  #
+  # Events and their extra payload keys:
+  #   :task_started      {}
+  #   :task_deprecated   {}
+  #   :task_retried      { attempt: Integer }
+  #   :task_rolled_back  {}
+  #   :task_executed     { result: CMDx::Result }
   #
   # Every event also carries: event.cid, event.xid, event.tid, event.task,
-  # event.type, event.root, event.timestamp.
+  # event.type, event.name, event.root, event.payload, event.timestamp.
   #
   # config.telemetry.subscribe(:task_executed, proc do |event|
   #   StatsD.timing("cmdx.task", event.payload[:result].duration)
@@ -89,8 +115,11 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Coercions
+  # https://drexed.github.io/cmdx/configuration/#coercions
   # ===========================================================================
-  # Register custom type coercions. Callable receives `(value, **options)`.
+  # Teach CMDx how to convert raw input into a custom type. The callable gets
+  # `(value, **options)` and returns the coerced value (or
+  # `CMDx::Coercions::Failure.new("message")` to signal a bad value).
   #
   # config.coercions.register(:currency, proc do |value, **|
   #   BigDecimal(value.to_s.gsub(/[^\d.-]/, ""))
@@ -98,9 +127,11 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Validators
+  # https://drexed.github.io/cmdx/configuration/#validators
   # ===========================================================================
-  # Register custom validators. Callable receives `(value, options)` and
-  # returns a `CMDx::Validators::Failure.new(message)` on failure.
+  # Custom input validators. The callable gets `(value, options)` (options is
+  # a positional Hash). Return `CMDx::Validators::Failure.new(message)` to
+  # fail — anything else (even `nil`) means the value passed.
   #
   # config.validators.register(:uuid, proc do |value, _options|
   #   unless value.to_s.match?(/\A[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/i)
@@ -110,11 +141,13 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Retriers
+  # https://drexed.github.io/cmdx/retries/
   # ===========================================================================
-  # Registered retriers compute the sleep duration between `retry_on` attempts.
-  # Built-ins: `:exponential` (default), `:linear`, `:fibonacci`, `:half_random`,
-  # `:full_random`, `:bounded_random`, `:decorrelated_jitter`. A callable
-  # receives `call(attempt, delay, prev_delay)` and returns seconds.
+  # Retriers decide how long to wait between `retry_on` attempts. A callable
+  # gets `(attempt, delay, prev_delay)` and returns the next sleep in seconds.
+  #
+  # Built-ins: :exponential (default), :linear, :fibonacci, :half_random,
+  # :full_random, :bounded_random, :decorrelated_jitter.
   #
   # config.retriers.register(:capped_exponential, proc do |attempt, delay, _prev|
   #   [delay * (2**(attempt - 1)), 30.0].min
@@ -122,9 +155,13 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Deprecators
+  # https://drexed.github.io/cmdx/deprecation/
   # ===========================================================================
-  # Registered deprecators dispatch a task class's `deprecation` declaration.
-  # Built-ins: `:log`, `:warn`, `:error`. A callable receives `call(task)`.
+  # Decide what happens when a task with a `deprecation` declaration runs —
+  # log a warning, raise, ping your error tracker, whatever you like. The
+  # callable receives the task instance.
+  #
+  # Built-ins: :log, :warn, :error.
   #
   # config.deprecators.register(:notify, proc do |task|
   #   Bugsnag.notify("Deprecated task invoked: #{task.class.name}")
@@ -132,11 +169,13 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Executors
+  # https://drexed.github.io/cmdx/workflows/#parallel-execution
   # ===========================================================================
-  # Registered executors drive `:parallel` workflow groups. Built-ins:
-  # `:threads` (default), `:fibers`. A callable receives
-  # `call(jobs:, concurrency:, on_job:)` and must invoke `on_job.call(job)`
-  # for each job, blocking until every job is done.
+  # Executors power `:parallel` workflow groups. The callable gets
+  # `(jobs:, concurrency:, on_job:)`, runs `on_job.call(job)` for every job,
+  # and blocks until every job is done.
+  #
+  # Built-ins: :threads (default), :fibers.
   #
   # config.executors.register(:ractors, proc do |jobs:, concurrency:, on_job:|
   #   jobs.each_slice(concurrency) do |slice|
@@ -146,10 +185,12 @@ CMDx.configure do |config|
 
   # ===========================================================================
   # Mergers
+  # https://drexed.github.io/cmdx/workflows/#parallel-execution
   # ===========================================================================
-  # Merge strategies fold successful parallel task contexts back into the
-  # workflow context. Built-ins: `:last_write_wins` (default), `:deep_merge`,
-  # `:no_merge`. A callable receives `call(workflow_context, result)`.
+  # After parallel branches succeed, a merger folds each branch's context back
+  # into the workflow context. The callable gets `(workflow_context, result)`.
+  #
+  # Built-ins: :last_write_wins (default), :deep_merge, :no_merge.
   #
   # config.mergers.register(:whitelist, proc do |workflow_context, result|
   #   result.context.to_h.slice(:order_id, :total).each do |key, value|

data/mkdocs.yml

@@ -189,6 +189,7 @@ nav:
       - Tips and Tricks: tips_and_tricks.md
       - Comparison: comparison.md
       - v1 → v2 Migration: v2-migration.md
+      - Examples: https://github.com/drexed/cmdx/blob/main/examples/index.md
     - References:
       - API Documentation: https://drexed.github.io/cmdx/api/index.html
       - llms.txt: https://drexed.github.io/cmdx/llms.txt

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Juan Gomez