ivy-serializers 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d908e19f0785161aaf56472b179ef00f1e82946d
+  data.tar.gz: cb49a7e6f89ff4d47457da9371f5857421f09683
+SHA512:
+  metadata.gz: 5d798714be3d66d8e57bf66919706b03bae4ff46b1925387a13d65a764e05f4c61cf8fa98cbb4de155ae20e4a07d27fce0e2cabc823b0b668d68af95e417e4c4
+  data.tar.gz: 520e783e3b0c2860f9dd2a1997dfd1fe8bf9df9cc8667b663b0a3a9814c8ed4477e111499ee949378940f04d1626be3e1ca9473fd2199e7d0228a42bf14f6f63

data/.gitignore

@@ -0,0 +1,22 @@
+*.a
+*.bundle
+*.gem
+*.o
+*.rbc
+*.so
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+mkmf.log
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - 2.2
+
+cache: bundler
+
+notifications:
+  email:
+    on_success: change
+    on_failure: always

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Envy Labs, LLC.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,155 @@
+# Ivy::Serializers
+
+[![Build Status](https://travis-ci.org/IvyApp/ivy-serializers.svg?branch=master)](https://travis-ci.org/IvyApp/ivy-serializers)
+
+JSON serialization for client-side apps, with multiple output formats. Ships
+with [ActiveModel::Serializers][ams] and [JSON-API][jsonapi] RC3 support
+out of the box.
+
+[ams]: https://github.com/rails-api/active_model_serializers
+[jsonapi]: http://jsonapi.org/
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ivy-serializers'
+```
+
+And then execute:
+
+```sh
+bundle
+```
+
+Or install it yourself:
+
+```sh
+gem install ivy-serializers
+```
+
+## Usage
+
+### Defining a Serializer
+
+Assuming we have `Post` and `Comment` models:
+
+```ruby
+class Post < ActiveRecord::Base
+  has_many :comments
+end
+
+class Comment < ActiveRecord::Base
+  belongs_to :post
+end
+```
+
+Define a serializer in `app/serializers/serializer.rb`:
+
+```ruby
+class Serializer < Ivy::Serializers::Serializer
+  map Post do
+    attributes :id, :title
+    has_many :comments
+  end
+
+  map Comment do
+    attributes :id, :body
+    belongs_to :post
+  end
+end
+```
+
+Then set up your controllers to use the serializer:
+
+```ruby
+class ApplicationController < ActionController::Base
+  self.serializer = Serializer
+end
+```
+
+Note that you're not limited to a single serializer. If you have multiple
+serialization formats, such as one for admin and one for public-facing, you can
+define alternate serializers in `app/serializers` and use them as well.
+
+### Sideloading
+
+The `#belongs_to` and `#has_many` methods support an optional `:embed_in_root`
+option, which will load the associated record into the root of the payload. For
+instance, if we wanted the list of comments to be included when fetching
+a post, we could define the `has_many` relationship like so:
+
+```ruby
+map Post do
+  has_many :comments, :embed_in_root => true
+end
+```
+
+The same thing also works with `belongs_to`, so if we wanted to ensure the post
+was included when fetching a comment:
+
+```ruby
+map Comment do
+  belongs_to :post, :embed_in_root => true
+end
+```
+
+### Polymorphic Associations
+
+There is also support for polymorphic associations. To use it, pass the
+`:polymorphic => true` option to the `#belongs_to` or `#has_many` methods:
+
+```ruby
+map Post do
+  has_many :replies, :polymorphic => true
+end
+
+map Comment do
+  belongs_to :commentable, :polymorphic => true
+end
+```
+
+### Customizing Attributes
+
+By default, attributes are mapped directly to methods on the record being
+serialized. So defining:
+
+```ruby
+map Post do
+  attributes :id, :title
+end
+```
+
+will read `id` and `title` from the post and write it into the hash under the
+`:id` and `:title` keys. If you want to customize the value, you can use the
+`#attribute` method instead, and pass it a block:
+
+```ruby
+map Post do
+  attribute(:title) { |post| post.headline }
+end
+```
+
+In the above example, we read the `headline` attribute from the post and write
+it into the payload under the `:title` key.
+
+### Alternate Output Formats
+
+By default the ActiveModel::Serializers output format is used. If you'd rather
+use JSON-API (or a custom format), you can do so by setting
+`serialization_format` in your controller. For instance, to use JSON-API:
+
+```ruby
+class ApplicationController < ActionController::Base
+  self.serialization_format = Ivy::Serializers::Formats::JSONAPI
+end
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/ivy-serializers/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+desc 'Default: run specs.'
+task :default => :spec

data/ivy-serializers.gemspec

@@ -0,0 +1,24 @@
+require File.expand_path('../lib/ivy/serializers/version', __FILE__)
+
+Gem::Specification.new do |spec|
+  spec.name = 'ivy-serializers'
+  spec.version = Ivy::Serializers::VERSION
+  spec.authors = ['Dray Lacy']
+  spec.email = ['dray@envylabs.com']
+  spec.summary = 'JSON serialization for client-side apps.'
+  spec.homepage = ''
+  spec.license = 'MIT'
+
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~> 3.2.0'
+  spec.add_development_dependency 'simplecov', '~> 0.10.0'
+
+  spec.add_dependency 'activesupport', '>= 2.2.1'
+  spec.add_dependency 'hash_generator', '~> 1.1'
+end

data/lib/ivy-serializers.rb

@@ -0,0 +1 @@
+require 'ivy/serializers'

data/lib/ivy/serializers.rb

@@ -0,0 +1,5 @@
+require 'ivy/serializers/documents'
+require 'ivy/serializers/formats'
+require 'ivy/serializers/serializer'
+require 'ivy/serializers/version'
+require 'ivy/serializers/railtie' if defined?(::Rails)

data/lib/ivy/serializers/action_controller/serialization_support.rb

@@ -0,0 +1,35 @@
+module Ivy
+  module Serializers
+    module ActionController
+      module SerializationSupport
+        extend ActiveSupport::Concern
+
+        class SerializerNotFound < ::StandardError
+        end
+
+        included do
+          class_attribute :serializer, :instance_writer => false
+          class_attribute :serialization_format, :instance_writer => false
+          self.serialization_format = Formats::ActiveModelSerializers
+        end
+
+        private
+
+        %w[ _render_option_json _render_with_renderer_json ].each do |renderer_method|
+          define_method(renderer_method) do |resource, options|
+            unless serializer
+              raise SerializerNotFound, "No serializer found in #{self.class.name}"
+            end
+
+            unless resource.kind_of?(::Hash)
+              resource = Documents.create(serializer, controller_name, resource)
+              resource = serialization_format.new(resource)
+            end
+
+            super(resource, options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ivy/serializers/attribute.rb

@@ -0,0 +1,24 @@
+module Ivy
+  module Serializers
+    class Attribute
+      def initialize(name, &getter)
+        @name = name
+        @getter = getter || method(:default_getter)
+      end
+
+      def generate(generator, resource)
+        generator.attribute(@name, get(resource))
+      end
+
+      private
+
+      def default_getter(resource)
+        resource.public_send(@name)
+      end
+
+      def get(resource)
+        @getter.call(resource)
+      end
+    end
+  end
+end

data/lib/ivy/serializers/documents.rb

@@ -0,0 +1,17 @@
+require 'ivy/serializers/documents/individual_resource'
+require 'ivy/serializers/documents/resource_collection'
+
+module Ivy
+  module Serializers
+    module Documents
+      def self.create(serializer, primary_resource_name, primary_resource)
+        klass = document_class_for(primary_resource)
+        klass.new(serializer, primary_resource_name, primary_resource)
+      end
+
+      def self.document_class_for(resource)
+        resource.respond_to?(:to_ary) ? ResourceCollection : IndividualResource
+      end
+    end
+  end
+end

data/lib/ivy/serializers/documents/document.rb

@@ -0,0 +1,55 @@
+require 'set'
+
+module Ivy
+  module Serializers
+    module Documents
+      class Document
+        def initialize(serializer, primary_resource_name, primary_resource)
+          @serializer = serializer
+          @primary_resource_name = primary_resource_name
+          @primary_resource = primary_resource
+          @linked_resources = Hash.new { |hash, klass| hash[klass] = Set.new }
+        end
+
+        def belongs_to(name, resource, options={})
+          link(resource) if options[:embed_in_root]
+        end
+
+        def generate(generator)
+          generator.document(self)
+        end
+
+        def generate_linked(generator)
+          generator.linked(self) unless @linked_resources.empty?
+        end
+
+        def generate_linked_resources(generator)
+          @linked_resources.each_pair { |klass, resources| generator.linked_resources(klass, resources) }
+        end
+
+        def generate_links(generator, resource)
+          @serializer.links(generator, resource)
+        end
+
+        def generate_resource(generator, resource)
+          @serializer.resource(generator, resource)
+          generator.links(resource)
+        end
+
+        def has_many(name, resources, options={})
+          link_many(resources) if options[:embed_in_root]
+        end
+
+        private
+
+        def link(resource)
+          @serializer.links(self, resource) if @linked_resources[resource.class].add?(resource)
+        end
+
+        def link_many(resources)
+          resources.each { |resource| link(resource) }
+        end
+      end
+    end
+  end
+end

data/lib/ivy/serializers/documents/individual_resource.rb

@@ -0,0 +1,18 @@
+require 'ivy/serializers/documents/document'
+
+module Ivy
+  module Serializers
+    module Documents
+      class IndividualResource < Document
+        def generate_linked(generator)
+          @serializer.links(self, @primary_resource)
+          super
+        end
+
+        def generate_primary_resource(generator)
+          generator.primary_resource(@primary_resource_name, @primary_resource)
+        end
+      end
+    end
+  end
+end

data/lib/ivy/serializers/documents/resource_collection.rb

@@ -0,0 +1,18 @@
+require 'ivy/serializers/documents/document'
+
+module Ivy
+  module Serializers
+    module Documents
+      class ResourceCollection < Document
+        def generate_linked(generator)
+          @primary_resource.each { |resource| @serializer.links(self, resource) }
+          super
+        end
+
+        def generate_primary_resource(generator)
+          generator.primary_resources(@primary_resource_name, @primary_resource)
+        end
+      end
+    end
+  end
+end