active_mappers 1.2.4 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 492d45c2bd3a72e786b65fa4305dfec8c2847208e4f92b8c1ed790414b4b45fa
-  data.tar.gz: 2db83741a820fc9a797228e2f026d191df807e7c7f0006211e46ec5ede34e63b
+  metadata.gz: 2ec2a77d6b91e05de5d86ab9a43b37d5fd7245085d696ccd9c7fb5aa900a42a3
+  data.tar.gz: b930be8ee3ac6adf404cfe9c0bad1107b9eb3287912c347b940438f2bab95af4
 SHA512:
-  metadata.gz: 0d4b8f0683eb36a445903f1752be3041661f93ec0a6b9fd2a755794f10208a127d9dd94e68c1dc718bc1fa9b97cf422efb910e333e9aec4ded1482a9075659b8
-  data.tar.gz: 38a26b2aea1672f3a4f95740a31397fe3e49123e2f189b9fb596dde97dfcd1ab9ade069bb5d1d0cc8b12c55f97bd772cd97c798f358b23a3488f2f12027c85e2
+  metadata.gz: 9d29e59cc9231aab42657fbc2eb8c8e8106ed3a5e61752763efa3454de2775f4a7189886ebf46f626ea7b74b6d70c93bb3cf6c930dc23a77b7ffdb10cdfeaa8b
+  data.tar.gz: 774c84aea5e4b793ea0ce59ea8160ad2b626fe1d3d53392bc7d4909eff89c9629b7e69c1859ae8b6dc1198407f671554250430d26333d1ee8fbe26c4b657afe0

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.3.0
+  - 2.4.0
+  - 2.5.0
+
+script: echo "Running tests against $(ruby -v) ..."

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem 'rake'
+gemspec

data/Gemfile.lock

