active_model_serializers 0.10.0.rc4 → 0.10.0.rc5

data/docs/howto/add_pagination_links.md

@@ -74,32 +74,30 @@ ActiveModelSerializers pagination relies on a paginated collection with the meth
 
 If you are using `JSON` adapter, pagination links will not be included automatically, but it is possible to do so using `meta` key.
 
-In your action specify a custom serializer.
+Add this method to your base API controller.
+
 ```ruby
-render json: @posts, serializer: PaginatedSerializer, each_serializer: PostPreviewSerializer
+def pagination_dict(object)
+  {
+    current_page: object.current_page,
+    next_page: object.next_page,
+    prev_page: object.prev_page,
+    total_pages: object.total_pages,
+    total_count: object.total_count
+  }
+end
 ```
 
-And then, you could do something like the following class.
+Then, use it on your render method.
+
 ```ruby
-class PaginatedSerializer < ActiveModel::Serializer::CollectionSerializer
-  def initialize(object, options={})
-    meta_key = options[:meta_key] || :meta
-    options[meta_key] ||= {}
-    options[meta_key] = {
-      current_page: object.current_page,
-      next_page: object.next_page,
-      prev_page: object.prev_page,
-      total_pages: object.total_pages,
-      total_count: object.total_count
-    }
-    super(object, options)
-  end
-end
+render json: posts, meta: pagination_dict(posts)
 ```
+
 ex.
 ```json
 {
-  "articles": [
+  "posts": [
     {
       "id": 2,
       "title": "JSON API paints my bikeshed!",
@@ -116,6 +114,26 @@ ex.
 }
 ```
 
+You can also achieve the same result if you have a helper method that adds the pagination info in the meta tag. For instance, in your action specify a custom serializer.
+
+```ruby
+render json: @posts, each_serializer: PostPreviewSerializer, meta: meta_attributes(@post)
+```
+
+```ruby
+#expects pagination!
+def meta_attributes(resource, extra_meta = {})
+  {
+    current_page: resource.current_page,
+    next_page: resource.next_page,
+    prev_page: resource.prev_page,
+    total_pages: resource.total_pages,
+    total_count: resource.total_count
+  }.merge(extra_meta)
+end
+```
+
+
 ### Attributes adapter
 
 This adapter does not allow us to use `meta` key, due to that it is not possible to add pagination links.

data/docs/howto/outside_controller_use.md

