sloth.js

sloth.coffee

#     sloth 0.1(alpha)
#     Version for Node.js.
#     (c) 2010 John Wright, QuickLeft Inc.
#     sloth may be freely distributed under the MIT license.
#     For all details and documentation:
#     http://github.com/mrjjwright/sloth
#

#
# Sloth is a content based JSON store.  It tracks changes in the content of JSON objects, not ids, uuids or timestamps.
# Sloth objects are organized in collections (by default named `master`), 
# that are simply a group of objects with a name that live at a url.
# You add JSON objects to  a sloth working collection, then commit the collection to sloth's object store by calling sloth.commit
# with the name of the collection and an optional message. 
# You can remove objects from sloth by calling remove, and reset sloth working collections to old commits.
# You can push and pull from other sloth collections and merge changes with a couple of strategies.
# You can search for JSON objects by passing a fairly rich criteria object to 'find'.
# Sloth comes with token based user authentication functions, that can be used when sloth is started in secure mode.
#
# Sloth would not be possible without D. Richard Hipp who wrote the wonderful SQLite and Linus Torvalds who wrote the very smart
# (ironically for the name) git, both of which are huge inspirations for sloth.
#
# This version of sloth is for JS and runs on node.js.  You can use it in the browser remotely by passing in a dNode or now.js
# object as a `remoteObject` param to sloth.start.
# There is at least one other planned version for iOS/Cocoa.
#

# Save a reference to the global object.
root = this

# Save the previous value of the `sloth` variable.
previousSloth = root.sloth

# The top-level namespace. All public sloth classes and modules will
# be attached to this. Exported for both CommonJS and the browser.
if exports? then sloth = exports
else sloth = root.sloth = new Sloth()

# Current version of the library. Keep in sync with `package.json`.
sloth.VERSION = '0.1-pre'

# Require Underscore, if we're on the server, and it's not already present.
_ = root._
if (!_ and require?) then _ = require('underscore')._

# Runs sloth.js in *noConflict* mode, returning the `sloth` variable
# to its previous owner. Returns a reference to this sloth object.
sloth.noConflict = ->
  root.sloth = previousSloth
  return this

class Sloth
  
  # Start sloth.
  #
  # Options
  # db:         Path to SQLite file that Sloth will use as it's local db.  Defaults to sloth.db in current directory.
  # nodeServer: A node http server object that sloth will listen on http requests.
  # remoteObject: pass a dnode or other remote object that Sloth will attach it's functions too, so it can be invoked remotely via Socket.io.
  # secure:     start Sloth in secure mode, so that all Sloth functions will take an authenticated user
  #             object as the first param with a valid accessToken on it.
  start: (options) ->
  
  # Tell Sloth to track a collection.
  # The url param is optional; it is the url of a remote collection to track.
  # If missing, the collection will be created locally.
  addCollection(collection, url, cb): ->
  
  # Stop tracking the collection.
  # The objects in the collection remain if they are tracked by other collections in the local sloth store (I think this is right).
  removeCollection(collection, cb): ->
    
  # Add objects to a sloth working collection..
  # The optional collection defaults to master, and must exist.
  # You are telling sloth of your changes to existing object content or brand new object content;
  # sloth will figure it out.  This does not commit the objects.
  # If you want to stop tracking the objects call sloth.remove and pass the same objects.
  add: (objs, collection, cb) ->
    
  # Tell sloth to remove the objects from the working collection and its object store.
  # The optional collection is where sloth should look for the objects, and defaults to master.
  remove: (objs, collection, cb) ->
    
  # Discards the changes, if any, of the supplied objects in the working collection.  
  # The optional collection defaults to master, and must exist.
  discardChanges: (objs, cb) ->
  
  # Commit the working collection to sloth's object store.
  # The optional collection defaults to master, and must exist.
  # User is the user making the commit.  The user object must have a name and email on it for blame purposes.
  # In secure mode, the user object must have a valid accessToken property.
  # The optional collection defaults to master, and must exist.
  # The optional message is a user focused message for this commit.
  # This will create a commit object with the sha, parentSha, collection name, user name, email, timestamp, message and a hash of the changes.
  # and store it in the special 'sloth-commits' collection.
  # The sha is the SHA-1 hash of the contents of the commit plus the commit message, which can be passed
  # to sloth.findByCommit to find the commit.
  # Callback will be invoked as cb(err, commit)
  commit: (user, msg, collection, cb) ->
    
  # Adds and commits in one command
  addAndCommit: (user, objs, msg, collection, cb) ->
    
  # Finds objects in the collection, that match the supplied criteria
  # Criteria is MongoDB like criteria JSON object and will be explained later.
  # Callback will be invoked as cb(err, foundObjects).
  find: (critera, collection, cb)
  
  # Pushes the changes from one collection to another using a content based sync.
  # The target collection can be remote.
  # Both collections must be known and tracked by sloth.
  push: (sourceCollection, targetCollection, cb) ->
    
  # Pulls the changes from one collection to another using a content based sync.
  # The source collection can be remote.
  # Both collections must be known and tracked by sloth.
  pull: (sourceCollection, targetCollection, cb) ->