brainstem-adaptor 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6746d8612cec0a387c002ad99c0a75615ef2c00c
+  data.tar.gz: f9cc76d40aaa1bc0fc53461f6caa7e6e34bbfc68
+SHA512:
+  metadata.gz: fa62456fbccacbaa9236b7174acef004b4fdf101a85048432498d802bcf54b4910df7a11306de996467b5e5458ca284dd6d059929b3dc8a5cfc4396158940753
+  data.tar.gz: 09887da73e019a9b9ab8bc9b7f2a10b270ca780dcf3aede4cca0be0f2951907106e995eeeb1acb23c1f86ba448505fbe0db72863ab419b1decea0e44b7e65534

data/.gitignore

@@ -0,0 +1,10 @@
+*.gem
+.yardoc
+rdoc
+coverage
+.bundle
+.ruby-version
+.rvmrc
+.idea
+Gemfile.lock
+

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - "2.0.0"
+  - "1.9.3"

data/Gemfile

@@ -0,0 +1,3 @@
+source 'http://rubygems.org'
+gemspec
+gem 'rake'

data/README.md

@@ -0,0 +1,98 @@
+## Ruby Brainstem Adaptor
+[![Build Status](https://travis-ci.org/einzige/brainstem-adaptor.svg?branch=master)](https://travis-ci.org/einzige/brainstem-adaptor)
+[![Dependency Status](https://gemnasium.com/einzige/brainstem-ruby.svg)](https://gemnasium.com/einzige/brainstem-ruby)
+
+Brainstem Adaptor provides an easy to use interface for [Brainstem](https://github.com/mavenlink/brainstem) API.
+
+```ruby
+BrainstemAdaptor.load_specification('my_api_service.yml')
+response_data = MyApi.get('/users.json')
+
+# response_data can be a JSON string or Hash
+response = BrainstemAdaptor::Response.new(response_data)
+
+response.count                 # returns total count as Integer
+# ...
+response.results               # returns Array<BrainstemAdaptor::Record>
+response.results[0]['friends'] # returns Array<BrainstemAdaptor::Record>
+
+response.results[0]['friends'].last['name']
+
+response.results[0]['name']    # returns String
+response.results[0].id         # returns String or Integer
+response.results[0]['mom']     # returns BrainstemAdaptor::Record
+
+response.results[0]['mom']['name']
+# ...
+response['users']              # returns plain Hash as is from response
+response['count']              # same here, Integer
+```
+
+## Installation
+
+Run:
+```bash
+gem install brainstem-adaptor
+```
+
+Or put in your Gemfile:
+```ruby
+gem 'brainstem-adaptor'
+```
+
+## Configuration
+#### Create specification for your API.
+The only missing thing in Brainstem responses is an __associations information__.
+Having `customer_ids` field does not guarantee that customer ids are related to `customers` collection, those may also be ids of `users` collection.
+Specification is the thing which describes missing information about responses you receive.
+You can also put any additional information you need in your specification (see details below).
+
+```yaml
+---
+# my_api_service.yml file
+users:
+  associations:
+    friends:
+      foreign_key: friend_ids
+      collection: 'users'
+    mom:
+      foreign_key: mom_id
+      collection: 'users'
+
+projects:
+  fields:
+    name:
+      type: string
+      required: true
+    employee_ids:
+      type: array
+
+  associations:
+    employees:
+      foreign_key: employee_ids
+      collection: users
+```
+
+### Multiple specifications
+
+You may also have multiple APIs which have different specificaitons.
+
+```ruby
+BrainstemAdaptor::Specification[:my_tracker_api] = { 'users' => {} } # ...
+response_data = MyApi.get('/users.json')
+
+response = BrainstemAdaptor::Response.new(response_data, BrainstemAdaptor::Specification[:my_tracker_api])
+# ...
+```
+
+## Contributing
+
+1. Fork
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request (`git pull-request`)
+
+## License
+
+Brainstem Adaptor was created by Mavenlink, Inc. and are available under the MIT License.

data/Rakefile

@@ -0,0 +1,6 @@
+#!/usr/bin/env rake
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new :spec
+task :default => :spec
+

data/brainstem-adaptor.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{brainstem-adaptor}
+  s.version = "0.0.3"
+
+  s.date = %q{2014-03-10}
+  s.authors = ["Sergei Zinin (einzige)"]
+  s.email = %q{szinin@gmail.com}
+  s.homepage = %q{http://github.com/einzige/brainstem-adaptor}
+
+  s.licenses = ["MIT"]
+
+  s.files = `git ls-files`.split("\n")
+  s.require_paths = ["lib"]
+  s.extra_rdoc_files = ["README.md"]
+
+  s.description = %q{Parses Brainstem responses, makes it convenient to organize access to your data.}
+  s.summary = %q{Brainstem API Adaptor}
+
+  s.add_development_dependency 'rspec'
+  s.add_runtime_dependency 'activesupport', ">= 3.0.0"
+end
+
+

data/lib/brainstem-adaptor.rb

@@ -0,0 +1,40 @@
+require 'yaml'
+require 'json'
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/hash/slice'
+require 'active_support/core_ext/object/try'
+require 'brainstem_adaptor/specification'
+require 'brainstem_adaptor/association'
+require 'brainstem_adaptor/record'
+require 'brainstem_adaptor/invalid_response_error'
+require 'brainstem_adaptor/response'
+
+module BrainstemAdaptor
+  VERSION = '0.0.3'
+
+  def self.parser
+    @parser ||= JSON
+  end
+
+  # @param parser Any JSON parser
+  # @raise [ArgumentError] if parser does not respond to #parse
+  def self.parser=(parser)
+    raise ArgumentError, 'Parser must respond to #parse message' unless parser.respond_to?(:parse)
+    @parser = parser
+  end
+
+  # @return [BrainstemAdaptor::Specification]
+  def self.default_specification
+    BrainstemAdaptor::Specification[:default]
+  end
+
+  # @param specification [Hash]
+  def self.specification=(specification)
+    BrainstemAdaptor::Specification[:default] = specification
+  end
+
+  # @param path [String] Path to YML specification file
+  def self.load_specification(path)
+    self.specification = YAML::load_file(path)
+  end
+end

data/lib/brainstem_adaptor/association.rb

@@ -0,0 +1,73 @@
+module BrainstemAdaptor
+  class Association
+    include Enumerable
+
+    attr_reader :name, :record, :specification, :collection_name, :foreign_key
+
+    # @param record [BrainstemAdaptor::Record]
+    # @param name [String, Symbol]
+    def initialize(record, name)
+      @name = name.to_s
+
+      unless record.has_association?(@name)
+        raise ArgumentError, "No '#@name' specification found for #{record.collection_name}"
+      end
+
+      @record          = record
+      @specification   = record.associations_specification[@name]
+      @collection_name = @specification['collection'] || @name
+      @foreign_key     = @specification['foreign_key']
+    end
+
+    # @param other [Enumerable]
+    # @return [true, false]
+    def ==(other)
+      other == each.to_a
+    end
+
+    # @param order [Integer] Index in collection starting from zero
+    def [](order)
+      records[order]
+    end
+
+    # @return [Enumerable]
+    def each(&block)
+      records.each(&block)
+    end
+
+    def has_many?
+      ids.is_a?(Array)
+    end
+
+    def has_one?
+      !has_many?
+    end
+
+    # Checks if association has been included in request
+    # @return [true, false]
+    def loaded?
+      (!record[foreign_key].nil?) && (!!record.response[@collection_name].try(:any?))
+    end
+
+    # @return [Array<BrainstemAdaptor::Record>]
+    def records
+      [*ids].map do |id|
+        BrainstemAdaptor::Record.new(collection_name, id, record.response)
+      end
+    end
+    alias_method :all, :records
+
+    # Returns relation object for has_many associations and record for has_one
+    # Acts as AR::find for has_one associations, as AR::where for has_many
+    # @return [BrainstemAdaptor::Record, self]
+    def reflect
+      has_many? ? self : records.first
+    end
+
+    private
+
+    def ids # TODO(SZ): move to public?
+      record[foreign_key]
+    end
+  end
+end

data/lib/brainstem_adaptor/invalid_response_error.rb

@@ -0,0 +1,12 @@
+module BrainstemAdaptor
+  class InvalidResponseError < StandardError
+    attr_reader :response
+
+    # @param [Hash] response
+    # @param [Stirng] message
+    def initialize(response, message = response.inspect)
+      @response = response
+      super(message)
+    end
+  end
+end

data/lib/brainstem_adaptor/record.rb

@@ -0,0 +1,74 @@
+module BrainstemAdaptor
+  class Record < ActiveSupport::HashWithIndifferentAccess
+    attr_reader :collection_name, :id, :response
+
+    # @param collection_name [String, Symbol]
+    # @param id
+    # @param response [BrainstemAdaptor::Response, nil]
+    def initialize(collection_name, id, response = nil)
+      super([])
+      @collection_name = collection_name.to_s
+      @id = id
+      load_fields_with(response) if response
+    end
+
+    # @param key [String]
+    def [](key)
+      if has_key?(key = key.to_s)
+        super
+      elsif has_association?(key)
+        association_by_name(key).reflect
+      end
+    end
+
+    # @return [Hash]
+    def associations_specification
+      @associations_specification ||= specification['associations'] || {}
+    end
+
+    # @param name [String]
+    # @raise [ArgumentError] if name is not related to any association
+    # @return [BrainstemAdaptor::Association]
+    def association_by_name(name)
+      if has_association?(name)
+        (@associations ||= {})[name] ||= BrainstemAdaptor::Association.new(self, name)
+      end
+    end
+
+    # @param name [String]
+    def has_association?(name)
+      associations_specification.has_key?(name.to_s)
+    end
+
+    # @return [Hash]
+    def specification
+      @specification ||= {}
+    end
+
+    protected
+
+    # @param response [Brainstem::Response]
+    # @param fields_to_reload [Array] Reloads all fields if empty
+    def load_fields_with(response, fields_to_reload = [])
+      @response = response
+
+      if @response.specification.has_key?(collection_name)
+        @specification = @response.specification[collection_name] || {}
+      else
+        raise BrainstemAdaptor::InvalidResponseError, "Can't find '#{collection_name}' association in specification"
+      end
+
+      collection = @response[@collection_name] or
+        raise BrainstemAdaptor::InvalidResponseError, "No such collection #@collection_name"
+
+      fields = collection[@id] or
+        raise BrainstemAdaptor::InvalidResponseError, "No such record #{@collection_name}##{@id}"
+
+      if fields_to_reload.any?
+        merge!(fields.slice(*fields_to_reload))
+      else
+        merge!(fields)
+      end
+    end
+  end
+end

data/lib/brainstem_adaptor/response.rb

@@ -0,0 +1,57 @@
+module BrainstemAdaptor
+  class Response
+    attr_reader :response_data, :specification
+
+    # @param response_data [String, Hash]
+    # @param specification [BrainstemAdaptor::Specification]
+    def initialize(response_data, specification = BrainstemAdaptor.default_specification)
+      @specification = specification or raise ArgumentError, 'Specification is not set'
+
+      case response_data
+      when String
+        @response_data = BrainstemAdaptor.parser.parse(response_data)
+      when Hash
+        @response_data = response_data
+      else
+        raise ArgumentError, "Expected String, got #{@response_data.class.name}"
+      end
+
+      raise InvalidResponseError, "count isn't returned" unless @response_data['count']
+      raise InvalidResponseError, "results collection isn't returned" unless @response_data['results']
+      raise InvalidResponseError, "results collection is not an array" unless @response_data['results'].is_a?(Array)
+
+    rescue JSON::ParserError => e
+      raise BrainstemAdaptor::InvalidResponseError, response_data, e.message
+    end
+
+    # @param key [String, Symbol]
+    # @return [Hash, nil]
+    def [](key)
+      response_data[key.to_s]
+    end
+
+    # Returns __TOTAL__ number of records
+    # @return [Integer]
+    def count
+      response_data['count']
+    end
+    alias_method :total_count, :count
+
+    # @return [String]
+    def to_hash
+      response_data
+    end
+
+    # Returns results has with proper ordering
+    # @return [Array<BrainstemAdaptor::Record>]
+    def results
+      self['results'].map do |result|
+        BrainstemAdaptor::Record.new(result['key'], result['id'], self)
+      end
+    end
+
+    def ==(other)
+      other == response_data
+    end
+  end
+end

data/lib/brainstem_adaptor/specification.rb

@@ -0,0 +1,27 @@
+module BrainstemAdaptor
+  class Specification < Hash
+
+    # @param specification [Hash]
+    def initialize(specification)
+      super
+      self.merge!(specification)
+    end
+
+    # @return [Hash]
+    def self.instances
+      @instances ||= {}
+    end
+
+    # @param key [Symbol] Specification name
+    # @return [BrainstemAdaptor::Specification]
+    def self.[](key)
+      self.instances[key.to_sym] or raise ArgumentError, "No such specification '#{key}'"
+    end
+
+    # @param key [Symbol] Specification name
+    # @param value [Hash] Specification body
+    def self.[]=(key, value)
+      self.instances[key.to_sym] = self.new(value)
+    end
+  end
+end

data/spec/lib/brainstem_adaptor/association_spec.rb

@@ -0,0 +1,243 @@
+require 'spec_helper'
+
+describe BrainstemAdaptor::Association do
+  let(:nickolai) { { 'name' => 'Nickolai', 'friend_ids' => ['13', '14'], 'enemy_id' => '14' } }
+  let(:ivan)     { { 'name' => 'Ivan',     'friend_ids' => [],           'enemy_id' => '12' } }
+  let(:anatolii) { { 'name' => 'Anatolii', 'friend_ids' => ['13', '14'], 'enemy_id' => '12' } }
+
+  let(:response_data) do
+    {
+      'count' => 0,
+      'results' => [],
+      'users' => {
+        '12' => nickolai,
+        '13' => ivan,
+        '14' => anatolii
+      }
+    }
+  end
+
+  let(:specification) do
+    {
+      'users' => {
+        'fields' => {
+          'name' => {}
+        },
+        'associations' => {
+          'friends' => {
+            'foreign_key' => 'friend_ids',
+            'collection' => 'users'
+          },
+          'enemy' => {
+            'foreign_key' => 'enemy_id',
+            'collection' => 'users'
+          },
+          'mother_in_law' => {
+            'foreign_key' => 'mother_in_law_id',
+            'collection' => 'users'
+          },
+          'some_empty' => {
+            'foreign_key' => 'friend_ids',
+            'collection' => 'some_empty_collection'
+          }
+        }
+      }
+    }
+  end
+
+  let(:response) do
+    BrainstemAdaptor::Response.new(response_data, specification)
+  end
+
+  let(:nickolai_user) { BrainstemAdaptor::Record.new('users', '12', response) }
+  let(:ivan_user)     { BrainstemAdaptor::Record.new('users', '13', response) }
+  let(:anatolii_user) { BrainstemAdaptor::Record.new('users', '14', response) }
+
+  let(:nickolai_friends) { described_class.new(nickolai_user, 'friends') }
+  let(:ivan_friends)     { described_class.new(ivan_user,     'friends') }
+  let(:anatoliy_friends) { described_class.new(anatolii_user, 'friends') }
+
+  let(:nickolai_enemy) { described_class.new(nickolai_user, 'enemy') }
+  let(:ivan_enemy)     { described_class.new(ivan_user,     'enemy') }
+  let(:anatoliy_enemy) { described_class.new(anatolii_user, 'enemy') }
+
+  describe '#==' do
+    context 'has_many relations' do
+      specify do
+        expect(nickolai_friends).to eq(anatoliy_friends)
+      end
+
+      specify do
+        expect(nickolai_friends).not_to eq(ivan_friends)
+      end
+
+      specify do
+        expect(nickolai_friends).to eq(nickolai_friends)
+      end
+
+      specify do
+        expect(ivan_friends).not_to eq(nickolai_friends)
+      end
+
+      specify do
+        expect(ivan_friends).not_to eq(anatoliy_friends)
+      end
+
+      specify do
+        expect(ivan_friends).to eq(ivan_friends)
+      end
+
+      specify do
+        expect(anatoliy_friends).to eq(nickolai_friends)
+      end
+
+      specify do
+        expect(anatoliy_friends).not_to eq(ivan_friends)
+      end
+
+      specify do
+        expect(anatoliy_friends).to eq(anatoliy_friends)
+      end
+    end
+
+    context 'has_one relations' do
+      specify do
+        expect(nickolai_enemy).not_to eq(anatoliy_enemy)
+      end
+
+      specify do
+        expect(nickolai_enemy).not_to eq(ivan_enemy)
+      end
+
+      specify do
+        expect(nickolai_enemy).to eq(nickolai_enemy)
+      end
+
+      specify do
+        expect(ivan_enemy).not_to eq(nickolai_enemy)
+      end
+
+      specify do
+        expect(ivan_enemy).to eq(anatoliy_enemy)
+      end
+
+      specify do
+        expect(ivan_enemy).to eq(ivan_enemy)
+      end
+
+      specify do
+        expect(anatoliy_enemy).not_to eq(nickolai_enemy)
+      end
+
+      specify do
+        expect(anatoliy_enemy).to eq(ivan_enemy)
+      end
+
+      specify do
+        expect(anatoliy_enemy).to eq(anatoliy_enemy)
+      end
+    end
+  end
+
+  describe '#[]' do
+    specify do
+      expect(nickolai_friends[0]).to eq(ivan)
+    end
+
+    specify do
+      expect(nickolai_friends[0]).to eq(ivan_user)
+    end
+
+    specify do
+      expect(nickolai_friends[1]).to eq(anatolii)
+    end
+
+    specify do
+      expect(nickolai_friends[1]).to eq(anatolii_user)
+    end
+
+    specify do
+      expect(nickolai_friends[2]).to be_nil
+    end
+
+    specify do
+      expect(nickolai_enemy[0]).to eq(anatolii)
+    end
+
+    specify do
+      expect(nickolai_enemy[0]).to eq(anatolii_user)
+    end
+
+    specify do
+      expect(nickolai_enemy[1]).to be_nil
+    end
+  end
+
+  describe '#each' do
+    specify do
+      expect(nickolai_friends.each).to be_a Enumerable
+    end
+  end
+
+  describe '#records' do
+    specify do
+      expect(nickolai_friends.records).to eq([ivan, anatolii])
+    end
+
+    specify do
+      expect(nickolai_enemy.records).to eq([anatolii])
+    end
+  end
+
+  describe '#reflect' do
+    specify do
+      expect(nickolai_friends.reflect).to eq(nickolai_friends)
+    end
+
+    specify do
+      expect(nickolai_enemy.reflect).to eq(anatolii)
+    end
+  end
+
+  context 'association is not included in specification' do
+    subject { described_class.new(nickolai_user, 'something wrong') }
+
+    specify do
+      expect { subject }.to raise_error ArgumentError, /specification/
+    end
+  end
+
+  describe '#has_many?' do
+    specify do
+      expect(nickolai_friends.has_many?).to eq(true)
+    end
+
+    specify do
+      expect(nickolai_enemy.has_many?).to eq(false)
+    end
+  end
+
+  describe '#has_one?' do
+    specify do
+      expect(nickolai_friends.has_one?).to eq(false)
+    end
+
+    specify do
+      expect(nickolai_enemy.has_one?).to eq(true)
+    end
+  end
+
+  describe '#loaded?' do
+    specify do
+      expect(nickolai_user.association_by_name('mother_in_law').loaded?).to eq(false)
+    end
+
+    specify do
+      expect(nickolai_user.association_by_name('friends').loaded?).to eq(true)
+    end
+
+    specify do
+      expect(nickolai_user.association_by_name('some_empty').loaded?).to eq(false)
+    end
+  end
+end

data/spec/lib/brainstem_adaptor/invalid_response_error_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+describe BrainstemAdaptor::InvalidResponseError do
+  subject { described_class.new(response) }
+  let(:response) { {failed: true} }
+
+  its(:response) { should == response }
+  its(:message) { should include('failed') }
+
+  specify do
+    expect { raise BrainstemAdaptor::InvalidResponseError, 'failed' }.to raise_error(described_class)
+  end
+end

data/spec/lib/brainstem_adaptor/record_spec.rb

@@ -0,0 +1,139 @@
+require 'spec_helper'
+
+describe BrainstemAdaptor::Record do
+  let(:response_data) do
+    {
+      'count' => 0,
+      'results' => [],
+      'users' => {
+        '12' => { 'name' => 'Petr', 'friend_ids' => ['13'], 'enemy_id' => nil },
+        '13' => { 'name' => 'Pelat', 'friend_ids' => [], 'enemy_id' => '12' },
+      }
+    }
+  end
+
+  let(:specification) do
+    {
+      'users' => {
+        'fields' => {
+          'name' => {}
+        },
+        'associations' => {
+          'friends' => {
+            'foreign_key' => 'friend_ids',
+            'collection' => 'users'
+          },
+          'enemy' => {
+            'foreign_key' => 'enemy_id',
+            'collection' => 'users'
+          }
+        }
+      }
+    }
+  end
+
+  let(:response) do
+    BrainstemAdaptor::Response.new(response_data, specification)
+  end
+
+  subject { described_class.new('users', '12', response) }
+
+  its(:id) { should == '12' }
+  its(:collection_name) { should == 'users' }
+  its(:response) { should == response }
+  its(:associations_specification) { should == specification['users']['associations'] }
+
+  context 'invalid response' do
+    context 'collection is not described in specification' do
+      let(:specification) { {} }
+
+      specify do
+        expect { subject }.to raise_error BrainstemAdaptor::InvalidResponseError, /association/
+      end
+    end
+
+    context 'collection is not included in response' do
+      let(:response_data) { {'count' => 0, 'results' => []} }
+
+      specify do
+        expect { subject }.to raise_error BrainstemAdaptor::InvalidResponseError, /collection/
+      end
+    end
+
+    context 'record is not listed in collection' do
+      let(:response_data) { {'count' => 0, 'results' => [], 'users' => {} } }
+
+      specify do
+        expect { subject }.to raise_error BrainstemAdaptor::InvalidResponseError, /record/
+      end
+    end
+  end
+
+  describe '#[]' do
+    specify do
+      expect(subject['name']).to eq('Petr')
+    end
+
+    specify do
+      expect(subject['friends']).to eq([{'name' => 'Pelat', 'friend_ids' => [], 'enemy_id' => '12'}])
+    end
+
+    specify do
+      expect(subject['enemy']).to be_nil
+    end
+
+    context 'inverse' do
+      subject { described_class.new('users', '13', response) }
+
+      specify do
+        expect(subject['name']).to eq('Pelat')
+      end
+
+      specify do
+        expect(subject['friends']).to be_a Enumerable
+      end
+
+      specify do
+        expect(subject['friends'].any?).to eq(false)
+      end
+
+      specify do
+        expect(subject['enemy']).to be_a BrainstemAdaptor::Record
+      end
+
+      specify do
+        expect(subject['enemy']).to eq({'name' => 'Petr', 'friend_ids' => ['13'], 'enemy_id' => nil})
+      end
+    end
+  end
+
+  describe '#has_association?' do
+    specify do
+      expect(subject.has_association?('friends')).to eq(true)
+    end
+
+    specify do
+      expect(subject.has_association?('something invalid')).to eq(false)
+    end
+  end
+
+  describe '#association_by_name' do
+    context 'association exists' do
+      specify do
+        expect(subject.association_by_name('friends')).to be_a BrainstemAdaptor::Association
+      end
+    end
+
+    context 'association does not exist' do
+      specify do
+        expect(subject.association_by_name('something wrong')).to be_nil
+      end
+    end
+  end
+
+  context 'no specification set' do
+    specify do
+      expect { described_class.new('test', 1)['any key'] }.not_to raise_error
+    end
+  end
+end

data/spec/lib/brainstem_adaptor/response_spec.rb

@@ -0,0 +1,197 @@
+require 'spec_helper'
+
+describe BrainstemAdaptor::Response do
+  let(:plain_text_response) do
+    <<-JSON_RESPONSE
+    {
+      "count": 99,
+      "results": [{ "key": "workspaces", "id": "10" }, { "key": "workspaces", "id": "11" }],
+      "workspaces": {
+        "10": {
+          "id": "10",
+          "title": "some project",
+          "participant_ids": ["2", "6"],
+          "primary_counterpart_id": "6"
+        },
+        "11": {
+          "id": "11",
+          "title": "another project",
+          "participant_ids": ["2", "8"],
+          "primary_counterpart_id": "8"
+        }
+      },
+      "users": {
+        "2": { "id": "2", "full_name": "bob" },
+        "6": { "id": "6", "full_name": "chaz" },
+        "8": { "id": "8", "full_name": "jane" }
+      }
+    }
+    JSON_RESPONSE
+  end
+
+  let(:response_hash) { BrainstemAdaptor.parser.parse(plain_text_response) }
+
+  let(:specification) do
+    {
+      'workspaces' => {
+        'associations' => {
+          'participants' => {
+            'foreign_key' => 'participant_ids',
+            'collection' => 'users'
+          },
+          'primary_counterpart' => {
+            'foreign_key' => 'primary_counterpart_id',
+            'collection' => 'users'
+          }
+        }
+      },
+      'users' => nil
+    }
+  end
+
+  before do
+    BrainstemAdaptor.specification = specification
+  end
+
+  let(:response_data) { plain_text_response }
+
+  subject(:response) { described_class.new(response_data) }
+
+  describe 'collection' do
+    its(:count) { should == 99 }
+
+    specify do
+      expect(response.results).to have(2).records
+    end
+
+    describe 'records data' do
+      specify do
+        expect(response.results[0]).to be_a BrainstemAdaptor::Record
+      end
+
+      specify do
+        expect(response.results[1]).to be_a BrainstemAdaptor::Record
+      end
+
+      specify do
+        expect(response.results[0].collection_name).to eq('workspaces')
+      end
+
+      specify do
+        expect(response.results[1].collection_name).to eq('workspaces')
+      end
+
+      specify do
+        expect(response.results[0]).to eq(response_hash['workspaces']['10'])
+      end
+
+      specify do
+        expect(response.results[1]).to eq(response_hash['workspaces']['11'])
+      end
+    end
+  end
+
+  describe 'associations' do
+    specify do
+      expect(response['users']).to eq(response_hash['users'])
+    end
+
+    describe '"has many" relations' do
+      specify do
+        expect(response.results[0]['participants'][0]).to be_a BrainstemAdaptor::Record
+      end
+
+      specify do
+        expect(response.results[0]['participants'][1]).to be_a BrainstemAdaptor::Record
+      end
+
+      specify do
+        expect(response.results[1]['participants'][0]).to be_a BrainstemAdaptor::Record
+      end
+
+      specify do
+        expect(response.results[1]['participants'][1]).to be_a BrainstemAdaptor::Record
+      end
+
+      specify do
+        expect(response.results[0]['participants']).to eq([response_hash['users']['2'], response_hash['users']['6']])
+      end
+
+      specify do
+        expect(response.results[1]['participants']).to eq([response_hash['users']['2'], response_hash['users']['8']])
+      end
+    end
+
+    describe '"has one" relations' do
+      specify do
+        expect(response.results[0]['primary_counterpart']).to be_a BrainstemAdaptor::Record
+      end
+
+      specify do
+        expect(response.results[1]['primary_counterpart']).to be_a BrainstemAdaptor::Record
+      end
+    end
+  end
+
+  context 'invalid JSON format' do
+    let(:response_data) { 'test; invalid " json ' }
+
+    specify do
+      expect { subject }.to raise_error BrainstemAdaptor::InvalidResponseError
+    end
+  end
+
+  context 'parsed input' do
+    let(:response_data) { response_hash }
+
+    specify do
+      expect(subject.response_data).to eq(response_data)
+    end
+  end
+
+  context 'invalid input' do
+    let(:response_data) { nil }
+
+    specify do
+      expect { subject }.to raise_error ArgumentError, /Expected String/
+    end
+
+    context 'count is not returned' do
+      let(:response_data) { { 'results' => [] } }
+
+      specify do
+        expect { subject }.to raise_error BrainstemAdaptor::InvalidResponseError, /count/
+      end
+    end
+
+    context 'results collection is not returned' do
+      let(:response_data) { { 'count' => 0 } }
+
+      specify do
+        expect { subject }.to raise_error BrainstemAdaptor::InvalidResponseError, /results.*returned/
+      end
+    end
+
+    context 'results collection is not an array' do
+      let(:response_data) { { 'count' => 0, 'results' => {} } }
+
+      specify do
+        expect { subject }.to raise_error BrainstemAdaptor::InvalidResponseError, /results.*array/
+      end
+    end
+  end
+
+  describe '#to_hash' do
+    specify do
+      expect(subject.to_hash).to eq(response_hash)
+    end
+  end
+
+  describe '#==' do
+    let(:response_data) { { 'count' => 1, 'results' => [{'key' => 'user', 'value' => 2}] } }
+
+    specify do
+      expect(subject).to eq(response_data)
+    end
+  end
+end

data/spec/lib/brainstem_adaptor/specification_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+describe BrainstemAdaptor::Specification do
+  describe '.[]' do
+    before do
+      described_class[:test] = {stored: true}
+      described_class[:another_test] = {something_else: false}
+    end
+
+    it 'stores multiple specifications' do
+      expect(described_class[:test]).to eq({stored: true})
+      expect(described_class[:another_test]).to eq({something_else: false})
+    end
+  end
+end

data/spec/lib/brainstem_adaptor_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+
+describe BrainstemAdaptor do
+  describe '.parser=' do
+    let(:parser) { double('real parser', parse: true) }
+
+    specify do
+      expect { described_class.parser = parser }.to change(described_class, :parser).to(parser)
+    end
+
+    specify do
+      expect { described_class.parser = double('something wrong') }.to raise_error ArgumentError
+    end
+  end
+
+  describe '.parser' do
+    it 'users JSON parser by default' do
+      expect { described_class.parser }.not_to raise_error
+    end
+  end
+
+  describe '.default_specification' do
+    specify do
+      expect { described_class.default_specification }.not_to raise_error
+    end
+  end
+
+  describe '.specification=' do
+    let(:specification) { {users: {}} }
+
+    specify do
+      expect { described_class.specification = specification }.to change(described_class, :default_specification).to(specification)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'brainstem-adaptor'
+
+RSpec.configure do |config|
+  config.mock_with :rspec
+  config.color_enabled = true
+  config.formatter = :documentation
+end
+

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: brainstem-adaptor
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- Sergei Zinin (einzige)
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+description: Parses Brainstem responses, makes it convenient to organize access to
+  your data.
+email: szinin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- README.md
+- Rakefile
+- brainstem-adaptor.gemspec
+- lib/brainstem-adaptor.rb
+- lib/brainstem_adaptor/association.rb
+- lib/brainstem_adaptor/invalid_response_error.rb
+- lib/brainstem_adaptor/record.rb
+- lib/brainstem_adaptor/response.rb
+- lib/brainstem_adaptor/specification.rb
+- spec/lib/brainstem_adaptor/association_spec.rb
+- spec/lib/brainstem_adaptor/invalid_response_error_spec.rb
+- spec/lib/brainstem_adaptor/record_spec.rb
+- spec/lib/brainstem_adaptor/response_spec.rb
+- spec/lib/brainstem_adaptor/specification_spec.rb
+- spec/lib/brainstem_adaptor_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/einzige/brainstem-adaptor
+licenses:
+- MIT
+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.1.5
+signing_key: 
+specification_version: 4
+summary: Brainstem API Adaptor
+test_files: []