activeinteractor 2.0.0.alpha.2.3.3 → 2.0.0.alpha.2.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7e53178ed391a9de1b1841a29f7655f66aa61e70d54e3a00df830550f71c70a
-  data.tar.gz: 462c26605e5db213de957fa7d6afd076849b500e93e4dc45f2ea0cc57a927ba5
+  metadata.gz: d75851d221fb7d266849601c5eef65939edfb615419818393ca9ea9b165a4279
+  data.tar.gz: '08f62a487d21f34df03f63b0dc112010df68fbb0a6aa6f3931d972eb0dbaed36'
 SHA512:
-  metadata.gz: 278fbc63da4056d07904f48547e4ac40942e380194294d1836dbe866c665e16799e12e2fbcd1f47efc65ccfaab80bb84ce2c91e40ca53395e1648cd7d0cdcf9c
-  data.tar.gz: d35e2da1526d2b9f069227b72e048e2c55c38995dd539760b8338e8087afd487afe0257e45551b33921895781a16d04022d9c56cda2b8ef9294b0e95ec9d46de
+  metadata.gz: 533fa79817a6d0598c1dac316da54f19ac5e96067ede7f65869f26a2c84b5481a134fab044ed947061d6a19f9021c829dc428456e4cb25483ea276b44c5ba6a7
+  data.tar.gz: 9efe50f237b0bd204678158dd9ba27482b93e640193f8c3f3cbd71025d2b46fb1490bbb19bf25b31adeecdb02298947dbf41a1bd7cb03659c3bc1871faf1605e

data/lib/active_interactor/active_model_error_methods.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 module ActiveInteractor
+  # @private
   module ActiveModelErrorMethods
     extend ActiveSupport::Concern
 
     attr_reader :errors
 
+    # @private
     module ClassMethods
       def human_attribute_name(attribute, _options = {})
         attribute.respond_to?(:to_s) ? attribute.to_s.humanize : attribute

data/lib/active_interactor/base.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module ActiveInteractor
-  class Base < ActiveInteractor::Interactor::Base
-    include Type::DeclerationMethods
-  end
+  # The Main interface for ActiveInteractor
+  #
+  # @deprecated will be removed in version 2.0.0-alpha.3.0.0
+  #   use {ActiveInteractor::Interactor::Base} instead
+  class Base < ActiveInteractor::Interactor::Base; end
 end

data/lib/active_interactor/context.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveInteractor
+  # The Context namespace
   module Context
     extend ActiveSupport::Autoload
 

data/lib/active_interactor/errors.rb

@@ -1,9 +1,22 @@
 # frozen_string_literal: true
 
 module ActiveInteractor
+  # Raised when an interactor fails
+  #
+  # @!attribute [r] result
+  #  @return [ActiveInteractor::Result] An instance of {ActiveInteractor::Result} for the
+  #    {ActiveInteractor::Interactor::Base interactor} that failed
   class Error < StandardError
     attr_reader :result
 
+    # Create a new instance of {ActiveInteractor::Error}
+    #
+    # @param result [ActiveInteractor::Result] An instance of {ActiveInteractor::Result} for the
+    #   {ActiveInteractor::Interactor::Base interactor} that failed
+    # @param message [String] The error message
+    #
+    # @private
+    # @return [ActiveInteractor::Error]
     def initialize(result, message = nil)
       @result = result
       super(message)

data/lib/active_interactor/interactor/base.rb

@@ -5,6 +5,7 @@ module ActiveInteractor
     class Base
       include ContextMethods
       include InteractionMethods
+      include Type::DeclerationMethods
 
       def initialize(input = {})
         @raw_input = input.dup

data/lib/active_interactor/interactor.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveInteractor
+  # The Interactor namespace
   module Interactor
     extend ActiveSupport::Autoload
 

data/lib/active_interactor/result.rb

@@ -1,11 +1,64 @@
 # frozen_string_literal: true
 
 module ActiveInteractor
+  # The object returned by an {ActiveInteractor::Interactor::Base interactor}
+  #
+  # @!attribute [r] data
+  #
+  #  @example Given an {ActiveInteractor::Interactor::Base interactor} that creates an ActiveRecord User
+  #   class CreateUser < ActiveInteractor::Interactor::Base
+  #     argument :login, String, 'The login for the User', required: true
+  #     argument :password, String, 'The password for the User', required: true
+  #     argument :password_confirmation, String, 'The password confirmation for the user', required: true
+  #
+  #     returns :user, User, 'The created User', required: true
+  #
+  #     def interact
+  #       context.user = User.new(context)
+  #       fail!(context.user.errors) unless context.user.save
+  #     end
+  #   end
+  #
+  #   result = CreateUser.perform(login: 'johndoe', password: 'password', password_confirmation: 'password')
+  #   result.data.user
+  #
+  #   #=> <# User @login='johndoe'>
+  #
+  #  @return [ActiveInteractor::Context::Result] the data returned by the
+  #   {ActiveInteractor::Interactor::Base interactor}
+  #
+  # @!attribute [r] errors
+  #  @return [ActiveModel::Errors] the errors returned by the
+  #   {ActiveInteractor::Interactor::Base interactor}
+  #  @see https://github.com/rails/rails/blob/main/activemodel/lib/active_model/errors.rb ActiveModel::Errors
   class Result
     include ActiveModelErrorMethods
 
