active_model_serializers 0.1.0 → 0.5.0

data/{README.textile → DESIGN.textile}

@@ -1,5 +1,4 @@
-"!https://secure.travis-ci.org/josevalim/active_model_serializers.png!":http://travis-ci.org/josevalim/active_model_serializers
-
+<strong>This was the original design document for serializers.</strong> It is useful mostly for historical purposes as the public API has changed.
 
 h2. Rails Serializers
 
@@ -456,7 +455,36 @@ The +association_ids+ helper will use the overridden version of the association,
 this case, +association_ids+ will only include the ids of the comments provided by the
 +comments+ method.
 
-h3. Authorization Scope
+
+h3. Special Association Serializers
+
+So far, associations defined in serializers use either the +as_json+ method on the model
+or the defined serializer for the association type. Sometimes, you may want to serialize
+associated models differently when they are requested as part of another resource than
+when they are requested on their own.
+
+For instance, we might want to provide the full comment when it is requested directly,
+but only its title when requested as part of the post. To achieve this, you can define
+a serializer for associated objects nested inside the main serializer.
+
+<pre lang="ruby">
+class PostSerializer < ActiveModel::Serializer
+  class CommentSerializer < ActiveModel::Serializer
+    attributes :id, :title
+  end
+
+  # same as before
+  # ...
+end
+</pre>
+
+In other words, if a +PostSerializer+ is trying to serialize comments, it will first
+look for +PostSerializer::CommentSerializer+ before falling back to +CommentSerializer+
+and finally +comment.as_json+.
+
+h3. Overriding the Defaults
+
+h4. Authorization Scope
 
 By default, the authorization scope for serializers is +:current_user+. This means
 that when you call +render json: @post+, the controller will automatically call

data/Gemfile

@@ -2,3 +2,6 @@ source 'http://rubygems.org'
 
 # Specify your gem's dependencies in active_model_serializers.gemspec
 gemspec
+
+gem "pry"
+gem "simplecov", :require => false

data/MIT-LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2011-2012 José Valim & Yehuda Katz
+
+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.markdown

