active_model_serializers 0.8.3 → 0.10.0.rc4

data/Rakefile

@@ -1,18 +1,75 @@
-#!/usr/bin/env rake
-require "bundler/gem_tasks"
-require "rake/testtask"
+begin
+  require 'simplecov'
+rescue LoadError
+end
+
+require 'bundler/gem_tasks'
+
+begin
+  require 'rubocop'
+  require 'rubocop/rake_task'
+rescue LoadError
+else
+  Rake::Task[:rubocop].clear if Rake::Task.task_defined?(:rubocop)
+  require 'rbconfig'
+  # https://github.com/bundler/bundler/blob/1b3eb2465a/lib/bundler/constants.rb#L2
+  windows_platforms = /(msdos|mswin|djgpp|mingw)/
+  if RbConfig::CONFIG['host_os'] =~ windows_platforms
+    desc 'No-op rubocop on Windows-- unsupported platform'
+    task :rubocop do
+      puts 'Skipping rubocop on Windows'
+    end
+  elsif defined?(::Rubinius)
+    desc 'No-op rubocop to avoid rbx segfault'
+    task :rubocop do
+      puts 'Skipping rubocop on rbx due to segfault'
+      puts 'https://github.com/rubinius/rubinius/issues/3499'
+    end
+  else
+    Rake::Task[:rubocop].clear if Rake::Task.task_defined?(:rubocop)
+    desc 'Execute rubocop'
+    RuboCop::RakeTask.new(:rubocop) do |task|
+      task.options = ['--rails', '--display-cop-names', '--display-style-guide']
+      task.fail_on_error = true
+    end
+  end
+end
 
-desc 'Run tests'
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
   t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.ruby_opts = ['-r./test/test_helper.rb']
   t.verbose = true
 end
 
