yaks 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f3292feb7cef328921828cc97b68f397d23b7269
-  data.tar.gz: 0d074d9a0ea85e905d22572182904fe4f6fb3e36
+  metadata.gz: 40c42f259955a15a723d0782ab4378201bf511b3
+  data.tar.gz: 360a9de28a43b27cf820c26aec19c6627a7dac2b
 SHA512:
-  metadata.gz: a61962b2c69d90ba0b4ccbd2223bc14b27e0ee5ae773bcb12392c7d5bb9a9969497e5e86ae85761ebbab732230dd14f59dc3e8241b35282d9630c39b5c0f41fe
-  data.tar.gz: 12d9e712b28185dc1409518045da51d4eb4a9fd32c7be42a55747e7fd33b4698728a3c46bf170f54183576f7437eafa54db795fb13d4177594b9de62ed418165
+  metadata.gz: 5fb54a5b204c60f385aa4b8e4915c6fce1c89dcb1340b48323242c4ade3a4265d44a5ff37f5d587302cab90ad6e05003e160e290fe69b36f19285934d94f3faf
+  data.tar.gz: 5d4462422ddd28e6106846a8663fbdb43bf2ad33b302c24bdcc0f424edae60d1774455d0f70cd3041422aafdd6d0d6ee697558942026ac1bd84d66f149816748

data/CHANGELOG.md

