From 454b150fb618bb5859c3729cd184885db1c478bc Mon Sep 17 00:00:00 2001 From: Nicolas Dextraze Date: Sun, 6 Nov 2016 22:58:11 -0800 Subject: [PATCH] Working on documentation (wip) --- .gitignore | 2 +- .idea/eventstore-node.iml | 1 + package.json | 3 +- src/client.js | 34 ++++++------ src/clientOperations/operationBase.js | 4 +- src/common/bufferSegment.js | 1 + src/common/hash.js | 1 + src/core/eventStoreConnectionLogicHandler.js | 1 + src/core/messages.js | 1 + src/core/operationsManager.js | 1 + src/eventData.js | 1 + src/eventStoreConnection.js | 2 + src/eventStoreNodeConnection.js | 57 ++++++++++++++++++-- src/results.js | 1 + src/transport/tcp/tcpPackageConnection.js | 1 + src/volatileEventStoreSubscription.js | 1 + 16 files changed, 87 insertions(+), 25 deletions(-) diff --git a/.gitignore b/.gitignore index 4f37f65..6569af6 100644 --- a/.gitignore +++ b/.gitignore @@ -39,4 +39,4 @@ node_modules lib/ .eslintrc.json jsconfig.json - +docs/ diff --git a/.idea/eventstore-node.iml b/.idea/eventstore-node.iml index 8b64aa0..831172f 100644 --- a/.idea/eventstore-node.iml +++ b/.idea/eventstore-node.iml @@ -3,6 +3,7 @@ + diff --git a/package.json b/package.json index 598aa2f..bce6de9 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,8 @@ "build": "webpack", "pretest": "npm run build", "test": "nodeunit", - "prepublish": "npm run build" + "prepublish": "npm run build", + "gendocs": "rm -rf docs && jsdoc src -r -R README.md -P package.json -d docs" }, "files": [ "lib", diff --git a/src/client.js b/src/client.js index e6a4762..90382aa 100644 --- a/src/client.js +++ b/src/client.js @@ -12,31 +12,35 @@ const positions = { }; /** - * @param {string} eventId - * @param {object} event - * @param {object} [metadata] - * @param {string} [type] + * Create an EventData object from JavaScript event/metadata that will be serialized as json + * @public + * @param {string} eventId Event UUID + * @param {object} event Event object + * @param {object} [metadata] Event metadata + * @param {string} [type] Event type * @returns {EventData} */ -function jsonEventDataFactory(eventId, event, metadata, type) { +module.exports.createJsonEventData = function (eventId, event, metadata, type) { if (!event || typeof event !== 'object') throw new TypeError("data must be an object."); var eventBuf = new Buffer(JSON.stringify(event)); var metaBuf = metadata ? new Buffer(JSON.stringify(metadata)) : null; return new EventData(eventId, type || event.constructor.name, true, eventBuf, metaBuf); -} +}; /** - * @param {string} eventId - * @param {string} type - * @param {boolean} isJson - * @param {Buffer} data - * @param {Buffer} [metadata] + * Create an EventData object from event/metadata buffer(s) + * @public + * @param {string} eventId Event UUID + * @param {string} type Event type + * @param {boolean} isJson is buffer(s) content json + * @param {Buffer} data Data buffer + * @param {Buffer} [metadata] Metadata buffer * @returns {EventData} */ -function eventDataFactory(eventId, type, isJson, data, metadata) { +module.exports.createEventData = function (eventId, type, isJson, data, metadata) { return new EventData(eventId, type, isJson, data, metadata); -} +}; // Expose classes module.exports.EventStoreConnection = require('./eventStoreConnection'); @@ -59,6 +63,4 @@ module.exports.sliceReadStatus = require('./sliceReadStatus'); module.exports.NoopLogger = require('./common/log/noopLogger'); module.exports.FileLogger = require('./common/log/fileLogger'); // Expose Helper functions -module.exports.createConnection = module.exports.EventStoreConnection.create; -module.exports.createEventData = eventDataFactory; -module.exports.createJsonEventData = jsonEventDataFactory; \ No newline at end of file +module.exports.createConnection = module.exports.EventStoreConnection.create; \ No newline at end of file diff --git a/src/clientOperations/operationBase.js b/src/clientOperations/operationBase.js index 3454b2f..295e3ac 100644 --- a/src/clientOperations/operationBase.js +++ b/src/clientOperations/operationBase.js @@ -75,7 +75,7 @@ OperationBase.prototype.inspectPackage = function(pkg) { case TcpCommand.NotHandled: return this._inspectNotHandled(pkg); default: - return this._inspectUnexpectedCommand(package, this._responseCommand); + return this._inspectUnexpectedCommand(pkg, this._responseCommand); } } catch(e) { this.fail(e); @@ -136,7 +136,7 @@ OperationBase.prototype._inspectUnexpectedCommand = function(pkg, expectedComman this.log.error("Unexpected TcpCommand received.\n" + "Expected: %s, Actual: %s, Flags: %s, CorrelationId: %s\n" + "Operation (%s): %s\n" - +"TcpPackage Data Dump:\n%j", + + "TcpPackage Data Dump:\n%j", expectedCommand, TcpCommand.getName(pkg.command), pkg.flags, pkg.correlationId, this.constructor.name, this, pkg.data); diff --git a/src/common/bufferSegment.js b/src/common/bufferSegment.js index 3bbb5c3..627d76e 100644 --- a/src/common/bufferSegment.js +++ b/src/common/bufferSegment.js @@ -1,5 +1,6 @@ /** * Create a buffer segment + * @private * @param {Buffer} buf * @param {number} [offset] * @param {number} [count] diff --git a/src/common/hash.js b/src/common/hash.js index f5ef3a6..0c3aa4f 100644 --- a/src/common/hash.js +++ b/src/common/hash.js @@ -1,4 +1,5 @@ /** + * @private * @constructor * @property {number} length */ diff --git a/src/core/eventStoreConnectionLogicHandler.js b/src/core/eventStoreConnectionLogicHandler.js index 7b56b60..1adb5b2 100644 --- a/src/core/eventStoreConnectionLogicHandler.js +++ b/src/core/eventStoreConnectionLogicHandler.js @@ -36,6 +36,7 @@ const TimerTickMessage = new messages.TimerTickMessage(); const EmptyGuid = '00000000-0000-0000-0000-000000000000'; /** + * @private * @param {EventStoreNodeConnection} esConnection * @param {Object} settings * @constructor diff --git a/src/core/messages.js b/src/core/messages.js index 9c5cedd..6892b59 100644 --- a/src/core/messages.js +++ b/src/core/messages.js @@ -41,6 +41,7 @@ function StartSubscriptionMessage( util.inherits(StartSubscriptionMessage, Message); /** + * @private * @constructor * @property {object} endPoints * @property {object} endPoints.secureTcpEndPoint diff --git a/src/core/operationsManager.js b/src/core/operationsManager.js index eb2a5c1..6e2e12d 100644 --- a/src/core/operationsManager.js +++ b/src/core/operationsManager.js @@ -5,6 +5,7 @@ var Hash = require('../common/hash'); var TcpCommand = require('../systemData/tcpCommand'); /** + * @private * @param {string} connectionName * @param {object} settings * @constructor diff --git a/src/eventData.js b/src/eventData.js index 5205a6d..35d7aa5 100644 --- a/src/eventData.js +++ b/src/eventData.js @@ -12,6 +12,7 @@ function isValidId(id) { /** * Create an EventData + * @private * @param {string} eventId * @param {string} type * @param {boolean} [isJson] diff --git a/src/eventStoreConnection.js b/src/eventStoreConnection.js index 98b7245..c64c666 100644 --- a/src/eventStoreConnection.js +++ b/src/eventStoreConnection.js @@ -97,6 +97,8 @@ function createFromGossipSeeds(connectionSettings, gossipSeeds, connectionName) /** * Create an EventStore connection + * @public + * @alias createConnection * @param {object} settings * @param {string|object|array} endPointOrGossipSeeds * @param {string} [connectionName] diff --git a/src/eventStoreNodeConnection.js b/src/eventStoreNodeConnection.js index 3df5b20..f2e3a71 100644 --- a/src/eventStoreNodeConnection.js +++ b/src/eventStoreNodeConnection.js @@ -33,12 +33,8 @@ var EventData = require('./eventData'); const MaxReadSize = 4096; /** - * @param settings - * @param clusterSettings - * @param endpointDiscoverer - * @param connectionName + * @protected * @constructor - * @property {string} connectionName */ function EventStoreNodeConnection(settings, clusterSettings, endpointDiscoverer, connectionName) { this._connectionName = connectionName || ['ES-', uuid.v4()].join(''); @@ -73,6 +69,8 @@ Object.defineProperty(EventStoreNodeConnection.prototype, 'connectionName', { }); /** + * Start connection task + * @public * @returns {Promise} */ EventStoreNodeConnection.prototype.connect = function() { @@ -87,12 +85,17 @@ EventStoreNodeConnection.prototype.connect = function() { }); }; +/** + * Close connection + * @public + */ EventStoreNodeConnection.prototype.close = function() { this._handler.enqueueMessage(new messages.CloseConnectionMessage("Connection close requested by client.", null)); }; /** * Delete a stream (async) + * @public * @param {string} stream * @param {number} expectedVersion * @param {boolean} [hardDelete] @@ -120,6 +123,7 @@ EventStoreNodeConnection.prototype.deleteStream = function(stream, expectedVersi /** * Append events to a stream (async) + * @public * @param {string} stream The name of the stream to which to append. * @param {number} expectedVersion The version at which we currently expect the stream to be in order that an optimistic concurrency check can be performed. * @param {EventData[]|EventData} events The event(s) to append. @@ -148,6 +152,7 @@ EventStoreNodeConnection.prototype.appendToStream = function(stream, expectedVer /** * Start a transaction (async) + * @public * @param {string} stream * @param {number} expectedVersion * @param {UserCredentials} [userCredentials] @@ -172,6 +177,7 @@ EventStoreNodeConnection.prototype.startTransaction = function(stream, expectedV /** * Continue a transaction + * @public * @param {number} transactionId * @param {UserCredentials} userCredentials * @returns {EventStoreTransaction} @@ -199,6 +205,13 @@ EventStoreNodeConnection.prototype.transactionalWrite = function(transaction, ev }); }; +/** + * Commit a transaction + * @public + * @param transaction + * @param userCredentials + * @returns {Promise.} + */ EventStoreNodeConnection.prototype.commitTransaction = function(transaction, userCredentials) { ensure.isTypeOf(EventStoreTransaction, transaction, "transaction"); @@ -216,6 +229,7 @@ EventStoreNodeConnection.prototype.commitTransaction = function(transaction, use /** * Read a single event (async) + * @public * @param {string} stream * @param {number} eventNumber * @param {boolean} [resolveLinkTos] @@ -248,6 +262,7 @@ EventStoreNodeConnection.prototype.readEvent = function(stream, eventNumber, res /** * Reading a specific stream forwards (async) + * @public * @param {string} stream * @param {number} start * @param {number} count @@ -281,6 +296,7 @@ EventStoreNodeConnection.prototype.readStreamEventsForward = function( /** * Reading a specific stream backwards (async) + * @public * @param {string} stream * @param {number} start * @param {number} count @@ -313,6 +329,7 @@ EventStoreNodeConnection.prototype.readStreamEventsBackward = function( /** * Reading all events forwards (async) + * @public * @param {Position} position * @param {number} maxCount * @param {boolean} [resolveLinkTos] @@ -343,6 +360,7 @@ EventStoreNodeConnection.prototype.readAllEventsForward = function( /** * Reading all events backwards (async) + * @public * @param {Position} position * @param {number} maxCount * @param {boolean} [resolveLinkTos] @@ -373,6 +391,7 @@ EventStoreNodeConnection.prototype.readAllEventsBackward = function( /** * Subscribe to a stream (async) + * @public * @param {!string} stream * @param {!boolean} resolveLinkTos * @param {function} eventAppeared @@ -402,6 +421,8 @@ EventStoreNodeConnection.prototype.subscribeToStream = function( }; /** + * Subscribe to a stream from position + * @public * @param {!string} stream * @param {?number} lastCheckpoint * @param {!boolean} resolveLinkTos @@ -430,6 +451,7 @@ EventStoreNodeConnection.prototype.subscribeToStreamFrom = function( /** * Subscribe to all (async) + * @public * @param {!boolean} resolveLinkTos * @param {!function} eventAppeared * @param {function} [subscriptionDropped] @@ -456,6 +478,7 @@ EventStoreNodeConnection.prototype.subscribeToAll = function( /** * Subscribe to all from + * @public * @param {?Position} lastCheckpoint * @param {!boolean} resolveLinkTos * @param {!function} eventAppeared @@ -481,6 +504,7 @@ EventStoreNodeConnection.prototype.subscribeToAllFrom = function( /** * Subscribe to a persistent subscription + * @public * @param {string} stream * @param {string} groupName * @param {function} eventAppeared @@ -488,6 +512,7 @@ EventStoreNodeConnection.prototype.subscribeToAllFrom = function( * @param {UserCredentials} [userCredentials] * @param {number} [bufferSize] * @param {boolean} [autoAck] + * @return {EventStorePersistentSubscription} */ EventStoreNodeConnection.prototype.connectToPersistentSubscription = function( stream, groupName, eventAppeared, subscriptionDropped, userCredentials, bufferSize, autoAck @@ -510,6 +535,8 @@ EventStoreNodeConnection.prototype.connectToPersistentSubscription = function( }; /** + * Create a persistent subscription + * @public * @param {string} stream * @param {string} groupName * @param {PersistentSubscriptionSettings} settings @@ -533,6 +560,8 @@ EventStoreNodeConnection.prototype.createPersistentSubscription = function(strea }; /** + * Update a persistent subscription + * @public * @param {string} stream * @param {string} groupName * @param {string} settings @@ -555,6 +584,8 @@ EventStoreNodeConnection.prototype.updatePersistentSubscription = function(strea }; /** + * Delete a persistent subscription + * @public * @param {string} stream * @param {string} groupName * @param {UserCredentials} [userCredentials] @@ -574,6 +605,10 @@ EventStoreNodeConnection.prototype.deletePersistentSubscription = function(strea }); }; +/** + * Set stream metadata + * @private + */ EventStoreNodeConnection.prototype.setStreamMetadata = function() { //TODO: set stream metadata (non-raw) throw new Error("Not implemented."); @@ -581,6 +616,7 @@ EventStoreNodeConnection.prototype.setStreamMetadata = function() { /** * Set stream metadata with raw object (async) + * @public * @param {string} stream * @param {number} expectedMetastreamVersion * @param {object} metadata @@ -608,6 +644,12 @@ EventStoreNodeConnection.prototype.setStreamMetadataRaw = function( }); }; +/** + * Get stream metadata + * @private + * @param stream + * @param userCredentials + */ EventStoreNodeConnection.prototype.getStreamMetadata = function(stream, userCredentials) { //TODO: get stream metadata (non-raw) throw new Error("Not implemented."); @@ -615,6 +657,7 @@ EventStoreNodeConnection.prototype.getStreamMetadata = function(stream, userCred /** * Get stream metadata as raw object (async) + * @public * @param {string} stream * @param {UserCredentials} [userCredentials] * @returns {Promise.} @@ -640,6 +683,10 @@ EventStoreNodeConnection.prototype.getStreamMetadataRaw = function(stream, userC }); }; +/** + * Set system settings + * @private + */ EventStoreNodeConnection.prototype.setSystemSettings = function() { //TODO: set system settings throw new Error("Not implemented."); diff --git a/src/results.js b/src/results.js index 5f970ab..bb63c8b 100644 --- a/src/results.js +++ b/src/results.js @@ -4,6 +4,7 @@ var Long = require('long'); var ensure = require('./common/utils/ensure'); /** + * @public * @param {!number|!Long} commitPosition * @param {!number|!Long} preparePosition * @constructor diff --git a/src/transport/tcp/tcpPackageConnection.js b/src/transport/tcp/tcpPackageConnection.js index eb5b1b2..4472b86 100644 --- a/src/transport/tcp/tcpPackageConnection.js +++ b/src/transport/tcp/tcpPackageConnection.js @@ -7,6 +7,7 @@ var TcpPackage = require('../../systemData/tcpPackage'); var TcpCommand = require('../../systemData/tcpCommand'); /** + * @private * @param log * @param remoteEndPoint * @param connectionId diff --git a/src/volatileEventStoreSubscription.js b/src/volatileEventStoreSubscription.js index d0a74f8..6735310 100644 --- a/src/volatileEventStoreSubscription.js +++ b/src/volatileEventStoreSubscription.js @@ -3,6 +3,7 @@ var util = require('util'); var EventStoreSubsription = require('./eventStoreSubscription'); /** + * @private * @param {SubscriptionOperation} subscriptionOperation * @param {string} streamId * @param {Position} lastCommitPosition