active_model_serializers 0.10.0 → 0.10.7

data/README.md

@@ -24,17 +24,6 @@
   </tr>
 </table>
 
-
-## Documentation
-
-- [0.10 (master) Documentation](https://github.com/rails-api/active_model_serializers/tree/master)
-  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/v0.10.0)
-  - [Guides](docs)
-- [0.9 (0-9-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-9-stable)
-  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/0-9-stable)
-- [0.8 (0-8-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-8-stable)
-  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/0-8-stable)
-
 ## About
 
 ActiveModelSerializers brings convention over configuration to your JSON generation.
@@ -50,33 +39,22 @@ resource serialization. The serialization has the `#as_json`, `#to_json` and `#s
 methods used by the Rails JSON Renderer. (SerializableResource actually delegates
 these methods to the adapter.)
 
-By default ActiveModelSerializers will use the **Attributes Adapter**.
+By default ActiveModelSerializers will use the **Attributes Adapter** (no JSON root).
 But we strongly advise you to use **JsonApi Adapter**, which
 follows 1.0 of the format specified in [jsonapi.org/format](http://jsonapi.org/format).
 Check how to change the adapter in the sections below.
 
-## RELEASE CANDIDATE, PLEASE READ
-
-This is the **master** branch of ActiveModelSerializers.
-
-It will become the `0.10.0` release when it's ready. Currently this is a release candidate.
-
 `0.10.x` is **not** backward compatible with `0.9.x` nor `0.8.x`.
 
-`0.10.x` will be based on the `0.8.0` code, but with a more flexible
+`0.10.x` is based on the `0.8.0` code, but with a more flexible
 architecture. We'd love your help. [Learn how you can help here.](CONTRIBUTING.md)
 
-It is generally safe and recommended to use the master branch.
-
-For more information, see the post '[The future of
-AMS](https://medium.com/@joaomdmoura/the-future-of-ams-e5f9047ca7e9)'.
-
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```
-gem 'active_model_serializers'
+gem 'active_model_serializers', '~> 0.10.0'
 ```
 
 And then execute:
@@ -103,8 +81,30 @@ If you'd like to chat, we have a [community slack](http://amserializers.herokuap
 
 Thanks!
 
+## Documentation
+
+If you're reading this at https://github.com/rails-api/active_model_serializers you are
+reading documentation for our `master`, which may include features that have not
+been released yet. Please see below for the documentation relevant to you.
+
+- [0.10 (master) Documentation](https://github.com/rails-api/active_model_serializers/tree/master)
+- [0.10.6 (latest release) Documentation](https://github.com/rails-api/active_model_serializers/tree/v0.10.6)
+  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/active_model_serializers/0.10.6)
+  - [Guides](docs)
+- [0.9 (0-9-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-9-stable)
+  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/0-9-stable)
+- [0.8 (0-8-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-8-stable)
+  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/0-8-stable)
+
+
 ## High-level behavior
 
+Choose an adapter from [adapters](lib/active_model_serializers/adapter):
+
+``` ruby
+ActiveModelSerializers.config.adapter = :json_api # Default: `:attributes`
+```
+
 Given a [serializable model](lib/active_model/serializer/lint.rb):
 
 ```ruby
@@ -114,7 +114,7 @@ class SomeResource < ActiveRecord::Base
 end
 # or
 class SomeResource < ActiveModelSerializers::Model
-  attr_accessor :title, :body
+  attributes :title, :body
 end
 ```
 
@@ -160,8 +160,146 @@ serializer = SomeSerializer.new(resource, serializer_options)
 serializer.attributes
 serializer.associations
 ```
-See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for more information.
 
