granola 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9d89e36c1e6cf872c3e3fafff7ddabd364af6a20
+  data.tar.gz: 292659322f51f57ba16ad7a47cda7aa366ce2362
+SHA512:
+  metadata.gz: 6a5f68618ec9682f837db0a45b033bf850dc256875d3b26fcad3b187a26401bcd0bc569fc3512ab63e29781a7e2215838670de4695b31fbc568a3251276d761a
+  data.tar.gz: e64ee844b50f5ee5b2081988406bf408f9b3bd51e35e406795b3c188b078c32a3a0b2dd8059df701471de60b9e094fa436f54b4fee87d2d787f50dbb4cc17f11

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Nicolas Sanguinetti <hi@nicolassanguinetti.info>
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,87 @@
+# Granola, a JSON serializer
+
+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.
+
+## Example
+
+``` ruby
+class PersonSerializer < Granola::Serializer
+  def attributes
+    {
+      "name" => object.name,
+      "email" => object.email,
+      "age" => object.age
+    }
+  end
+end
+
+PersonSerializer.new(person).to_json #=> '{"name":"John Doe",...}'
+```
+
+## Install
+
+    gem install granola
+
+## JSON serialization
+
+Granola doesn't make assumptions about your code, so it shouldn't depend on a
+specific JSON backend. It uses [MultiJson][] to serialize your objects with your
+favorite backend.
+
+Try to avoid using the default, which is the `stdlib`'s pure-ruby JSON library,
+since it's slow. If in doubt, I like [Yajl][].
+
+If you want to pass options to `MultiJson` (like `pretty: true`), any keywords
+passed to `#to_json` will be forwarded to `MultiJson.dump`.
+
+[MultiJson]: https://github.com/intridea/multi_json
+[Yajl]: https://github.com/brianmario/yajl-ruby
+
+## Handling lists of models
+
+A Granola serializer can handle a list of entities of the same type by using the
+`Serializer.list` method (instead of `Serializer.new`). For example:
+
+``` ruby
+serializer = PersonSerializer.list(Person.all)
+serializer.to_json #=> '[{"name":"John Doe",...},{...}]'
+```
+
+## Rack Helpers
+
+If your application is based on rack, you have a `Rack::Response` called `res`
+in your context, and you have an `env` method that returns the Rack env hash,
+you can simply `include Granola::Rack` and you get access to the following
+interface:
+
+``` ruby
+json(person) #=> This will try to infer PersonSerializer from a Person instance
+json(person, with: AnotherSerializer)
+```
+
+*NOTE*: This works out of the box in frameworks like [Cuba][] or [Roda][]. You
+might need to provide glue code to make `res` and/or `env` available in other
+frameworks.
+
+[Cuba]: https://github.com/soveran/cuba
+[Roda]: https://github.com/jeremyevans/roda
+
+## Caching
+
+`Granola::Serializer` gives you to methods that you can implement in your
+serializers, `last_modified` and `cache_key`, that will be used to prevent
+rendering JSON at all if possible, when using the `Granola::Rack#json` helper.
+
+If your serializer implements this method, and the `env` has the appropriate
+`If-Modified-Since` or `If-None-Match` headers, the helper will automatically
+return a 304 response.
+
+Plus, it sets appropriate `ETag` and `Last-Modified` so your clients can avoid
+hitting the endpoint altogether.
+
+## License
+
+This project is shared under the MIT license. See the attached LICENSE file for
+details.

data/lib/granola/caching.rb

@@ -0,0 +1,37 @@
+require "granola"
+
+module Granola
+  # Mixin to add caching-awareness to Serializers.
+  module Caching
+    # Public: Provides a key that's unique to the current representation of the
+    # JSON object generated by the serializer. This will be MD5'd to become the
+    # ETag header that will be sent in responses.
+    #
+    # Returns a String or `nil`, indicaing that no ETag should be sent.
+    def cache_key
+    end
+
+    # Public: Provides the date of last modification of this entity. This will
+    # become the Last-Modified header that will be sent in responses, if
+    # present.
+    #
+    # Returns a Time or `nil`, indicating that no Last-Modified should be sent.
+    def last_modified
+    end
+  end
+
+  class Serializer
+    include Caching
+  end
+
+  class List < Serializer
+    def cache_key
+      all = @list.map(&:cache_key).compact
+      all.join("-") if all.any?
+    end
+
+    def last_modified
+      @list.map(&:last_modified).compact.sort.last
+    end
+  end
+end

data/lib/granola/helper.rb

@@ -0,0 +1,44 @@
+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.
+  #
+  # 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)
+    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
+    const_get("#{object.class.name}Serializer")
+  end
+
+  # Internal: Null serializer that transparently handles rendering `nil` in case
+  # it's passed.
+  class NilClassSerializer < Granola::Serializer
+    def attributes
+      {}
+    end
+  end
+end

data/lib/granola/rack.rb

