yaks 0.6.0.alpha.1 → 0.6.0

data/lib/yaks/runner.rb

@@ -56,7 +56,7 @@ module Yaks
 
     def primitivizer
       ->(input) do
-        if format_class.serializer == :json
+        if format_class.serializer.equal? :json
           primitivize.call(input)
         else
           input
@@ -73,9 +73,7 @@ module Yaks
     memoize :format_name
 
     def serializer
-      serializers.fetch(format_class.serializer) do
-        policy.serializer_for_format(format_class)
-      end
+      serializers.fetch(format_class.serializer)
     end
     memoize :serializer
 

data/lib/yaks/serializer.rb

@@ -0,0 +1,12 @@
+module Yaks
+  module Serializer
+    def self.register(format, serializer)
+      raise "Serializer for #{format} already registered" if all.key? format
+      all[format] = serializer
+    end
+
+    def self.all
+      @serializers ||= {json: JSON.method(:pretty_generate)}
+    end
+  end
+end

data/lib/yaks/stateful_builder.rb

@@ -0,0 +1,54 @@
+module Yaks
+  # State monad-ish thing.
+  #
+  # Generate a DSL syntax for immutable classes.
+  #
+  # @example
+  #
+  #   # This code
+  #   Control.create(:search)
+  #          .method("POST")
+  #          .href("/search")
+  #
+  #   # Can be written as
+  #   StatefulBuilder.new(Control, [:method, :href]).create(:search) do
+  #     method "POST"
+  #     href "/search"
+  #   end
+  #
+  class StatefulBuilder < BasicObject
+    def create(*args, &block)
+      @state = @klass.create(*args)
+      instance_eval(&block)
+      @state
+    end
+
+    def initialize(klass, methods)
+      @klass = klass
+      StatefulMethods.new(methods).send(:extend_object, self)
+    end
+
+    def validate_state(method_name, args)
+      unless @state.instance_of?(@klass)
+        ::Kernel.raise(
+          IllegalState,
+          "#{@klass}##{method_name}(#{args.map(&:inspect).join(', ')}) "\
+          "returned #{@state.inspect}. Expected instance of #{@klass}"
+        )
+      end
+    end
+
+    class StatefulMethods < ::Module
+      def initialize(methods)
+        methods.each { |name| define_stateful_method(name) }
+      end
+
+      def define_stateful_method(method_name)
+        define_method method_name do |*args, &block|
+          @state = @state.public_send(method_name, *args, &block)
+          validate_state(method_name, args)
+        end
+      end
+    end
+  end
+end

data/lib/yaks/version.rb

@@ -1,3 +1,3 @@
 module Yaks
-  VERSION = '0.6.0.alpha.1'
+  VERSION = '0.6.0'
 end

data/lib/yaks.rb

@@ -3,6 +3,7 @@
 require 'forwardable'
 require 'set'
 require 'pathname'
+require 'json'
 
 require 'anima'
 require 'concord'
@@ -11,11 +12,13 @@ require 'uri_template'
 require 'rack/accept'
 
 require 'yaks/util'
+require 'yaks/configurable'
 require 'yaks/fp'
-require 'yaks/fp/updatable'
-require 'yaks/fp/hash_updatable'
 require 'yaks/fp/callable'
 require 'yaks/primitivize'
+require 'yaks/attributes'
+require 'yaks/stateful_builder'
+require 'yaks/errors'
 
 require 'yaks/default_policy'
 
@@ -41,19 +44,25 @@ require 'yaks/null_resource'
 require 'yaks/resource/link'
 require 'yaks/collection_resource'
 
-require 'yaks/mapper/class_methods'
-require 'yaks/mapper'
-require 'yaks/mapper/attribute'
-require 'yaks/mapper/link'
 require 'yaks/mapper/association'
-require 'yaks/mapper/association_mapper'
 require 'yaks/mapper/has_one'
 require 'yaks/mapper/has_many'
+require 'yaks/mapper/attribute'
+require 'yaks/mapper/link'
+require 'yaks/mapper/control'
 require 'yaks/mapper/config'
+require 'yaks/mapper/class_methods'
+require 'yaks/mapper'
+require 'yaks/mapper/association_mapper'
 require 'yaks/collection_mapper'
 
+require 'yaks/resource/control'
+
+require 'yaks/serializer'
+
 require 'yaks/format'
 require 'yaks/format/hal'
+require 'yaks/format/halo'
 require 'yaks/format/json_api'
 require 'yaks/format/collection_json'
 

data/spec/acceptance/acceptance_spec.rb

