requisite 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 50d02a760bbc8b06f7add5b13fa19f6b3e6d6e84
+  data.tar.gz: ff9ab4dfe47ce3ebf3972bb71f3baf8b29341dd8
+SHA512:
+  metadata.gz: f23920831c22a63ecb735413e0277e67111bfbfbb4b6ddf25e187c6f4163a3150b11b5e5cdaada1da94f9e59c0b8e77b9b0ac53ef63696c129d332f604920448
+  data.tar.gz: 79d2835433fde444c7329a1bbc05847a980fa7d9a93087296fec6ba47574ed9d4a6ff169b825db59028cd5e05036a6811be2be28a10de0d65722e0817f379c7b

data/.gitignore

@@ -0,0 +1 @@
+*.gem

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/LICENCE.txt

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2014 Intercom.io
+
+   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,205 @@
+# Requisite
+
+Requisite is an elegant way of strongly defining request and response models for serialization. How nice would it be if you could do:
+
+```ruby
+def create
+  api_user = ApiRequestUser.new(params)
+  user = User.create(api_user.to_hash)
+  render json: ApiResponseUser.new(user).to_json
+end
+```
+
+Without worrying about strong parameters, type safety and keeping a consistent API?
+
+## Usage
+
+```ruby
+require 'requisite'
+```
+
+## ApiModel
+
+ApiModels are the primary way of using Requisite, they represent a model defined as part of an API. Attributes can be listed within a `serialized_attributes` block, with the format `<attribute-type> <attribute-name> <options>`.
+
+|   method   |                                                                                                               behaviour                                                                                                               |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| attribute  | The attribute with the given name will be looked up on the model, nil if not found. If a method with the same name exists on the UserResponse object it will be called for a value instead. Can take several options. Aliased to `a`. |
+| attribute! | as attribute, but raises an error if not found on model. Aliased to `a!`.                                                                                                                                                             |
+
+ApiModels can be constructed from other objects, or from Hashes (like those you might find in _params_). The helper method `attribute_from_model(:attribute_name)` gives access that will work with either.
+
+These objects have methods to access, and can be serialized back to a Hash (post-transformation; with non-listed parameters removed), or directly to json.
+
+```ruby
+class UserApiModel < Requisite::ApiModel
+  serialized_attributes do
+    attribute! :id
+    attribute! :username
+    attribute :real_name
+  end
+  
+  # method with the name of of an attribute will be called to calculate the mapped value
+  def real_name
+    "#{attribute_from_model(:first_name)} #{attribute_from_model(:last_name)}"
+  end
+end
+
+current_user = User.new(:id => 5, :first_name => 'Jamie', :last_name => 'Osler', :username => 'josler')
+user = UserApiModel.new(current_user)
+user.username
+# => 'josler'
+user.real_name
+# => 'Jamie Osler'
+user.to_hash
+# => { :id => 5, :real_name => 'Jamie Osler', :username => 'josler' }
+user.to_json
+# => "{\"id\":5,\"real_name\":\"Jamie Osler\",\"username\":\"josler\"}"
+```
+
+`nil` values are not returned in the response.
+
+Errors are thrown when a required attribute is not present:
+
+```ruby
+UserApiModel.new({:id => 5, :first_name => 'Jamie', :last_name => 'Osler'}).to_hash
+# => Requisite::NotImplementedError: 'username' not found on model
+```
+
+#### Options
+
+There are several options that can be used with ApiModel attributes:
+
+|    option   |                                                               behaviour                                                               |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| default     | `value` will be used as a default if the attribute is not found. Not available for `attribute!`                                       |
+| stringify   | `.to_s` will be called on `value`                                                                                                     |
+| rename      | The returned value will be sourced from the model's `value` attribute                                                                 |
+| type        | Raises error if value does not match given type. Works on the model's value prior to stringification and renaming. Nils are excluded. |
+| scalar_hash | Attribute is a hash with only scalar values permitted - Numeric, String, TrueClass and FalseClass types.                                                                               |
+| typed_hash  | Attribute is a typed hash, with `value` a hash specifying a mapping of sub-attribute to types.                                        |
+| typed_array | Attribute is a typed array, with `value` specifying the type of elements within the array                                             |
+
+They can also be combined.
+
+Example:
+
+```ruby
+class UserApiModel < Requisite::ApiModel
+  serialized_attributes do
+    attribute :id, stringify: true
+    attribute :custom_attributes, rename: :custom_data 
+    attribute :is_awesome, default: true
+    attribute :awesome_score, rename: :score, stringify: true, default: 9001
+    attribute :age, type: Fixnum,
+    attribute :tired, type: Requisite::Boolean
+  end
+end
+
+current_user = User.new(:id => 5, :custom_data => [ {:number_events => 4} ], :age => 26)
+UserApiModel.new(current_user).to_json
+# => "{\"id\":\"5\",\"custom_attributes\":[{\"number_events\":4}],\"is_awesome\":true,\"awesome_score\":\"9001\",\"age\":26}"
+```
+
+The `Requisite::Boolean` type will match `TrueClass` and `FalseClass`.
+
+#### Nested Structure Support
+
+Nested structure support only applies one level deep; beyond that we recommend you use a nested ApiModel that's well structured.
+
+##### Hashes
+
+ApiModels support nested hashes in two forms; specifying that a Hash should contain only Scalar (Numeric, String and Boolean) values, or a nested hash of a typed attributes.
+
+With scalar hashes, any scalar value is permitted:
+
+```ruby
+class UserApiModel < Requisite::ApiModel
+  serialized_attributes do
+    attribute :data, scalar_hash: true
+  end
+end
+
+UserApiModel.new(:data => {:is_awesome => true, :score => 9001, :name => 'Jamie'}).to_hash
+# => { :data => {:is_awesome => true, :score => 9001, :name => 'Jamie'} }
+```
+
+Non-scalar values will raise a `Requisite::BadTypeError`. Empty scalar hash attributes are returned as `{}`.
+
+With typed hashes, only values specified with a type are permitted:
+
+```ruby
+class UserApiModel < Requisite::ApiModel
+  serialized_attributes do
+    attribute :data, typed_hash: { is_awesome: Requisite::Boolean, score: Fixnum, name: String  }
+  end
+end
+
+UserApiModel.new(:data => {:is_awesome => true, :score => 9001, :name => 'Jamie'}).to_hash
+# => { :data => {:is_awesome => true, :score => 9001, :name => 'Jamie'} }
+```
+
+Note that setting the type to the provided `Requisite::Boolean` permits `TrueClass` and `FalseClass` values.
+
+Fields within a fixed hash that are not listed as permitted will be omitted (even with attribute! their presence will not raise an error).
+
+Fields with the wrong data type will result in a `Requisite::BadTypeError` being raised. Empty typed hash attributes are returned as `{}`.
+
+##### Arrays
+
+Typed arrays are supported; arrays must be all of one type:
+
+```ruby
+class UserApiModel < Requisite::ApiModel
+  serialized_attributes do
+    attribute :ids, typed_array: String
+  end
+end
+
+UserApiModel.new(:ids => ['x123D', 'u71d', '96yD']).to_hash
+# => { :ids => ['x123D', 'u71d', '96yD'] }
+```
+
+Array values not corresponding to the correct type will raise a `Requisite::BadTypeError`. Empty Array attributes will be returned as `[]`.
+
+#### Advanced Nested Structures
+
+To work with advanced nested structures, we recommend you create a method with the attribute name that will be called, and use another ApiModel to perform validation, for example:
+
+```ruby
+class ApiUser < Requisite::ApiModel
+  serialized_attributes do
+    attribute :id, type: String
+    attribute :company
+  end
+
+  # ApiCompany object handles its' own validation
+  def company
+    ApiCompany.new(attribute_from_model(:company)).to_hash
+  end
+end
+```
+
+#### Preprocess Request
+
+A `preprocess_model` method can be defined to carry out any required steps before the model is processed, e.g.:
+
+```ruby
+class ApiUser < Requisite::ApiModel
+  serialized_attributes do
+    attribute :id, type: String
+    attribute :email, type: String
+  end
+
+  # preprocess to check we have an identifier for the user
+  def preprocess_model
+    identifier = attribute_from_model(:id)
+    identifier ||= attribute_from_model(:email)
+    raise IdentifierNotFoundError unless identifier
+  end
+end
+```  
+
+#### Thanks
+
+Strongly inspired by the work done in the [mutations gem](https://github.com/cypriss/mutations), and with [restpack_serializer](https://github.com/RestPack/restpack_serializer), as well as some of the patterns laid out in Robert Martin's demonstrations of [clean architecture](http://blog.8thlight.com/uncle-bob/2012/08/13/the-clean-architecture.html).

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require "bundler"
+
+Bundler.require
+
+Rake::TestTask.new('test') do |test|
+  test.libs << 'lib'
+  test.libs << 'test'
+
+  test.test_files = FileList['test/**/*_test.rb']
+  test.warning = false
+  test.verbose = true
+end

data/lib/requisite.rb

@@ -0,0 +1,6 @@
+require 'requisite/version'
+require 'requisite/boundary_object'
+require 'requisite/boolean'
+require 'requisite/api_model'
+require 'requisite/bad_request_error'
+require 'requisite/bad_type_error'

data/lib/requisite/api_model.rb

@@ -0,0 +1,98 @@
+require 'json'
+
+module Requisite
+  class ApiModel < BoundaryObject
+    attr_reader :model
+    
+    def initialize(model={})
+      @model = model.kind_of?(Hash) ? Hash[model.map{ |k, v| [k.to_sym, v] }] : model
+    end
+    
+    def convert(name)
+      attribute_from_model(name)
+    end
+    
+    def convert!(name)
+      attribute_from_model(name) || (raise NotImplementedError.new("'#{name}' not found on model"))
+    end
+
+    def attribute_from_model(name)
+      if @model.kind_of?(Hash)
+        @model[name]
+      else
+        @model.send(name) if @model.respond_to?(name)
+      end
+    end
+
+    def merge_attribute_if_exists!(to_merge, attribute_name)
+      attribute_from_model(attribute_name) ? to_merge.merge!(attribute_from_model(attribute_name)) : to_merge
+    end
+
+    def to_hash
+      preprocess_model
+      {}.tap do |result|
+        self.class.attribute_keys.each do |meth|
+          value = self.send(meth)
+          result.merge!({meth => value}) unless value.nil?
+        end
+      end
+    end
+    
+    def to_json
+      to_hash.to_json
+    end
+    
+    def parse_typed_hash(name, hash)
+      {}.tap do |result|
+        passed_hash = attribute_from_model(name)
+        hash.each do |key, value|
+          next unless passed_hash && passed_hash[key]
+          raise_bad_type_if_type_mismatch(passed_hash[key], value)
+          result[key] = passed_hash[key]
+        end
+      end
+    end
+    
+    def parse_scalar_hash(name)
+      {}.tap do |result|
+        passed_hash = attribute_from_model(name) || {}
+        passed_hash.each do |key, value|
+          raise BadTypeError.new(value, 'Numeric, String or Boolean') unless (value.kind_of?(Numeric) || value.kind_of?(String) || value.kind_of?(TrueClass) || value.kind_of?(FalseClass))
+          result[key] = value
+        end
+      end
+    end
+    
+    def parse_typed_array(name, type)
+      [].tap do |result|
+        passed_array = attribute_from_model(name) || []
+        passed_array.each do |value|
+          raise_bad_type_if_type_mismatch(value, type)
+          result << value
+        end
+      end
+    end
+    
+    def with_type!(desired_type)
+      yield.tap do |value|
+        raise_bad_type_if_type_mismatch(value, desired_type) if value
+      end
+    end
+    
+    def first_attribute_from_model(*attributes)
+      attributes.each do |attribute|
+        value = attribute_from_model(attribute)
+        if value && !(value.kind_of?(Hash) && value.empty?)
+          return value
+        end
+      end
+      nil
+    end
+    
+    private
+
+    def preprocess_model
+      # noop
+    end
+  end
+end

data/lib/requisite/bad_request_error.rb

@@ -0,0 +1,9 @@
+module Requisite
+  class BadRequestError < StandardError
+    attr_accessor :message
+    
+    def initialize(message = nil)
+      @message = message || self.class.to_s
+    end
+  end
+end

data/lib/requisite/bad_type_error.rb

@@ -0,0 +1,9 @@
+module Requisite
+  class BadTypeError < StandardError
+    attr_accessor :message
+    
+    def initialize(value, desired_class)
+      @message = "Value: #{value} not of type #{desired_class}"
+    end
+  end
+end

data/lib/requisite/boolean.rb

@@ -0,0 +1,4 @@
+module Requisite
+  class Boolean
+  end
+end

data/lib/requisite/boundary_object.rb

@@ -0,0 +1,60 @@
+module Requisite
+  class BoundaryObject
+    class << self
+      def attribute(name, options={})
+        attribute_keys << name
+        define_method(name) do
+          resolved_name = options[:rename] || name
+          result = self.send(:convert, resolved_name)
+          result = self.send(:parse_typed_hash, resolved_name, options[:typed_hash]) if options[:typed_hash]
+          result = self.send(:parse_scalar_hash, resolved_name) if options[:scalar_hash]
+          result = self.send(:parse_typed_array, resolved_name, options[:typed_array]) if options[:typed_array]
+          result = options[:default] if (options[:default] && empty_result?(result))
+          raise_bad_type_if_type_mismatch(result, options[:type]) if options[:type] && result
+          result = result.to_s if options[:stringify]
+          result
+        end
+      end
+      
+      def attribute!(name, options={})
+        attribute_keys << name
+        define_method(name) do
+          resolved_name = options[:rename] || name
+          result = self.send(:convert!, resolved_name)
+          result = self.send(:parse_typed_hash, resolved_name, options[:typed_hash]) if options[:typed_hash]
+          result = self.send(:parse_scalar_hash, resolved_name) if options[:scalar_hash]
+          result = self.send(:parse_typed_array, resolved_name, options[:typed_array]) if options[:typed_array]
+          result = result.to_s if options[:stringify]
+          raise_bad_type_if_type_mismatch(result, options[:type]) if options[:type]
+          result
+        end
+      end
+      
+      def serialized_attributes(&block)
+        @attribute_keys = []
+        instance_eval(&block)
+      end
+
+      def attribute_keys
+        @attribute_keys
+      end
+    end
+
+    private
+    
+    self.singleton_class.send(:alias_method, :a, :attribute)
+    self.singleton_class.send(:alias_method, :a!, :attribute!)
+    
+    def raise_bad_type_if_type_mismatch(value, desired_type)
+      raise BadTypeError.new(value, desired_type) unless (value.kind_of?(desired_type)) || ((value.kind_of?(TrueClass) || value.kind_of?(TrueClass)) && desired_type == Requisite::Boolean)
+    end
+
+    def raise_not_implemented_for_attribute(name)
+      raise NotImplementedError.new("'#{name}' method not implemented")
+    end
+    
+    def empty_result?(result)
+      result.nil? || result == {}
+    end
+  end
+end

data/lib/requisite/version.rb

@@ -0,0 +1,3 @@
+module Requisite
+  VERSION = '0.1.0'
+end

data/requisite.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'requisite/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'requisite'
+  gem.version       = Requisite::VERSION
+  gem.authors       = ['James Osler']
+  gem.email         = ['jamie@intercom.io']
+  gem.summary       = 'Strongly defined models for HTTP APIs'
+  gem.description   = %q{ Requisite is an elegant way of strongly defining request and response models for serialization }
+  gem.homepage      = 'https://www.intercom.io'
+  gem.license       = 'Apache License Version 2.0'
+  gem.add_development_dependency "minitest"
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+end

data/test/requisite/api_event_test.rb

@@ -0,0 +1,37 @@
+require 'test_helper'
+
+## Example Object
+class ApiEvent < Requisite::ApiModel
+  serialized_attributes do
+    attribute! :event_name, type: String
+    attribute :id, type: String
+    attribute :user_id, type: String
+    attribute :email, type: String
+    attribute :metadata, scalar_hash: true
+  end
+end
+
+module Requisite
+  describe ApiEvent do
+    it 'accepts an event' do
+      event_request_params = {
+        :event_name => 'bought',
+        :user_id => 'abcdef',
+        :metadata => {
+          :item => 'CD',
+          :price => 20.01
+        },
+        :junk => 'data'
+      }
+      event = ApiEvent.new(event_request_params)
+      event.to_hash.must_equal({
+        :event_name => 'bought',
+        :user_id => 'abcdef',
+        :metadata => {
+          :item => 'CD',
+          :price => 20.01
+        }
+      })
+    end
+  end
+end

data/test/requisite/api_model_test.rb

@@ -0,0 +1,292 @@
+require 'test_helper'
+
+module Requisite
+  describe ApiModel do
+    it 'creates methods from serialized_attributes block' do
+      ApiModel.serialized_attributes { attribute :a; attribute :b }
+      response = ApiModel.new
+      def response.a; 'A'; end
+      def response.b; 2; end
+      response.to_hash.must_equal( :a => 'A', :b => 2 )
+      response.must_respond_to :a
+      response.must_respond_to :b
+    end
+    
+    it 'attribute provides a default implementation of calling a hash model' do
+      ApiModel.serialized_attributes { attribute :c }
+      mock = {:c => 'C'}
+      response = ApiModel.new(mock)
+      response.to_hash.must_equal( :c => 'C' )
+    end
+
+    let(:params_hash) { {:c => 'C', :num => 12} }
+    
+    it 'attribute provides a default implementation of calling a model' do
+      ApiModel.serialized_attributes { attribute :c }
+      response = ApiModel.new(params_hash)
+      response.to_hash.must_equal(:c => 'C')
+    end
+
+    it 'attribute can work with a default' do
+      ApiModel.serialized_attributes { attribute :c, default: 'see' }
+      response = ApiModel.new
+      response.to_hash.must_equal(:c => 'see')
+    end
+    
+    it 'ignores default if value given' do
+      ApiModel.serialized_attributes { attribute :num, default: 0 }
+      response = ApiModel.new(params_hash)
+      response.to_hash.must_equal(:num => 12)
+    end
+    
+    it 'attribute can be set to stringify fields' do
+      ApiModel.serialized_attributes { attribute :num, stringify: true }
+      response = ApiModel.new(params_hash)
+      response.to_hash.must_equal(:num => '12')
+    end
+    
+    it 'attribute can be set to rename fields' do
+      ApiModel.serialized_attributes { attribute :my_num, rename: :num }
+      response = ApiModel.new(params_hash)
+      response.to_hash.must_equal(:my_num => 12)
+    end
+    
+    it 'attribute can assert type of a field' do
+      ApiModel.serialized_attributes { attribute :num, type: String }
+      response = ApiModel.new(params_hash)
+      proc { response.to_hash }.must_raise(BadTypeError)
+    end
+    
+    it 'with_type! helper raises on mismatched type' do
+      model = ApiModel.new()
+      proc { model.with_type!(String) { 1 + 2 }}.must_raise(Requisite::BadTypeError)
+    end
+    
+    it 'first_attribute_from_model helper finds first matching attriubute' do
+      model = ApiModel.new(:oh => 12, :a => nil, :b => 'B', :c => 'C')
+      model.first_attribute_from_model(:a, :b, :c).must_equal('B')
+    end
+    
+    it 'attribute can assert type of a boolean field' do
+      ApiModel.serialized_attributes { attribute :truthy_val, type: Requisite::Boolean }
+      response = ApiModel.new(:truthy_val => false)
+      response.to_hash.must_equal(:truthy_val => false)
+    end
+    
+    it 'attribute does not include values of nil' do
+      ApiModel.serialized_attributes { attribute :num, type: String }
+      response = ApiModel.new({:num => nil})
+      response.to_hash.must_equal({})
+    end
+    
+    it 'attribute can be stringified and renamed with default fields' do
+      ApiModel.serialized_attributes { attribute :my_num, rename: :num, stringify: true, default: 22 }
+      response = ApiModel.new
+      response.to_hash.must_equal(:my_num => '22')
+    end
+    
+    it 'attribute can be stringified after type check' do
+      ApiModel.serialized_attributes { attribute :num, stringify: true, type: Fixnum }
+      response = ApiModel.new(params_hash)
+      response.to_hash.must_equal(:num => '12')
+    end
+    
+    it 'attribute type checks after rename' do
+      ApiModel.serialized_attributes { attribute :my_num, rename: :num, type: String }
+      response = ApiModel.new(params_hash)
+      proc { response.to_hash }.must_raise(BadTypeError)
+    end
+    
+    it 'attribute can be stringified, renamed, defaulted and have type checking on a field' do
+      ApiModel.serialized_attributes { attribute :my_num, rename: :num, stringify: true, default: 22, type: String }
+      response = ApiModel.new
+      proc { response.to_hash }.must_raise(BadTypeError)
+    end
+    
+    let(:invalid_params_hash) { {:d => nil} }
+
+    it "attribute! raises an error if not found on model" do
+      ApiModel.serialized_attributes { attribute! :d }
+      response = ApiModel.new(invalid_params_hash)
+      proc { response.to_hash }.must_raise(NotImplementedError, "'d' not found on model")
+    end
+        
+    it 'attribute! can be set to stringify fields' do
+      ApiModel.serialized_attributes { attribute! :num, stringify: true }
+      response = ApiModel.new(params_hash)
+      response.to_hash.must_equal(:num => '12')
+    end
+    
+    it 'attribute! can be set to rename fields' do
+      ApiModel.serialized_attributes { attribute! :my_num, rename: :num }
+      response = ApiModel.new(params_hash)
+      response.to_hash.must_equal(:my_num => 12)
+    end
+
+    it 'sets the model from a hash' do
+      ApiModel.serialized_attributes { }
+      response = ApiModel.new(params_hash)
+      response.model.must_equal(params_hash)
+    end
+    
+    it 'sets the model from an object' do
+      mc = MockClass.new
+      mc.a = 'a'
+      mc.b = 2
+      ApiModel.serialized_attributes { attribute :a }
+      response = ApiModel.new(mc)
+      response.model.must_equal(mc)
+      response.to_hash.must_equal(:a => 'a')
+    end
+    
+    it 'has alias a for attribute' do
+      ApiModel.serialized_attributes { a :num }
+      response = ApiModel.new(params_hash)
+      response.to_hash.must_equal(:num => 12)
+    end
+    
+    it 'has alias a! for attribute!' do
+      ApiModel.serialized_attributes { a! :num }
+      response = ApiModel.new(params_hash)
+      response.to_hash.must_equal(:num => 12)
+    end
+    
+    it 'can convert to json' do
+      ApiModel.serialized_attributes { a! :num }
+      response = ApiModel.new(params_hash)
+      response.to_json.must_equal("{\"num\":12}")
+    end
+    
+    it 'drops non-listed parameters' do
+      ApiModel.serialized_attributes { attribute :num }
+      response = ApiModel.new({num: 12, other: 'value'})
+      response.to_hash.must_equal(:num => 12)
+    end
+    
+    describe 'with nested structures' do
+      
+      describe 'with typed arrays' do
+        it 'allows arrays of one type' do
+          ApiModel.serialized_attributes { attribute :ids, typed_array: Fixnum }
+          response = ApiModel.new({ids: [1, 2, 3]})
+          response.to_hash.must_equal(:ids => [1, 2, 3])
+        end
+        
+        it 'raises errors when array has a wrongly typed value' do
+          ApiModel.serialized_attributes { attribute :ids, typed_array: Requisite::Boolean }
+          response = ApiModel.new({ids: [true, 'value', false]})
+          Proc.new {response.to_hash}.must_raise(BadTypeError)
+        end
+      end
+      
+      describe 'with typed nested hashes' do
+        it 'drops non listed parameters in nested hashes' do
+          ApiModel.serialized_attributes { attribute :data, typed_hash: { num: Numeric, bool: Requisite::Boolean } }
+          response = ApiModel.new({data: { num: 12, value: 'x', bool: true }})
+          response.to_hash.must_equal(:data => { :num => 12, :bool => true })
+        end
+        
+        it 'can stringify nested hashes' do
+          ApiModel.serialized_attributes { attribute :data, typed_hash: { num: Numeric }, stringify: true }
+          response = ApiModel.new({data: { num: 12, value: 'x' }})
+          response.to_hash.must_equal(:data => "{:num=>12}")
+        end
+        
+        it 'raises an error when nested hash values of the wrong type' do
+          ApiModel.serialized_attributes { attribute :data, typed_hash: { num: Numeric } }
+          Proc.new {ApiModel.new({data: { num: '12'}}).to_hash}.must_raise(BadTypeError)
+        end
+              
+        it 'can rename param and work with nested hashes' do
+          ApiModel.serialized_attributes { attribute :my_data, typed_hash: { num: Numeric }, rename: :data }
+          response = ApiModel.new({data: { num: 12, value: 'x' }})
+          response.to_hash.must_equal(:my_data => { :num => 12 })
+        end
+        
+        it 'can set a default value for a nested hash' do
+          ApiModel.serialized_attributes { attribute :data, typed_hash: { num: Numeric }, default: { num: 4 } }
+          response = ApiModel.new({data: { value: 'x' }})
+          response.to_hash.must_equal(:data => { :num => 4 })
+        end
+        
+        it 'drops non listed fields with attribute!' do
+          ApiModel.serialized_attributes { attribute! :data, typed_hash: { num: Numeric } }
+          response = ApiModel.new({data: { num: 12, value: 'x' }})
+          response.to_hash.must_equal(:data => { :num => 12 })
+        end
+        
+        it 'attribute! does not raise an error with missing values in hash' do
+          ApiModel.serialized_attributes { attribute! :data, typed_hash: { num: Numeric } }
+          response = ApiModel.new({data: { value: 'x' }})
+          response.to_hash.must_equal(:data => { })
+        end
+      end
+      
+      describe 'with scalar only nested hashes' do
+        it 'should parse scalar hashes permitting anything scalar' do
+          ApiModel.serialized_attributes { attribute :data, scalar_hash: true }
+          response = ApiModel.new({data: { num: 12, value: 'x', :truthy => false }})
+          response.to_hash.must_equal(:data => { :num => 12, :value => 'x', :truthy => false })
+        end
+        
+        it 'should parse a renamed scalar hash' do
+          ApiModel.serialized_attributes { attribute :my_data, scalar_hash: true, rename: :data }
+          response = ApiModel.new({data: { num: 12, value: 'x' }})
+          response.to_hash.must_equal(:my_data => { :num => 12, :value => 'x' })
+        end
+        
+        it 'should stringify a scalar hash' do
+          ApiModel.serialized_attributes { attribute :data, scalar_hash: true, stringify: true }
+          response = ApiModel.new({data: { num: 12, value: 'x' }})
+          response.to_hash.must_equal(:data => "{:num=>12, :value=>\"x\"}")
+        end
+        
+        it 'should parse scalar hashes permitting anything scalar with object' do
+          mc = MockClass.new
+          mc.a = 'a'
+          mc.b = { num: 12, value: 'x' }
+          ApiModel.serialized_attributes { attribute :b, scalar_hash: true }
+          response = ApiModel.new(mc)
+          response.to_hash.must_equal(:b => { :num => 12, :value => 'x' })
+        end
+        
+        it 'should fail to parse scalar hashes when non scalar values present' do
+          ApiModel.serialized_attributes { attribute :data, scalar_hash: true }
+          Proc.new { ApiModel.new({data: { num: 12, value: { nested: 'value' } }}).to_hash}.must_raise(BadTypeError)
+          Proc.new { ApiModel.new({data: { num: 12, value: ['array value'] }}).to_hash}.must_raise(BadTypeError)
+        end
+        
+        it 'should fail to parse scalar hashes permitting anything scalar with object' do
+          mc = MockClass.new
+          mc.a = 'a'
+          mc.b = { value: { nested: 'value' } }
+          ApiModel.serialized_attributes { attribute :b, scalar_hash: true }
+          response = ApiModel.new(mc)
+          Proc.new { response.to_hash }.must_raise(BadTypeError)
+        end
+        
+        it 'can set a default value for a scalar hash' do
+          ApiModel.serialized_attributes { attribute :data, scalar_hash: true, default: { num: 9, value: 'y' } }
+          response = ApiModel.new({data: { }})
+          response.to_hash.must_equal(:data => { :num => 9, :value => 'y' })
+        end
+        
+        it 'doesnt raise with attribute! when an empty hash passed' do
+          ApiModel.serialized_attributes { attribute! :data, scalar_hash: true }
+          response = ApiModel.new({data: {}})
+          response.to_hash.must_equal(:data => {})
+        end
+        
+        it 'raises with attribute! when nil is passed' do
+          ApiModel.serialized_attributes { attribute! :data, scalar_hash: true }
+          response = ApiModel.new({data: nil})
+          Proc.new {response.to_hash}.must_raise(NotImplementedError)
+        end
+      end
+    end
+  end
+end
+
+class MockClass
+  attr_accessor :a, :b
+end

data/test/requisite/api_user_test.rb

@@ -0,0 +1,75 @@
+require 'test_helper'
+
+# Example Object
+class ApiUser < Requisite::ApiModel
+  serialized_attributes do
+    attribute :id, type: String
+    attribute :user_id
+    attribute :email, type: String
+    attribute :name, type: String
+    attribute :created_at, type: Fixnum
+    attribute :last_seen_user_agent, type: String
+    attribute :last_request_at, type: Fixnum
+    attribute :unsubscribed_from_emails, type: Requisite::Boolean
+    attribute :update_last_request_at, type: Requisite::Boolean
+    attribute :new_session, type: Requisite::Boolean
+    attribute :custom_data, scalar_hash: true, rename: :custom_attributes
+    attribute :company
+    attribute :companies
+  end
+  
+  # Ensure that at least one identifier is passed
+  def preprocess_model
+    identifier = attribute_from_model(:id)
+    identifier ||= attribute_from_model(:user_id)
+    identifier ||= attribute_from_model(:email)
+    raise StandardError unless identifier
+  end
+  
+  # We want to accept someone sending `created_at` or `created` as parameters
+  def created_at
+    with_type!(Fixnum) { attribute_from_model(:created_at) || attribute_from_model(:created) }
+  end
+end
+
+module Requisite
+  describe ApiUser do
+    it 'accepts a user' do
+      user_request_params = {
+        :user_id => 'abcdef',
+        :name => 'Bob',
+        :created => 1414173164,
+        :new_session => true,
+        :custom_attributes => {
+          :is_cool => true,
+          :logins => 77
+        },
+        :junk => 'data'
+      }
+      user = ApiUser.new(user_request_params)
+      user.to_hash.must_equal({
+        :user_id => 'abcdef',
+        :name => 'Bob',
+        :created_at => 1414173164,
+        :new_session => true,
+        :custom_data => {
+          :is_cool => true,
+          :logins => 77
+        }
+      })
+      user.name.must_equal('Bob')
+    end
+    
+    it 'raises an error without an identifier' do
+      user_request_params = { :name => 'Bob' }
+      user = ApiUser.new(user_request_params)
+      proc { user.to_hash }.must_raise(StandardError)
+    end
+    
+    it 'raises an error when created or created_at is not of the right type' do
+      user_request_params = { :user_id => 'abcdef', :created => 'Thursday' }
+      user = ApiUser.new(user_request_params)
+      proc { user.to_hash }.must_raise(Requisite::BadTypeError)
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+require 'requisite'
+require 'minitest/autorun'
+require 'minitest/mock'
+require 'minitest/spec'

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: requisite
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- James Osler
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ' Requisite is an elegant way of strongly defining request and response
+  models for serialization '
+email:
+- jamie@intercom.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENCE.txt
+- README.md
+- Rakefile
+- lib/requisite.rb
+- lib/requisite/api_model.rb
+- lib/requisite/bad_request_error.rb
+- lib/requisite/bad_type_error.rb
+- lib/requisite/boolean.rb
+- lib/requisite/boundary_object.rb
+- lib/requisite/version.rb
+- requisite.gemspec
+- test/requisite/api_event_test.rb
+- test/requisite/api_model_test.rb
+- test/requisite/api_user_test.rb
+- test/test_helper.rb
+homepage: https://www.intercom.io
+licenses:
+- Apache License Version 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.0.14
+signing_key: 
+specification_version: 4
+summary: Strongly defined models for HTTP APIs
+test_files:
+- test/requisite/api_event_test.rb
+- test/requisite/api_model_test.rb
+- test/requisite/api_user_test.rb
+- test/test_helper.rb
+has_rdoc: