fars 0.0.1 → 0.0.2

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NDg4ZDFkOTVmYmQ0YTQ4MTI1N2I1ZjlmOWI2MThmZDM1ZDUwMTU0OA==
+  data.tar.gz: !binary |-
+    MGIzMDgzZmVhNWM0MzEyMDkzODgzMTZkMjhlNWIyODhmYmRiM2YxMA==
+SHA512:
+  metadata.gz: !binary |-
+    YzhkZWI4MDdmMzExY2M3OGQ0YjhiZmI2NjQ3MzdlYTA4NDEzYTAzOWNjNGJl
+    NDM3YjczZTQ5MmE1YzE2MDdkZGVkZmExNmEzMDI3OGVjZDM2Yjc0OTQyOTg3
+    YTcxZWFlMTEwZWI4NzY0Zjg2ODU3MzI0OWEzZmE2OTYwMjY1ZTM=
+  data.tar.gz: !binary |-
+    NzZkM2FlNmFkNWI3ZTg5NTQ0ZmM3M2NiYjk1MjYyYTM5MzZkYjdkNWNjYjkz
+    OGZmMTEyODliZjQ2MGExOWFmMzAyOWIxZDZlYmI4ODliOGQzMDUwZmY3NjU0
+    YTE5MjdiNWMwMzVlMDUyMTU5YThjNTJlM2EzNjlmYmM1YzRkZWM=

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    fars (0.0.1)
+    fars (0.0.2)
       activerecord (>= 3.2)
 
 GEM

data/README.md

@@ -1,4 +1,260 @@
-fars
-====
+# Fast ActiveRecord Serializer (fars).
 