@@ -6,7 +6,7 @@ require 'acceptance/json_shared_examples'
 RSpec.describe Yaks::Format::Hal do
   yaks_rel_template = Yaks.new do
     format_options :hal, plural_links: ['http://literature.example.com/rels/quotes']
-    rel_template "http://literature.example.com/rel/{association_name}"
+    rel_template "http://literature.example.com/rel/{rel}"
     skip :serialize
   end
 
@@ -18,8 +18,18 @@ RSpec.describe Yaks::Format::Hal do
     skip :serialize
   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::Format::Halo do
+  yaks = Yaks.new do
+    default_format :halo
+    rel_template "http://literature.example.com/rel/{rel}"
+    skip :serialize
+  end
+
+  include_examples 'JSON output format', yaks, :halo, 'confucius'
 end
 
 RSpec.describe Yaks::Format::JsonAPI do
@@ -28,7 +38,7 @@ RSpec.describe Yaks::Format::JsonAPI do
     skip :serialize
   end
 
-  include_examples 'JSON output format' , config , :json_api , 'confucius'
+  include_examples 'JSON output format', config, :json_api, 'confucius'
 end
 
 RSpec.describe Yaks::Format::CollectionJson do

data/spec/acceptance/models.rb

@@ -28,6 +28,15 @@ class ScholarMapper < LiteratureBaseMapper
   link 'http://literature.example.com/rels/quotes', 'http://literature.example.com/quotes/?author={downcased_pinyin}&q={query}', expand: [:downcased_pinyin], title: 'Search for quotes'
   link :self, 'http://literature.example.com/authors/{downcased_pinyin}'
 
+  control :search do
+    title 'Find a Scholar'
+    method 'POST'
+    media_type 'application/x-www-form-urlencoded'
+
+    field :name,   label: 'Scholar Name', type: 'text'
+    field :pinyin, label: 'Hanyu Pinyin', type: 'text'
+  end
+
   def downcased_pinyin
     object.pinyin.downcase
   end

data/spec/integration/map_to_resource_spec.rb

@@ -10,7 +10,7 @@ RSpec.describe 'Mapping domain models to Resource objects' do
   it { should be_a Yaks::Resource }
   its(:type)         { should eql 'friend' }
   its(:attributes)   { should eql(id: 1, name: 'john') }
-  its(:links)        { should eql [ Yaks::Resource::Link.new(:copyright, '/api/copyright/2024', {}) ] }
+  its(:links)        { should eql [ Yaks::Resource::Link.new(rel: :copyright, uri: '/api/copyright/2024') ] }
 
   its(:subresources) {
     should eq(

data/spec/json/confucius.halo.json

@@ -0,0 +1,80 @@
+{
+  "id": 9,
+  "name": "孔子",
+  "pinyin": "Kongzi",
+  "latinized": "Confucius",
+  "_links": {
+    "self":    { "href": "http://literature.example.com/authors/kongzi"  },
+    "profile": { "href": "http://literature.example.com/profiles/scholar" },
+    "http://literature.example.com/rels/quotes": {
+       "href": "http://literature.example.com/quotes/?author=kongzi&q={query}",
+       "templated": true,
+       "title": "Search for quotes"
+     }
+  },
+  "_embedded": {
+    "http://literature.example.com/rel/works": [
+      {
+        "id": 11,
+        "chinese_name": "論語",
+        "english_name": "Analects",
+        "_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
+        }
+      }
+    ]
+  },
+  "_controls": {
+    "search": {
+      "name": "search",
+      "href": null,
+      "title": "Find a Scholar",
+      "method": "POST",
+      "media_type": "application/x-www-form-urlencoded",
+      "fields": [
+        {
+          "name": "name",
+          "label": "Scholar Name",
+          "type": "text",
+          "value": null
+        },
+        {
+          "name": "pinyin",
+          "label": "Hanyu Pinyin",
+          "type": "text",
+          "value": null
+        }
+      ]
+    }
+  }
+}

data/spec/spec_helper.rb

@@ -1,7 +1,9 @@
 require 'rspec/its'
 require 'bogus/rspec'
+require 'timeout'
 
 require 'yaks'
+require 'yaks-html'
 require 'virtus'
 
 require 'fixture_helpers'
@@ -22,6 +24,9 @@ RSpec.configure do |rspec|
   rspec.backtrace_exclusion_patterns = [] if ENV['FULLSTACK']
   rspec.disable_monkey_patching!
   rspec.raise_errors_for_deprecations!
+  rspec.around(:each) do |example|
+    Timeout.timeout(1, &example)
+  end
 end
 
 Bogus.configure do |bogus|

data/spec/support/shared_contexts.rb

@@ -31,7 +31,7 @@ RSpec.shared_context 'plant collection resource' do
     [ :oak         , :self    , 'http://api.example.com/plants/15/oak'        ],
     [ :passiflora  , :self    , 'http://api.example.com/plants/33/passiflora' ],
   ].each do |name, type, uri|
