cheap_ams 0.10.0.rc2

data/docs/general/getting_started.md

@@ -0,0 +1,73 @@
+# Getting Started
+
+## Installation
+
+### ActiveModel::Serializer is already included on Rails >= 5
+
+Add this line to your application's Gemfile:
+
+```
+gem 'active_model_serializers'
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+## Creating a Serializer
+
+The easiest way to create a new serializer is to generate a new resource, which
+will generate a serializer at the same time:
+
+```
+$ rails g resource post title:string body:string
+```
+
+This will generate a serializer in `app/serializers/post_serializer.rb` for
+your new model. You can also generate a serializer for an existing model with
+the serializer generator:
+
+```
+$ rails g serializer post
+```
+
+The generated seralizer will contain basic `attributes` and
+`has_many`/`has_one`/`belongs_to` declarations, based on the model. For example:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :title, :body
+
+  has_many :comments
+  has_one :author
+
+end
+```
+
+and
+
+```ruby
+class CommentSerializer < ActiveModel::Serializer
+  attributes :name, :body
+
+  belongs_to :post_id
+
+end
+```
+
+## Rails Integration
+
+AMS will automatically integrate with you Rails app, you won't need to update your controller, this is a example of how it will look like:
+
+```ruby
+class PostsController < ApplicationController
+
+  def show
+    @post = Post.find(params[:id])
+    render json: @post
+  end
+
+end
+```

data/docs/howto/add_pagination_links.md

