@barchart/portfolio-api-common 1.0.130 → 1.0.134

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,19 +325,55 @@ module.exports = (() => {
 			Object.keys(this._trees).forEach(key => this._trees[key].walk(group => group.setForexRate(rate), true, false));
 		}
 
-		setPositionFundamentals(symbol, data) {
-			return;
+		/**
+		 * Updates fundamental data for a single symbol.
+		 *
+		 * @public
+		 * @param {String} symbol
+		 * @param {Object} data
+		 */
+		setPositionFundamentalData(symbol, data) {
+			assert.argumentIsRequired(symbol, 'symbol', String);
+			assert.argumentIsRequired(data, 'data', Object);
+
+			if (this._symbols.hasOwnProperty(symbol)) {
+				this._symbols[symbol].forEach(item => item.setPositionFundamentalData(data));
+			}
 		}
 
-		setNewsArticleExists(symbol, exists) {
+		/**
+		 * 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);
 
-			if (this._symbols.hasOwnProperty(symbol)) {
-				this._symbols[symbol].forEach(item => item.setNewsArticleExists(exists));
+			let map;
+
+			if (display) {
+				map = this._symbolsDisplay;
+			} else {
+				map = this._symbols;
+			}
+
+			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);
@@ -299,6 +381,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);
@@ -310,8 +400,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,6 +40,7 @@ module.exports = (() => {
 			this._suspended = false;
 
 			this._marketPercentChangeEvent = new Event(this);
+			this._excludedChangeEvent = new Event(this);
 
 			this._dataFormat = { };
 			this._dataActual = { };
@@ -52,10 +63,12 @@ module.exports = (() => {
 				this._dataFormat.portfolio = item.portfolio.portfolio;
 				this._dataFormat.position = item.position.position;
 				this._dataFormat.instrument = item.position.instrument;
+				this._dataFormat.fundamental = item.fundamental || { };
 			} else {
 				this._dataFormat.portfolio = null;
 				this._dataFormat.position = null;
 				this._dataFormat.instrument = null;
+				this._dataFormat.fundamental = { };
 			}
 
 			this._dataFormat.quoteLast = null;
@@ -126,8 +139,12 @@ module.exports = (() => {
 
 				if (this._single) {
 					item.registerNewsExistsChangeHandler((exists, sender) => {
+						this._dataActual.newsExists = exists;
 						this._dataFormat.newsExists = exists;
-						this._dataFormat.newsExists = exists;
+					});
+
+					item._fundamentalDataChangeEvent((data, sender) => {
+						this._dataFormat.fundamental = data;
 					});
 				}
 			});
@@ -135,30 +152,73 @@ module.exports = (() => {
 			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;
 		}
@@ -167,10 +227,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();
@@ -181,11 +253,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);
 			}
 		}
 
@@ -199,6 +267,11 @@ module.exports = (() => {
 			}
 		}
 
+		/**
+		 * Causes all aggregated data to be recalculated.
+		 *
+		 * @public
+		 */
 		refresh() {
 			const rates = this._container.getForexQuotes();
 
@@ -206,6 +279,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);
 		}

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;
@@ -40,7 +50,7 @@ module.exports = (() => {
 
 			this._data.unrealized = null;
 			this._data.unrealizedChange = null;
-			
+
 			this._data.summaryTotalCurrent = null;
 			this._data.summaryTotalCurrentChange = null;
 
@@ -51,70 +61,127 @@ module.exports = (() => {
 			this._data.basisPrice = null;
 
 			this._data.newsExists = false;
-
-			this._excluded = false;
+			this._data.fundamental = { };
 
 			calculateStaticData(this);
 			calculatePriceData(this, null);
 
 			this._quoteChangedEvent = new Event(this);
-			this._excludedChangeEvent = new Event(this);
 			this._newsExistsChangedEvent = new Event(this);
+			this._fundamentalDataChangeEvent = 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) {
-			assert.argumentIsRequired(value, 'value', Boolean);
+		/**
+		 * Sets fundamental data for the position.
+		 *
+		 * @public
+		 * @param {Object} data
+		 */
+		setPositionFundamentalData(data) {
+			assert.argumentIsRequired(data, 'data', Object);
 
-			if (this._excluded !== value) {
-				this._excludedChangeEvent.fire(this._excluded = value);
-			}
+			this._fundamentalDataChangeEvent(this._data.fundamental = data);
 		}
 
+		/**
+		 * 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);
 
@@ -123,14 +190,33 @@ module.exports = (() => {
 			}
 		}
 
+		/**
+		 * 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 for fundamental data changes.
+		 *
+		 * @public
+		 * @param {Function} handler
+		 */
+		registerFundamentalDataChangeHandler(handler) {
+			this._fundamentalDataChangeEvent.register(handler);
 		}
 
+		/**
+		 * Registers an observer changes to the status of news existence.
+		 *
+		 * @public
+		 * @param {Function} handler
+		 */
 		registerNewsExistsChangeHandler(handler) {
 			this._newsExistsChangedEvent.register(handler);
 		}
@@ -259,10 +345,10 @@ module.exports = (() => {
 			data.unrealizedChange = Decimal.ZERO;
 		}
 	}
-	
+
 	function calculateSummaryTotal(summary) {
 		let returnRef;
-		
+
 		if (summary) {
 			const period = summary.period;
 
@@ -270,7 +356,7 @@ module.exports = (() => {
 		} else {
 			returnRef = Decimal.ZERO;
 		}
-		
+
 		return returnRef;
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barchart/portfolio-api-common",
-  "version": "1.0.130",
+  "version": "1.0.134",
   "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,19 +1041,55 @@ module.exports = (() => {
 			Object.keys(this._trees).forEach(key => this._trees[key].walk(group => group.setForexRate(rate), true, false));
 		}
 
-		setPositionFundamentals(symbol, data) {
-			return;
+		/**
+		 * Updates fundamental data for a single symbol.
+		 *
+		 * @public
+		 * @param {String} symbol
+		 * @param {Object} data
+		 */
+		setPositionFundamentalData(symbol, data) {
+			assert.argumentIsRequired(symbol, 'symbol', String);
+			assert.argumentIsRequired(data, 'data', Object);
+
+			if (this._symbols.hasOwnProperty(symbol)) {
+				this._symbols[symbol].forEach(item => item.setPositionFundamentalData(data));
+			}
 		}
 
-		setNewsArticleExists(symbol, exists) {
+		/**
+		 * 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);
 
-			if (this._symbols.hasOwnProperty(symbol)) {
-				this._symbols[symbol].forEach(item => item.setNewsArticleExists(exists));
+			let map;
+
+			if (display) {
+				map = this._symbolsDisplay;
+			} else {
+				map = this._symbols;
+			}
+
+			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);
@@ -1015,6 +1097,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);
@@ -1026,8 +1116,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);
@@ -1081,7 +1169,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) {
@@ -1101,6 +1199,7 @@ module.exports = (() => {
 			this._suspended = false;
 
 			this._marketPercentChangeEvent = new Event(this);
+			this._excludedChangeEvent = new Event(this);
 
 			this._dataFormat = { };
 			this._dataActual = { };
@@ -1123,10 +1222,12 @@ module.exports = (() => {
 				this._dataFormat.portfolio = item.portfolio.portfolio;
 				this._dataFormat.position = item.position.position;
 				this._dataFormat.instrument = item.position.instrument;
+				this._dataFormat.fundamental = item.fundamental || { };
 			} else {
 				this._dataFormat.portfolio = null;
 				this._dataFormat.position = null;
 				this._dataFormat.instrument = null;
+				this._dataFormat.fundamental = { };
 			}
 
 			this._dataFormat.quoteLast = null;
@@ -1197,8 +1298,12 @@ module.exports = (() => {
 
 				if (this._single) {
 					item.registerNewsExistsChangeHandler((exists, sender) => {
+						this._dataActual.newsExists = exists;
 						this._dataFormat.newsExists = exists;
-						this._dataFormat.newsExists = exists;
+					});
+
+					item._fundamentalDataChangeEvent((data, sender) => {
+						this._dataFormat.fundamental = data;
 					});
 				}
 			});
@@ -1206,30 +1311,73 @@ module.exports = (() => {
 			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;
 		}
@@ -1238,10 +1386,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();
@@ -1252,11 +1412,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);
 			}
 		}
 
@@ -1270,6 +1426,11 @@ module.exports = (() => {
 			}
 		}
 
+		/**
+		 * Causes all aggregated data to be recalculated.
+		 *
+		 * @public
+		 */
 		refresh() {
 			const rates = this._container.getForexQuotes();
 
@@ -1277,6 +1438,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);
 		}
@@ -1560,7 +1727,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) {
@@ -1576,10 +1751,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;
@@ -1589,7 +1766,7 @@ module.exports = (() => {
 
 			this._data.unrealized = null;
 			this._data.unrealizedChange = null;
-			
+
 			this._data.summaryTotalCurrent = null;
 			this._data.summaryTotalCurrentChange = null;
 
@@ -1600,70 +1777,127 @@ module.exports = (() => {
 			this._data.basisPrice = null;
 
 			this._data.newsExists = false;
-
-			this._excluded = false;
+			this._data.fundamental = { };
 
 			calculateStaticData(this);
 			calculatePriceData(this, null);
 
 			this._quoteChangedEvent = new Event(this);
-			this._excludedChangeEvent = new Event(this);
 			this._newsExistsChangedEvent = new Event(this);
+			this._fundamentalDataChangeEvent = 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) {
-			assert.argumentIsRequired(value, 'value', Boolean);
+		/**
+		 * Sets fundamental data for the position.
+		 *
+		 * @public
+		 * @param {Object} data
+		 */
+		setPositionFundamentalData(data) {
+			assert.argumentIsRequired(data, 'data', Object);
 
-			if (this._excluded !== value) {
-				this._excludedChangeEvent.fire(this._excluded = value);
-			}
+			this._fundamentalDataChangeEvent(this._data.fundamental = data);
 		}
 
+		/**
+		 * 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);
 
@@ -1672,14 +1906,33 @@ module.exports = (() => {
 			}
 		}
 
+		/**
+		 * 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 for fundamental data changes.
+		 *
+		 * @public
+		 * @param {Function} handler
+		 */
+		registerFundamentalDataChangeHandler(handler) {
+			this._fundamentalDataChangeEvent.register(handler);
 		}
 
+		/**
+		 * Registers an observer changes to the status of news existence.
+		 *
+		 * @public
+		 * @param {Function} handler
+		 */
 		registerNewsExistsChangeHandler(handler) {
 			this._newsExistsChangedEvent.register(handler);
 		}
@@ -1808,10 +2061,10 @@ module.exports = (() => {
 			data.unrealizedChange = Decimal.ZERO;
 		}
 	}
-	
+
 	function calculateSummaryTotal(summary) {
 		let returnRef;
-		
+
 		if (summary) {
 			const period = summary.period;
 
@@ -1819,7 +2072,7 @@ module.exports = (() => {
 		} else {
 			returnRef = Decimal.ZERO;
 		}
-		
+
 		return returnRef;
 	}