-    let(:"#{name}_#{type}_link") { Yaks::Resource::Link.new(type, uri, {}) }
+    let(:"#{name}_#{type}_link") { Yaks::Resource::Link.new(rel: type, uri: uri) }
   end
 
   let(:plain_grass) do

data/spec/unit/yaks/attributes_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+
+RSpec.describe Yaks::Attributes do
+  subject { Class.new { include Yaks::Attributes.new(:foo, bar: 3) } }
+
+  it 'should have a hash-based constructor' do
+    expect(subject.new(foo: 3, bar: 4).bar).to equal 4
+  end
+
+  it 'should have defaults constructor' do
+    expect(subject.new(foo: 3).bar).to equal 3
+  end
+
+  it 'should allow updating through attribute methods' do
+    expect(subject.new(foo: 3).foo(4).to_h).to eql(foo: 4, bar: 3)
+  end
+
+  it 'should add an #append_to method' do
+    expect(subject.new(foo: [6]).append_to(:foo, 7, 8).foo).to eql [6, 7, 8]
+  end
+
+  context 'with all defaults' do
+    subject { Class.new { include Yaks::Attributes.new(foo: 5, bar: 3) } }
+
+    it 'should be able to construct without arguments' do
+      expect(subject.new.to_h).to eql(foo: 5, bar: 3)
+    end
+  end
+
+  context 'without any defaults' do
+    subject { Class.new { include Yaks::Attributes.new(:foo, :bar) } }
+
+    it 'should allow setting all attributes' do
+      expect(subject.new(foo: 5, bar: 6).bar).to equal 6
+    end
+
+    it 'should expect all attributes' do
+      expect { subject.new(foo: 5) }.to raise_exception
+    end
+  end
+
+  context 'when extending' do
+    subject { Class.new(super()) { include attributes.add(baz: 7) } }
+
+    it 'should make the new attributes available' do
+      expect(subject.new(foo: 3, baz: 6).baz).to equal 6
+    end
+
+    it 'should make the old attributes available' do
+      expect(subject.new(foo: 3, baz: 6).foo).to equal 3
+    end
+
+    context 'without any defaults' do
+      subject { Class.new(super()) { include attributes.add(:bax) } }
+
+      it 'should allow setting all attributes' do
+        expect(subject.new(foo: 5, bar: 6, bax: 7).bax).to equal 7
+      end
+
+      it 'should expect all attributes' do
+        expect { subject.new(foo: 5, bar: 6) }.to raise_exception
+      end
+    end
+  end
+end

data/spec/unit/yaks/collection_mapper_spec.rb

