yaks 0.3.1 → 0.4.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ef13062afc3ed4ab23fcb46adb79f920f0ea19eb
-  data.tar.gz: 3af6551324cee70e9dafea7c809f57109649f72d
+  metadata.gz: 598793af50666377a34d0efb9e5264b2c7767f3b
+  data.tar.gz: 87071e277c536147dcbe47a3201dbb59156191ef
 SHA512:
-  metadata.gz: dea7bd7a65ff486565f0ff020bbfaf5dc8d7860d92d18d83a84d57a10c856c646ae66bdb7ed2c87a16be703e964a646e3256c48897c6120f46c373168bd5a6c4
-  data.tar.gz: 264fe081d2943d5143d698b9389742a4833fa9cdae2cb29ee255765617a6f4b273832d756d59b4f7144fdbc2cbb15181416769c8a1c631efc8fef0164b7f3b6e
+  metadata.gz: 45b38a236ceb4ceafcb68007663069a158b638116a46599071e054979d2747fd47550cfa3b0d04028ccefd8e47e0999e251686ab2bba2f3b08615a84e9b8bf16
+  data.tar.gz: 0a0887de90d46d746a4dc1761a2f2d377dbb0bae99dd59c6e1101c1a493eceb147a4fae8344655f98fbebbd1a35ca00c7b0e7fc92b11f4db97df1205e71dcb1b

data/.gitignore

@@ -1,3 +1,4 @@
 pkg
 .bundle
 coverage
+Gemfile.lock

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+# v0.4.0 (unreleased)
+
+* Introduce Yaks.new as the main public interface
+* Fix JsonApiSerializer and make it compliant with current spec
+* Remove Hamster dependency, Yaks new uses plain old Ruby arrays and hashes
+* Remove RelRegistry and ProfileRegistry in favor of a simpler explicit syntax + policy based fallback
+* Add more policy derivation hooks, plus make DefaultPolicy template for rel urls configurable
+* Optionally take a Rack env hash, pass it around so mappers can inspect it
+* Honor the HTTP Accept header if it is present in the rack env
+* Add map_to_primitive configuration option
+
 # v0.3.0
 
 * Allow partial expansion of templates, expand certain fields, leave others as URI template in the result.

data/Gemfile

@@ -1,5 +1,3 @@
 source 'https://rubygems.org'
 
 gemspec
-
-gem 'hamster', github: 'harukizaemon/hamster'

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2013-2014 Arne Brasseur
+
+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

@@ -8,12 +8,16 @@
 [gemnasium]: https://gemnasium.com/plexus/yaks
 [codeclimate]: https://codeclimate.com/github/plexus/yaks
 
-# Yaks
+# Yak Serializers
 
 ### One Stop Hypermedia Shopping ###
 
+*We did the shaving for you*
+
 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
@@ -48,10 +52,39 @@ class PostMapper < Yaks::Mapper
 end
 ```
 
-Now you can use this to create a Resource
+Configure a Yaks instance and start serializing!
 
 ```ruby
-resource = PostMapper.new(post).to_resource
+yaks = Yaks.new
+yaks.serialize(post)
+```
+
+or a bit more elaborate
+
+```ruby
+yaks = Yaks.new do
+  default_format :json_api
+  rel_template 'http://api.example.com/rels/{association_name}'
+  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
@@ -64,6 +97,7 @@ For example, if you are representing data that is stored in a Hash, you could do
 class PostHashMapper < Yaks::Mapper
   attributes :id, :body
 
+  # @param name [Symbol]
   def load_attribute(name)
     object[name]
   end
@@ -88,7 +122,7 @@ Implement `filter(attrs)` to filter out specific attributes, e.g. based on optio
 
 ```ruby
 def filter(attrs)
-  attrs.reject{|attr| options[:exclude].include? attr
+  attrs.reject{|attr| options[:exclude].include? attr }
 end
 ```
 
@@ -140,40 +174,101 @@ Use `has_one` for an association that returns a single object, or `has_many` for
 
 Options
 
-* `:as` : use a different name for the association in the result
 * `:mapper` : Use a specific for each instance, will be derived from the class name if omitted (see Policy vs Configuration)
 * `: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
-* `:policy` : supply an alternative Policy object
+* `: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
 
