v2 / Core: impl. and test parsing of nodes & rels!

Author: aseemk

lib-new/GraphDatabase.coffee

@@ -1,6 +1,8 @@
 $ = require 'underscore'
 errors = require './errors'
 lib = require '../package.json'
+Node = require './Node'
+Relationship = require './Relationship'
 Request = require 'request'
 URL = require 'url'
 
@@ -36,7 +38,6 @@ module.exports = class GraphDatabase
         method or= 'get'
         headers or= {}
 
-        # TODO: Parse response body before calling back.
         # TODO: Do we need to do anything special to support streaming response?
         req = Request[method.toLowerCase()]
             url: URL.resolve @url, path
@@ -66,5 +67,39 @@ module.exports = class GraphDatabase
                     http: {body, headers, statusCode}
                 return cb err
 
-            # TODO: Parse nodes and relationships.
-            return cb null, body
+            # Parse nodes and relationships in the body, and return:
+            return cb null, _transform body
+
+
+## HELPERS
+
+#
+# Deep inspects the given object -- which could be a simple primitive, a map,
+# an array with arbitrary other objects, etc. -- and transforms any objects that
+# look like nodes and relationships into Node and Relationship instances.
+# Returns the transformed object, and does not mutate the input object.
+#
+_transform = (obj) ->
+    # Nothing to transform for primitives and null:
+    if (not obj) or (typeof obj isnt 'object')
+        return obj
+
+    # Process arrays:
+    # (NOTE: Not bothering to detect arrays made in other JS contexts.)
+    if obj instanceof Array
+        return obj.map _transform
+
+    # Feature-detect (AKA "duck-type") Node & Relationship objects, by simply
+    # trying to parse them as such.
+    # Important: check relationships first, for precision/specificity.
+    # TODO: If we add a Path class, we'll need to check for that here too.
+    if rel = Relationship._fromRaw obj
+        return rel
+    if node = Node._fromRaw obj
+        return node
+
+    # Otherwise, process as a dictionary/map:
+    map = {}
+    for key, val of obj
+        map[key] = _transform val
+    map

lib-new/Node.coffee

@@ -0,0 +1,51 @@
+utils = require './utils'
+
+module.exports = class Node
+
+    constructor: (opts={}) ->
+        {@_id, @labels, @properties} = opts
+
+    equals: (other) ->
+        # TODO: Is this good enough? Often don't want exact equality, e.g.
+        # nodes' properties may change between queries.
+        (other instanceof Node) and (@_id is other._id)
+
+    toString: ->
+        labels = @labels.map (label) -> ":#{label}"
+        "(#{@_id}#{labels.join ''})"    # E.g. (123), (456:Foo), (789:Foo:Bar)
+
+    #
+    # Accepts the given raw JSON from Neo4j's REST API, and if it represents a
+    # valid node, creates and returns a Node instance from it.
+    # If the JSON doesn't represent a valid node, returns null.
+    #
+    @_fromRaw: (obj) ->
+        return null if (not obj) or (typeof obj isnt 'object')
+
+        {data, metadata, self} = obj
+
+        return null if (not self) or (typeof self isnt 'string') or
+            (not data) or (typeof data isnt 'object')
+
+        # Metadata was only added in Neo4j 2.1.5, so don't *require* it,
+        # but (a) it makes our job easier, and (b) it's the only way we can get
+        # labels, so warn the developer if it's missing, but only once.
+        if metadata
+            {id, labels} = metadata
+        else
+            id = utils.parseId self
+            labels = null
+
+            if not @_warnedMetadata
+                @_warnedMetadata = true
+                console.warn 'It looks like you’re running Neo4j <2.1.5.
+                    Neo4j <2.1.5 didn’t return label metadata to drivers,
+                    so node-neo4j has no way to associate nodes with labels.
+                    Thus, the `labels` property on neo4j `Node`s will always be
+                    null for you. Consider upgrading to fix. =)
+                    http://neo4j.com/release-notes/neo4j-2-1-5/'
+
+        return new Node
+            _id: id
+            labels: labels
+            properties: data

lib-new/Relationship.coffee