@@ -108,7 +108,7 @@ RSpec.describe Yaks::CollectionMapper do
     it 'should map the links' do
       expect(mapper.call(collection)).to eql Yaks::CollectionResource.new(
         type: 'the_type',
-        links: [ Yaks::Resource::Link.new(:self, 'http://api.example.com/orders', {}) ],
+        links: [ Yaks::Resource::Link.new(rel: :self, uri: 'http://api.example.com/orders') ],
         attributes: { },
         members: [],
         collection_rel: 'rel:the_types'

data/spec/unit/yaks/collection_resource_spec.rb

@@ -21,14 +21,14 @@ RSpec.describe Yaks::CollectionResource do
       {
         type: 'order',
         links: [
-          Yaks::Resource::Link.new('http://rels/summary', 'http://order/10/summary', {}),
-          Yaks::Resource::Link.new(:profile, 'http://rels/collection', {})
+          Yaks::Resource::Link.new(rel: 'http://rels/summary', uri: 'http://order/10/summary'),
+          Yaks::Resource::Link.new(rel: :profile, uri: 'http://rels/collection')
         ],
         attributes: { total: 10.00 },
         members: [
           Yaks::Resource.new(
             type: 'order',
-            links: [Yaks::Resource::Link.new(:self, 'http://order/10', {})],
+            links: [Yaks::Resource::Link.new(rel: :self, uri: 'http://order/10')],
             attributes: { customer: 'John Doe', price: 10.00 }
           )
         ],
@@ -38,40 +38,22 @@ RSpec.describe Yaks::CollectionResource do
 
     its(:type)       { should eql 'order' }
     its(:links)      { should eql [
-        Yaks::Resource::Link.new('http://rels/summary', 'http://order/10/summary', {}),
-        Yaks::Resource::Link.new(:profile, 'http://rels/collection', {})
+        Yaks::Resource::Link.new(rel: 'http://rels/summary', uri: 'http://order/10/summary'),
+        Yaks::Resource::Link.new(rel: :profile, uri: 'http://rels/collection')
       ]
     }
     its(:attributes) { should eql( total: 10.00 ) }
     its(:members)    { should eql [
         Yaks::Resource.new(
           type: 'order',
-          links: [Yaks::Resource::Link.new(:self, 'http://order/10', {})],
+          links: [Yaks::Resource::Link.new(rel: :self, uri: 'http://order/10')],
           attributes: { customer: 'John Doe', price: 10.00 }
         )
       ]
     }
     its(:collection_rel) { should eq 'http://api.example.org/rels/orders'}
 
-    its(:subresources) { should eql(
-        'http://api.example.org/rels/orders' => Yaks::CollectionResource.new(
-          type: 'order',
-          attributes: { total: 10.00 },
-          links: [
-            Yaks::Resource::Link.new('http://rels/summary', 'http://order/10/summary', {}),
-            Yaks::Resource::Link.new(:profile, 'http://rels/collection', {})
-          ],
-          members: [
-            Yaks::Resource.new(
-              type: 'order',
-              links: [Yaks::Resource::Link.new(:self, 'http://order/10', {})],
-              attributes: { customer: 'John Doe', price: 10.00 }
-            )
-          ],
-          collection_rel: 'http://api.example.org/rels/orders'
-        )
-      )
-    }
+    its(:subresources) { should eql({}) }
 
   end
 end

data/spec/unit/yaks/config/dsl_spec.rb

@@ -61,6 +61,11 @@ RSpec.describe Yaks::Config::DSL do
     specify   { expect(yaks_config.policy_options[:rel_template]).to eql 'rels:{rel}' }
   end
 
+  describe '#serializer' do
+    configure { serializer(:json) { |i| "foo #{i}" } }
+    specify   { expect(yaks_config.serializers[:json].call(7)).to eql 'foo 7' }
+  end
+
   describe '#json_serializer' do
     configure { json_serializer { |i| "foo #{i}" } }
     specify   { expect(yaks_config.serializers[:json].call(7)).to eql 'foo 7' }

data/spec/unit/yaks/config_spec.rb

@@ -14,7 +14,8 @@ RSpec.describe Yaks::Config do
       its(:default_format) { should equal :hal }
       its(:policy_class)   { should < Yaks::DefaultPolicy }
       its(:primitivize)    { should be_a Yaks::Primitivize }
-      its(:serializers)    { should eql({})  }
+      its(:serializers)    { should eql(Yaks::Serializer.all)  }
+      its(:serializers)    { should_not equal(Yaks::Serializer.all)  }
       its(:hooks)          { should eql([])  }
 
       it 'should have empty format options' do

data/spec/unit/yaks/configurable_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+RSpec.describe Yaks::Configurable do
+  class Creatable
+    def self.create(*args, &block)
+      ["->", *args, block.call]
+    end
+  end
+
+  subject do
+    Class.new do
+      include Yaks::Attributes.new(foo: []), Yaks::Configurable
+
+      config_method :bar, append_to: :foo, create: Creatable
+    end
+  end
+
+  it 'should generate the config method' do
+    expect(
+      subject.new.bar(1,2,3) { 4 }
+                 .bar(:baz)  { :booz }
+                 .foo
+    ).to eql [["->", 1, 2, 3, 4], ["->", :baz, :booz]]
+  end
+end

data/spec/unit/yaks/default_policy_spec.rb

@@ -4,7 +4,7 @@ RSpec.describe Yaks::DefaultPolicy do
   subject(:policy) { described_class.new( options ) }
 
   let(:options) { {} }
-  let(:association) { Yaks::Mapper::HasMany.new(name: 'shoes', collectionMapper: nil) }
+  let(:association) { Yaks::Mapper::HasMany.create('shoes') }
 
   describe '#initialize' do
     it 'should work without arguments' do
@@ -61,10 +61,4 @@ RSpec.describe Yaks::DefaultPolicy do
     end
   end
 
-  describe '#serializer_for_format' do
-    specify {
-      expect(policy.serializer_for_format(Yaks::Format::JsonAPI).call('foo' => [1,2])).to eql "{\n  \"foo\": [\n    1,\n    2\n  ]\n}"
-    }
-  end
-
 end

data/spec/unit/yaks/format/collection_json_spec.rb

@@ -13,7 +13,7 @@ RSpec.describe Yaks::Format::CollectionJson do
     let(:resource) {
       Yaks::Resource.new(
         attributes: {foo: 'fooval', bar: 'barval'},
-        links: [Yaks::Resource::Link.new('the_rel', 'the_uri', {})]
+        links: [Yaks::Resource::Link.new(rel: 'the_rel', uri: 'the_uri')]
       )
     }
 

data/spec/unit/yaks/format/hal_spec.rb

@@ -18,8 +18,8 @@ RSpec.describe Yaks::Format::Hal do
       Yaks::Resource.new(
         attributes: {foo: 'fooval', bar: 'barval'},
         links: [
-          Yaks::Resource::Link.new('my_plural_rel', 'the_uri1', {}),
-          Yaks::Resource::Link.new('my_plural_rel', 'the_uri2', {})
+          Yaks::Resource::Link.new(rel: 'my_plural_rel', uri: 'the_uri1'),
+          Yaks::Resource::Link.new(rel: 'my_plural_rel', uri: 'the_uri2')
         ]
       )
     }

data/spec/unit/yaks/format/html_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+# RSpec.describe Yaks::Format::HTML do
+
+# end

data/spec/unit/yaks/format/json_api_spec.rb

@@ -22,7 +22,7 @@ RSpec.describe Yaks::Format::JsonAPI do
           href: '/the/href'
         },
         links: [
-          Yaks::Resource::Link.new(:self, '/the/self/link', {})
+          Yaks::Resource::Link.new(rel: :self, uri: '/the/self/link')
         ]
       )
     }