+    # @!method to_json
+    # The {ActiveInteractor::Interactor::Base result} as a Hash
+    #
+    # @example When an {ActiveInteractor::Interactor::Base interactor} succeeds
+    #  result = CreateUser.perform(login: 'johndoe', password: 'password', password_confirmation: 'password')
+    #  result.to_hash
+    #
+    #  #=> { :success => true, :errors => {}, :data => { :login => 'johndoe' } }
+    #
+    # @example When an {ActiveInteractor::Interactor::Base interactor} fails
+    #  result = CreateUser.perform(login: 'johndoe', password: 'password', password_confirmation: 'notpassword')
+    #  result.to_hash
+    #
+    #  #=> {
+    #  #=>   :success => false,
+    #  #=>   :errors => { :password_confirmation => ["doesn't match Password"] },
+    #  #=>   :data => { :login => 'johndoe' }
+    #  #=> }
+    #
+    # @deprecated will be removed in version 2.0.0-alpha.3.0.0
+    #  use {#to_hash} instead
+    # @return [Hash {Symbol => Boolean, Hash}]
     delegate :to_json, to: :to_hash
 
+    # @private
     STATUS = {
       success: 0,
       failed_at_input: 1,
@@ -16,10 +69,12 @@ module ActiveInteractor
     attr_reader :data
 
     class << self
+      # @private
       def success(data: {})
         new(status: STATUS[:success], data: data)
       end
 
+      # @private
       def failure(data: {}, errors: {}, status: STATUS[:failed_at_runtime])
         result = new(status: status, data: data)
         parse_errors(errors).each_pair do |attribute, messages|
@@ -43,27 +98,65 @@ module ActiveInteractor
     end
 
     private_class_method :new
-
+    # @private
     def initialize(status:, data: {})
       @status = status
       @data = data
       @errors = ActiveModel::Errors.new(self)
     end
 
+    # Whether or not the {ActiveInteractor::Interactor::Base result} is a failure
+    #
+    # @example When an {ActiveInteractor::Interactor::Base interactor} fails
+    #  result = CreateUser.perform(login: 'johndoe', password: 'password', password_confirmation: 'notpassword')
+    #  result.failure?
+    #
+    #  #=> true
+    #
+    # @example When an {ActiveInteractor::Interactor::Base interactor} succeeds
+    #  result = CreateUser.perform(login: 'johndoe', password: 'password', password_confirmation: 'password')
+    #  result.failure?
+    #
+    #  #=> false
+    #
+    # @return [Boolean]
     def failure?
       !success?
     end
     alias failed? failure?
 
+    # @private
     def read_attribute_for_validation(attribute_name)
       data.send(attribute_name.to_sym)
     end
 
+    # Whether or not the {ActiveInteractor::Interactor::Base result} is a success
+    #
+    # @return [Boolean]
     def success?
       @status == STATUS[:success]
     end
     alias successful? success?
 
+    # The {ActiveInteractor::Interactor::Base result} as a Hash
+    #
+    # @example When an {ActiveInteractor::Interactor::Base interactor} succeeds
+    #  result = CreateUser.perform(login: 'johndoe', password: 'password', password_confirmation: 'password')
+    #  result.to_hash
+    #
+    #  #=> { :success => true, :errors => {}, :data => { :login => 'johndoe' } }
+    #
+    # @example When an {ActiveInteractor::Interactor::Base interactor} fails
+    #  result = CreateUser.perform(login: 'johndoe', password: 'password', password_confirmation: 'notpassword')
+    #  result.to_hash
+    #
+    #  #=> {
+    #  #=>   :success => false,
+    #  #=>   :errors => { :password_confirmation => ["doesn't match Password"] },
+    #  #=>   :data => { :login => 'johndoe' }
+    #  #=> }
+    #
+    # @return [Hash {Symbol => Boolean, Hash}]
     def to_hash
       {
         success: success?,

data/lib/active_interactor/type.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveInteractor
+  # @private
   module Type
     extend ActiveSupport::Autoload
 

data/lib/active_interactor.rb

@@ -6,6 +6,36 @@ require 'active_support/core_ext'
 
 require_relative 'active_interactor/errors'
 
+# ## License
+#
+# Copyright (c) 2023 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
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# {file:CHANGELOG.md Changelog}
+#
+# {file:HUMANS.md Acknowledgements}
+#
+# {file:SECURITY.md Security Policy}
+#
+# @author {hello@aaronmallen.me Aaron Allen}
+
 module ActiveInteractor
   extend ActiveSupport::Autoload
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activeinteractor
 version: !ruby/object:Gem::Version
-  version: 2.0.0.alpha.2.3.3
+  version: 2.0.0.alpha.2.3.4
 platform: ruby
 authors:
 - Aaron Allen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-16 00:00:00.000000000 Z
+date: 2023-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -93,9 +93,10 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/activeinteractor/activeinteractor/issues
-  changelog_uri: https://github.com/activeinteractor/activeinteractor/blob/v2.0.0-alpha.2.3.3/CHANGELOG.md
+  changelog_uri: https://github.com/activeinteractor/activeinteractor/blob/v2.0.0-alpha.2.3.4/CHANGELOG.md
   homepage_uri: https://github.com/activeinteractor/activeinteractor
-  source_code_uri: https://github.com/activeinteractor/activeinteractor/tree/v2.0.0-alpha.2.3.3
+  source_code_uri: https://github.com/activeinteractor/activeinteractor/tree/v2.0.0-alpha.2.3.4
+  documentation_uri: https://api.activeinteractor.io
   wiki_uri: https://github.com/activeinteractor/activeinteractor/wiki
   rubygems_mfa_required: 'true'
 post_install_message: