haku 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b807f104854f0cd9619b5a3a5be55a5e9744e7eaef85ace5f775772395d9957b
-  data.tar.gz: fb389738d56e37d6f397ee32316c7ad249ef95ad1d39f790c083742a0e6fad83
+  metadata.gz: d706591454ee0f992403b400e7dc75e621bccb120978050d98f55f2aaceca5bd
+  data.tar.gz: 18652ffbeff0a83d8a7344d7de7e7f4bb905d973a740fecc99a14a05d1258d46
 SHA512:
-  metadata.gz: baa9206fa09e7aec2212a226fc66a0dd4a4fcb88ca437c95032c1e7f9fb244fda6e2fa9b7869d38c736a3c88970fa808bc12234f72d93d0d3ba741f3107a68e1
-  data.tar.gz: 3fbcf48768c7125fb1e60c1b1b022cef94b34e6cfc1236ada836d559d2e4595776a12a441f6af2fe0fc7cd948675b43681479edeb66836bf436b3ea12e7e7294
+  metadata.gz: f4ad33422d9efcba85416ee72099e1c577b1172f6e4a40bea8c9d28cfd4edb8f3259eb5f04671a54ca67dcab0cc796bb407f39111d5ecb9fd30cc6d2d6bf235a
+  data.tar.gz: ee0e64b2f70d88f833cedbf96b56af02a9ffaaa17e29df5d582ae6b71a6199935e6897b8bbc704f4d2c035215be45b9767e5814275da002aa8836e627f5c5db8

data/.rubocop.yml

@@ -12,6 +12,8 @@ AllCops:
   DisplayCopNames: true
   Exclude:
     - "**/bin/**/*"
+    - "**/gemfiles/**/*"
+    - "**/Appraisals"
   NewCops: enable
   TargetRubyVersion: 2.6
 

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.1.1

data/Appraisals

@@ -0,0 +1,11 @@
+appraise "activesupport-6.0" do
+  gem "activesupport", "6.0"
+end
+
+appraise "activesupport-6.1" do
+  gem "activesupport", "6.1"
+end
+
+appraise "activesupport-7.0" do
+  gem "activesupport", "7.0"
+end

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
-## [0.1.0] - 2022-04-05
+## [1.1.0] - 2022-04-19
+- Allow to configure Haku using block
+- Add Eventable module to fire events
+- Add persist_resource to Resourceable
+- Allow to declare inputs instead of create automatically
+- Avoid using run to execute code. Using call is better
+- Improve README
+- Use Appraisal to test against multiple versions of some gems
 
+## [1.0.0] - 2022-04-11
 - Initial release

data/Gemfile

@@ -2,10 +2,9 @@
 
 source "https://rubygems.org"
 
-ruby "3.1.1"
-
 gemspec
 
+gem "appraisal", github: "excid3/appraisal", branch: "fix-bundle-env"
 gem "minitest", "~> 5.0"
 gem "pry", "~> 0.14"
 gem "rake", "~> 13.0"

data/Gemfile.lock

@@ -1,7 +1,17 @@
+GIT
+  remote: https://github.com/excid3/appraisal.git
+  revision: 14855fc54ce88b42def871ce8bfd4259fbf06043
+  branch: fix-bundle-env
+  specs:
+    appraisal (2.4.1)
+      bundler
+      rake
+      thor (>= 0.14.0)
+
 PATH
   remote: .
   specs:
-    haku (0.1.0)
+    haku (1.1.0)
       activesupport (>= 6.0, < 8.0)
 
 GEM
@@ -14,7 +24,7 @@ GEM
       tzinfo (~> 2.0)
     ast (2.4.2)
     coderay (1.1.3)
-    concurrent-ruby (1.1.9)
+    concurrent-ruby (1.1.10)
     i18n (1.10.0)
       concurrent-ruby (~> 1.0)
     method_source (1.0.0)
@@ -45,6 +55,7 @@ GEM
     rubocop-rake (0.6.0)
       rubocop (~> 1.0)
     ruby-progressbar (1.11.0)
+    thor (1.2.1)
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.1.0)
@@ -54,6 +65,7 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  appraisal!
   haku!
   minitest (~> 5.0)
   pry (~> 0.14)
@@ -62,8 +74,5 @@ DEPENDENCIES
   rubocop-minitest (~> 0.19)
   rubocop-rake (~> 0.6)
 
-RUBY VERSION
-   ruby 3.1.1p18
-
 BUNDLED WITH
    2.3.7

data/README.md