@@ -1,10 +1,17 @@
+# v0.4.1
+
+* Change how env is passed to yaks.serialize to match docs
+* Fix JSON-API bug (#18 reported by Nicolas Blanco)
+* Don't pluralize has_one association names in JSON-API
+
 # v0.4.0
 
 * Introduce after {} post-processing hook
-* Streamline interfaces and variable names
+* Streamline interfaces and variable names, especially the use of `call`
 * Improve deriving mappers automatically, even with Rails style autoloading
 * Give CollectionResource a members_rel, for HAL-like formats with no top-level collection concept
-* Switch back to using `src` and `dest` as the rel-template keys
+* Switch back to using `src` and `dest` as the rel-template keys, instead of `association_name`
+* deprecate `mapper_namespace` in favor of `namespace`
 
 # v0.4.0.rc1
 

data/README.md

@@ -16,8 +16,6 @@
 
 Yaks is a tool for turning your domain models into Hypermedia resources.
 
-**If you're just starting out with Yaks it is currently recommended to run directly from master until 0.4.0 comes out.**
-
 There are at the moment a number of competing media types for building Hypermedia APIs. These all add a layer of semantics on top of a low level serialization format such as JSON or XML. Even though they each have their own design goals, the core features mostly overlap. They typically provide a way to represent resources (entities), and resource collections, consisting of
 
 * Data in key-value format, possibly with composite values
@@ -64,29 +62,13 @@ or a bit more elaborate
 ```ruby
 yaks = Yaks.new do
   default_format :json_api
-  rel_template 'http://api.example.com/rels/{association_name}'
+  rel_template 'http://api.example.com/rels/{dest}'
   format_options(:hal, plural_links: [:copyright])
 end
 
 yaks.serialize(post, mapper: PostMapper, format: :hal)
 ```
 
-Yaks by default will find your mappers for you if they follow the naming convention of appending 'Mapper' to the model class name. This (and all other "conventions") can be easily redefined though, see below. If you have your mappers inside a module, use `mapper_namespace`.
-
-```ruby
-module API
-  module Mappers
-    class PostMapper < Yaks::Mapper
-      #...
-    end
-  end
-end
-
-yaks = Yaks.new do
-  mapper_namespace API::Mappers
-end
-```
-
 ### Attributes
 
 Use the `attributes` DSL method to specify which attributes of your model you want to expose, as in the example above. You can override the `load_attribute` method to change how attributes are fetched from the model.
@@ -178,6 +160,80 @@ Options
 * `:collection_mapper` : For mapping the collection as a whole, this defaults to Yaks::CollectionMapper, but you can subclass it for example to add links or attributes on the collection itself
 * `:rel` : Set the relation (symbol or URI) this association has with the object. Will be derived from the association name and the configured rel_template if ommitted
 
+## Namespace
+
+Yaks by default will find your mappers for you if they follow the naming convention of appending 'Mapper' to the model class name. This (and all other "conventions") can be easily redefined though, see below. If you have your mappers inside a module, use `namespace`.
+
+```ruby
+module API
+  module Mappers
+    class PostMapper < Yaks::Mapper
+      #...
+    end
+  end
+end
+
+yaks = Yaks.new do
+  namespace API::Mappers
+end
+```
+
+If your namespace contains a `CollectionMapper`, Yaks will use that instead of `Yaks::CollectionMapper`, e.g.
+
+```ruby
+module API
+  module Mappers
+    class CollectionMapper < Yaks::CollectionMapper
+      link :profile, 'http://api.example.com/profiles/collection'
+    end
+  end
+end
+```
+
+You can also have collection mappers based on the type of members the collection holds, e.g.
+
+```ruby
+module API
+  module Mappers
+    class LineItemCollectionMapper < Yaks::CollectionMapper
+      link :profile, 'http://api.example.com/profiles/line_items'
+      attributes :total
+
+      def total
+        collection.inject(0) do |memo, line_item|
+          memo + line_item.price * line_item.quantity
+        end
+      end
+    end
+  end
+end
+```
+
+Yaks will automatically detect and use this collection when serializing an array of `LineItem` objects.
+
+## Rack env
+
+When serializing, Yaks lets you pass in an `env` hash, which will be made available to all mappers.
+
+```ruby
+yaks = Yaks.new
+yaks.serialize(foo, env: my_env)
+
+class FooMapper
+  attributes :bar
+
+  def bar
+    if env['something']
+      #...
+    end
+  end
+end
+```
+
+You can use this to pass around context, in particular context related to the current HTTP request, e.g. the current logged in user, which is why the recommended use is to pass in the Rack environment.
+
+If `env` contains a `HTTP_ACCEPT` key (Rack's way of representing the `Accept` header), Yaks will return the format that most closely matches what was requested.
+
 ## Custom attribute/link/subresource handling
 
 When inheriting from `Yaks::Mapper`, you can override `map_attributes`, `map_links` and `map_resources` to skip (or augment) above methods, and instead implement your own custom mechanism. For example
@@ -320,8 +376,8 @@ For JSON based formats, a final step in serializing is to turn the nested data i
 
 ```ruby
 Yaks.new do
-  map_to_primitive Date, Time, DateTime do
-    object.iso8601
+  map_to_primitive Date, Time, DateTime do |date|
+    date.iso8601
   end
 end
 ```
@@ -330,8 +386,8 @@ This can also be used to transform alternative data structures, like those from
 
 ```ruby
 Yaks.new do
-  map_to_primitive Hamster::Vector, Hamster::List do
-    object.map do |item|
+  map_to_primitive Hamster::Vector, Hamster::List do |list|
+    list.map do |item|
       call(item)
     end
   end

data/lib/yaks/collection_mapper.rb

@@ -20,21 +20,24 @@ module Yaks
     def call(collection)
       @object = collection
 
-      CollectionResource.new(
+      attrs = {
         type: collection_type,
-        members_rel: members_rel,
         links: map_links,
         attributes: map_attributes,
         members: collection.map do |obj|
           mapper_for_model(obj).new(context).call(obj)
         end
-      )
+      }
+
+      attrs[ :members_rel ] = members_rel if members_rel
+
+      CollectionResource.new(attrs)
     end
 
     private
 
     def members_rel
-      policy.expand_rel( 'collection', pluralize( collection_type ) )
+      policy.expand_rel( 'collection', pluralize( collection_type ) ) if collection_type
     end
 
     def collection_type

data/lib/yaks/config.rb

@@ -88,7 +88,8 @@ module Yaks
     # Yaks::Resource       => serialized structure
     # serialized structure => serialized flat
 
-    def call(object, opts = {}, env = {})
+    def call(object, opts = {})
+      env = opts.fetch(:env, {})
       context = {
         policy: policy,
         env: env

data/lib/yaks/default_policy.rb

@@ -38,7 +38,7 @@ module Yaks
     end
 
     def derive_mapper_from_association(association)
-      @options[:namespace].const_get("#{camelize(singularize(association.name.to_s))}Mapper")
+      @options[:namespace].const_get("#{camelize(association.singular_name)}Mapper")
     end
 
     def derive_rel_from_association(mapper, association)

data/lib/yaks/mapper/has_many.rb

@@ -1,7 +1,10 @@
 module Yaks
   class Mapper
     class HasMany < Association
+      include Util
+
       def map_resource(collection, context)
+        return NullResource.new(collection: true) if collection.nil?
         policy        = context.fetch(:policy)
         member_mapper = association_mapper(policy)
         context       = context.merge(member_mapper: member_mapper)
@@ -12,6 +15,10 @@ module Yaks
         return @collection_mapper unless @collection_mapper.equal? Undefined
         policy.derive_mapper_from_object(collection)
       end
+
+      def singular_name
+        singularize(name.to_s)
+      end
     end
   end
 end

data/lib/yaks/mapper/has_one.rb

@@ -6,6 +6,10 @@ module Yaks
           .new(context)
           .call(object)
       end
+
+      def singular_name
+        name.to_s
+      end
     end
   end
 end

data/lib/yaks/null_resource.rb

@@ -2,6 +2,10 @@ module Yaks
   class NullResource
     include Enumerable
 
+    def initialize(opts = {})
+      @collection = opts.fetch(:collection, false)
+    end
+
     def each
       return to_enum unless block_given?
     end
@@ -21,8 +25,11 @@ module Yaks
     def [](*)
     end
 
+    def type
+    end
+
     def collection?
-      false
+      @collection
     end
   end
 end

data/lib/yaks/serializer/json_api.rb

@@ -29,7 +29,9 @@ module Yaks
 
       def serialize_links(subresources)
         subresources.each_with_object({}) do |(name, resource), hsh|
-          hsh[pluralize(resource.type)] = serialize_link(resource)
+          next if resource.is_a? NullResource
+          key = resource.collection? ? pluralize(resource.type) : resource.type
+          hsh[key] = serialize_link(resource)
         end
       end
 
@@ -53,7 +55,7 @@ module Yaks
       def serialize_subresource(resource, linked)
         key = pluralize(resource.type)
         set = linked.fetch(key) { Set.new }
-        linked = linked[key] = (set << serialize_resource(resource))
+        linked[key] = (set << serialize_resource(resource))
         serialize_linked_subresources(resource.subresources, linked)
       end
     end

data/lib/yaks/version.rb

@@ -1,3 +1,3 @@
 module Yaks
-  VERSION = '0.4.0'
+  VERSION = '0.4.1'
 end

data/spec/acceptance/acceptance_spec.rb

@@ -3,12 +3,12 @@ require 'spec_helper'
 require_relative './models'
 
 RSpec.shared_examples_for 'JSON output format' do |yaks, format, name|
-  let(:input)  { load_yaml_fixture name }
+  let(:input)  { load_yaml_fixture(name) }
   let(:output) { load_json_fixture "#{name}.#{format}" }
 
   subject { yaks.serialize(input) }
 
-  it { should eql output }
+  it { should deep_eql output }
 end
 
 RSpec.describe Yaks::Serializer::Hal do
@@ -22,8 +22,8 @@ RSpec.describe Yaks::Serializer::Hal do
     end
   end
 
-  include_examples 'JSON output format' , yaks_rel_template    , :hal      , 'confucius'
-  include_examples 'JSON output format' , yaks_policy_dsl      , :hal      , 'confucius'
+  include_examples 'JSON output format' , yaks_rel_template , :hal , 'confucius'
+  include_examples 'JSON output format' , yaks_policy_dsl   , :hal , 'confucius'
 end
 
 RSpec.describe Yaks::Serializer::JsonApi do

data/spec/acceptance/models.rb

@@ -5,7 +5,15 @@ class Scholar
 end
 
 class Work
-  include Anima.new(:id, :chinese_name, :english_name)
+  include Anima.new(:id, :chinese_name, :english_name, :quotes, :era)
+end
+
+class Quote
+  include Anima.new(:id, :chinese, :english, :sources)
+end
+
+class Era
+  include Anima.new(:id, :name)
 end
 
 class LiteratureBaseMapper < Yaks::Mapper
@@ -25,4 +33,14 @@ end
 
 class WorkMapper < LiteratureBaseMapper
   attributes :id, :chinese_name, :english_name
+  has_many :quotes
+  has_one  :era
+end
+
+class QuoteMapper < Yaks::Mapper
+  attributes :id, :chinese
+end
+
+class EraMapper < Yaks::Mapper
+  attributes :id, :name
 end

data/spec/json/confucius.hal.json

@@ -16,6 +16,35 @@
         "_links": {
           "self":    { "href": "http://literature.example.com/work/11" },
           "profile": { "href": "http://literature.example.com/profiles/work" }
+        },
+        "_embedded": {
+          "http://literature.example.com/rel/quotes": [
+            {
+              "id": 17,
+              "chinese": "廄焚。子退朝，曰：“傷人乎？” 不問馬。"
+            },
+            {
+              "id": 18,
+              "chinese": "子曰：“其恕乎！己所不欲、勿施於人。”"
+            }
+          ],
+          "http://literature.example.com/rel/era": {
+            "id": 99,
+            "name": "Zhou Dynasty"
+          }
+        }
+      },
+      {
+        "id": 12,
+        "chinese_name": "易經",
+        "english_name": "Commentaries to the Yi-jing",
+        "_links": {
+          "self":    { "href": "http://literature.example.com/work/12" },
+          "profile": { "href": "http://literature.example.com/profiles/work" }
+        },
+        "_embedded": {
+          "http://literature.example.com/rel/quotes": [],
+          "http://literature.example.com/rel/era": null
         }
       }
     ]

data/spec/json/confucius.json_api.json

@@ -6,7 +6,7 @@
       "pinyin": "Kongzi",
       "latinized": "Confucius",
       "links": {
-        "works": [11]
+        "works": [11,12]
       }
     }
   ],
@@ -15,7 +15,33 @@
       {
         "id": 11,
         "chinese_name": "論語",
-        "english_name": "Analects"
+        "english_name": "Analects",
+        "links": {
+          "quotes": [17, 18],
+          "era": 99
+        }
+      },
+      {
+        "id": 12,
+        "chinese_name": "易經",
+        "english_name": "Commentaries to the Yi-jing",
+        "links": {}
+      }
+    ],
+    "quotes": [
+      {
+        "id": 17,
+        "chinese": "廄焚。子退朝，曰：“傷人乎？” 不問馬。"
+      },
+      {
+        "id": 18,
+        "chinese": "子曰：“其恕乎！己所不欲、勿施於人。”"
+      }
+    ],
+    "erae": [
+      {
+        "id": 99,
+        "name": "Zhou Dynasty"
       }
     ]
   }

data/spec/spec_helper.rb

@@ -12,6 +12,7 @@ require_relative 'support/friends_mapper'
 require_relative 'support/fixtures'
 require_relative 'support/shared_contexts'
 require_relative 'support/youtypeit_models_mappers'
+require_relative 'support/deep_eql'
 
 
 RSpec.configure do |rspec|

data/spec/support/deep_eql.rb

@@ -0,0 +1,110 @@
+# When comparing deep nested structures, it can be really hard to figure out what
+# the actual differences are looking at the RSpec output. This custom matcher
+# traverses nested hashes and arrays recursively, and reports each difference
+# separately, with a JSONPath string of where the difference was found
+#
+# e.g.
+#
+# at $.shows[0].venues[0].name, got Foo, expected Bar
+
+module Matchers
+  class DeepEql
+    extend Forwardable
+    attr_reader :expectation, :stack, :target, :diffs, :result
+    def_delegators :stack, :push, :pop
+
+    def initialize(expectation, stack = [], diffs = [])
+      @expectation = expectation
+      @stack       = stack
+      @diffs       = diffs
+      @result      = true
+    end
+
+    def description
+      'be deeply equal'
+    end
+
+    def recurse(target, expectation)
+      @result &&= DeepEql.new(expectation, stack, diffs).matches?(target)
+    end
+
+    def stack_as_jsonpath
+      '$' + stack.map do |item|
+        case item
+        when Integer, /\W/
+          "[#{item.inspect}]"
+        else
+          ".#{item}"
+        end
+      end.join
+    end
+
+    def failure_message(message)
+      diffs << "at %s, %s" % [stack_as_jsonpath, message]
+      @result = false
+    end
+
+    def compare(key)
+      push key
+      if target[key] != expectation[key]
+        if [Hash, Array].any?{|klz| target[key].is_a? klz }
+          recurse(target[key], expectation[key])
+        else
+          failure_message begin
+                            if expectation[key].class == target[key].class
+                              "expected #{expectation[key].inspect}, got #{target[key].inspect}"
+                            else
+                              "expected #{expectation[key].class}: #{expectation[key].inspect}, got #{target[key].class}: #{target[key].inspect}"
+                            end
+                          rescue Encoding::CompatibilityError
+                            "expected #{expectation[key].encoding}, got #{target[key].encoding}"
+                          end
+        end
+      end
+      pop
+    end
+
+    def matches?(target)
+      @target = target
+
+      case expectation
+      when Hash
+        if target.is_a?(Hash)
+          if target.class != expectation.class # e.g. HashWithIndifferentAccess
+            failure_message("expected #{expectation.class}, got #{target.class}")
+          end
+          (target.keys | expectation.keys).each do |key|
+            compare key
+          end
+        else
+          failure_message("expected Hash got #{@target.inspect}")
+        end
+
+      when Array
+        if target.is_a?(Array)
+          0.upto([target.count, expectation.count].max) do |idx|
+            compare idx
+          end
+        else
+          failure_message("expected Array got #{@target.inspect}")
+        end
+      end
+
+      result
+    end
+
+    def failure_message_for_should
+      diffs.join("\n")
+    end
+
+    def failure_message_for_should_not
+      "expected #{@target.inspect} not to be in deep_eql with #{@expectation.inspect}"
+    end
+  end
+end
+
+module RSpec::Matchers
+  def deep_eql(exp)
+    Matchers::DeepEql.new(exp)
+  end
+end

data/spec/yaml/confucius.yaml

@@ -8,3 +8,21 @@ works:
     id: 11
     chinese_name: "論語"
     english_name: "Analects"
+    era: !ruby/object:Era
+      id: 99
+      name: "Zhou Dynasty"
+    quotes:
+      - !ruby/object:Quote
+        id: 17
+        chinese: "廄焚。子退朝，曰：“傷人乎？” 不問馬。"
+        english: "When the stables were burnt down, on returning from court Confucius said, “Was anyone hurt?” He did not ask about the horses."
+        sources: "Analects X.11 (tr. Waley), 10–13 (tr. Legge), or X-17 (tr. Lau)"
+      - !ruby/object:Quote
+        id: 18
+        chinese: "子曰：“其恕乎！己所不欲、勿施於人。”"
+        english: "The Master replied: “How about 'reciprocity'! Never impose on others what you would not choose for yourself.”"
+        sources: "Analects XV.24, tr. David Hinton"
+  - !ruby/object:Work
+    id: 12
+    chinese_name: "易經"
+    english_name: "Commentaries to the Yi-jing"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yaks
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Arne Brasseur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-17 00:00:00.000000000 Z
+date: 2014-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inflection
@@ -219,6 +219,7 @@ files:
 - spec/json/john.hal.json
 - spec/json/youtypeitwepostit.collection.json
 - spec/spec_helper.rb
+- spec/support/deep_eql.rb
 - spec/support/fixtures.rb
 - spec/support/friends_mapper.rb
 - spec/support/models.rb
@@ -280,6 +281,7 @@ test_files:
 - spec/json/john.hal.json
 - spec/json/youtypeitwepostit.collection.json
 - spec/spec_helper.rb
+- spec/support/deep_eql.rb
 - spec/support/fixtures.rb
 - spec/support/friends_mapper.rb
 - spec/support/models.rb