servactory 1.5.2 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f9511d2fb9a463c46f04ba4e6f005b14f9048039524a1aed476ee1a4fa997ef
-  data.tar.gz: f5e03fa8943d3a5fd4735ec3817528202ce3b2e06106d81f0ad08fde2e4e4baf
+  metadata.gz: 77500bca8d6ee7ee302e77b8b64eb840a2e004bece8743a2b246e49a49a42b24
+  data.tar.gz: dfff784e9b2787ac349d5e33f84f75a318814ecf64ac0df7915a500b2073f6ef
 SHA512:
-  metadata.gz: 406a99f8386dc97033fd28231e8b11438aa8827878ee332b11efa43747b92f7fcc993b547413733651a93bc0d1f59f6799f4b7e70778038f685d91206ff35be9
-  data.tar.gz: 2895de4a4fc256dcec75cddaddc0ff92b70e9cf42de13309acde95447b0466d4afa8103d52b6ec66e219109065f7f9ffea022c7c41789e88383f32cf08a5e8bb
+  metadata.gz: 16091e0330a74cda1246f0a3a4ccdbc9ed572cba9c29d485e306c95c2405792e12bd9d03cbf13e1e17cf0c40bd4839ea997d75eac7f5f26a199eb8bc757af01a
+  data.tar.gz: 2d67bd5beff3c5a4d73a28a70662b3df52e61757fadc37f15751e745e28f9a3b18cd3af43d84684339debd58b6231ca70bdcbcc8b2af8c20ef76f9eb9e68c883

data/README.md

