granola 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bf1c567fa58a115fc7f8d55fa10ca0e0d482baa9
-  data.tar.gz: a6c5f64bf66e7445fc3f11c48ff046d66fd701c6
+  metadata.gz: 6b87c4322ddf8aa97dd49c26607172fe2119d681
+  data.tar.gz: 959742990805ff8890d821177d1c70c5804e5c18
 SHA512:
-  metadata.gz: a6918a2d025d20e08ea0f2756adafaa5d0dbf5134a2ad05059edfff3eba26e31d36ffbd7d0ae72a394243edad1d125317b09b40e4eb02aeba0fd31a2eb3e3e55
-  data.tar.gz: 2117365b5ee8f946ab307a6d2020d8beb0173d06adb26fd3e974272cfa95a8911f348ca5e78023f9c0b1755c6e21fceb332f45d76bb87a947050eae907e63284
+  metadata.gz: 4cbdca00522d796177eaa836f822355fbda7959033b71a1eefaea8ceac9dcf48517fd8395c628cf3ab137fa30433d8e66e7a063eb74a42c88be8560caac63251
+  data.tar.gz: 05a3665f2b5e13385c014de61e6a213520a339ae162159ca4e86f5e753dc506c2ad2d02016119aa016198ae25b5fa56ffac28ec9e6f5ee5f0f08f1f208ba4240

data/README.md