-desc 'Benchmark'
-task :bench do
-  load 'bench/perf.rb' 
+desc 'Run isolated tests'
+task isolated: ['test:isolated:railtie']
+namespace :test do
+  namespace :isolated do
+    desc 'Run isolated tests for Railtie'
+    task :railtie do
+      dir = File.dirname(__FILE__)
+      file = "#{dir}/test/active_model_serializers/railtie_test_isolated.rb"
+
+      # https://github.com/rails/rails/blob/3d590add45/railties/lib/rails/generators/app_base.rb#L345-L363
+      _bundle_command = Gem.bin_path('bundler', 'bundle')
+      require 'bundler'
+      Bundler.with_clean_env do
+        command = "-w -I#{dir}/lib -I#{dir}/test #{file}"
+        full_command = %("#{Gem.ruby}" #{command})
+        system(full_command) or fail 'Failures' # rubocop:disable Style/AndOr
+      end
+    end
+  end
+end
+
+if ENV['RAILS_VERSION'].to_s > '4.0' && RUBY_ENGINE == 'ruby'
+  task default: [:isolated, :test, :rubocop]
+else
+  task default: [:test, :rubocop]
 end
 
-task :default => :test
+desc 'CI test task'
+task :ci => [:default]

data/active_model_serializers.gemspec

@@ -1,24 +1,58 @@
-# -*- 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"]
-  gem.description   = %q{Making it easy to serialize models for client-side use}
-  gem.summary       = %q{Bringing consistency and object orientation to model serialization. Works great for client-side MVC frameworks!}
-  gem.homepage      = "https://github.com/rails-api/active_model_serializers"
-
-  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  gem.files         = `git ls-files`.split("\n")
-  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  gem.name          = "active_model_serializers"
-  gem.require_paths = ["lib"]
-  gem.version       = ActiveModel::Serializer::VERSION
-
-  gem.add_dependency 'activemodel', '>= 3.0'
-  gem.add_development_dependency "rails", ">= 3.0"
-  gem.add_development_dependency "pry"
-  gem.add_development_dependency "minitest"
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'active_model/serializer/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'active_model_serializers'
+  spec.version       = ActiveModel::Serializer::VERSION
+  spec.platform      = Gem::Platform::RUBY
+  spec.authors       = ['Steve Klabnik']
+  spec.email         = ['steve@steveklabnik.com']
+  spec.summary       = 'Conventions-based JSON generation for Rails.'
+  spec.description   = 'ActiveModel::Serializers allows you to generate your JSON in an object-oriented and convention-driven manner.'
+  spec.homepage      = 'https://github.com/rails-api/active_model_serializers'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.0.0'
+
+  rails_versions = '>= 4.0'
+  spec.add_runtime_dependency 'activemodel', rails_versions
+    # 'activesupport', rails_versions
+    # 'builder'
+
+  spec.add_runtime_dependency 'actionpack', rails_versions
+    # 'activesupport', rails_versions
+    # 'rack'
+    # 'rack-test', '~> 0.6.2'
+
+  spec.add_runtime_dependency 'railties', rails_versions
+    # 'activesupport', rails_versions
+    # 'actionpack', rails_versions
+    # 'rake', '>= 0.8.7'
+
+  # 'activesupport', rails_versions
+    # 'i18n,
+    # 'tzinfo'
+    # 'minitest'
+    # 'thread_safe'
+
+  spec.add_development_dependency 'activerecord', rails_versions
+    # arel
+    # activesupport
+    # activemodel
+
+  # Soft dependency for pagination
+  spec.add_development_dependency 'kaminari', ' ~> 0.16.3'
+  spec.add_development_dependency 'will_paginate', '~> 3.0', '>= 3.0.7'
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'timecop', '~> 0.7'
+  spec.add_development_dependency 'minitest-reporters'
+  spec.add_development_dependency 'grape', ['>= 0.13', '< 1.0']
+  spec.add_development_dependency 'json_schema'
 end

data/appveyor.yml

@@ -0,0 +1,27 @@
+version: '{build}'
+
+skip_tags: true
+
+environment:
+  matrix:
+    - ruby_version: "200"
+    - ruby_version: "200-x64"
+    - ruby_version: "21"
+    - ruby_version: "21-x64"
+
+cache:
+  - vendor/bundle
+
+install:
+  - SET PATH=C:\Ruby%ruby_version%\bin;%PATH%
+  - ruby --version
+  - gem --version
+  - gem install bundler
+  - bundler --version
+  - bundle platform
+  - bundle install --path=vendor/bundle --retry=3 --jobs=3
+
+test_script:
+  - bundle exec rake ci
+
+build: off

data/docs/ARCHITECTURE.md

@@ -0,0 +1,120 @@
+[Back to Guides](README.md)
+
+# ARCHITECTURE
+
+An **`ActiveModel::Serializer`** wraps a [serializable resource](https://github.com/rails/rails/blob/4-2-stable/activemodel/lib/active_model/serialization.rb)
+and exposes an `attributes` method, among a few others.
+It allows you to specify which attributes and associations should be represented in the serializatation of the resource.
+It requires an adapter to transform its attributes into a JSON document; it cannot be serialized itself.
+It may be useful to think of it as a
+[presenter](http://blog.steveklabnik.com/posts/2011-09-09-better-ruby-presenters).
+
+The **`ActiveModel::ArraySerializer`** represent a collection of resources as serializers
+and, if there is no serializer, primitives.
+
+The **`ActiveModel::Adapter`** describes the structure of the JSON document generated from a
+serializer. For example, the `Attributes` example represents each serializer as its
+unmodified attributes.  The `JsonApi` adapter represents the serializer as a [JSON
+API](http://jsonapi.org/) document.
+
+The **`ActiveModel::SerializableResource`** acts to coordinate the serializer(s) and adapter
+to an object that responds to `to_json`, and `as_json`.  It is used in the controller to
+encapsulate the serialization resource when rendered. However, it can also be used on its own
+to serialize a resource outside of a controller, as well.
+
+## Primitive handling
+
+Definitions: A primitive is usually a String or Array. There is no serializer
+defined for them; they will be serialized when the resource is converted to JSON (`as_json` or
+`to_json`).  (The below also applies for any object with no serializer.)
+
+ActiveModelSerializers doesn't handle primitives passed to `render json:` at all.
+
+However, when a primitive value is an attribute or in a collection,
+it is not modified.
+
+Internally, if no serializer can be found in the controller, the resource is not decorated by
+ActiveModelSerializers.
+
+If the collection serializer (ArraySerializer) cannot
+identify a serializer for a resource in its collection, it raises [`NoSerializerError`](https://github.com/rails-api/active_model_serializers/issues/1191#issuecomment-142327128)
+which is rescued in `AcitveModel::Serializer::Reflection#build_association` which sets
+the association value directly:
+
+```ruby
+reflection_options[:virtual_value] = association_value.try(:as_json) || association_value
+```
+
+(which is called by the adapter as `serializer.associations(*)`.)
+
+## How options are parsed
+
+High-level overview:
+
+- For a collection
+  - `:serializer` specifies the collection serializer and
+  - `:each_serializer` specifies the serializer for each resource in the collection.
+- For a single resource, the `:serializer` option is the resource serializer.
+- Options are partitioned in serializer options and adapter options.  Keys for adapter options are specified by
+    [`ADAPTER_OPTIONS`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializable_resource.rb#L4).
+    The remaining options are serializer options.
+
+Details:
+
+1. **ActionController::Serialization**
+  1. `serializable_resource = ActiveModel::SerializableResource.new(resource, options)`
+    1. `options` are partitioned into `adapter_opts` and everything else (`serializer_opts`).
+      The adapter options keys for the are defined by `ADAPTER_OPTIONS`.
+1. **ActiveModel::SerializableResource**
+  1. `if serializable_resource.serializer?` (there is a serializer for the resource, and an adapter is used.)
+    - Where `serializer?` is `use_adapter? && !!(serializer)`
+      - Where `use_adapter?`: 'True when no explicit adapter given, or explicit value is truthy (non-nil);
+        False when explicit adapter is falsy (nil or false)'
+      - Where `serializer`:
+        1. from explicit `:serializer` option, else
+        2. implicitly from resource `ActiveModel::Serializer.serializer_for(resource)`
+  1. A side-effect of checking `serializer` is:
+     - The `:serializer` option is removed from the serializer_opts hash
+     - If the `:each_serializer` option is present, it is removed from the serializer_opts hash and set as the `:serializer` option
+  1. The serializer and adapter are created as
+    1. `serializer_instance = serializer.new(resource, serializer_opts)`
+    2. `adapter_instance = ActiveModel::Serializer::Adapter.create(serializer_instance, adapter_opts)`
+1. **ActiveModel::Serializer::ArraySerializer#new**
+  1. If the `serializer_instance` was a `ArraySerializer` and the `:serializer` serializer_opts
+    is present, then [that serializer is passed into each resource](https://github.com/rails-api/active_model_serializers/blob/a54d237e2828fe6bab1ea5dfe6360d4ecc8214cd/lib/active_model/serializer/array_serializer.rb#L14-L16).
+1. **ActiveModel::Serializer#attributes** is used by the adapter to get the attributes for
+  resource as defined by the serializer.
+
+## What does a 'serializable resource' look like?
+
+- An `ActiveRecord::Base` object.
+- Any Ruby object at passes or otherwise passes the
+  [Lint](http://www.rubydoc.info/github/rails-api/active_model_serializers/ActiveModel/Serializer/Lint/Tests)
+  [code](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer/lint.rb).
+
+ActiveModelSerializers provides a
+[`ActiveModelSerializers::Model`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/model.rb),
+which is a simple serializable PORO (Plain-Old Ruby Object).
+
+ActiveModelSerializers::Model may be used either as a template, or in production code.
+
+```ruby
+class MyModel < ActiveModelSerializers::Model
+  attr_accessor :id, :name, :level
+end
+```
+
+The default serializer for `MyModel` would be `MyModelSerializer` whether MyModel is an
+ActiveRecord::Base object or not.
+
+Outside of the controller the rules are **exactly** the same as for records. For example:
+
+```ruby
+render json: MyModel.new(level: 'awesome'), adapter: :json
+```
+
+would be serialized the same as
+
+```ruby
+ActiveModel::SerializableResource.new(MyModel.new(level: 'awesome'), adapter: :json).as_json
+```

data/docs/DESIGN.textile

@@ -0,0 +1 @@
+<strong>This was the original design document for serializers.</strong> It is useful mostly for historical purposes as the public API has changed.
  def initialize(post, scope)
    @post, @scope = post, scope
  end
  def as_json
    { post: { title: @post.name, body: @post.body } }
  end
  def show
    @post = Post.find(params[:id])
    render json: @post
  end
  def initialize(post, scope)
    @post, @scope = post, scope
  end
  def serializable_hash
    { title: @post.name, body: @post.body }
  end
  def as_json
    { post: serializable_hash }
  end
  def initialize(post, scope)
    @post, @scope = post, scope
  end
  def as_json
    { post: serializable_hash }
  end
  def serializable_hash
    hash = post
    hash.merge!(super_data) if super?
    hash
  end
  def post
    { title: @post.name, body: @post.body }
  end
  def super_data
    { email: @post.email }
  end
  def super?
    @scope.superuser?
  end
  # For now, we use a very simple authorization structure. These tests will need
  # refactoring if we change that.
  plebe = OpenStruct.new(super?: false)
  god   = OpenStruct.new(super?: true)
  post  = OpenStruct.new(title: "Welcome to my blog!", body: "Blah blah blah", email: "tenderlove@gmail.com")
  test "a regular user sees just the title and body" do
    json = PostSerializer.new(post, plebe).to_json
    hash = JSON.parse(json)
    assert_equal post.title, hash.delete("title")
    assert_equal post.body, hash.delete("body")
    assert_empty hash
  end
  test "a superuser sees the title, body and email" do
    json = PostSerializer.new(post, god).to_json
    hash = JSON.parse(json)
    assert_equal post.title, hash.delete("title")
    assert_equal post.body, hash.delete("body")
    assert_equal post.email, hash.delete("email")
    assert_empty hash
  end
  # @param [~body, ~title, ~email] post the post to serialize
  # @param [~super] scope the authorization scope for this serializer
  def initialize(post, scope)
    @post, @scope = post, scope
  end
  # ...
+ActiveModel::Serializer+ to simplify our post serializer.
  attributes :title, :body
  def serializable_hash
    hash = attributes
    hash.merge!(super_data) if super?
    hash
  end
  def super_data
    { email: @post.email }
  end
  def super?
    @scope.superuser?
  end
+attributes+ that extracts those attributes from the post model.
  attributes :title, :body
  def attributes
    hash = super
    hash.merge!(email: post.email) if super?
    hash
  end
  def super?
    @scope.superuser?
  end
+attributes+. We can call +super+ to get the hash based on the attributes we declared, and then add in any additional
  attributes :title, :body
  has_many :comments
  def attributes
    hash = super
    hash.merge!(email: post.email) if super?
    hash
  end
  def super?
    @scope.superuser?
  end
  post: {
    title: "Hello Blog!",
    body: "This is my first post. Isn't it fabulous!",
    comments: [
      {
        title: "Awesome",
        body: "Your first post is great"
      }
    ]
  }
  def initialize(comment, scope)
    @comment, @scope = comment, scope
  end
  def serializable_hash
    { title: @comment.title }
  end
  def as_json
    { comment: serializable_hash }
  end
  post: {
    title: "Hello Blog!",
    body: "This is my first post. Isn't it fabulous!",
    comments: [{ title: "Awesome" }]
  }
+comments+ accessor on the post object. We can override the +comments+ accessor to limit the comments used
  attributes :title. :body
  has_many :comments
  def attributes
    hash = super
    hash.merge!(email: post.email) if super?
    hash
  end
  def comments
    post.comments_for(scope)
  end
  def super?
    @scope.superuser?
  end
+ActiveModel::Serializer+ will still embed the comments, but this time it will use just the comments
  has_many :followed_posts, :key => :posts
  has_one :owned_account, :key => :account
  has_many :followed_posts, :key => :posts, :serializer => CustomPostSerializer
  has_one :owne_account, :key => :account, :serializer => PrivateAccountSerializer
  post: {
    id: 1
    title: "Hello Blog!",
    body: "This is my first post. Isn't it fabulous!",
    comments: [1,2]
  },
  comments: [
    {
      id: 1
      title: "Awesome",
      body: "Your first post is great"
    },
    {
      id: 2
      title: "Not so awesome",
      body: "Why is it so short!"
    }
  ]
  attributes :id, :title, :body
  # define any logic for dealing with authorization-based attributes here
  attributes :title, :body
  has_many :comments
  def as_json
    { post: serializable_hash }.merge!(associations)
  end
  def serializable_hash
    post_hash = attributes
    post_hash.merge!(association_ids)
    post_hash
  end
  def attributes
    hash = super
    hash.merge!(email: post.email) if super?
    hash
  end
  def comments
    post.comments_for(scope)
  end
  def super?
    @scope.superuser?
  end
+associations+, creates a hash of all of the define associations, using their defined
+comments+ method.
  class CommentSerializer < ActiveModel::Serializer
    attributes :id, :title
  end
  # same as before
  # ...
  serialization_scope :current_app
  posts: [
    {
      title: "FIRST POST!",
      body: "It's my first pooooost"
    },
    { title: "Second post!",
      body: "Zomg I made it to my second post"
    }
  ]
  def serializable_array
    serializers.map do |serializer|
      serializer.serializable_hash
    end
  end
  def as_json
    hash = { root => serializable_array }
    hash.merge!(associations)
    hash
  end

data/docs/README.md

@@ -0,0 +1,35 @@
+# Docs - ActiveModel::Serializer 0.10.x
+
+This is the documentation of ActiveModelSerializers, it's focused on the **0.10.x version.**
+
+-----
+
+## General
+
+- [Getting Started](general/getting_started.md)
+- [Configuration Options](general/configuration_options.md)
+- [Serializers](general/serializers.md)
+- [Adapters](general/adapters.md)
+- [Rendering](general/rendering.md)
+- [Caching](general/caching.md)
+- [Logging](general/logging.md)
+- [Instrumentation](general/instrumentation.md)
+- [JSON API Schema](jsonapi/schema.md)
+- [ARCHITECTURE](ARCHITECTURE.md)
+
+## How to
+
+- [How to add root key](howto/add_root_key.md)
+- [How to add pagination links](howto/add_pagination_links.md)
+- [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
+- [Testing ActiveModelSerializers](howto/test.md)
+
+## Integrations
+
+| Integration | Supported ActiveModelSerializers versions |  Gem name and/or link
+|----|-----|----
+| Ember.js | 0.9.x | [active-model-adapter](https://github.com/ember-data/active-model-adapter)
+| Ember.js | 0.10.x + |  [docs/integrations/ember-and-json-api.md](integrations/ember-and-json-api.md)
+| Grape | 0.10.x + | [docs/integrations/grape.md](integrations/grape.md)  |
+| Grape | 0.9.x | https://github.com/jrhe/grape-active_model_serializers/ |
+| Sinatra | 0.9.x | https://github.com/SauloSilva/sinatra-active-model-serializers/