encore 0.0.3 → 0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c05497c6b6640c47a20eafba79c3eb344cc523a6
-  data.tar.gz: 1e727f1662fdf0927f940e0a4d46fa5054073d88
+  metadata.gz: 58e8c5a2cb80f79ec4fdf6afec91a6d67dd1108c
+  data.tar.gz: f45565ef1a3ae7732237728783146b8a008d4f8e
 SHA512:
-  metadata.gz: 2b0c3d9175e9665cb709d725cf48873f2c16a4b9fb4100af1dafc07f087a9a9a075fbb8492822624a186386f4b5a0e7f25c560fdfd3b02dee4efd43e89820157
-  data.tar.gz: 46d9c310cdaed3ea98051dea98f3a463137468f512abadfd62019553e74dd4c35e0c88d9531f14d47c289b358b516d82ed2e208b6f1059ba87fb3d1a5796c7f2
+  metadata.gz: cd79df1408e83a0792e7723c47fd0d7466140492ca7f10ce36e95902c3e42b992472aa96e27021e07ed9724290ab828983055e9119f79cf7b8caf4be49e2ef79
+  data.tar.gz: 44b77c571699964d6b3c0b5b6593d660a9e62eac44bc2d9de8e3be72315a57a7fb264a39fd83fc94151171493e53d06be94271241254049c8a5cc68e85441a7a

data/.gitignore

@@ -1,17 +1 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
 Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp

data/.rubocop.yml

@@ -0,0 +1,53 @@
+AllCops:
+  Include:
+    - encore.gemspec
+
+Documentation:
+  Enabled: false
+
+Encoding:
+  Enabled: false
+
+LineLength:
+  Max: 200
+
+ClassLength:
+  Max: 200
+
+AccessModifierIndentation:
+  EnforcedStyle: outdent
+
+IfUnlessModifier:
+  Enabled: false
+
+CaseIndentation:
+  IndentWhenRelativeTo: case
+  IndentOneStep: true
+
+MethodLength:
+  CountComments: false
+  Max: 20
+
+SignalException:
+  Enabled: false
+
+ColonMethodCall:
+  Enabled: false
+
+AsciiComments:
+  Enabled: false
+
+Lambda:
+  Enabled: false
+
+RegexpLiteral:
+  Enabled: false
+
+AssignmentInCondition:
+  Enabled: false
+
+ClassAndModuleChildren:
+  Enabled: false
+
+GuardClause:
+  Enabled: false

data/.travis.yml

@@ -1,11 +1,19 @@
 language: ruby
 
 rvm:
+  - 2.1.1
   - 2.0.0
-  - 1.9.3
 
 gemfile:
   - gemfiles/Gemfile.activerecord-4.0
-  - gemfiles/Gemfile.activerecord-3.2.x
+  - gemfiles/Gemfile.activerecord-4.1
 
 script: "echo 'DO IT' && bundle exec rake spec"
+
+notifications:
+  hipchat:
+    rooms:
+      secure: "lLUK7HuJzZiae6dSB35I/ZlTI8guiRteImGQBhj1DKe533HPGZQHnhwAdML2YY6nLzhfw1uaXHNgGDCLTkylHK2ChLROHZicoX6mCLPqspwkB2GCx4K+1neltReeOIIi5ZIg2fz6wAV9rdSSaIBpIUg1717nhbOCP3ouIf0j3X0="
+    template:
+      - '%{repository}#%{build_number} (%{branch} - %{commit} : %{author}): %{message} (<a href="%{build_url}">Build</a>/<a href="%{compare_url}">Changes</a>)'
+    format: 'html'

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2013, Mirego
+Copyright (c) 2013-2014, Mirego
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/README.md

@@ -3,15 +3,10 @@
     <img src="http://i.imgur.com/erXBozp.png" alt="Encore" />
   </a>
   <br />
-  Encore is a Ruby framework to help dealing with entities.
+  Encore provides serializers and persisters to build <a href="http://jsonapi.org">JSON API</a>-compliant Web services with Ruby on Rails.
   <br /><br />
