Add: has_one(chainable: true) option

docs/ActiveNode.rst

@@ -387,6 +387,13 @@ You can query associations:
     comment.post.comments       # Original comment and all of it's siblings.  Makes just one query
     post.comments.authors.posts # All posts of people who have commented on the post.  Still makes just one query
 
+When querying ``has_one`` associations, by default ``.first`` will be called on the result. This makes the result non-chainable if the result is ``nil``. If you want to ensure a chainable result, you can call ``has_one`` with a ``chainable: true`` argument.
+
+.. code-block:: ruby
+
+    comment.post                    # Post object
+    comment.post(chainable: true)   # Association proxy object wrapping post
+
 You can create associations
 
 .. code-block:: ruby
@@ -428,9 +435,9 @@ The two orphan-destruction options are unique to Neo4j.rb. As an example of when
 
 
 .. seealso::
-  :ref:`#has_many <Neo4j/ActiveNode/HasN/ClassMethods#has_many>`
+  #has_many http://www.rubydoc.info/gems/neo4j/Neo4j/ActiveNode/HasN/ClassMethods#has_many-instance_method
   and
-  :ref:`#has_one <Neo4j/ActiveNode/HasN/ClassMethods#has_one>`
+  #has_one http://www.rubydoc.info/gems/neo4j/Neo4j/ActiveNode/HasN/ClassMethods#has_one-instance_method
 
 
 Creating Unique Relationships

lib/neo4j/active_node/has_n.rb

@@ -463,13 +463,14 @@ def define_has_one_id_methods(name)
         end
       end
 
-      def define_has_one_getter(name)
+      def define_has_one_getter(name) # rubocop:disable Metrics/PerceivedComplexity
         define_method(name) do |node = nil, rel = nil, options = {}|
           options, node = node, nil if node.is_a?(Hash)
 
-          # Return all results if a variable-length relationship length was given
           association_proxy = association_proxy(name, {node: node, rel: rel}.merge!(options))
-          if options[:rel_length] && !options[:rel_length].is_a?(Integer)
+
+          # Return all results if options[:chainable] == true or a variable-length relationship length was given
+          if options[:chainable] || (options[:rel_length] && !options[:rel_length].is_a?(Integer))
             association_proxy
           else
             target_class = self.class.send(:association_target_class, name)

spec/e2e/has_one_spec.rb

@@ -24,6 +24,12 @@
       it 'returns a nil object' do
         expect(unsaved_node.parent).to eq nil
       end
+
+      describe 'with chainable: true option' do
+        it 'returns an empty association proxy object' do
+          expect(unsaved_node.parent(chainable: true).inspect).to eq '#<AssociationProxy HasOneB#parent []>'
+        end
+      end
     end
 
     it 'find the nodes via the has_one accessor' do
@@ -38,6 +44,22 @@
       expect(a.children.to_a).to match_array([b, c])
     end
 
+    describe 'with chainable: true option' do
+      it 'find the nodes via the has_one accessor' do
+        a = HasOneA.create(name: 'a')
+        b = HasOneB.create(name: 'b')
+        c = HasOneB.create(name: 'c')
+        a.children << b
+        a.children << c
+
+        expect(c.parent(chainable: true).inspect).to include('#<AssociationProxy HasOneB#parent')
+        expect(c.parent(chainable: true).first).to eq(a)
+        expect(b.parent(chainable: true).inspect).to include('#<AssociationProxy HasOneB#parent')
+        expect(b.parent(chainable: true).first).to eq(a)
+        expect(a.children.to_a).to match_array([b, c])
+      end
+    end
+
     it 'caches the result of has_one accessor' do
       a = HasOneA.create(name: 'a')
       b = HasOneB.create(name: 'b')