restpack_serializer 0.2.3

data/lib/restpack_serializer/serializable/side_loading.rb

@@ -0,0 +1,115 @@
+module RestPack::Serializer::SideLoading
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    def side_loads(models, options)
+      side_loads = {
+        :meta => { }
+      }
+      return side_loads if models.empty? || options.includes.nil?
+
+      options.includes.each do |include|
+        side_load_data = side_load(include, models, options)
+        side_loads[:meta].merge!(side_load_data[:meta] || {})
+        side_loads.merge! side_load_data.except(:meta)
+      end
+      side_loads
+    end
+
+    def filterable_by
+      filters = [self.model_class.primary_key.to_sym]
+      filters += self.model_class.reflect_on_all_associations(:belongs_to).map(&:foreign_key).map(&:to_sym)
+      filters.uniq
+    end
+
+    def can_includes
+      @can_includes || []
+    end
+
+    def can_include(*includes)
+      @can_includes ||= []
+      @can_includes += includes
+    end
+
+    def links
+      links = {}
+
+      associations.each do |association|
+        if association.macro == :belongs_to
+          href = "/#{association.plural_name}/{#{self.key}.#{association.name}}.json"
+        elsif association.macro == :has_many
+          singular_key = self.key.to_s.singularize
+          href = "/#{association.plural_name}.json?#{singular_key}_id={#{key}.id}"
+        end
+
+        links["#{self.key}.#{association.plural_name}"] = {
+          :href => href,
+          :type => association.plural_name.to_sym
+        }
+      end
+
+      links
+    end
+
+    def associations
+      associations = []
+      can_includes.each do |include|
+        association = association_from_include(include)
+        associations << association if supported_association?(association)
+      end
+      associations
+    end
+
+    private
+
+    def side_load(include, models, options)
+      association = association_from_include(include)
+
+      if supported_association?(association)
+        serializer = RestPack::Serializer::Factory.create(association.class_name)
+        return send("side_load_#{association.macro}", association, models, serializer)
+      else
+        return {}
+      end
+    end
+
+    def supported_association?(association)
+      [:belongs_to, :has_many].include?(association.macro)
+    end
+
+    def side_load_belongs_to(association, models, serializer)
+      foreign_keys = models.map { |model| model.send(association.foreign_key) }.uniq
+      side_load = association.klass.find(foreign_keys)
+
+      return {
+        association.plural_name.to_sym => side_load.map { |model| serializer.as_json(model) },
+        :meta => { }
+      }
+    end
+
+    def side_load_has_many(association, models, serializer)
+      return {} if models.empty?
+      options = RestPack::Serializer::Options.new(serializer.class.model_class)
+      options.filters = { association.foreign_key.to_sym => models.map(&:id) }
+      options.include_links = false
+      return serializer.class.page_with_options(options)
+    end
+
+    def association_from_include(include)
+      raise_invalid_include(include) unless self.can_includes.include?(include)
+
+      possible_relations = [include.to_s.singularize.to_sym, include]
+      possible_relations.each do |relation|
+        association = self.model_class.reflect_on_association(relation)
+        return association unless association.nil?
+      end
+
+      raise_invalid_include(include)
+    end
+
+    def raise_invalid_include(include)
+      raise RestPack::Serializer::InvalidInclude.new,
+        ":#{include} is not a valid include for #{self.model_class}"
+    end
+  end
+end

data/lib/restpack_serializer/serializable.rb