-Fast ActiveRecord Serializer
+JSON serialization of ActiveRecord models and colections (relations or array of objects). Also can serialzie any Array or Hash with minimal syntax.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'fars'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install fars
+
+## Usage
+
+### Serialize instance (of Class inherited from ActiveRecord::Bace)
+
+```rb
+class Customer < ActiveRecord::Base
+  has_many :orders
+end
+```
+
+Create serializer class named `CustomerSerializer` or `V1::CustomerSerializer`
+
+```rb
+class CustomerSerializer < Fars::BaseModelSerializer
+  attributes :id, :name, :data, # attrs
+                  :created_at, :updated_at, # methods
+                  :orders # relations
+
+  def created_at
+    object.created_at.try(:strftime, "%F %H:%M")
+  end
+
+  def updated_at
+    object.updated_at.try(:strftime, "%F %H:%M")
+  end
+
+  # _metadata (optional)
+  def meta
+    abilities = [:update, :destroy].select { |a| scope.can?(a, object) }
+    { abilities: abilities }
+  end
+end
+```
+
+Then you can call #serialize method on object
+
+```rb
+# Option :scope is optional, can be used for providing metadata.
+Customer.first.serialize scope: current_user
+```
+
+Available options are: `:api_version`, `:serializer`, `:scope`, `:fields`, `:add_metadata`, `:root_key`, `:params`.
+Description of this options provided in [next section](#serialize-relation).
+
+```rb
+customer = Customer.first
+
+# whould be serizlized with CustomerSerializer class
+customer.serialize
+
+# whould be serizlized with V1::CustomerSerializer class
+customer.serialize api_version: 'V1'
+
+# whould be serizlized with V1::ExtendedCustomerSerializer class
+customer.serialize api_version: 'V1', serializer: "ExtendedCustomerSerializer"
+```
+
+You can specify model class and item root key in serializer:
+
+
+```rb
+class ExtendedCustomerSerializer < Fars::BaseModelSerializer
+  self.model = Customer
+  self.root_key = :client
+end
+```
+
+### Serialize relation
+
+```rb
+customers = Customer.where("1 = 1")
+customers.serialize
+```
+
+Available some options
+
+```rb
+customers.serialize
+  root_key: :clients, # collection root key, default whoud be :customers, false if omit
+  api_version: "V1", # namesapce of model serializer class
+  fields: [:id, :name, :updated_at], # array of needed fields
+  scope: current_user, # user or ability, can be used in serializer meta method
+  add_metadata: true, # add or not item metadata, default is true if serializer respond_to? :meta
+  serializer: "ExtendedCustomerSerializer", # custom model serializer class
+  class_name: "Client", # item model class (can construct serializer class name from it), useful for array of objects
+  metadata: { limit: 10, offset: 50 }, # collection metadata (:root_key cannot be omitted)
+  params: { format: 'long' } # any parameters, can be accessed in serializes class
+```
+
+You can override serializers `#available_attributes` method for providing dynamic attributes
+depending on internal serializer's logic.
+
+```rb
+class CustomerSerializer < Fars::BaseModelSerializer
+  attributes :id, :name, :data, # attrs
+                  :created_at, :updated_at, # methods
+                  :orders # relations
+
+  def created_at
+    object.created_at.try(:strftime, "%F %H:%M")
+  end
+
+  def updated_at
+    object.updated_at.try(:strftime, "%F %H:%M")
+  end
+
+  def available_attributes
+     attributes = [:id, :name, :created_at, :updated_at, :orders]
+     attributes << :data if scope.can?(:view_data, object)
+     attributes
+  end
+
+  # _metadata (optional)
+  def meta
+    abilities = [:update, :destroy].select { |a| scope.can?(a, object) }
+    { abilities: abilities }
+  end
+end
+```
+
+### Serialize array of instances
+
+Array of instances can by serialized same as relation. In this case default collection's root_key will be constructed from first element class name (can't be empty array) or from povided class name (class_name option). 
+
+### Serialize any Array
+
+Provide root_key (false if omit) and serializer (proc, block or custom class)
+
+```rb
+array = %w{green blue grey}
+
+# with proc
+array.serialize root_key: :colors,
+  serializer: Proc.new { |c| { color: c }
+
+# with block
+array.serialize(root_key: :colors) { |c| { color: c } }
+
+# with custom class
+class ColorSerializer < Fars::BaseObjectSerializer
+  def as_json
+    { color: object }
+  end
+end
+
+array.serialize(root_key: :colors, serializer: 'ColorSerializer')
+```
+This will produce:
+
+```rb
+{ colors: [
+  { color: 'green' },
+  { color: 'blue' },
+  { color: 'grey' }
+] }.to_json
+```
+
+### Serialize Hash
+
+Provide root_key (false if omit) and serializer (proc, block or custom class)
+
+```rb
+hash = {
+  '2014-01-01' => { visitors: 23, visits: 114 },
+  '2014-01-02' => { visitors: 27, visits: 217 }
+}
+
+# with proc
+hash.serialize root_key: :stats,
+  serializer: Proc.new { |k, v| { day: k, visitors: v[:visitors] } })
+
+# with block
+hash.serialize root_key: :stats do |k, v|
+  { day: k, visitors: v[:visitors] }
+end
+
+# with custom class
+# object in this case is key-value pair
+class StatSerializer < Fars::BaseObjectSerializer
+  def as_json
+    { stat_key: object[0], stat_value: object[1] }
+  end
+end
+
+hash.serialize root_key: :stats, serializer: 'StatSerializer'
+```
+
+This will produce:
+
+```rb
+{ stats: [
+  { day: '2014-01-01', visitors: 23 },
+  { day: '2014-01-02', visitors: 27 }
+] }.to_json
+```
+
+### Serialize any object with serializer inherited from Fars::BaseObjectSerializer
+
+```rb
+Book = Struct.new(:isbn, :title, :author, :price, :count)
+b1 = Book.new('isbn1', 'title1', 'author1', 10, nil)
+b2 = Book.new('isbn2', 'title2', 'author2', 20.0, 4)
+b3 = Book.new('isbn3', 'title3', 'author3', 30.5, 7)
+book = b1
+books = [b1, b2, b3]
+
+class BookSerializer < Fars::BaseObjectSerializer
+  attributes :isbn, :title, :author, # attrs
+             :price, :count # methods
+
+  def price
+    "%.2f" % object.price
+  end
+
+  def count
+    object.count.to_i
+  end
+end
+
+# serializes any object with appropriate serializer
+BookSerializer.new(book, fields: [:isbn, :title, :price]).to_json
+# => { book: { isbn: 'isbn1', title: 'title1', price: '10.00' } }.to_json
+
+# serialize collection
+books.serialize(root_key: :books, # can be resolved automatically for non empty array
+  serializer: 'BookSerializer', # can be resolved automatically for non empty array
+  fields: [:isbn, :title, :price]) # all by default
+
+# => { books: [
+#  { book: { isbn: 'isbn1', title: 'title1', price: '10.00' } },
+#  { book: { isbn: 'isbn2', title: 'title2', price: '20.00' } },
+#  { book: { isbn: 'isbn3', title: 'title3', price: '30.50' } }
+# ] }.to_json
+```
+
+## Contributing
+
+1. Fork it ( http://github.com/Lightpower/fars/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/fars.gemspec

@@ -1,4 +1,4 @@
-# -*- encoding: utf-8 -*-
+# encoding: utf-8
 require File.expand_path('../lib/fars/version', __FILE__)
 
 Gem::Specification.new do |gem|
@@ -15,12 +15,11 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Fars::VERSION
 
-  gem.add_dependency  'activerecord',  '>= 3.2'
+  gem.add_dependency  'activerecord', '>= 3.2'
 
-  gem.add_development_dependency 'rspec',        '>= 2.11'
+  gem.add_development_dependency 'rspec', '>= 2.11'
   gem.add_development_dependency 'rake'
   gem.add_development_dependency 'shoulda'
   gem.add_development_dependency 'pg'
   gem.add_development_dependency 'database_cleaner'
-
 end

data/lib/fars.rb

@@ -1,5 +1,24 @@
-module Fars
-  require 'fars/base_collection_serializer'
-  require 'fars/base_model_serializer'
+require 'active_record'
 
+module Fars; end
+require 'fars/base_object_serializer'
+require 'fars/base_model_serializer'
+require 'fars/base_collection_serializer'
+require 'fars/model_serializable'
+require 'fars/relation_serializable'
+
+class ActiveRecord::Base
+  include Fars::ModelSerializable
+end
+
+class ActiveRecord::Relation
+  include Fars::RelationSerializable
+end
+
+class Array
+  include Fars::RelationSerializable
+end
+
+class Hash
+  include Fars::RelationSerializable
 end

data/lib/fars/base_collection_serializer.rb

@@ -1,72 +1,126 @@
 ##
 # Class: BaseCollectionSerializer
 #
-# It is used to represent collections
+# It is used to represent collection
 #
 class Fars::BaseCollectionSerializer
-  class << self
-    # Returns {String} capitalized API version
-    def api_version
-      namespace_array = name.split('::')
-      namespace_array.size > 1 ? namespace_array[0] : nil
+  ##
+  # Constructor
+  #
+  # Params:
+  #   - objects {ActiveRecord::Relation} or {Array} collection to serialize
+  #   - opts {Hash} of options:
+  #     - fields {Array} of attributes to serialize. Can be {NilClass}.
+  #       If so - will use all available.
+  #     - scope {Object} context of request. Usually current user
+  #       or current ability. Can be passed as a {Proc}. If so -
+  #       evaluated only when actually called.
+  #     - :add_metadata {Boolean} if to add a node '_metadata'
+  #     - :root_key {Symbol} overwrites the default one from serializer's Class
+  #     - :api_version {String} namespace for serializers classes, e.g. "V1"
+  #     - :class_name {String} serialized model class name
+  #     - :serializer {String} model serializer class name
+  #     - :metadata {Hash} optional hash with metadata (root_key should not be false)
+  #
+  def initialize(objects, opts = {}, &block)
+    @objects = objects
+    if !opts.has_key?(:root_key) && !opts[:class_name] && empty_array?
+      raise ArgumentError, 'Specify :root_key or model :class_name for empty array.'
+    end
+    # Cann't use Hash#fetch here, becouse if root_key provided default_root_key method should not be called.
+    @root_key = opts.has_key?(:root_key) ? opts[:root_key] : default_root_key
+    if !@root_key && opts[:metadata]
+      raise ArgumentError, 'Can not omit :root_key if provided :metadata'
+    end
+    # Serialized model class name.
+    @class_name = opts[:class_name]
+    if opts[:serializer]
+      if opts[:serializer].is_a? Proc
+        @item_serializer = opts[:serializer]
+      else
+        @item_serializer_class = opts[:serializer].constantize
+      end
+    elsif block_given?
+      @item_serializer = block
+    end
+    @api_version = opts[:api_version]
+    @params = opts[:params] || {}
+    @metadata = opts[:metadata]
+    # Do not need options if serialize items with proc.
+    unless @item_serializer
+      # Options for model serializer.
+      @options = opts.slice(:scope, :fields, :add_metadata, :api_version, :params)
+      # If root_key is false, do not transfer this option to the model serializer class.
+      @options[:root_key] = item_root_key if @root_key
     end
   end
 
-  def initialize(objects, opts={})
-    @objects      = objects
-    @scope        = opts[:scope]
-    @fields       = opts[:fields]
-    @add_metadata = opts[:add_metadata]
-    @root_key     = opts.fetch(:root_key, get_root_key)
-    @item_serializer_class = get_item_serializer_class
-  end
-
+  ##
+  # Returns: Hash
+  #
   def as_json
     items = []
 
-    the_class = item_serializer_class.new(
-      nil,
-      scope:        @scope,
-      add_metadata: add_metadata,
-      fields:       fields,
-      root_key:     get_instance_root_key,
-    )
+    unless empty_array?
+      @item_serializer ||= item_serializer_class.new(nil, options)
 
-    objects.each do |object|
-      items << the_class.with_object(object).as_json
+      objects.each do |object|
+        items << item_serializer.call(object)
+      end
     end
 
-    root_key ? {root_key => items} : items
+    return items unless root_key
+
+    hash = { root_key => items }
+    hash[:_metadata] = metadata if metadata
+    hash
   end
 
   def to_json
     MultiJson.dump(as_json)
   end
 
-  # Returns {String} - API version is got by instance class
-  def api_version
-    self.class.api_version
-  end
-
 private
 
-  attr_reader :objects, :scope, :fields, :add_metadata, :root_key, :item_serializer_class
+  attr_reader :objects, :options, :root_key, :api_version, :params, :metadata, :item_serializer
+
+  ##
+  # Checks if objets is not ActiveRecord::Relation and it's empty.
+  # In this case impossible to obtain model's class name.
+  #
+  def empty_array?
+    objects.is_a?(Array) && objects.empty?
+  end
 
-  def get_root_key
-    (self.to_s.match /#{api_prefix}(\w+)Serializer/)[1].underscore.to_sym
+  ##
+  # Returns: {String} ActiveRecord Model base_class name
+  #
+  def class_name
+    @class_name ||= if objects.is_a?(ActiveRecord::Relation)
+      objects.klass
+    else
+      objects.first.class
+    end.base_class.to_s
   end
 
-  def get_instance_root_key
-    # If root_key is false, get a real one
-    (root_key || get_root_key).to_s.singularize.to_sym
+  ##
+  # Returns: {Symbol}, requires @class_name
+  #
+  def default_root_key
+    class_name.to_s.underscore.pluralize.to_sym
   end
 
-  def get_item_serializer_class
-    (self.class.to_s.gsub('Serializer', '').singularize + 'Serializer').constantize
+  ##
+  # Returns: {Symbol} or nil
+  #
+  def item_root_key
+    root_key.to_s.singularize.to_sym if root_key
   end
 
-  # Returns {String} prefix for serializer class name using API version
-  def api_prefix
-    api_version ? api_version + '::' : ''
+  ##
+  # Returns: {Class} of Model Serializer
+  #
+  def item_serializer_class
+    @item_serializer_class ||= "#{api_version + '::' if api_version}#{class_name}Serializer".constantize
   end
 end