active_model_serializers 0.10.0.rc4 → 0.10.0.rc5

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/ARCHITECTURE.md

@@ -1,5 +1,11 @@
 [Back to Guides](README.md)
 
+This document 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).
+
 # ARCHITECTURE
 
 An **`ActiveModel::Serializer`** wraps a [serializable resource](https://github.com/rails/rails/blob/4-2-stable/activemodel/lib/active_model/serialization.rb)
@@ -17,7 +23,7 @@ serializer. For example, the `Attributes` example represents each serializer as
 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
+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.
@@ -56,16 +62,16 @@ High-level overview:
   - `: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).
+    [`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 = ActiveModel::SerializableResource.new(resource, options)`
+  1. `serializable_resource = ActiveModelSerializers::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**
+      The `adapter_opts`  keys are defined in `ActiveModelSerializers::SerializableResource::ADAPTER_OPTION_KEYS`.
+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);
@@ -88,7 +94,7 @@ Details:
 ## What does a 'serializable resource' look like?
 
 - An `ActiveRecord::Base` object.
-- Any Ruby object at passes or otherwise passes the
+- 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).
 
@@ -116,5 +122,5 @@ 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
+ActiveModelSerializers::SerializableResource.new(MyModel.new(level: 'awesome'), adapter: :json).as_json
 ```

data/docs/README.md

@@ -13,8 +13,11 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - [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)
+- JSON API
+  - [Schema](jsonapi/schema.md)
+  - [Errors](jsonapi/errors.md)
 - [ARCHITECTURE](ARCHITECTURE.md)
 
 ## How to
@@ -23,6 +26,7 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - [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)
+- [Passing Arbitrary Options](howto/passing_arbitrary_options.md)
 
 ## Integrations
 

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

@@ -11,7 +11,7 @@ It should be set only once, preferably at initialization.
 For example:
 
 ```ruby
-ActiveModelSerializers.config.adapter = ActiveModel::Serializer::Adapter::JsonApi
+ActiveModelSerializers.config.adapter = ActiveModelSerializers::Adapter::JsonApi
 ```
 
 or
@@ -43,6 +43,28 @@ Use either the `JSON` or `JSON API` adapters if you want the response document t
 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 response document always with a root key.
@@ -51,11 +73,72 @@ The root key **can't be overridden**, and will be derived from the resource bein
 
 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
+    }
+  }
+}
+```
+
 #### Included
 
 It will include the associated resources in the `"included"` member
@@ -117,46 +200,46 @@ 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`,
-`ActiveModel::Serializer::Adapter::GreatExample`, or registered.
+`ActiveModelSerializers::Adapter::GreatExample`, or registered.
 
 There are two ways to register an adapter:
 
-1) The simplest, is to subclass `ActiveModel::Serializer::Adapter`, e.g. the below will
-register the `Example::UsefulAdapter` as `:useful_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 < ActiveModel::Serializer::Adapter
+  class UsefulAdapter < ActiveModelSerializers::Adapter::Base
   end
 end
 ```
 
-You'll notice that the name it registers is the class name underscored, not the full namespace.
+You'll notice that the name it registers is the underscored namespace and class.
 
-Under the covers, when the `ActiveModel::Serializer::Adapter` is subclassed, it registers
-the subclass as `register(:useful_adapter, Example::UsefulAdapter)`
+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
-`ActiveModel::Serializer::Adapter` class. e.g., the below registers `MyAdapter` as
+`ActiveModelSerializers::Adapter` class. e.g., the below registers `MyAdapter` as
 `:special_adapter`.
 
 ```ruby
 class MyAdapter; end
-ActiveModel::Serializer::Adapter.register(:special_adapter, MyAdapter)
+ActiveModelSerializers::Adapter.register(:special_adapter, MyAdapter)
 ```
 
 ### Looking up an adapter
 
 | Method | Return value |
 | :------------ |:---------------|
-| `ActiveModel::Serializer::Adapter.adapter_map` | A Hash of all known adapters `{ adapter_name => adapter_class }` |
-| `ActiveModel::Serializer::Adapter.adapters` | A (sorted) Array of all known `adapter_names` |
-| `ActiveModel::Serializer::Adapter.lookup(name_or_klass)` |  The `adapter_class`, else raises an `ActiveModel::Serializer::Adapter::UnknownAdapter` error |
-| `ActiveModel::Serializer::Adapter.adapter_class(adapter)` | Delegates to `ActiveModel::Serializer::Adapter.lookup(adapter)` |
-| `ActiveModel::Serializer.adapter` | A convenience method for `ActiveModel::Serializer::Adapter.lookup(config.adapter)` |
+| `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/serializer/adapter.rb)
+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/configuration_options.md

@@ -2,26 +2,99 @@
 
 # Configuration Options
 
-The following configuration options can be set on `ActiveModelSerializers.config`,
-preferably inside an initializer.
+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, :json, :json_api`. Default: `:attributes`.
-- `serializer_lookup_enabled`: When `false`, serializers must be explicitly specified. Default: `true`
+##### 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 |
+|----|----|
+| `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.
+
 
 ## JSON API
 
-- `jsonapi_resource_type`: Whether the `type` attributes of resources should be singular or plural. Possible values: `:singular, :plural`. Default: `:plural`.
-- `jsonapi_include_toplevel_object`: Whether to include a [top level JSON API member](http://jsonapi.org/format/#document-jsonapi-object)
-   in the response document.
-   Default: `false`.
-- Used when `jsonapi_include_toplevel_object` is `true`:
-  - `jsonapi_version`: The latest version of the spec the API conforms to.
-    Default: `'1.0'`.
-  - `jsonapi_toplevel_meta`: Optional metadata. Not included if empty.
-    Default: `{}`.
+
+##### 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_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`*
+
 
 ## Hooks
 
-To run a hook when ActiveModelSerializers is loaded, use `ActiveSupport.on_load(:action_controller) do end`
+To run a hook when ActiveModelSerializers is loaded, use
+`ActiveSupport.on_load(:action_controller) do end`