Permalink
Browse files

Add jsdoc and start documenting dispatcher modules

  • Loading branch information...
lovett committed Jul 31, 2018
1 parent 5a8bc67 commit 0fa1831bfbd00f505939b9aadeb29c69a0bcac60
Showing with 190 additions and 15 deletions.
  1. +1 −0 .gitignore
  2. +5 −0 Makefile
  3. +16 −7 dispatcher/index.js
  4. +16 −1 dispatcher/schema.js
  5. +18 −4 dispatcher/startup.js
  6. +9 −0 jsdoc.json
  7. +117 −0 package-lock.json
  8. +1 −0 package.json
  9. +7 −3 test/dispatcher/startup-spec.js
@@ -14,3 +14,4 @@ env.json
coverage
*.sqlite
.nyc_output
docs
@@ -49,3 +49,8 @@ coverage: dummy
#
lint: dummy
eslint dispatcher test Gruntfile.js

#
# Generate documentation.
docs: dummy
jsdoc -c jsdoc.json dispatcher server
@@ -1,12 +1,21 @@
/**
* The dispatcher is an event emitter configured with faux-namespaced
* events. Its job is to perform server-side work related to feed
* management and ingestion, and to provide the results of that work
* to the UI.
*
* Event names usually have 2 segments. The first segment is the
* group, which serves as a means of organization and is not otherwise
* significant. Group names usually correspond to subdirectories.
*
* The second segment is the action, and corresponds to a file name.
*
* @module dispatcher
* @listens schema
* @listens startup
*/
'use strict';

// Set up the dispatcher.
//
// The dispatcher is an event emitter configured with faux-namespaced
// events. The first segment of an event name is its group, and the
// second is the action it is responsible for. Groups are just a means
// of organization and not otherwise significant.

const events = require('events');
const emitter = new events.EventEmitter();

@@ -1,8 +1,17 @@
/** @module schema */
'use strict';

const fs = require('fs');
const path = require('path');

/**
* Callback for the schema event.
*
* @callback schemaCallback
* @param {error} [err] - Database error.
*
*/

/**
* Load SQL statements from an external file until the schema is
* up-to-date.
@@ -13,8 +22,14 @@ const path = require('path');
* SQL files are kept in the schema folder at the project root.
*
* Versions are expected to increment by whole numbers.
*
* @param {String} schemaRoot - Filesystem path for directory containing versioned SQL files.
* @param {Number} version - The schema number to apply to the database.
* @param {schemaCallback} callback - A function to invoke on success or failure.
* @event schema
* @fires schema
*/
module.exports = function(schemaRoot, version, callback) {
module.exports = function (schemaRoot, version, callback) {
const self = this;

const sqlPath = path.join(
@@ -1,13 +1,27 @@
/** @module startup */
'use strict';

const sqlite3 = require('sqlite3');

/**
* Callback for the startup event.
*
* @callback startupCallback
* @param {error} [err] - Database error.
*/

/**
* Connect to an SQLite database and update the schema.
*
* There is a single database connection shared by all dispatcher
* modules. Although schema changes are performed elsehwere, this
* is where SQLite pragmas are set.
* Dispatcher modules share a single database connection. This is
* where that connection is opened (if not already open) and where
* SQLite pragmas are set.
*
* @param {string|sqlite3.Database} database - A database path or an already-opened handle.
* @param {string} schemaRoot - Filesystem path to the directory containing schema definitions.
* @param {startupCallback} callback - A function to invoke on success or failure.
* @event startup
* @fires schema
*/
module.exports = function (database, schemaRoot, callback) {
const self = this;
@@ -35,7 +49,7 @@ module.exports = function (database, schemaRoot, callback) {
self.db.get('SELECT schemaVersion FROM versions', (err, row) => {
if (err) {
self.emit('log:error', `Determination of schema version failed: ${err.message}`);
callback();
callback(err);
return;
}

@@ -0,0 +1,9 @@
{
"opts": {
"destination": "./docs/",
"recurse": true
},
"plugins": [
"plugins/markdown"
]
}

Some generated files are not rendered by default. Learn more.

Oops, something went wrong.
@@ -24,6 +24,7 @@
"grunt-http": "2.3.1",
"grunt-shell": "2.1.0",
"grunt-string-replace": "1.3.1",
"jsdoc": "3.5.5",
"load-grunt-tasks": "4.0.0",
"mocha": "5.2.0",
"nock": "9.4.3",
@@ -40,7 +40,8 @@ describe('startup', function() {
it('creates a database instance from a DSN string', function (done) {
const self = this;

self.emitter.emit('startup', self.dbConfig, self.schemaRoot, () => {
self.emitter.emit('startup', self.dbConfig, self.schemaRoot, (err) => {
assert.strictEqual(null, err);
assert.ok(self.emitter.db instanceof sqlite3.Database);
done();
});
@@ -52,7 +53,9 @@ describe('startup', function() {
it('sets foreign_keys pragma', function (done) {
const self = this;

self.emitter.emit('startup', self.dbConfig, self.schemaRoot, () => {
self.emitter.emit('startup', self.dbConfig, self.schemaRoot, (err) => {
assert.strictEqual(null, err);

self.emitter.db.get('PRAGMA foreign_keys', (err, row) => {
if (err) {
throw err;
@@ -80,7 +83,8 @@ describe('startup', function() {
if (err) {
throw err;
}
self.emitter.emit('startup', self.db, self.schemaRoot, () => {
self.emitter.emit('startup', self.db, self.schemaRoot, (err) => {
assert.strictEqual(null, err);
self.db.get(
'SELECT schemaVersion FROM versions',
(err, row) => {

0 comments on commit 0fa1831

Please sign in to comment.