azeroth 0.10.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcc284d1b166fec28f03e31cd42642ad09a86c85a81718ba401531443b1bbc08
-  data.tar.gz: 335851aa5d9a160cf387971e904248c2f89041594ccdaec57fa9ab130624558f
+  metadata.gz: 7c8e0229917b320108b25371d2c30ca48f83663288d50d2e767b8cf45c037c95
+  data.tar.gz: 2e6fe774d10fa5b5ca3f22c0b4deac4828a28480ebd3ebb1cce370c84c0f359c
 SHA512:
-  metadata.gz: 7ef7afcbd3282d181339fa6f154d1b4dcb6c6bad00f7c4e33e5c0b912b55eecc7de9876e44d2d54e7709a006a7cef487ee6c057dc0645bc0e336ff2b70629fdf
-  data.tar.gz: d37ba6ffdfe83b55fd51f103fd9ba3f35a3edf5eb0121c5aab424da29ffcce3e7850d52acdb4c41097c773d2f5b56692dc5f0e6c751ebce1651153bde42f2e1d
+  metadata.gz: b517e33573aa729a94fee810f0f4cea17a39533359332017e1dea8a3d80c74aacaac1010754739d8ba312d42353c57bb93d0c172aa640453450383ea1ff99328
+  data.tar.gz: 7bdfbfce3bdc6f40c2c82ea904a5778b5d0e7cc037f4fbf73f2e7d5fe8a449b7dacbac41f55523afea298bea5de998cc5d442e395fbf4949e555775aeabccff4

data/.circleci/config.yml

@@ -22,7 +22,7 @@ workflows:
 jobs:
   test:
     docker:
-      - image: darthjee/circleci_rails_gems:1.1.0
+      - image: darthjee/circleci_rails_gems:1.2.0
         environment:
           PROJECT: azeroth
     steps:
@@ -41,7 +41,7 @@ jobs:
           command: cc-test-reporter after-build --exit-code $?
   checks:
     docker:
-      - image: darthjee/circleci_rails_gems:1.1.0
+      - image: darthjee/circleci_rails_gems:1.2.0
         environment:
           PROJECT: azeroth
     steps:
@@ -66,7 +66,7 @@ jobs:
           command: check_specs
   build-and-release:
     docker:
-      - image: darthjee/circleci_rails_gems:1.1.0
+      - image: darthjee/circleci_rails_gems:1.2.0
         environment:
           PROJECT: azeroth
     steps:

data/Dockerfile

@@ -1,6 +1,6 @@
 FROM darthjee/scripts:0.3.1 as scripts
 
-FROM darthjee/rails_gems:1.1.0 as base
+FROM darthjee/rails_gems:1.2.0 as base
 
 COPY --chown=app:app ./ /home/app/app/
 

data/README.md

@@ -11,7 +11,7 @@ Azeroth
 
 Yard Documentation
 -------------------