data/spec/unit/yaks/format_spec.rb

@@ -27,11 +27,7 @@ RSpec.describe Yaks::Format do
 
   describe '.mime_types' do
     specify do
-      expect(Yaks::Format.mime_types).to eql(
-        collection_json: "application/vnd.collection+json",
-        hal: "application/hal+json",
-        json_api: "application/vnd.api+json"
-      )
+      expect(Yaks::Format.mime_types.values_at(:collection_json, :hal, :json_api)).to eql(["application/vnd.collection+json", "application/hal+json", "application/vnd.api+json"])
     end
   end
 end

data/spec/unit/yaks/mapper/association_mapper_spec.rb

@@ -26,8 +26,8 @@ RSpec.describe Yaks::Mapper::AssociationMapper do
         expect(association_mapper.call(Yaks::Resource.new)).to eql Yaks::Resource.new(
           links: [
             Yaks::Resource::Link.new(
-              'rels:the_rel',
-              'http://this/is_where_the_associated_thing_can_be_found', {}
+              rel: 'rels:the_rel',
+              uri: 'http://this/is_where_the_associated_thing_can_be_found'
             )
           ]
         )

data/spec/unit/yaks/mapper/association_spec.rb

@@ -6,7 +6,7 @@ RSpec.describe Yaks::Mapper::Association do
   subject(:association) do
     described_class.new(
       name: name,
-      mapper: mapper,
+      item_mapper: mapper,
       rel: rel,
       href: href,
       link_if: link_if
@@ -20,13 +20,13 @@ RSpec.describe Yaks::Mapper::Association do
   let(:link_if)           { Yaks::Undefined }
 
   its(:name)         { should equal :shoes }
-  its(:child_mapper) { should equal Yaks::Mapper }
+  its(:item_mapper) { should equal Yaks::Mapper }
 
   context 'with a minimal constructor' do
     subject(:association) { described_class.new(name: :foo) }
 
     its(:name)         { should be :foo }
-    its(:child_mapper) { should be Yaks::Undefined }
+    its(:item_mapper) { should be Yaks::Undefined }
     its(:rel)          { should be Yaks::Undefined }
     its(:href)         { should be Yaks::Undefined }
     its(:link_if)      { should be Yaks::Undefined }
@@ -132,4 +132,28 @@ RSpec.describe Yaks::Mapper::Association do
       end
     end
   end
+
+  describe '.create' do
+    it 'should take a name' do
+      expect(described_class.create(:foo).name).to be :foo
+    end
+
+    it 'should optionally take a mapper' do
+      expect(described_class.create(:foo, mapper: :bar).item_mapper).to be :bar
+    end
+
+    it 'should take other options' do
+      expect(described_class.create(:foo, mapper: :bar, href: 'xxx').href).to eql 'xxx'
+    end
+
+    it 'should respect attribute defaults' do
+      expect(described_class.create(:foo, href: 'xxx').item_mapper).to be Yaks::Undefined
+    end
+
+    it 'should not munge the options hash' do
+      opts  = {mapper: :foo}
+      described_class.create(:foo, opts)
+      expect(opts).to eql(mapper: :foo)
+    end
+  end
 end