@@ -0,0 +1,69 @@
+require 'active_support/concern'
+require_relative "options"
+require_relative "serializable/attributes"
+require_relative "serializable/paging"
+require_relative "serializable/resource"
+require_relative "serializable/side_loading"
+
+module RestPack
+  module Serializer
+    extend ActiveSupport::Concern
+
+    include RestPack::Serializer::Paging
+    include RestPack::Serializer::Resource
+    include RestPack::Serializer::Attributes
+    include RestPack::Serializer::SideLoading
+
+    class InvalidInclude < Exception; end
+
+    def as_json(model, options = {})
+      @model, @options = model, options
+
+      data = {}
+      if self.class.serializable_attributes.present?
+        self.class.serializable_attributes.each do |key, name|
+          data[key] = self.send(name) if include_attribute?(name)
+        end
+      end
+
+      add_links(model, data)
+
+      data
+    end
+
+    private
+
+    def add_links(model, data)
+      self.class.associations.each do |association|
+        if association.macro == :belongs_to
+          data[:links] ||= {}
+          data[:links][association.name.to_sym] = model.send(association.foreign_key).to_s
+        end
+      end
+      data
+    end
+
+    def include_attribute?(name)
+      self.send("include_#{name}?".to_sym)
+    end
+
+    module ClassMethods
+      def as_json(model, options = {})
+        new.as_json(model, options)
+      end
+
+      def model_name
+        self.name.chomp('Serializer')
+      end
+
+      def model_class
+        model_name.constantize
+      end
+
+      def key
+        self.model_class.send(:table_name).to_sym
+      end
+
+    end
+  end
+end

data/lib/restpack_serializer/version.rb

@@ -0,0 +1,5 @@
+module RestPack
+  module Serializer
+    VERSION = '0.2.3'
+  end
+end

data/lib/restpack_serializer.rb

@@ -0,0 +1,6 @@
+require 'will_paginate'
+require 'will_paginate/active_record'
+
+require 'restpack_serializer/version'
+require 'restpack_serializer/serializable'
+require 'restpack_serializer/factory'

data/restpack_serializer.gemspec

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'restpack_serializer/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "restpack_serializer"
+  gem.version       = RestPack::Serializer::VERSION
+  gem.authors       = ["Gavin Joyce"]
+  gem.email         = ["gavinjoyce@gmail.com"]
+  gem.description   = %q{Model serialization, paging, side-loading and filtering}
+  gem.summary       = %q{Model serialization, paging, side-loading and filtering}
+  gem.homepage      = "https://github.com/RestPack"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency 'activerecord', '>= 3.0'
+  gem.add_dependency 'activesupport', '>= 3.0'
+  gem.add_dependency 'will_paginate', '~> 3.0'
+
+  gem.add_development_dependency 'rake', '~> 10.0.3'
+  gem.add_development_dependency 'rspec', '~> 2.12'
+  gem.add_development_dependency 'guard-rspec', '~> 2.5.4'
+  gem.add_development_dependency 'growl', '~> 1.0.3'
+  gem.add_development_dependency 'factory_girl', '~> 4.2.0'
+  gem.add_development_dependency 'sqlite3', '~> 1.3.7'
+  gem.add_development_dependency 'database_cleaner', '~> 0.9.1'
+  gem.add_development_dependency 'bump'
+end

data/spec/factory/factory_spec.rb

@@ -0,0 +1,28 @@
+require './spec/spec_helper'
+
+describe RestPack::Serializer::Factory do
+  let(:factory) { RestPack::Serializer::Factory }
+
+  it "creates by string" do
+    factory.create("Song").should be_an_instance_of(SongSerializer)
+  end
+  it "creates by lowercase string" do
+    factory.create("song").should be_an_instance_of(SongSerializer)
+  end
+  it "creates by lowercase plural string" do
+    factory.create("songs").should be_an_instance_of(SongSerializer)
+  end
+  it "creates by symbol" do
+    factory.create(:song).should be_an_instance_of(SongSerializer)
+  end
+  it "creates by class" do
+    factory.create(Song).should be_an_instance_of(SongSerializer)
+  end
+
+  it "creates multiple with Array" do
+    serializers = factory.create("Song", "artists", :album)
+    serializers[0].should be_an_instance_of(SongSerializer)
+    serializers[1].should be_an_instance_of(ArtistSerializer)
+    serializers[2].should be_an_instance_of(AlbumSerializer)
+  end
+end

data/spec/fixtures/db.rb