@@ -5,402 +5,14 @@ A set of tools for building reliable services of any complexity.
 [![Gem version](https://img.shields.io/gem/v/servactory?logo=rubygems&logoColor=fff)](https://rubygems.org/gems/servactory)
 [![Release Date](https://img.shields.io/github/release-date/afuno/servactory)](https://github.com/afuno/servactory/releases)
 
-## Contents
+## Documentation
 
-- [Requirements](#requirements)
-- [Getting started](#getting-started)
-  - [Conventions](#conventions)
-  - [Installation](#installation)
-  - [Preparation](#preparation)
-- [Usage](#usage)
-  - [Minimal example](#minimal-example)
-  - [Call](#call)
-  - [Result](#result)
-  - [Input attributes](#input-attributes)
-    - [Isolated usage](#isolated-usage)
-    - [As an internal argument](#isolated-usage)
-    - [Optional inputs](#optional-inputs)
-    - [As (internal name)](#as-internal-name)
-    - [An array of specific values](#an-array-of-specific-values)
-    - [Inclusion](#inclusion)
-    - [Must](#must)
-  - [Output attributes](#output-attributes)
-  - [Internal attributes](#internal-attributes)
-  - [Make](#make)
-  - [Failures](#failures)
-- [I18n](#i18n)
-- [Testing](#testing)
-- [Thanks](#thanks)
-- [Contributing](#contributing)
+See [servactory.com](https://servactory.com) for documentation.
 
-## Requirements
-
-- Ruby >= 2.7
-
-## Getting started
-
-### Conventions
-
-- Services are subclasses of `Servactory::Base` and are located in the `app/services` directory. It is common practice to create and inherit from `ApplicationService::Base`, which is a subclass of `Servactory::Base`.
-- Name services by what they do, not by what they accept. Try to use verbs in names. For example, `UsersService::Create` instead of `UsersService::Creation`.
-
-### Installation
-
-Add this to `Gemfile`:
-
-```ruby
-gem "servactory"
-```
-
-And execute:
-
-```shell
-bundle install
-```
-
-### Preparation
-
-As a first step, it is recommended to prepare the base class for further inheritance.
-
-#### ApplicationService::Errors
-
-```ruby
-# app/services/application_service/errors.rb
-
-module ApplicationService
-  module Errors
-    class InputArgumentError < Servactory::Errors::InputArgumentError; end
-    class OutputArgumentError < Servactory::Errors::OutputArgumentError; end
-    class InternalArgumentError < Servactory::Errors::InternalArgumentError; end
-
-    class Failure < Servactory::Errors::Failure; end
-  end
-end
-```
-
-#### ApplicationService::Base
-
-```ruby
-# app/services/application_service/base.rb
-
-module ApplicationService
-  class Base < Servactory::Base
-    configuration do
-      input_argument_error_class ApplicationService::Errors::InputArgumentError
-      output_argument_error_class ApplicationService::Errors::OutputArgumentError
-      internal_argument_error_class ApplicationService::Errors::InternalArgumentError
-
-      failure_class ApplicationService::Errors::Failure
-    end
-  end
-end
-```
-
-## Usage
-
-### Minimal example
-
-```ruby
-class MinimalService < ApplicationService::Base
-  make :call
-  
-  private
-  
-  def call
-    # ...
-  end
-end
-```
-
-[More examples](https://github.com/afuno/servactory/tree/main/examples/usual)
-
-### Call
-
-Services can only be called via `.call` and `.call!` methods.
-
-The `.call` method will only fail if it catches an exception in the input arguments.
-Internal and output attributes, as well as methods for failures - all this will be collected in the result.
-
-The `.call!` method will fail if it catches any exception.
-
-#### Via .call
-
-```ruby
-UsersService::Accept.call(user: User.first)
-```
-
-#### Via .call!
-
-```ruby
-UsersService::Accept.call!(user: User.first)
-```
-
-### Result
-
-All services have the result of their work. For example, in case of success this call:
-
-```ruby
-service_result = UsersService::Accept.call!(user: User.first)
-```
-
-Will return this:
-
-```ruby
-#<Servactory::Result:0x0000000107ad9e88 @user="...">
-```
-
-And then you can work with this result, for example, in this way:
-
-```ruby
-Notification::SendJob.perform_later(service_result.user.id)
-```
-
-### Input attributes
-
-#### Isolated usage
-
-With this approach, all input attributes are available only from `inputs`. This is default behaviour.
-
-```ruby
-class UsersService::Accept < ApplicationService::Base
-  input :user, type: User
-
-  make :accept!
-  
-  private
-  
-  def accept!
-    inputs.user.accept!
-  end
-end
-```
-
-#### As an internal argument
-
-With this approach, all input attributes are available from `inputs` as well as directly from the context.
-
-```ruby
-class UsersService::Accept < ApplicationService::Base
-  input :user, type: User, internal: true
-
-  make :accept!
-  
-  private
-  
-  def accept!
-    user.accept!
-  end
-end
-```
-
-#### Optional inputs
-
-By default, all inputs are required. To make an input optional, specify `false` in the `required` option.
-
-```ruby
-class UsersService::Create < ApplicationService::Base
-  input :first_name, type: String
-  input :middle_name, type: String, required: false
-  input :last_name, type: String
-
-  # ...
-end
-```
-
-#### As (internal name)
-
-This option changes the name of the input within the service.
-
-```ruby
-class NotificationService::Create < ApplicationService::Base
-  input :customer, as: :user, type: User
-
-  output :notification, type: Notification
-
-  make :create_notification!
-
-  private
-
-  def create_notification!
-    self.notification = Notification.create!(user: inputs.user)
-  end
-end
-```
-
-#### An array of specific values
-
-```ruby
-class PymentsService::Send < ApplicationService::Base
-  input :invoice_numbers, type: String, array: true
-
-  # ...
-end
-```
-
-#### Inclusion
-
-```ruby
-class EventService::Send < ApplicationService::Base
-  input :event_name, type: String, inclusion: %w[created rejected approved]
-
-  # ...
-end
-```
-
-#### Must
-
-Sometimes there are cases that require the implementation of a specific input attribute check. In such cases `must` can help.
-
-```ruby
-class PymentsService::Send < ApplicationService::Base
-  input :invoice_numbers,
-        type: String,
-        array: true,
-        must: {
-          be_6_characters: {
-            is: ->(value:) { value.all? { |id| id.size == 6 } }
-          }
-        }
-
-  # ...
-end
-```
-
-### Output attributes
-
-```ruby
-class NotificationService::Create < ApplicationService::Base
-  input :user, type: User
-  
-  output :notification, type: Notification
-
-  make :create_notification!
-  
-  private
-  
-  def create_notification!
-    self.notification = Notification.create!(user: inputs.user)
-  end
-end
-```
-
-### Internal attributes
-
-```ruby
-class NotificationService::Create < ApplicationService::Base
-  input :user, type: User
-
-  internal :inviter, type: User
-  
-  output :notification, type: Notification
-
-  make :assign_inviter
-  make :create_notification!
-  
-  private
-  
-  def assign_inviter
-    self.inviter = user.inviter
-  end
-  
-  def create_notification!
-    self.notification = Notification.create!(user: inputs.user, inviter:)
-  end
-end
-```
-
-### Make
-
-#### Minimal example
-
-```ruby
-make :something
-
-def something
-  # ...
-end
-```
-
-#### Condition
-
-```ruby
-make :something, if: -> { Settings.something.enabled }
-
-def something
-  # ...
-end
-```
-
-#### Several
-
-```ruby
-make :assign_api_model
-make :perform_api_request
-make :process_result
-
-def assign_api_model
-  self.api_model = APIModel.new
-end
-
-def perform_api_request
-  self.response = APIClient.resource.create(api_model)
-end
-
-def process_result
-  ARModel.create!(response)
-end
-```
-
-#### Inheritance
-
-Service inheritance is also supported.
-
-### Failures
-
-The methods that are used in `make` may fail. In order to more informatively provide information about this outside the service, the following methods were prepared.
-
-#### Fail
-
-```ruby
-make :check!
-
-def check!
-  return if inputs.invoice_number.start_with?("AA")
-
-  fail!("Invalid invoice number")
-end
-```
-
-#### Fail for input
-
-```ruby
-make :check!
-
-def check!
-  return if inputs.invoice_number.start_with?("AA")
-
-  fail_input!(:invoice_number, "Invalid invoice number")
-end
-```
-
-## I18n
-
-All texts are stored in the localization file. All texts can be changed or supplemented by new locales.
-
-[See en.yml file](https://github.com/afuno/servactory/tree/main/config/locales/en.yml)
-
-## Testing
-
-Testing Servactory services is the same as testing regular Ruby classes.
-
-## Thanks
+## Contributing
 
-Thanks to [@sunny](https://github.com/sunny) for [Service Actor](https://github.com/sunny/actor).
+This project is intended to be a safe, welcoming space for collaboration. Contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. We recommend reading the [contributing guide](./docs/pages/CONTRIBUTING.md) as well.
 
-## Contributing
+## License
 
-1. Fork it (https://github.com/afuno/servactory/fork);
-2. Create your feature branch (`git checkout -b my-new-feature`);
-3. Commit your changes (`git commit -am "Add some feature"`);
-4. Push to the branch (`git push origin my-new-feature`);
-5. Create a new Pull Request.
+ViewComponent is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/config/locales/en.yml

@@ -1,6 +1,6 @@
 en:
   servactory:
-    input_arguments:
+    inputs:
       checks:
         inclusion:
           default_error: "[%{service_class_name}] Wrong value in `%{input_name}`, must be one of `%{input_inclusion}`"
@@ -20,14 +20,14 @@ en:
           error: "[%{service_class_name}] Unexpected attributes: `%{unnecessary_attributes}`"
         rules:
           error: "[%{service_class_name}] Conflict in `%{input_name}` input options: `%{conflict_code}`"
-    internal_arguments:
+    internals:
       checks:
         type:
-          default_error: "[%{service_class_name}] Wrong type of internal argument `%{internal_argument_name}`, expected `%{expected_type}`, got `%{given_type}`"
-    output_arguments:
+          default_error: "[%{service_class_name}] Wrong type of internal attribute `%{internal_name}`, expected `%{expected_type}`, got `%{given_type}`"
+    outputs:
       checks:
         type:
-          default_error: "[%{service_class_name}] Wrong type of output argument `%{output_argument_name}`, expected `%{expected_type}`, got `%{given_type}`"
+          default_error: "[%{service_class_name}] Wrong type of output attribute `%{output_name}`, expected `%{expected_type}`, got `%{given_type}`"
       tools:
         conflicts:
           error: "[%{service_class_name}] Conflict between internal and output attributes `%{overlapping_attributes}`"

data/lib/servactory/base.rb

@@ -4,10 +4,10 @@ module Servactory
   class Base
     include Configuration::DSL
     include Context::DSL
-    include InputArguments::DSL
-    include InternalArguments::DSL
-    include OutputArguments::DSL
-    include MakeMethods::DSL
+    include Inputs::DSL
+    include Internals::DSL
+    include Outputs::DSL
+    include Methods::DSL
 
     private_class_method :new
   end

data/lib/servactory/configuration/factory.rb

@@ -3,21 +3,25 @@
 module Servactory
   module Configuration
     class Factory
-      def input_argument_error_class(input_argument_error_class)
-        Servactory.configuration.input_argument_error_class = input_argument_error_class
+      def input_error_class(input_error_class)
+        Servactory.configuration.input_error_class = input_error_class
       end
 
-      def output_argument_error_class(output_argument_error_class)
-        Servactory.configuration.output_argument_error_class = output_argument_error_class
+      def output_error_class(output_error_class)
+        Servactory.configuration.output_error_class = output_error_class
       end
 
-      def internal_argument_error_class(internal_argument_error_class)
-        Servactory.configuration.internal_argument_error_class = internal_argument_error_class
+      def internal_error_class(internal_error_class)
+        Servactory.configuration.internal_error_class = internal_error_class
       end
 
       def failure_class(failure_class)
         Servactory.configuration.failure_class = failure_class
       end
+
+      def method_shortcuts(method_shortcuts)
+        Servactory.configuration.method_shortcuts.merge(method_shortcuts)
+      end
     end
   end
 end

data/lib/servactory/configuration/setup.rb

@@ -3,17 +3,20 @@
 module Servactory
   module Configuration
     class Setup
-      attr_accessor :input_argument_error_class,
-                    :internal_argument_error_class,
-                    :output_argument_error_class,
-                    :failure_class
+      attr_accessor :input_error_class,
+                    :internal_error_class,
+                    :output_error_class,
+                    :failure_class,
+                    :method_shortcuts
 
       def initialize
-        @input_argument_error_class = Servactory::Errors::InputArgumentError
-        @internal_argument_error_class = Servactory::Errors::InternalArgumentError
-        @output_argument_error_class = Servactory::Errors::OutputArgumentError
+        @input_error_class = Servactory::Errors::InputError
+        @internal_error_class = Servactory::Errors::InternalError
+        @output_error_class = Servactory::Errors::OutputError
 
         @failure_class = Servactory::Errors::Failure
+
+        @method_shortcuts = Servactory::Methods::Shortcuts::Collection.new
       end
     end
   end

data/lib/servactory/context/callable.rb

@@ -8,23 +8,23 @@ module Servactory
 
         assign_data_with(arguments)
 
-        input_arguments_workbench.find_unnecessary!
-        input_arguments_workbench.check_rules!
-        output_arguments_workbench.find_conflicts_in!(
-          collection_of_internal_arguments: collection_of_internal_arguments
+        inputs_workbench.find_unnecessary!
+        inputs_workbench.check_rules!
+        outputs_workbench.find_conflicts_in!(
+          collection_of_internals: collection_of_internals
         )
 
         prepare_data
 
-        input_arguments_workbench.check!
+        inputs_workbench.check!
 
-        make_methods_workbench.run!
+        methods_workbench.run!
 
         context_store.context.raise_first_fail
 
         Servactory::Result.prepare_for(
           context: context_store.context,
-          collection_of_output_arguments: collection_of_output_arguments
+          collection_of_outputs: collection_of_outputs
         )
       end
 
@@ -33,21 +33,21 @@ module Servactory
 
         assign_data_with(arguments)
 
-        input_arguments_workbench.find_unnecessary!
-        input_arguments_workbench.check_rules!
-        output_arguments_workbench.find_conflicts_in!(
-          collection_of_internal_arguments: collection_of_internal_arguments
+        inputs_workbench.find_unnecessary!
+        inputs_workbench.check_rules!
+        outputs_workbench.find_conflicts_in!(
+          collection_of_internals: collection_of_internals
         )
 
         prepare_data
 
-        input_arguments_workbench.check!
+        inputs_workbench.check!
 
-        make_methods_workbench.run!
+        methods_workbench.run!
 
         Servactory::Result.prepare_for(
           context: context_store.context,
-          collection_of_output_arguments: collection_of_output_arguments
+          collection_of_outputs: collection_of_outputs
         )
       end
 
@@ -56,21 +56,20 @@ module Servactory
       attr_reader :context_store
 
       def assign_data_with(arguments)
-        input_arguments_workbench.assign(
+        inputs_workbench.assign(
           context: context_store.context,
           arguments: arguments
         )
 
-        internal_arguments_workbench.assign(context: context_store.context)
-        output_arguments_workbench.assign(context: context_store.context)
-        make_methods_workbench.assign(context: context_store.context)
+        internals_workbench.assign(context: context_store.context)
+        outputs_workbench.assign(context: context_store.context)
+        methods_workbench.assign(context: context_store.context)
       end
 
       def prepare_data
-        input_arguments_workbench.prepare     # 1
-
-        output_arguments_workbench.prepare    # 2
-        internal_arguments_workbench.prepare  # 3
+        inputs_workbench.prepare      # 1
+        outputs_workbench.prepare     # 2
+        internals_workbench.prepare   # 3
       end
     end
   end

data/lib/servactory/context/workspace/inputs.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Context
+    module Workspace
+      class Inputs
+        def initialize(**)
+          # NOTE: Look at the file `lib/servactory/inputs/tools/prepare.rb`
+        end
+      end
+    end
+  end
+end

data/lib/servactory/context/workspace.rb

@@ -6,26 +6,28 @@ module Servactory
       attr_reader :inputs
 
       def errors
-        @errors ||= Errors.new
+        @errors ||= Servactory::Errors::Collection.new
       end
 
       def assign_inputs(inputs)
         @inputs = inputs
       end
 
-      def fail_input!(input_attribute_name, message)
-        raise Servactory.configuration.input_argument_error_class,
-              Error.new(type: :input, attribute_name: input_attribute_name, message: message).message
+      def fail_input!(input_name, message:)
+        raise Servactory.configuration.input_error_class.new(
+          input_name: input_name,
+          message: message
+        )
       end
 
-      def fail!(error)
-        errors << Error.new(type: :fail, message: error)
+      def fail!(message:, meta: nil)
+        errors << Servactory.configuration.failure_class.new(message: message, meta: meta)
       end
 
       def raise_first_fail
         return if (tmp_errors = errors.for_fails.not_blank).empty?
 
-        raise Servactory.configuration.failure_class, tmp_errors.first.message
+        raise tmp_errors.first
       end
     end
   end

data/lib/servactory/errors/base.rb

@@ -2,6 +2,7 @@
 
 module Servactory
   module Errors
-    class Base < StandardError; end
+    class Base < StandardError
+    end
   end
 end

data/lib/servactory/errors/collection.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Errors
+    class Collection
+      # NOTE: http://words.steveklabnik.com/beware-subclassing-ruby-core-classes
+      extend Forwardable
+      def_delegators :@collection, :<<, :to_a, :filter, :reject, :empty?, :first
+
+      def initialize(collection = Set.new)
+        @collection = collection
+      end
+
+      def not_blank
+        Collection.new(reject(&:blank?))
+      end
+
+      def for_fails
+        filtered = filter { |error| error.is_a?(Failure) }
+
+        Collection.new(filtered)
+      end
+    end
+  end
+end