-  <a href="https://rubygems.org/gems/encore"><img src="https://badge.fury.io/rb/encore.png" /></a>
-  <a href="https://codeclimate.com/github/mirego/encore"><img src="https://codeclimate.com/github/mirego/encore.png" /></a>
-  <a href="https://travis-ci.org/mirego/encore"><img src="https://travis-ci.org/mirego/encore.png?branch=master" /></a>
 </p>
 
----
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -32,196 +27,153 @@ Or install it yourself as:
 $ gem install encore
 ```
 
-## Usage
-
-Let’s say we have the `UserEntity` entity class bound to the `User` model:
+## Disclaimer
 
-```ruby
-class User < ActiveRecord::Base
-end
+Encore is under heavy development at the moment, do not use this gem in production unless you know exactly what you're doing. **Breaking changes** are still being committed.
 
-class UserEntity
-  include Encore::Entity
-
-  expose :name
-  expose :email
-  expose :created_at, readonly: true
-  expose :updated_at, readonly: true
-end
-```
+## Basic serializer usage
 
-We can create a new `User` resource with attributes:
+### Configure your serializer
 
 ```ruby
-@entity = UserEntity.new
-@entity.assign_attributes email: 'remi@example.com', name: 'Rémi Prévost'
-@entity.save
-```
-
-When assigning attributes to an entity, we can pass either an `:update` or a `:partial_update` context.
-
-With the (default) `:partial_update` context, Encore will assign new attributes and ignore the other exposed attributes. This makes sense in a `PATCH` HTTP request context.
-
-```ruby
-new_attributes = { email: 'remi+new@example.com' }
-@entity.assign_attributes new_attributes
-@entity.object.email # => "remi+new@example.com"
-@entity.object.name # => "Rémi Prévost"
-```
-
-However, with the `:update` context, Encore will assign new attributes and set all non-provided exposed attributes to `nil`. This
-makes sense in a `PUT` HTTP request context.
-
-```ruby
-new_attributes = { email: 'remi+new-again@example.com' }
-@entity.assign_attributes new_attributes, context: :update
-@entity.object.email # => "remi+new-again@example.com"
-@entity.object.name # => nil
-```
-
-If we try to assign a value to a non-exposed or readonly attribute, Encore will raise an error.
-
-```ruby
-@entity.assign_attributes email: 'remi+new@example.com', created_at: Time.now
-# => raises #<Encore::Entity::Input::InvalidAttributeError: The #<Encore::Attribute UserEntity@created_at> attribute is not exposed.>
+class CommentSerializer < Encore::Serializer::Base
+  attributes :id, :body, :links
+
+  # By default, root_key will be the pluralized model
+  # name. If you want to set a custom root_key, you can
+  # do that:
+  def self.root_key
+    :user_comments
+  end
+end
 ```
 
-### Associations
+The `links` attribute is generated by Encore and will return the included associations. Read more in the [Inclusion](#inclusion) section.
 
-You can also expose associations.
+### Returning serialized model
 
 ```ruby
-class User < ActiveRecord::Base
-  belongs_to :organization
-end
+class CommentsController < ApplicationController
+  before_action :fetch_comments, only: %i(index)
 
-class Organization < ActiveRecord::Base
-  has_many :users
-end
+  def index
+    render json: Encore::Serializer::Instance.new(@comments)
+  end
 
-class UserEntity
-  include Encore::Entity
+protected
 
-  expose :name
-  expose_one :organization
+  def fetch_comments
+    @comments = Comment.all
+  end
 end
 ```
 
-Assigning new value for associations doesn’t save them right away.
-
-```ruby
-@user = User.first # => #<User id=1 organization_id=1>
-@entity = UserEntity.new(@user)
-@entity.assign_attributes organization: 2
-@entity.object.organization_id # => 1
+Will result in the following JSON output:
+
+```json
+{
+  "comments": [
+    {
+      "id": "1",
+      "body": "First!",
+      "links": {}
+    }
+  ],
+  "links": {},
+  "linked": {},
+  "meta": {
+    "comments": {
+      "page": 1,
+      "count": 1,
+      "page_count": 1,
+      "previous_page": null,
+      "next_page": null
+    }
+  }
 ```
 
