From 9b47e47e93eac6f6dbd0abb1808357e45bc9bbb7 Mon Sep 17 00:00:00 2001 From: Victor Woeltjen Date: Tue, 2 Dec 2014 18:06:49 -0800 Subject: [PATCH] [Persistence] Add JSDoc Fill in JSDoc for the CouchDB adapter which provides the ability to persist domain object models. Part of ongoing transition of the platform/persistence bundle, WTD-537. --- .../src/CouchPersistenceProvider.js | 70 ++++++++++++++++++- .../test/CouchPersistenceProviderSpec.js | 10 ++- 2 files changed, 75 insertions(+), 5 deletions(-) diff --git a/platform/persistence/src/CouchPersistenceProvider.js b/platform/persistence/src/CouchPersistenceProvider.js index cf644b857f..1b5ae38a79 100644 --- a/platform/persistence/src/CouchPersistenceProvider.js +++ b/platform/persistence/src/CouchPersistenceProvider.js @@ -5,6 +5,12 @@ define( function (CouchDocument) { 'use strict'; + /** + * The CouchPersistenceProvider reads and writes JSON documents + * (more specifically, domain object models) to/from a CouchDB + * instance. + * @constructor + */ function CouchPersistenceProvider($http, $q, SPACE, PATH) { var spaces = [ SPACE ], revs = {}; @@ -29,19 +35,21 @@ define( }); } - // Shorthand methods for various HTTP methods + // Shorthand methods for GET/PUT methods function get(subpath) { return request(subpath, "GET"); } - function put(subpath, value) { return request(subpath, "PUT", value); } + // Pull out a list of document IDs from CouchDB's + // _all_docs response function getIdsFromAllDocs(allDocs) { return allDocs.rows.map(function (r) { return r.id; }); } + // Get a domain object model out of CouchDB's response /*jslint nomen: true */ // Allow the _id and _rev that couch provides function getModel(response) { if (response && response.model) { @@ -52,6 +60,9 @@ define( } } + // Check the response to a create/update/delete request; + // track the rev if it's valid, otherwise return false to + // indicate that the request failed. function checkResponse(response) { if (response && response.ok) { revs[response.id] = response.rev; @@ -62,23 +73,78 @@ define( } return { + /** + * List all persistence spaces which this provider + * recognizes. + * + * @returns {Promise.} a promise for a list of + * spaces supported by this provider + */ listSpaces: function () { return $q.when(spaces); }, + /** + * List all objects (by their identifiers) that are stored + * in the given persistence space, per this provider. + * @param {string} space the space to check + * @returns {Promise.} a promise for the list of + * identifiers + */ listObjects: function (space) { return get("_all_docs").then(getIdsFromAllDocs); }, + /** + * Create a new object in the specified persistence space. + * @param {string} space the space in which to store the object + * @param {string} key the identifier for the persisted object + * @param {object} value a JSONifiable object that should be + * stored and associated with the provided identifier + * @returns {Promise.} a promise for an indication + * of the success (true) or failure (false) of this + * operation + */ createObject: function (space, key, value) { return put(key, new CouchDocument(key, value)) .then(checkResponse); }, + + /** + * Read an existing object back from persistence. + * @param {string} space the space in which to look for + * the object + * @param {string} key the identifier for the persisted object + * @returns {Promise.} a promise for the stored + * object; this will resolve to undefined if no such + * object is found. + */ readObject: function (space, key) { return get(key).then(getModel); }, + /** + * Update an existing object in the specified persistence space. + * @param {string} space the space in which to store the object + * @param {string} key the identifier for the persisted object + * @param {object} value a JSONifiable object that should be + * stored and associated with the provided identifier + * @returns {Promise.} a promise for an indication + * of the success (true) or failure (false) of this + * operation + */ updateObject: function (space, key, value) { return put(key, new CouchDocument(key, value, revs[key])) .then(checkResponse); }, + /** + * Delete an object in the specified persistence space. + * @param {string} space the space from which to delete this + * object + * @param {string} key the identifier of the persisted object + * @param {object} value a JSONifiable object that should be + * deleted + * @returns {Promise.} a promise for an indication + * of the success (true) or failure (false) of this + * operation + */ deleteObject: function (space, key, value) { return put(key, new CouchDocument(key, value, revs[key], true)) .then(checkResponse); diff --git a/platform/persistence/test/CouchPersistenceProviderSpec.js b/platform/persistence/test/CouchPersistenceProviderSpec.js index 07b8b0a35a..4002464fdd 100644 --- a/platform/persistence/test/CouchPersistenceProviderSpec.js +++ b/platform/persistence/test/CouchPersistenceProviderSpec.js @@ -46,6 +46,10 @@ define( expect(capture).toHaveBeenCalledWith([testSpace]); }); + // General pattern of tests below is to simulate CouchDB's + // response, verify that request looks like what CouchDB + // would expect, and finally verify that CouchPersistenceProvider's + // return values match what is expected. it("lists all available documents", function () { mockHttp.andReturn(mockPromise({ data: { rows: [ { id: "a" }, { id: "b" }, { id: "c" } ] } @@ -65,7 +69,7 @@ define( })); provider.createObject("testSpace", "abc", model).then(capture); expect(mockHttp).toHaveBeenCalledWith({ - url: "/test/db/abc", // couch document listing + url: "/test/db/abc", method: "PUT", data: { "_id": "abc", @@ -83,7 +87,7 @@ define( })); provider.readObject("testSpace", "abc").then(capture); expect(mockHttp).toHaveBeenCalledWith({ - url: "/test/db/abc", // couch document listing + url: "/test/db/abc", method: "GET" }); expect(capture).toHaveBeenCalledWith(model); @@ -104,7 +108,7 @@ define( })); provider.updateObject("testSpace", "abc", model).then(capture); expect(mockHttp).toHaveBeenCalledWith({ - url: "/test/db/abc", // couch document listing + url: "/test/db/abc", method: "PUT", data: { "_id": "abc",