@@ -0,0 +1,112 @@
+# How to add pagination links
+
+### JSON-API adapter
+
+Pagination links will be included in your response automatically as long as the resource is paginated and if you are using a ```JSON-API``` adapter.
+
+If you want pagination links in your response, use [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
+
+###### Kaminari examples
+```ruby
+#array
+@posts = Kaminari.paginate_array([1, 2, 3]).page(3).per(1)
+render json: @posts
+
+#active_record
+@posts = Post.page(3).per(1)
+render json: @posts
+```
+
+###### WillPaginate examples
+
+```ruby
+#array
+@posts = [1,2,3].paginate(page: 3, per_page: 1)
+render json: @posts
+
+#active_record
+@posts = Post.page(3).per_page(1)
+render json: @posts
+```
+
+```ruby
+ActiveModel::Serializer.config.adapter = :json_api
+```
+
+ex:
+```json
+{
+  "data": [
+    {
+      "type": "articles",
+      "id": "3",
+      "attributes": {
+        "title": "JSON API paints my bikeshed!",
+        "body": "The shortest article. Ever.",
+        "created": "2015-05-22T14:56:29.000Z",
+        "updated": "2015-05-22T14:56:28.000Z"
+      }
+    }
+  ],
+  "links": {
+    "self": "http://example.com/articles?page[number]=3&page[size]=1",
+    "first": "http://example.com/articles?page[number]=1&page[size]=1",
+    "prev": "http://example.com/articles?page[number]=2&page[size]=1",
+    "next": "http://example.com/articles?page[number]=4&page[size]=1",
+    "last": "http://example.com/articles?page[number]=13&page[size]=1"
+  }
+}
+```
+
+AMS pagination relies on a paginated collection with the methods `current_page`, `total_pages`, and `size`, such as are supported by both [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
+
+
+### JSON adapter
+
+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.
+```ruby
+render json: @posts, serializer: PaginatedSerializer, each_serializer: PostPreviewSerializer
+```
+
+And then, you could do something like the following class.
+```ruby
+class PaginatedSerializer < ActiveModel::Serializer::ArraySerializer
+  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
+```
+ex.
+```json
+{
+  "articles": [
+    {
+      "id": 2,
+      "title": "JSON API paints my bikeshed!",
+      "body": "The shortest article. Ever."
+    }
+  ],
+  "meta": {
+    "current_page": 3,
+    "next_page": 4,
+    "prev_page": 2,
+    "total_pages": 10,
+    "total_count": 10
+  }
+}
+```
+
+### FlattenJSON 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/add_root_key.md

@@ -0,0 +1,51 @@
+# How to add root key
+
+Add the root key to your API is quite simple with AMS. The **Adapter** is what determines the format of your JSON response. The default adapter is the ```FlattenJSON``` which doesn't have the root key, so your response is something similar to:
+
+```json
+{
+  "id": 1,
+  "title": "Awesome Post Tile",
+  "content": "Post content"
+}
+```
+
+In order to add the root key you need to use the ```JSON``` Adapter, you can change this in an initializer:
+
+```ruby
+ActiveModel::Serializer.config.adapter = :json
+```
+
+You can also specify a class as adapter, as long as it complies with the AMS adapters interface.
+It will add the root key to all your serialized endpoints.
+
+ex:
+
+```json
+{
+  "post": {
+    "id": 1,
+    "title": "Awesome Post Tile",
+    "content": "Post content"
+  }
+}
+```
+
+or if it returns a collection:
+
+```json
+{
+  "posts": [
+    {
+      "id": 1,
+      "title": "Awesome Post Tile",
+      "content": "Post content"
+    },
+    {
+      "id": 2,
+      "title": "Another Post Tile",
+      "content": "Another post content"
+    }
+  ]
+}
+```

data/lib/action_controller/serialization.rb

@@ -0,0 +1,62 @@
+require 'active_support/core_ext/class/attribute'
+
+module ActionController
+  module Serialization
+    extend ActiveSupport::Concern
+
+    include ActionController::Renderers
+
+    # Deprecated
+    ADAPTER_OPTION_KEYS = ActiveModel::SerializableResource::ADAPTER_OPTION_KEYS
+
+    included do
+      class_attribute :_serialization_scope
+      self._serialization_scope = :current_user
+    end
+
+    def serialization_scope
+      send(_serialization_scope) if _serialization_scope &&
+        respond_to?(_serialization_scope, true)
+    end
+
+    def get_serializer(resource, options = {})
+      if ! use_adapter?
+        warn "ActionController::Serialization#use_adapter? has been removed. "\
+          "Please pass 'adapter: false' or see ActiveSupport::SerializableResource#serialize"
+        options[:adapter] = false
+      end
+      ActiveModel::SerializableResource.serialize(resource, options) do |serializable_resource|
+        if serializable_resource.serializer?
+          serializable_resource.serialization_scope ||= serialization_scope
+          serializable_resource.serialization_scope_name = _serialization_scope
+          begin
+            serializable_resource.adapter
+          rescue ActiveModel::Serializer::ArraySerializer::NoSerializerError
+            resource
+          end
+        else
+          resource
+        end
+      end
+    end
+
+    # Deprecated
+    def use_adapter?
+      true
+    end
+
+    [:_render_option_json, :_render_with_renderer_json].each do |renderer_method|
+      define_method renderer_method do |resource, options|
+        options.fetch(:context) { options[:context] = request }
+        serializable_resource = get_serializer(resource, options)
+        super(serializable_resource, options)
+      end
+    end
+
+    module ClassMethods
+      def serialization_scope(scope)
+        self._serialization_scope = scope
+      end
+    end
+  end
+end

data/lib/active_model/serializable_resource.rb

@@ -0,0 +1,84 @@
+require 'set'
+module ActiveModel
+  class SerializableResource
+
+    ADAPTER_OPTION_KEYS = Set.new([:include, :fields, :adapter])
+
+    def initialize(resource, options = {})
+      @resource = resource
+      @adapter_opts, @serializer_opts =
+        options.partition { |k, _| ADAPTER_OPTION_KEYS.include? k }.map { |h| Hash[h] }
+    end
+
+    delegate :serializable_hash, :as_json, :to_json, to: :adapter
+
+    # Primary interface to building a serializer (with adapter)
+    # If no block is given,
+    # returns the serializable_resource, ready for #as_json/#to_json/#serializable_hash.
+    # Otherwise, yields the serializable_resource and
+    # returns the contents of the block
+    def self.serialize(resource, options = {})
+      serializable_resource = SerializableResource.new(resource, options)
+      if block_given?
+        yield serializable_resource
+      else
+        serializable_resource
+      end
+    end
+
+    def serialization_scope=(scope)
+      serializer_opts[:scope] = scope
+    end
+
+    def serialization_scope
+      serializer_opts[:scope]
+    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
+
+    private
+
+    ActiveModelSerializers.silence_warnings do
+    attr_reader :resource, :adapter_opts, :serializer_opts
+    end
+
+  end
+end

data/lib/active_model/serializer/adapter/flatten_json.rb

@@ -0,0 +1,19 @@
+module ActiveModel
+  class Serializer
+    class Adapter
+      class FlattenJson < Json
+        def serializable_hash(options = {})
+          super
+          @result
+        end
+
+        private
+
+        # no-op: FlattenJson adapter does not include meta data, because it does not support root.
+        def include_meta(json)
+          json
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/fragment_cache.rb

@@ -0,0 +1,82 @@
+module ActiveModel
+  class Serializer
+    class Adapter
+      class FragmentCache
+
+        attr_reader :serializer
+
+        def initialize(adapter, serializer, options)
+          @options    = options
+          @adapter    = adapter
+          @serializer = serializer
+        end
+
+        def fetch
+          klass = serializer.class
+          # It will split the serializer into two, one that will be cached and other wont
+          serializers = fragment_serializer(serializer.object.class.name, klass)
+
+          # Instanciate both serializers
+          cached_serializer     = serializers[:cached].constantize.new(serializer.object)
+          non_cached_serializer = serializers[:non_cached].constantize.new(serializer.object)
+
+          cached_adapter     = @adapter.class.new(cached_serializer, @options)
+          non_cached_adapter = @adapter.class.new(non_cached_serializer, @options)
+
+          # Get serializable hash from both
+          cached_hash     = cached_adapter.serializable_hash
+          non_cached_hash = non_cached_adapter.serializable_hash
+
+          # Merge both results
+          @adapter.fragment_cache(cached_hash, non_cached_hash)
+        end
+
+        private
+
+        def cached_attributes(klass, serializers)
+          attributes            = serializer.class._attributes
+          cached_attributes     = (klass._cache_only) ? klass._cache_only : attributes.reject {|attr| klass._cache_except.include?(attr) }
+          non_cached_attributes = attributes - cached_attributes
+
+          cached_attributes.each do |attribute|
+            options = serializer.class._attributes_keys[attribute]
+            options ||= {}
+            # Add cached attributes to cached Serializer
+            serializers[:cached].constantize.attribute(attribute, options)
+          end
+
+          non_cached_attributes.each do |attribute|
+            options = serializer.class._attributes_keys[attribute]
+            options ||= {}
+            # Add non-cached attributes to non-cached Serializer
+            serializers[:non_cached].constantize.attribute(attribute, options)
+          end
+        end
+
+        def fragment_serializer(name, klass)
+          cached     = "#{to_valid_const_name(name)}CachedSerializer"
+          non_cached = "#{to_valid_const_name(name)}NonCachedSerializer"
+
+          Object.const_set cached, Class.new(ActiveModel::Serializer) unless Object.const_defined?(cached)
+          Object.const_set non_cached, Class.new(ActiveModel::Serializer) unless Object.const_defined?(non_cached)
+
+          klass._cache_options       ||= {}
+          klass._cache_options[:key] = klass._cache_key if klass._cache_key
+
+          cached.constantize.cache(klass._cache_options)
+
+          cached.constantize.fragmented(serializer)
+          non_cached.constantize.fragmented(serializer)
+
+          serializers = {cached: cached, non_cached: non_cached}
+          cached_attributes(klass, serializers)
+          serializers
+        end
+
+        def to_valid_const_name(name)
+          name.gsub('::', '_')
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/json/fragment_cache.rb

@@ -0,0 +1,16 @@
+require 'active_model/serializer/adapter/fragment_cache'
+module ActiveModel
+  class Serializer
+    class Adapter
+      class Json < Adapter
+        class FragmentCache
+
+          def fragment_cache(cached_hash, non_cached_hash)
+            non_cached_hash.merge cached_hash
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/json.rb

@@ -0,0 +1,53 @@
+require 'active_model/serializer/adapter/json/fragment_cache'
+
+module ActiveModel
+  class Serializer
+    class Adapter
+      class Json < Adapter
+        def serializable_hash(options = nil)
+          options ||= {}
+          if serializer.respond_to?(:each)
+            @result = serializer.map { |s| FlattenJson.new(s).serializable_hash(options) }
+          else
+            @hash = {}
+
+            @core = cache_check(serializer) do
+              serializer.attributes(options)
+            end
+
+            serializer.associations.each do |association|
+              serializer = association.serializer
+              opts = association.options
+
+              if serializer.respond_to?(:each)
+                array_serializer = serializer
+                @hash[association.key] = array_serializer.map do |item|
+                  cache_check(item) do
+                    item.attributes(opts)
+                  end
+                end
+              else
+                @hash[association.key] =
+                  if serializer && serializer.object
+                    cache_check(serializer) do
+                      serializer.attributes(options)
+                    end
+                  elsif opts[:virtual_value]
+                    opts[:virtual_value]
+                  end
+              end
+            end
+            @result = @core.merge @hash
+          end
+
+          { root => @result }
+        end
+
+        def fragment_cache(cached_hash, non_cached_hash)
+          Json::FragmentCache.new().fragment_cache(cached_hash, non_cached_hash)
+        end
+
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/json_api/fragment_cache.rb

@@ -0,0 +1,24 @@
+require 'active_model/serializer/adapter/fragment_cache'
+module ActiveModel
+  class Serializer
+    class Adapter
+      class JsonApi < Adapter
+        class FragmentCache
+
+          def fragment_cache(root, cached_hash, non_cached_hash)
+            hash              = {}
+            core_cached       = cached_hash.first
+            core_non_cached   = non_cached_hash.first
+            no_root_cache     = cached_hash.delete_if {|key, value| key == core_cached[0] }
+            no_root_non_cache = non_cached_hash.delete_if {|key, value| key == core_non_cached[0] }
+            cached_resource   = (core_cached[1]) ? core_cached[1].deep_merge(core_non_cached[1]) : core_non_cached[1]
+            hash = (root) ? { root => cached_resource } : cached_resource
+
+            hash.deep_merge no_root_non_cache.deep_merge no_root_cache
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/active_model/serializer/adapter/json_api/pagination_links.rb

@@ -0,0 +1,58 @@
+module ActiveModel
+  class Serializer
+    class Adapter
+      class JsonApi < Adapter
+        class PaginationLinks
+          FIRST_PAGE = 1
+
+          attr_reader :collection, :context
+
+          def initialize(collection, context)
+            @collection = collection
+            @context = context
+          end
+
+          def serializable_hash(options = {})
+            pages_from.each_with_object({}) do |(key, value), hash|
+              params = query_parameters.merge(page: { number: value, size: collection.size }).to_query
+
+              hash[key] = "#{url(options)}?#{params}"
+            end
+          end
+
+          private
+
+          def pages_from
+            return {} if collection.total_pages == FIRST_PAGE
+
+            {}.tap do |pages|
+              pages[:self] = collection.current_page
+
+              unless collection.current_page == FIRST_PAGE
+                pages[:first] = FIRST_PAGE
+                pages[:prev]  = collection.current_page - FIRST_PAGE
+              end
+
+              unless collection.current_page == collection.total_pages
+                pages[:next] = collection.current_page + FIRST_PAGE
+                pages[:last] = collection.total_pages
+              end
+            end
+          end
+
+          def url(options)
+            @url ||= options.fetch(:links, {}).fetch(:self, nil) || original_url
+          end
+
+          def original_url
+            @original_url ||= context.original_url[/\A[^?]+/]
+          end
+
+          def query_parameters
+            @query_parameters ||= context.query_parameters
+          end
+        end
+      end
+    end
+  end
+end