-Calling `save` on the entity saves them.
-
-```ruby
-@entity.save
-@entity.object.organization_id # => 2
-```
+### Inclusion
 
-## Typical setup with Ruby on Rails
-
-_This is work-in-progress. There’s still missing stuff._
-
-### Model
+Encore can handle model associations. For example, let's include the `author` in the code sample above.
 
 ```ruby
-# app/models/user.rb
-class User < ActiveRecord::Base
-end
+Encore::Serializer::Instance.new(@comments, include: 'author')
 ```
 
-### Entity
+Since we don't want all associations to be exposed, we also need to allow the serializer to include the association. To do so, we need to update the `CommentSerializer`.
 
 ```ruby
-# app/entities/user_entity.rb
-class UserEntity
-  include Encore::Entity
-
-  expose :name
-  expose :email
-  expose :created_at, readonly: true
-  expose :updated_at, readonly: true
-end
-```
-
-### Routes
+class CommentSerializer < Encore::Serializer::Base
+  # ...
 
-```ruby
-# config/routes.rb
-Rails::Application.routes.draw do
-  resources :users do
-    # This makes Rails route PUT and PATCH requests to two separate actions
-    patch on: :member, action: :partial_update
+  def self.can_include
+    [:author]
   end
 end
 ```
 
-### Controller
-
-```ruby
-# app/controllers/users_controller.rb
-class UsersController < ApplicationController
-  before_action :fetch_user, only: [:update, :partial_update]
-
-  # POST /users
-  def create
-    @entity = UserEntity.new
-    @entity.assign_attributes(params[:user], context: :create)
-
-    process! @entity
-
-    # Here, `process!` is a shortcut for:
-    #
-    # if @entity.save
-    #   render json: @entity, status: 201
-    # else
-    #   render json: { errors: @entity.errors }, status: 422
-    # end
-  end
-
-  # PUT /users/:id
-  def update
-    @entity = UserEntity.new(@user)
-    @entity.assign_attributes(params[:user], context: :update)
-
-    process! @entity
-  end
-
-  # PATCH /users/:id
-  def partial_update
-    @entity = UserEntity.new(@user)
-    @entity.assign_attributes(params[:user], context: :partial_update)
+This will result in the following JSON output:
+
+```json
+{
+  "comments": [
+    {
+      "id": "1",
+      "body": "First!",
+      "links": {
+        "author": "1"
+      }
+    }
+  ],
+  "links": {
+    "comments.author": {
+      "href": "/authors?ids={author.id}",
+      "type": "user"
+    }
+  },
+  "linked": {
+    "authors": [
+      {
+        "id": "1",
+        "name": "John Doe"
+      }
+    ]
+  },
+  "meta": {
+    "comments": {
+      "page": 1,
+      "count": 1,
+      "page_count": 1,
+      "previous_page": null,
+      "next_page": null
+    }
+  }
+```
 
-    process! @entity
-  end
+If you want the `author` the **always** be included when you request a `comment`, update the `CommentSerializer` this way:
 
-protected
+```ruby
+class CommentSerializer < Encore::Serializer::Base
+  attributes :id, :body, :links
 
-  def fetch_user
-    @user = User.find(params[:id])
+  def self.always_include
+    [:author]
   end
 end
 ```
 
-## Todo
+### Pagination
 
-Please keep in mind that this gem is far from finished and totally not ready to use in production.
-This is something we’ve been wanting to build for a long time and now we’re finally taking the time
-do it right.
+Lot more work to do here :)
 
 ## License
 
-`Encore` is © 2013 [Mirego](http://www.mirego.com) and may be freely distributed under the [New BSD license](http://opensource.org/licenses/BSD-3-Clause).  See the [`LICENSE.md`](https://github.com/mirego/encore/blob/master/LICENSE.md) file.
+`Encore` is © 2013-2014 [Mirego](http://www.mirego.com) and may be freely distributed under the [New BSD license](http://opensource.org/licenses/BSD-3-Clause).  See the [`LICENSE.md`](https://github.com/mirego/encore/blob/master/LICENSE.md) file.
 
-The nut logo is based on [this lovely icon](http://thenounproject.com/noun/hazelnuts/#icon-No3618) by [Alessandro Suraci](http://thenounproject.com/alessandro.suraci/), from The Noun Project. Used under a [Creative Commons BY 3.0](http://creativecommons.org/licenses/by/3.0/) license.
+The hazelnut logo is based on [this lovely icon](http://thenounproject.com/term/hazelnuts/3618/) by [Alessandro Suraci](http://thenounproject.com/alessandro.suraci/), from The Noun Project. Used under a [Creative Commons BY 3.0](http://creativecommons.org/licenses/by/3.0/) license.
 
 ## About Mirego
 
-Mirego is a team of passionate people who believe that work is a place where you can innovate and have fun. We proudly build mobile applications for [iPhone](http://mirego.com/en/iphone-app-development/ "iPhone application development"), [iPad](http://mirego.com/en/ipad-app-development/ "iPad application development"), [Android](http://mirego.com/en/android-app-development/ "Android application development"), [Blackberry](http://mirego.com/en/blackberry-app-development/ "Blackberry application development"), [Windows Phone](http://mirego.com/en/windows-phone-app-development/ "Windows Phone application development") and [Windows 8](http://mirego.com/en/windows-8-app-development/ "Windows 8 application development") in beautiful Quebec City.
+[Mirego](http://mirego.com) is a team of passionate people who believe that work is a place where you can innovate and have fun. We're a team of [talented people](http://life.mirego.com) who imagine and build beautiful Web and mobile applications. We come together to share ideas and [change the world](http://mirego.org).
 
-We also love [open-source software](http://open.mirego.com/) and we try to extract as much code as possible from our projects to give back to the community.
+We also [love open-source software](http://open.mirego.com) and we try to give back to the community as much as we can.

data/Rakefile

@@ -9,3 +9,13 @@ desc 'Run all specs'
 RSpec::Core::RakeTask.new(:spec) do |task|
   task.pattern = 'spec/**/*_spec.rb'
 end
+
+desc 'Start an IRB session with the gem'
+task :console do
+  $:.unshift File.expand_path('..', __FILE__)
+  require 'encore'
+  require 'irb'
+
+  ARGV.clear
+  IRB.start
+end

data/encore.gemspec

@@ -1,4 +1,5 @@
 # coding: utf-8
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'encore/version'
@@ -6,23 +7,25 @@ require 'encore/version'
 Gem::Specification.new do |spec|
   spec.name          = 'encore'
   spec.version       = Encore::VERSION
-  spec.authors       = ['Rémi Prévost']
-  spec.email         = ['rprevost@mirego.com']
-  spec.description   = 'Encore is a Ruby framework to help dealing with entities.'
+  spec.authors       = ['Simon Prévost']
+  spec.email         = ['sprevost@mirego.com']
+  spec.description   = 'Encore provides serializers and persisters to build JSON API-compliant Web services with Ruby on Rails.'
   spec.summary       = spec.description
   spec.homepage      = 'https://github.com/mirego/encore'
-  spec.license       = "BSD 3-Clause"
+  spec.license       = 'BSD 3-Clause'
 
-  spec.files         = `git ls-files`.split($/)
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'rake'
-  spec.add_development_dependency 'rspec'
-  spec.add_development_dependency 'sqlite3'
-  spec.add_development_dependency 'rails', '>= 3.0.0'
+  spec.add_dependency 'activemodel', '>= 4.0.0'
+  spec.add_dependency 'activerecord', '>= 4.0.0'
+  spec.add_dependency 'active_model_serializers', '~> 0.8.0'
+  spec.add_dependency 'kaminari', '~> 0.15.1'
 
-  spec.add_dependency 'activesupport', '>= 3.0.0'
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake', '~> 10.3'
+  spec.add_development_dependency 'rspec', '3.0.0beta2'
+  spec.add_development_dependency 'sqlite3', '>= 1.3.8', '< 1.4'
+  spec.add_development_dependency 'rubocop', '0.22'
+  spec.add_development_dependency 'phare'
 end

data/gemfiles/{Gemfile.activerecord-3.2.x → Gemfile.activerecord-4.1}

@@ -2,4 +2,4 @@ source 'https://rubygems.org'
 
 gemspec path: '../'
 
-gem 'activerecord', '~> 3.2.0'
+gem 'activerecord', '~> 4.1.0'

data/lib/encore/config.rb

@@ -0,0 +1,2 @@
+ActiveModel::Serializer.root = false
+Kaminari::Hooks.init

data/lib/encore/persister/errors_parser.rb

@@ -0,0 +1,17 @@
+module Encore
+  module Persister
+    module ErrorsParser
+      extend ActiveSupport::Concern
+
+      def parse_errors(record, index)
+        record.errors.messages.map do |field, values|
+          {
+            field: field.to_s,
+            types: values,
+            path: "#{record.class.name.underscore}/#{index}/#{field}"
+          }
+        end
+      end
+    end
+  end
+end

data/lib/encore/persister/instance.rb

@@ -0,0 +1,85 @@
+require 'encore/persister/param_injection'
+require 'encore/persister/errors_parser'
+require 'encore/persister/key_mapping'
+require 'encore/persister/links_parser'
+
+module Encore
+  module Persister
+    class Instance
+      include LinksParser
+      include ErrorsParser
+
+      attr_reader :errors
+
+      def initialize(model, payload, options = {})
+        @model = model
+        @payload = payload
+        @options = options
+        @errors = []
+        @ids = Set.new
+      end
+
+      def persist!
+        @model.transaction do
+          procces_payload!(action)
+
+          if @errors.any? || @ids.empty?
+            raise ActiveRecord::Rollback
+          end
+
+          true
+        end
+      end
+
+      def active_records
+        active_record_class.where(id: @ids.to_a.compact)
+      end
+
+    private
+
+      def procces_payload!(action)
+        payload = key_mapping(@payload)
+        payload = param_injection(payload)
+
+        payload.each_with_index do |args, i|
+          args = parse_links(args)
+          record = send("#{action}_record", args)
+
+          next unless record.present?
+
+          @ids += fetch_id(record)
+          @errors += parse_errors(record, i)
+        end
+      end
+
+      def active_record_class
+        @model.is_a?(Class) ? @model : @model.class
+      end
+
+      def action
+        @model.is_a?(Class) ? :create : :update
+      end
+
+      def create_record(args)
+        @model.create args
+      end
+
+      def update_record(args)
+        @model.update_attributes(args)
+        @model
+      end
+
+      def fetch_id(record)
+        [record.id]
+      end
+
+      def key_mapping(payload)
+        @model.active_model_serializer ? KeyMapping.map_keys(payload, @model.active_model_serializer) : payload
+      end
+
+      def param_injection(payload)
+        ParamInjection.inject(payload, @options[:inject_params])
+      end
+    end
+  end
+end

data/lib/encore/persister/key_mapping.rb

@@ -0,0 +1,15 @@
+module Encore
+  module Persister
+    module KeyMapping
+      def self.map_keys(array_params, serializer)
+        array_params.map do |params|
+          mappings = serializer.key_mappings
+
+          params.keys.each { |k| params[mappings[k]] = params.delete(k) if mappings[k] }
+
+          params
+        end
+      end
+    end
+  end
+end