active_model_serializers 0.8.3 → 0.10.8

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/bin/serve_benchmark

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+set -e
+
+case "$1" in
+
+  start)
+  config="${CONFIG_RU:-test/benchmark/config.ru}"
+  bundle exec ruby -Ilib -S rackup "$config" --daemonize --pid tmp/benchmark_app.pid --warn --server webrick
+  until [ -f 'tmp/benchmark_app.pid' ]; do
+    sleep 0.1 # give it time to start.. I don't know a better way
+  done
+  cat tmp/benchmark_app.pid
+  true
+  ;;
+
+  stop)
+  if [ -f 'tmp/benchmark_app.pid' ]; then
+    kill -TERM $(cat tmp/benchmark_app.pid)
+  else
+    echo 'No pidfile'
+    false
+  fi
+  ;;
+
+  status)
+  if [ -f 'tmp/benchmark_app.pid' ]; then
+    kill -0 $(cat tmp/benchmark_app.pid)
+    [ "$?" -eq 0 ]
+  else
+    echo 'No pidfile'
+    false
+  fi
+  ;;
+
+  *)
+  echo "Usage: $0 [start|stop|status]"
+  ;;
+
+esac

data/docs/README.md

@@ -0,0 +1,41 @@
+# 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)
+- [Deserialization](general/deserialization.md)
+- [Instrumentation](general/instrumentation.md)
+- JSON API
+  - [Schema](jsonapi/schema.md)
+  - [Errors](jsonapi/errors.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
+
+| 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/

data/docs/STYLE.md

@@ -0,0 +1,58 @@
+# STYLE
+
+## Code and comments
+
+- We are actively working to identify tasks under the label [**Good for New
+  Contributors**](https://github.com/rails-api/active_model_serializers/labels/Good%20for%20New%20Contributors).
+  - [Changelog
+      Missing](https://github.com/rails-api/active_model_serializers/issues?q=label%3A%22Changelog+Missing%22+is%3Aclosed) is
+    an easy way to help out.
+
+- [Fix a bug](https://github.com/rails-api/active_model_serializers/labels/Ready%20for%20PR).
+  - Ready for PR - A well defined bug, needs someone to PR a fix.
+  - Bug - Anything that is broken.
+  - Regression - A bug that did not exist in previous versions and isn't a new feature (applied in tandem with Bug).
+  - Performance - A performance related issue. We could track this as a bug, but usually these would have slightly lower priority than standard bugs.
+
+- [Develop new features](https://github.com/rails-api/active_model_serializers/labels/Feature).
+
+- [Improve code quality](https://codeclimate.com/github/rails-api/active_model_serializers/code?sort=smell_count&sort_direction=desc).
+
+- [Improve amount of code exercised by tests](https://codeclimate.com/github/rails-api/active_model_serializers/coverage?sort=covered_percent&sort_direction=asc).
+
+- [Fix RuboCop (Style) TODOS](https://github.com/rails-api/active_model_serializers/blob/master/.rubocop_todo.yml).
+  - Delete and offsense, run `rake rubocop` (or possibly `rake rubocop:auto_correct`),
+    and [submit a PR](CONTRIBUTING.md#submitting-a-pull-request-pr).
+
+- We are also encouraging comments to substantial changes (larger than bugfixes and simple features) under an
+  "RFC" (Request for Comments) process before we start active development.
+   Look for the [**RFC**](https://github.com/rails-api/active_model_serializers/labels/RFC) label.
+
+
+## Pull requests
+
+- If the tests pass and the pull request looks good, a maintainer will merge it.
+- If the pull request needs to be changed,
+  - you can change it by updating the branch you generated the pull request from
+    - either by adding more commits, or
+    - by force pushing to it
+  - A maintainer can make any changes themselves and manually merge the code in.
+
+## Commit messages
+
+- [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
+- [http://stopwritingramblingcommitmessages.com/](http://stopwritingramblingcommitmessages.com/)
+- [ThoughtBot style guide](https://github.com/thoughtbot/guides/tree/master/style#git)
+
+#### About Pull Requests (PR's)
+
+- [Using Pull Requests](https://help.github.com/articles/using-pull-requests)
+- [Github pull requests made easy](http://www.element84.com/github-pull-requests-made-easy.html)
+- [Exercism Git Workflow](http://help.exercism.io/git-workflow.html).
+- [Level up your Git](http://rakeroutes.com/blog/deliberate-git/)
+- [All Your Open Source Code Are Belong To Us](http://www.benjaminfleischer.com/2013/07/30/all-your-open-source-code-are-belong-to-us/)
+
+## Issue Labeling
+
+ActiveModelSerializers uses a subset of [StandardIssueLabels](https://github.com/wagenet/StandardIssueLabels) for Github Issues. You can [see our labels here](https://github.com/rails-api/active_model_serializers/labels).
+

data/docs/general/adapters.md

@@ -0,0 +1,269 @@
+[Back to Guides](../README.md)
+
+# Adapters
+
+ActiveModelSerializers offers the ability to configure which adapter
+to use both globally and/or when serializing (usually when rendering).
+
+The global adapter configuration is set on [`ActiveModelSerializers.config`](configuration_options.md).
+It should be set only once, preferably at initialization.
+
+For example:
+
+```ruby
+ActiveModelSerializers.config.adapter = ActiveModelSerializers::Adapter::JsonApi
+```
+
+or
+
+```ruby
+ActiveModelSerializers.config.adapter = :json_api
+```
+
+or
+
+```ruby
+ActiveModelSerializers.config.adapter = :json
+```
+
+The local adapter option is in the format `adapter: adapter`, where `adapter` is
+any of the same values as set globally.
+
+The configured adapter can be set as a symbol, class, or class name, as described in
+[Advanced adapter configuration](adapters.md#advanced-adapter-configuration).
+
+The `Attributes` adapter does not include a root key. It is just the serialized attributes.
+
+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
+
+It's the default adapter, it generates a json response without a root key.
+Doesn't follow any specific convention.
+
+##### Example output
+
+```json
+{
+  "title": "Title 1",
+  "body": "Body 1",
+  "publish_at": "2020-03-16T03:55:25.291Z",
+  "author": {
+    "first_name": "Bob",
+    "last_name": "Jones"
+  },
+  "comments": [
+    {
+      "body": "cool"
+    },
+    {
+      "body": "awesome"
+    }
+  ]
+}
+```
+
+### JSON
+
+The json response is always rendered with a root key.
+
+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.
+
+##### Example output
+
+```json
+{
+  "post": {
+    "title": "Title 1",
+    "body": "Body 1",
+    "publish_at": "2020-03-16T03:55:25.291Z",
+    "author": {
+      "first_name": "Bob",
+      "last_name": "Jones"
+    },
+    "comments": [{
+      "body": "cool"
+    }, {
+      "body": "awesome"
+    }]
+  }
+}
+```
+
+### JSON API
+
+This adapter follows **version 1.0** of the [format specified](../jsonapi/schema.md) in
+[jsonapi.org/format](http://jsonapi.org/format).
+
+##### Example output
+
+```json
+{
+  "data": {
+    "id": "1337",
+    "type": "posts",
+    "attributes": {
+      "title": "Title 1",
+      "body": "Body 1",
+      "publish-at": "2020-03-16T03:55:25.291Z"
+    },
+    "relationships": {
+      "author": {
+        "data": {
+          "id": "1",
+          "type": "authors"
+        }
+      },
+      "comments": {
+        "data": [{
+          "id": "7",
+          "type": "comments"
+        }, {
+          "id": "12",
+          "type": "comments"
+        }]
+      }
+    },
+    "links": {
+      "post-authors": "https://example.com/post_authors"
+    },
+    "meta": {
+      "rating": 5,
+      "favorite-count": 10
+    }
+  }
+}
+```
+
+### Include option
+
+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.
+- `**` includes all recursively.
+
+These can be combined with other paths.
+
+```ruby
+  render json: @posts, include: '**' # or '*' for a single layer
+```
+
+
+The following would render posts and include:
+
+- the author
+- the author's comments, and
+- every resource referenced by the author's comments (recursively).
+
+It could be combined, like above, with other paths in any combination desired.
+
+```ruby
+  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):
+
+```ruby
+  render json: @posts, include: params[:include]
+```
+
+The user could pass in `include=**`.
+
+We recommend filtering any user-supplied includes appropriately.
+
+## Advanced adapter configuration
+
+### Registering an adapter
+
+The default adapter can be configured, as above, to use any class given to it.
+
+An adapter may also be specified, e.g. when rendering, as a class or as a symbol.
+If a symbol, then the adapter must be, e.g. `:great_example`,
+`ActiveModelSerializers::Adapter::GreatExample`, or registered.
+
+There are two ways to register an adapter:
+
+1) The simplest, is to subclass `ActiveModelSerializers::Adapter::Base`, e.g. the below will
+register the `Example::UsefulAdapter` as `"example/useful_adapter"`.
+
+```ruby
+module Example
+  class UsefulAdapter < ActiveModelSerializers::Adapter::Base
+  end
+end
+```
+
+You'll notice that the name it registers is the underscored namespace and class.
+
+Under the covers, when the `ActiveModelSerializers::Adapter::Base` is subclassed, it registers
+the subclass as `register("example/useful_adapter", Example::UsefulAdapter)`
+
+2) Any class can be registered as an adapter by calling `register` directly on the
+`ActiveModelSerializers::Adapter` class. e.g., the below registers `MyAdapter` as
+`:special_adapter`.
+
+```ruby
+class MyAdapter; end
+ActiveModelSerializers::Adapter.register(:special_adapter, MyAdapter)
+```
+
+### Looking up an adapter
+
+| Method | Return value |
+| :------------ |:---------------|
+| `ActiveModelSerializers::Adapter.adapter_map` | A Hash of all known adapters `{ adapter_name => adapter_class }` |
+| `ActiveModelSerializers::Adapter.adapters` | A (sorted) Array of all known `adapter_names` |
+| `ActiveModelSerializers::Adapter.lookup(name_or_klass)` |  The `adapter_class`, else raises an `ActiveModelSerializers::Adapter::UnknownAdapter` error |
+| `ActiveModelSerializers::Adapter.adapter_class(adapter)` | Delegates to `ActiveModelSerializers::Adapter.lookup(adapter)` |
+| `ActiveModelSerializers::Adapter.configured_adapter` | A convenience method for `ActiveModelSerializers::Adapter.lookup(config.adapter)` |
+
+The registered adapter name is always a String, but may be looked up as a Symbol or String.
+Helpfully, the Symbol or String is underscored, so that `get(:my_adapter)` and `get("MyAdapter")`
+may both be used.
+
+For more information, see [the Adapter class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/adapter.rb)

data/docs/general/caching.md

@@ -0,0 +1,58 @@
+[Back to Guides](../README.md)
+
+# 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
+on a pattern ```"#{key}/#{object.id}-#{object.updated_at}"```.
+
+The cache support is optimized to use the cached object in multiple request. An object cached on a ```show``` request will be reused at the ```index```. If there is a relationship with another cached serializer it will also be created and reused automatically.
+
+**[NOTE] Every object is individually cached.**
+
+**[NOTE] The cache is automatically expired after an object is updated, but it's not deleted.**
+
+```ruby
+cache(options = nil) # options: ```{key, expires_in, compress, force, race_condition_ttl}```
+```
+
+Take the example below:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  cache key: 'post', expires_in: 3.hours
+  attributes :title, :body
+
+  has_many :comments
+end
+```
+
+On this example every ```Post``` object will be cached with
+the key ```"post/#{post.id}-#{post.updated_at}"```. You can use this key to expire it as you want,
+but in this case it will be automatically expired after 3 hours.
+
+## Fragment Caching
+
+If there is some API endpoint that shouldn't be fully cached, you can still optimise it, using Fragment Cache on the attributes and relationships that you want to cache.
+
+You can define the attribute by using ```only``` or ```except``` option on cache method.
+
+**[NOTE] Cache serializers will be used at their relationships**
+
+Example:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  cache key: 'post', expires_in: 3.hours, only: [:title]
+  attributes :title, :body
+
+  has_many :comments
+end
+```

data/docs/general/configuration_options.md

@@ -0,0 +1,185 @@
+[Back to Guides](../README.md)
+
+# Configuration Options
+
+The following configuration options can be set on
+`ActiveModelSerializers.config`, preferably inside an initializer.
+
+## General
+
+##### adapter
+
+The [adapter](adapters.md) to use.
+
+Possible values:
+
+- `:attributes` (default)
+- `:json`
+- `:json_api`
+
+##### serializer_lookup_enabled
+
+Enable automatic serializer lookup.
+
+Possible values:
+
+- `true` (default)
+- `false`
+
+When `false`, serializers must be explicitly specified.
+
+##### key_transform
+
+The [key transform](key_transforms.md) to use.
+
+
+| Option | Result |
+|----|----|
+| `:camel` | ExampleKey |
+| `:camel_lower` | exampleKey |
+| `:dash` | example-key |
+| `:unaltered` | the original, unaltered key |
+| `:underscore` | example_key |
+| `nil` | use the adapter default |
+
+Each adapter has a default key transform configured:
+
+| Adapter | Default Key Transform |
+|----|----|
+| `Attributes` | `:unaltered` |
+| `Json` | `:unaltered` |
+| `JsonApi` | `:dash` |
+
+`config.key_transform` is a global override of the adapter default. Adapters
+still prefer the render option `:key_transform` over this setting.
+
+*NOTE: Key transforms can be expensive operations. If key transforms are unnecessary for the
+application, setting `config.key_transform` to `:unaltered` will provide a performance boost.*
+
+##### default_includes
+
+What relationships to serialize by default.  Default: `'*'`, which includes one level of related
+objects. See [includes](adapters.md#included) for more info.
+
+
+##### serializer_lookup_chain
+
+Configures how serializers are searched for. By default, the lookup chain is
+
+```ruby
+ActiveModelSerializers::LookupChain::DEFAULT
+```
+
+which is shorthand for
+
+```ruby
+[
+  ActiveModelSerializers::LookupChain::BY_PARENT_SERIALIZER,
+  ActiveModelSerializers::LookupChain::BY_NAMESPACE,
+  ActiveModelSerializers::LookupChain::BY_RESOURCE_NAMESPACE,
+  ActiveModelSerializers::LookupChain::BY_RESOURCE
+]
+```
+
+Each of the array entries represent a proc. A serializer lookup proc will be yielded 3 arguments. `resource_class`, `serializer_class`, and `namespace`.
+
+Note that:
+ - `resource_class` is the class of the resource being rendered
+ - by default `serializer_class` is `ActiveModel::Serializer`
+   - for association lookup it's the "parent" serializer
+ - `namespace` correspond to either the controller namespace or the [optionally] specified [namespace render option](./rendering.md#namespace)
+
+An example config could be:
+
+```ruby
+ActiveModelSerializers.config.serializer_lookup_chain = [
+  lambda do |resource_class, serializer_class, namespace|
+    "API::#{namespace}::#{resource_class}"
+  end
+]
+```
+
+If you simply want to add to the existing lookup_chain. Use `unshift`.
+
+```ruby
+ActiveModelSerializers.config.serializer_lookup_chain.unshift(
+  lambda do |resource_class, serializer_class, namespace|
+    # ...
+  end
+)
+```
+
+See [lookup_chain.rb](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/lookup_chain.rb) for further explanations and examples.
+
+## JSON API
+
+##### jsonapi_resource_type
+
+Sets whether the [type](http://jsonapi.org/format/#document-resource-identifier-objects)
+of the resource should be `singularized` or `pluralized` when it is not
+[explicitly specified by the serializer](https://github.com/rails-api/active_model_serializers/blob/master/docs/general/serializers.md#type)
+
+Possible values:
+
+- `:singular`
+- `:plural` (default)
+
+##### jsonapi_namespace_separator
+
+Sets separator string for namespaced models to render `type` attribute.
+
+
+| Separator | Example: Admin::User |
+|----|----|
+| `'-'` (default) | 'admin-users'
+| `'--'` (recommended) | 'admin--users'
+
+See [Recommendation for dasherizing (kebab-case-ing) namespaced object, such as `Admin::User`](https://github.com/json-api/json-api/issues/850)
+for more discussion.
+
+##### jsonapi_include_toplevel_object
+
+Include a [top level jsonapi member](http://jsonapi.org/format/#document-jsonapi-object)
+in the response document.
+
+Possible values:
+
+- `true`
+- `false` (default)
+
+##### jsonapi_version
+
+The latest version of the spec to which the API conforms.
+
+Default: `'1.0'`.
+
+*Used when `jsonapi_include_toplevel_object` is `true`*
+
+##### jsonapi_toplevel_meta
+
+Optional top-level metadata. Not included if empty.
+
+Default: `{}`.
+
+*Used when `jsonapi_include_toplevel_object` is `true`*
+
+##### jsonapi_use_foreign_key_on_belongs_to_relationship
+
+When true, the relationship will determine its resource object identifier
+without calling the association or its serializer.  This can be useful when calling
+the association object is triggering unnecessary queries.
+
+For example, if a `comment` belongs to a `post`, and the comment
+uses the foreign key `post_id`, we can determine the resource object
+identifier `id` as `comment.post_id` and the `type` from the association options.
+Or quite simply, it behaves as `belongs_to :post, type: :posts, foreign_key: :post_id`.
+
+Note: This option has *no effect* on polymorphic associations as we cannot reliably
+determine the associated object's type without instantiating it.
+
+Default: `false`.
+
+## Hooks
+
+To run a hook when ActiveModelSerializers is loaded, use
+`ActiveSupport.on_load(:action_controller) do end`