subjoin 0.2.1

data/lib/subjoin/linkable.rb

@@ -0,0 +1,18 @@
+module Subjoin
+  # Generically construct and handle {Links} objects
+  module Linkable
+    attr_reader :links
+    
+    # Load the object's links
+    # @param data [Hash] The object's parsed JSON `links` member
+    # @return [Hash]
+    def load_links(data)
+      return nil if data.nil?
+      Hash[data.map{|k, v| [k, Link.new(v)]}]
+    end
+
+    def has_links?
+      return ! @links.nil?
+    end
+  end
+end

data/lib/subjoin/meta.rb

@@ -0,0 +1,10 @@
+module Subjoin
+  # Meta object
+  # @see http://jsonapi.org/format/#document-meta
+  class Meta
+    include Attributable
+    def initialize(data)
+      load_attributes(data)
+    end
+  end
+end

data/lib/subjoin/metable.rb

@@ -0,0 +1,21 @@
+module Subjoin
+  # Generically handle meta objects
+  module Metable
+
+    # The object's meta attribute
+    # @return [Meta]
+    attr_reader :meta
+
+    # Load the object's attributes
+    # @param data [Hash] The object's parsed JSON `meta` member
+    # @return [Metable,nil]
+    def load_meta(data)
+      return nil if data.nil?
+      Meta.new(data)
+    end
+
+    def has_meta?
+      return ! @meta.nil?
+    end
+  end
+end

data/lib/subjoin/relationship.rb

@@ -0,0 +1,32 @@
+module Subjoin
+  # A related resource link, providing access to resource objects
+  # linked in a relationship
+  # @see http://jsonapi.org/format/#document-resource-object-related-resource-links
+  class Relationship
+    include Linkable
+    include Metable
+
+    attr_reader :links, :linkages
+    def initialize(data, doc)
+      @document = doc
+      @links = load_links(data['links'])
+      @linkages = load_linkages(data['data'], doc)
+      @meta = load_meta(data['meta'])
+    end
+
+    # Resolve available linkages and return related resources
+    # @return [Array<Subjoin::Resource>]
+    def lookup
+      return [] unless @document.has_included?
+      @linkages.map{|l| @document.included[l]}
+    end
+
+    private
+    def load_linkages(data, doc)
+      return [] if data.nil?
+      return [Identifier.new(data['type'], data['id'], data['meta'])] if data.is_a? Hash
+      data.map{|l| Identifier.new(l['type'], l['id'], l['meta'])}
+    end
+
+  end
+end

data/lib/subjoin/resource.rb

@@ -0,0 +1,93 @@
+module Subjoin
+  # A JSON-API Resource object
+  # @see http://jsonapi.org/format/#document-resource-objects
+  class Resource
+    include Attributable
+    #include Keyable
+    include Linkable
+    include Metable
+
+    # The relationships specified for the object
+    # @return [Hash<Relationship>]
+    attr_reader :relationships
+
+    attr_reader :identifier
+    
+    def initialize(spec, doc = nil)
+      @document = doc
+      if spec.is_a?(URI)
+        data = Subjoin::get(spec)
+      elsif spec.is_a?(Hash)
+        data = spec
+      end
+
+      if data.has_key?("data")
+        data = data["data"]
+      end
+
+      if data.is_a?(Array)
+        raise UnexpectedTypeError.new
+      end
+
+      @identifier = Identifier.new(data['type'], data['id'])
+      
+      load_attributes(data['attributes'])
+      @links = load_links(data['links'])
+      @relationships = load_relationships(data['relationships'], @document)
+      @meta = load_meta(data['meta'])
+    end
+
+    # Resource type
+    # @return [String]
+    def type
+      @identifier.type
+    end
+
+    # Resource id
+    # @return [String]
+    def id
+      @identifier.id
+    end
+
+    # Get a related resource or resources. This method resolves the
+    # relationship linkages and fetches the included {Subjoin::Resource}
+    # objects themselves.
+    # @param spec [String] key for the desired resource
+    # @param doc [Subjoin::Document] Document in which to look for related
+    #   resources. By default it is the same document from which the resource
+    #   came itself.
+    # @return [Hash, Array<Subjoin:Resource>, nil] If called with a spec
+    # parameter, the return value will be an Array of {Subjoin::Resource}
+    # objects corresponding to the key, or nil if that key doesn't exist. If
+    # called without a spec parameter, the return value will be a Hash whose
+    # keys are the same as {Resource#relationships}, but whose values are
+    # Arrays of resolved {Resource} objects. In practice this means that you
+    # have a choice of idioms (method vs. hash) since
+    #
+    #    obj.rels("key")
+    #
+    # and
+    #
+    #    obj.rels["key"]
+    #
+    # are equivalent
+    def rels(spec = nil, doc = @document)
+      return nil if doc.nil?
+      return nil unless doc.has_included?
+
+      if spec.nil?
+        return Hash[relationships.keys.map{|k| [k, rels(k, doc)]}]
+      end
+      
+      relationships[spec].linkages.map{|l| doc.included[l]}
+    end
+    
+    private
+    def load_relationships(data, doc)
+      return {} if data.nil?
+
+      Hash[data.map{|k, v| [k, Relationship.new(v, doc)]}]
+    end
+  end
+end
+

