@barchart/portfolio-api-common 1.0.128 → 1.0.132

package/lib/processing/PositionContainer.js

@@ -22,11 +22,11 @@ module.exports = (() => {
 
 	/**
 	 * A container for positions which groups the positions into one or more
-	 * trees for aggregation and display purposes. For example, perhaps a positions
-	 * grouped first by asset class then by position is desired.
+	 * trees for aggregation and display purposes. For example, positions could be
+	 * grouped first by asset class then by position.
 	 *
 	 * Furthermore, the container performs aggregation (driven primarily by price
-	 * changes) for each level of grouping in the internal tree(s).
+	 * changes) for each level of grouping.
 	 *
 	 * @public
 	 * @param {Array.<PositionTreeDefinition>} definitions
@@ -108,6 +108,20 @@ module.exports = (() => {
 				return map;
 			}, { });
 
+			this._symbolsDisplay = this._items.reduce((map, item) => {
+				const symbol = extractSymbolForDisplay(item.position);
+
+				if (symbol) {
+					if (!map.hasOwnProperty(symbol)) {
+						map[symbol] = [ ];
+					}
+
+					map[symbol].push(item);
+				}
+
+				return map;
+			}, { });
+
 			this._currencies = this._items.reduce((map, item) => {
 				const position = item.position;
 
@@ -219,10 +233,14 @@ module.exports = (() => {
 			}, { });
 		}
 
-		get defaultCurrency() {
-			return this._defaultCurrency;
-		}
-		
+		/**
+		 * Returns a distinct list of all symbols used by the positions
+		 * within the container.
+		 *
+		 * @public
+		 * @param {Boolean} display - If true, all "display" symbols are returned; otherwise Barchart symbols are returned.
+		 * @returns {Array.<String>}
+		 */
 		getPositionSymbols(display) {
 			const symbols = this._items.reduce((symbols, item) => {
 				const position = item.position;
@@ -245,6 +263,14 @@ module.exports = (() => {
 			return array.unique(symbols);
 		}
 
+		/**
+		 * Updates the quote for a single symbol; causing updates to any grouping
+		 * level that contains the position(s) for the symbol.
+		 *
+		 * @public
+		 * @param {String} symbol
+		 * @param {Object} quote
+		 */
 		setPositionQuote(symbol, quote) {
 			assert.argumentIsRequired(symbol, 'symbol', String);
 			assert.argumentIsRequired(quote, 'quote', Object);
@@ -254,14 +280,34 @@ module.exports = (() => {
 			}
 		}
 
+		/**
+		 * Returns all forex symbols that are required to do currency translations.
+		 *
+		 * @public
+		 * @returns {Array.<String>}
+		 */
 		getForexSymbols() {
 			return this._forexSymbols;
 		}
 
+		/**
+		 * Returns all current forex quotes.
+		 *
+		 * @public
+		 * @returns {Array.<Object>}
+		 */
 		getForexQuotes() {
 			return this._forexQuotes;
 		}
 
+		/**
+		 * Updates the forex quote for a single currency pair; causing updates to
+		 * any grouping level that contains that requires translation.
+		 *
+		 * @public
+		 * @param {String} symbol
+		 * @param {Object} quote
+		 */
 		setForexQuote(symbol, quote) {
 			assert.argumentIsRequired(symbol, 'symbol', String);
 			assert.argumentIsRequired(quote, 'quote', Object);
@@ -279,10 +325,50 @@ module.exports = (() => {
 			Object.keys(this._trees).forEach(key => this._trees[key].walk(group => group.setForexRate(rate), true, false));
 		}
 
-		setPositionFundamentals(data) {
+		/**
+		 * Updates fundamental data for a single symbol.
+		 *
+		 * @public
+		 * @param {String} symbol
+		 * @param {Object} data
+		 */
+		setPositionFundamentalData(symbol, data) {
 			return;
 		}
 
+		/**
+		 * Indicates if a news article exists for a symbol.
+		 *
+		 * @public
+		 * @param {String} symbol
+		 * @param {Boolean} display
+		 * @param {Boolean} exists
+		 */
+		setNewsArticleExists(symbol, display, exists) {
+			assert.argumentIsRequired(symbol, 'symbol', String);
+			assert.argumentIsRequired(display, 'display', Boolean);
+			assert.argumentIsRequired(exists, 'exists', Boolean);
+
+			let map;
+
+			if (display) {
+				map = this._symbols;
+			} else {
+				map = this._symbolsDisplay;
+			}
+
+			if (map.hasOwnProperty(symbol)) {
+				map[symbol].forEach(item => item.setNewsArticleExists(exists));
+			}
+		}
+
+		/**
+		 * Returns a single level of grouping from one of the internal trees.
+		 *
+		 * @param {String} name
+		 * @param {Array.<String> keys
+		 * @returns {PositionGroup}
+		 */
 		getGroup(name, keys) {
 			assert.argumentIsRequired(name, 'name', String);
 			assert.argumentIsArray(keys, 'keys', Number);
@@ -290,6 +376,14 @@ module.exports = (() => {
 			return findNode(this._trees[name], keys).getValue();
 		}
 
+		/**
+		 * Returns all child groups from a level of grouping within one of
+		 * the internal trees.
+		 *
+		 * @param {String} name
+		 * @param {Array.<String> keys
+		 * @returns {Array.<PositionGroup>}
+		 */
 		getGroups(name, keys) {
 			assert.argumentIsRequired(name, 'name', String);
 			assert.argumentIsArray(keys, 'keys', Number);
@@ -301,8 +395,6 @@ module.exports = (() => {
 			assert.argumentIsRequired(name, 'name', String);
 			assert.argumentIsRequired(executor, 'executor', Function);
 
-			assert.argumentIsRequired(executor, 'executor', Function);
-
 			this._trees[name].walk(group => group.setSuspended(true), false, false);
 
 			executor(this);

package/lib/processing/PositionGroup.js

@@ -10,7 +10,17 @@ module.exports = (() => {
 	'use strict';
 
 	/**
+	 * A grouping of {@link PositionItem} instances. The group aggregates from across
+	 * all the positions and performs currency translation, as necessary.
+	 *
 	 * @public
+	 * @param {PositionContainer} container
+	 * @param {PositionGroup|null} parent
+	 * @param {Array.<PositionItem>} items
+	 * @param {Currency} currency
+	 * @param {String} key
+	 * @param {String} description
+	 * @param {Boolean=} single
 	 */
 	class PositionGroup {
 		constructor(container, parent, items, currency, key, description, single) {
@@ -30,15 +40,22 @@ module.exports = (() => {
 			this._suspended = false;
 
 			this._marketPercentChangeEvent = new Event(this);
+			this._excludedChangeEvent = new Event(this);
 
 			this._dataFormat = { };
 			this._dataActual = { };
 
 			this._dataFormat.key = this._key;
 			this._dataFormat.description = this._description;
-			this._dataFormat.c = this._currency.code;
-
+			this._dataFormat.newsExists = false;
 			this._dataFormat.quantity = null;
+			this._dataFormat.basisPrice = null;
+
+			this._dataActual.key = this._key;
+			this._dataActual.description = this._description;
+			this._dataActual.newsExists = false;
+			this._dataActual.quantity = null;
+			this._dataActual.basisPrice = null;
 
 			if (this._single) {
 				const item = items[0];
@@ -117,35 +134,85 @@ module.exports = (() => {
 
 					calculatePriceData(this, this._container.getForexQuotes(), sender, false);
 				});
+
+				if (this._single) {
+					item.registerNewsExistsChangeHandler((exists, sender) => {
+						this._dataFormat.newsExists = exists;
+						this._dataFormat.newsExists = exists;
+					});
+				}
 			});
 
 			this.refresh();
 		}
 
+		/**
+		 * The key of the group.
+		 *
+		 * @public
+		 * @returns {String}
+		 */
 		get key() {
 			return this._key;
 		}
 
+		/**
+		 * The description of the group.
+		 *
+		 * @public
+		 * @returns {String}
+		 */
 		get description() {
 			return this._description;
 		}
 
+		/**
+		 * The {@link Currency} which all aggregated data is presented in.
+		 *
+		 * @public
+		 * @returns {Currency}
+		 */
 		get currency() {
 			return this._currency;
 		}
 
+		/**
+		 * The {@link PositionItem} instances which for which aggregated data is compiled.
+		 *
+		 * @public
+		 * @returns {Currency}
+		 */
 		get items() {
 			return this._items;
 		}
 
+		/**
+		 * The string-based, human-readable aggregated data for the group.
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get data() {
 			return this._dataFormat;
 		}
 
+		/**
+		 * The raw aggregated data for the group (typically {@link Decimal} instances).
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get actual() {
 			return this._dataActual;
 		}
 
+		/**
+		 * Indicates if the group will only contain one {@link PositionItem} -- that is,
+		 * indicates if the group represents a single position.
+		 *
+		 * @public
+		 * @returns {Boolean}
+		 */
 		get single() {
 			return this._single;
 		}
@@ -154,10 +221,22 @@ module.exports = (() => {
 			return this._suspended;
 		}
 
+		/**
+		 * Indicates if the group should be excluded from higher-level aggregations.
+		 *
+		 * @public
+		 * @returns {Boolean}
+		 */
 		get excluded() {
 			return this._excluded;
 		}
 
+		/**
+		 * Causes aggregated data to be recalculated using a new exchange rate.
+		 *
+		 * @public
+		 * @param {Rate} rate
+		 */
 		setForexRate(rate) {
 			if (!this._bypassCurrencyTranslation) {
 				this.refresh();
@@ -168,11 +247,7 @@ module.exports = (() => {
 			assert.argumentIsRequired(value, 'value', Boolean);
 
 			if (this._excluded !== value) {
-				this._container.startTransaction(() => {
-					this._items.forEach((item) => {
-						item.setExcluded(value);
-					});
-				});
+				this._excludedChangeEvent(this._excluded = value);
 			}
 		}
 
@@ -186,6 +261,11 @@ module.exports = (() => {
 			}
 		}
 
+		/**
+		 * Causes all aggregated data to be recalculated.
+		 *
+		 * @public
+		 */
 		refresh() {
 			const rates = this._container.getForexQuotes();
 
@@ -193,6 +273,12 @@ module.exports = (() => {
 			calculatePriceData(this, rates, null, true);
 		}
 
+		/**
+		 * Causes the percent of the position, with respect to the parent container's
+		 * total, to be recalculated.
+		 *
+		 * @public
+		 */
 		refreshMarketPercent() {
 			calculateMarketPercent(this, this._container.getForexQuotes(), true);
 		}
@@ -246,7 +332,7 @@ module.exports = (() => {
 		
 		const items = group._items;
 
-		group._bypassCurrencyTranslation = items.some(item => item.currency !== currency);
+		group._bypassCurrencyTranslation = items.every(item => item.currency === currency);
 
 		const translate = (item, value) => {
 			let translated;
@@ -298,8 +384,11 @@ module.exports = (() => {
 		if (group.single) {
 			const item = group._items[0];
 
-			format.quantity = formatDecimal(item.position.snapshot.open, 2);
-			format.basisPrice = formatCurrency(item.data.basisPrice, currency);
+			actual.quantity = item.position.snapshot.open;
+			actual.basisPrice = item.data.basisPrice;
+
+			format.quantity = formatDecimal(actual.quantity, 2);
+			format.basisPrice = formatCurrency(actual.basisPrice, currency);
 		}
 	}
 

package/lib/processing/PositionItem.js

@@ -11,7 +11,15 @@ module.exports = (() => {
 	'use strict';
 
 	/**
+	 * A container for a single position, which handles quote changes and
+	 * notifies observers -- which are typically parent-level {@link PositionGroup}
+	 * instances.
+	 *
 	 * @public
+	 * @param {Object} portfolio
+	 * @param {Object} position
+	 * @param {Object} currentSummary
+	 * @param {Array.<Object>} previousSummaries
 	 */
 	class PositionItem {
 		constructor(portfolio, position, currentSummary, previousSummaries) {
@@ -27,10 +35,12 @@ module.exports = (() => {
 			this._data.basis = null;
 
 			this._currentQuote = null;
-			this._previousQuote = null;
+
+			this._currentPrice = null;
+			this._previousPrice = null;
 
 			this._data.currentPrice = null;
-			this._data.previousPrice = null;
+			this._data.currentPricePrevious = null;
 
 			this._data.market = null;
 			this._data.marketChange = null;
@@ -50,74 +60,141 @@ module.exports = (() => {
 			this._data.income = null;
 			this._data.basisPrice = null;
 
-			this._excluded = false;
+			this._data.newsExists = false;
 
 			calculateStaticData(this);
 			calculatePriceData(this, null);
 
 			this._quoteChangedEvent = new Event(this);
-			this._excludedChangeEvent = new Event(this);
+			this._newsExistsChangedEvent = new Event(this);
 		}
 
+		/**
+		 * The portfolio of the encapsulated position.
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get portfolio() {
 			return this._portfolio;
 		}
 
+		/**
+		 * The encapsulated position.
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get position() {
 			return this._position;
 		}
 
+		/**
+		 * The {@link Currency} of the encapsulated position.
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get currency() {
 			return this._currency;
 		}
 
+		/**
+		 * The year-to-date position summary of the encapsulated position.
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get currentSummary() {
 			return this._currentSummary;
 		}
-		
+
+		/**
+		 * Previous year's summaries for the encapsulated position.
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get previousSummaries() {
 			return this._previousSummaries;
 		}
 
+		/**
+		 * Various data regarding the encapsulated position.
+		 *
+		 * @public
+		 * @returns {*}
+		 */
 		get data() {
 			return this._data;
 		}
 
+		/**
+		 * The current quote for the symbol of the encapsulated position.
+		 *
+		 * @public
+		 * @returns {null|{Object}}
+		 */
 		get quote() {
 			return this._currentQuote;
 		}
 
-		get excluded() {
-			return this._excluded;
-		}
-
+		/**
+		 * Sets the current quote -- causing position-level data (e.g. market value) to
+		 * be recalculated.
+		 *
+		 * @public
+		 * @param {Object} quote
+		 */
 		setQuote(quote) {
 			assert.argumentIsRequired(quote, 'quote', Object);
 
-			if (this._previousQuote === null || this._previousQuote.lastPrice !== quote.lastPrice) {
+			if (this._currentPricePrevious !== quote.lastPrice) {
 				calculatePriceData(this, quote.lastPrice);
 
-				this._previousQuote = this._currentQuote;
+				this._currentPricePrevious = this._currentPrice;
+				this._currentPrice = quote.lastPrice;
+
 				this._currentQuote = quote;
 
 				this._quoteChangedEvent.fire(this._currentQuote);
 			}
 		}
 
-		setExcluded(value) {
+		/**
+		 * Sets a flag which indicates if news article(s) exist for the encapsulated position's
+		 * symbol.
+		 *
+		 * @public
+		 * @param {Boolean} value
+		 */
+		setNewsArticleExists(value) {
 			assert.argumentIsRequired(value, 'value', Boolean);
 
-			if (this._excluded !== value) {
-				this._excludedChangeEvent.fire(this._excluded = value);
+			if (this._data.newsExists !== value) {
+				this._newsExistsChangedEvent.fire(this._data.newsExists = value);
 			}
 		}
 
+		/**
+		 * Registers an observer for quote changes, which is fired after internal recalculations
+		 * of position data are complete.
+		 *
+		 * @public
+		 * @param {Function} handler
+		 */
 		registerQuoteChangeHandler(handler) {
 			this._quoteChangedEvent.register(handler);
 		}
 
-		registerExcludedChangeHandler(handler) {
-			this._excludedChangeEvent.register(handler);
+		/**
+		 * Registers an observer changes to the status of news existence.
+		 *
+		 * @public
+		 * @param {Function} handler
+		 */
+		registerNewsExistsChangeHandler(handler) {
+			this._newsExistsChangedEvent.register(handler);
 		}
 
 		toString() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barchart/portfolio-api-common",
-  "version": "1.0.128",
+  "version": "1.0.132",
   "description": "Common classes used by the Portfolio system",
   "author": {
     "name": "Bryan Ingle",

package/test/SpecRunner.js

@@ -738,11 +738,11 @@ module.exports = (() => {
 
 	/**
 	 * A container for positions which groups the positions into one or more
-	 * trees for aggregation and display purposes. For example, perhaps a positions
-	 * grouped first by asset class then by position is desired.
+	 * trees for aggregation and display purposes. For example, positions could be
+	 * grouped first by asset class then by position.
 	 *
 	 * Furthermore, the container performs aggregation (driven primarily by price
-	 * changes) for each level of grouping in the internal tree(s).
+	 * changes) for each level of grouping.
 	 *
 	 * @public
 	 * @param {Array.<PositionTreeDefinition>} definitions
@@ -824,6 +824,20 @@ module.exports = (() => {
 				return map;
 			}, { });
 
+			this._symbolsDisplay = this._items.reduce((map, item) => {
+				const symbol = extractSymbolForDisplay(item.position);
+
+				if (symbol) {
+					if (!map.hasOwnProperty(symbol)) {
+						map[symbol] = [ ];
+					}
+
+					map[symbol].push(item);
+				}
+
+				return map;
+			}, { });
+
 			this._currencies = this._items.reduce((map, item) => {
 				const position = item.position;
 
@@ -935,10 +949,14 @@ module.exports = (() => {
 			}, { });
 		}
 
-		get defaultCurrency() {
-			return this._defaultCurrency;
-		}
-		
+		/**
+		 * Returns a distinct list of all symbols used by the positions
+		 * within the container.
+		 *
+		 * @public
+		 * @param {Boolean} display - If true, all "display" symbols are returned; otherwise Barchart symbols are returned.
+		 * @returns {Array.<String>}
+		 */
 		getPositionSymbols(display) {
 			const symbols = this._items.reduce((symbols, item) => {
 				const position = item.position;
@@ -961,6 +979,14 @@ module.exports = (() => {
 			return array.unique(symbols);
 		}
 
+		/**
+		 * Updates the quote for a single symbol; causing updates to any grouping
+		 * level that contains the position(s) for the symbol.
+		 *
+		 * @public
+		 * @param {String} symbol
+		 * @param {Object} quote
+		 */
 		setPositionQuote(symbol, quote) {
 			assert.argumentIsRequired(symbol, 'symbol', String);
 			assert.argumentIsRequired(quote, 'quote', Object);
@@ -970,14 +996,34 @@ module.exports = (() => {
 			}
 		}
 
+		/**
+		 * Returns all forex symbols that are required to do currency translations.
+		 *
+		 * @public
+		 * @returns {Array.<String>}
+		 */
 		getForexSymbols() {
 			return this._forexSymbols;
 		}
 
+		/**
+		 * Returns all current forex quotes.
+		 *
+		 * @public
+		 * @returns {Array.<Object>}
+		 */
 		getForexQuotes() {
 			return this._forexQuotes;
 		}
 
+		/**
+		 * Updates the forex quote for a single currency pair; causing updates to
+		 * any grouping level that contains that requires translation.
+		 *
+		 * @public
+		 * @param {String} symbol
+		 * @param {Object} quote
+		 */
 		setForexQuote(symbol, quote) {
 			assert.argumentIsRequired(symbol, 'symbol', String);
 			assert.argumentIsRequired(quote, 'quote', Object);
@@ -995,10 +1041,50 @@ module.exports = (() => {
 			Object.keys(this._trees).forEach(key => this._trees[key].walk(group => group.setForexRate(rate), true, false));
 		}
 
-		setPositionFundamentals(data) {
+		/**
+		 * Updates fundamental data for a single symbol.
+		 *
+		 * @public
+		 * @param {String} symbol
+		 * @param {Object} data
+		 */
+		setPositionFundamentalData(symbol, data) {
 			return;
 		}
 
+		/**
+		 * Indicates if a news article exists for a symbol.
+		 *
+		 * @public
+		 * @param {String} symbol
+		 * @param {Boolean} display
+		 * @param {Boolean} exists
+		 */
+		setNewsArticleExists(symbol, display, exists) {
+			assert.argumentIsRequired(symbol, 'symbol', String);
+			assert.argumentIsRequired(display, 'display', Boolean);
+			assert.argumentIsRequired(exists, 'exists', Boolean);
+
+			let map;
+
+			if (display) {
+				map = this._symbols;
+			} else {
+				map = this._symbolsDisplay;
+			}
+
+			if (map.hasOwnProperty(symbol)) {
+				map[symbol].forEach(item => item.setNewsArticleExists(exists));
+			}
+		}
+
+		/**
+		 * Returns a single level of grouping from one of the internal trees.
+		 *
+		 * @param {String} name
+		 * @param {Array.<String> keys
+		 * @returns {PositionGroup}
+		 */
 		getGroup(name, keys) {
 			assert.argumentIsRequired(name, 'name', String);
 			assert.argumentIsArray(keys, 'keys', Number);
@@ -1006,6 +1092,14 @@ module.exports = (() => {
 			return findNode(this._trees[name], keys).getValue();
 		}
 
+		/**
+		 * Returns all child groups from a level of grouping within one of
+		 * the internal trees.
+		 *
+		 * @param {String} name
+		 * @param {Array.<String> keys
+		 * @returns {Array.<PositionGroup>}
+		 */
 		getGroups(name, keys) {
 			assert.argumentIsRequired(name, 'name', String);
 			assert.argumentIsArray(keys, 'keys', Number);
@@ -1017,8 +1111,6 @@ module.exports = (() => {
 			assert.argumentIsRequired(name, 'name', String);
 			assert.argumentIsRequired(executor, 'executor', Function);
 
-			assert.argumentIsRequired(executor, 'executor', Function);
-
 			this._trees[name].walk(group => group.setSuspended(true), false, false);
 
 			executor(this);
@@ -1072,7 +1164,17 @@ module.exports = (() => {
 	'use strict';
 
 	/**
+	 * A grouping of {@link PositionItem} instances. The group aggregates from across
+	 * all the positions and performs currency translation, as necessary.
+	 *
 	 * @public
+	 * @param {PositionContainer} container
+	 * @param {PositionGroup|null} parent
+	 * @param {Array.<PositionItem>} items
+	 * @param {Currency} currency
+	 * @param {String} key
+	 * @param {String} description
+	 * @param {Boolean=} single
 	 */
 	class PositionGroup {
 		constructor(container, parent, items, currency, key, description, single) {
@@ -1092,15 +1194,22 @@ module.exports = (() => {
 			this._suspended = false;
 
 			this._marketPercentChangeEvent = new Event(this);
+			this._excludedChangeEvent = new Event(this);
 
 			this._dataFormat = { };
 			this._dataActual = { };
 
 			this._dataFormat.key = this._key;
 			this._dataFormat.description = this._description;
-			this._dataFormat.c = this._currency.code;
-
+			this._dataFormat.newsExists = false;
 			this._dataFormat.quantity = null;
+			this._dataFormat.basisPrice = null;
+
+			this._dataActual.key = this._key;
+			this._dataActual.description = this._description;
+			this._dataActual.newsExists = false;
+			this._dataActual.quantity = null;
+			this._dataActual.basisPrice = null;
 
 			if (this._single) {
 				const item = items[0];
@@ -1179,35 +1288,85 @@ module.exports = (() => {
 
 					calculatePriceData(this, this._container.getForexQuotes(), sender, false);
 				});
+
+				if (this._single) {
+					item.registerNewsExistsChangeHandler((exists, sender) => {
+						this._dataFormat.newsExists = exists;
+						this._dataFormat.newsExists = exists;
+					});
+				}
 			});
 
 			this.refresh();
 		}
 
+		/**
+		 * The key of the group.
+		 *
+		 * @public
+		 * @returns {String}
+		 */
 		get key() {
 			return this._key;
 		}
 
+		/**
+		 * The description of the group.
+		 *
+		 * @public
+		 * @returns {String}
+		 */
 		get description() {
 			return this._description;
 		}
 
+		/**
+		 * The {@link Currency} which all aggregated data is presented in.
+		 *
+		 * @public
+		 * @returns {Currency}
+		 */
 		get currency() {
 			return this._currency;
 		}
 
+		/**
+		 * The {@link PositionItem} instances which for which aggregated data is compiled.
+		 *
+		 * @public
+		 * @returns {Currency}
+		 */
 		get items() {
 			return this._items;
 		}
 
+		/**
+		 * The string-based, human-readable aggregated data for the group.
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get data() {
 			return this._dataFormat;
 		}
 
+		/**
+		 * The raw aggregated data for the group (typically {@link Decimal} instances).
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get actual() {
 			return this._dataActual;
 		}
 
+		/**
+		 * Indicates if the group will only contain one {@link PositionItem} -- that is,
+		 * indicates if the group represents a single position.
+		 *
+		 * @public
+		 * @returns {Boolean}
+		 */
 		get single() {
 			return this._single;
 		}
@@ -1216,10 +1375,22 @@ module.exports = (() => {
 			return this._suspended;
 		}
 
+		/**
+		 * Indicates if the group should be excluded from higher-level aggregations.
+		 *
+		 * @public
+		 * @returns {Boolean}
+		 */
 		get excluded() {
 			return this._excluded;
 		}
 
+		/**
+		 * Causes aggregated data to be recalculated using a new exchange rate.
+		 *
+		 * @public
+		 * @param {Rate} rate
+		 */
 		setForexRate(rate) {
 			if (!this._bypassCurrencyTranslation) {
 				this.refresh();
@@ -1230,11 +1401,7 @@ module.exports = (() => {
 			assert.argumentIsRequired(value, 'value', Boolean);
 
 			if (this._excluded !== value) {
-				this._container.startTransaction(() => {
-					this._items.forEach((item) => {
-						item.setExcluded(value);
-					});
-				});
+				this._excludedChangeEvent(this._excluded = value);
 			}
 		}
 
@@ -1248,6 +1415,11 @@ module.exports = (() => {
 			}
 		}
 
+		/**
+		 * Causes all aggregated data to be recalculated.
+		 *
+		 * @public
+		 */
 		refresh() {
 			const rates = this._container.getForexQuotes();
 
@@ -1255,6 +1427,12 @@ module.exports = (() => {
 			calculatePriceData(this, rates, null, true);
 		}
 
+		/**
+		 * Causes the percent of the position, with respect to the parent container's
+		 * total, to be recalculated.
+		 *
+		 * @public
+		 */
 		refreshMarketPercent() {
 			calculateMarketPercent(this, this._container.getForexQuotes(), true);
 		}
@@ -1308,7 +1486,7 @@ module.exports = (() => {
 		
 		const items = group._items;
 
-		group._bypassCurrencyTranslation = items.some(item => item.currency !== currency);
+		group._bypassCurrencyTranslation = items.every(item => item.currency === currency);
 
 		const translate = (item, value) => {
 			let translated;
@@ -1360,8 +1538,11 @@ module.exports = (() => {
 		if (group.single) {
 			const item = group._items[0];
 
-			format.quantity = formatDecimal(item.position.snapshot.open, 2);
-			format.basisPrice = formatCurrency(item.data.basisPrice, currency);
+			actual.quantity = item.position.snapshot.open;
+			actual.basisPrice = item.data.basisPrice;
+
+			format.quantity = formatDecimal(actual.quantity, 2);
+			format.basisPrice = formatCurrency(actual.basisPrice, currency);
 		}
 	}
 
@@ -1535,7 +1716,15 @@ module.exports = (() => {
 	'use strict';
 
 	/**
+	 * A container for a single position, which handles quote changes and
+	 * notifies observers -- which are typically parent-level {@link PositionGroup}
+	 * instances.
+	 *
 	 * @public
+	 * @param {Object} portfolio
+	 * @param {Object} position
+	 * @param {Object} currentSummary
+	 * @param {Array.<Object>} previousSummaries
 	 */
 	class PositionItem {
 		constructor(portfolio, position, currentSummary, previousSummaries) {
@@ -1551,10 +1740,12 @@ module.exports = (() => {
 			this._data.basis = null;
 
 			this._currentQuote = null;
-			this._previousQuote = null;
+
+			this._currentPrice = null;
+			this._previousPrice = null;
 
 			this._data.currentPrice = null;
-			this._data.previousPrice = null;
+			this._data.currentPricePrevious = null;
 
 			this._data.market = null;
 			this._data.marketChange = null;
@@ -1574,74 +1765,141 @@ module.exports = (() => {
 			this._data.income = null;
 			this._data.basisPrice = null;
 
-			this._excluded = false;
+			this._data.newsExists = false;
 
 			calculateStaticData(this);
 			calculatePriceData(this, null);
 
 			this._quoteChangedEvent = new Event(this);
-			this._excludedChangeEvent = new Event(this);
+			this._newsExistsChangedEvent = new Event(this);
 		}
 
+		/**
+		 * The portfolio of the encapsulated position.
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get portfolio() {
 			return this._portfolio;
 		}
 
+		/**
+		 * The encapsulated position.
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get position() {
 			return this._position;
 		}
 
+		/**
+		 * The {@link Currency} of the encapsulated position.
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get currency() {
 			return this._currency;
 		}
 
+		/**
+		 * The year-to-date position summary of the encapsulated position.
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get currentSummary() {
 			return this._currentSummary;
 		}
-		
+
+		/**
+		 * Previous year's summaries for the encapsulated position.
+		 *
+		 * @public
+		 * @returns {Object}
+		 */
 		get previousSummaries() {
 			return this._previousSummaries;
 		}
 
+		/**
+		 * Various data regarding the encapsulated position.
+		 *
+		 * @public
+		 * @returns {*}
+		 */
 		get data() {
 			return this._data;
 		}
 
+		/**
+		 * The current quote for the symbol of the encapsulated position.
+		 *
+		 * @public
+		 * @returns {null|{Object}}
+		 */
 		get quote() {
 			return this._currentQuote;
 		}
 
-		get excluded() {
-			return this._excluded;
-		}
-
+		/**
+		 * Sets the current quote -- causing position-level data (e.g. market value) to
+		 * be recalculated.
+		 *
+		 * @public
+		 * @param {Object} quote
+		 */
 		setQuote(quote) {
 			assert.argumentIsRequired(quote, 'quote', Object);
 
-			if (this._previousQuote === null || this._previousQuote.lastPrice !== quote.lastPrice) {
+			if (this._currentPricePrevious !== quote.lastPrice) {
 				calculatePriceData(this, quote.lastPrice);
 
-				this._previousQuote = this._currentQuote;
+				this._currentPricePrevious = this._currentPrice;
+				this._currentPrice = quote.lastPrice;
+
 				this._currentQuote = quote;
 
 				this._quoteChangedEvent.fire(this._currentQuote);
 			}
 		}
 
-		setExcluded(value) {
+		/**
+		 * Sets a flag which indicates if news article(s) exist for the encapsulated position's
+		 * symbol.
+		 *
+		 * @public
+		 * @param {Boolean} value
+		 */
+		setNewsArticleExists(value) {
 			assert.argumentIsRequired(value, 'value', Boolean);
 
-			if (this._excluded !== value) {
-				this._excludedChangeEvent.fire(this._excluded = value);
+			if (this._data.newsExists !== value) {
+				this._newsExistsChangedEvent.fire(this._data.newsExists = value);
 			}
 		}
 
+		/**
+		 * Registers an observer for quote changes, which is fired after internal recalculations
+		 * of position data are complete.
+		 *
+		 * @public
+		 * @param {Function} handler
+		 */
 		registerQuoteChangeHandler(handler) {
 			this._quoteChangedEvent.register(handler);
 		}
 
-		registerExcludedChangeHandler(handler) {
-			this._excludedChangeEvent.register(handler);
+		/**
+		 * Registers an observer changes to the status of news existence.
+		 *
+		 * @public
+		 * @param {Function} handler
+		 */
+		registerNewsExistsChangeHandler(handler) {
+			this._newsExistsChangedEvent.register(handler);
 		}
 
 		toString() {