@@ -0,0 +1,68 @@
+require 'sqlite3'
+require 'active_record'
+
+ActiveRecord::Base.establish_connection(
+  :adapter => 'sqlite3',
+  :database => 'test.db'
+)
+
+ActiveRecord::Schema.define(:version => 1) do
+  create_table "artists", :force => true do |t|
+    t.string   "name"
+    t.string   "website"
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+
+  create_table "albums", :force => true do |t|
+    t.string   "title"
+    t.integer  "year"
+    t.integer  "artist_id"
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+
+  create_table "songs", :force => true do |t|
+    t.string   "title"
+    t.integer  "album_id"
+    t.integer  "artist_id"
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+
+  create_table "payments", :force => true do |t|
+    t.integer "amount"
+    t.integer  "artist_id"
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+end
+
+class Artist < ActiveRecord::Base
+  attr_accessible :name, :website
+
+  has_many :albums
+  has_many :songs
+  has_many :payments
+end
+
+class Album < ActiveRecord::Base
+  attr_accessible :title, :year, :artist
+  scope :classic, where("year < 1950")
+
+  belongs_to :artist
+  has_many :songs
+end
+
+class Song < ActiveRecord::Base
+  attr_accessible :title, :artist, :album
+
+  belongs_to :artist
+  belongs_to :album
+end
+
+class Payment < ActiveRecord::Base
+  attr_accessible :amount, :artist
+
+  belongs_to :artist
+end

data/spec/fixtures/serializers.rb

@@ -0,0 +1,17 @@
+class SongSerializer
+  include RestPack::Serializer
+  attributes :id, :title, :album_id
+  can_include :albums, :artists
+end
+
+class AlbumSerializer
+  include RestPack::Serializer
+  attributes :id, :title, :year, :artist_id
+  can_include :artists, :songs
+end
+
+class ArtistSerializer
+  include RestPack::Serializer
+  attributes :id, :name, :website
+  can_include :albums, :songs
+end

data/spec/serializable/attributes_spec.rb

@@ -0,0 +1,27 @@
+require './spec/spec_helper'
+
+describe RestPack::Serializer::Attributes do
+	class CustomSerializer
+		include RestPack::Serializer
+		attributes :a, :b, :c
+		attribute :old_attribute, :key => :new_key
+	end
+
+	before do
+		@attributes = CustomSerializer.serializable_attributes
+	end
+
+	it "correctly models specified attributes" do
+		@attributes.length.should == 4
+	end
+
+	it "correctly maps normal attributes" do
+		[:a, :b, :c].each do |attr|
+			@attributes[attr].should == attr
+		end
+	end
+
+	it "correctly maps attribute with :key options" do
+		@attributes[:new_key].should == :old_attribute
+	end
+end

data/spec/serializable/options_spec.rb

@@ -0,0 +1,65 @@
+require './spec/spec_helper'
+
+describe RestPack::Serializer::Options do
+  let(:subject) { RestPack::Serializer::Options.new(Song, params, scope) }
+  let(:params) { {} }
+  let(:scope) { nil }
+
+  describe 'default values' do
+    it { subject.model_class.should == Song }
+    it { subject.includes.should == [] }
+    it { subject.page.should == 1 }
+    it { subject.page_size.should == 10 }
+    it { subject.filters.should == {} }
+    it { subject.scope.should == Song.scoped }
+  end
+
+  describe 'with paging params' do
+    let(:params) { { 'page' => '2', 'page_size' => '8' } }
+    it { subject.page.should == 2 }
+    it { subject.page_size.should == 8 }
+  end
+
+  describe 'with includes' do
+    let(:params) { { 'includes' => 'model1,model2' } }
+    it { subject.includes.should == [:model1, :model2] }
+  end
+
+  context 'with filters' do
+    describe 'with no filter params' do
+      let(:params) { { } }
+      it { subject.filters.should == {} }
+    end
+    describe 'with a primary key with a single value' do
+      let(:params) { { 'id' => '142857' } }
+      it { subject.filters.should == { id: ['142857'] } }
+    end
+    describe 'with a primary key with multiple values' do
+      let(:params) { { 'ids' => '42,142857' } }
+      it { subject.filters.should == { id: ['42', '142857'] } }
+    end
+    describe 'with a foreign key with a single value' do
+      let(:params) { { 'album_id' => '789' } }
+      it { subject.filters.should == { album_id: ['789'] } }
+    end
+    describe 'with a foreign key with multiple values' do
+      let(:params) { { 'album_id' => '789,678,567' } }
+      it { subject.filters.should == { album_id: ['789', '678', '567'] } }
+    end
+    describe 'with multiple foreign keys' do
+      let(:params) { { 'album_id' => '111,222', 'artist_id' => '888,999' } }
+      it { subject.filters.should == { album_id: ['111', '222'], artist_id: ['888', '999'] } }
+    end
+  end
+
+  context 'scopes' do
+    describe 'with default scope' do
+      it { subject.scope.should == Song.scoped }
+    end
+
+    describe 'with custom scope' do
+      let(:scope) { Song.where("id >= 100") }
+      it { subject.scope.should == scope }
+    end
+  end
+end