data/lib/subjoin/version.rb

@@ -0,0 +1,4 @@
+module Subjoin
+  # Gem version
+  VERSION = "0.2.1"
+end

data/spec/document_spec.rb

@@ -0,0 +1,210 @@
+require "spec_helper"
+
+describe Subjoin::Document do
+  before :all do
+    rsp = JSON.parse(COMPOUND)
+    @doc = Subjoin::Document.new(rsp)
+
+    dataless = JSON.parse(COMPOUND)
+    dataless.delete("data")
+    @nodata = Subjoin::Document.new(dataless)
+
+    excluded = JSON.parse(COMPOUND)
+    excluded.delete("included")
+    @noincl = Subjoin::Document.new(excluded)
+
+    linkless = JSON.parse(COMPOUND)
+    linkless.delete("links")
+    @nolinks = Subjoin::Document.new(linkless)
+
+    metaless = JSON.parse(COMPOUND)
+    metaless.delete("meta")
+    @nometa = Subjoin::Document.new(metaless)
+
+    versionless = JSON.parse(COMPOUND)
+    versionless.delete("jsonapi")
+    @noversion = Subjoin::Document.new(versionless)
+
+    @simple = Subjoin::Document.new(JSON.parse(ARTICLE))
+  end
+
+  describe "#data" do
+    context "when there is primary data" do
+      it "is an Array" do
+        expect(@doc.data).to be_an_instance_of Array
+      end
+
+      it "contains an expected Resource" do
+        expect(@doc.data.first["title"]).to eq "JSON API paints my bikeshed!"
+      end
+    end
+
+    context "when there is no primary data" do
+      it "is nil" do
+        expect(@nodata.data).to be_nil
+      end
+    end
+
+    context "when there is a single object in primary data" do
+      it "is still an Array" do
+        expect(@simple.data).to be_an_instance_of Array
+      end
+
+      it "has one element" do
+        expect(@simple.data.count).to eq 1
+      end
+    end
+  end
+
+  describe "#has_data?" do
+    context "when there is primary data" do
+      it "returns true" do
+        expect(@doc.has_data?).to be true
+      end
+    end
+
+    context "when there is no primary data" do
+      it "returns false" do
+        expect(@nodata.has_data?).to be false
+      end
+    end
+  end
+
+
+  describe "#included" do
+    context "when there are included resources" do
+      it "is an Array" do
+        expect(@doc.included).to be_an_instance_of Subjoin::Inclusions
+      end
+
+      it "contains an expected Resource" do
+        expect(@doc.included[0].type).to eq "people"
+      end
+    end
+
+    context "when there are no included resources" do
+      it "is nil" do
+        expect(@noincl.included).to be_nil
+      end
+    end
+  end
+
+  describe "#has_included?" do
+    context "when there are included resources" do
+      it "returns true" do
+        expect(@doc.has_included?).to be true
+      end
+    end
+
+    context "when there are no included resources" do
+      it "returns false" do
+        expect(@noincl.has_included?).to be false
+      end
+    end
+  end
+
+  describe "#links" do
+    context "when there are links" do
+      it "is a Hash of Link objects" do
+        expect(@doc.links.map{|k, v| v.class}.uniq).to eq [Subjoin::Link]
+      end
+
+      it "has an expected link" do
+        expect(@doc.links["related"].to_s).to eq "http://jsonapi.org"
+      end
+    end
+
+    context "when there are no links" do
+      it "is nil" do
+        expect(@nolinks.links).to be_nil
+      end
+    end
+  end
+  
+  describe "#has_links?" do
+    context "when there are links" do
+      it "returns true" do
+        expect(@doc.has_links?).to be true
+      end
+    end
+
+    context "when there no links" do
+      it "returns false" do
+        expect(@nolinks.has_links?).to be false
+      end
+    end
+  end
+
+  describe "#meta" do
+    context "when there is meta information" do
+      it "is a Meta object" do
+        expect(@doc.meta).to be_an_instance_of(Subjoin::Meta)
+      end
+
+      it "has an expected attribute" do
+        expect(@doc.meta["category"]).to eq "Example response"
+      end
+    end
+
+    context "when there is no meta information" do
+      it "is nil" do
+        expect(@nometa.meta).to be nil
+      end
+    end
+  end
+
+  describe "#has_meta?" do
+    context "when there is meta information" do
+      it "returns true" do
+        expect(@doc.has_meta?).to be true
+      end
+    end
+
+    context "when there is no meta information" do
+      it "returns false" do
+        expect(@nometa.has_meta?).to be false
+      end
+    end
+  end
+
+  describe "#jsonapi" do
+    context "when there is version information" do
+      it "is a JsonApi object" do
+        expect(@doc.jsonapi).to be_an_instance_of(Subjoin::JsonApi)
+      end
+
+      it "has an expected attribute" do
+        expect(@doc.jsonapi.version).to eq "1.0"
+      end
+    end
+
+    context "when there is no version information" do
+      it "is nil" do
+        expect(@noversion.jsonapi).to be nil
+      end
+    end
+  end
+
+  describe "#has_jsonapi?" do
+    context "when there is version information" do
+      it "returns true" do
+        expect(@doc.has_jsonapi?).to be true
+      end
+    end
+
+    context "when there is no version information" do
+      it "returns false" do
+        expect(@noversion.has_jsonapi?).to be false
+      end
+    end
+  end
+
+  context "instantiated with a URI" do
+    it "succeeds" do
+      allow_any_instance_of(Faraday::Connection).
+        to receive(:get).and_return(double(Faraday::Response, :body => ARTICLE))
+      expect(Subjoin::Document.new(URI("http://example.com/articles"))).
+        to be_an_instance_of(Subjoin::Document)
+    end
+  end
+end