@@ -0,0 +1,44 @@
+utils = require './utils'
+
+module.exports = class Relationship
+
+    constructor: (opts={}) ->
+        {@_id, @type, @properties, @_fromId, @_toId} = opts
+
+    equals: (other) ->
+        # TODO: Is this good enough? Often don't want exact equality, e.g.
+        # nodes' properties may change between queries.
+        (other instanceof Relationship) and (@_id is other._id)
+
+    toString: ->
+        "-[#{@_id}:#{@type}]-"  # E.g. -[123:FOLLOWS]-
+
+    #
+    # Accepts the given raw JSON from Neo4j's REST API, and if it represents a
+    # valid relationship, creates and returns a Relationship instance from it.
+    # If the JSON doesn't represent a valid relationship, returns null.
+    #
+    @_fromRaw: (obj) ->
+        return null if (not obj) or (typeof obj isnt 'object')
+
+        {data, self, type, start, end} = obj
+
+        return null if (not self) or (typeof self isnt 'string') or
+            (not type) or (typeof type isnt 'string') or
+            (not start) or (typeof start isnt 'string') or
+            (not end) or (typeof end isnt 'string') or
+            (not data) or (typeof data isnt 'object')
+
+        # Relationships also have `metadata`, added in Neo4j 2.1.5, but it
+        # doesn't provide anything new. (And it doesn't give us from/to ID.)
+        # We don't want to rely on it, so we don't bother using it at all.
+        id = utils.parseId self
+        fromId = utils.parseId start
+        toId = utils.parseId end
+
+        return new Relationship
+            _id: id
+            type: type
+            properties: data
+            _fromId: fromId
+            _toId: toId

lib-new/index.coffee

@@ -2,5 +2,7 @@ $ = require 'underscore'
 
 $(exports).extend
     GraphDatabase: require './GraphDatabase'
+    Node: require './Node'
+    Relationship: require './Relationship'
 
 $(exports).extend require './errors'

lib-new/utils.coffee

@@ -0,0 +1,9 @@
+
+#
+# Parses and returns the native Neo4j ID out of the given Neo4j URL,
+# or null if no ID could be matched.
+#
+@parseId = (url) ->
+    match = url.match /// /db/data/(node|relationship)/(\d+)$ ///
+    return null if not match
+    return parseInt match[2], 10

test-new/fixtures/index._coffee

@@ -0,0 +1,13 @@
+#
+# NOTE: This file is within a directory named `fixtures`, rather than a file
+# named `fixtures._coffee`, in order to not have Mocha treat it like a test.
+#
+
+neo4j = require '../../'
+
+exports.DB =
+    new neo4j.GraphDatabase process.env.NEO4J_URL or 'http://localhost:7474'
+
+exports.TEST_LABEL = 'Test'
+
+exports.TEST_REL_TYPE = 'TEST'

test-new/http._coffee

@@ -1,11 +1,27 @@
 {expect} = require 'chai'
+fixtures = require './fixtures'
 http = require 'http'
 neo4j = require '../'
 
 
 ## SHARED STATE
 
-DB = new neo4j.GraphDatabase process.env.NEO4J_URL or 'http://localhost:7474'
+{DB, TEST_LABEL, TEST_REL_TYPE} = fixtures
+
+TEST_NODE_A = new neo4j.Node
+    # _id will get filled in once we persist
+    labels: [TEST_LABEL]
+    properties: {suite: module.filename, name: 'a'}
+
+TEST_NODE_B = new neo4j.Node
+    # _id will get filled in once we persist
+    labels: [TEST_LABEL]
+    properties: {suite: module.filename, name: 'b'}
+
+TEST_REL = new neo4j.Relationship
+    # _id, _fromId (node A), _toId (node B) will get filled in once we persist
+    type: TEST_REL_TYPE
+    properties: {suite: module.filename, name: 'r'}
 
 
 ## HELPERS
@@ -106,3 +122,120 @@ describe 'GraphDatabase::http', ->
         # Test that it immediately returns a duplex HTTP stream.
         # Test writing request data to this stream.
         # Test reading response data from this stream.
