Serialization (#75): add PropertyContainer::toJSON().

Along with a GraphDatabase helper to get the JSON foundation.

lib/GraphDatabase._coffee

@@ -4,6 +4,8 @@
 # this can be done in Streamline syntax by adding one line before cases where
 # we're returning immediately: process.nextTick _
 
+PACKAGE = require '../package'
+
 status = require 'http-status'
 
 util = require './util'
@@ -602,6 +604,25 @@ module.exports = class GraphDatabase
         catch error
             throw adjustError error
 
+    ## Serialization: ##
+
+    #
+    # Helper for other classes to serialize their data in a format that this
+    # GraphDatabase class will understand for *de*-serialization.
+    #
+    # @private
+    #
+    _toJSON: (obj) ->
+        # save this lib's basic info both for identification purposes and in
+        # case we ever need it in the future (e.g. for breaking changes):
+        package:
+            name: PACKAGE.name
+            version: PACKAGE.version
+        # save the object's constructor name, so we can deserialize it:
+        constructor: obj.constructor.name
+        # important: we don't save this db's URL, because it might contain a
+        # basic auth password!
+
     ### Misc/Other: ###
 
     #

lib/PropertyContainer._coffee

@@ -115,3 +115,17 @@ module.exports = class PropertyContainer
     #
     del: ->
         @delete.apply @, arguments
+
+    #
+    # Return a JSON representation of this property container, suitable for
+    # serialization (e.g. caching).
+    #
+    toJSON: ->
+        # take the basic info for this db, then just add the data object
+        # directly since we need that for deserialization/construction.
+        # TODO it'd be great if we could store a trimmed down version of
+        # the data object instead of e.g. all the hypermedia URLs...
+        # but we need those hypermedia URLs for making requests for now.
+        json = @db._toJSON @
+        json._data = @_data
+        json