data/spec/serializable/paging_spec.rb

@@ -0,0 +1,184 @@
+require './spec/spec_helper'
+
+describe RestPack::Serializer::Paging do
+  before(:each) do
+    @album1 = FactoryGirl.create(:album_with_songs, song_count: 11)
+    @album2 = FactoryGirl.create(:album_with_songs, song_count: 7)
+  end
+
+  context "#page" do
+    let(:page) { SongSerializer.page(params) }
+    let(:params) { { } }
+
+    context "with defaults" do
+      it "page defaults to 1" do
+        page[:meta][:songs][:page].should == 1
+      end
+      it "page_size defaults to 10" do
+        page[:meta][:songs][:page_size].should == 10
+      end
+      it "includes valid paging meta data" do
+        page[:meta][:songs][:count].should == 18
+        page[:meta][:songs][:page_count].should == 2
+        page[:meta][:songs][:previous_page].should == nil
+        page[:meta][:songs][:next_page].should == 2
+      end
+      it "includes links" do
+        page[:links].should == {
+          'songs.albums' => { :href => "/albums/{songs.album}.json", :type => :albums },
+          'songs.artists' => { :href => "/artists/{songs.artist}.json", :type => :artists }
+        }
+      end
+    end
+
+    context "with custom page size" do
+      let(:params) { { page_size: '3' } }
+      it "returns custom page sizes" do
+        page[:meta][:songs][:page_size].should == 3
+        page[:meta][:songs][:page_count].should == 6
+      end
+    end
+
+    it "serializes results" do
+      first = Song.first
+      page[:songs].first.should == {
+        id: first.id.to_s,
+        title: first.title,
+        album_id: first.album_id,
+        links: {
+          album: first.album_id.to_s,
+          artist: first.artist_id.to_s
+        }
+      }
+    end
+
+    context "first page" do
+      let(:params) { { page: '1' } }
+
+      it "returns first page" do
+        page[:meta][:songs][:page].should == 1
+        page[:meta][:songs][:page_size].should == 10
+        page[:meta][:songs][:previous_page].should == nil
+        page[:meta][:songs][:next_page].should == 2
+      end
+    end
+
+    context "second page" do
+      let(:params) { { page: '2' } }
+
+      it "returns second page" do
+        page[:songs].length.should == 8
+        page[:meta][:songs][:page].should == 2
+        page[:meta][:songs][:previous_page].should == 1
+        page[:meta][:songs][:next_page].should == nil
+      end
+    end
+
+    context "when sideloading" do
+      let(:params) { { includes: 'albums' } }
+
+      it "includes side-loaded models" do
+        page[:albums].should_not == nil
+      end
+
+      it "includes the side-loads in the main meta data" do
+        page[:meta][:songs][:includes].should == [:albums]
+      end
+
+      context "with includes as comma delimited string" do
+        let(:params) { { includes: "albums,artists" } }
+        it "includes side-loaded models" do
+          page[:albums].should_not == nil
+          page[:artists].should_not == nil
+        end
+
+        it "includes links" do
+          page[:links]['songs.albums'].should_not == nil
+          page[:links]['songs.artists'].should_not == nil
+          page[:links]['albums.songs'].should_not == nil
+          page[:links]['albums.artists'].should_not == nil
+          page[:links]['artists.songs'].should_not == nil
+          page[:links]['artists.albums'].should_not == nil
+        end
+      end
+    end
+
+    context "when filtering" do
+      context "with no filters" do
+        let(:params) { {} }
+
+        it "returns a page of all data" do
+          page[:meta][:songs][:count].should == 18
+        end
+      end
+
+      context "with :album_id filter" do
+        let(:params) { { album_id: @album1.id.to_s } }
+
+        it "returns a page with songs from album1" do
+          page[:meta][:songs][:count].should == @album1.songs.length
+        end
+      end
+    end
+
+    context "with custom scope" do
+      before do
+        FactoryGirl.create(:album, year: 1930)
+        FactoryGirl.create(:album, year: 1948)
+      end
+      let(:page) { AlbumSerializer.page(params, scope) }
+      let(:scope) { Album.classic }
+
+      it "returns a page of scoped data" do
+        page[:meta][:albums][:count].should == 2
+      end
+    end
+  end
+
+  context "#page_with_options" do
+    let(:page) { SongSerializer.page_with_options(options) }
+    let(:params) { {} }
+    let(:options) { RestPack::Serializer::Options.new(Song, params) }
+
+    context "with defaults" do
+      it "includes valid paging meta data" do
+        page[:meta][:songs][:count].should == 18
+        page[:meta][:songs][:page_count].should == 2
+        page[:meta][:songs][:previous_page].should == nil
+        page[:meta][:songs][:next_page].should == 2
+      end
+    end
+
+    context "with custom page size" do
+      let(:params) { { page_size: '3' } }
+      it "returns custom page sizes" do
+        page[:meta][:songs][:page_size].should == 3
+        page[:meta][:songs][:page_count].should == 6
+      end
+    end
+  end
+
+  context "paging with paged side-load" do
+    let(:page) { AlbumSerializer.page_with_options(options) }
+    let(:options) { RestPack::Serializer::Options.new(Album, { includes: 'songs' }) }
+
+    it "includes side-loaded paging data in meta data" do
+      page[:meta][:albums].should_not == nil
+      page[:meta][:albums][:page].should == 1
+      page[:meta][:songs].should_not == nil
+      page[:meta][:songs][:page].should == 1
+    end
+  end
+
+  context "paging with two paged side-loads" do
+    let(:page) { ArtistSerializer.page_with_options(options) }
+    let(:options) { RestPack::Serializer::Options.new(Artist, { includes: 'albums,songs' }) }
+
+    it "includes side-loaded paging data in meta data" do
+      page[:meta][:albums].should_not == nil
+      page[:meta][:albums][:page].should == 1
+      page[:meta][:songs].should_not == nil
+      page[:meta][:songs][:page].should == 1
+    end
+  end
+end