+
+
+    ## Object parsing:
+
+    it '(create test objects)', (_) ->
+        # NOTE: Using the old Cypher endpoint for simplicity here.
+        # Nicer than using the raw REST API to create these test objects,
+        # but also nice to neither use this driver's Cypher functionality
+        # (which is tested in a higher-level test suite), nor re-implement it.
+        # http://neo4j.com/docs/stable/rest-api-cypher.html#rest-api-use-parameters
+        {data} = DB.http
+            method: 'POST'
+            path: '/db/data/cypher'
+            body:
+                query: """
+                    CREATE (a:#{TEST_LABEL} {propsA})
+                    CREATE (b:#{TEST_LABEL} {propsB})
+                    CREATE (a) -[r:#{TEST_REL_TYPE} {propsR}]-> (b)
+                    RETURN ID(a), ID(b), ID(r)
+                """
+                params:
+                    propsA: TEST_NODE_A.properties
+                    propsB: TEST_NODE_B.properties
+                    propsR: TEST_REL.properties
+        , _
+
+        [row] = data
+        [idA, idB, idR] = row
+
+        TEST_NODE_A._id = idA
+        TEST_NODE_B._id = idB
+        TEST_REL._id = idR
+        TEST_REL._fromId = idA
+        TEST_REL._toId = idB
+
+    it 'should parse nodes by default', (_) ->
+        node = DB.http
+            method: 'GET'
+            path: "/db/data/node/#{TEST_NODE_A._id}"
+        , _
+
+        expect(node).to.be.an.instanceOf neo4j.Node
+        expect(node).to.eql TEST_NODE_A
+
+    it 'should parse relationships by default', (_) ->
+        rel = DB.http
+            method: 'GET'
+            path: "/db/data/relationship/#{TEST_REL._id}"
+        , _
+
+        expect(rel).to.be.an.instanceOf neo4j.Relationship
+        expect(rel).to.eql TEST_REL
+
+    it 'should parse nested nodes & relationships by default', (_) ->
+        {data} = DB.http
+            method: 'POST'
+            path: '/db/data/cypher'
+            body:
+                query: """
+                    START a = node({idA})
+                    MATCH (a) -[r:#{TEST_REL_TYPE}]-> (b)
+                    RETURN a, r, b
+                """
+                params:
+                    idA: TEST_NODE_A._id
+        , _
+
+        [row] = data
+        [nodeA, rel, nodeB] = row
+
+        expect(nodeA).to.be.an.instanceOf neo4j.Node
+        expect(nodeA).to.eql TEST_NODE_A
+        expect(nodeB).to.be.an.instanceOf neo4j.Node
+        expect(nodeB).to.eql TEST_NODE_B
+        expect(rel).to.be.an.instanceOf neo4j.Relationship
+        expect(rel).to.eql TEST_REL
+
+    it 'should not parse nodes for raw responses', (_) ->
+        {body} = DB.http
+            method: 'GET'
+            path: "/db/data/node/#{TEST_NODE_A._id}"
+            raw: true
+        , _
+
+        expect(body).to.not.be.an.instanceOf neo4j.Node
+        expect(body.metadata).to.be.an 'object'
+        expect(body.metadata.id).to.equal TEST_NODE_A._id
+        expect(body.metadata.labels).to.eql TEST_NODE_A.labels
+        expect(body.data).to.eql TEST_NODE_A.properties
+
+    it 'should not parse relationships for raw responses', (_) ->
+        {body} = DB.http
+            method: 'GET'
+            path: "/db/data/relationship/#{TEST_REL._id}"
+            raw: true
+        , _
+
+        expect(body.metadata).to.be.an 'object'
+        expect(body.metadata.id).to.equal TEST_REL._id
+        expect(body).to.not.be.an.instanceOf neo4j.Relationship
+        expect(body.type).to.equal TEST_REL.type
+        expect(body.data).to.eql TEST_REL.properties
+
+    it '(delete test objects)', (_) ->
+        DB.http
+            method: 'POST'
+            path: '/db/data/cypher'
+            body:
+                query: """
+                    START a = node({idA}), b = node({idB}), r = rel({idR})
+                    DELETE a, b, r
+                """
+                params:
+                    idA: TEST_NODE_A._id
+                    idB: TEST_NODE_B._id
+                    idR: TEST_REL._id
+        , _