-# Contributing
+## Architecture
+
+This section focuses on architecture the 0.10.x version of ActiveModelSerializers. If you are interested in the architecture of the 0.8 or 0.9 versions,
+please refer to the [0.8 README](https://github.com/rails-api/active_model_serializers/blob/0-8-stable/README.md) or
+[0.9 README](https://github.com/rails-api/active_model_serializers/blob/0-9-stable/README.md).
+
+The original design is also available [here](https://github.com/rails-api/active_model_serializers/blob/d72b66d4c5355b0ff0a75a04895fcc4ea5b0c65e/README.textile).
+
+### ActiveModel::Serializer
+
+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).
+
+#### ActiveModel::CollectionSerializer
+
+The **`ActiveModel::CollectionSerializer`** represents a collection of resources as serializers
+and, if there is no serializer, primitives.
+
+### ActiveModelSerializers::Adapter::Base
+
+The **`ActiveModelSerializers::Adapter::Base`** 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.
+
+### ActiveModelSerializers::SerializableResource
+
+The **`ActiveModelSerializers::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.
+
+Internally, if no serializer can be found in the controller, the resource is not decorated by
+ActiveModelSerializers.
+
+- However, when a primitive value is an attribute or in a collection, it is not modified.
+
+When serializing a collection and the collection serializer (CollectionSerializer) cannot
+identify a serializer for a resource in its collection, it throws [`:no_serializer`](https://github.com/rails-api/active_model_serializers/issues/1191#issuecomment-142327128).
+For example, when caught by `Reflection#build_association`, and the association value is set 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_OPTION_KEYS`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/serializable_resource.rb#L5).
+    The remaining options are serializer options.
+
+Details:
+
+1. **ActionController::Serialization**
+  1. `serializable_resource = ActiveModelSerializers::SerializableResource.new(resource, options)`
+    1. `options` are partitioned into `adapter_opts` and everything else (`serializer_opts`).
+      The `adapter_opts` keys are defined in [`ActiveModelSerializers::SerializableResource::ADAPTER_OPTION_KEYS`](lib/active_model_serializers/serializable_resource.rb#L5).
+1. **ActiveModelSerializers::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::CollectionSerializer#new**
+  1. If the `serializer_instance` was a `CollectionSerializer` 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.
+
+(In Rails, the `options` are also passed to the `as_json(options)` or `to_json(options)`
+methods on the resource serialization by the Rails JSON renderer.  They are, therefore, important
+to know about, but not part of ActiveModelSerializers.)
+
+### What does a 'serializable resource' look like?
+
+- An `ActiveRecord::Base` object.
+- Any Ruby object that 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 reference implementation, or in production code.
+
+```ruby
+class MyModel < ActiveModelSerializers::Model
+  attributes :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
+ActiveModelSerializers::SerializableResource.new(MyModel.new(level: 'awesome'), adapter: :json).as_json
+```
+
+## Semantic Versioning
+
+This project adheres to [semver](http://semver.org/)
+
+## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)

data/Rakefile

@@ -5,8 +5,9 @@ rescue LoadError
 end
 begin
   require 'simplecov'
-rescue LoadError
+rescue LoadError # rubocop:disable Lint/HandleExceptions
 end
+import('lib/tasks/rubocop.rake')
 
 Bundler::GemHelper.install_tasks
 
@@ -30,36 +31,6 @@ namespace :yard do
   end
 end
 
-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
-
 require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
@@ -100,4 +71,4 @@ else
 end
 
 desc 'CI test task'
-task :ci => [:default]
+task ci: [:default]

data/active_model_serializers.gemspec

@@ -19,33 +19,36 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
   spec.executables   = []
 
-  spec.required_ruby_version = '>= 2.0.0'
+  spec.required_ruby_version = '>= 2.1'
 
-  rails_versions = '>= 4.0'
+  rails_versions = ['>= 4.1', '< 6']
   spec.add_runtime_dependency 'activemodel', rails_versions
-    # 'activesupport', rails_versions
-    # 'builder'
+  # 'activesupport', rails_versions
+  # 'builder'
 
   spec.add_runtime_dependency 'actionpack', rails_versions
-    # 'activesupport', rails_versions
-    # 'rack'
-    # 'rack-test', '~> 0.6.2'
+  # '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'
+  spec.add_development_dependency 'railties', rails_versions
+  # 'activesupport', rails_versions
+  # 'actionpack', rails_versions
+  # 'rake', '>= 0.8.7'
 
   # 'activesupport', rails_versions
-    # 'i18n,
-    # 'tzinfo'
-    # 'minitest'
-    # 'thread_safe'
+  # 'i18n,
+  # 'tzinfo'
+  # 'minitest'
+  # 'thread_safe'
+
+  spec.add_runtime_dependency 'jsonapi-renderer', ['>= 0.1.1.beta1', '< 0.3']
+  spec.add_runtime_dependency 'case_transform', '>= 0.2'
 
   spec.add_development_dependency 'activerecord', rails_versions
-    # arel
-    # activesupport
-    # activemodel
+  # arel
+  # activesupport
+  # activemodel
 
   # Soft dependency for pagination
   spec.add_development_dependency 'kaminari', ' ~> 0.16.3'
@@ -54,13 +57,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.6'
   spec.add_development_dependency 'simplecov', '~> 0.11'
   spec.add_development_dependency 'timecop', '~> 0.7'
-  spec.add_development_dependency 'grape', ['>= 0.13', '< 1.0']
+  spec.add_development_dependency 'grape', ['>= 0.13', '< 0.19.1']
   spec.add_development_dependency 'json_schema'
   spec.add_development_dependency 'rake', ['>= 10.0', '< 12.0']
-
-  spec.post_install_message = <<-EOF
-NOTE: The default key case for the JsonApi adapter has changed to dashed.
-See https://github.com/rails-api/active_model_serializers/blob/master/docs/general/key_transforms.md
-for more information on configuring this behavior.
-EOF
 end

data/appveyor.yml

@@ -1,22 +1,26 @@
-version: '{build}'
+version: 1.0.{build}-{branch}
 
 skip_tags: true
 
 environment:
   JRUBY_OPTS: "--dev -J-Xmx1024M --debug"
   matrix:
-    - ruby_version: "Ruby21"
-    - ruby_version: "Ruby21-x64"
-    - ruby_version: "jruby-9.0.0.0"
+    - ruby_version: "Ruby23"
+    - ruby_version: "Ruby23-x64"
 
 cache:
   - vendor/bundle
 
 install:
   - SET PATH=C:\%ruby_version%\bin;%PATH%
-  - gem install bundler
   - bundle env
-  - bundle install --path=vendor/bundle --retry=3 --jobs=3
+  - bundle check || bundle install --path=vendor/bundle --retry=3 --jobs=3
+  - bundle clean --force
+
+before_test:
+  - ruby -v
+  - gem -v
+  - bundle -v
 
 test_script:
   - bundle exec rake ci

data/bin/rubocop

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+#
+# Usage:
+#   bin/rubocop [-A|-t|-h]
+#   bin/rubocop [file or path] [cli options]
+#
+# Options:
+#  Autocorrect    -A
+#  AutoGenConfig  -t
+#  Usage          -h,--help,help
+
+set -e
+
+case $1 in
+  -A)
+     echo "Rubocop autocorrect is ON" >&2
+     bundle exec rake -f lib/tasks/rubocop.rake rubocop:auto_correct
+     ;;
+
+  -t)
+     echo "Rubocop is generating a new TODO" >&2
+     bundle exec rake -f lib/tasks/rubocop.rake rubocop:auto_gen_config
+     ;;
+
+  -h|--help|help)
+     sed -ne '/^#/!q;s/.\{1,2\}//;1d;p' < "$0"
+     ;;
+
+  *)
+     # with no args, run vanilla rubocop
+     # else assume we're passing in arbitrary arguments
+     if [ -z "$1" ]; then
+       bundle exec rake -f lib/tasks/rubocop.rake rubocop
+     else
+       bundle exec rubocop "$@"
+     fi
+     ;;
+esac