@@ -0,0 +1,46 @@
+PATH
+  remote: .
+  specs:
+    active_mappers (1.3.0)
+      activesupport (>= 4.2)
+      method_source (~> 0.9.2)
+      mocha (>= 1.8.0)
+      ruby2ruby (> 2.4.0)
+      ruby_parser (~> 3.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (5.2.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    concurrent-ruby (1.1.5)
+    i18n (1.6.0)
+      concurrent-ruby (~> 1.0)
+    metaclass (0.0.4)
+    method_source (0.9.2)
+    minitest (5.11.3)
+    mocha (1.8.0)
+      metaclass (~> 0.0.1)
+    rake (12.3.1)
+    ruby2ruby (2.4.2)
+      ruby_parser (~> 3.1)
+      sexp_processor (~> 4.6)
+    ruby_parser (3.13.0)
+      sexp_processor (~> 4.9)
+    sexp_processor (4.12.0)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  active_mappers!
+  rake
+
+BUNDLED WITH
+   1.17.2

data/README.md

@@ -0,0 +1,431 @@
+# ActiveMappers
+
+[![Build Status](https://travis-ci.org/FidMe/active_mappers.svg?branch=master)](https://travis-ci.org/FidMe/active_mappers)
+[![Gem Version](https://badge.fury.io/rb/active_mappers.svg)](https://badge.fury.io/rb/active_mappers)
+
+If you have ever done Rails API development, you must have considered using a layer to abstract and centralize your JSON objects construction.
+
+There are multiple solutions out on the market, here is a quick overview of each :
+
+| Solution                 | Pros                                                                               | Cons                                                  |
+| ------------------------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| JBuilder                 | Simple, easy, integrates with the default View layer                               | Very slow, dedicated to JSON                          |
+| Active Model Serializers | Simple, easy to declare                                                            | Can be hard to customize, slow, project is abandonned |
+| fast_json_api            | As simple as AMS, fast                                                             | Hard to customize, JSONAPI standard is required       |
+| ActiveMappers            | Blazing fast, Easy to declare/customize, works with any format output (JSON, Hash) | Limited number of options (for now)                   |
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_mappers'
+```
+
+Execute
+
+```bash
+$ bundle install
+```
+
+Then, depending on your usage you may want to create an `app/mappers` folder in your Rails application.
+
+You will put all your mappers inside of it.
+
+## Usage
+
+```ruby
+UserMapper.with(user)
+# =>
+# {
+#   user: {
+#     id: '123',
+#     email: 'mvilleneuve@snapp.fr',
+#     profile: {
+#       first_name: 'Michael',
+#       last_name: 'Villeneuve',
+#     }
+#   }
+# }
+```
+
+### Setup (optional)
+
+You may want to customize some parts of ActiveMappers behavior.
+
+If you want to, create an initializer in your project :
+
+```ruby
+# config/initializers/active_mappers.rb
+ActiveMappers::Setup.configure do |config|
+  config.camelcase_keys = false
+  config.ignored_namespaces = [:admin, :back_office]
+end
+```
+
+Here is the list of configurable options
+
+| Option                  | Type      | Default   | Description                                                        |
+| ----------------------- | --------- | --------- | ------------------------------------------------------------------ |
+| `camelcase_keys`        | `boolean` | `true`    | Should keys name be camelcase. Fallback to snake when set to false |
+| `ignored_namespaces`    | `Array`   | `[]`      | Namespaces to ignore when generating json root key name            |
+| `root_keys_transformer` | `Proc`    | See below | Custom way to change a mapper class name into a JSON root key      |
+
+**Root Keys Transformer**
+
+A root key transform is used to transform the mapper class name into a JSON root key name.
+
+For example this mapper class :
+
+```ruby
+class User::ProfileInformationMapper < ActiveMappers::Base
+end
+```
+
+Will automatically resolve to the following json :
+
+```json
+{
+  "user/profileInformation": {}
+}
+```
+
+To customize this behavior you can do the following :
+
+```ruby
+config.root_keys_transformer = proc do |key|
+  # Return any key transform based on the key which is the class name of your mapper
+
+  # The below line transforms User::ProfileInformationMapper to user/profile_informations
+  key.gsub('Mapper', '').tableize
+end
+```
+
+### Creating a mapper
+
+**Declaring your attributes**
+
+Most basic usage, just declare the attributes you want to display.
+
+```ruby
+class UserMapper < ActiveMappers::Base # You must extend ActiveMappers::Base in order to use the DSL
+  attributes :id, :email
+end
+```
+
+**Delegating your attributes**
+
+Say you have a model with the following structure :
+
+```ruby
+{
+  email: 'mvilleneuve@snapp.fr',
+  profile: {
+    first_name: 'Michael',
+  }
+}
+```
+
+And you want to generate this structure :
+
+```ruby
+{
+  email: 'mvilleneuve@snapp.fr',
+  first_name: 'Michael',
+  last_name: 'Villeneuve',
+}
+```
+
+To implement this, you must use the `delegate` feature :
+
+```ruby
+class UserMapper < ActiveMappers::Base
+  delegate :first_name, :last_name, to: :profile
+end
+```
+
+**Declaring relationship**
+
+You can declare any type of relationship (`has_one`, `belongs_to`, `has_many`, etc) and the mapper that matches it will automatically be fetched and used.
+
+For example if a `User` has a `belongs_to` relationship with an `Account` you can write :
+
+```ruby
+class UserMapper < ActiveMappers::Base
+  attributes :email
+  relation :account # Will automatically resolve to AccountMapper
+end
+
+class AccountMapper < ActiveMappers::Base
+  attributes :first_name, :last_name
+end
+```
+
+It will generate something like
+
+```ruby
+{
+  user: {
+    email: 'mvilleneuve@snapp.fr',
+    account: {
+      first_name: 'Michael',
+      last_name: 'Villeneuve'
+    }
+  }
+}
+```
+
+It also works with namespaced resources.
+
+If you need you can specify more options :
+
+```ruby
+class UserMapper < ActiveMappers::Base
+  relation :account, AccountMapper, scope: :admin 
+end
+
+
+
+**Declaring polymorphic relationships**
+
+Consider the following polymorphic relation :
+
+```ruby
+class Post
+  belongs_to :author, polymorphic: true
+end
+
+class AdminUser
+  has_many :posts, class_name: 'Post', as: :author
+end
+
+class NormalUser
+  has_many :posts, class_name: 'Post', as: :author
+end
+```
+
+In order to use the `author` polymorphic attribute in your `PostMapper` you need to declare the following :
+
+```ruby
+class PostMapper < ActiveMappers::Base
+  polymorphic :author
+end
+```
+
+And of course, you must implement the associated mappers :
+
+```ruby
+class AdminUserMapper
+  attributes :id, :name
+end
+
+class NormalUserMapper
+  attributes :id, :name
+end
+```
+
+Then, based of the `XXX_type` column, the mapper will automatically resolve to either `AdminUserMapper` or `NormalUserMapper`
+
+**Rendering a collection of different classes**
+
+Say you want to render many resources with a single Mapper
+
+```ruby
+collection = Bird.all + Fish.all + Insect.all
+
+render json: AnimalMapper.with(collection)
+
+class AnimalMapper < ActiveMappers::Base
+  acts_as_polymorphic
+end
+
+class BirdMapper < ActiveMappers::Base
+  attributes :name, :wings_count
+end
+
+class FishMapper < ActiveMappers::Base
+  attributes :name, :fins_count
+end
+
+class InsectMapper < ActiveMappers::Base
+  attributes :name, :has_venom
+end
+```
+
+Will generate the following :
+
+```ruby
+{
+  animals: [
+    { name: 'Michael', wings_count: 2 },
+    { name: 'Emeric', fins_count: 1 },
+    { name: 'Arthur', has_venom: true },
+  ]
+}
+```
+
+Again, just like the above polymorphic declaration, the mapper will automatically resolve to the corresponding one.
+
+**Custom Attributes**
+
+If you need to implement custom attributes you can always use the `each` statement.
+
+```ruby
+class UserMapper < ActiveMappers::Base
+  attributes :email, :id
+
+  each do |user|
+    {
+      custom_attribute: "Hi, I'm a custom attribute",
+      another_custom_attribute: Time.now
+    }
+  end
+end
+```
+
+Will generate the following:
+
+```ruby
+{
+  user: {
+    id: '12345',
+    email: 'mvilleneuve@snapp.fr',
+    custom_attribute: "Hi, I'm a custom attribute",
+    another_custom_attribute: "2018-09-26 17:49:59 +0200"
+  }
+}
+```
+
+You can declare any number of `each` in a single mapper.
+Actually, `each` is used to implement every above features.
+
+**Scope**
+
+ActiveMappers does not yet support inheritance. However we provide an even better alternative named `scope`.
+
+Whenever you feel the need to declare more or less attributes based on who called the mapper, you may want to consider using scope.
+
+A very usual use case would be to have a different way to map a resource depending on wether you are an administrator or not.
+Instead of declaring a whole new mapper just to add/remove attributes, you can do the following :
+
+```ruby
+class UserMapper < ActiveMappers::Base
+  attributes :pseudo
+
+  scope :admin
+    attributes :id
+  end
+
+  scope :owner
+    attributes :email
+  end
+end
+
+# This declaration gives you 3 ways to call the mapper
+
+# By an administrator
+UserMapper.with(User.first, scope: :admin)
+# => { pseudo: 'michael33', id: '1234' }
+
+# By anyone
+UserMapper.with(User.first)
+# => { pseudo: 'michael33' }
+
+# Or by the corresponding user that will gain access to personal informations
+UserMapper.with(User.first, scope: :owner)
+# => { pseudo: 'michael33', email: 'mvilleneuve@fidme.com' }
+```
+
+
+## Using a mapper
+
+Even though there are many ways to declare a mapper, there is only one way to use it
+
+```ruby
+UserMapper.with(User.first)
+
+# Or use it with a collection
+UserMapper.with(User.all)
+```
+
+In a Rails controller :
+
+```ruby
+def index
+  render json: UserMapper.with(User.all)
+end
+```
+
+### JSON Root
+
+You can choose to use ActiveMappers with or without a JSON root.
+
+By default, root will be enabled, meaning a UserMapper, will generate a JSON prefixed by :
+
+```ruby
+{
+  user: {}
+}
+```
+
+**Custom Root**
+
+If you want to customize the root name, you can use
+
+```ruby
+UserMapper.with(user, root: :hello)
+```
+
+which will generate :
+
+```ruby
+{
+  hello: {}
+}
+```
+
+**Rootless**
+
+If you do not want to set any root, use :
+
+```ruby
+UserMapper.with(user, rootless: true)
+```
+
+## Adding your own features to Active Mapper DSL
+
+If you want to add specific features to the DSL you can reopen `::ActiveMappers::Base` class and add your own methods.
+The most convenient way to do that is in your Active Mapper initializer following this pattern:
+
+```ruby
+ActiveMappers::Setup.configure do |config|
+  ...
+end
+
+module ActiveMappers
+  class Base
+    include Rails.application.routes.url_helpers
+
+    def self.my_capitalize_dsl_feature(*params)
+      each do |resource|                              #your mapped resource(s)
+        h = {}
+        params.each do |param|
+          h[param] = resource.try(param)&.capitalize  #your treatment
+        end
+        h                                             #the returned hash will be merged to the mapper result.
+      end
+    end
+  end
+end
+```
+and then: 
+
+```ruby
+class UserMapper < ActiveMappers::Base
+  my_capitalize_dsl_feature :civility
+end
+```
+
+## Anything is missing ?
+
+File an issue

data/Rakefile

@@ -0,0 +1,9 @@
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/active_mappers.gemspec

@@ -0,0 +1,20 @@
+Gem::Specification.new do |s|
+  s.name        = 'active_mappers'
+  s.version     = '1.3.0'
+  s.date        = '2019-05-10'
+  s.summary     = 'Slick, fast view layer for you Rails API.'
+  s.description = 'Fast, simple, declarative way to design your API\'s view layer'
+  s.authors     = ['Michaël Villeneuve']
+  s.homepage    = 'https://github.com/fidme/active_mappers'
+  s.email       = 'contact@michaelvilleneuve.fr'
+  s.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+
+  s.license = 'MIT'
+  s.add_runtime_dependency('activesupport', ['>= 4.2'])
+  s.add_runtime_dependency('method_source', ['~> 0.9.2'])
+  s.add_runtime_dependency('mocha', ['>= 1.8.0'])
+  s.add_runtime_dependency('ruby2ruby', ['> 2.4.0'])
+  s.add_runtime_dependency('ruby_parser', ['~> 3.1'])
+end

data/lib/active_mappers.rb

@@ -1,14 +1,23 @@
+require 'method_source'
+require 'ruby2ruby'
+require 'ruby_parser'
+
 require 'active_support'
 require 'active_support/core_ext/object/try'
+require 'active_support/core_ext/hash/except'
 require 'active_support/core_ext/string/inflections'
 require_relative 'core_ext/hash'
+require_relative 'active_mappers/handlers/inheritance'
 require_relative 'active_mappers/key_transformer'
 
+
 module ActiveMappers
   class Base
     @@renderers = {}
-    @@initial_renderers = {}
-    @@scopes = {}
+
+    def self.inherited(subclass)
+      Handlers::Inheritance.new(subclass, self).handle
+    end
 
     def self.attributes(*params)
       each do |resource|
@@ -66,36 +75,28 @@ module ActiveMappers
     end
 
     def self.with(args, options = {})
-      evaluate_scopes(options[:scope])
-
+      return evaluate_scopes(args, options) unless options[:scope].nil?
+      
       response = if options[:rootless]
         args.respond_to?(:each) ? all(args) : one(args)
       else
         render_with_root(args, options)
       end
       response
-    ensure
-      reset_renderers_before_scopes if !options[:scope].nil?
     end
 
-    def self.evaluate_scopes(scope_name)
-      return if scope_name.nil?
-      @@initial_renderers[name] = @@initial_renderers[name] ? @@initial_renderers[name] : [] + (@@renderers[name] || [])
-      
-      found_scope = (@@scopes[name] || []).detect { |s| s[:name] === scope_name }
-      raise "ActiveMappers [#{name}] Scope named #{scope_name} has not been declared or is not a block" if found_scope.nil? || found_scope[:lambda].nil? || !found_scope[:lambda].respond_to?(:call)
-      
-      found_scope[:lambda].call
+    def self.evaluate_scopes(args, options)
+      class_to_call = "::#{name}Scope#{options[:scope].capitalize}".constantize rescue raise("ActiveMappers [#{name}] No scope named #{options[:scope]} found")
+      return class_to_call.with(args, options.except(:scope))
     end
 
     def self.scope(*params, &block)
       raise "ActiveMappers [#{name}] scope must be a bloc" if block.nil? || !block.respond_to?(:call)
 
+      
       params.each do |param|
-        @@scopes[name] = (@@scopes[name] || []) << {
-          name: param,
-          lambda: block,
-        }
+        block_content = Ruby2Ruby.new.process(RubyParser.new.process(block.source).to_a.last)
+        eval("class ::#{name}Scope#{param.capitalize} < ::#{name} ; #{block_content}; end")
       end
     end
 
@@ -123,10 +124,5 @@ module ActiveMappers
 
       KeyTransformer.format_keys(renderers)
     end
-
-    def self.reset_renderers_before_scopes
-      return if !@@initial_renderers || !@@initial_renderers[name]
-      @@renderers[name] = @@initial_renderers[name].dup
-    end
   end
 end

data/lib/active_mappers/handlers/inheritance.rb

@@ -0,0 +1,26 @@
+module ActiveMappers
+  module Handlers
+    class Inheritance
+      def initialize(subclass, klass)
+        @subclass = subclass
+        @klass = klass
+      end
+
+      def handle
+        return nil if regular_inheritance?
+
+        @klass.class_variables.each do |var_name|
+          dsl_values = @subclass.class_variable_get(var_name)
+
+          dsl_values[@subclass.name] = dsl_values[@klass.name].dup
+        end
+      end
+
+      private
+
+      def regular_inheritance?
+        @klass == ActiveMappers::Base
+      end
+    end
+  end
+end

data/lib/active_mappers/key_transformer.rb

@@ -32,6 +32,7 @@ module ActiveMappers
       Setup.ignored_namespaces.each do |namespace|
         @name.gsub!("#{namespace.to_s.capitalize}::", '')
       end
+      @name = @name.split('MapperScope')[0]
       self
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_mappers
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.3.0
 platform: ruby
 authors:
 - Michaël Villeneuve
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: method_source
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.2
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
@@ -38,13 +52,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.8.0
+- !ruby/object:Gem::Dependency
+  name: ruby2ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+- !ruby/object:Gem::Dependency
+  name: ruby_parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
 description: Fast, simple, declarative way to design your API's view layer
 email: contact@michaelvilleneuve.fr
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- active_mappers.gemspec
 - lib/active_mappers.rb
+- lib/active_mappers/handlers/inheritance.rb
 - lib/active_mappers/key_transformer.rb
 - lib/active_mappers/setup.rb
 - lib/core_ext/hash.rb