@barchart/portfolio-api-common 1.3.4 → 1.3.8

package/lib/api/failures/PortfolioFailureType.js

@@ -296,8 +296,8 @@ module.exports = (() => {
 	const transactionCreateFailedOutOfSequence = new FailureType('TRANSACTION_CREATE_FAILED_OUT_OF_SEQUENCE', 'Unable to process transaction, because the transaction date is out-of-sequence. In other words, it would occur before an existing transaction. Please confirm your intent to re-write transaction history (which could take some time and alter the historical results for this position).');
 	const transactionCreateFailedInvalidDate = new FailureType('TRANSACTION_CREATE_FAILED_INVALID_DATE', 'Unable to process transaction with given date.');
 	const transactionCreateFailedTypeInvalidForInstrument = new FailureType('TRANSACTION_CREATE_FAILED_TYPE_INVALID_FOR_INSTRUMENT', 'Unable to process transaction, {L|transactionType.description} transactions cannot be used with {L|instrumentType.description} positions.');
-	const transactionCreateFailedTypeInvalidForDirection = new FailureType('TRANSACTION_CREATE_FAILED_TYPE_INVALID_FOR_DIRECTION', 'Unable to process transaction, a {L|positionDirection.description} position would be created (i.e. you would have {L|positionDirection.sign} shares/units). {u|instrumentType.description} positions cannot have {L|positionDirection.description} positions.');
-	const transactionCreateFailedInvalidDirectionSwitch = new FailureType('TRANSACTION_CREATE_FAILED_INVALID_DIRECTION_SWITCH', 'Unable to process transaction, the transaction would switch the position from {L|currentDirection.description} to {L|proposedDirection.description} (i.e. {L|currentDirection.sign} to {L|proposedDirection.sign} shares/units). This is not allowed. Please close the current position (i.e. zero it out) and then enter a second transaction.');
+	const transactionCreateFailedTypeInvalidForDirection = new FailureType('TRANSACTION_CREATE_FAILED_TYPE_INVALID_FOR_DIRECTION', 'Unable to process transaction, a {L|positionDirection.description} position would be created (i.e. you would have {L|positionDirection.sign} shares/units). {u|instrumentType.description} positions cannot have {L|positionDirection.description} positions.', false);
+	const transactionCreateFailedInvalidDirectionSwitch = new FailureType('TRANSACTION_CREATE_FAILED_INVALID_DIRECTION_SWITCH', 'Unable to process transaction, the transaction would switch the position from {L|currentDirection.description} to {L|proposedDirection.description} (i.e. {L|currentDirection.sign} to {L|proposedDirection.sign} shares/units). This is not allowed. Please close the current position (i.e. zero it out) and then enter a second transaction.', false);
 	const transactionCreateFailedInvalidInitialType = new FailureType('TRANSACTION_CREATE_FAILED_INVALID_INITIAL_TYPE', 'Unable to process operation because the first transaction would to be a {U|transactionType.description}, which is not allowed -- since {U|transactionType.description} transactions cannot open a position.');
 
 	const transactionCreateFailedTypeReserved = new FailureType('TRANSACTION_CREATE_FAILED_TYPE_RESERVED', 'Unable to create {U|type.description} transaction, this type of transaction is managed by the system.');
@@ -307,7 +307,7 @@ module.exports = (() => {
 
 	const transactionDeleteFailedOutOfSequence = new FailureType('TRANSACTION_DELETE_FAILED_OUT_OF_SEQUENCE', 'Deleting any transaction, except for the most recent, will cause transaction history to be re-written. Please confirm your intent to re-write transaction history (which could take some time and alter the historical results for this position).');
 	const transactionDeleteFailedNoTransaction = new FailureType('TRANSACTION_DELETE_FAILED_NO_TRANSACTION', 'Unable to delete transaction. The referenced transaction does not exist.');
-	const transactionDeleteFailedDirectionSwitchOnRewrite = new FailureType('TRANSACTION_DELETE_FAILED_DIRECTION_SWITCH_ON_REWRITE', 'Deleting this transaction would cause your history to be re-written and the position to switch from long to short (i.e. positive to negative) or vice versa.');
+	const transactionDeleteFailedDirectionSwitchOnRewrite = new FailureType('TRANSACTION_DELETE_FAILED_DIRECTION_SWITCH_ON_REWRITE', 'Deleting this transaction would cause your history to be re-written and the position to switch from long to short (i.e. positive to negative) or vice versa.', false);
 	const transactionDeleteFailedPositionLocked = new FailureType('TRANSACTION_DELETE_FAILED_POSITION_LOCKED', 'Unable to delete transaction, your {L|description} history is being recalculated. Please wait a minute or two and retry.');
 	const transactionDeleteFailedTypeReserved = new FailureType('TRANSACTION_DELETE_FAILED_TYPE_RESERVED', 'Unable to delete {U|type.description} transaction, this type of transaction is managed by the system.');
 

package/lib/data/InstrumentType.js

@@ -236,7 +236,7 @@ module.exports = (() => {
 		 *
 		 * @public
 		 * @static
-		 * @param code
+		 * @param {Number} code
 		 * @returns {InstrumentType}
 		 */
 		static fromSymbolType(code) {

package/lib/formatters/TransactionFormatter.js

@@ -23,8 +23,7 @@ module.exports = (() => {
 		}
 
 		/**
-		 * Maps transaction objects into new objects whose properties are human-readable (or
-		 * mutates the original objects, adding a "formatted" property to each transaction).
+		 * Maps transaction objects into new objects whose properties are human-readable.
 		 *
 		 * @public
 		 * @static

package/lib/processing/PositionContainer.js

@@ -41,8 +41,8 @@ module.exports = (() => {
 	 * @public
 	 * @param {PositionTreeDefinition[]} definitions
 	 * @param {Object[]} portfolios - The portfolios.
-	 * @param {Object[]} positions - The positions (for all of the portfolios).
-	 * @param {Object[]} summaries - The positions summaries (for all of the positions).
+	 * @param {Object[]} positions - The positions (for all of portfolios).
+	 * @param {Object[]} summaries - The positions summaries (for all of positions).
 	 * @param {PositionSummaryFrame=} reportFrame - If specified, locks the current (and previous) periods to a specific frame, use for reporting.
 	 * @param {Day=} reportDate - The end date for the report frame.
 	 */
@@ -933,7 +933,6 @@ module.exports = (() => {
 		});
 	}
 
-
 	function updateEmptyPortfolioGroups(portfolio) {
 		Object.keys(this._trees).forEach((key) => {
 			this._trees[key].walk((group) => {

package/lib/processing/definitions/PositionLevelDefinition.js

@@ -74,7 +74,7 @@ module.exports = (() => {
 		}
 
 		/**
-		 * A function, when given a {@link PositionItem} returns a string that is used
+		 * A function, when given a {@link PositionItem}, returns a string that is used
 		 * to group {@link PositionItem} instances into different groups.
 		 *
 		 * @public
@@ -85,7 +85,7 @@ module.exports = (() => {
 		}
 
 		/**
-		 * A function, when given a {@link PositionItem} returns a string used to describe the
+		 * A function, when given a {@link PositionItem}, returns a string used to describe the
 		 * group.
 		 *
 		 * @public
@@ -96,7 +96,7 @@ module.exports = (() => {
 		}
 
 		/**
-		 * A function, when given a {@link PositionItem} returns the {@link Currency} used to
+		 * A function, when given a {@link PositionItem}, returns the {@link Currency} used to
 		 * display values for the group.
 		 *
 		 * @public
@@ -111,7 +111,7 @@ module.exports = (() => {
 		 * groups.
 		 *
 		 * @public
-		 * @returns {Array<String>}
+		 * @returns {String[]}
 		 */
 		get requiredGroups() {
 			return this._requiredGroups;
@@ -160,13 +160,16 @@ module.exports = (() => {
 		 * @public
 		 * @static
 		 * @param {Object} portfolio
+		 * @param {Currency=} currency
 		 * @returns {PositionLevelDefinition~RequiredGroup}
 		 */
-		static buildRequiredGroupForPortfolio(portfolio) {
+		static buildRequiredGroupForPortfolio(portfolio, currency) {
+			assert.argumentIsOptional(currency, 'currency', Currency, 'Currency');
+
 			return {
 				key: PositionLevelDefinition.getKeyForPortfolioGroup(portfolio),
 				description: PositionLevelDefinition.getDescriptionForPortfolioGroup(portfolio),
-				currency: Currency.CAD
+				currency: (currency || Currency.CAD)
 			};
 		}
 
@@ -182,12 +185,12 @@ module.exports = (() => {
 			return portfolio.name;
 		}
 
-		static getRequiredGroupGeneratorForPortfolio() {
+		static getRequiredGroupGeneratorForPortfolio(currency) {
 			return (portfolio) => {
 				let requiredGroup;
 
 				if (is.object(portfolio) && is.string(portfolio.portfolio) && is.string(portfolio.name)) {
-					requiredGroup = PositionLevelDefinition.buildRequiredGroupForPortfolio(portfolio);
+					requiredGroup = PositionLevelDefinition.buildRequiredGroupForPortfolio(portfolio, currency);
 				} else {
 					requiredGroup = null;
 				}
@@ -203,12 +206,13 @@ module.exports = (() => {
 		 * @static
 		 * @param {InstrumentType} type
 		 * @param {Currency} currency
+		 * @param {Currency=} defaultCurrency
 		 * @returns {PositionLevelDefinition~RequiredGroup}
 		 */
-		static buildRequiredGroupForAssetClass(type, currency) {
+		static buildRequiredGroupForAssetClass(type, currency, defaultCurrency) {
 			return {
 				key: PositionLevelDefinition.getKeyForAssetClassGroup(type, currency),
-				description: PositionLevelDefinition.getDescriptionForAssetClassGroup(type, currency),
+				description: PositionLevelDefinition.getDescriptionForAssetClassGroup(type, currency, defaultCurrency),
 				currency: currency
 			};
 		}
@@ -220,11 +224,12 @@ module.exports = (() => {
 			return `${type.code}|${currency.code}`;
 		}
 
-		static getDescriptionForAssetClassGroup(type, currency) {
+		static getDescriptionForAssetClassGroup(type, currency, defaultCurrency) {
 			assert.argumentIsRequired(type, 'type', InstrumentType, 'InstrumentType');
 			assert.argumentIsRequired(currency, 'currency', Currency, 'Currency');
+			assert.argumentIsOptional(defaultCurrency, 'defaultCurrency', Currency, 'Currency');
 
-			return `${type.alternateDescription}${currency.code === 'CAD' ? '' : ` (${currency.alternateDescription})`}`;
+			return `${type.alternateDescription}${currency === (defaultCurrency || Currency.CAD) ? '' : ` (${currency.alternateDescription})`}`;
 		}
 
 		toString() {

package/lib/processing/definitions/PositionLevelType.js

@@ -3,19 +3,49 @@ const Enum = require('@barchart/common-js/lang/Enum');
 module.exports = (() => {
 	'use strict';
 
+	/**
+	 * Describes the contents of a grouping level within a tree of positions.
+	 * This is an attribute of a {@link PositionLevelDefinition}.
+	 *
+	 * @public
+	 * @extends {Enum}
+	 */
 	class PositionLevelType extends Enum {
 		constructor(code) {
 			super(code, code);
 		}
 
+		/**
+		 * A level of grouping that represents an entire portfolio's contents.
+		 *
+		 * @public
+		 * @static
+		 * @returns {PositionLevelType}
+		 */
 		static get PORTFOLIO() {
 			return portfolio;
 		}
 
+		/**
+		 * A level of grouping that represents a single positions (i.e. guaranteed to
+		 * be a leaf node in a grouping tree).
+		 *
+		 * @public
+		 * @static
+		 * @return {PositionLevelType}
+		 */
 		static get POSITION() {
 			return position;
 		}
 
+		/**
+		 * A level of grouping that is neither a portfolio or a position. This could be an
+		 * intermediate level of grouping (e.g. an asset class within a portfolio).
+		 *
+		 * @public
+		 * @static
+		 * @return {PositionLevelType}
+		 */
 		static get OTHER() {
 			return other;
 		}

package/lib/processing/definitions/PositionTreeDefinition.js

@@ -11,7 +11,7 @@ module.exports = (() => {
 	 * @public
 	 * @param {String} name
 	 * @param {PositionLevelDefinition[]} definitions
-	 * @oaram {String[]=} exclusionDependencies
+	 * @param {String[]=} exclusionDependencies
 	 */
 	class PositionTreeDefinitions {
 		constructor(name, definitions, exclusionDependencies) {
@@ -44,7 +44,7 @@ module.exports = (() => {
 		 * bottom-most level of the tree (i.e. leaf nodes).
 		 *
 		 * @public
-		 * @returns {PositionLevelDefinitions>[]}
+		 * @returns {PositionLevelDefinitions[]}
 		 */
 		get definitions() {
 			return this._definitions;

package/lib/websockets/WebsocketActionType.js

@@ -0,0 +1,123 @@
+const assert = require('@barchart/common-js/lang/assert'),
+  Enum = require('@barchart/common-js/lang/Enum');
+
+module.exports = (() => {
+  'use strict';
+
+  /**
+   * Types of websocket response actions.
+   *
+   * @public
+   * @extends {Enum}
+   * @param {String} code
+   * @param {String} description
+   * @param {String} action
+   */
+  class WebsocketActionType extends Enum {
+    constructor(code, description, action) {
+      super(code, description);
+
+      assert.argumentIsRequired(action, 'action', String);
+
+      this._action = action;
+    }
+
+    /**
+     * An action of websocket response
+     *
+     * @public
+     * @returns {String}
+     */
+    get action() {
+      return this._action;
+    }
+
+    /**
+     * Action type for creating new portfolio.
+     *
+     * @public
+     * @static
+     * @returns {WebsocketActionType}
+     */
+    static get PORTFOLIO_CREATE() {
+      return portfolioCreate;
+    }
+
+    /**
+     * Action type for deleting portfolio.
+     *
+     * @public
+     * @static
+     * @returns {WebsocketActionType}
+     */
+    static get PORTFOLIO_DELETE() {
+      return portfolioDelete;
+    }
+
+    /**
+     * Action type for updating new portfolio.
+     *
+     * @public
+     * @static
+     * @returns {WebsocketActionType}
+     */
+    static get PORTFOLIO_UPDATE() {
+      return portfolioUpdate;
+    }
+
+    /**
+     * Action type for creating new transaction.
+     *
+     * @public
+     * @static
+     * @returns {WebsocketActionType}
+     */
+    static get TRANSACTION_CREATE() {
+      return transactionCreate;
+    }
+
+    /**
+     * Action type for deleting transaction.
+     *
+     * @public
+     * @static
+     * @returns {WebsocketActionType}
+     */
+    static get TRANSACTION_DELETE() {
+      return transactionDelete;
+    }
+
+    /**
+     * Action type for editing transaction.
+     *
+     * @public
+     * @static
+     * @returns {WebsocketActionType}
+     */
+    static get TRANSACTION_EDIT() {
+      return transactionEdit;
+    }
+
+    /**
+     * Action type for batching transaction.
+     *
+     * @public
+     * @static
+     * @returns {WebsocketActionType}
+     */
+    static get TRANSACTION_BATCH() {
+      return transactionBatch;
+    }
+  }
+
+  const portfolioCreate = new WebsocketActionType('PORTFOLIO_CREATE', 'Create portfolio action', 'portfolio/create');
+  const portfolioDelete = new WebsocketActionType('PORTFOLIO_DELETE', 'Delete portfolio action', 'portfolio/delete');
+  const portfolioUpdate = new WebsocketActionType('PORTFOLIO_UPDATE', 'Update portfolio action', 'portfolio/update');
+
+  const transactionCreate = new WebsocketActionType('TRANSACTION_CREATE', 'Create transaction action', 'transaction/create');
+  const transactionDelete = new WebsocketActionType('TRANSACTION_DELETE', 'Delete transaction action', 'transaction/delete');
+  const transactionEdit = new WebsocketActionType('TRANSACTION_EDIT', 'Edit transaction action', 'transaction/edit');
+  const transactionBatch = new WebsocketActionType('TRANSACTION_BATCH', 'Batch transaction action', 'transaction/batch');
+
+  return WebsocketActionType;
+})();

package/package.json

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

package/test/SpecRunner.js

@@ -237,7 +237,7 @@ module.exports = (() => {
 		 *
 		 * @public
 		 * @static
-		 * @param code
+		 * @param {Number} code
 		 * @returns {InstrumentType}
 		 */
 		static fromSymbolType(code) {
@@ -1527,8 +1527,8 @@ module.exports = (() => {
 	 * @public
 	 * @param {PositionTreeDefinition[]} definitions
 	 * @param {Object[]} portfolios - The portfolios.
-	 * @param {Object[]} positions - The positions (for all of the portfolios).
-	 * @param {Object[]} summaries - The positions summaries (for all of the positions).
+	 * @param {Object[]} positions - The positions (for all of portfolios).
+	 * @param {Object[]} summaries - The positions summaries (for all of positions).
 	 * @param {PositionSummaryFrame=} reportFrame - If specified, locks the current (and previous) periods to a specific frame, use for reporting.
 	 * @param {Day=} reportDate - The end date for the report frame.
 	 */
@@ -2419,7 +2419,6 @@ module.exports = (() => {
 		});
 	}
 
-
 	function updateEmptyPortfolioGroups(portfolio) {
 		Object.keys(this._trees).forEach((key) => {
 			this._trees[key].walk((group) => {
@@ -4400,7 +4399,7 @@ module.exports = (() => {
 		}
 
 		/**
-		 * A function, when given a {@link PositionItem} returns a string that is used
+		 * A function, when given a {@link PositionItem}, returns a string that is used
 		 * to group {@link PositionItem} instances into different groups.
 		 *
 		 * @public
@@ -4411,7 +4410,7 @@ module.exports = (() => {
 		}
 
 		/**
-		 * A function, when given a {@link PositionItem} returns a string used to describe the
+		 * A function, when given a {@link PositionItem}, returns a string used to describe the
 		 * group.
 		 *
 		 * @public
@@ -4422,7 +4421,7 @@ module.exports = (() => {
 		}
 
 		/**
-		 * A function, when given a {@link PositionItem} returns the {@link Currency} used to
+		 * A function, when given a {@link PositionItem}, returns the {@link Currency} used to
 		 * display values for the group.
 		 *
 		 * @public
@@ -4437,7 +4436,7 @@ module.exports = (() => {
 		 * groups.
 		 *
 		 * @public
-		 * @returns {Array<String>}
+		 * @returns {String[]}
 		 */
 		get requiredGroups() {
 			return this._requiredGroups;
@@ -4486,13 +4485,16 @@ module.exports = (() => {
 		 * @public
 		 * @static
 		 * @param {Object} portfolio
+		 * @param {Currency=} currency
 		 * @returns {PositionLevelDefinition~RequiredGroup}
 		 */
-		static buildRequiredGroupForPortfolio(portfolio) {
+		static buildRequiredGroupForPortfolio(portfolio, currency) {
+			assert.argumentIsOptional(currency, 'currency', Currency, 'Currency');
+
 			return {
 				key: PositionLevelDefinition.getKeyForPortfolioGroup(portfolio),
 				description: PositionLevelDefinition.getDescriptionForPortfolioGroup(portfolio),
-				currency: Currency.CAD
+				currency: (currency || Currency.CAD)
 			};
 		}
 
@@ -4508,12 +4510,12 @@ module.exports = (() => {
 			return portfolio.name;
 		}
 
-		static getRequiredGroupGeneratorForPortfolio() {
+		static getRequiredGroupGeneratorForPortfolio(currency) {
 			return (portfolio) => {
 				let requiredGroup;
 
 				if (is.object(portfolio) && is.string(portfolio.portfolio) && is.string(portfolio.name)) {
-					requiredGroup = PositionLevelDefinition.buildRequiredGroupForPortfolio(portfolio);
+					requiredGroup = PositionLevelDefinition.buildRequiredGroupForPortfolio(portfolio, currency);
 				} else {
 					requiredGroup = null;
 				}
@@ -4529,12 +4531,13 @@ module.exports = (() => {
 		 * @static
 		 * @param {InstrumentType} type
 		 * @param {Currency} currency
+		 * @param {Currency=} defaultCurrency
 		 * @returns {PositionLevelDefinition~RequiredGroup}
 		 */
-		static buildRequiredGroupForAssetClass(type, currency) {
+		static buildRequiredGroupForAssetClass(type, currency, defaultCurrency) {
 			return {
 				key: PositionLevelDefinition.getKeyForAssetClassGroup(type, currency),
-				description: PositionLevelDefinition.getDescriptionForAssetClassGroup(type, currency),
+				description: PositionLevelDefinition.getDescriptionForAssetClassGroup(type, currency, defaultCurrency),
 				currency: currency
 			};
 		}
@@ -4546,11 +4549,12 @@ module.exports = (() => {
 			return `${type.code}|${currency.code}`;
 		}
 
-		static getDescriptionForAssetClassGroup(type, currency) {
+		static getDescriptionForAssetClassGroup(type, currency, defaultCurrency) {
 			assert.argumentIsRequired(type, 'type', InstrumentType, 'InstrumentType');
 			assert.argumentIsRequired(currency, 'currency', Currency, 'Currency');
+			assert.argumentIsOptional(defaultCurrency, 'defaultCurrency', Currency, 'Currency');
 
-			return `${type.alternateDescription}${currency.code === 'CAD' ? '' : ` (${currency.alternateDescription})`}`;
+			return `${type.alternateDescription}${currency === (defaultCurrency || Currency.CAD) ? '' : ` (${currency.alternateDescription})`}`;
 		}
 
 		toString() {
@@ -4608,19 +4612,49 @@ const Enum = require('@barchart/common-js/lang/Enum');
 module.exports = (() => {
 	'use strict';
 
+	/**
+	 * Describes the contents of a grouping level within a tree of positions.
+	 * This is an attribute of a {@link PositionLevelDefinition}.
+	 *
+	 * @public
+	 * @extends {Enum}
+	 */
 	class PositionLevelType extends Enum {
 		constructor(code) {
 			super(code, code);
 		}
 
+		/**
+		 * A level of grouping that represents an entire portfolio's contents.
+		 *
+		 * @public
+		 * @static
+		 * @returns {PositionLevelType}
+		 */
 		static get PORTFOLIO() {
 			return portfolio;
 		}
 
+		/**
+		 * A level of grouping that represents a single positions (i.e. guaranteed to
+		 * be a leaf node in a grouping tree).
+		 *
+		 * @public
+		 * @static
+		 * @return {PositionLevelType}
+		 */
 		static get POSITION() {
 			return position;
 		}
 
+		/**
+		 * A level of grouping that is neither a portfolio or a position. This could be an
+		 * intermediate level of grouping (e.g. an asset class within a portfolio).
+		 *
+		 * @public
+		 * @static
+		 * @return {PositionLevelType}
+		 */
 		static get OTHER() {
 			return other;
 		}
@@ -4647,7 +4681,7 @@ module.exports = (() => {
 	 * @public
 	 * @param {String} name
 	 * @param {PositionLevelDefinition[]} definitions
-	 * @oaram {String[]=} exclusionDependencies
+	 * @param {String[]=} exclusionDependencies
 	 */
 	class PositionTreeDefinitions {
 		constructor(name, definitions, exclusionDependencies) {
@@ -4680,7 +4714,7 @@ module.exports = (() => {
 		 * bottom-most level of the tree (i.e. leaf nodes).
 		 *
 		 * @public
-		 * @returns {PositionLevelDefinitions>[]}
+		 * @returns {PositionLevelDefinitions[]}
 		 */
 		get definitions() {
 			return this._definitions;