@@ -0,0 +1,270 @@
+[![Build Status](https://secure.travis-ci.org/josevalim/active_model_serializers.png)](http://travis-ci.org/josevalim/active_model_serializers)
+
+# Purpose
+
+The purpose of `ActiveModel::Serializers` is to provide an object to
+encapsulate serialization of `ActiveModel` objects, including `ActiveRecord`
+objects.
+
+Serializers know about both a model and the `current_user`, so you can
+customize serialization based upon whether a user is authorized to see the
+content.
+
+In short, **serializers replaces hash-driven development with object-oriented
+development.**
+
+# Installing Serializers
+
+For now, the easiest way to install `ActiveModel::Serializers` is to add this
+to your `Gemfile`:
+
+```ruby
+gem "active_model_serializers", :git => "git://github.com/josevalim/active_model_serializers.git"
+```
+
+Then, install it on the command line:
+
+```
+$ bundle install
+```
+
+# Creating a Serializer
+
+The easiest way to create a new serializer is to generate a new resource, which
+will generate a serializer at the same time:
+
+```
+$ rails g resource post title:string body:string 
+```
+
+This will generate a serializer in `app/serializers/post_serializer.rb` for
+your new model. You can also generate a serializer for an existing model with
+the `serializer generator`:
+
+```
+$ rails g serializer post
+```
+
+# ActiveModel::Serializer
+
+All new serializers descend from ActiveModel::Serializer
+
+# render :json
+
+In your controllers, when you use `render :json`, Rails will now first search
+for a serializer for the object and use it if available.
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+    render :json => @post
+  end
+end
+```
+
+In this case, Rails will look for a serializer named `PostSerializer`, and if
+it exists, use it to serialize the `Post`. 
+
+This also works with `render_with`, which uses `to_json` under the hood. Also
+note that any options passed to `render :json` will be passed to your
+serializer and available as `@options` inside.
+
+## Getting the old version
+
+If you find that your project is already relying on the old rails to_json
+change `render :json` to `render :json => @your_object.to_json`.
+
+# Attributes and Associations
+
+Once you have a serializer, you can specify which attributes and associations
+you would like to include in the serialized form.
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body
+  has_many :comments
+end
+```
+
+## Attributes
+
+For specified attributes, the serializer will look up the attribute on the
+object you passed to `render :json`. It uses
+`read_attribute_for_serialization`, which `ActiveRecord` objects implement as a
+regular attribute lookup.
+
+If you would like the key in the outputted JSON to be different from its name
+in ActiveRecord, you can use the `:key` option to customize it:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :body
+
+  # look up :subject on the model, but use +title+ in the JSON
+  attribute :subject, :key => :title
+  has_many :comments
+end
+```
+
+## Associations
+
+For specified associations, the serializer will look up the association and
+then serialize each element of the association. For instance, a `has_many
+:comments` association will create a new `CommentSerializer` for each comment
+and use it to serialize the comment.
+
+By default, serializers simply look up the association on the original object.
+You can customize this behavior by implementing a method with the name of the
+association and returning a different Array. Often, you will do this to
+customize the objects returned based on the current user.
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body
+  has_many :comments
+
+  # only let the user see comments he created.
+  def comments
+    post.comments.where(:created_by => @scope)
+  end
+end
+```
+
+In a serializer, `@scope` is the current authorization scope (usually
+`current_user`), which the controller gives to the serializer when you call
+`render :json`
+
+As with attributes, you can also change the JSON key that the serializer should
+use for a particular association.
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body
+
+  # look up comments, but use +my_comments+ as the key in JSON
+  has_many :comments, :key => :my_comments
+end
+```
+
+## Embedding Associations
+
+By default, associations will be embedded inside the serialized object. So if
+you have a post, the outputted JSON will look like:
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "New post",
+    "body": "A body!",
+    "comments": [
+      { "id": 1, "body": "what a dumb post" }
+    ]
+  }
+}
+```
+
+This is convenient for simple use-cases, but for more complex clients, it is
+better to supply an Array of IDs for the association. This makes your API more
+flexible from a performance standpoint and avoids wasteful duplication.
+
+To embed IDs instead of associations, simply use the `embed` class method:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  embed :ids
+
+  attributes :id, :title, :body
+  has_many :comments
+end
+```
+
+Now, any associations will be supplied as an Array of IDs:
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "New post",
+    "body": "A body!",
+    "comments": [ 1, 2, 3 ]
+  }
+}
+```
+
+In addition to supplying an Array of IDs, you may want to side-load the data
+alongside the main object. This makes it easier to process the entire package
+of data without having to recursively scan the tree looking for embedded
+information. It also ensures that associations that are shared between several
+objects (like tags), are only delivered once for the entire payload.
+
+You can specify that the data be included like this:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  embed :ids, :include => true
+
+  attributes :id, :title, :body
+  has_many :comments
+end
+```
+
+Assuming that the comments also `has_many :tags`, you will get a JSON like
+this:
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "New post",
+    "body": "A body!",
+    "comments": [ 1 ]
+  },
+  "comments": [
+    { "id": 1, "body": "what a dumb post", "tags": [ 1, 2 ] },
+    { "id": 1, "body": "i liked it", "tags": [ 1, 3 ] },
+  ],
+  "tags": [
+    { "id": 1, "name": "short" },
+    { "id": 2, "name": "whiny" },
+    { "id": 3, "name": "happy" }
+  ]
+}
+```
+
+You can also specify a different root for the embedded objects than the key
+used to reference them:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  embed :ids, :include => true
+
+  attributes :id, :title, :body
+  has_many :comments, :key => :comment_ids, :root => :comment_objects
+end
+```
+
+This would generate JSON that would look like this:
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "New post",
+    "body": "A body!",
+    "comment_ids": [ 1 ]
+  },
+  "comment_objects": [
+    { "id": 1, "body": "what a dumb post" }
+  ]
+}
+```
+
+**NOTE**: The `embed :ids` mechanism is primary useful for clients that process
+data in bulk and load it into a local store. For these clients, the ability to
+easily see all of the data per type, rather than having to recursively scan the
+data looking for information, is extremely useful.
+
+If you are mostly working with the data in simple scenarios and manually making
+Ajax requests, you probably just want to use the default embedded behavior.

data/RELEASE_NOTES.md

@@ -0,0 +1,4 @@
+# VERSION 0.5 (May 16, 2012)
+
+* First tagged version
+* Changes generators to always generate an ApplicationSerializer

data/active_model_serializers.gemspec

@@ -1,4 +1,8 @@
 # -*- encoding: utf-8 -*-
+
+$:.unshift File.expand_path("../lib", __FILE__)
+require "active_model/serializers/version"
+
 Gem::Specification.new do |gem|
   gem.authors       = ["José Valim", "Yehuda Katz"]
   gem.email         = ["jose.valim@gmail.com", "wycats@gmail.com"]
@@ -11,7 +15,7 @@ Gem::Specification.new do |gem|
   gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   gem.name          = "active_model_serializers"
   gem.require_paths = ["lib"]
-  gem.version       = "0.1.0"
+  gem.version       = ActiveModel::Serializer::VERSION
 
   gem.add_dependency 'activemodel', '~> 3.0'
   gem.add_development_dependency "rails", "~> 3.0"

data/lib/action_controller/serialization.rb

@@ -33,12 +33,23 @@ module ActionController
     end
 
     def serialization_scope
-      send(_serialization_scope)
+      send(_serialization_scope) if respond_to?(_serialization_scope)
+    end
+
+    def default_serializer_options
     end
 
     def _render_option_json(json, options)
-      if json.respond_to?(:active_model_serializer) && (serializer = json.active_model_serializer)
-        json = serializer.new(json, serialization_scope, options)
+      if json.respond_to?(:to_ary)
+        options[:root] ||= controller_name
+      end
+
+      serializer = options.delete(:serializer) ||
+        (json.respond_to?(:active_model_serializer) && json.active_model_serializer)
+
+      if serializer
+        options[:scope] = serialization_scope
+        json = serializer.new(json, options.merge(default_serializer_options || {}))
       end
       super
     end

data/lib/active_model/serializer.rb

@@ -1,23 +1,47 @@
 require "active_support/core_ext/class/attribute"
 require "active_support/core_ext/module/anonymous"
+require "set"
 
 module ActiveModel
+  class OrderedSet
+    def initialize(array)
+      @array = array
+      @hash = {}
+
+      array.each do |item|
+        @hash[item] = true
+      end
+    end
+
+    def merge!(other)
+      other.each do |item|
+        next if @hash.key?(item)
+
+        @hash[item] = true
+        @array.push item
+      end
+    end
+
+    def to_a
+      @array
+    end
+  end
+
   # Active Model Array Serializer
   #
   # It serializes an array checking if each element that implements
-  # the +active_model_serializer+ method passing down the current scope.
+  # the +active_model_serializer+ method.
   class ArraySerializer
-    attr_reader :object, :scope
+    attr_reader :object, :options
 
-    def initialize(object, scope, options={})
-      @object, @scope, @options = object, scope, options
-      @hash = options[:hash]
+    def initialize(object, options={})
+      @object, @options = object, options
     end
 
     def serializable_array
       @object.map do |item|
         if item.respond_to?(:active_model_serializer) && (serializer = item.active_model_serializer)
-          serializer.new(item, scope, :hash => @hash)
+          serializer.new(item, @options)
         else
           item
         end
@@ -25,11 +49,13 @@ module ActiveModel
     end
 
     def as_json(*args)
-      @hash = {}
-      array = serializable_array.as_json(*args)
+      @options[:hash] = hash = {}
+      @options[:unique_values] = {}
+
+      array = serializable_array.map(&:serializable_hash)
 
       if root = @options[:root]
-        @hash.merge!(root => array)
+        hash.merge!(root => array)
       else
         array
       end
@@ -40,12 +66,13 @@ module ActiveModel
   #
   # Provides a basic serializer implementation that allows you to easily
   # control how a given object is going to be serialized. On initialization,
-  # it expects to object as arguments, a resource and a scope. For example,
+  # it expects to object as arguments, a resource and options. For example,
   # one may do in a controller:
   #
-  #     PostSerializer.new(@post, current_user).to_json
+  #     PostSerializer.new(@post, :scope => current_user).to_json
   #
-  # The object to be serialized is the +@post+ and the scope is +current_user+.
+  # The object to be serialized is the +@post+ and the current user is passed
+  # in for authorization purposes.
   #
   # We use the scope to check if a given attribute should be serialized or not.
   # For example, some attributes maybe only be returned if +current_user+ is the
@@ -70,22 +97,86 @@ module ActiveModel
   #
   class Serializer
     module Associations #:nodoc:
-      class Config < Struct.new(:name, :options) #:nodoc:
-        def serializer
-          options[:serializer]
+      class Config #:nodoc:
+        class_attribute :options
+
+        def self.refine(name, class_options)
+          current_class = self
+
+          Class.new(self) do
+            singleton_class.class_eval do
+              define_method(:to_s) do
+                "(subclass of #{current_class.name})"
+              end
+
+              alias inspect to_s
+            end
+
+            self.options = class_options
+          end
+        end
+
+        self.options = {}
+
+        def initialize(name, source, options={})
+          @name = name
+          @source = source
+          @options = options
+        end
+
+        def option(key, default=nil)
+          if @options.key?(key)
+            @options[key]
+          elsif self.class.options.key?(key)
+            self.class.options[key]
+          else
+            default
+          end
+        end
+
+        def target_serializer
+          option(:serializer)
+        end
+
+        def source_serializer
+          @source
         end
 
         def key
-          options[:key] || name
+          option(:key) || @name
+        end
+
+        def root
+          option(:root) || plural_key
+        end
+
+        def name
+          option(:name) || @name
+        end
+
+        def associated_object
+          option(:value) || source_serializer.send(name)
+        end
+
+        def embed_ids?
+          option(:embed, source_serializer._embed) == :ids
+        end
+
+        def embed_objects?
+          option(:embed, source_serializer._embed) == :objects
+        end
+
+        def embed_in_root?
+          option(:include, source_serializer._root_embed)
         end
 
-        protected
+      protected
 
-        def find_serializable(object, scope, context, options)
-          if serializer
-            serializer.new(object, scope, options)
+        def find_serializable(object)
+          if target_serializer
+            target_serializer.new(object, source_serializer.options)
           elsif object.respond_to?(:active_model_serializer) && (ams = object.active_model_serializer)
-            ams.new(object, scope, options)
+            ams.new(object, source_serializer.options)
           else
             object
           end
@@ -93,32 +184,47 @@ module ActiveModel
       end
 
       class HasMany < Config #:nodoc:
-        def serialize(collection, scope, context, options)
-          array = collection.map do |item|
-            find_serializable(item, scope, context, options).as_json(:root => false)
+        alias plural_key key
+
+        def serialize
+          associated_object.map do |item|
+            find_serializable(item).serializable_hash
           end
-          { key => array }
         end
+        alias serialize_many serialize
 
-        def serialize_ids(collection, scope)
+        def serialize_ids
           # Use pluck or select_columns if available
           # return collection.ids if collection.respond_to?(:ids)
 
-          array = collection.map do |item|
+          associated_object.map do |item|
             item.read_attribute_for_serialization(:id)
           end
-
-          { key => array }
         end
       end
 
       class HasOne < Config #:nodoc:
-        def serialize(object, scope, context, options)
-          { key => object && find_serializable(object, scope, context, options).as_json(:root => false) }
+        def plural_key
+          key.to_s.pluralize.to_sym
+        end
+
+        def serialize
+          object = associated_object
+          object && find_serializable(object).serializable_hash
         end
 
-        def serialize_ids(object, scope)
-          { key => object && object.read_attribute_for_serialization(:id) }
+        def serialize_many
+          object = associated_object
+          value = object && find_serializable(object).serializable_hash
+          value ? [value] : []
+        end
+
+        def serialize_ids
+          if object = associated_object
+            object.read_attribute_for_serialization(:id)
+          else
+            nil
+          end
         end
       end
     end
@@ -127,7 +233,7 @@ module ActiveModel
     self._attributes = {}
 
     class_attribute :_associations
-    self._associations = []
+    self._associations = {}
 
     class_attribute :_root
     class_attribute :_embed
@@ -150,11 +256,14 @@ module ActiveModel
 
       def associate(klass, attrs) #:nodoc:
         options = attrs.extract_options!
-        self._associations += attrs.map do |attr|
+        self._associations = _associations.dup
+
+        attrs.each do |attr|
           unless method_defined?(attr)
             class_eval "def #{attr}() object.#{attr} end", __FILE__, __LINE__
           end
-          klass.new(attr, options)
+
+          self._associations[attr] = klass.refine(attr, options)
         end
       end
 
@@ -188,7 +297,6 @@ module ActiveModel
       #     { :name => :string, :age => :integer }
       #
       # The +associations+ hash looks like this:
-      #
       #     { :posts => { :has_many => :posts } }
       #
       # If :key is used:
@@ -220,7 +328,9 @@ module ActiveModel
           hash.merge key => column.type
         end
 
-        associations = _associations.inject({}) do |hash, association|
+        associations = _associations.inject({}) do |hash, (attr,association_class)|
+          association = association_class.new(attr, self)
+
           model_association = klass.reflect_on_association(association.name)
           hash.merge association.key => { model_association.macro => model_association.name }
         end
@@ -260,11 +370,10 @@ module ActiveModel
       end
     end
 
-    attr_reader :object, :scope
+    attr_reader :object, :options
 
-    def initialize(object, scope, options={})
-      @object, @scope, @options = object, scope, options
-      @hash = options[:hash]
+    def initialize(object, options={})
+      @object, @options = object, options
     end
 
     # Returns a json representation of the serializable
@@ -272,63 +381,107 @@ module ActiveModel
     def as_json(options=nil)
       options ||= {}
       if root = options.fetch(:root, @options.fetch(:root, _root))
-        @hash = hash = {}
+        @options[:hash] = hash = {}
+        @options[:unique_values] = {}
+
         hash.merge!(root => serializable_hash)
         hash
       else
-        @hash = serializable_hash
+        serializable_hash
       end
     end
 
     # Returns a hash representation of the serializable
     # object without the root.
     def serializable_hash
-      if _embed == :ids
-        merge_associations(@hash, associations) if _root_embed
-        attributes.merge(association_ids)
-      elsif _embed == :objects
-        attributes.merge(associations)
-      else
-        attributes
-      end
+      node = attributes
+      include_associations!(node) if _embed
+      node
     end
 
-    # Merge associations for embed case by always adding
-    # root associations to the given hash.
-    def merge_associations(hash, associations)
-      associations.each do |key, value|
-        if hash[key]
-          hash[key] |= value
-        elsif value
-          hash[key] = value
+    def include_associations!(node)
+      _associations.each do |attr, klass|
+        opts = { :node => node }
+
+        if options.include?(:include) || options.include?(:exclude)
+          opts[:include] = included_association?(attr)
         end
+
+        include! attr, opts
       end
     end
 
-    # Returns a hash representation of the serializable
-    # object associations.
-    def associations
-      hash = {}
-
-      _associations.each do |association|
-        associated_object = send(association.name)
-        hash.merge! association.serialize(associated_object, scope, self, :hash => @hash)
+    def included_association?(name)
+      if options.key?(:include)
+        options[:include].include?(name)
+      elsif options.key?(:exclude)
+        !options[:exclude].include?(name)
+      else
+        true
       end
-
-      hash
     end
 
-    # Returns a hash representation of the serializable
-    # object associations ids.
-    def association_ids
-      hash = {}
+    def include!(name, options={})
+      # Make sure that if a special options[:hash] was passed in, we generate
+      # a new unique values hash and don't clobber the original. If the hash
+      # passed in is the same as the current options hash, use the current
+      # unique values.
+      #
+      # TODO: Should passing in a Hash even be public API here?
+      unique_values =
+        if hash = options[:hash]
+          if @options[:hash] == hash
+            @options[:unique_values] ||= {}
+          else
+            {}
+          end
+        else
+          hash = @options[:hash]
+          @options[:unique_values] ||= {}
+        end
 
-      _associations.each do |association|
-        associated_object = send(association.name)
-        hash.merge! association.serialize_ids(associated_object, scope)
+      node = options[:node]
+      value = options[:value]
+
+      association_class =
+        if klass = _associations[name]
+          klass
+        elsif value.respond_to?(:to_ary)
+          Associations::HasMany
+        else
+          Associations::HasOne
+        end
+
+      association = association_class.new(name, self, options)
+
+      if association.embed_ids?
+        node[association.key] = association.serialize_ids
+
+        if association.embed_in_root?
+          merge_association hash, association.root, association.serialize_many, unique_values
+        end
+      elsif association.embed_objects?
+        node[association.key] = association.serialize
       end
+    end
 
-      hash
+    # In some cases, an Array of associations is built by merging the associated
+    # content for all of the children. For instance, if a Post has_many comments,
+    # which has_many tags, the top-level :tags key will contain the merged list
+    # of all tags for all comments of the post.
+    #
+    # In order to make this efficient, we store a :unique_values hash containing
+    # a unique list of all of the objects that are already in the Array. This
+    # avoids the need to scan through the Array looking for entries every time
+    # we want to merge a new list of values.
+    def merge_association(hash, key, value, unique_values)
+      if current_value = unique_values[key]
+        current_value.merge! value
+        hash[key] = current_value.to_a
+      elsif value
+        hash[key] = value
+        unique_values[key] = OrderedSet.new(value)
+      end
     end
 
     # Returns a hash representation of the serializable