@@ -2,7 +2,7 @@
 
 ![CI](https://github.com/javierav/haku/workflows/CI/badge.svg)
 
-TODO: Write a better gem description.
+A library for build simple service objects.
 
 ## Installation
 
@@ -14,11 +14,200 @@ gem 'haku'
 
 And then execute:
 
-    $ bundle install
+```shell
+bundle install
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Basic example
+
+````ruby
+class Users::Update
+  include Haku::Core
+
+  input :user, :attributes
+  on_success :send_email
+
+  def call
+    if user.update(attributes)
+      success! resource: user
+    else
+      failure! resource: user, errors: user.errors
+    end
+  end
+
+  private
+
+  def send_email
+    UserMailer.with(user: user).update.deliver_later
+  end
+end
+
+response = Users::Update.call(user: User.first, attributes: { name: "Javier" })
+
+response.success? # => true
+response.resource # => <User id="1" ...>
+````
+
+### Using resourceable helpers
+
+````ruby
+class Users::Update
+  include Haku::Core
+  include Haku::Resourceable
+
+  input :user, :attributes
+  on_success :send_email
+
+  def call
+    update_resource(user, attributes)
+  end
+
+  private
+
+  def send_email
+    UserMailer.with(user: user).update.deliver_later
+  end
+end
+````
+
+### Controller helpers
+
+```ruby
+class UsersController < ApplicationController
+  before_action :find_user
+
+  def update
+    execute Users::Update, user: @user, attributes: update_params
+
+    if execution.success?
+      redirect_to user_path(execution.resource)
+    else
+      render :edit, errors: execution.errors
+    end
+  end
+
+  private
+
+  def find_user
+    @user = User.find(params[:id])
+  end
+
+  def update_params
+    params.require(:user).permit(:first_name, :last_name)
+  end
+end
+```
+
+### Using eventable
+
+````ruby
+class Users::Update
+  include Haku::Core
+  include Haku::Resourceable
+  include Haku::Eventable
+
+  input :user, :attributes
+  event resource: :user
+
+  def call
+    update_resource(user, attributes)
+  end
+end
+
+Users::Update.call(user: User.first, attributes: { name: "Javier" })
+
+# => call Event.create(name: "user:update", resource: User.first)
+````
+
+### Using parent class
+
+```ruby
+class ApplicationAction
+  include Haku::Core
+  include Haku::Resourceable
+  include Haku::Eventable
+end
+
+class Users::Update < ApplicationAction
+end
+```
+
+## Configure
+
+### Example
+
+```ruby
+# config/initializers/haku.rb
+
+Haku.configure do |config|
+  config.event_model = "EventLog"
+end
+```
+
+### Allowed options
+
+| Config                             | Description                                            | Default value                                            |
+|:-----------------------------------|:-------------------------------------------------------|:---------------------------------------------------------|
+| `enable_in_action_controller_base` | Include controller helpers in `ActionController::Base` | `true`                                                     |
+| `enable_in_action_controller_api`  | Include controller helpers in `ActionController::API`  | `true`                                                     |
+| `event_model`                      | Name of the model used for create events               | `Event`                                                  |
+| `event_properties`                 | List of attributes passed from service to event model  | `%i[actor resource target context]`                      |
+| `event_property_for_name`          | Property used for name in event model                  | `:name`                                                  |
+| `event_name`                       | String or Proc to determine the event name             | Custom Proc. Example: `user:created` for `Users::Create` |
+
+
+## Resourceable
+
+This module include helpers to works with *ActiveRecord* compatible model resources, invoking `success!` or `failure!`
+based in the result of the performed operation.
+
+### create_resource
+
+Call to `create` or `<singleton>_create` method of the `parent` object passing the `attributes` and storing
+the result object in the `ivar` instance variable. Invoke `success!` if the model is persisted or `failure!` in other
+case.
+
+| parameter    | type     | description                                                      |
+|--------------|----------|------------------------------------------------------------------|
+| `parent`     | `Object` | Parent object where new resource will be created                 |
+| `attributes` | `Hash`   | Attributes for create                                            |
+| `ivar`       | `Symbol` | Name of the instance variable used to access to the new resource |
+| `options`    | `Hash`   | Options hash                                                     |
+
+#### options
+
+| parameter   | type     | description                                                          |
+|-------------|----------|----------------------------------------------------------------------|
+| `singleton` | `Symbol` | If the resource should be created using `<singleton>_create` suffix. |
+
+### update_resource
+
+Call to `update` method of the `resource` object passing `attributes`to it. Invoke `success!` if the model is updated or
+`failure!` in other case.
+
+| parameter    | type     | description            |
+|--------------|----------|------------------------|
+| `resource`   | `Object` | Resource to be updated |
+| `attributes` | `Hash`   | Attributes to update   |
+
+### destroy_resource
+
+Call to `destroy` method of the `resource`. Invoke `success!` if the model is destroyed or `failure!` in other case.
+
+| parameter    | type     | description              |
+|--------------|----------|--------------------------|
+| `resource`   | `Object` | Resource to be destroyed |
+
+### persist_resource
+
+| parameter      | type     | description                                 |
+|----------------|----------|---------------------------------------------|
+| `resource`     | `Object` | Resource to be destroyed                    |
+| `save_options` | `Hash`   | Options passed to `save` method of resource |
+
+For more info please view the [source code](lib/haku/resourceable.rb) of the module.
 
 ## Development
 
@@ -26,15 +215,15 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
+
 To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`,
 which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/javierav/haku. This project is intended to be
-a safe, welcoming space for collaboration, and contributors are expected to adhere to the
-[code of conduct](https://github.com/javierav/haku/blob/development/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome, please follow
+[Github Flow](https://docs.github.com/en/get-started/quickstart/github-flow).
 
 ## Code of Conduct
 
@@ -43,4 +232,4 @@ follow the [code of conduct](https://github.com/javierav/haku/blob/development/C
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Copyright © 2022 Javier Aranda. Released under the terms of the [MIT license](LICENSE).

data/gemfiles/activesupport_6.0.gemfile

@@ -0,0 +1,14 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal", "~> 2.4"
+gem "minitest", "~> 5.0"
+gem "pry", "~> 0.14"
+gem "rake", "~> 13.0"
+gem "rubocop", "~> 1.21"
+gem "rubocop-minitest", "~> 0.19"
+gem "rubocop-rake", "~> 0.6"
+gem "activesupport", "6.0"
+
+gemspec path: "../"

data/gemfiles/activesupport_6.1.gemfile

@@ -0,0 +1,14 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal", "~> 2.4"
+gem "minitest", "~> 5.0"
+gem "pry", "~> 0.14"
+gem "rake", "~> 13.0"
+gem "rubocop", "~> 1.21"
+gem "rubocop-minitest", "~> 0.19"
+gem "rubocop-rake", "~> 0.6"
+gem "activesupport", "6.1"
+
+gemspec path: "../"

data/gemfiles/activesupport_7.0.gemfile

@@ -0,0 +1,14 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal", "~> 2.4"
+gem "minitest", "~> 5.0"
+gem "pry", "~> 0.14"
+gem "rake", "~> 13.0"
+gem "rubocop", "~> 1.21"
+gem "rubocop-minitest", "~> 0.19"
+gem "rubocop-rake", "~> 0.6"
+gem "activesupport", "7.0"
+
+gemspec path: "../"

data/lib/haku/core.rb

@@ -9,15 +9,30 @@ module Haku
     extend ActiveSupport::Concern
 
     included do
+      prepend Callable
+
       attr_reader :params
 
+      class_attribute :haku_inputs, default: []
       class_attribute :haku_success_callbacks, default: []
       class_attribute :haku_failure_callbacks, default: []
     end
 
     module ClassMethods
+      def inherited(base)
+        super
+
+        base.class_eval do
+          prepend Callable
+        end
+      end
+
       def call(params={})
-        new(params).run
+        new(params).call
+      end
+
+      def input(*names)
+        self.haku_inputs += names
       end
 
       def on_success(*methods)
@@ -29,19 +44,24 @@ module Haku
       end
     end
 
-    def initialize(params={})
-      @params = params
+    module Callable
+      def call
+        result = super
 
-      @params.each_key do |key|
-        define_singleton_method(key) { @params[key] } unless respond_to?(key)
+        Result.new(_haku_status, _haku_response.merge(result: result)).tap do
+          _haku_run_callbacks
+        end
       end
     end
 
-    def run
-      result = call
+    def initialize(params={})
+      @params = params
+
+      @_haku_status = :success
+      @_haku_response = {}
 
-      Result.new(_haku_status, _haku_response.merge(result: result)).tap do
-        _haku_run_callbacks
+      self.class.haku_inputs.each do |name|
+        define_singleton_method(name) { @params[name] } unless respond_to?(name)
       end
     end
 
@@ -64,11 +84,11 @@ module Haku
     end
 
     def _haku_status
-      @_haku_status || :success
+      @_haku_status
     end
 
     def _haku_response
-      @_haku_response || {}
+      @_haku_response
     end
 
     def _haku_run_callbacks

data/lib/haku/eventable.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+module Haku
+  module Eventable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :haku_success_events, default: []
+      class_attribute :haku_failure_events, default: []
+
+      on_success :haku_process_events_for_success
+      on_failure :haku_process_events_for_failure
+    end
+
+    module ClassMethods
+      def event(options={})
+        on = options.delete(:on)&.to_sym || :success
+
+        send("haku_#{on}_events=", send("haku_#{on}_events") + [options])
+      end
+    end
+
+    def haku_process_events_for_success
+      haku_process_events(:success)
+    end
+
+    def haku_process_events_for_failure
+      haku_process_events(:failure)
+    end
+
+    def haku_process_events(on)
+      send("haku_#{on}_events").each do |evt|
+        haku_create_event(haku_prepare_event_data(evt))
+      end
+    end
+
+    def haku_prepare_event_data(evt, data={})
+      data.tap do
+        haku_event_data_base(data)
+        haku_event_data_name(data, evt)
+        haku_event_data_values(data, evt)
+      end
+    end
+
+    def haku_event_data_base(data)
+      Haku.event_properties.each do |property|
+        data[property] = send(property) if respond_to?(property)
+      end
+    end
+
+    def haku_process_value(value)
+      if value.respond_to?(:call)
+        instance_exec(&value)
+      else
+        value.is_a?(Symbol) ? send(value) : value
+      end
+    end
+
+    def haku_event_data_name(data, evt)
+      key = Haku.event_property_for_name.to_sym
+      data[key] = evt[key] || haku_process_value(Haku.event_name)
+    end
+
+    def haku_event_data_values(data, evt)
+      evt.except(Haku.event_property_for_name.to_sym).each_pair do |key, value|
+        data[key] = haku_process_value(value)
+      end
+    end
+
+    def haku_create_event(data)
+      Haku.event_model.safe_constantize&.create(data)
+    end
+  end
+end

data/lib/haku/resourceable.rb

@@ -36,5 +36,18 @@ module Haku
         end
       end
     end
+
+    def persist_resource(resource, **save_options)
+      resource.tap do
+        if resource.save(save_options)
+          yield resource if block_given?
+          success! resource: resource
+        else
+          failure! resource: resource, errors: resource.errors
+        end
+      end
+    end
+
+    alias save_resource persist_resource
   end
 end

data/lib/haku/version.rb

@@ -3,7 +3,7 @@
 module Haku
   module VERSION
     MAJOR = 1
-    MINOR = 0
+    MINOR = 1
     TINY  = 0
     PRE   = nil
 

data/lib/haku.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/module/attribute_accessors"
+require "active_support/core_ext/string/inflections"
 require_relative "haku/core"
+require_relative "haku/eventable"
 require_relative "haku/railtie" if defined?(Rails)
 require_relative "haku/resourceable"
 require_relative "haku/version"
@@ -9,4 +11,17 @@ require_relative "haku/version"
 module Haku
   mattr_accessor :enable_in_action_controller_base, default: true
   mattr_accessor :enable_in_action_controller_api, default: true
+  mattr_accessor :event_model, default: "Event"
+  mattr_accessor :event_properties, default: %i[actor resource target context]
+  mattr_accessor :event_property_for_name, default: :name
+  mattr_accessor :event_name, default: proc {
+    chain = self.class.name.underscore.split("/")
+    (chain[0...-1].map(&:singularize) + [chain.last]).join(":")
+  }
+
+  class << self
+    def configure
+      yield self
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: haku
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Javier Aranda
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-04-11 00:00:00.000000000 Z
+date: 2022-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -36,23 +36,29 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files:
-- LICENSE.txt
+- LICENSE
 - README.md
 files:
 - ".editorconfig"
 - ".envrc"
 - ".pryrc"
 - ".rubocop.yml"
+- ".tool-versions"
+- Appraisals
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
-- LICENSE.txt
+- LICENSE
 - README.md
 - Rakefile
+- gemfiles/activesupport_6.0.gemfile
+- gemfiles/activesupport_6.1.gemfile
+- gemfiles/activesupport_7.0.gemfile
 - lib/haku.rb
 - lib/haku/controller.rb
 - lib/haku/core.rb
+- lib/haku/eventable.rb
 - lib/haku/railtie.rb
 - lib/haku/resourceable.rb
 - lib/haku/result.rb
@@ -62,8 +68,8 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/javierav/haku
-  source_code_uri: https://github.com/javierav/haku/tree/v1.0.0
-  changelog_uri: https://github.com/javierav/haku/blob/v1.0.0/CHANGELOG.md
+  source_code_uri: https://github.com/javierav/haku/tree/v1.1.0
+  changelog_uri: https://github.com/javierav/haku/blob/v1.1.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: