README.md

This is a demo of (some of the features of) the Node.js library lightsaber.

Simply run:

npm install lightsaber
./generate_docs.coffee > generated_docs.md

To rebuild generated_docs.md from the coffeescript source.

generate_docs.coffee

#!/usr/bin/env coffee

{
  canonical_json
  indent
  log
  p
  pretty
  quote
  sane
  say
  sha384
} = require 'lightsaber'

say """
  # Nodesphere

  ## Saving a Graph
  
  ### HTTP PUT request

  For example, suppose you perform an HTTP `PUT`, with a json payload of nodes and edges:

  """

sphere =
  nodes: {}
  edges: {}

subject   = 'John Perry Barlow'
predicate = 'published'
object    = 'A Declaration of Independence of Cyberspace'

sphere.nodes[sha384 subject]   = subject
sphere.nodes[sha384 predicate] = predicate
sphere.nodes[sha384 object]    = object

edge = {
  subject:   sha384 subject
  predicate: sha384 predicate
  object:    sha384 object
}

sphere.edges[sha384 canonical_json edge] = edge

log indent sane pretty sphere

say """

The ID of each node can be any unique string.  In this case we use the hash of the node's sorted minified JSON.  For example:
    
"""

log indent sane sha384 subject

say """

is the hash of 
    
"""

log indent quote subject

say """

And:
    
"""

log indent sane sha384 canonical_json edge

say """

is the hash of 
    
"""

log indent quote sane canonical_json edge

say """

Note that the JSON is minified and sorted by keys.
    
"""

#####

sphere_packed =
  nodes: 
    [
      sha384 subject
      sha384 predicate
      sha384 object
    ]
  edges: 
    [
      sha384 canonical_json edge
    ]

say """

### HTTP PUT response

The expected response to the `PUT` request is one or more keys:

"""

sphere_hash = sha384 canonical_json sphere_packed
log indent sane pretty sha384: sphere_hash

say """

Where `#{sane sphere_hash}` is the hash of the JSON of the entire "packed" sphere:

"""

log indent quote sane canonical_json sphere_packed

say """

Note that the array values are sorted, as well as the object keys.
    
"""

generated_docs.md

Nodesphere

Saving a Graph

HTTP PUT request

For example, suppose you perform an HTTP PUT, with a json payload of nodes and edges:

{
    "nodes": {
        "e9381b02": "John Perry Barlow",
        "85c3ef1e": "published",
        "b8925d6f": "A Declaration of Independence of Cyberspace"
    },
    "edges": {
        "dbfaa3ef": {
            "subject": "e9381b02",
            "predicate": "85c3ef1e",
            "object": "b8925d6f"
        }
    }
}

The ID of each node can be any unique string. In this case we use the hash of the node's sorted minified JSON. For example:

e9381b02

is the hash of

'John Perry Barlow'

And:

dbfaa3ef

is the hash of

'{"object":"b8925d6f","predicate":"85c3ef1e","subject":"e9381b02"}'

Note that the JSON is minified and sorted by keys.

HTTP PUT response

The expected response to the PUT request is one or more keys:

{
    "sha384": "490c56e9"
}

Where 490c56e9 is the hash of the JSON of the entire "packed" sphere:

'{"edges":["dbfaa3ef"],"nodes":["85c3ef1e","b8925d6f","e9381b02"]}'

Note that the array values are sorted, as well as the object keys.