-[https://www.rubydoc.info/gems/azeroth/0.10.1](https://www.rubydoc.info/gems/azeroth/0.10.1)
+[https://www.rubydoc.info/gems/azeroth/1.1.0](https://www.rubydoc.info/gems/azeroth/1.1.0)
 
 Azeroth has been designed making the coding of controllers easier
 as routes in controllers are usually copy, paste and replace of same
@@ -25,6 +25,10 @@ does not perform database operations
 Future versions will enable `html` rendering to also perform
 database operations.
 
+Current Release: [1.1.0](https://github.com/darthjee/azeroth/tree/1.1.0)
+
+[Next release](https://github.com/darthjee/azeroth/compare/1.1.0...master)
+
 Installation
 ---------------
 
@@ -131,12 +135,50 @@ It accepts options
   end
 ```
 
+```ruby
+  class PaginatedDocumentsController < ApplicationController
+    include Azeroth::Resourceable
+
+    resource_for :document, only: 'index', paginated: true
+  end
+
+  30.times { create(:document) }
+
+  get '/paginated_documents.json'
+
+  # returns Array with 20 first documents
+  # returns in the headers pagination headers
+  # {
+  #   'pages' => 2,
+  #   'per_page' => 20,
+  #   'page' => 1
+  # }
+
+  get '/paginated_documents.json?page=2'
+
+  # returns Array with 10 next documents
+  # returns in the headers pagination headers
+  # {
+  #   'pages' => 2,
+  #   'per_page' => 20,
+  #   'page' => 2
+  # }
+```
+
 ## Azeroth::Decorator
 
 [Decorators](https://www.rubydoc.info/gems/azeroth/Azeroth/Decorator) are
 used to define how an object is exposed as json on controller responses
 defining which and how fields will be exposed
 
+Exposing options:
+
+- as: custom key to expose the value as
+- if: method/block to be called checking if an attribute should or should not be exposed
+- decorator: flag to use or not a decorator or decorator class to be used
+- reader: Flag indicating if a reader to access the attribute should be created. usefull if you want method_missing to take over
+- override: Flag indicating if an existing method should be overriden. This is useful when a method acessor was included from another module
+
 ```ruby
   # pokemon/decorator.rb
 
@@ -172,35 +214,6 @@ defining which and how fields will be exposed
   end
 ```
 
-```ruby
-  class PaginatedDocumentsController < ApplicationController
-    include Azeroth::Resourceable
-
-    resource_for :document, only: 'index', paginated: true
-  end
-
-  30.times { create(:document) }
-
-  get '/paginated_documents.json'
-
-  # returns Array with 20 first documents
-  # returns in the headers pagination headers
-  {
-    'pages' => 2,
-    'per_page' => 20,
-    'page' => 1
-  }
-
-  get '/paginated_documents.json?page=2'
-
-  # returns Array with 10 next documents
-  # returns in the headers pagination headers
-  {
-    'pages' => 2,
-    'per_page' => 20,
-    'page' => 2
-  }
-```
 Exposing is done through the class method
 [expose](https://www.rubydoc.info/gems/azeroth/Azeroth/Decorator#expose-class_method)
 which accepts several options:

data/azeroth.gemspec

@@ -18,20 +18,20 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ['lib']
 
-  gem.add_runtime_dependency 'activesupport',       '~> 5.2.x'
+  gem.add_runtime_dependency 'activesupport',       '~> 7.0.x'
   gem.add_runtime_dependency 'darthjee-active_ext', '>= 1.3.2'
   gem.add_runtime_dependency 'jace',                '>= 0.1.1'
-  gem.add_runtime_dependency 'sinclair',            '>= 1.6.7'
+  gem.add_runtime_dependency 'sinclair',            '>= 2.0.0'
 
-  gem.add_development_dependency 'actionpack',                '5.2.8.1'
-  gem.add_development_dependency 'activerecord',              '5.2.8.1'
-  gem.add_development_dependency 'bundler',                   '~> 2.3.14'
+  gem.add_development_dependency 'actionpack',                '7.0.4.3'
+  gem.add_development_dependency 'activerecord',              '7.0.4.3'
+  gem.add_development_dependency 'bundler',                   '~> 2.4.8'
   gem.add_development_dependency 'factory_bot',               '6.2.1'
   gem.add_development_dependency 'minitest',                  '5.16.2'
-  gem.add_development_dependency 'nokogiri',                  '1.13.6'
+  gem.add_development_dependency 'nokogiri',                  '1.13.8'
   gem.add_development_dependency 'pry',                       '0.14.1'
   gem.add_development_dependency 'pry-nav',                   '1.0.0'
-  gem.add_development_dependency 'rails',                     '5.2.8.1'
+  gem.add_development_dependency 'rails',                     '7.0.4.3'
   gem.add_development_dependency 'rails-controller-testing',  '1.0.5'
   gem.add_development_dependency 'rake',                      '13.0.6'
   gem.add_development_dependency 'reek',                      '6.0.3'
@@ -47,6 +47,7 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rubycritic',                '4.7.0'
   gem.add_development_dependency 'shoulda-matchers',          '4.3.0'
   gem.add_development_dependency 'simplecov',                 '0.21.2'
+  gem.add_development_dependency 'sprockets-rails',           '3.4.2'
   gem.add_development_dependency 'sqlite3',                   '1.4.2'
   gem.add_development_dependency 'tzinfo-data',               '~> 1.2022.1'
   gem.add_development_dependency 'yard',                      '0.9.27'

data/config/check_specs.yml

@@ -1,4 +1,5 @@
 ignore:
+  - lib/azeroth/decorator/class_methods.rb
   - lib/azeroth/decorator/options.rb
   - lib/azeroth/resourceable/class_methods.rb
   - lib/azeroth/resourceable.rb

data/lib/azeroth/decorator/class_methods.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Azeroth
+  class Decorator
+    # @api private
+    # @author Darthjee
+    #
+    # Class methods added by {Decorator}
+    #
+    # @see ClassMethods#expose
+    module ClassMethods
+      # @api private
+      #
+      # All attributes exposed
+      #
+      # @return [Hash<Symbol,Hash>]
+      def attributes_map
+        @attributes_map ||= build_attributes_map
+      end
+
+      private
+
+      # @api private
+      # @private
+      #
+      # Initialize attributes to be exposed map
+      #
+      # When the class inherity from another
+      # decorator, the new class should expose the
+      # same attributes.
+      #
+      # @return [Hash<Symbol,Hash>]
+      def build_attributes_map
+        superclass.try(:attributes_map).dup || {}
+      end
+
+      # @visibility public
+      # @api (see Decorator.expose)
+      # @private
+      #
+      # Expose attributes on json decorated
+      #
+      # @param (see Decorator.expose)
+      # @option (see Decorator.expose)
+      #
+      # @return (see Decorator.expose)
+      #
+      # @example Simple usage
+      #   class DummyModel
+      #     include ActiveModel::Model
+      #
+      #     attr_accessor :id, :first_name, :last_name, :age,
+      #                   :favorite_pokemon
+      #
+      #     class Decorator < Azeroth::Decorator
+      #       expose :name
+      #       expose :age
+      #       expose :favorite_pokemon, as: :pokemon
+      #
+      #       def name
+      #         [object.first_name, object.last_name].join(' ')
+      #       end
+      #     end
+      #   end
+      #
+      # @example With relations
+      #   # pokemon/decorator.rb
+      #
+      #   class Pokemon::Decorator < Azeroth::Decorator
+      #     expose :name
+      #     expose :previous_form_name, as: :evolution_of, if: :evolution?
+      #
+      #     def evolution?
+      #       previous_form
+      #     end
+      #
+      #     def previous_form_name
+      #       previous_form.name
+      #     end
+      #   end
+      #
+      #   # pokemon/favorite_decorator.rb
+      #
+      #   class Pokemon::FavoriteDecorator < Pokemon::Decorator
+      #     expose :nickname
+      #   end
+      #
+      #   # pokemon_master/decorator.rb
+      #
+      #   class PokemonMaster < ActiveRecord::Base
+      #     has_one :favorite_pokemon, -> { where(favorite: true) },
+      #             class_name: 'Pokemon'
+      #     has_many :pokemons
+      #   end
+      #
+      #   # pokemon.rb
+      #
+      #   class Pokemon < ActiveRecord::Base
+      #     belongs_to :pokemon_master
+      #     has_one :previous_form,
+      #             class_name: 'Pokemon',
+      #             foreign_key: :previous_form_id
+      #   end
+      #
+      #   # pokemon_master.rb
+      #
+      #   class PokemonMaster::Decorator < Azeroth::Decorator
+      #     expose :name
+      #     expose :age
+      #     expose :favorite_pokemon, decorator: Pokemon::FavoriteDecorator
+      #     expose :pokemons
+      #
+      #     def name
+      #       [
+      #         first_name,
+      #         last_name
+      #       ].compact.join(' ')
+      #     end
+      #   end
+      #
+      #   # schema.rb
+      #
+      #   ActiveRecord::Schema.define do
+      #     self.verbose = false
+      #
+      #      create_table :pokemon_masters, force: true do |t|
+      #       t.string :first_name, null: false
+      #       t.string :last_name
+      #       t.integer :age, null: false
+      #     end
+      #
+      #     create_table :pokemons, force: true do |t|
+      #       t.string :name, null: false
+      #       t.string :nickname
+      #       t.integer :pokemon_master_id
+      #       t.boolean :favorite
+      #       t.integer :previous_form_id
+      #       t.index %i[pokemon_master_id favorite], unique: true
+      #     end
+      #
+      #     add_foreign_key 'pokemons', 'pokemon_masters'
+      #   end
+      #
+      #   # test.rb
+      #
+      #   master = PokemonMaster.create(
+      #     first_name: 'Ash',
+      #     last_name: 'Ketchum',
+      #     age: 10
+      #   )
+      #
+      #   master.create_favorite_pokemon(
+      #     name: 'pikachu',
+      #     nickname: 'Pikachu'
+      #   )
+      #
+      #   metapod = Pokemon.create(name: :metapod)
+      #
+      #   master.pokemons.create(
+      #     name: 'butterfree', previous_form: metapod
+      #   )
+      #   master.pokemons.create(name: 'squirtle')
+      #
+      #   decorator = PokemonMaster::Decorator.new(master)
+      #
+      #   decorator.as_json
+      #   # returns
+      #   # {
+      #   #   'age' => 10,
+      #   #   'name' => 'Ash Ketchum',
+      #   #   'favorite_pokemon' => {
+      #   #     'name' => 'pikachu',
+      #   #     'nickname' => 'Pikachu'
+      #   #   },
+      #   #   'pokemons' => [{
+      #   #     'name' => 'butterfree',
+      #   #     'evolution_of' => 'metapod'
+      #   #   }, {
+      #   #     'name' => 'squirtle'
+      #   #   }, {
+      #   #     'name' => 'pikachu'
+      #   #   }]
+      #   # }
+      #
+      # @example With method building options
+      #   ActiveRecord::Schema.define do
+      #     self.verbose = false
+      #
+      #     create_table :websites, force: true do |t|
+      #       t.string :domain, null: false
+      #       t.integer :port, limit: 2, unsigned: true
+      #       t.string :protocol, limit: 5
+      #     end
+      #   end
+      #
+      #   class Website < ActiveRecord::Base
+      #   end
+      #
+      #   class Website < ActiveRecord::Base
+      #     module WithLocation
+      #       def location
+      #         "#{protocol}://#{domain}:#{port}"
+      #       end
+      #
+      #       def protocol
+      #         website.protocol || '*'
+      #       end
+      #
+      #       def domain
+      #         website.domain || '*'
+      #       end
+      #
+      #       def port
+      #         website.port || '*'
+      #       end
+      #     end
+      #   end
+      #
+      #   class Website < ActiveRecord::Base
+      #     class Decorator < Azeroth::Decorator
+      #       include WithLocation
+      #
+      #       expose :location, override: false
+      #
+      #       alias website object
+      #     end
+      #   end
+      #
+      #   website = Website.create(
+      #     protocol: :http,
+      #     domain: 'google.com'
+      #   )
+      #
+      #   decorator = Website::Decorator.new(website)
+      #
+      #   decorator.as_json
+      #
+      #   # returns
+      #   # { 'location' => 'http://google.com:*' }
+      def expose(attribute, **options_hash)
+        options = Decorator::Options.new(options_hash)
+
+        MethodBuilder.build_reader(self, attribute, options)
+
+        attributes_map[attribute] = options
+      end
+    end
+  end
+end

data/lib/azeroth/decorator/hash_builder.rb

@@ -25,7 +25,9 @@ module Azeroth
       # @return [Hash]
       def as_json
         attributes_map.inject({}) do |hash, (method, options)|
-          new_hash = KeyValueExtractor.new(decorator, method, options).as_json
+          new_hash = KeyValueExtractor.new(
+            decorator: decorator, attribute: method, options: options
+          ).as_json
           hash.merge!(new_hash)
         end
       end

data/lib/azeroth/decorator/key_value_extractor.rb

@@ -11,18 +11,14 @@ module Azeroth
     #
     # A decorator is infered for the value / attribute
     # or used from the options given
-    class KeyValueExtractor
+    class KeyValueExtractor < Sinclair::Model
+      initialize_with(:decorator, :attribute, :options)
       # @param decorator [Decorator] decorator object
       # @param attribute [Symbol] attribute to be used on output hash
       # @param options [Decorator::Options] decoration options
       # @option options if [Proc,Symbol] conditional to be
       #   checked when exposing field
       #   (see {Decorator::Options#if})
-      def initialize(decorator, attribute, options)
-        @decorator = decorator
-        @attribute = attribute
-        @options = options
-      end
 
       # Return hash for attribute
       #
@@ -38,9 +34,8 @@ module Azeroth
         }
       end
 
-      # private
+      private
 
-      attr_reader :decorator, :attribute, :options
       # @method decorator
       # @api private
       # @private

data/lib/azeroth/decorator/method_builder.rb

@@ -7,20 +7,36 @@ module Azeroth
     # Responsible for building readers for attributes
     # @api private
     class MethodBuilder < Sinclair
-      # Builds reader
-      #
-      # reaader delegate method calls to @object
-      #
-      # @return [Array<Sinclair::MethodDefinition>]
-      def self.build_reader(klass, attribute)
-        new(klass).build_reader(attribute)
+      class << self
+        # Builds reader
+        #
+        # reaader delegate method calls to @object
+        #
+        # @return [Array<Sinclair::MethodDefinition>]
+        def build_reader(klass, attribute, options)
+          new(klass, options).build_reader(attribute)
+        end
+      end
+
+      def initialize(klass, options)
+        super(klass)
+        @options = options
       end
 
       # (see MethodBuilder.build_reader)
       def build_reader(attribute)
+        return if skip_creation?(attribute)
+
         add_method(attribute, "@object.#{attribute}")
         build
       end
+
+      def skip_creation?(attribute)
+        return true unless options.reader
+        return false unless klass.method_defined?(attribute)
+
+        !options.override
+      end
     end
   end
 end

data/lib/azeroth/decorator/options.rb

@@ -13,7 +13,9 @@ module Azeroth
       DEFAULT_OPTIONS = {
         as: nil,
         if: nil,
-        decorator: true
+        decorator: true,
+        override: true,
+        reader: true
       }.freeze
 
       with_options DEFAULT_OPTIONS