@barchart/portfolio-api-common 1.0.96 → 1.0.100

package/lib/formatters/TransactionFormatter.js

@@ -8,7 +8,7 @@ module.exports = (() => {
 	'use strict';
 
 	/**
-	 * Static configuration data.
+	 * Static utility for formatting transaction data in human-readable form.
 	 *
 	 * @public
 	 */
@@ -18,54 +18,66 @@ module.exports = (() => {
 		}
 
 		/**
-		 * Formats transactions by adding "formatted" attribute
-		 * and "instrument" attribute from position
+		 * Maps transaction objects into new objects whose properties are human-readable or,
+		 * optionally returns the original objects with a "formatted" property appended to
+		 * each transaction.
 		 *
 		 * @public
 		 * @static
-		 * @param {Array} transactions
-		 * @param {Array} positions
-		 * @param {String} returnType - Whether the return values should be appended to the transaction
-		 * 	
+		 * @param {Array<Object>} transactions
+		 * @param {Array<Object>} positions
+		 * @param {Boolean=} append
 		 * @returns {Array}
 		 */
-		static format(transactions, positions, returnType) {
-			assert.argumentIsRequired(transactions, 'transactions', Array);
-			assert.argumentIsRequired(positions, 'positions', Array);
+		static format(transactions, positions, append) {
+			assert.argumentIsArray(transactions, 'transactions');
+			assert.argumentIsArray(positions, 'positions');
+			assert.argumentIsOptional(append, 'append', Boolean);
 
-			const positionMap = {};
+			const instruments = positions.reduce((map, p) => {
+				map[p.position] = p.instrument;
 
-			positions.map(p => positionMap[p.position] = p.instrument);
+				return map;
+			}, { });
 
-			return transactions.filter(t => positionMap[t.position]).map((transaction) => {
-				transaction.instrument = positionMap[transaction.position];
+			return transactions.reduce((list, transaction) => {
+				const position = transaction.position;
 
-				let formatted = getBasicTransaction(transaction);
+				if (instruments.hasOwnProperty(position)) {
+					transaction.instrument = instruments[position];
 
-				if (formatters.has(transaction.type)) {
-					const formatterFunction = formatters.get(transaction.type);
+					let formatted = getBasicTransaction(transaction);
 
-					const formattedTransaction = formatterFunction(transaction);
+					if (formatters.has(transaction.type)) {
+						const formatterFunction = formatters.get(transaction.type);
+						const formattedTransaction = formatterFunction(transaction);
 
-					Object.keys(formattedTransaction).map((key) => {
-						if (!is.undefined(formattedTransaction[key]) && is.fn(formattedTransaction[key].toFloat)) {
-							const precision = transaction.instrument.currency.precision;
+						Object.keys(formattedTransaction).map((key) => {
+							if (!is.undefined(formattedTransaction[key]) && is.fn(formattedTransaction[key].toFloat)) {
+								const precision = transaction.instrument.currency.precision;
 
-							formattedTransaction[key] = formatter.numberToString(formattedTransaction[key].toFloat(), precision, ',');
-						}
-					});
+								formattedTransaction[key] = formatter.numberToString(formattedTransaction[key].toFloat(), precision, ',');
+							}
+						});
 
-					formatted = Object.assign({}, formatted, formattedTransaction);
-				}
+						formatted = Object.assign({}, formatted, formattedTransaction);
+					}
+
+					let transactionToInsert;
 
-				if (returnType === 'append') {
-					transaction.formatted = formatted;
+					if (append) {
+						transaction.formatted = formatted;
 
-					return transaction;
-				} else {
-					return formatted;
+						transactionToInsert = transaction;
+					} else {
+						transactionToInsert = formatted;
+					}
+
+					list.push(transactionToInsert);
 				}
-			});
+
+				return list;
+			}, [ ]);
 		}
 
 		toString() {

package/lib/processing/PositionContainer.js

@@ -1,13 +1,16 @@
 const array = require('@barchart/common-js/lang/array'),
+	assert = require('@barchart/common-js/lang/assert'),
 	ComparatorBuilder = require('@barchart/common-js/collections/sorting/ComparatorBuilder'),
 	comparators = require('@barchart/common-js/collections/sorting/comparators'),
 	Currency = require('@barchart/common-js/lang/Currency'),
-	assert = require('@barchart/common-js/lang/assert'),
 	is = require('@barchart/common-js/lang/is'),
 	Tree = require('@barchart/common-js/collections/Tree');
 
 const PositionSummaryFrame = require('./../data/PositionSummaryFrame');
 
+const PositionLevelDefinition = require('./definitions/PositionLevelDefinition'),
+	PositionTreeDefinition = require('./definitions/PositionTreeDefinition');
+
 const PositionGroup = require('./PositionGroup'),
 	PositionItem = require('./PositionItem');
 
@@ -15,22 +18,32 @@ module.exports = (() => {
 	'use strict';
 
 	/**
+	 * 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.
+	 *
+	 * Furthermore, the container performs aggregation (driven primarily by price
+	 * changes) for each level of grouping in the internal tree(s).
+	 *
 	 * @public
+	 * @param {Array.<PositionTreeDefinition>} definitions
+	 * @param {Array.<Object>} portfolios
+	 * @param {Array.<Object>} positions
+	 * @param {Array.<Object>} summaries
 	 */
 	class PositionContainer {
-		constructor(portfolios, positions, summaries, definitions, defaultCurrency, summaryFrame) {
-			this._definitions = definitions;
-			this._defaultCurrency = defaultCurrency || Currency.CAD;
+		constructor(definitions, portfolios, positions, summaries) {
+			assert.argumentIsArray(definitions, 'definitions', PositionTreeDefinition, 'PositionTreeDefinition');
+			assert.argumentIsArray(portfolios, 'portfolios');
+			assert.argumentIsArray(positions, 'positions');
+			assert.argumentIsArray(summaries, 'summaries');
 			
-			const previousSummaryFrame = summaryFrame || PositionSummaryFrame.YEARLY;
+			const previousSummaryFrame = PositionSummaryFrame.YEARLY;
 			const previousSummaryRanges = previousSummaryFrame.getRecentRanges(0);
 
 			const currentSummaryFrame = PositionSummaryFrame.YTD;
 			const currentSummaryRange = array.last(currentSummaryFrame.getRecentRanges(0));
 
-			this._summaryDescriptionCurrent = previousSummaryFrame.describeRange(array.last(previousSummaryRanges));
-			this._summaryDescriptionPrevious = currentSummaryFrame.describeRange(currentSummaryRange);
-
 			this._portfolios = portfolios.reduce((map, portfolio) => {
 				map[portfolio.portfolio] = portfolio;
 
@@ -109,111 +122,107 @@ module.exports = (() => {
 
 				return map;
 			}, { });
+			
+			this._trees = definitions.reduce((map, treeDefinition) => {
+				const tree = new Tree();
 
-			this._tree = new Tree();
-
-			const createGroups = (tree, items, definitions) => {
-				if (definitions.length === 0) {
-					return;
-				}
-
-				const parent = tree.getValue() || null;
-
-				const currentDefinition = definitions[0];
-				const additionalDefinitions = array.dropLeft(definitions);
-
-				const populatedObjects = array.groupBy(items, currentDefinition.keySelector);
-				const populatedGroups = Object.keys(populatedObjects).map(key => populatedObjects[key]).map((items) => {
-					const first = items[0];
+				const createGroups = (currentTree, items, levelDefinitions) => {
+					if (levelDefinitions.length === 0) {
+						return;
+					}
 
-					return new PositionGroup(this, parent, items, currentDefinition.currencySelector(first), currentDefinition.descriptionSelector(first), currentDefinition.single && items.length === 1);
-				});
+					const parent = currentTree.getValue() || null;
 
-				const missingGroups = array.difference(currentDefinition.requiredGroups.map(group => group.description), populatedGroups.map(group => group.description));
+					const levelDefinition = levelDefinitions[0];
 
-				const empty = missingGroups.map((description) => {
-					return new PositionGroup(this, parent, [ ], currentDefinition.requiredGroups.find(group => group.description === description).currency, description);
-				});
+					const populatedObjects = array.groupBy(items, levelDefinition.keySelector);
+					const populatedGroups = Object.keys(populatedObjects).reduce((list, key) => {
+						const items = populatedObjects[key];
+						const first = items[0];
 
-				const compositeGroups = populatedGroups.concat(empty);
+						list.push(new PositionGroup(this, parent, items, levelDefinition.currencySelector(first), key, levelDefinition.descriptionSelector(first), levelDefinition.single && items.length === 1));
 
-				let builder;
+						return list;
+					}, [ ]);
 
-				if (currentDefinition.requiredGroups.length !== 0) {
-					const ordering = currentDefinition.requiredGroups.reduce((map, group, index) => {
-						map[group.description] = index;
+					const missingGroups = array.difference(levelDefinition.requiredGroups.map(group => group.key), populatedGroups.map(group => group.key))
+						.map((key) => {
+							return levelDefinition.requiredGroups.find(g => g.key === key);
+						});
 
-						return map;
-					}, { });
+					const empty = missingGroups.map((group) => {
+						return new PositionGroup(this, parent, [ ], group.currency, group.key, group.description);
+					});
 
-					const getIndex = (description) => {
-						if (ordering.hasOwnProperty(description)) {
-							return ordering[description];
-						} else {
-							return Number.MAX_VALUE;
-						}
-					};
+					const compositeGroups = populatedGroups.concat(empty);
+
+					let builder;
+
+					if (levelDefinition.requiredGroups.length !== 0) {
+						const ordering = levelDefinition.requiredGroups.reduce((map, group, index) => {
+							map[group.description] = index;
+
+							return map;
+						}, { });
+
+						const getIndex = (description) => {
+							if (ordering.hasOwnProperty(description)) {
+								return ordering[description];
+							} else {
+								return Number.MAX_VALUE;
+							}
+						};
+
+						builder = ComparatorBuilder.startWith((a, b) => {
+							return comparators.compareNumbers(getIndex(a.description), getIndex(b.description));
+						}).thenBy((a, b) => {
+							return comparators.compareStrings(a.description, b.description);
+						});
+					} else {
+						builder = ComparatorBuilder.startWith((a, b) => {
+							return comparators.compareStrings(a.description, b.description);
+						});
+					}
 
-					builder = ComparatorBuilder.startWith((a, b) => {
-						return comparators.compareNumbers(getIndex(a.description), getIndex(b.description));
-					}).thenBy((a, b) => {
-						return comparators.compareStrings(a.description, b.description);
-					});
-				} else {
-					builder = ComparatorBuilder.startWith((a, b) => {
-						return comparators.compareStrings(a.description, b.description);
-					});
-				}
+					compositeGroups.sort(builder.toComparator());
 
-				compositeGroups.sort(builder.toComparator());
+					compositeGroups.forEach((group) => {
+						const childTree = currentTree.addChild(group);
 
-				compositeGroups.forEach((group) => {
-					const child = tree.addChild(group);
+						group.registerMarketPercentChangeHandler(() => {
+							currentTree.walk((childGroup) => childGroup.refreshMarketPercent());
+						});
 
-					group.registerMarketPercentChangeHandler(() => {
-						this._tree.walk((childGroup) => childGroup.refreshMarketPercent());
+						createGroups(childTree, group.items, array.dropLeft(levelDefinitions));
 					});
+				};
 
-					createGroups(child, group.items, additionalDefinitions);
-				});
-			};
+				createGroups(tree, this._items, treeDefinition.definitions);
+				
+				map[treeDefinition.name] = tree;
 
-			createGroups(this._tree, this._items, this._definitions);
+				return map;
+			}, { });
 		}
 
 		get defaultCurrency() {
 			return this._defaultCurrency;
 		}
 		
-		getCurrentSummaryDescription() {
-			return this._summaryDescriptionCurrent;
-		}
-		
-		getPreviousSummaryDescription() {
-			return this._summaryDescriptionPrevious;
-		}
-
-		startTransaction(executor) {
-			assert.argumentIsRequired(executor, 'executor', Function);
-
-			this._tree.walk(group => group.setSuspended(true), false, false);
-
-			executor(this);
-
-			this._tree.walk(group => group.setSuspended(false), false, false);
-		}
-		
-		getSymbols() {
+		getPositionSymbols() {
 			return Object.keys(this._symbols);
 		}
 
-		setPrice(symbol, price) {
-			if (this._symbols.hasOwnProperty(symbol)) {
+		setPositionPrice(symbol, price) {
+			assert.argumentIsOptional(symbol, 'symbol', String);
+			assert.argumentIsOptional(price, 'price', Number);
+
+			if (this._symbols.hasOwnProperty(symbol) && is.number(price)) {
 				this._symbols[symbol].forEach(item => item.setPrice(price));
 			}
 		}
 
-		getCurrencySymbols() {
+		getForexSymbols() {
 			const codes = Object.keys(this._currencies);
 
 			return codes.reduce((symbols, code) => {
@@ -225,28 +234,38 @@ module.exports = (() => {
 			}, [ ]);
 		}
 
-		setExchangeRate(symbol, price) {
+		setForexPrice(symbol, price) {
+			assert.argumentIsOptional(symbol, 'symbol', String);
+			assert.argumentIsOptional(price, 'price', Number);
 
+			return;
 		}
 
-		getGroup(keys) {
-			const node = keys.reduce((tree, key) => {
-				tree = tree.findChild(group => group.description === key);
+		getGroup(name, keys) {
+			assert.argumentIsRequired(name, 'name', String);
+			assert.argumentIsArray(keys, 'keys', Number);
 
-				return tree;
-			}, this._tree);
+			return findNode(this._trees[name], keys).getValue();
+		}
+
+		getGroups(name, keys) {
+			assert.argumentIsRequired(name, 'name', String);
+			assert.argumentIsArray(keys, 'keys', Number);
 
-			return node.getValue();
+			return findNode(this._trees[name], keys).getChildren().map(node => node.getValue());
 		}
 
-		getGroups(keys) {
-			const node = keys.reduce((tree, key) => {
-				tree = tree.findChild(group => group.description === key);
+		startTransaction(name, executor) {
+			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);
 
-				return tree;
-			}, this._tree);
+			executor(this);
 
-			return node.getChildren().map((node) => node.getValue());
+			this._trees[name].walk(group => group.setSuspended(false), false, false);
 		}
 
 		toString() {
@@ -254,6 +273,14 @@ module.exports = (() => {
 		}
 	}
 
+	function findNode(tree, keys) {
+		return keys.reduce((tree, key) => {
+			tree = tree.findChild(group => group.description === key);
+
+			return tree;
+		}, tree);
+	}
+
 	function getSummaryArray(ranges) {
 		return ranges.map(range => null);
 	}

package/lib/processing/PositionGroup.js

@@ -12,13 +12,14 @@ module.exports = (() => {
 	 * @public
 	 */
 	class PositionGroup {
-		constructor(container, parent, items, currency, description, single) {
+		constructor(container, parent, items, currency, key, description, single) {
 			this._container = container;
 			this._parent = parent || null;
 
 			this._items = items;
-			this._currency = currency;
+			this._currency = currency || Currency.CAD;
 
+			this._key = key;
 			this._description = description;
 
 			this._single = is.boolean(single) && single;
@@ -30,9 +31,10 @@ module.exports = (() => {
 
 			this._dataFormat = { };
 			this._dataActual = { };
-			
+
+			this._dataFormat.key = this._key;
 			this._dataFormat.description = this._description;
-			
+
 			this._dataActual.currentPrice = null;
 			this._dataActual.previousPrice = null;
 			this._dataActual.basis = null;
@@ -66,7 +68,7 @@ module.exports = (() => {
 				item.registerPriceChangeHandler((data, sender) => {
 					if (this._single) {
 						this._dataActual.currentPrice = data.currentPrice;
-						this._dataFormat.currentPrice = format(data.currentPrice, sender.position.instrument.currency);
+						this._dataFormat.currentPrice = formatCurrency(data.currentPrice, sender.position.instrument.currency);
 					} else {
 						this._dataActual.currentPrice = null;
 						this._dataFormat.currentPrice = null;
@@ -79,16 +81,20 @@ module.exports = (() => {
 			this.refresh();
 		}
 
-		get items() {
-			return this._items;
+		get key() {
+			return this._key;
+		}
+
+		get description() {
+			return this._description;
 		}
 
 		get currency() {
 			return this._currency;
 		}
 
-		get description() {
-			return this._description;
+		get items() {
+			return this._items;
 		}
 
 		get data() {

package/lib/processing/definitions/PositionLevelDefinition.js

@@ -0,0 +1,154 @@
+const assert = require('@barchart/common-js/lang/assert'),
+	is = require('@barchart/common-js/lang/is');
+
+module.exports = (() => {
+	'use strict';
+
+	/**
+	 * Defines a grouping level within a tree of positions. A level could represent a
+	 * group of multiple positions (e.g. all equities or all positions for a portfolio).
+	 * Alternately, a level could also represent a single position.
+	 *
+	 * @public
+	 * @param {String} name
+	 * @param {PositionLevelDefinition~keySelector} keySelector
+	 * @param {PositionLevelDefinition~descriptionSelector} descriptionSelector
+	 * @param {PositionLevelDefinition~currencySelector} currencySelector
+	 * @param {Array.<PositionLevelDefinition~RequiredGroup>=} requiredGroups
+	 * @param {Boolean=} single
+	 */
+	class PositionLevelDefinition {
+		constructor(name, keySelector, descriptionSelector, currencySelector, requiredGroups, single) {
+			assert.argumentIsRequired(name, 'name', String);
+			assert.argumentIsRequired(keySelector, 'keySelector', Function);
+			assert.argumentIsRequired(descriptionSelector, 'descriptionSelector', Function);
+			assert.argumentIsRequired(currencySelector, 'currencySelector', Function);
+
+			if (requiredGroups) {
+				assert.argumentIsArray(requiredGroups, 'requiredGroups', String);
+			}
+
+			assert.argumentIsOptional(single, 'single', Boolean);
+
+			this._name = name;
+
+			this._keySelector = keySelector;
+			this._descriptionSelector = descriptionSelector;
+			this._currencySelector = currencySelector;
+
+			this._requiredGroups = requiredGroups || [ ];
+			this._single = is.boolean(single) && single;
+		}
+
+		/**
+		 * The name of the grouping level.
+		 *
+		 * @public
+		 * @returns {String}
+		 */
+		get name() {
+			return this._name;
+		}
+
+		/**
+		 * A function, when given a {@link PositionItem} returns a string that is used
+		 * to group {@link PositionItem} instances into different groups.
+		 *
+		 * @public
+		 * @returns {PositionLevelDefinition~keySelector}
+		 */
+		get keySelector() {
+			return this._keySelector;
+		}
+
+		/**
+		 * A function, when given a {@link PositionItem} returns a string used to describe the
+		 * group.
+		 *
+		 * @public
+		 * @returns {PositionLevelDefinition~descriptionSelector}
+		 */
+		get descriptionSelector() {
+			return this._descriptionSelector;
+		}
+
+		/**
+		 * A function, when given a {@link PositionItem} returns the {@link Currency} used to
+		 * display values for the group.
+		 *
+		 * @public
+		 * @returns {PositionLevelDefinition~currencySelector}
+		 */
+		get currencySelector() {
+			return this._currencySelector;
+		}
+
+		/**
+		 * Indicates the required groups (i.e. descriptions). The allows for the creation of empty
+		 * groups.
+		 *
+		 * @public
+		 * @returns {Array<String>}
+		 */
+		get requiredGroups() {
+			return this._requiredGroups;
+		}
+
+		/**
+		 * Indicates if the grouping level is meant to only contain a single item.
+		 *
+		 * @public
+		 * @returns {Boolean}
+		 */
+		get single() {
+			return this._single;
+		}
+
+		toString() {
+			return '[PositionLevelDefinition]';
+		}
+	}
+
+	/**
+	 * A callback used to determine the eligibility for membership of a {@link PositionItem}
+	 * within a group.
+	 *
+	 * @public
+	 * @callback PositionLevelDefinition~keySelector
+	 * @param {PositionItem} session
+	 * @returns {String}
+	 */
+
+	/**
+	 * A callback used to determine the human-readable name of a group. This function should
+	 * return the same value for any {@link PositionItem} in the group.
+	 *
+	 * @public
+	 * @callback PositionLevelDefinition~descriptionSelector
+	 * @param {PositionItem} session
+	 * @returns {String}
+	 */
+
+	/**
+	 * A callback used to determine the display {@link Currency} for the group. This function should
+	 * return the same value for any {@link PositionItem} in the group.
+	 *
+	 * @public
+	 * @callback PositionLevelDefinition~currencySelector
+	 * @param {PositionItem} session
+	 * @returns {Currency}
+	 */
+
+	/**
+	 * The data required to construct a group.
+	 *
+	 * @public
+	 * @typedef PositionLevelDefinition~RequiredGroup
+	 * @type {Object}
+	 * @property {String} key
+	 * @property {String} description
+	 * @property {Currency} currency
+	 */
+
+	return PositionLevelDefinition;
+})();

package/lib/processing/definitions/PositionTreeDefinition.js

@@ -0,0 +1,52 @@
+const assert = require('@barchart/common-js/lang/assert');
+
+const PositionLevelDefinition = require('./PositionLevelDefinition');
+
+module.exports = (() => {
+	'use strict';
+
+	/**
+	 * Defines the structure for a tree of positions.
+	 *
+	 * @public
+	 * @param {String} name
+	 * @param {Array.<PositionLevelDefinition>} definitions
+	 */
+	class PositionTreeDefinitions {
+		constructor(name, definitions) {
+			assert.argumentIsRequired(name, 'name', String);
+			assert.argumentIsArray(definitions, 'definitions', PositionLevelDefinition, 'PositionLevelDefinition');
+
+			this._name = name;
+			this._definitions = definitions;
+		}
+
+		/**
+		 * The name of the tree.
+		 *
+		 * @returns {String}
+		 */
+		get name() {
+			return this._name;
+		}
+
+		/**
+		 * An ordered list of {@link PositionLevelDefinitions} that describes the
+		 * levels of the tree. The first item represents the top-most level of the
+		 * tree (i.e. the children of the root node) and the last item represents the
+		 * bottom-most level of the tree (i.e. leaf nodes).
+		 *
+		 * @public
+		 * @returns {Array.<PositionTreeDefinition>}
+		 */
+		get definitions() {
+			return this._definitions;
+		}
+
+		toString() {
+			return '[PositionTreeDefinitions]';
+		}
+	}
+
+	return PositionTreeDefinitions;
+})();