data/spec/serializable/resource_spec.rb

@@ -0,0 +1,40 @@
+require './spec/spec_helper'
+
+describe RestPack::Serializer::Resource do
+  before(:each) do
+    @album = FactoryGirl.create(:album_with_songs, song_count: 11)
+    @song = @album.songs.first
+  end
+
+  let(:resource) { SongSerializer.resource(params) }
+  let(:params) { { id: @song.id.to_s } }
+
+  it "returns a resource by id" do
+    resource[:songs].count.should == 1
+    resource[:songs][0][:id].should == @song.id.to_s
+  end
+
+  describe "side-loading" do
+    let(:params) { { id: @song.id.to_s, includes: 'albums' } }
+
+    it "includes side-loaded models" do
+      resource[:albums].count.should == 1
+      resource[:albums].first[:id].should == @song.album.id.to_s
+    end
+
+    it "includes the side-loads in the main meta data" do
+      resource[:meta][:songs][:includes].should == [:albums]
+    end
+  end
+
+  describe "missing resource" do
+    let(:params) { { id: "-99" } }
+    it "returns no resource" do
+      resource[:songs].length.should == 0
+    end
+
+    #TODO: add specs for jsonapi error format when it has been standardised
+    # https://github.com/RestPack/restpack_serializer/issues/27
+    # https://github.com/json-api/json-api/issues/7
+  end
+end