@@ -14,7 +14,7 @@ post = Post.create(title: "Sample post", body: "I love Active Model Serializers!
 options = {}
 
 # Create a serializable resource instance
-serializable_resource = ActiveModel::SerializableResource.new(post, options)
+serializable_resource = ActiveModelSerializers::SerializableResource.new(post, options)
 
 # Convert your resource into json
 model_json = serializable_resource.as_json
@@ -38,20 +38,20 @@ serializer = ActiveModel::Serializer.serializer_for(post, options)
 You could also retrieve the serializer via:
 
 ```ruby
-ActiveModel::SerializableResource.new(post, options).serializer
+ActiveModelSerializers::SerializableResource.new(post, options).serializer
 ```
 
 Both approaches will return an instance, if any, of the resource's serializer.
 
 ## Serializing before controller render
 
-At times, you might want to use a serializer without rendering it to the view. For those cases, you can create an instance of `ActiveModel::SerializableResource` with
+At times, you might want to use a serializer without rendering it to the view. For those cases, you can create an instance of `ActiveModelSerializers::SerializableResource` with
 the resource you want to be serialized and call `.as_json`.
 
 ```ruby
 def create
   message = current_user.messages.create!(message_params)
-  message_json = ActiveModel::SerializableResource.new(message).as_json
+  message_json = ActiveModelSerializers::SerializableResource.new(message).as_json
   MessageCreationWorker.perform(message_json)
   head 204
 end

data/docs/howto/passing_arbitrary_options.md

@@ -0,0 +1,27 @@
+[Back to Guides](../README.md)
+
+# Passing Arbitrary Options To A Serializer
+
+In addition to the [`serialization_scope`](../general/serializers.md#scope), any options passed to `render`
+that are not reserved for the [adapter](../general/rendering.md#adapter_opts)
+are available in the serializer as [instance_options](../general/serializers.md#instance_options).
+
+For example, we could pass in a field, such as `user_id` into our serializer.
+
+```ruby
+# posts_controller.rb
+class PostsController < ApplicationController
+  def dashboard  
+    render json: @post, user_id: 12
+  end
+end
+
+# post_serializer.rb
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body
+
+  def comments_by_me  
+    Comments.where(user_id: instance_options[:user_id], post_id: object.id)
+  end
+end
+```

data/docs/jsonapi/errors.md

@@ -0,0 +1,56 @@
+[Back to Guides](../README.md)
+
+# [JSON API Errors](http://jsonapi.org/format/#errors)
+
+Rendering error documents requires specifying the error serializer(s):
+
+- Serializer:
+  - For a single resource: `serializer: ActiveModel::Serializer::ErrorSerializer`.
+  - For a collection: `serializer: ActiveModel::Serializer::ErrorsSerializer`, `each_serializer: ActiveModel::Serializer::ErrorSerializer`.
+
+The resource **MUST** have a non-empty associated `#errors` object.
+The `errors` object must have a `#messages` method that returns a hash of error name to array of
+descriptions.
+
+## Use in controllers
+
+```ruby
+resource = Profile.new(name: 'Name 1',
+                       description: 'Description 1',
+                       comments: 'Comments 1')
+resource.errors.add(:name, 'cannot be nil')
+resource.errors.add(:name, 'must be longer')
+resource.errors.add(:id, 'must be a uuid')
+
+render json: resource, status: 422, adapter: :json_api, serializer: ActiveModel::Serializer::ErrorSerializer
+# #=>
+#  { :errors =>
+#    [
+#      { :source => { :pointer => '/data/attributes/name' }, :detail => 'cannot be nil' },
+#      { :source => { :pointer => '/data/attributes/name' }, :detail => 'must be longer' },
+#      { :source => { :pointer => '/data/attributes/id' }, :detail => 'must be a uuid' }
+#    ]
+#  }.to_json
+```
+
+## Direct error document generation
+
+```ruby
+options = nil
+resource = ModelWithErrors.new
+resource.errors.add(:name, 'must be awesome')
+
+serializable_resource = ActiveModelSerializers::SerializableResource.new(
+  resource, {
+    serializer: ActiveModel::Serializer::ErrorSerializer,
+    adapter: :json_api
+  })
+serializable_resource.as_json(options)
+# #=>
+# {
+#   :errors =>
+#     [
+#       { :source => { :pointer => '/data/attributes/name' }, :detail => 'must be awesome' }
+#     ]
+# }
+```

data/docs/jsonapi/schema.md

@@ -58,33 +58,33 @@ Example supported requests
 |-----------------------|----------------------------------------------------------------------------------------------------|----------|---------------------------------------|
 | schema                | oneOf (success, failure, info)                                                                     |          |
 | success               | data, included, meta, links, jsonapi                                                               |          | AM::SerializableResource
-| success.meta          | meta                                                                                               |          | AM::S::Adapter::Base#meta
-| success.included      | UniqueArray(resource)                                                                              |          | AM::S::Adapter::JsonApi#serializable_hash_for_collection
+| success.meta          | meta                                                                                               |          | AMS::Adapter::Base#meta
+| success.included      | UniqueArray(resource)                                                                              |          | AMS::Adapter::JsonApi#serializable_hash_for_collection
 | success.data          | data                                                                                               |          |
-| success.links         | allOf (links, pagination)                                                                          |          | AM::S::Adapter::JsonApi#links_for
+| success.links         | allOf (links, pagination)                                                                          |          | AMS::Adapter::JsonApi#links_for
 | success.jsonapi       | jsonapi                                                                                            |          |
-| failure               | errors, meta, jsonapi                                                                              | errors   |
-| failure.errors        | UniqueArray(error)                                                                                 |          | #1004
-| meta                  | Object                                                                                             |          |
-| data                  | oneOf (resource, UniqueArray(resource))                                                            |          | AM::S::Adapter::JsonApi#serializable_hash_for_collection,#serializable_hash_for_single_resource
+| failure               | errors, meta, jsonapi                                                                              | errors   | AMS::Adapter::JsonApi#failure_document, #1004
+| failure.errors        | UniqueArray(error)                                                                                 |          | AM::S::ErrorSerializer, #1004
+| meta                  | Object                                                                                             |          | 
+| data                  | oneOf (resource, UniqueArray(resource))                                                            |          | AMS::Adapter::JsonApi#serializable_hash_for_collection,#serializable_hash_for_single_resource
 | resource              | String(type), String(id),<br>attributes, relationships,<br>links, meta                                   | type, id | AM::S::Adapter::JsonApi#primary_data_for
 | links                 | Uri(self), Link(related)                                                                           |          | #1028, #1246, #1282
 | link                  | oneOf (linkString, linkObject)                                                                     |          |
 | link.linkString       | Uri                                                                                                |          |
 | link.linkObject       | Uri(href), meta                                                                                    | href     |
-| attributes            | patternProperties(<br>`"^(?!relationships$|links$)\\w[-\\w_]*$"`),<br>any valid JSON                      |          | AM::Serializer#attributes, AM::S::Adapter::JsonApi#resource_object_for
-| relationships         | patternProperties(<br>`"^\\w[-\\w_]*$"`);<br>links, relationships.data, meta                              |          | AM::S::Adapter::JsonApi#relationships_for
-| relationships.data    | oneOf (relationshipToOne, relationshipToMany)                                                      |          | AM::S::Adapter::JsonApi#resource_identifier_for
+| attributes            | patternProperties(<br>`"^(?!relationships$|links$)\\w[-\\w_]*$"`),<br>any valid JSON                      |          | AM::Serializer#attributes, AMS::Adapter::JsonApi#resource_object_for
+| relationships         | patternProperties(<br>`"^\\w[-\\w_]*$"`);<br>links, relationships.data, meta                              |          | AMS::Adapter::JsonApi#relationships_for
+| relationships.data    | oneOf (relationshipToOne, relationshipToMany)                                                      |          | AMS::Adapter::JsonApi#resource_identifier_for
 | relationshipToOne     | anyOf(empty, linkage)                                                                              |          |
 | relationshipToMany    | UniqueArray(linkage)                                                                               |          |
 | empty                 | null                                                                                               |          |
-| linkage               | String(type), String(id), meta                                                                     | type, id | AM::S::Adapter::JsonApi#primary_data_for
-| pagination            | pageObject(first), pageObject(last),<br>pageObject(prev), pageObject(next)                            |          | AM::S::Adapter::JsonApi::PaginationLinks#serializable_hash
+| linkage               | String(type), String(id), meta                                                                     | type, id | AMS::Adapter::JsonApi#primary_data_for
+| pagination            | pageObject(first), pageObject(last),<br>pageObject(prev), pageObject(next)                            |          | AMS::Adapter::JsonApi::PaginationLinks#serializable_hash
 | pagination.pageObject | oneOf(Uri, null)                                                                                   |          |
-| jsonapi               | String(version), meta                                                                              |          | AM::S::Adapter::JsonApi::ApiObjects::JsonApi
-| error                 | String(id), links, String(status),<br>String(code), String(title),<br>String(detail), error.source, meta |          |
-| error.source          | String(pointer), String(parameter)                                                                 |          |
-| pointer               | [JSON Pointer RFC6901](https://tools.ietf.org/html/rfc6901)                                        |          |
+| jsonapi               | String(version), meta                                                                              |          | AMS::Adapter::JsonApi::Jsonapi#as_json
+| error                 | String(id), links, String(status),<br>String(code), String(title),<br>String(detail), error.source, meta |          | AM::S::ErrorSerializer, AMS::Adapter::JsonApi::Error.resource_errors
+| error.source          | String(pointer), String(parameter)                                                                 |          | AMS::Adapter::JsonApi::Error.error_source
+| pointer               | [JSON Pointer RFC6901](https://tools.ietf.org/html/rfc6901)                                        |          | AMS::JsonPointer
 
 
 The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap.
@@ -102,7 +102,7 @@ The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap.
 ### Failure Document
 
 - [ ] failure
-  - [ ] errors: array of unique items of type ` "$ref": "#/definitions/error"`
+  - [x] errors: array of unique items of type ` "$ref": "#/definitions/error"`
   - [ ] meta:  `"$ref": "#/definitions/meta"`
   - [ ] jsonapi: `"$ref": "#/definitions/jsonapi"`
 
@@ -137,4 +137,15 @@ The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap.
   - [ ] pagination
   - [ ] jsonapi
     - [ ] meta
-  - [ ] error: id, links, status, code, title: detail: source [{pointer, type}, {parameter: {description, type}], meta
+  - [ ] error
+    - [ ] id: a unique identifier for this particular occurrence of the problem.
+    - [ ] links: a links object containing the following members:
+      - [ ] about: a link that leads to further details about this particular occurrence of the problem.
+    - [ ] status: the HTTP status code applicable to this problem, expressed as a string value.
+    - [ ] code: an application-specific error code, expressed as a string value.
+    - [ ] title: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
+    - [x] detail: a human-readable explanation specific to this occurrence of the problem.
+    - [x] source: an object containing references to the source of the error, optionally including any of the following members:
+      -  [x] pointer: a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].
+      -  [x] parameter: a string indicating which query parameter caused the error.
+    - [ ] meta: a meta object containing non-standard meta-information about the error.

data/docs/rfcs/0000-namespace.md

@@ -0,0 +1,106 @@
+- Start Date: (2015-10-29)
+- RFC PR: https://github.com/rails-api/active_model_serializers/pull/1310
+- ActiveModelSerializers Issue: https://github.com/rails-api/active_model_serializers/issues/1298
+
+# Summary
+
+Provide a consistent API for the user of the AMS.
+
+# Motivation
+
+The actual public API is defined under `ActiveModelSerializers`,
+`ActiveModel::Serializer` and `ActiveModel`.
+
+At the `ActiveModel::Serializer` we have:
+
+- `ActiveModel::Serializer.config`
+- `ActiveModel::Serializer`
+
+At the `ActiveModelSerializers` we have:
+
+- `ActiveModelSerializers::Model`
+- `ActiveModelSerializers.logger`
+
+At `ActiveModel` we have:
+
+- `ActiveModel::SerializableResource`
+
+The idea here is to provide a single namespace `ActiveModelSerializers` to the user.
+Following the same idea we have on other gems like
+[Devise](https://github.com/plataformatec/devise/blob/e9c82472ffe7c43a448945f77e034a0e47dde0bb/lib/devise.rb),
+[Refile](https://github.com/refile/refile/blob/6b24c293d044862dafbf1bfa4606672a64903aa2/lib/refile.rb) and
+[Active Job](https://github.com/rails/rails/blob/30bacc26f8f258b39e12f63fe52389a968d9c1ea/activejob/lib/active_job.rb)
+for example.
+
+This way we are clarifing the boundaries of
+[ActiveModelSerializers and Rails](https://github.com/rails-api/active_model_serializers/blob/master/CHANGELOG.md#prehistory)
+and make clear that the `ActiveModel::Serializer` class is no longer the primary
+behavior of the ActiveModelSerializers.
+
+# Detailed design
+
+## New classes and modules organization
+
+Since this will be a big change we can do this on baby steps, read small pull requests. A
+possible approach is:
+
+- All new code will be in `lib/active_model_serializers/` using
+  the module namespace `ActiveModelSerializers`.
+- Move all content under `ActiveModel::Serializer` to be under
+  `ActiveModelSerializers`, the adapter is on this steps;
+- Move all content under `ActiveModel` to be under `ActiveModelSerializers`,
+  the `SerializableResource` is on this step;
+- Change all public API that doesn't make sense, keeping in mind only to keep
+  this in the same namespace
+- Update the README;
+- Update the docs;
+
+The following table represents the current and the desired classes and modules
+at the first moment.
+
+| Current                                                | Desired                                          | Notes              |
+|--------------------------------------------------------|--------------------------------------------------|--------------------|
+| `ActiveModelSerializers` and `ActiveModel::Serializer` | `ActiveModelSerializers`                         | The main namespace |
+| `ActiveModelSerializers.logger`                        | `ActiveModelSerializers.logger`                  ||
+| `ActiveModelSerializers::Model`                        | `ActiveModelSerializers::Model`                  ||
+| `ActiveModel::SerializableResource`                    | `ActiveModelSerializers::SerializableResource`   ||
+| `ActiveModel::Serializer`                              | `ActiveModelSerializers::Serializer`             | The name can be discussed in a future pull request. For example, we can rename this to `Resource` [following this idea](https://github.com/rails-api/active_model_serializers/pull/1301/files#r42963185) more info about naming in the next section|
+| `ActiveModel::Serializer.config`                       | `ActiveModelSerializers.config`                ||
+
+## Renaming of class and modules
+
+When moving some content to the new namespace we can find some names that does
+not make much sense like `ActiveModel::Serializer::Adapter::JsonApi`.
+Discussion of renaming existing classes / modules and JsonApi objects will
+happen in separate pull requests, and issues, and in the google doc
+https://docs.google.com/document/d/1rcrJr0sVcazY2Opd_6Kmv1iIwuHbI84s1P_NzFn-05c/edit?usp=sharing
+
+Some of names already have a definition.
+
+- Adapters get their own namespace under ActiveModelSerializers. E.g
+  `ActiveModelSerializers::Adapter`
+- Serializers get their own namespace under ActiveModelSerializers. E.g
+  `ActiveModelSerializers::Serializer`
+
+## Keeping compatibility
+
+All moved classes or modules be aliased to their old name and location with
+deprecation warnings, such as
+[was done for CollectionSerializer](https://github.com/rails-api/active_model_serializers/pull/1251).
+
+# Drawbacks
+
+This will be a breaking change, so all users serializers will be broken after a
+major bump.
+All pull requests will need to rebase since the architeture will change a lot.
+
+# Alternatives
+
+We can keep the way it is, and keep in mind to not add another namespace as a
+public API.
+
+# Unresolved questions
+
+What is the better class name to be used to the class that will be inherited at
+the creation of a serializer. This can be discussed in other RFC or directly via
+pull request.

data/docs/rfcs/template.md

@@ -0,0 +1,15 @@
+- Start Date: (YYYY-MM-DD)
+- RFC PR: https://github.com/rails-api/active_model_serializers/pull/dddd
+- ActiveModelSerializers Issue: https://github.com/rails-api/active_model_serializers/issues/dddd
+
+# Summary
+
+# Motivation
+
+# Detailed design
+
+# Drawbacks
+
+# Alternatives
+
+# Unresolved questions

data/lib/action_controller/serialization.rb

@@ -7,9 +7,6 @@ module ActionController
 
     include ActionController::Renderers
 
-    # Deprecated
-    ADAPTER_OPTION_KEYS = ActiveModel::SerializableResource::ADAPTER_OPTION_KEYS
-
     module ClassMethods
       def serialization_scope(scope)
         self._serialization_scope = scope
@@ -32,21 +29,13 @@ module ActionController
           "Please pass 'adapter: false' or see ActiveSupport::SerializableResource.new"
         options[:adapter] = false
       end
-      serializable_resource = ActiveModel::SerializableResource.new(resource, options)
-      if serializable_resource.serializer?
-        serializable_resource.serialization_scope ||= serialization_scope
-        serializable_resource.serialization_scope_name = _serialization_scope
-        begin
-          # Necessary to ensure we have an adapter for the serializable resource
-          # after it has been figured.
-          # TODO: This logic should be less opaque and probably moved into the SerializableResource.
-          serializable_resource.tap(&:adapter)
-        rescue ActiveModel::Serializer::CollectionSerializer::NoSerializerError
-          resource
-        end
-      else
-        resource
-      end
+      serializable_resource = ActiveModelSerializers::SerializableResource.new(resource, options)
+      serializable_resource.serialization_scope ||= options.fetch(:scope) { serialization_scope }
+      serializable_resource.serialization_scope_name = options.fetch(:scope_name) { _serialization_scope }
+      # For compatibility with the JSON renderer: `json.to_json(options) if json.is_a?(String)`.
+      # Otherwise, since `serializable_resource` is not a string, the renderer would call
+      # `to_json` on a String and given odd results, such as `"".to_json #=> '""'`
+      serializable_resource.adapter.is_a?(String) ? serializable_resource.adapter : serializable_resource
     end
 
     # Deprecated
@@ -56,7 +45,9 @@ module ActionController
 
     [:_render_option_json, :_render_with_renderer_json].each do |renderer_method|
       define_method renderer_method do |resource, options|
-        options.fetch(:serialization_context) { options[:serialization_context] = ActiveModelSerializers::SerializationContext.new(request) }
+        options.fetch(:serialization_context) do
+          options[:serialization_context] = ActiveModelSerializers::SerializationContext.new(request, options)
+        end
         serializable_resource = get_serializer(resource, options)
         super(serializable_resource, options)
       end

data/lib/active_model/serializable_resource.rb

@@ -1,72 +1,11 @@
 require 'set'
+
 module ActiveModel
   class SerializableResource
-    ADAPTER_OPTION_KEYS = Set.new([:include, :fields, :adapter, :meta, :meta_key, :links])
-    include ActiveModelSerializers::Logging
-
-    delegate :serializable_hash, :as_json, :to_json, to: :adapter
-    notify :serializable_hash, :render
-    notify :as_json, :render
-    notify :to_json, :render
-
-    # Primary interface to composing a resource with a serializer and adapter.
-    # @return the serializable_resource, ready for #as_json/#to_json/#serializable_hash.
-    def initialize(resource, options = {})
-      @resource = resource
-      @adapter_opts, @serializer_opts =
-        options.partition { |k, _| ADAPTER_OPTION_KEYS.include? k }.map { |h| Hash[h] }
-    end
-
-    def serialization_scope=(scope)
-      serializer_opts[:scope] = scope
-    end
+    class << self
+      extend ActiveModelSerializers::Deprecate
 
-    def serialization_scope
-      serializer_opts[:scope]
+      delegate_and_deprecate :new, ActiveModelSerializers::SerializableResource
     end
-
-    def serialization_scope_name=(scope_name)
-      serializer_opts[:scope_name] = scope_name
-    end
-
-    def adapter
-      @adapter ||= ActiveModel::Serializer::Adapter.create(serializer_instance, adapter_opts)
-    end
-    alias_method :adapter_instance, :adapter
-
-    def serializer_instance
-      @serializer_instance ||= serializer.new(resource, serializer_opts)
-    end
-
-    # Get serializer either explicitly :serializer or implicitly from resource
-    # Remove :serializer key from serializer_opts
-    # Replace :serializer key with :each_serializer if present
-    def serializer
-      @serializer ||=
-        begin
-          @serializer = serializer_opts.delete(:serializer)
-          @serializer ||= ActiveModel::Serializer.serializer_for(resource)
-
-          if serializer_opts.key?(:each_serializer)
-            serializer_opts[:serializer] = serializer_opts.delete(:each_serializer)
-          end
-          @serializer
-        end
-    end
-    alias_method :serializer_class, :serializer
-
-    # True when no explicit adapter given, or explicit appear is truthy (non-nil)
-    # False when explicit adapter is falsy (nil or false)
-    def use_adapter?
-      !(adapter_opts.key?(:adapter) && !adapter_opts[:adapter])
-    end
-
-    def serializer?
-      use_adapter? && !!(serializer)
-    end
-
-    protected
-
-    attr_reader :resource, :adapter_opts, :serializer_opts
   end
 end