cmdx 1.8.0 → 1.9.1

data/lib/cmdx/validator_registry.rb

@@ -7,6 +7,14 @@ module CMDx
 
     extend Forwardable
 
+    # Returns the internal registry mapping validator types to classes.
+    #
+    # @return [Hash{Symbol => Class}] Hash of validator type names to validator classes
+    #
+    # @example
+    #   registry.registry # => { presence: Validators::Presence, format: Validators::Format }
+    #
+    # @rbs @registry: Hash[Symbol, Class]
     attr_reader :registry
     alias to_h registry
 
@@ -17,6 +25,8 @@ module CMDx
     # @param registry [Hash, nil] Optional hash mapping validator names to validator classes
     #
     # @return [ValidatorRegistry] A new validator registry instance
+    #
+    # @rbs (?Hash[Symbol, Class]? registry) -> void
     def initialize(registry = nil)
       @registry = registry || {
         exclusion: Validators::Exclusion,
@@ -31,6 +41,8 @@ module CMDx
     # Create a duplicate of the registry with copied internal state.
     #
     # @return [ValidatorRegistry] A new validator registry with duplicated registry hash
+    #
+    # @rbs () -> ValidatorRegistry
     def dup
       self.class.new(registry.dup)
     end
@@ -45,6 +57,8 @@ module CMDx
     # @example
     #   registry.register(:custom, CustomValidator)
     #   registry.register("email", EmailValidator)
+    #
+    # @rbs ((String | Symbol) name, Class validator) -> self
     def register(name, validator)
       registry[name.to_sym] = validator
       self
@@ -59,6 +73,8 @@ module CMDx
     # @example
     #   registry.deregister(:format)
     #   registry.deregister("presence")
+    #
+    # @rbs ((String | Symbol) name) -> self
     def deregister(name)
       registry.delete(name.to_sym)
       self
@@ -77,6 +93,8 @@ module CMDx
     # @example
     #   registry.validate(:presence, task, user.name, presence: true)
     #   registry.validate(:length, task, password, { min: 8, allow_nil: false })
+    #
+    # @rbs (Symbol type, Task task, untyped value, untyped options) -> untyped
     def validate(type, task, value, options = {})
       raise TypeError, "unknown validator type #{type.inspect}" unless registry.key?(type)
 

data/lib/cmdx/validators/exclusion.rb

@@ -32,6 +32,8 @@ module CMDx
       #   # => raises ValidationError if value is 5 (within 1..10)
       # @example Exclude with custom message
       #   Exclusion.call("test", in: ["test", "demo"], message: "value %{values} is forbidden")
+      #
+      # @rbs (untyped value, Hash[Symbol, untyped] options) -> nil
       def call(value, options = {})
         values = options[:in] || options[:within]
 

data/lib/cmdx/validators/format.rb

@@ -38,6 +38,8 @@ module CMDx
       # @example Validate with custom message
       #   Format.call("invalid", with: /\A\d+\z/, message: "Must contain only digits")
       #   # => raises ValidationError with custom message
+      #
+      # @rbs (untyped value, (Hash[Symbol, untyped] | Regexp) options) -> nil
       def call(value, options = {})
         match =
           if options.is_a?(Regexp)

data/lib/cmdx/validators/inclusion.rb

@@ -34,6 +34,8 @@ module CMDx
       #   # => nil (validation passes - 5 is within 1..10)
       # @example Include with custom message
       #   Inclusion.call("test", in: ["admin", "user"], message: "must be one of: %{values}")
+      #
+      # @rbs (untyped value, Hash[Symbol, untyped] options) -> nil
       def call(value, options = {})
         values = options[:in] || options[:within]
 

data/lib/cmdx/validators/length.rb

@@ -51,6 +51,8 @@ module CMDx
       # @example Exclusion validation
       #   Length.call("short", not_in: 1..3)
       #   # => nil (validation passes - length 5 is not in excluded range)
+      #
+      # @rbs (untyped value, Hash[Symbol, untyped] options) -> nil
       def call(value, options = {})
         length = value&.length
 
@@ -87,6 +89,8 @@ module CMDx
       # @param options [Hash] Validation options containing custom messages
       #
       # @raise [ValidationError] Always raised with appropriate message
+      #
+      # @rbs (Integer min, Integer max, Hash[Symbol, untyped] options) -> void
       def raise_within_validation_error!(min, max, options)
         message = options[:within_message] || options[:in_message] || options[:message]
         message %= { min:, max: } unless message.nil?
@@ -101,6 +105,8 @@ module CMDx
       # @param options [Hash] Validation options containing custom messages
       #
       # @raise [ValidationError] Always raised with appropriate message
+      #
+      # @rbs (Integer min, Integer max, Hash[Symbol, untyped] options) -> void
       def raise_not_within_validation_error!(min, max, options)
         message = options[:not_within_message] || options[:not_in_message] || options[:message]
         message %= { min:, max: } unless message.nil?
@@ -114,6 +120,8 @@ module CMDx
       # @param options [Hash] Validation options containing custom messages
       #
       # @raise [ValidationError] Always raised with appropriate message
+      #
+      # @rbs (Integer min, Hash[Symbol, untyped] options) -> void
       def raise_min_validation_error!(min, options)
         message = options[:min_message] || options[:message]
         message %= { min: } unless message.nil?
@@ -127,6 +135,8 @@ module CMDx
       # @param options [Hash] Validation options containing custom messages
       #
       # @raise [ValidationError] Always raised with appropriate message
+      #
+      # @rbs (Integer max, Hash[Symbol, untyped] options) -> void
       def raise_max_validation_error!(max, options)
         message = options[:max_message] || options[:message]
         message %= { max: } unless message.nil?
@@ -140,6 +150,8 @@ module CMDx
       # @param options [Hash] Validation options containing custom messages
       #
       # @raise [ValidationError] Always raised with appropriate message
+      #
+      # @rbs (Integer is, Hash[Symbol, untyped] options) -> void
       def raise_is_validation_error!(is, options)
         message = options[:is_message] || options[:message]
         message %= { is: } unless message.nil?
@@ -153,6 +165,8 @@ module CMDx
       # @param options [Hash] Validation options containing custom messages
       #
       # @raise [ValidationError] Always raised with appropriate message
+      #
+      # @rbs (Integer is_not, Hash[Symbol, untyped] options) -> void
       def raise_is_not_validation_error!(is_not, options)
         message = options[:is_not_message] || options[:message]
         message %= { is_not: } unless message.nil?

data/lib/cmdx/validators/numeric.rb

@@ -48,6 +48,8 @@ module CMDx
       # @example Validate value exclusion
       #   Numeric.call(5, not_in: 1..10)
       #   # => nil (validation passes - 5 is not in 1..10)
+      #
+      # @rbs (Numeric value, Hash[Symbol, untyped] options) -> nil
       def call(value, options = {})
         case options
         in within:
@@ -82,6 +84,8 @@ module CMDx
       # @param options [Hash] Validation options containing custom messages
       #
       # @raise [ValidationError] With appropriate error message
+      #
+      # @rbs (Numeric min, Numeric max, Hash[Symbol, untyped] options) -> void
       def raise_within_validation_error!(min, max, options)
         message = options[:within_message] || options[:in_message] || options[:message]
         message %= { min:, max: } unless message.nil?
@@ -96,6 +100,8 @@ module CMDx
       # @param options [Hash] Validation options containing custom messages
       #
       # @raise [ValidationError] With appropriate error message
+      #
+      # @rbs (Numeric min, Numeric max, Hash[Symbol, untyped] options) -> void
       def raise_not_within_validation_error!(min, max, options)
         message = options[:not_within_message] || options[:not_in_message] || options[:message]
         message %= { min:, max: } unless message.nil?
@@ -109,6 +115,8 @@ module CMDx
       # @param options [Hash] Validation options containing custom messages
       #
       # @raise [ValidationError] With appropriate error message
+      #
+      # @rbs (Numeric min, Hash[Symbol, untyped] options) -> void
       def raise_min_validation_error!(min, options)
         message = options[:min_message] || options[:message]
         message %= { min: } unless message.nil?
@@ -122,6 +130,8 @@ module CMDx
       # @param options [Hash] Validation options containing custom messages
       #
       # @raise [ValidationError] With appropriate error message
+      #
+      # @rbs (Numeric max, Hash[Symbol, untyped] options) -> void
       def raise_max_validation_error!(max, options)
         message = options[:max_message] || options[:message]
         message %= { max: } unless message.nil?
@@ -135,6 +145,8 @@ module CMDx
       # @param options [Hash] Validation options containing custom messages
       #
       # @raise [ValidationError] With appropriate error message
+      #
+      # @rbs (Numeric is, Hash[Symbol, untyped] options) -> void
       def raise_is_validation_error!(is, options)
         message = options[:is_message] || options[:message]
         message %= { is: } unless message.nil?
@@ -148,6 +160,8 @@ module CMDx
       # @param options [Hash] Validation options containing custom messages
       #
       # @raise [ValidationError] With appropriate error message
+      #
+      # @rbs (Numeric is_not, Hash[Symbol, untyped] options) -> void
       def raise_is_not_validation_error!(is_not, options)
         message = options[:is_not_message] || options[:message]
         message %= { is_not: } unless message.nil?

data/lib/cmdx/validators/presence.rb

@@ -38,6 +38,8 @@ module CMDx
       # @example Validate with custom message
       #   Presence.call(nil, message: "Value cannot be blank")
       #   # => raises ValidationError with custom message
+      #
+      # @rbs (untyped value, ?Hash[Symbol, untyped] options) -> nil
       def call(value, options = {})
         match =
           if value.is_a?(String)

data/lib/cmdx/version.rb

@@ -2,6 +2,9 @@
 
 module CMDx
 
-  VERSION = "1.8.0"
+  # @return [String] the version of the CMDx gem
+  #
+  # @rbs return: String
+  VERSION = "1.9.1"
 
 end

data/lib/cmdx/workflow.rb

@@ -20,6 +20,8 @@ module CMDx
       #     # This would raise an error:
       #     # def work; end
       #   end
+      #
+      # @rbs (Symbol method_name) -> void
       def method_added(method_name)
         raise "cannot redefine #{name}##{method_name} method" if method_name == :work
 
@@ -37,6 +39,8 @@ module CMDx
       #     task Task2
       #     puts pipeline.size # => 2
       #   end
+      #
+      # @rbs () -> Array[ExecutionGroup]
       def pipeline
         @pipeline ||= []
       end
@@ -55,6 +59,8 @@ module CMDx
       #     include CMDx::Workflow
       #     tasks ValidateTask, ProcessTask, NotifyTask, breakpoints: [:failure, :halt]
       #   end
+      #
+      # @rbs (*untyped tasks, **untyped options) -> void
       def tasks(*tasks, **options)
         pipeline << ExecutionGroup.new(
           tasks.map do |task|
@@ -83,6 +89,8 @@ module CMDx
     #     include CMDx::Workflow
     #     # Now has access to task, tasks, and work methods
     #   end
+    #
+    # @rbs (Class base) -> void
     def self.included(base)
       base.extend(ClassMethods)
     end
@@ -100,6 +108,8 @@ module CMDx
     #
     #   workflow = MyWorkflow.new
     #   result = workflow.work
+    #
+    # @rbs () -> void
     def work
       Pipeline.execute(self)
     end

data/lib/cmdx.rb

@@ -5,6 +5,7 @@ require "date"
 require "forwardable"
 require "json"
 require "logger"
+require "pathname"
 require "securerandom"
 require "set"
 require "time"
@@ -16,6 +17,14 @@ module CMDx
 
   extend self
 
+  # Returns the path to the CMDx gem.
+  #
+  # @return [Pathname] the path to the CMDx gem
+  #
+  # @example
+  #   CMDx.gem_path # => Pathname.new("/path/to/cmdx")
+  #
+  # @rbs return: Pathname
   def gem_path
     @gem_path ||= Pathname.new(__dir__).parent
   end

data/lib/generators/cmdx/locale_generator.rb

@@ -30,7 +30,6 @@ module Cmdx
     #   # Copy Spanish locale file
     #   rails generate cmdx:locale es
     #   # => Creates config/locales/es.yml
-    #
     def copy_locale_files
       copy_file("#{locale}.yml", "config/locales/#{locale}.yml")
     end

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

@@ -32,6 +32,15 @@ CMDx.configure do |config|
     level: Logger::INFO
   )
 
+  # Backtrace configuration - controls whether to log backtraces on faults and exceptions
+  # https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#backtraces
+  # config.backtrace = false
+  # config.backtrace_cleaner = nil
+
+  # Exception handler configuration - called when non-fault exceptions are raised
+  # https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#exception-handler
+  # config.exception_handler = nil
+
   # Additional global configurations - automatically applied to all tasks
   #
   # Middlewares - https://github.com/drexed/cmdx/blob/main/docs/middlewares.md

data/mkdocs.yml

@@ -0,0 +1,122 @@
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+
+site_name: CMDx
+site_url: https://drexed.github.io/cmdx/
+site_description: Build business logic that's powerful, predictable, and chaos-free.
+site_author: drexed
+repo_name: drexed/cmdx
+repo_url: https://github.com/drexed/cmdx
+edit_uri: edit/main/docs/
+copyright: Drexed, Inc. © 2025 - EoT
+
+theme:
+  name: material
+  logo: assets/favicon.svg
+  favicon: assets/favicon.ico
+  icon:
+    repo: fontawesome/brands/github
+  font:
+    text: Inter
+    code: IBM Plex Mono
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+  features:
+    - navigation.footer
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.instant.progress
+    - navigation.tracking
+    - navigation.sections
+    - navigation.expand
+    - navigation.path
+    - navigation.top
+    - search.share
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - tables
+  - attr_list
+  - md_in_html
+  - toc:
+      permalink: true
+
+plugins:
+  - search
+
+nav:
+  - Home: index.md
+  - Getting Started: getting_started.md
+  - Basics:
+    - Setup: basics/setup.md
+    - Execution: basics/execution.md
+    - Context: basics/context.md
+    - Chain: basics/chain.md
+  - Interruptions:
+    - Halt: interruptions/halt.md
+    - Faults: interruptions/faults.md
+    - Exceptions: interruptions/exceptions.md
+  - Outcomes:
+    - Result: outcomes/result.md
+    - States: outcomes/states.md
+    - Statuses: outcomes/statuses.md
+  - Attributes:
+    - Definitions: attributes/definitions.md
+    - Naming: attributes/naming.md
+    - Coercions: attributes/coercions.md
+    - Validations: attributes/validations.md
+    - Defaults: attributes/defaults.md
+    - Transformations: attributes/transformations.md
+  - Callbacks: callbacks.md
+  - Middlewares: middlewares.md
+  - Logging: logging.md
+  - Internationalization: internationalization.md
+  - Deprecation: deprecation.md
+  - Workflows: workflows.md
+  - Tips and Tricks: tips_and_tricks.md
+
+extra:
+  generator: false
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/drexed/cmdx
+
+extra_css:
+  - stylesheets/extra.css

data/src/cmdx-favicon.svg

@@ -0,0 +1 @@
+<svg width="104.098" height="112.266" viewBox="0 0 60 64.708" xmlns="http://www.w3.org/2000/svg"><path d="M29.907 17.723 26.4 23.17 13.384 3.323h3.507l9.508 14.77 1.938-3.139L18.737 0H7.291L26.4 29.262 45.045 0h-3.97L30 17.54zM9.23 61.293H6.091l18.646-29.447L4.43.093H.46l20.308 31.846L0 64.708l10.985-.092 39.138-61.2h3.323L31.57 37.754l13.662 21.415h3.97L35.445 37.754 59.537.093H48.37zm29.63-23.262 15.047 23.262H43.384l-13.662-20.77-15.508 24.093h3.97l11.63-18 11.723 18H60L41.17 35.354l-.278-.461z" fill="#000"/></svg>

data/src/cmdx-logo.svg

@@ -0,0 +1 @@
+<svg width="352.2" height="112.266" viewBox="0 0 203 64.708" xmlns="http://www.w3.org/2000/svg" xmlSpace="preserve"><path d="M172.908 17.723 169.4 23.17 156.385 3.323h3.507l9.508 14.77 1.938-3.139L161.738 0h-11.446L169.4 29.262 188.046 0h-3.97L173 17.54zm-20.677 43.57h-3.139l18.646-29.447L147.431.093h-3.97l20.308 31.846L143 64.708l10.985-.092 39.138-61.2h3.323L174.57 37.754l13.662 21.415h3.969l-13.754-21.415L202.538.093H191.37zm29.63-23.262 15.047 23.262h-10.523l-13.662-20.77-15.508 24.093h3.97l11.63-18 11.723 18H203l-18.83-29.262-.278-.461z" fill="#fe1817"/><path d="M41.667 14v12.8h-23.42c-3.214.272-5.665 3.05-5.665 6.318s2.45 5.937 5.664 6.318H33.17v4.248H18.246a10.65 10.65 0 0 1-9.858-10.62c0-5.447 4.194-10.077 9.64-10.512h19.39v-4.303H18.246v.054A14.823 14.823 0 0 0 4.248 33.118c0 7.898 6.21 14.38 13.998 14.815h19.172v-8.497h4.249v12.745h-23.42A19.063 19.063 0 0 1 0 33.118a19.033 19.033 0 0 1 18.246-19.063zM75 35.623 87.2 14h13.508v38.181H87.963v-14.27l-8.116 14.27h-9.749L57.734 30.504v-8.007l14.87 25.436h4.792l14.815-25.436v25.436h4.249V18.249H89.65l-14.76 25.49-14.542-25.49H53.54v29.684h4.194v-8.007l4.249 7.299v4.956H49.292v-38.18H62.8zM108.333 14h23.42C141.94 14.436 150 22.824 150 33.064c0 10.294-8.061 18.681-18.246 19.117h-23.42V22.497h23.42a10.65 10.65 0 0 1 9.858 10.621c0 5.447-4.194 10.13-9.64 10.566H116.83V30.286h4.248v9.15l10.676-.054c3.213-.273 5.664-3.05 5.664-6.264 0-2.778-1.743-5.065-4.194-5.991-.926-.382-1.47-.382-2.94-.382h-17.702v21.188h19.172a14.84 14.84 0 0 0 13.998-14.87c0-7.897-6.21-14.379-13.998-14.814h-23.42z"/></svg>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.1
 platform: ruby
 authors:
 - Juan Gomez
@@ -214,10 +214,14 @@ files:
 - LLM.md
 - README.md
 - Rakefile
+- docs/.DS_Store
+- docs/assets/favicon.ico
+- docs/assets/favicon.svg
 - docs/attributes/coercions.md
 - docs/attributes/defaults.md
 - docs/attributes/definitions.md
 - docs/attributes/naming.md
+- docs/attributes/transformations.md
 - docs/attributes/validations.md
 - docs/basics/chain.md
 - docs/basics/context.md
@@ -226,6 +230,7 @@ files:
 - docs/callbacks.md
 - docs/deprecation.md
 - docs/getting_started.md
+- docs/index.md
 - docs/internationalization.md
 - docs/interruptions/exceptions.md
 - docs/interruptions/faults.md
@@ -235,8 +240,11 @@ files:
 - docs/outcomes/result.md
 - docs/outcomes/states.md
 - docs/outcomes/statuses.md
+- docs/stylesheets/extra.css
 - docs/tips_and_tricks.md
 - docs/workflows.md
+- examples/active_record_query_tagging.md
+- examples/paper_trail_whatdunnit.md
 - lib/cmdx.rb
 - lib/cmdx/.DS_Store
 - lib/cmdx/attribute.rb
@@ -265,7 +273,6 @@ files:
 - lib/cmdx/exceptions.rb
 - lib/cmdx/executor.rb
 - lib/cmdx/faults.rb
-- lib/cmdx/freezer.rb
 - lib/cmdx/identifier.rb
 - lib/cmdx/locale.rb
 - lib/cmdx/log_formatters/json.rb
@@ -386,7 +393,11 @@ files:
 - lib/locales/zh-HK.yml
 - lib/locales/zh-TW.yml
 - lib/locales/zh-YUE.yml
-- src/cmdx-logo.png
+- mkdocs.yml
+- src/cmdx-dark-logo.png
+- src/cmdx-favicon.svg
+- src/cmdx-light-logo.png
+- src/cmdx-logo.svg
 homepage: https://github.com/drexed/cmdx
 licenses:
 - MIT

data/lib/cmdx/freezer.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  # Provides freezing functionality for CMDx tasks and their associated objects.
-  #
-  # The Freezer module is responsible for making task objects immutable after execution
-  # to prevent accidental modifications and ensure data integrity. It can be disabled
-  # via environment variable for testing or debugging purposes.
-  module Freezer
-
-    extend self
-
-    # Freezes a task and its associated objects to prevent modifications.
-    #
-    # This method makes the task, result, context, and chain immutable after execution.
-    # Freezing can be skipped by setting the SKIP_CMDX_FREEZING environment variable.
-    #
-    # @param task [Task] The task instance to freeze
-    # @option ENV["SKIP_CMDX_FREEZING"] [String, Boolean] Set to "true" or true to skip freezing
-    #
-    # @raise [RuntimeError] If attempting to stub on frozen objects
-    #
-    # @example Freeze a completed task
-    #   task = MyTask.new
-    #   task.execute
-    #   CMDx::Freezer.immute(task)
-    #   # task, result, context, and chain are now frozen
-    # @example Skip freezing for testing
-    #   ENV["SKIP_CMDX_FREEZING"] = "true"
-    #   CMDx::Freezer.immute(task)
-    #   # No freezing occurs
-    def immute(task)
-      # Stubbing on frozen objects is not allowed
-      skip_freezing = ENV.fetch("SKIP_CMDX_FREEZING", false)
-      return if Coercions::Boolean.call(skip_freezing)
-
-      task.freeze
-      task.result.freeze
-
-      # Freezing the context and chain can only be done
-      # once the outer-most task has completed.
-      return unless task.result.index.zero?
-
-      task.context.freeze
-      task.chain.freeze
-
-      Chain.clear
-    end
-
-  end
-end