-## Serializers
+## Custom attribute/link/subresource handling
 
-A resource can be turned in to a specific media type representation, for example [HAL](http://stateless.co/hal_specification.html) using a Serializer
+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
 
 ```ruby
-hal = Yaks::HalSerializer.new(resource).serialize
+class ErrorMapper < Yaks::Mapper
+  link :profile, '/api/error'
+
+  def map_attributes
+    attrs = {
+      http_code: 500,
+      message: object.to_s,
+      type: object.class.name.underscore
+    }
+
+    case object
+    when AllocationException
+      attrs[:http_code] = 422
+    when ActiveRecord::RecordNotFound
+      attrs[:http_code] = 404
+      attrs[:type] = "record_not_found"
+    end
+
+    attrs
+  end
+end
+```
+
+## Resources and Serializers
+
+Yaks uses an intermediate "Resource" representation to support multiple output formats. A mapper turns a domain model into a `Yaks::Resource`. A serializer (e.g. `Yaks::Serializer::Hal`) takes the resource and outputs the structure of the target format.
+
+Since version 0.4 the recommended API is through `Yaks.new {...}.serialize`. This will give you back a composite value consisting of primitives that have a mapping to JSON, so you can use your favorite JSON encoder to turn this into a character stream.
+
+```ruby
+my_yaks = Yaks.new
+hal = my_yaks.serialize(model)
 puts JSON.dump(hal)
 ```
 
-This will give you back a composite types consisting of primitives that have a mapping to JSON, so you can use your favorite JSON encoder to turn this into a character stream.
+There are at least a handful of JSON libraries and implementations for Ruby out there, with different trade-offs. Yaks does not impose an opinion on which one to use
 
-### Yaks::HalSerializer
+### HAL
 
-Serializes to HAL. In HAL one decides when building an API which links can only be singular (e.g. self), and which are always represented as an array. So the HalSerializer understand the `:singular_links` option.
+This is the default. In HAL one decides when building an API which links can only be singular (e.g. self), and which are always represented as an array. Yaks defaults to singular as I've found it to be the most common case. If you want specific links to be plural, then configure their rel href as such.
 
 ```ruby
-hal = Yaks::HalSerializer.new(resource, singular_links: [:self, :"ea:find", :"ea:basket"])
+hal = Yaks.new do
+  format_options :hal, plural_links: ['http://api.example.com/rels/foo']
+end
 ```
 
-CURIEs are not explicitly supported, but it's possible to use them with some effort, see `examples/hal01.rb` for an example.
+CURIEs are not explicitly supported (yet), but it's possible to use them with some effort, see `examples/hal01.rb` for an example.
 
 The line between a singular resource and a collection is fuzzy in HAL. To stick close to the spec you're best to create your own singular types that represent collections, rather than rendering a top level CollectionResource.
 
-### Yaks::JsonApiSerializer
+### JSON-API
 
-JSON-API has no concept of outbound links, so these will not be rendered, but the profile link information will be used to derive the root key.
+```ruby
+default_format :json_api
+```
+
+JSON-API has no concept of outbound links, so these will not be rendered. Instead the key will be inferred from the mapper class name by default. This can be changed per mapper:
+
+```ruby
+class AnimalMapper
+  key :pet
+end
+```
 
-* `embed: :resources` : Embed resources in a `{"linked":` section, referenced by id
-* `embed: :links` : Use URL style JSON-API
+Or the policy can be overridden:
+
+```ruby
+yaks = Yaks.new do
+  derive_type_from_mapper_class do |mapper_class|
+    piglatinize(mapper_class.to_s.sub(/Mapper$/, ''))
+  end
+end
+```
+
+### Collection+JSON
+
+```ruby
+default_format :collection_json
+```
+
+Subresources aren't mapped because Collection+JSON doesn't really have that concept, and the other way around templates and queries don't exist (yet) in Yaks.
+
+### More formats
+
+Are planned... at the moment HAL is the only format I actually use, so it's the one that's best supported. Adding formats that follow the resource=(attributes, links, subresources) structure or a subset thereof is straightforward. More features, e.g. forms/actions such as used in Mason might be added in the future.
 
 ## Policy over Configuration
 
@@ -181,30 +276,64 @@ It's an old adage in the Ruby/Rails world to have "Convention over Configuration
 
 This saves a lot of typing, but for the uninitiated it can also create confusion, the implicitness makes it hard to follow what's going on.
 
-What's worse, is that often the Configuration part is skimmed over, making it very hard to deviate from the Golden Standard.
+What's worse, is that often the Configuration part is skipped entirely, making it very hard to deviate from the Golden Standard.
 
 There is another old adage, "Policy vs Mechanism". Implement the mechanisms, but don't dictate the policy.
 
-In Yaks whenever missing values need to be inferred, like finding an unspecified mapper for a relation, this is handled by a policy object. The default is `Yaks::DefaultPolicy`, you can go there to find all the rules of inference. Subclass it and override to fit your needs, then pass it in to each mapper/serializer, they will pass it on to whatever objects they call.
+In Yaks whenever missing values need to be inferred, like finding an unspecified mapper for a relation, this is handled by a policy object. The default is `Yaks::DefaultPolicy`, you can go there to find all the rules of inference. Single rules of inference can be redefined directly in the Yaks configuration:
 
 ```ruby
-PostMapper.new(post, policy: MyPolicy.new)
+yaks = Yaks.new do
+  derive_mapper_from_object do |model|
+    # ...
+  end
+
+  derive_type_from_mapper_class do |mapper_class|
+    # ...
+  end
+
+  derive_mapper_from_association do |association|
+    # ...
+  end
+
+  derive_rel_from_association do |mapper, association|
+    # ...
+  end
+end
 ```
 
-## ProfileRegistry , RelationRegistry
+You can also subclass or create from scratch your own policy class
+
+```ruby
+class MyPolicy < DefaultPolicy
+  #...
+end
+
+yaks = Yaks.new do
+  policy MyPolicy
+end
+```
 
-...
+## Usage
 
-## Future plans
+Yaks is used in production by [Ticketsolve](http://www.ticketsolve.com/). You can find an example API endpoint [here](http://leicestersquaretheatre.ticketsolve.com/api).
 
-* Collection+JSON
-* Siren
-* Examples on how to integrate with web frameworks
+Get in touch if you like to see your name and API here.
 
 ## Acknowledgment
 
 The mapper syntax is largely borrowed from ActiveModel::Serializers, which in turn closely mimics the syntax of ActiveRecord models. It's a great concise syntax that still offers plenty of flexibility, so to not reinvent the wheel I've stuck to the existing syntax as far as practical, although there are several extensions and deviations.
 
+## Lightweight
+
+Yaks is a lean library. It only depends on a few other tiny libraries (inflection, concord, uri_template). It has no core extensions (monkey patches). There is deliberately no built-in "integration" with existing frameworks, since the API is simply enough. You just call it.
+
+If this approach sounds appealing, have a look at [microrb.com](http://microrb.com/).
+
+## Is it any good
+
+[Yes](https://news.ycombinator.com/item?id=3067434)
+
 ## How to contribute
 
 Run the tests, the examples, try it with your own stuff and leave your impressions in the issues. Or discuss on API-craft.
@@ -221,14 +350,10 @@ To add a feature
 1. Open an issue as soon as possible to gather feedback
 2. Same as above, fork, push to named branch, make a pull-request
 
-## Non-Features
-
-* No core extensions
-* Minimal dependencies
-* Only serializes what explicitly has a Serializer, will never call to_json/as_json
-* Adding extra output formats does not require altering existing code
-* Has no opinion on what to use for final JSON encoding (json, multi_json, yajl, oj, etc.)
+Yaks uses [Mutation Testing](https://github.com/mbj/mutant). Run `rake mutant` and look for percentage coverage. In general this should only go up.
 
 ## License
 
-MIT
+MIT License (Expat License), see [LICENSE](./LICENSE)
+
+![](shaved_yak.gif)

data/Rakefile

@@ -15,6 +15,7 @@ task :default => :mutant
 
 task :mutant do
   pattern = ENV.fetch('PATTERN', 'Yaks*')
-  result  = Mutant::CLI.run(%w[-Ilib -ryaks --use rspec --score 100] + [pattern])
+  opts    = ENV.fetch('MUTANT_OPTS', '').split(' ')
+  result  = Mutant::CLI.run(%w[-Ilib -ryaks --use rspec --score 100] + opts + [pattern])
   fail unless result == Mutant::CLI::EXIT_SUCCESS
 end

data/lib/yaks/collection_mapper.rb

@@ -1,33 +1,40 @@
 # -*- coding: utf-8 -*-
 
 module Yaks
-  class CollectionMapper
-    include Util, Mapper::MapLinks, SharedOptions
-    extend Mapper::ClassMethods
+  class CollectionMapper < Mapper
+    attr_reader :collection
+    alias collection object
 
-    attr_reader :collection, :resource_mapper, :options
-    private :collection, :resource_mapper, :options
-
-    def_delegators 'self.class', :config
-    def_delegators :config, :links
+    def initialize(collection, context)
+      super(collection, context)
+    end
 
-    def initialize(collection, resource_mapper, options = {})
-      @collection      = collection
-      @resource_mapper = resource_mapper
-      @options         = YAKS_DEFAULT_OPTIONS.merge(options)
+    def resource_mapper
+      context[:resource_mapper]
     end
 
     def to_resource
-      CollectionResource.new(map_links, collection.map {|obj| resource_mapper.new(obj, options).to_resource})
+      CollectionResource.new(
+        type: collection_type,
+        links: map_links,
+        attributes: map_attributes,
+        members: collection.map do |obj|
+          mapper_for_model(obj).new(obj, context).to_resource
+        end
+      )
     end
 
-    def load_attribute(name)
-      respond_to?(name) ? send(name) : collection.map(&name.to_sym)
-    end
+    private
 
-    def profile_type
-      resource_mapper.new(nil, options).profile_type
+    def collection_type
+      return unless context.key?(:resource_mapper)
+      resource_mapper.config.type || policy.derive_type_from_mapper_class(resource_mapper)
     end
 
+    def mapper_for_model(model)
+      context.fetch(:resource_mapper) do
+        policy.derive_mapper_from_object(model)
+      end
+    end
   end
 end

data/lib/yaks/collection_resource.rb

@@ -14,23 +14,19 @@ module Yaks
   #
   # In the second case a collection has a single "subresource", being its
   # members.
-  class CollectionResource
-    include Equalizer.new(:links, :members)
-    include Enumerable, LinkLookup
+  class CollectionResource < Resource
+    include Equalizer.new(:type, :links, :attributes, :members)
+    include Enumerable
 
     extend Forwardable
 
-    attr_reader :links, :members
+    attr_reader :type, :links, :members
 
     def_delegators :members, :each
 
-    def initialize(links, members)
-      @links   = Yaks::List(links)
-      @members = Yaks::List(members)
-    end
-
-    def attributes
-      Yaks::Hash()
+    def initialize(options)
+      super
+      @members = options.fetch(:members, [])
     end
 
     # Make a CollectionResource quack like a resource.
@@ -47,16 +43,14 @@ module Yaks
     #
     # :(
     def subresources
-      if members && members.any?
-        Yaks::Hash( profile => self )
+      if members.any?
+        profile_link = links.select{|link| link.rel.equal? :profile}.first.uri
+        { profile_link => self }
       else
-        Yaks::Hash()
+        {}
       end
     end
 
-    def []
-    end
-
     def collection?
       true
     end

data/lib/yaks/config.rb

@@ -0,0 +1,96 @@
+module Yaks
+  class Config
+    class DSL
+      attr_reader :config
+
+      def initialize(config, &blk)
+        @config = config
+        @policy_class = Class.new(DefaultPolicy)
+        @policies     = []
+        instance_eval(&blk) if blk
+        @policies.each do |policy_blk|
+          @policy_class.class_eval &policy_blk
+        end
+        config.policy_class = @policy_class
+      end
+
+      def format_options(format, options)
+        config.format_options[format] = options
+      end
+
+      def default_format(format)
+        config.default_format = format
+      end
+
+      def policy(klass)
+        @policy_class = klass
+      end
+
+      def rel_template(templ)
+        config.policy_options[:rel_template] = templ
+      end
+
+      def mapper_namespace(namespace)
+        config.policy_options[:namespace] = namespace
+      end
+
+      def map_to_primitive(*args, &blk)
+        config.primitivize.map(*args, &blk)
+      end
+
+      DefaultPolicy.public_instance_methods(false).each do |method|
+        define_method method do |&blk|
+          @policies << proc {
+            define_method method, &blk
+          }
+        end
+      end
+    end
+
+    attr_accessor :format_options, :default_format, :policy_class, :policy_options, :primitivize
+
+    def initialize(&blk)
+      @format_options = Hash.new({})
+      @default_format = :hal
+      @policy_options = {}
+      @primitivize =  Primitivize.create
+      DSL.new(self, &blk)
+    end
+
+    def policy
+      @policy_class.new(@policy_options)
+    end
+
+    def serializer_class(opts, env)
+      if env.key? 'HTTP_ACCEPT'
+        accept = Rack::Accept::Charset.new(env['HTTP_ACCEPT'])
+        mime_type = accept.best_of(Yaks::Serializer.mime_types)
+        return Yaks::Serializer.by_mime_type(mime_type) if mime_type
+      end
+      Yaks::Serializer.by_name(opts.fetch(:format) { @default_format })
+    end
+
+    def format_name(opts)
+      opts.fetch(:format) { @default_format }
+    end
+
+    def options_for_format(format)
+      format_options[format]
+    end
+
+    # model                => Yaks::Resource
+    # Yaks::Resource       => serialized structure
+    # serialized structure => serialized flat
+
+    def serialize(object, opts = {}, env = {})
+      context = {
+        policy: policy,
+        env: env
+      }
+      mapper     = opts.fetch(:mapper) { policy.derive_mapper_from_object(object) }
+      resource   = mapper.new(object, context).to_resource
+      serialized = serializer_class(opts, env).new(resource, format_options[format_name(opts)]).call
+      primitivize.call(serialized)
+    end
+  end
+end

data/lib/yaks/default_policy.rb

@@ -2,12 +2,42 @@ module Yaks
   class DefaultPolicy
     include Util
 
-    def derive_profile_from_mapper(mapper)
-      underscore(mapper.class.name.sub(/Mapper$/, '')).to_sym
+    DEFAULTS = {
+      rel_template: "rel:src={mapper_name}&dest={association_name}",
+      namespace: Kernel
+    }
+
+    attr_reader :options
+
+    def initialize(options = {})
+      @options = DEFAULTS.merge(options)
     end
 
-    def derive_missing_mapper_for_association(association)
-      Object.const_get("#{camelize(association.name.to_s)}Mapper")
+    def derive_mapper_from_object(model)
+      if model.respond_to? :to_ary
+        if @options[:namespace].const_defined?(:CollectionMapper)
+          @options[:namespace].const_get(:CollectionMapper)
+        end
+      else
+        name = model.class.name.split('::').last
+        @options[:namespace].const_get(name + 'Mapper')
+      end
     end
+
+    def derive_type_from_mapper_class(mapper_class)
+      underscore(mapper_class.to_s.sub(/Mapper$/, ''))
+    end
+
+    def derive_mapper_from_association(association)
+      Object.const_get("#{camelize(singularize(association.name.to_s))}Mapper")
+    end
+
+    def derive_rel_from_association(mapper, association)
+      URITemplate.new(@options[:rel_template]).expand(
+        mapper_name: derive_type_from_mapper_class(mapper.class),
+        association_name: association.name
+      )
+    end
+
   end
 end

data/lib/yaks/fp.rb

@@ -0,0 +1,18 @@
+module Yaks
+  module FP
+    extend self
+
+    def curry_method(name)
+      method(name).to_proc.curry
+    end
+
+    def identity_function
+      ->(x) {x}
+    end
+    I = identity_function
+
+    def send_with_args(symbol, *args, &blk)
+      ->(obj) { obj.method(symbol).(*args, &blk) }
+    end
+  end
+end