domainic-command 0.1.0.alpha.1.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cdb2e918654e0c6287f9aeaf7d65db72fdb12b45d9c70809c78d908069a7748
-  data.tar.gz: 2b537214957be06288517fd475203cae6d7bf58bda96df38e0b903b3a86d644c
+  metadata.gz: 37af16c660cced1f71598b53c4eebd3930683e76cbc5c5c32f715071b976dd58
+  data.tar.gz: 89dd55523e0a75bfd2ffacc209b1b3cb968eadadd413dfd4208772794a841919
 SHA512:
-  metadata.gz: db9e2b2098d586300d92035a695085df3744300c3a04b0584cdb35c6b86ccfa30f64c22b50a0e6fe1ceae88b1014d75ce940a08dc16691d8a656fc5f39c86c97
-  data.tar.gz: '08186473bb926e22a1a4fea1f13d15055d87a69e20f4d74c2630d17c48f9a977aac7cd627f4fb5b21982a925251f1a0aa91d2335a02b9dc73949cc884c294d2b'
+  metadata.gz: 75144138e2240b1e90c5e16935747c3f8d5073d28cc957227ec661839441953357a95fdf60664ada068af81e6ade28c6dbe88fac2ff86cd0988526473d1a19bb
+  data.tar.gz: 7658065d96b7264d047461f69f4d3a4985988e17c663df668e3a91d98327f9460f17d5b39917c0f9abd5e9d06d30ca0d185f02185b514dd98e22c79a2e3010bb

data/.yardopts

@@ -0,0 +1,11 @@
+--title Domainic::Command
+--readme README.md
+--no-private
+--protected
+--markup markdown
+--markup-provider redcarpet
+--embed-mixins
+--tag rbs
+--hide-tag rbs
+--files CHANGELOG.md,LICENSE
+'lib/**/*.rb'

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog], and this project adheres to [Break Versioning].
+
+## [Unreleased]
+
+## [v0.1.0] - 2024-12-29
+
+* Initial release
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
+[Break Versioning]: https://www.taoensso.com/break-versioning
+
+<!-- versions -->
+
+[Unreleased]: https://github.com/domainic/domainic/compare/domainic-command-v0.1.0...HEAD
+[v0.1.0]: https://github.com/domainic/domainic/compare/1fdeec3d5d3c6bfe61c2186ba848681c51469e90...domainic-command-v0.1.0

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2024 Aaron Allen
+Copyright (c) Aaron Allen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,3 +1,94 @@
-# Domainic
+# Domainic::Command
 