@@ -0,0 +1,128 @@
+require "digest/md5"
+require "time"
+require "granola"
+require "granola/helper"
+require "granola/caching"
+
+# 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
+
+  # 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, and of controlling whether the object should
+  # be rendered at all or not (issuing a 304 response in this case).
+  #
+  # This expects the class mixing in this module to implement two methods:
+  # `res`, that should be a Rack::Response, and `env`, that should be a Rack
+  # environment hash.
+  #
+  # 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.
+  #   **json_options: Any other keywords passed will be forwarded to the
+  #                   serializer's `#to_json` call.
+  #
+  # 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 json(object, with: nil, **json_options)
+    serializer = serializer_for(object, with: with)
+
+    if serializer.last_modified
+      res["Last-Modified".freeze] = serializer.last_modified.httpdate
+    end
+
+    if serializer.cache_key
+      res["ETag".freeze] = Digest::MD5.hexdigest(serializer.cache_key)
+    end
+
+    stale_check = StaleCheck.new(
+      env, last_modified: serializer.last_modified, etag: serializer.cache_key
+    )
+
+    if stale_check.fresh?
+      res.status = 304
+    else
+      json_string = serializer.to_json(json_options)
+      res["Content-Type".freeze] = serializer.mime_type
+      res["Content-Length".freeze] = json_string.length.to_s
+      res.write(json_string)
+    end
+  end
+
+  # Internal: Check whether a request is fresh or stale by both modified time
+  # and/or etag.
+  class StaleCheck
+    # Internal: Get the env Hash of the request.
+    attr_reader :env
+
+    # Internal: Get the Time at which the domain model was last-modified.
+    attr_reader :last_modified
+
+    # Internal: Get the String with the ETag ggenerated by this domain model.
+    attr_reader :etag
+
+    IF_MODIFIED_SINCE = "HTTP_IF_MODIFIED_SINCE".freeze
+    IF_NONE_MATCH = "HTTP_IF_NONE_MATCH".freeze
+
+    # Public: Initialize the check.
+    #
+    # env - Rack's env Hash.
+    #
+    # Keywords:
+    #   last_modified: The Time at which the domain model was last modified, if
+    #                  applicable (Defaults to `nil`).
+    #   etag:          The HTTP ETag for this domain model, if applicable
+    #                  (Defaults to `nil`).
+    def initialize(env, last_modified: nil, etag: nil)
+      @env = env
+      @last_modified = last_modified
+      @etag = etag
+    end
+
+    # Public: Checks whether the request is fresh. A fresh request is one that
+    # is stored in the client's cache and doesn't need updating (so it can be
+    # responded to with a 304 response).
+    #
+    # Returns Boolean.
+    def fresh?
+      fresh_by_time? || fresh_by_etag?
+    end
+
+    # Public: Returns a Boolean denoting whether the request is stale (i.e. not
+    # fresh).
+    def stale?
+      !fresh?
+    end
+
+    # Internal: Checks if a request is fresh by modified time, if applicable, by
+    # comparing the `If-Modified-Since` header with the last modified time of
+    # the domain model.
+    #
+    # Returns Boolean.
+    def fresh_by_time?
+      return false unless env.key?(IF_MODIFIED_SINCE) && !last_modified.nil?
+      if_modified_since = Time.parse(env.fetch(IF_MODIFIED_SINCE))
+      last_modified <= if_modified_since
+    end
+
+    # Internal: Checks if a request is fresh by etag, if applicable, by
+    # comparing the `If-None-Match` header with the ETag for the domain model.
+    #
+    # Returns Boolean.
+    def fresh_by_etag?
+      return false unless env.key?(IF_NONE_MATCH) && !etag.nil?
+      if_none_match = env.fetch(IF_NONE_MATCH, "").split(/\s*,\s*/)
+      return false if if_none_match.empty?
+      return true if if_none_match.include?("*".freeze)
+      if_none_match.any? { |tag| tag == etag }
+    end
+  end
+end

data/lib/granola/version.rb

@@ -0,0 +1,3 @@
+module Granola
+  VERSION = "0.0.1"
+end

data/lib/granola.rb

@@ -0,0 +1,84 @@
+require "multi_json"
+require "granola/version"
+
+module Granola
+  # A Serializer describes how to serialize a certain type of object, by
+  # declaring the structure of JSON objects.
+  class Serializer
+    attr_reader :object
+
+    # 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)
+      List.new(ary, 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 the Hash of attributes that should be serialized into
+    # JSON.
+    #
+    # Raises NotImplementedError unless you override in subclasses.
+    def attributes
+      fail NotImplementedError
+    end
+
+    # Public: Generate the JSON string using the current MultiJson adapter.
+    #
+    # **options - Any options valid for `MultiJson.dump`.
+    #
+    # Returns a String.
+    def to_json(**options)
+      MultiJson.dump(attributes, 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`).
+    #
+    # Returns a String.
+    def mime_type
+      "application/json".freeze
+    end
+  end
+
+  # Internal: The List serializer provides an interface for serializing lists of
+  # objects, wrapping around a specific serializer.
+  #
+  # Example:
+  #
+  #   serializer = Granola::List.new(people, 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.
+    # serializer - A subclass of Granola::Serializer.
+    def initialize(list, serializer)
+      @item_serializer = serializer
+      @list = list.map { |obj| serializer.new(obj) }
+    end
+
+    # Public: Returns an Array of Hashes that can be serialized into JSON.
+    def attributes
+      @list.map(&:attributes)
+    end
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: granola
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Nicolas Sanguinetti
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-09-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: cutest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+description: Granola is a very simple and fast library to turn your models to JSON
+email:
+- contacto@nicolassanguinetti.info
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- 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
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: 'Granola: JSON Serializers for your app.'
+test_files: []