@@ -1,8 +1,7 @@
-# Granola, a JSON serializer [![Build Status](https://travis-ci.org/foca/granola.svg?branch=master)](https://travis-ci.org/foca/granola)
+# Granola, a JSON serializer [![Build Status](https://img.shields.io/travis/foca/granola.svg)](https://travis-ci.org/foca/granola) [![RubyGem](https://img.shields.io/gem/v/granola.svg)](https://rubygems.org/gems/granola)
 
 ![A tasty bowl of Granola](https://cloud.githubusercontent.com/assets/437/4827156/9e8d33da-5f76-11e4-8574-7803e84845f2.JPG)
 
-
 Granola aims to provide a simple interface to generate JSON responses based on
 your application's domain models. It doesn't make assumptions about anything and
 gets out of your way. You just write plain ruby.
@@ -11,7 +10,7 @@ gets out of your way. You just write plain ruby.
 
 ``` ruby
 class PersonSerializer < Granola::Serializer
-  def serialized
+  def data
     {
       "name" => object.name,
       "email" => object.email,
@@ -38,7 +37,9 @@ Granola.json = Yajl::Encoder.method(:encode)
 ```
 
 If your project already uses [MultiJson][] then we will default to whatever it's
-using, so you shouldn't worry.
+using, so you shouldn't worry. Be warned that using MultiJson instead of
+using a library (such as Yajl) straight away incurs a small performance penalty
+(see, and run, [the benchmark](./benchmarks/multi_json.rb)).
 
 [Yajl]: https://github.com/brianmario/yajl-ruby
 [MultiJson]: https://github.com/intridea/multi_json
@@ -63,10 +64,6 @@ granola(person) #=> This will infer PersonSerializer from a Person instance
 granola(person, with: AnotherSerializer)
 ```
 
-*NOTE* The method relies on being an `env` method that returns the Rack
-environment Hash in the same context where you call the method. See [the
-documentation](./lib/granola/rack.rb) for further details.
-
 This method returns a Rack response tuple that you can use like so (this example
 uses [Cuba][], but similar code will work for other frameworks):
 
@@ -99,7 +96,7 @@ generating the JSON response altogether. For example, using Cuba:
 
 ``` ruby
 class UserSerializer < Granola::Serializer
-  def serialized
+  def data
     { "id" => object.id, "name" => object.name, "email" => object.email }
   end
 
@@ -141,12 +138,12 @@ class BaseSerializer < Granola::Serializer
   MIME_TYPES[:msgpack] = "application/x-msgpack".freeze
 
   def to_msgpack(*)
-    MsgPack.pack(serialized)
+    MsgPack.pack(data)
   end
 end
 ```
 
-Now all serializers that inherit from `BaseSerializer` can be serialized into
+Now all serializers that inherit from `BaseSerializer` can be data into
 MsgPack. In order to use this from our Rack helpers, you'd do:
 
 ``` ruby
@@ -159,5 +156,7 @@ This will set the correct MIME type.
 
 ## License
 
-This project is shared under the MIT license. See the attached LICENSE file for
-details.
+This project is shared under the MIT license. See the attached [LICENSE][] file
+for details.
+
+[LICENSE]: ./LICENSE

data/lib/granola.rb

@@ -1,117 +1,4 @@
 require "granola/version"
-require "json"
-
-module Granola
-  class << self
-    # Public: Get/Set a Proc that takes an Object and a Hash of options and
-    # returns a JSON String.
-    #
-    # The default implementation uses the standard library's JSON module, but
-    # you're welcome to swap it out.
-    #
-    # Example:
-    #
-    #   require "yajl"
-    #   Granola.json = ->(obj, **opts) { Yajl::Encoder.encode(obj, opts) }
-    attr_accessor :json
-  end
-
-  if defined?(MultiJson)
-    self.json = MultiJson.method(:dump)
-  else
-    self.json = JSON.method(:generate)
-  end
-
-  # A Serializer describes how to serialize a certain type of object, by
-  # declaring the structure of JSON objects.
-  class Serializer
-    attr_reader :object
-
-    # Public: Map of the default MIME type for each given type of serialization
-    # for this object.
-    MIME_TYPES = { json: "application/json".freeze }
-
-    # Public: Instantiates a list serializer that wraps around an iterable of
-    # objects of the type expected by this serializer class.
-    #
-    # Example:
-    #
-    #   serializer = PersonSerializer.list(people)
-    #   serializer.to_json
-    #
-    # Returns a Granola::List.
-    def self.list(ary, *args)
-      List.new(ary, *args, with: self)
-    end
-
-    # Public: Initialize the serializer with a given object.
-    #
-    # object - The domain model that we want to serialize into JSON.
-    def initialize(object)
-      @object = object
-    end
-
-    # Public: Returns a primitive Object that can be serialized into JSON,
-    # meaning one of `nil`, `true`, `false`, a String, a Numeric, an Array of
-    # primitive objects, or a Hash with String keys and primitive objects as
-    # values.
-    #
-    # Raises NotImplementedError unless you override in subclasses.
-    def serialized
-      fail NotImplementedError
-    end
-
-    # Public: Generate the JSON String.
-    #
-    # **options - Any options to be passed to the `Granola.json` Proc.
-    #
-    # Returns a String.
-    def to_json(**options)
-      Granola.json.(serialized, options)
-    end
-
-    # Public: Returns the MIME type generated by this serializer. By default
-    # this will be `application/json`, but you can override in your serializers
-    # if your API uses a different MIME type (e.g. `application/my-app+json`).
-    #
-    # type - A Symbol describing the expected mime type.
-    #
-    # Returns a String.
-    def mime_type(type = :json)
-      MIME_TYPES.fetch(type)
-    end
-  end
-
-  # Internal: The List serializer provides an interface for serializing lists of
-  # objects, wrapping around a specific serializer. The preferred API for this
-  # is to use `Granola::Serializer.list`.
-  #
-  # Example:
-  #
-  #   serializer = Granola::List.new(people, with: PersonSerializer)
-  #   serializer.to_json
-  #
-  # You should use Serializer.list instead of this class.
-  class List < Serializer
-    # Internal: Get the serializer class to use for each item of the list.
-    attr_reader :item_serializer
-
-    # Public: Instantiate a new list serializer.
-    #
-    # list  - An Array-like structure.
-    # *args - Any other arguments that the item serializer takes.
-    #
-    # Keywords:
-    #   with: The subclass of Granola::Serializer to use when serializing
-    #         specific elements in the list.
-    def initialize(list, *args, with: serializer)
-      @item_serializer = with
-      @list = list.map { |obj| @item_serializer.new(obj, *args) }
-    end
-
-    # Public: Returns an Array of Hashes that can be serialized into JSON.
-    def serialized
-      @list.map(&:serialized)
-    end
-  end
-end
+require "granola/serializer"
+require "granola/json"
+require "granola/rack"

data/lib/granola/caching.rb

@@ -1,4 +1,4 @@
-require "granola"
+require "granola/serializer"
 
 module Granola
   # Mixin to add caching-awareness to Serializers.

data/lib/granola/rack.rb

@@ -1,58 +1,60 @@
 require "digest/md5"
 require "time"
-require "granola"
-require "granola/helper"
+require "granola/serializer"
+require "granola/util"
 require "granola/caching"
+require "granola/json"
 
-# Mixin to render JSON in the context of a Rack application. See the #json
-# method for the specifics.
-module Granola::Rack
-  def self.included(base)
-    base.send(:include, Granola::Helper)
-  end
+module Granola
+  # Mixin to render JSON in the context of a Rack application. See the #json
+  # method for the specifics.
+  module Rack
+    # Public: Renders a JSON representation of an object using a
+    # Granola::Serializer. This takes care of setting the `Last-Modified` and
+    # `ETag` headers if appropriate.
+    #
+    # You can customize the response tuple by passing the status and the default
+    # headers, as in the following example:
+    #
+    #   granola(user, status: 400, headers: { "X-Error" => "Boom!" })
+    #
+    # object - An object to serialize into JSON.
+    #
+    # Keywords:
+    #   with:    A specific serializer class to use. If this is `nil`,
+    #            `Util.serializer_class_for` will be used to infer the
+    #            serializer class.
+    #   as:      A Symbol with the type of serialization desired. Defaults to
+    #            `:json` (and it's the only one available by default), but could
+    #            be expanded with plugins to provide serialization to, for
+    #            example, MsgPack.
+    #   status:  The HTTP status to return on stale responses. Defaults to `200`
+    #   headers: A Hash of default HTTP headers. Defaults to an empty Hash.
+    #   **opts:  Any other keywords passed will be forwarded to the serializer's
+    #            serialization backend call.
+    #
+    # Raises NameError if no specific serializer is provided and we fail to
+    # infer one for this object.
+    #
+    # Returns a Rack response tuple.
+    def granola(object, with: nil, status: 200, headers: {}, as: :json, **opts)
+      serializer = Granola::Util.serializer_for(object, with: with)
 
-  # Public: Renders a JSON representation of an object using a
-  # Granola::Serializer. This takes care of setting the `Last-Modified` and
-  # `ETag` headers if appropriate.
-  #
-  # You can customize the response tuple by passing the status and the default
-  # headers, as in the following example:
-  #
-  #   granola(user, status: 400, headers: { "X-Error" => "Boom!" })
-  #
-  # object - An object to serialize into JSON.
-  #
-  # Keywords:
-  #   with:    A specific serializer class to use. If this is `nil`,
-  #            `Helper.serializer_class_for` will be used to infer the
-  #            serializer class.
-  #   as:      A Symbol with the type of serialization desired. Defaults to
-  #            `:json` (and it's the only one available with Granola by default)
-  #            but could be expanded with plugins to provide serialization to,
-  #            for example, MsgPack.
-  #   status:  The HTTP status to return on stale responses. Defaults to `200`.
-  #   headers: A Hash of default HTTP headers. Defaults to an empty Hash.
-  #   **opts:  Any other keywords passed will be forwarded to the serializer's
-  #            serialization backend call.
-  #
-  # Raises NameError if no specific serializer is provided and we fail to infer
-  #   one for this object.
-  # Returns a Rack response tuple.
-  def granola(object, with: nil, status: 200, headers: {}, as: :json, **opts)
-    serializer = serializer_for(object, with: with)
+      if serializer.last_modified
+        headers["Last-Modified".freeze] = serializer.last_modified.httpdate
+      end
 
-    if serializer.last_modified
-      headers["Last-Modified".freeze] = serializer.last_modified.httpdate
-    end
+      if serializer.cache_key
+        headers["ETag".freeze] = Digest::MD5.hexdigest(serializer.cache_key)
+      end
 
-    if serializer.cache_key
-      headers["ETag".freeze] = Digest::MD5.hexdigest(serializer.cache_key)
-    end
+      headers["Content-Type".freeze] = serializer.mime_type(as)
 
-    headers["Content-Type".freeze] = serializer.mime_type(as)
+      body = Enumerator.new do |yielder|
+        yielder << serializer.public_send(:"to_#{as}", opts)
+      end
 
-    body = Enumerator.new { |y| y << serializer.public_send(:"to_#{as}", opts) }
-
-    [status, headers, body]
+      [status, headers, body]
+    end
   end
 end

data/lib/granola/version.rb

@@ -1,3 +1,3 @@
 module Granola
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: granola
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Nicolas Sanguinetti
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-15 00:00:00.000000000 Z
+date: 2015-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cutest
@@ -49,7 +49,6 @@ files:
 - README.md
 - lib/granola.rb
 - lib/granola/caching.rb
-- lib/granola/helper.rb
 - lib/granola/rack.rb
 - lib/granola/version.rb
 homepage: http://github.com/foca/granola

data/lib/granola/helper.rb

@@ -1,53 +0,0 @@
-require "granola"
-
-module Granola::Helper
-  # Public: Returns the serializer object for rendering a specific object. The
-  # class will attempt to be inferred based on the class of the passed object,
-  # but a specific serializer can be passed via a keyword argument `with`.
-  #
-  # object - The Object to serialize.
-  #
-  # Keywords
-  #   with: A specific serializer class to use. If this is `nil`,
-  #         `Helper.serializer_class_for` will be used to infer the serializer
-  #         class. This is ignored if `object` is already a Granola::Serializer.
-  #
-  # Raises NameError if no specific serializer is provided and we fail to infer
-  #   one for this object.
-  # Returns an instance of a Granola::Serializer subclass.
-  def serializer_for(object, with: nil)
-    return object if Granola::Serializer === object
-    serializer_class = with || Granola::Helper.serializer_class_for(object)
-    method = object.respond_to?(:to_ary) ? :list : :new
-    serializer_class.send(method, object)
-  end
-
-  # Internal: Infers the name of a serialized based on the class of the passed
-  # object. The pattern is the Object's class + "Serializer". So
-  # `PersonSerializer` for `Person`.
-  #
-  # object - An object of a class with a matching serializer.
-  #
-  # Raises NameError if no matching class exists.
-  # Returns a Class.
-  def self.serializer_class_for(object)
-    object = object.respond_to?(:to_ary) ? object.to_ary.fetch(0, nil) : object
-    name = object.class.name
-    Object.const_get("%sSerializer" % name)
-  rescue NameError
-    case object
-    when NilClass, TrueClass, FalseClass, Numeric, String
-      PrimitiveTypesSerializer
-    else
-      raise
-    end
-  end
-
-  # Internal: Null serializer that transparently handles rendering `nil` in case
-  # it's passed.
-  class PrimitiveTypesSerializer < Granola::Serializer
-    def serialized
-      object
-    end
-  end
-end