-Coming Soon
+[![Domainic::Command Version](https://img.shields.io/gem/v/domainic-command?style=for-the-badge&logo=rubygems&logoColor=white&logoSize=auto&label=Gem%20Version)](https://rubygems.org/gems/domainic-command)
+[![Domainic::Command License](https://img.shields.io/github/license/domainic/domainic?style=for-the-badge&logo=opensourceinitiative&logoColor=white&logoSize=auto)](./LICENSE)
+[![Domainic::Command Docs](https://img.shields.io/badge/rubydoc-blue?style=for-the-badge&logo=readthedocs&logoColor=white&logoSize=auto&label=docs)](https://rubydoc.info/gems/domainic-command/0.1.0)
+[![Domainic::Command Open Issues](https://img.shields.io/github/issues-search/domainic/domainic?query=state%3Aopen%20label%3Adomainic-command&style=for-the-badge&logo=github&logoColor=white&logoSize=auto&label=issues&color=red)](https://github.com/domainic/domainic/issues?q=state%3Aopen%20label%3Adomainic-command%20)
+
+A robust implementation of the Command pattern for Ruby applications, providing type-safe, self-documenting business
+operations with standardized error handling and composable workflows.
+
+Tired of scattered business logic and unclear error handling? Domainic::Command brings clarity to your domain operations
+by:
+
+* Enforcing explicit input/output contracts with type validation
+* Providing consistent error handling and status reporting
+* Enabling self-documenting business operations
+* Supporting composable command workflows
+* Maintaining thread safety for concurrent operations
+
+## Quick Start
+
+```ruby
+class CreateUser
+  include Domainic::Command
+
+  # Define expected inputs with validation
+  argument :login, String, "The user's login", required: true
+  argument :password, String, "The user's password", required: true
+
+  # Define expected outputs
+  output :user, User, "The created user", required: true
+  output :created_at, Time, "When the user was created"
+
+  def execute
+    user = User.create!(login: context.login, password: context.password)
+    context.user = user
+    context.created_at = Time.current
+  end
+end
+
+# Success case
+result = CreateUser.call(login: "user@example.com", password: "secret123")
+result.successful? # => true
+result.user       # => #<User id: 1, login: "user@example.com">
+
+# Failure case
+result = CreateUser.call(login: "invalid")
+result.failure?   # => true
+result.errors     # => { password: ["is required"] }
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'domainic-command'
+```
+
+Or install it yourself as:
+
+```bash
+gem install domainic-command
+```
+
+## Key Features
+
+* **Type-Safe Arguments**: Define and validate input parameters with clear type constraints
+* **Explicit Outputs**: Specify expected return values and their requirements
+* **Standardized Error Handling**: Consistent error reporting with detailed failure information
+* **Thread Safety**: Built-in thread safety for class definition and execution
+* **Command Composition**: Build complex workflows by combining simpler commands
+* **Self-Documenting**: Generate clear documentation from your command definitions
+* **Framework Agnostic**: Use with any Ruby application (Rails, Sinatra, pure Ruby)
+
+## Documentation
+
+For detailed usage instructions and examples, see [USAGE.md](./docs/USAGE.md).
+
+## Contributing
+
+We welcome contributions! Please see our
+[Contributing Guidelines](https://github.com/domainic/domainic/wiki/CONTRIBUTING) for:
+
+* Development setup and workflow
+* Code style and documentation standards
+* Testing requirements
+* Pull request process
+
+Before contributing, please review our [Code of Conduct](https://github.com/domainic/domainic/wiki/CODE_OF_CONDUCT).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](./LICENSE).

data/lib/domainic/command/class_methods.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'domainic/command/context/input_context'
+require 'domainic/command/context/output_context'
+require 'domainic/command/context/runtime_context'
+
+module Domainic
+  module Command
+    # Class methods that are extended onto any class that includes {Command}. These methods provide
+    # the DSL for defining command inputs and outputs, as well as class-level execution methods.
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    module ClassMethods
+      # @rbs @input_context_class: singleton(Context::InputContext)
+      # @rbs @output_context_class: singleton(Context::OutputContext)
+      # @rbs @runtime_context_class: singleton(Context::RuntimeContext)
+
+      # Specifies an external input context class for the command
+      #
+      # @param input_context_class [Class] A subclass of {Context::InputContext}
+      #
+      # @raise [ArgumentError] If the provided class is not a subclass of {Context::InputContext}
+      # @return [void]
+      # @rbs (singleton(Context::InputContext) input_context_class) -> void
+      def accepts_arguments_matching(input_context_class)
+        unless input_context_class < Context::InputContext
+          raise ArgumentError, 'Input context class must be a subclass of Context::InputContext'
+        end
+
+        # @type self: Class & ClassMethods
+        @input_context_class = begin
+          const_set(:InputContext, Class.new(input_context_class))
+          const_get(:InputContext)
+        end
+      end
+
+      # Defines an input argument for the command
+      #
+      # @overload argument(name, *type_validator_and_description, **options)
+      #   @param name [String, Symbol] The name of the argument
+      #   @param type_validator_and_description [Array<Class, Module, Object, Proc, String, nil>] Type validator or
+      #     description arguments
+      #   @param options [Hash] Configuration options for the argument
+      #   @option options [Object] :default A static default value
+      #   @option options [Proc] :default_generator A proc that generates the default value
+      #   @option options [Object] :default_value Alias for :default
+      #   @option options [String, nil] :desc Short description of the argument
+      #   @option options [String, nil] :description Full description of the argument
+      #   @option options [Boolean] :required Whether the argument is required
+      #   @option options [Class, Module, Object, Proc] :type A type validator
+      #
+      # @return [void]
+      # @rbs (
+      #   String | Symbol name,
+      #   *(Class | Module | Object | Proc | String)? type_validator_and_description,
+      #   ?default: untyped,
+      #   ?default_generator: untyped,
+      #   ?default_value: untyped,
+      #   ?desc: String?,
+      #   ?description: String?,
+      #   ?required: bool,
+      #   ?type: Class | Module | Object | Proc
+      #   ) -> void
+      def argument(...)
+        input_context_class.argument(...)
+      end
+
+      # Executes the command with the given context, handling any errors
+      #
+      # @param context [Hash] The input context for the command
+      #
+      # @return [Result] The result of the command execution
+      # @rbs (**untyped context) -> Result
+      def call(**context)
+        # @type self: Class & ClassMethods & InstanceMethods
+        new.call(**context)
+      end
+
+      # Executes the command with the given context, raising any errors
+      #
+      # @param context [Hash] The input context for the command
+      #
+      # @raise [ExecutionError] If the command execution fails
+      # @return [Result] The result of the command execution
+      # @rbs (**untyped context) -> Result
+      def call!(**context)
+        # @type self: Class & ClassMethods & InstanceMethods
+        new.call!(**context)
+      end
+
+      # Defines an output field for the command
+      #
+      # @overload output(name, *type_validator_and_description, **options)
+      #   @param name [String, Symbol] The name of the output field
+      #   @param type_validator_and_description [Array<Class, Module, Object, Proc, String, nil>] Type validator or
+      #     description arguments
+      #   @param options [Hash] Configuration options for the output
+      #   @option options [Object] :default A static default value
+      #   @option options [Proc] :default_generator A proc that generates the default value
+      #   @option options [Object] :default_value Alias for :default
+      #   @option options [String, nil] :desc Short description of the output
+      #   @option options [String, nil] :description Full description of the output
+      #   @option options [Boolean] :required Whether the output is required
+      #   @option options [Class, Module, Object, Proc] :type A type validator
+      #
+      # @return [void]
+      # @rbs (
+      #   String | Symbol name,
+      #   *(Class | Module | Object | Proc | String)? type_validator_and_description,
+      #   ?default: untyped,
+      #   ?default_generator: untyped,
+      #   ?default_value: untyped,
+      #   ?desc: String?,
+      #   ?description: String?,
+      #   ?required: bool,
+      #   ?type: Class | Module | Object | Proc
+      #   ) -> void
+      def output(...)
+        output_context_class.field(...)
+      end
+
+      # Specifies an external output context class for the command
+      #
+      # @param output_context_class [Class] A subclass of {Context::OutputContext}
+      #
+      # @raise [ArgumentError] If the provided class is not a subclass of {Context::OutputContext}
+      # @return [void]
+      # @rbs (singleton(Context::OutputContext) output_context_class) -> void
+      def returns_data_matching(output_context_class)
+        unless output_context_class < Context::OutputContext
+          raise ArgumentError, 'Output context class must be a subclass of Context::OutputContext'
+        end
+
+        # @type self: Class & ClassMethods
+        @output_context_class = begin
+          const_set(:OutputContext, Class.new(output_context_class))
+          const_get(:OutputContext)
+        end
+      end
+
+      private
+
+      # Returns the input context class for the command
+      #
+      # @return [Class] A subclass of {Context::InputContext}
+      # @rbs () -> singleton(Context::InputContext)
+      def input_context_class
+        # @type self: Class & ClassMethods
+        @input_context_class ||= begin
+          const_set(:InputContext, Class.new(Context::InputContext)) unless const_defined?(:InputContext)
+          const_get(:InputContext)
+        end
+      end
+
+      # Returns the output context class for the command
+      #
+      # @return [Class] A subclass of {Context::OutputContext}
+      # @rbs () -> singleton(Context::OutputContext)
+      def output_context_class
+        # @type self: Class & ClassMethods
+        @output_context_class ||= begin
+          const_set(:OutputContext, Class.new(Context::OutputContext)) unless const_defined?(:OutputContext)
+          const_get(:OutputContext)
+        end
+      end
+
+      # Returns the runtime context class for the command
+      #
+      # @return [Class] A subclass of {Context::RuntimeContext}
+      # @rbs () -> singleton(Context::RuntimeContext)
+      def runtime_context_class
+        # @type self: Class & ClassMethods
+        @runtime_context_class ||= begin
+          const_set(:RuntimeContext, Class.new(Context::RuntimeContext)) unless const_defined?(:RuntimeContext)
+          const_get(:RuntimeContext)
+        end
+      end
+    end
+  end
+end

data/lib/domainic/command/context/attribute.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Command
+    module Context
+      # Represents an attribute within a command context. This class manages the lifecycle of an attribute, including
+      # its validation, default values, and metadata such as descriptions
+      #
+      # The `Attribute` class supports a variety of configuration options, such as marking an attribute as required,
+      # defining static or dynamic default values, and specifying custom validators. These features ensure that
+      # attributes conform to expected rules and provide useful metadata for documentation or runtime behavior
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class Attribute
+        # Represents an undefined default value for an attribute. This is used internally to distinguish between
+        # an attribute with no default and one with a defined default
+        #
+        # @return [Object] A frozen object representing an undefined default value
+        UNDEFINED_DEFAULT = Object.new.freeze #: Object
+        private_constant :UNDEFINED_DEFAULT
+
+        # @rbs @default: untyped
+        # @rbs @description: String?
+        # @rbs @name: Symbol
+        # @rbs @required: bool
+        # @rbs @type_validator: Class | Module | Object | Proc
+
+        # The textual description of the attribute, providing metadata about its purpose or usage
+        #
+        # @return [String, nil] A description of the attribute
+        attr_reader :description #: String?
+
+        # The name of the attribute, uniquely identifying it within a command context
+        #
+        # @return [Symbol] The name of the attribute
+        attr_reader :name #: Symbol
+
+        # Create a new attribute instance
+        #
+        # @overload initialize(
+        #   name, type_validator_or_description = nil, description_or_type_validator = nil, **options
+        #   )
+        #   @param name [String, Symbol] The {#name} of the attribute
+        #   @param type_validator_or_description [Class, Module, Object, Proc, String, nil] A type validator or the
+        #     {#description} of the attribute
+        #   @param description_or_type_validator [Class, Module, Object, Proc, String, nil] The {#description} or a
+        #     type_validator of the attribute
+        #   @param options [Hash] Configuration options for the attribute
+        #   @option options [Object] :default The {#default} of the attribute
+        #   @option options [Proc] :default_generator An alias for :default
+        #   @option options [Object] :default_value An alias for :default
+        #   @option options [String, nil] :desc An alias for :description
+        #   @option options [String, nil] :description The {#description} of the attribute
+        #   @option options [Boolean] :required Whether the attribute is {#required?}
+        #   @option options [Class, Module, Object, Proc] :type A type validator for the attribute value
+        #
+        #   @return [Attribute] the new Attribute instance
+        # @rbs (
+        #   String | Symbol name,
+        #   *(Class | Module | Object | Proc | String)? type_validator_and_description,
+        #   ?default: untyped,
+        #   ?default_generator: untyped,
+        #   ?default_value: untyped,
+        #   ?desc: String?,
+        #   ?description: String?,
+        #   ?required: bool,
+        #   ?type: Class | Module | Object | Proc
+        #   ) -> void
+        def initialize(name, *type_validator_and_description, **options)
+          symbolized_options = options.transform_keys(&:to_sym)
+
+          @name = name.to_sym
+          @required = symbolized_options[:required] == true
+
+          initialize_default(symbolized_options)
+          initialize_description_and_type_validator(type_validator_and_description, symbolized_options)
+        end
+
+        # Retrieves the default value of the attribute. If a default generator is specified, it evaluates the generator
+        # and returns the result
+        #
+        # @return [Object, nil] The default value or the result of the generator
+        # @rbs () -> untyped
+        def default
+          return unless default?
+
+          @default.is_a?(Proc) ? @default.call : @default
+        end
+
+        # Determines whether the attribute has a default value defined
+        #
+        # @return [Boolean] `true` if a default is set; otherwise, `false`
+        # @rbs () -> bool
+        def default?
+          @default != UNDEFINED_DEFAULT
+        end
+
+        # Determines whether the attribute is marked as required
+        #
+        # @return [Boolean] `true` if the attribute is required; otherwise, `false`
+        # @rbs () -> bool
+        def required?
+          @required
+        end
+
+        # Validates the given value against the attribute's type validator
+        #
+        # @param value [Object] The value to validate
+        #
+        # @return [Boolean] `true` if the value is valid; otherwise, `false`
+        # @rbs (untyped value) -> bool
+        def valid?(value)
+          return false if value.nil? && required?
+          return true if @type_validator.nil?
+
+          validator = @type_validator
+          return validator.call(value) if validator.is_a?(Proc)
+
+          validator === value || value.is_a?(validator) # rubocop:disable Style/CaseEquality
+        end
+
+        private
+
+        # Initializes the {#default} value for the attribute, using the provided options
+        #
+        # @param options [Hash] Configuration options containing default-related keys
+        #
+        # @return [void]
+        # @rbs (Hash[Symbol, untyped] options) -> void
+        def initialize_default(options)
+          @default = if %i[default default_generator default_value].any? { |key| options.key?(key) }
+                       options.values_at(:default, :default_generator, :default_value).compact.first
+                     else
+                       UNDEFINED_DEFAULT
+                     end
+        end
+
+        # Initializes the description and type validator for the attribute based on the given arguments and options
+        #
+        # @param arguments [Array<Class, Module, Object, Proc, String, nil>] Arguments for validators or description
+        # @param options [Hash] Configuration options
+        #
+        # @return [void]
+        # @rbs (Array[(Class | Module | Object | Proc | String)?] arguments, Hash[Symbol, untyped] options) -> void
+        def initialize_description_and_type_validator(arguments, options)
+          @description = arguments.compact.find { |argument| argument.is_a?(String) } ||
+                         options[:description] ||
+                         options[:desc]
+
+          @type_validator = arguments.compact.find { |argument| !argument.is_a?(String) } ||
+                            options[:type]
+        end
+      end
+    end
+  end
+end

data/lib/domainic/command/context/attribute_set.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Command
+    module Context
+      # A collection class for managing a set of command context attributes. This class provides a simple interface
+      # for storing, accessing, and iterating over {Attribute} instances.
+      #
+      # @example
+      #   set = AttributeSet.new
+      #   set.add(Attribute.new(:name))
+      #   set[:name] # => #<Attribute name=:name>
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class AttributeSet
+        # @rbs @lookup: Hash[Symbol, Attribute]
+
+        # Creates a new AttributeSet instance
+        #
+        # @return [AttributeSet]
+        # @rbs () -> void
+        def initialize
+          @lookup = {}
+        end
+
+        # Retrieves an attribute by name
+        #
+        # @param attribute_name [String, Symbol] The name of the attribute to retrieve
+        #
+        # @return [Attribute, nil] The attribute with the given name, or nil if not found
+        # @rbs (String | Symbol attribute_name) -> Attribute?
+        def [](attribute_name)
+          @lookup[attribute_name.to_sym]
+        end
+
+        # Adds an attribute to the set
+        #
+        # @param attribute [Attribute] The attribute to add
+        #
+        # @raise [ArgumentError] If the provided attribute is not an {Attribute} instance
+        # @return [void]
+        # @rbs (Attribute attribute) -> void
+        def add(attribute)
+          unless attribute.is_a?(Attribute)
+            raise ArgumentError, 'Attribute must be an instance of Domainic::Command::Context::Attribute'
+          end
+
+          @lookup[attribute.name] = attribute
+        end
+
+        # Returns all attributes in the set
+        #
+        # @return [Array<Attribute>] An array of all attributes
+        # @rbs () -> Array[Attribute]
+        def all
+          @lookup.values
+        end
+
+        # Iterates over each attribute in the set
+        #
+        # @yield [Attribute] Each attribute in the set
+        #
+        # @return [void]
+        # @rbs () { (Attribute) -> untyped } -> void
+        def each(...)
+          all.each(...)
+        end
+
+        # Iterates over each attribute in the set with an object
+        #
+        # @overload each_with_object(object)
+        #   @param object [Object] The object to pass to the block
+        #   @yield [Attribute, Object] Each attribute and the object
+        #
+        #   @return [Object] The final state of the object
+        # @rbs [U] (U object) { (Attribute, U) -> untyped } -> U
+        def each_with_object(...)
+          all.each_with_object(...) # steep:ignore UnresolvedOverloading
+        end
+
+        private
+
+        # Ensure that Attributes are duplicated when the AttributeSet is duplicated
+        #
+        # @param source [AttributeSet] The source AttributeSet to copy
+        #
+        # @return [AttributeSet]
+        def initialize_copy(source)
+          @lookup = source.instance_variable_get(:@lookup).transform_values(&:dup)
+          super
+        end
+      end
+    end
+  end
+end