vendor/json2.js vendor/query.js @@ -1,64 +1,111 @@ jquery.cloudkit.js ------------------ -An in-browser queryable JSON store for CloudKit. +An in-browser query-able JSON store for CloudKit. -This plugin is the result of combining TaffyDB, patched for asynchronous -operation, with CloudKit and bundling it as a jQuery plugin. This should still -be considered experimental and subject to change. +This jQuery plugin produces in-browser collections of JSON data that map to a +remote CloudKit service. CloudKit is a schema-free auto-versioned RESTful JSON +store with OpenID and OAuth built in. + +Using your in-browser database automatically updates the remote store. Querying +is accomplished via JSONQuery. JSONQuery is a superset of JSONPath. See "Usage" +for examples. See also: - CloudKit: http://getcloudkit.com - TaffyDB: http://taffydb.com + CloudKit, An Open Web JSON Appliance: + http://getcloudkit.com + + JSONPath: + http://goessner.net/articles/JsonPath/ + + JSONQuery introduction on the SitePen blog (in the context of Dojo): + http://www.sitepen.com/blog/2008/07/16/jsonquery-data-querying-beyond-jsonpath/ Usage ----- -Assuming a CloudKit app hosting "notes" and "things" collections: +On the server: + +1) Mount two RESTful resource collections -- one for "notes" and another for + "things" -- in a file called "config.ru" (a rackup file): + + require 'cloudkit' + expose :notes, :things + + (This will mount the CloudKit REST API: http://getcloudkit.com/rest-api.html + for "notes" and "things.") + +2) Start the server: + + rackup config.ru + +3) In an HTML file, include the library. (Instructions for building the library + are included below in the "Building" section.): + + <script type="text/javascript" src="jquery.cloudkit.min.js"></script> + +4) In your JavaScript code: var store = $.cloudkit; + store.boot({ + + // booting the store reads the metadata on the server, loads existing data, + // and configures the local store for use + success: function() { - // insert a 'thing' - store.collection('things').insert({name:"box"}, { - success: function(index) { - // do something with your data + + // the local store is now ready + + // create a 'thing' + store.collection('things').create({name:"box"}, { + + success: function(thing) { + + // the 'thing' resource has now been created locally and posted + // to the server + + alert(thing.json().name); // this will display "box" + + // update the 'thing' + thing.update({name:"book"} { + + success: function() { + + // the updated 'thing' resource has been mirrored on the server + // and is ready for use again + + alert(thing.json().name); // this is now "book" + + // delete the 'thing' + thing.destroy({ + + success: function() { + // the 'thing' has now been deleted + } + } + } + }) } }); - - // insert a 'note' - store.collection('notes').insert({foo:"bar"}, { - success: function(index) { + + // create a 'note' + store.collection('notes').create({foo:"bar"}, { + success: function(note) { // do something with the note } }); - - // update all 'things', setting their name to "boxen". - // See the TaffyDB docs for the optional second "where" parameter - // (excluded below) specifying a subset of documents to update. - store.collection('things').update({name:"boxen"}, { - success: function(indexes) { - // do something with your updated data - } - }); - - // delete all 'things' where name is "boxen". - store.collection('things').remove({name:"boxen"}, { - success: function(indexes) { - // your data is now removed - } - }); - - // get all 'notes' - var notes = store.collection('notes').get(); - } -}); -This only scratches the surface of the API provided by TaffyDB. See the TaffyDB -site for advanced JSON queries. Keep in mind, the version of TaffyDB used in -this plugin has been patched to add success and error callbacks for insert, -update, and remove methods. All other methods should work identically. + // find all 'note' resources + var notes = store.collection('notes').all(); + // get a specific note + var note = store.collection('notes').get(some_random_note.id()); + + // find all things having a name of 'book' + var matches = store.collection('things').query("?name='book'"); + } +}); Building -------- @@ -71,7 +118,6 @@ The jsmin gem is required for building the minified version. To install: $ gem install jsmin - Running the Tests ----------------- @@ -83,14 +129,13 @@ If you are running an older version of CloudKit, you can upgrade like this: $ gem update cloudkit -To Test: +To test: $ rake Note: You may need to refresh your browser if it launches before rack finishes starting the test app. - Copyright (c) 2008, 2009 Jon Crosby http://joncrosby.me Permission is hereby granted, free of charge, to any person obtaining README @@ -14,11 +14,18 @@ task :dist do FileUtils.rm_rf('dist') FileUtils.mkdir('dist') source = File.read('jquery.cloudkit.js') - taffy = File.read('vendor/taffy-1.6.1-patched.js') - plugin = "#{taffy}\n\n#{source}" + json_util = File.read('vendor/json2.js') + json_query = File.read('vendor/query.js') + plugin = "#{json_util}\n\n#{json_query}\n\n#{source}" File.open('dist/jquery.cloudkit.js', 'w') { |io| io.write(plugin) } File.open('dist/jquery.cloudkit.min.js', 'w') { |io| io.write(JSMin.minify(plugin)) } puts "Complete" puts puts "Check the dist directory for development and minified versions of the plugin." end + +# JSONQuery.js is pulled from the fork at jcrosby/jsonquery on GitHub +desc 'pull in external jsonquery dependency' +task :dep do + FileUtils.cp('../jsonquery/JSONQuery.js', 'vendor/query.js') +end Rakefile @@ -4,7 +4,7 @@ // // Copyright (c) 2008, 2009 Jon Crosby http://joncrosby.me // -// For the complete source with the patched/bundled TaffyDB dependency, +// For the complete source with the bundled dependencies, // run 'rake dist' and use the contents of the dist directory. // //------------------------------------------------------------------------------ @@ -14,163 +14,224 @@ $.cloudkit = $.cloudkit || {}; //---------------------------------------------------------------------------- - // Private API + // Resource Model //---------------------------------------------------------------------------- + var buildResource = function(collection, spec, metadata) { + var that = {}; + var meta = {}; + var json = spec; - var collectionURIs = []; // collection URIs found during boot via discovery - var collections = {}; // TaffyDB stores, one per remote resource collection - var meta = {}; // metadata for each local object + // return a key that is unique across all local items + var generateId = function() { + return (new Date).getTime() + '-' + Math.floor(Math.random()*10000); + }; - // return a key that is unique across all local items - var uniqueId = function() { - return (new Date).getTime() + '-' + Math.floor(Math.random()*10000); - }; + var saveFromRemote = function() { + meta = metadata; + meta.id = generateId(); + }; - // load remote collection URIs - var loadMeta = function(options) { - $.ajax({ - type: 'GET', - url: '/cloudkit-meta', - complete: function(response, statusText) { - data = TAFFY.JSON.parse(response.responseText); - if (response.status == 200) { - collectionURIs = data.uris; - options.success(); - } else if (response.status >= 400) { - options.error(response.status); - } else { - options.error('unexpected error'); - } + that.save = function(callbacks) { + if (!(typeof metadata === 'undefined')) { + return saveFromRemote(); } - }); - }; - - // configure a local collection - var configureCollection = function(collection) { - - // set up TaffyDB - name = collection.replace(/^\//, ''); - collections[name] = new TAFFY([]); - collections[name].config.set('map', function(item) { - delete item['___cloudkit_local_id___']; - }); - - // map insert to POST - collections[name].onInsert = function(data, options) { $.ajax({ type: 'POST', url: collection, - data: TAFFY.JSON.stringify(data), + data: JSON.stringify(spec), contentType: 'application/json', dataType: 'json', processData: false, complete: function(response, statusText) { - localId = uniqueId(); - meta[localId] = TAFFY.JSON.parse(response.responseText); - data['___cloudkit_local_id___'] = localId; if (response.status == 201) { - options.success(); + meta = JSON.parse(response.responseText); + meta.id = generateId(); + callbacks.success(); } else { - options.error(response.status); + callbacks.error(response.status); } } }); }; - // map update to PUT - collections[name].onUpdate = function(data, original, options) { - localId = original['___cloudkit_local_id___']; - delete data['___cloudkit_local_id___'] - metadata = meta[localId]; + that.update = function(spec, callbacks) { + var id = meta.id; $.ajax({ type: 'PUT', - url: metadata.uri, - data: TAFFY.JSON.stringify(data), + url: meta.uri, + data: JSON.stringify(spec), contentType: 'application/json', dataType: 'json', beforeSend: function(xhr) { - xhr.setRequestHeader('If-Match', metadata.etag); + xhr.setRequestHeader('If-Match', meta.etag); }, processData: false, complete: function(response, statusText) { - meta[localId] = TAFFY.JSON.parse(response.responseText); - data['___cloudkit_local_id___'] = localId; if (response.status == 200) { - options.success(); + meta = JSON.parse(response.responseText); + meta.id = id; + json = spec; + callbacks.success(); } else { - // default 412 strategy is progressive diff/merge. - // first cut is to get current version, then update. - // TODO use callback to alter this behavior - if (response.status == 412) { - $.ajax({ - type: 'GET', - url: metadata.uri, - dataType: 'json', - processData: false, - complete: function(response, statusText) { - if (response.status == 200) { - var currentData = TAFFY.JSON.parse(response.responseText); - currentData['___cloudkit_local_id___'] = localId; - collections[name].updateFromRemote(currentData); - meta[localId] = { - uri: metadata.uri, - etag: response.getResponseHeader('ETag'), - last_modified: response.getResponseHeader('Last-Modified') - }; - collections[name].update(data, currentData, { - success: function() { - options.success(); - }, - error: function(status) { - options.error(status); - } - }); - } else { - options.error(response.status); - } - } - }); - - } else { - // TODO consider custom behavior for: - // 400, 401, 404, 405, 410, 422 - options.error(response.status); - } + // TODO implement default 412 strategy as progressive diff/merge + callbacks.error(response.status); } } }); }; - // map remove to DELETE - collections[name].onRemove = function(data, options) { - localId = data['___cloudkit_local_id___']; - metadata = meta[localId]; + that.destroy = function(callbacks) { + var id = meta.id $.ajax({ type: 'DELETE', - url: metadata.uri, + url: meta.uri, dataType: 'json', beforeSend: function(xhr) { - xhr.setRequestHeader('If-Match', metadata.etag); + xhr.setRequestHeader('If-Match', meta.etag); }, processData: false, complete: function(response, statusText) { - updated_metadata = TAFFY.JSON.parse(response.responseText); - meta[localId] = updated_metadata; + meta = JSON.parse(response.responseText); + meta.id = id; if (response.status == 200) { - meta['deleted'] = true; - options.success(); + meta.deleted = true; + callbacks.success(); } else { - options.error(response.status); + callbacks.error(response.status); } } }); }; + + that.json = function() { + return json; + }; + + that.id = function() { + return meta.id; + }; + + that.uri = function() { + return meta.uri; + }; + + that.isDeleted = function() { + return (meta.deleted == true); + } + + return that; + }; + + //---------------------------------------------------------------------------- + // Internal Data Store + //---------------------------------------------------------------------------- + var buildStore = function(collection) { + var that = {}; + + var key = function(resource) { + return collection+resource.id(); + }; + + var persist = function(resource) { + var k = key(resource); + $.data(window, k, resource); + var index = $.data(window, collection+'index') || []; + index.push(k); + $.data(window, collection+'index', index); + }; + + that.create = function(spec, callbacks) { + resource = buildResource(collection, spec); + resource.save({ + success: function() { + persist(resource); + callbacks.success(resource); + }, + error: function(status) { + callbacks.error(status); + } + }); + }; + + that.createFromRemote = function(spec, metadata) { + resource = buildResource(collection, spec, metadata); + resource.save(); + persist(resource); + return resource; + }; + + that.all = function(spec) { + // TODO - don't ignore spec + var result = []; + var index = $.data(window, collection+'index'); + $(index).each(function(count, id) { + var item = $.data(window, id); + if (!item.isDeleted()) { + result.push(item); + } + }); + return result; + }; + + that.get = function(id) { + return $.data(window, collection+id); + }; + + that.query = function(spec) { + var jsonObjects = []; + var self = this; + $(this.all()).each(function(index, item) { + json = $.extend(item.json(), {'___id___':item.id()}); + jsonObjects.push(json); + }); + var query_result = JSONQuery(spec, jsonObjects); + var resources = [] + $(query_result).each(function(index, item) { + resources.push(self.get(item['___id___'])); + }); + return resources; + } + + return that; + }; + + //---------------------------------------------------------------------------- + // Private API + //---------------------------------------------------------------------------- + + var collectionURIs = []; // collection URIs found during boot via discovery + var collections = {}; // local stores, one per remote resource collection + + // load remote collection URIs + var loadMeta = function(callbacks) { + $.ajax({ + type: 'GET', + url: '/cloudkit-meta', + complete: function(response, statusText) { + data = JSON.parse(response.responseText); + if (response.status == 200) { + collectionURIs = data.uris; + callbacks.success(); + } else if (response.status >= 400) { + callbacks.error(response.status); + } else { + callbacks.error('unexpected error'); + } + } + }); + }; + + // configure a local collection + var configureCollection = function(collection) { + $.data(window, collection+'index', []); + var name = collection.replace(/^\//, ''); + collections[name] = buildStore(collection); }; // load remote data into local store - var populateCollectionsFromRemote = function(index, options) { + var populateCollectionsFromRemote = function(index, callbacks) { if (index == collectionURIs.length) { - options.success(); + callbacks.success(); return; } $.ajax({ @@ -180,23 +241,22 @@ processData: false, complete: function(response, statusText) { if (response.status == 200) { - resources = TAFFY.JSON.parse(response.responseText).documents; - name = collectionURIs[index].replace(/^\//, ''); + var resources = JSON.parse(response.responseText).documents; + var name = collectionURIs[index].replace(/^\//, ''); for (var i = 0; i < resources.length; i++) { - resource = resources[i]; - localId = uniqueId(); - doc = TAFFY.JSON.parse(resource.document); - doc['___cloudkit_local_id___'] = localId; - collections[name].insertFromRemote(doc); - meta[localId] = { - uri: resource.uri, - etag: resource.etag, - last_modified: resource.last_modified - }; + var resource = resources[i]; + collections[name].createFromRemote( + JSON.parse(resource.document), + { + uri: resource.uri, + etag: resource.etag, + last_modified: resource.last_modified + } + ); } - populateCollectionsFromRemote(index+1,options); + populateCollectionsFromRemote(index+1, callbacks); } else { - options.error(response.status); + callbacks.error(response.status); } } }); @@ -210,10 +270,9 @@ //-------------------------------------------------------------------------- // setup the local store - boot: function(options) { + boot: function(callbacks) { collectionURIs = []; collections = []; - meta = {}; loadMeta({ success: function() { $(collectionURIs).each(function(index, collection) { @@ -221,32 +280,27 @@ }); populateCollectionsFromRemote(0, { success: function() { - options.success(); + callbacks.success(); }, error: function(status) { - options.error(status); + callbacks.error(status); } }); }, error: function(status) { - options.error(status); + callbacks.error(status); } }); }, - // return all TaffyDB collections + // return all collections collections: function() { return collections; }, - // return a specific TaffyDB collection + // return a specific collection collection: function(name) { return this.collections()[name]; - }, - - // return the metadata for a given local ID - metaObject: function(localId) { - return meta[localId]; } }); })(jQuery); jquery.cloudkit.js @@ -5,7 +5,8 @@ <title>jquery.cloudkit test</title> <link rel="Stylesheet" media="screen" href="testsuite.css"/> <script type="text/javascript" src="../vendor/jquery-1.3.1.js"></script> - <script type="text/javascript" src="../vendor/taffy-1.6.1-patched.js"></script> + <script type="text/javascript" src="../vendor/json2.js"></script> + <script type="text/javascript" src="../vendor/query.js"></script> <script type="text/javascript" src="../jquery.cloudkit.js"></script> <script type="text/javascript" src="jqUnit-1.1.1.js"></script> <script type="text/javascript" src="test.js"></script> test/test.html @@ -12,7 +12,7 @@ var tests = function($) { $.ajax({ type: 'POST', url: '/'+collection, - data: TAFFY.JSON.stringify(data), + data: JSON.stringify(data), async: false }); }; @@ -43,34 +43,34 @@ var tests = function($) { postData('things', {'a':'b'}); store.boot({ success: function() { - jqUnit.ok(store.collection('notes').get().length == 2, "Booting should load the notes collection data"); - jqUnit.ok(store.collection('things').get().length == 1, "Booting should load the things collection data"); + jqUnit.ok(store.collection('notes').all().length == 2, "Booting should load the notes collection data"); + jqUnit.ok(store.collection('things').all().length == 1, "Booting should load the things collection data"); jqUnit.start(); } }); }); - jqUnit.test('insert', function() { + jqUnit.test('create', function() { resetRemote(); jqUnit.expect(4); jqUnit.stop(); store.boot({ success: function() { - store.collection('things').insert({name:"box"}, { - success: function(index) { - jqUnit.ok(index == 0, "The first insert should return the proper index from TaffyDB"); - store.collection('things').insert({name:"book"}, { - success: function(index) { - jqUnit.ok(index == 1, "The second insert should return an index of 1"); - jqUnit.ok(store.collection('things').get().length == 2, "The store should have two items after booting"); - var result = TAFFY.JSON.parse( + store.collection('things').create({name:"box"}, { + success: function(resource) { + jqUnit.ok(!(typeof resource === 'undefined'), "Creating a resource should return the resource"); + jqUnit.ok(!(typeof resource.id() === 'undefined'), "The resource should have an ID"); + store.collection('things').create({name:"book"}, { + success: function(inner_resource) { + jqUnit.ok(store.collection('things').all().length == 2, "The store should have two items after the second create operation"); + var result = JSON.parse( $.ajax({ type: 'GET', url: '/things', async: false }).responseText ).total; - jqUnit.ok(result == 2); + jqUnit.ok(result == 2, "The store should POST to the remote store"); jqUnit.start(); } }); @@ -86,11 +86,11 @@ var tests = function($) { jqUnit.stop(); store.boot({ success: function() { - store.collection('things').insert({name:"box", color:"red"}, { - success: function(index) { - store.collection('things').insert({name:"book", color:"black"}, { - success: function(index) { - jqUnit.ok('book' == store.collection('things').get({color:"black"})[0].name, "The get method should return the correct object"); + store.collection('things').create({name:"box", color:"red"}, { + success: function(resource) { + store.collection('things').create({name:"book", color:"black"}, { + success: function(inner_resource) { + jqUnit.ok('book' == store.collection('things').get(inner_resource.id()).json().name, "The get method should return the correct object"); jqUnit.start(); } }); @@ -106,11 +106,11 @@ var tests = function($) { jqUnit.stop(); store.boot({ success: function() { - store.collection('things').insert({name:"box", color:"red"}, { - success: function(index) { - store.collection('things').update({name:"boxen"}, { - success: function(indexes) { - jqUnit.ok('boxen' == store.collection('things').get({color:"red"})[0].name, "The update method should update the object"); + store.collection('things').create({name:"box", color:"red"}, { + success: function(resource) { + resource.update({name:"boxen"}, { + success: function() { + jqUnit.ok('boxen' == store.collection('things').get(resource.id()).json().name, "The update method should update the object"); jqUnit.start(); } }); @@ -120,17 +120,46 @@ var tests = function($) { }); }); - jqUnit.test('delete', function() { // TODO test for 410 from CloudKit + jqUnit.test('destroy', function() { resetRemote(); - jqUnit.expect(1); + jqUnit.expect(3); jqUnit.stop(); store.boot({ success: function() { - store.collection('things').insert({name:"box", color:"red"}, { - success: function() { - store.collection('things').remove({name:"box"}, { + store.collection('things').create({name:"box", color:"red"}, { + success: function(resource) { + resource.destroy({ success: function() { - jqUnit.ok(0 == store.collection('things').get().length, "The remove method should remove the object"); + jqUnit.ok(0 == store.collection('things').all().length, "The destroy method should remove the object"); + var result = $.ajax({ + type: 'GET', + url: resource.uri(), + async: false + }); + jqUnit.ok(410 == result.status, "The destroy method should remove the remote resource"); + jqUnit.ok(true == resource.isDeleted(), "The destroy method should mark the resource as deleted"); + jqUnit.start(); + } + }); + } + }); + } + }); + }); + + jqUnit.test('jsonquery', function() { + resetRemote(); + jqUnit.expect(2); + jqUnit.stop(); + store.boot({ + success: function() { + store.collection('things').create({name:'foo',rating:3}, { + success: function(resource) { + store.collection('things').create({name:'bar',rating:2}, { + success: function(inner_resource) { + result = store.collection('things').query("?name='bar'"); + jqUnit.ok(1 == result.length, "The = operator should return the correct number of results"); + jqUnit.ok('bar' == result[0].json().name, "The = operator should return the correct resource"); jqUnit.start(); } }); test/test.js vendor/taffy-1.6.1-patched.js ef300b8f23874a5621bb811da38aeb3451b379b3 Jon Crosby jon@joncrosby.me http://github.com/jcrosby/jquery-cloudkit/commit/35b2722cad559999aa8cf4d9196621d596d0e7cb 35b2722cad559999aa8cf4d9196621d596d0e7cb 2009-04-04T15:12:01-07:00 2009-04-04T15:12:01-07:00 Implement JSONQuery * Remove TaffyDB * Use jQuery.data * Use forked JSONQuery.js 58faa0017a78a2ae5dc7917d3a7332c11f860c09 Jon Crosby jon@joncrosby.me