contrackt 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5b24a1a4206a9550aced407dd6a29c7496485d1e
+  data.tar.gz: f346524d7e88b2cd1987dee455dde888e42e3ce3
+SHA512:
+  metadata.gz: 7329932b9a65f010c19096a241c80077f2ce97b32b49df431791b10a490a30a22fab70a1c299df195ef54067f71c2b4c561a2477503c24f4521838c96bf624a2
+  data.tar.gz: a45b3e9c369ebeb5f3b66c4b801688c8507e9871cfa4e03863272be8dc9874099b8959c024666d40cf13a8821187fda6f927d91293b0e6d57b43152f65d75099

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gem 'rspec'

data/Gemfile.lock

@@ -0,0 +1,26 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.2.5)
+    rspec (3.5.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+    rspec-core (3.5.3)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rspec
+
+BUNDLED WITH
+   1.12.4

data/LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright 2016 Credit Karma
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,124 @@
+Contrackt is a tool to make handling request and response objects more object-oriented.
+
+In general, Ruby handles these request and response objects mostly using hashes. One would expect to see something along the lines of
+
+```ruby
+{
+	body: {
+    "foo" => {
+      "bar" => "baz"
+    }
+  }
+}
+```
+
+So your code might involve accessing variables like `response[:body]['foo']['bar']` (always keeping track of which key is a string and which is a symbol) instead of the more object-oriented `response.body.foo.bar`. Contracts are an attempt to represent these JSON hashes more clearly based on the objects they represent.
+
+`Contrackt` allows the user to define self-documenting "contracts" that they expect to receive or send based on whatever API tool (raml, swagger, blueprint) they use to specify an API. An example usage is
+
+```ruby
+class MyContract < Contrackt::Base
+  required 'foo' => Foo
+end
+
+class Foo < Contrackt::Base
+  required 'bar'
+end
+```
+
+You can then use those classes to work with the resulting JSON, e.g.
+
+```ruby
+# json_response = { body: { "foo" => { "bar" => "baz" } } }
+contract = MyContract.new(json_response[:body])
+contract.foo.bar #=> 'baz'
+contract.to_hash #=> { "foo" => { "bar" => "baz" } }
+```
+
+You can also specify arrays of type:
+```
+# json = { albums: [{ name: "21", artist: "Adele" }, { name: "IV", artist: "Led Zeppelin" }] }
+
+class Album < Contrackt::Base
+  required :name
+  required :artist
+end
+
+class AlbumPayload < Contrackt::Base
+  required albums: Album[]
+end
+```
+
+The RAML spec provides for the concept of a "discriminator," i.e. a field that indicates the object's type. You can specify a discriminator as follows:
+
+```ruby
+# json = { pets:
+#   [
+#      { type: "Cat", name: "Garfield", owner: "Jon", color: "striped" },
+#      { type: "Dog", name: "Marmaduke", owner: "Phil", breed: "great dane" },
+#      ...
+#   ]
+# }
+
+class Pet < Contrackt::Base
+  discriminator :type
+  required      :name
+  required      :owner
+end
+
+class PetsPayload < Contrackt::Base
+  required pets: Pet[]
+end
+
+class Cat < Pet
+  required :color
+end
+
+class Dog < Pet
+  required :breed
+end
+
+```
+
+You can also use discriminator along with a map if the discriminator doesn't provide the class name:
+
+```ruby
+# json = { pets:
+#   [
+#      { type: "cat", name: "Garfield", owner: "Jon", color: "striped" },
+#      { type: "dog", name: "Marmaduke", owner: "Phil", breed: "great dane" },
+#      ...
+#   ]
+# }
+
+class Pet < Contrackt::Base
+  discriminator :type, 'cat' => Cat, 'dog' => Dog
+  required      :name
+  required      :owner
+end
+
+class PetsPayload < Contrackt::Base
+  required pets: Pet[]
+end
+
+class Cat < Pet
+  required :color
+end
+
+class Dog < Pet
+  required :breed
+end
+
+```
+
+If you have complicated code, you can write a custom parser, e.g.
+
+```ruby
+# json = { foo: 'bar' }
+
+class Thing < Contrackt::Base
+  required(:foo).with_custom_parser { |json| "#{json} (came from key foo)" }
+end
+
+Thing.new(json).foo #=> "bar (came from key foo)"
+```

data/contrackt.gemspec

@@ -0,0 +1,13 @@
+Gem::Specification.new do |s|
+  s.name         = 'contrackt'
+  s.version      = '0.0.0'
+  s.date         = '2016-10-20'
+  s.summary      = "Contrackt: simple Ruby contracts"
+  s.description  = "Self-documenting contracts for Ruby"
+  s.authors      = ["David Reiman"]
+  s.email        = 'david.reiman@creditkarma.com'
+  s.files        = `git ls-files`.split($\)
+  s.require_path = 'lib'
+  s.homepage     = 'https://github.com/creditkarma/contrackt'
+  s.license      = 'Apache 2.0'
+end

data/lib/contrackt.rb

@@ -0,0 +1,3 @@
+require 'contrackt/version'
+require 'contrackt/props'
+require 'contrackt/base'

data/lib/contrackt/base.rb

@@ -0,0 +1,72 @@
+module Contrackt
+  class Base
+    def self.required(key)
+      define_prop(Props::Required.new(key))
+    end
+
+    def self.optional(key)
+      define_prop(Props::Optional.new(key))
+    end
+
+    def self.discriminator(discriminator, mapping = nil)
+      @discriminator = discriminator
+      @mapping = mapping
+      define_prop(Props::Required.new(discriminator))
+    end
+
+    def self.define_prop(prop)
+      symbol_key = prop.key.to_sym
+      attr_reader symbol_key
+      props[symbol_key] = prop
+    end
+
+    def self.props
+      @props ||= superclass == Contrackt::Base ? {} : superclass.clone_props
+    end
+
+    def self.clone_props
+      props.reduce({}) { |props, kvp| props.merge(kvp[0] => kvp[1].clone) }
+    end
+
+    def self.[]
+      Collection.new(self)
+    end
+
+    def self.new(json)
+      klass = determine_contract_class(json)
+      klass == self ? super(json) : klass.new(json)
+    end
+
+    def self.determine_contract_class(json)
+      if @discriminator
+        class_key = json[@discriminator]
+        (@mapping && @mapping[class_key]) || Object.const_get(class_key)
+      else
+        self
+      end
+    end
+
+    def initialize(json)
+      self.class.props.each do |symbol_key, prop|
+        instance_variable_set "@#{prop.key}", prop.parse(json)
+      end
+    end
+
+    def to_hash
+      self.class.props.reduce({}) do |hash, array|
+        symbol_key, prop = array
+        hash.merge(prop.hashify(send(symbol_key)))
+      end
+    end
+  end
+
+  class Collection
+    def initialize(klass)
+      @klass = klass
+    end
+
+    def new(values)
+      values.map {|value| @klass.new(value)}
+    end
+  end
+end

data/lib/contrackt/props.rb

@@ -0,0 +1,68 @@
+module Contrackt
+  module Props
+    class Prop
+      attr_reader :key
+      def initialize(key)
+        unpack(key)
+      end
+
+      def parse(json)
+        target = json[key]
+        if @custom_parser
+          @custom_parser[target]
+        elsif @klass
+          @klass.new(target)
+        else
+          target
+        end
+      end
+
+      def hashify(value)
+        { key => hashify_value(value) }
+      end
+
+      def with_custom_parser(&block)
+        @custom_parser = block
+      end
+
+      private
+      def unpack(key)
+        case key
+        when String
+          @key = key
+        when Symbol
+          @key = key
+        when Hash
+          raise ArgumentError, "Prop can only take one key-value pair" unless key.length == 1
+          @key = key.keys[0]
+          @klass = key.values[0]
+        else
+          raise ArgumentError, "Prop can only take a string or a hash"
+        end
+      end
+
+      def hashify_value(value)
+        if (value.is_a? Array)
+          value.map {|value| hashify_value(value)}
+        elsif value.respond_to?(:to_hash)
+          value.to_hash
+        else
+          value
+        end
+      end
+    end
+
+    class Required < Prop
+    end
+
+    class Optional < Prop
+      def parse(json)
+        json[key].nil? ? nil : super(json)
+      end
+
+      def hashify(value)
+        value.nil? ? {} : super(value)
+      end
+    end
+  end
+end

data/lib/contrackt/version.rb

@@ -0,0 +1,3 @@
+module Contrackt
+  VERSION = '0.0.0'
+end

data/spec/contrackt_spec.rb

@@ -0,0 +1,213 @@
+require_relative '../lib/contrackt'
+
+describe Contrackt::Base do
+  before(:all) do
+    class MyContract < Contrackt::Base
+      required 'foo'
+    end
+
+    class Foo < Contrackt::Base
+      required 'bar'
+    end
+
+    class ComposedContract < Contrackt::Base
+      required 'foo' => Foo
+    end
+
+    class ComposedWithArray < Contrackt::Base
+      required 'foos' => Foo[]
+    end
+
+    class ComposedWithOptional < Contrackt::Base
+      required 'foo' => Foo
+      optional 'additionalStuff' => Foo
+    end
+
+    class WithCustomParser < Contrackt::Base
+      required('foo').with_custom_parser { |foo| Foo.new(foo.merge('bar' => foo['bar'] + " (this was the bar)")) }
+    end
+
+    @simple_payload_hash = { "foo" => "bar" }
+    @complex_payload_hash = { "foo" => { "bar" => "baz" } }
+    @array_payload_hash = { "foos" => [{ "bar" => "baz" }, { "bar" => "qux" }] }
+    @complex_with_optional_hash = @complex_payload_hash.merge({ "additionalStuff" => { "bar" => "and more"}})
+  end
+
+  it "can be inherited" do
+    expect(true).to be true # if we get here, the inheritance(s) above didn't throw an error
+  end
+
+  context "when inherited" do
+    it "should be able to be constructed with a json payload" do
+      expect { MyContract.new(@simple_payload_hash) }.not_to raise_exception
+    end
+
+    it "should be able to reproduce the original json from which it was constructed" do
+      contract = MyContract.new(@simple_payload_hash)
+      expect(contract.to_hash).to eq @simple_payload_hash
+    end
+
+    it "should provide a getter for the key that is defined in inheritor::required" do
+      contract = MyContract.new(@simple_payload_hash)
+      expect(contract.foo).to eq @simple_payload_hash['foo']
+    end
+  end
+
+  context "with subcontract" do
+    it "should allow a hash like 'foo' => Foo in the required call" do
+      expect { ComposedContract.new(@complex_payload_hash) }.not_to raise_exception
+    end
+
+    it "should properly convert its subcontract values into contract objects" do
+      contract = ComposedContract.new(@complex_payload_hash)
+      expect(contract.foo).to be_a Foo
+      expect(contract.foo.bar).to eq 'baz'
+    end
+
+    it "should be able to reconstruct the hash from which it was constructed" do
+      expect(ComposedContract.new(@complex_payload_hash).to_hash).to eq @complex_payload_hash
+    end
+  end
+
+  context "with array subcontract" do
+    it "should allow a hash like 'foo' => Foo[] in the required call" do
+      expect { ComposedWithArray.new(@array_payload_hash) }.not_to raise_exception
+    end
+
+    it "should properly map its subcontract values into contract objects" do
+      contract = ComposedWithArray.new(@array_payload_hash)
+      expect(contract.foos.all? { |foo| foo.is_a? Foo }).to be true
+      expect(contract.foos.map(&:bar)).to eq ['baz', 'qux']
+    end
+
+    it "should be able to reconstruct the hash from which it was constructed" do
+      expect(ComposedWithArray.new(@array_payload_hash).to_hash).to eq @array_payload_hash
+    end
+  end
+
+  context "with optional props" do
+    context "missing in the payload" do
+      it "should not throw an exception if the properties are missing" do
+        expect { ComposedWithOptional.new(@complex_payload_hash) }.not_to raise_exception
+      end
+
+      it "should still allow those optional properties to be accessed, just with nil value" do
+        expect(ComposedWithOptional.new(@complex_payload_hash).additionalStuff).to be nil
+      end
+
+      it "should ignore those optional properties when reconstructing the hash" do
+        expect(ComposedWithOptional.new(@complex_payload_hash).to_hash).to eq @complex_payload_hash
+      end
+    end
+
+    context "present in the payload" do
+      it "should parse optional properties properly when they are present" do
+        expect(ComposedWithOptional.new(@complex_with_optional_hash).additionalStuff).to be_a Foo
+        expect(ComposedWithOptional.new(@complex_with_optional_hash).additionalStuff.bar).to eq "and more"
+      end
+
+      it "should ignore those optional properties when reconstructing the hash" do
+        expect(ComposedWithOptional.new(@complex_payload_hash).to_hash).to eq @complex_payload_hash
+      end
+    end
+  end
+
+  context "with custom parser" do
+    it "uses the custom parser to build new objects" do
+      expect(WithCustomParser.new(@complex_payload_hash).foo.bar).to eq "baz (this was the bar)"
+    end
+  end
+
+  context "discriminator" do
+    before(:all) do
+      class Card < Contrackt::Base
+        required      :owner
+        discriminator :type
+      end
+
+      class BusinessCard < Card
+        required :phone
+      end
+
+      class CreditCard < Card
+        required :account
+      end
+    end
+
+    context "not a collection" do
+      before(:all) do
+        @discriminator_hash = { card:
+          { type: "BusinessCard", owner: "Jane Doe", phone: "(555) 555-5555" }
+        }
+
+        class CardPayload < Contrackt::Base
+          required card: Card
+        end
+      end
+
+      it "properly applies the discriminator" do
+        contract = CardPayload.new(@discriminator_hash)
+        expect(contract.card.class).to be BusinessCard
+        expect(contract.card.owner).to eq "Jane Doe"
+      end
+    end
+
+    context "collection" do
+      before(:all) do
+        @discriminator_hash = {
+          cards: [
+            { type: "BusinessCard", owner: "Jane Doe", phone: "(555) 555-5555" },
+            { type: "CreditCard", owner: "Jane Doe", account: "1234-5678-9000-0000" }
+          ]
+        }
+
+        class CardsPayload < Contrackt::Base
+          required cards: Card[]
+        end
+      end
+
+      it "properly applies the discriminator" do
+        contract = CardsPayload.new(@discriminator_hash)
+        expect(contract.cards.first.class).to be BusinessCard
+        expect(contract.cards.first.owner).to eq "Jane Doe"
+        expect(contract.cards.first.phone).to eq "(555) 555-5555"
+        expect(contract.cards.last.class).to be CreditCard
+        expect(contract.cards.last.owner).to eq "Jane Doe"
+        expect(contract.cards.last.account).to eq "1234-5678-9000-0000"
+      end
+
+      it "reproduces the original hash via to_hash" do
+        expect(CardsPayload.new(@discriminator_hash).to_hash).to eq @discriminator_hash
+      end
+    end
+
+    context "custom discriminator handling" do
+      before(:all) do
+        class CustomCard < Contrackt::Base
+          required      :owner
+          discriminator :type, 'business' => BusinessCard, 'credit' => CreditCard
+        end
+
+        class CustomCardsPayload < Contrackt::Base
+          required cards: CustomCard[]
+        end
+
+        @discriminator_hash = {
+          cards: [
+            { type: "business", owner: "Jane Doe", phone: "(555) 555-5555" },
+            { type: "credit", owner: "Jane Doe", account: "1234-5678-9000-0000" }
+          ]
+        }
+      end
+      it "properly applies the discriminator" do
+        contract = CustomCardsPayload.new(@discriminator_hash)
+        expect(contract.cards.first.class).to be BusinessCard
+        expect(contract.cards.first.owner).to eq "Jane Doe"
+        expect(contract.cards.first.phone).to eq "(555) 555-5555"
+        expect(contract.cards.last.class).to be CreditCard
+        expect(contract.cards.last.owner).to eq "Jane Doe"
+        expect(contract.cards.last.account).to eq "1234-5678-9000-0000"
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: contrackt
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- David Reiman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-10-20 00:00:00.000000000 Z
+dependencies: []
+description: Self-documenting contracts for Ruby
+email: david.reiman@creditkarma.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- contrackt.gemspec
+- lib/contrackt.rb
+- lib/contrackt/base.rb
+- lib/contrackt/props.rb
+- lib/contrackt/version.rb
+- spec/contrackt_spec.rb
+homepage: https://github.com/creditkarma/contrackt
+licenses:
+- Apache 2.0
+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.4.6
+signing_key: 
+specification_version: 4
+summary: 'Contrackt: simple Ruby contracts'
+test_files: []