data/spec/identifier_spec.rb

@@ -0,0 +1,33 @@
+require "spec_helper"
+
+describe Subjoin::Identifier do
+  before :each do
+    data = JSON.parse(ARTICLE)['data']['relationships']['author']
+    @id = Subjoin::Identifier.
+          new(data['data']['type'], data['data']['id'], data['meta'])
+  end
+
+  it "has a type" do
+    expect(@id.type).to eq "people"
+  end
+
+  it "has an id" do
+    expect(@id.id).to eq "9"
+  end
+
+  it "has a Meta object" do
+    expect(@id.meta).to be_an_instance_of Subjoin::Meta
+  end
+
+  describe "equality" do
+    it "is equal if #type and #id are the same" do
+      other = Subjoin::Identifier.new("people", "9")
+      expect(@id == other).to be true
+    end
+
+    it "is other not equal" do
+      other = Subjoin::Identifier.new("schmeople", "9")
+      expect(@id == other).to be false
+    end
+  end
+end

data/spec/inclusions_spec.rb

@@ -0,0 +1,69 @@
+require "spec_helper"
+
+describe Subjoin::Inclusions do
+  before :all do
+    @doc = Subjoin::Document.new(JSON.parse(COMPOUND))
+  end
+
+  describe "#all" do
+    it "returns an Array" do
+      expect(@doc.included.all).to be_an_instance_of Array
+    end
+  end
+
+  describe "#first" do
+    it "returns a Resource" do
+      expect(@doc.included.first).to be_an_instance_of Subjoin::Resource
+    end
+  end
+
+  describe "#[]" do
+    context "when passed an Identifier" do
+      context "when the Identifier matches something included" do
+        it "returns a Resource" do
+          id = Subjoin::Identifier.new("people", "9")
+          expect(@doc.included[id]).to be_an_instance_of Subjoin::Resource
+        end
+
+        it "returns to expected Resource" do
+          id = Subjoin::Identifier.new("people", "9")
+          expect(@doc.included[id]['twitter']).to eq "dgeb"
+        end
+      end
+    end
+
+    context "when passed an Array" do
+      context "when the Identifier matches something included" do
+        it "returns a Resource" do
+          expect(@doc.included[["people", "9"]]).
+            to be_an_instance_of Subjoin::Resource
+        end
+
+        it "returns to expected Resource" do
+          expect(@doc.included[["people", "9"]]['twitter']).to eq "dgeb"
+        end
+      end
+    end
+
+    context "when passed a Fixnum" do
+      context "when the Identifier matches something included" do
+        it "returns a Resource" do
+          expect(@doc.included[0]).
+            to be_an_instance_of Subjoin::Resource
+        end
+
+        it "returns to expected Resource" do
+          expect(@doc.included[["people", "9"]]['twitter']).to eq "dgeb"
+        end
+      end
+    end
+      
+    context "when nothing matched" do
+      it "returns nil" do
+        expect(@doc.included[9]).
+          to be_nil
+      end
+    end
+  end
+end
+