data/docs/README.md

@@ -18,16 +18,17 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - JSON API
   - [Schema](jsonapi/schema.md)
   - [Errors](jsonapi/errors.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)
+- [How to add relationship links](howto/add_relationship_links.md)
 - [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
 - [Testing ActiveModelSerializers](howto/test.md)
 - [Passing Arbitrary Options](howto/passing_arbitrary_options.md)
 - [How to serialize a Plain-Old Ruby Object (PORO)](howto/serialize_poro.md)
+- [How to upgrade from `0.8` to `0.10` safely](howto/upgrade_from_0_8_to_0_10.md)
 
 ## Integrations
 

data/docs/general/adapters.md

@@ -36,6 +36,12 @@ The `Attributes` adapter does not include a root key. It is just the serialized
 
 Use either the `JSON` or `JSON API` adapters if you want the response document to have a root key.
 
+***IMPORTANT***: Adapter configuration has *no effect* on a serializer instance
+being used directly. That is, `UserSerializer.new(user).as_json` will *always*
+behave as if the adapter were the 'Attributes' adapter. See [Outside Controller
+Usage](../howto/outside_controller_use.md) for more details on recommended
+usage.
+
 ## Built in Adapters
 
 ### Attributes - Default
@@ -67,9 +73,11 @@ Doesn't follow any specific convention.
 
 ### JSON
 
-The response document always with a root key.
+The json response is always rendered with a root key.
 
-The root key **can't be overridden**, and will be derived from the resource being serialized.
+The root key can be overridden by:
+* passing the `root` option in the render call. See details in the [Rendering Guides](rendering.md#overriding-the-root-key).
+* setting the `type` of the serializer. See details in the [Serializers Guide](serializers.md#type).
 
 Doesn't follow any specific convention.
 
@@ -139,18 +147,25 @@ This adapter follows **version 1.0** of the [format specified](../jsonapi/schema
 }
 ```
 
-#### Included
+### Include option
 
-It will include the associated resources in the `"included"` member
-when the resource names are included in the `include` option.
-Including nested associated resources is also supported.
+Which [serializer associations](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/serializers.md#associations) are rendered can be specified using the `include` option. The option usage is consistent with [the include option in the JSON API spec](http://jsonapi.org/format/#fetching-includes), and is available in all adapters.
 
+Example of the usage:
 ```ruby
   render json: @posts, include: ['author', 'comments', 'comments.author']
   # or
   render json: @posts, include: 'author,comments,comments.author'
 ```
 
+The format of the `include` option can be either:
+
+- a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes).
+- an Array of Symbols and Hashes.
+- a mix of both.
+
+An empty string or an empty array will prevent rendering of any associations.
+
 In addition, two types of wildcards may be used:
 
 - `*` includes one level of associations.
@@ -162,11 +177,6 @@ These can be combined with other paths.
   render json: @posts, include: '**' # or '*' for a single layer
 ```
 
-The format of the `include` option can be either:
-
-- a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes).
-- an Array of Symbols and Hashes.
-- a mix of both.
 
 The following would render posts and include:
 
@@ -180,6 +190,20 @@ It could be combined, like above, with other paths in any combination desired.
   render json: @posts, include: 'author.comments.**'
 ```
 
+**Note:** Wildcards are ActiveModelSerializers-specific, they are not part of the JSON API spec.
+
+The default include for the JSON API adapter is no associations. The default for the JSON and Attributes adapters is all associations.
+
+For the JSON API adapter associated resources will be gathered in the `"included"` member. For the JSON and Attributes
+adapters associated resources will be rendered among the other attributes.
+
+Only for the JSON API adapter you can specify, which attributes of associated resources will be rendered. This feature
+is called [sparse fieldset](http://jsonapi.org/format/#fetching-sparse-fieldsets):
+
+```ruby
+  render json: @posts, include: 'comments', fields: { comments: ['content', 'created_at'] }
+```
+
 ##### Security Considerations
 
 Since the included options may come from the query params (i.e. user-controller):

data/docs/general/caching.md

@@ -2,6 +2,12 @@
 
 # Caching
 
+## Warning
+
+There is currently a problem with caching in AMS [Caching doesn't improve performance](https://github.com/rails-api/active_model_serializers/issues/1586). Adding caching _may_ slow down your application, rather than speeding it up. We suggest you benchmark any caching you implement before using in a production enviroment
+
+___
+
 To cache a serializer, call ```cache``` and pass its options.
 The options are the same options of ```ActiveSupport::Cache::Store```, plus
 a ```key``` option that will be the prefix of the object cache
@@ -17,7 +23,7 @@ The cache support is optimized to use the cached object in multiple request. An
 cache(options = nil) # options: ```{key, expires_in, compress, force, race_condition_ttl}```
 ```
 
-Take the example bellow:
+Take the example below:
 
 ```ruby
 class PostSerializer < ActiveModel::Serializer