@barchart/portfolio-api-common 1.18.0 → 1.20.0

package/lib/api/failures/PortfolioFailureType.js

@@ -280,6 +280,17 @@ module.exports = (() => {
 			return transactionCreateFailedInstrumentCorrupt;
 		}
 
+		/**
+		 * The transaction failed because instrument metadata could not be resolved.
+		 *
+		 * @public
+		 * @static
+		 * @returns {FailureType}
+		 */
+		static get TRANSACTION_CREATE_FAILED_INSTRUMENT_UNAVAILABLE() {
+			return transactionCreateFailedInstrumentUnavailable;
+		}
+
 		/**
 		 * The transaction (of this type) cannot be deleted by a user, instead,
 		 * it is created and managed by the system (e.g. dividends).
@@ -449,6 +460,7 @@ module.exports = (() => {
 	const transactionCreateFailedReinvestInvalid = new FailureType('TRANSACTION_CREATE_FAILED_REINVEST_INVALID', 'Unable to create transaction, short positions do not allow dividends to be reinvested.');
 	const transactionCreateFailedPositionLocked = new FailureType('TRANSACTION_CREATE_FAILED_POSITION_LOCKED', 'Unable to create transaction, your {L|description} history is being recalculated. Please re-enter this transaction in a minute or two.');
 	const transactionCreateFailedInstrumentCorrupt = new FailureType('TRANSACTION_CREATE_FAILED_INSTRUMENT_CORRUPT', 'Unable to create transaction, corporate action history for {U|symbol} cannot be located. The issue should be corrected within 24 to 48 hours.');
+	const transactionCreateFailedInstrumentUnavailable = new FailureType('TRANSACTION_CREATE_FAILED_INSTRUMENT_UNAVAILABLE', 'Unable to create transaction, no {L|description} instrument was found with the symbol {U|symbol}.');
 
 	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.', false);

package/lib/calculators/ValuationCalculator.js

@@ -0,0 +1,84 @@
+const Decimal = require('@barchart/common-js/lang/Decimal'),
+	is = require('@barchart/common-js/lang/is');
+
+const InstrumentType = require('./../data/InstrumentType');
+
+module.exports = (() => {
+	'use strict';
+	
+	class ValuationCalculator {
+		constructor() {
+
+		}
+
+		static calculate(instrument, price, quantity) {
+			let priceToUse = null;
+
+			if (is.number(price)) {
+				priceToUse = new Decimal(price);
+			} else if (price instanceof Decimal) {
+				priceToUse = price;
+			}
+
+			if (priceToUse === null) {
+				return null;
+			}
+
+			const calculator = calculators.get(instrument.type);
+
+			return calculator(instrument, priceToUse, quantity);
+		}
+
+		toString() {
+			return `[ValuationCalculator]`;
+		}
+	}
+
+	function calculateForCash(instrument, price, quantity) {
+		return new Decimal(quantity);
+	}
+
+	function calculateForEquity(instrument, price, quantity) {
+		return price.multiply(quantity);
+	}
+
+	function calculateForEquityOption(instrument, price, quantity) {
+		const priceMultiplier = instrument.option.multiplier;
+
+		return price.multiply(priceMultiplier).multiply(quantity);
+	}
+
+	function calculateForFund(instrument, price, quantity) {
+		return price.multiply(quantity);
+	}
+
+	function calculateForFuture(instrument, price, quantity) {
+		const minimumTick = instrument.future.tick;
+		const minimumTickValue = instrument.future.value;
+
+		return price.divide(minimumTick).multiply(minimumTickValue).multiply(quantity);
+	}
+
+	function calculateForFutureOption(instrument, price, quantity) {
+		const minimumTick = instrument.option.tick;
+		const minimumTickValue = instrument.option.value;
+
+		return price.divide(minimumTick).multiply(minimumTickValue).multiply(quantity);
+	}
+
+	function calculateForOther(instrument, price, quantity) {
+		return price.multiply(quantity);
+	}
+
+	const calculators = new Map();
+
+	calculators.set(InstrumentType.CASH, calculateForCash);
+	calculators.set(InstrumentType.EQUITY, calculateForEquity);
+	calculators.set(InstrumentType.EQUITY_OPTION, calculateForEquityOption);
+	calculators.set(InstrumentType.FUND, calculateForFund);
+	calculators.set(InstrumentType.FUTURE, calculateForFuture);
+	calculators.set(InstrumentType.FUTURE_OPTION, calculateForFutureOption);
+	calculators.set(InstrumentType.OTHER, calculateForOther);
+
+	return ValuationCalculator;
+})();

package/lib/data/CorporateActionType.js

@@ -1,5 +1,4 @@
-const Enum = require('@barchart/common-js/lang/Enum'),
-	is = require('@barchart/common-js/lang/is');
+const Enum = require('@barchart/common-js/lang/Enum');
 
 module.exports = (() => {
 	'use strict';
@@ -120,14 +119,14 @@ module.exports = (() => {
 		}
 	}
 
-	const split = new CorporateActionType('SPLIT', 'Split', false);
-	const dividend = new CorporateActionType('DIVIDEND', 'Dividend', false);
-	const stockDividend = new CorporateActionType('STOCK_DIVIDEND', 'Stock Dividend', false);
-	const symbolChange = new CorporateActionType('SYMBOL_CHANGE', 'Symbol Change', false);
-	const nameChange = new CorporateActionType('NAME_CHANGE', 'Name Change', false);
-	const delist = new CorporateActionType('DELIST', 'Delist', false);
-	const merger = new CorporateActionType('MERGER', 'Merger', false);
-	const spinoff = new CorporateActionType('SPINOFF', 'Spinoff', false);
+	const split = new CorporateActionType('SPLIT', 'Split');
+	const dividend = new CorporateActionType('DIVIDEND', 'Dividend');
+	const stockDividend = new CorporateActionType('STOCK_DIVIDEND', 'Stock Dividend');
+	const symbolChange = new CorporateActionType('SYMBOL_CHANGE', 'Symbol Change');
+	const nameChange = new CorporateActionType('NAME_CHANGE', 'Name Change');
+	const delist = new CorporateActionType('DELIST', 'Delist');
+	const merger = new CorporateActionType('MERGER', 'Merger');
+	const spinoff = new CorporateActionType('SPINOFF', 'Spinoff');
 
 	return CorporateActionType;
 })();

package/lib/data/InstrumentType.js

@@ -173,6 +173,26 @@ module.exports = (() => {
 			return this._roundQuantity;
 		}
 
+		/**
+		 * Indicates if the instrument is a futures contract.
+		 *
+		 * @public
+		 * @returns {boolean}
+		 */
+		get future() {
+			return this === future;
+		}
+
+		/**
+		 * Indicates if the instrument is an option contract.
+		 *
+		 * @public
+		 * @returns {boolean}
+		 */
+		get option() {
+			return this === equityOption || this === futureOption;
+		}
+
 		/**
 		 * Generates an identifier for the instrument.
 		 *
@@ -212,6 +232,17 @@ module.exports = (() => {
 			return equity;
 		}
 
+		/**
+		 * An option on equity shares.
+		 *
+		 * @public
+		 * @static
+		 * @returns {InstrumentType}
+		 */
+		static get EQUITY_OPTION() {
+			return equityOption;
+		}
+
 		/**
 		 * A mutual fund.
 		 *
@@ -234,6 +265,17 @@ module.exports = (() => {
 			return future;
 		}
 
+		/**
+		 * An option on a futures contract.
+		 *
+		 * @public
+		 * @static
+		 * @returns {InstrumentType}
+		 */
+		static get FUTURE_OPTION() {
+			return futureOption;
+		}
+
 		/**
 		 * An undefined asset (e.g. a house, or a collectible, or a salvaged alien spaceship).
 		 *
@@ -281,10 +323,14 @@ module.exports = (() => {
 
 			if (code === 1 || code === 6 || code === 7 || code === 11) {
 				return InstrumentType.EQUITY;
+			} else if (code === 34) {
+				return InstrumentType.EQUITY_OPTION;
 			} else if (code === 5 || code == 15) {
 				return InstrumentType.FUND;
 			} else if (code === 2) {
 				return InstrumentType.FUTURE;
+			} else if (code === 12) {
+				return InstrumentType.FUTURE_OPTION;
 			} else {
 				throw new Error(`Unable to determine InstrumentType for [ ${code} ]`);
 			}
@@ -297,8 +343,10 @@ module.exports = (() => {
 
 	const cash = new InstrumentType('CASH', 'cash', 'Cash', true, false, false, true, false, false, true, false, false, false, instrument => `BARCHART-${instrument.type.code}-${instrument.currency.code}`);
 	const equity = new InstrumentType('EQUITY', 'equity', 'Equities', false, true, true, false, true, true, true, true, true, true, instrument => `BARCHART-${instrument.type.code}-${instrument.symbol.barchart}`);
+	const equityOption = new InstrumentType('EQUITY_OPTION', 'equity option', 'Equity Option', false, false, true, false, true, false, false, false, false, true, instrument => `BARCHART-${instrument.type.code}-${instrument.symbol.barchart}`);
 	const fund = new InstrumentType('FUND', 'mutual fund', 'Funds', false, true, false, false, true, true, true,false, true, true, instrument => `BARCHART-${instrument.type.code}-${instrument.symbol.barchart}`);
 	const future = new InstrumentType('FUTURE', 'futures contract', 'Futures', false, false, true, false, true, false, false, false, false, true, instrument => `BARCHART-${instrument.type.code}-${instrument.symbol.barchart}`);
+	const futureOption = new InstrumentType('FUTURE_OPTION', 'futures option', 'Futures Option', false, false, true, false, true, false, false, false, false, true, instrument => `BARCHART-${instrument.type.code}-${instrument.symbol.barchart}`);
 	const other = new InstrumentType('OTHER', 'other', 'Other', false, false, false, false, false, false, true,false, true, true, instrument => `BARCHART-${instrument.type.code}-${uuid.v4()}`);
 
 	return InstrumentType;

package/lib/data/OptionSide.js

@@ -0,0 +1,61 @@
+const Enum = require('@barchart/common-js/lang/Enum');
+
+module.exports = (() => {
+	'use strict';
+
+	/**
+	 * Indicates whether an option conveys the right to buy or
+	 * sell the underlying instrument.
+	 *
+	 * @public
+	 * @extends {Enum}
+	 * @param {String} code
+	 * @param {String} description
+	 */
+	class OptionSide extends Enum {
+		constructor(code, description) {
+			super(code, description);
+		}
+
+		/**
+		 * The right to buy the underlying instrument.
+		 *
+		 * @public
+		 * @static
+		 * @returns {OptionSide}
+		 */
+		static get CALL() {
+			return call;
+		}
+
+		/**
+		 * The right to sell the underlying instrument.
+		 *
+		 * @public
+		 * @static
+		 * @returns {OptionSide}
+		 */
+		static get PUT() {
+			return put;
+		}
+
+		/**
+		 * @public
+		 * @static
+		 * @param {String} code
+		 * @returns {OptionSide|null}
+		 */
+		static parse(code) {
+			return Enum.fromCode(OptionSide, code);
+		}
+
+		toString() {
+			return `[OptionSide (code=${this.code})]`;
+		}
+	}
+
+	const put = new OptionSide('PUT', 'Put');
+	const call = new OptionSide('CALL', 'Call');
+
+	return OptionSide;
+})();

package/lib/data/TransactionValidator.js

@@ -250,6 +250,11 @@ module.exports = (() => {
 	associateTypes(InstrumentType.EQUITY, TransactionType.SPINOFF, false);
 	associateTypes(InstrumentType.EQUITY, TransactionType.SPINOFF_OPEN, false);
 
+	associateTypes(InstrumentType.EQUITY_OPTION, TransactionType.BUY, true, [ PositionDirection.LONG, PositionDirection.EVEN ]);
+	associateTypes(InstrumentType.EQUITY_OPTION, TransactionType.SELL, true, [ PositionDirection.LONG ]);
+	associateTypes(InstrumentType.EQUITY_OPTION, TransactionType.SELL_SHORT, true, [ PositionDirection.SHORT, PositionDirection.EVEN ]);
+	associateTypes(InstrumentType.EQUITY_OPTION, TransactionType.BUY_SHORT, true, [ PositionDirection.SHORT ]);
+
 	associateTypes(InstrumentType.FUND, TransactionType.BUY, true, [ PositionDirection.LONG, PositionDirection.EVEN ]);
 	associateTypes(InstrumentType.FUND, TransactionType.SELL, true, [ PositionDirection.LONG ]);
 	associateTypes(InstrumentType.FUND, TransactionType.FEE, true, [ PositionDirection.LONG ]);
@@ -268,6 +273,11 @@ module.exports = (() => {
 	associateTypes(InstrumentType.FUTURE, TransactionType.SELL_SHORT, true, [ PositionDirection.SHORT, PositionDirection.EVEN ]);
 	associateTypes(InstrumentType.FUTURE, TransactionType.BUY_SHORT, true, [ PositionDirection.SHORT ]);
 
+	associateTypes(InstrumentType.FUTURE_OPTION, TransactionType.BUY, true, [ PositionDirection.LONG, PositionDirection.EVEN ]);
+	associateTypes(InstrumentType.FUTURE_OPTION, TransactionType.SELL, true, [ PositionDirection.LONG ]);
+	associateTypes(InstrumentType.FUTURE_OPTION, TransactionType.SELL_SHORT, true, [ PositionDirection.SHORT, PositionDirection.EVEN ]);
+	associateTypes(InstrumentType.FUTURE_OPTION, TransactionType.BUY_SHORT, true, [ PositionDirection.SHORT ]);
+
 	associateTypes(InstrumentType.OTHER, TransactionType.BUY, true, [ PositionDirection.LONG, PositionDirection.EVEN ]);
 	associateTypes(InstrumentType.OTHER, TransactionType.SELL, true, [ PositionDirection.LONG ]);
 	associateTypes(InstrumentType.OTHER, TransactionType.INCOME, true, [ PositionDirection.LONG ]);
@@ -295,6 +305,10 @@ module.exports = (() => {
 	associateDirections(InstrumentType.EQUITY, PositionDirection.LONG);
 	associateDirections(InstrumentType.EQUITY, PositionDirection.SHORT);
 
+	associateDirections(InstrumentType.EQUITY_OPTION, PositionDirection.EVEN);
+	associateDirections(InstrumentType.EQUITY_OPTION, PositionDirection.LONG);
+	associateDirections(InstrumentType.EQUITY_OPTION, PositionDirection.SHORT);
+
 	associateDirections(InstrumentType.FUND, PositionDirection.EVEN);
 	associateDirections(InstrumentType.FUND, PositionDirection.LONG);
 
@@ -302,6 +316,10 @@ module.exports = (() => {
 	associateDirections(InstrumentType.FUTURE, PositionDirection.LONG);
 	associateDirections(InstrumentType.FUTURE, PositionDirection.SHORT);
 
+	associateDirections(InstrumentType.FUTURE_OPTION, PositionDirection.EVEN);
+	associateDirections(InstrumentType.FUTURE_OPTION, PositionDirection.LONG);
+	associateDirections(InstrumentType.FUTURE_OPTION, PositionDirection.SHORT);
+
 	associateDirections(InstrumentType.OTHER, PositionDirection.EVEN);
 	associateDirections(InstrumentType.OTHER, PositionDirection.LONG);
 

package/lib/processing/PositionItem.js

@@ -8,6 +8,8 @@ const assert = require('@barchart/common-js/lang/assert'),
 const InstrumentType = require('./../data/InstrumentType'),
 	PositionDirection = require('./../data/PositionDirection');
 
+const ValuationCalculator = require('./../calculators/ValuationCalculator');
+
 module.exports = (() => {
 	'use strict';
 
@@ -514,14 +516,8 @@ module.exports = (() => {
 			market = snapshot.value;
 		} else if (position.instrument.type === InstrumentType.CASH) {
 			market = snapshot.open;
-		} else if (position.instrument.type === InstrumentType.FUTURE) {
-			market = getFuturesValue(position.instrument, snapshot.open, price) || snapshot.value;
 		} else {
-			if (price) {
-				market = snapshot.open.multiply(price);
-			} else {
-				market = snapshot.value;
-			}
+			market = ValuationCalculator.calculate(position.instrument, price, snapshot.open) || snapshot.value;
 		}
 
 		let marketChange;
@@ -551,13 +547,7 @@ module.exports = (() => {
 		let unrealizedTodayChange;
 
 		if (data.previousPrice && price) {
-			let unrealizedTodayBase;
-
-			if (position.instrument.type === InstrumentType.FUTURE) {
-				unrealizedTodayBase = getFuturesValue(position.instrument, snapshot.open, data.previousPrice);
-			} else {
-				unrealizedTodayBase = snapshot.open.multiply(data.previousPrice);
-			}
+			const unrealizedTodayBase = ValuationCalculator.calculate(position.instrument, data.previousPrice, snapshot.open);
 
 			unrealizedToday = market.subtract(unrealizedTodayBase);
 
@@ -591,13 +581,7 @@ module.exports = (() => {
 			}
 
 			if (priceToUse !== null) {
-				let unrealized;
-
-				if (position.instrument.type === InstrumentType.FUTURE) {
-					unrealized = getFuturesValue(position.instrument, currentSummary.end.open, priceToUse).add(currentSummary.end.basis);
-				} else {
-					unrealized = currentSummary.end.open.multiply(priceToUse).add(currentSummary.end.basis);
-				}
+				const unrealized = ValuationCalculator.calculate(position.instrument, priceToUse, currentSummary.end.open).add(currentSummary.end.basis);
 
 				let unrealizedChange;
 
@@ -682,11 +666,7 @@ module.exports = (() => {
 			let endValue;
 
 			if (overridePrice) {
-				if (type === InstrumentType.FUTURE) {
-					endValue = getFuturesValue(instrument, currentSummary.end.open, overridePrice);
-				} else {
-					endValue = currentSummary.end.open.multiply(overridePrice);
-				}
+				endValue = ValuationCalculator.calculate(instrument, overridePrice, currentSummary.end.open);
 			} else {
 				endValue = currentSummary.end.value;
 			}
@@ -807,18 +787,5 @@ module.exports = (() => {
 		return snapshot;
 	}
 
-	function getFuturesValue(instrument, contracts, price) {
-		if (price || price === 0) {
-			const priceDecimal = new Decimal(price);
-
-			const minimumTick = instrument.future.tick;
-			const minimumTickValue = instrument.future.value;
-
-			return priceDecimal.divide(minimumTick).multiply(minimumTickValue).multiply(contracts);
-		} else {
-			return null;
-		}
-	}
-
 	return PositionItem;
 })();

package/lib/serialization/PositionSchema.js

@@ -5,6 +5,7 @@ const Currency = require('@barchart/common-js/lang/Currency'),
 	SchemaBuilder = require('@barchart/common-js/serialization/json/builders/SchemaBuilder');
 
 const InstrumentType = require('./../data/InstrumentType'),
+	OptionSide = require('./../data/OptionSide'),
 	PositionDirection = require('./../data/PositionDirection'),
 	ValuationType = require('./../data/ValuationType');
 
@@ -95,7 +96,11 @@ module.exports = (() => {
 		.withField('instrument.future.tick', DataType.DECIMAL, true)
 		.withField('instrument.future.value', DataType.DECIMAL, true)
 		.withField('instrument.option.expiration', DataType.DAY, true)
+		.withField('instrument.option.side', DataType.forEnum(OptionSide, 'OptionSide'), true)
 		.withField('instrument.option.strike', DataType.DECIMAL, true)
+		.withField('instrument.option.multiplier', DataType.DECIMAL, true)
+		.withField('instrument.option.tick', DataType.DECIMAL, true)
+		.withField('instrument.option.value', DataType.DECIMAL, true)
 		.withField('instrument.symbol.barchart', DataType.STRING, true)
 		.withField('instrument.symbol.display', DataType.STRING, true)
 		.withField('position', DataType.STRING)
@@ -136,7 +141,11 @@ module.exports = (() => {
 		.withField('instrument.future.tick', DataType.DECIMAL, true)
 		.withField('instrument.future.value', DataType.DECIMAL, true)
 		.withField('instrument.option.expiration', DataType.DAY, true)
+		.withField('instrument.option.side', DataType.forEnum(OptionSide, 'OptionSide'), true)
 		.withField('instrument.option.strike', DataType.DECIMAL, true)
+		.withField('instrument.option.multiplier', DataType.DECIMAL, true)
+		.withField('instrument.option.tick', DataType.DECIMAL, true)
+		.withField('instrument.option.value', DataType.DECIMAL, true)
 		.withField('instrument.symbol.barchart', DataType.STRING, true)
 		.withField('instrument.symbol.display', DataType.STRING, true)
 		.withField('position', DataType.STRING)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barchart/portfolio-api-common",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "Common JavaScript code used by Barchart's Portfolio Service",
   "author": {
     "name": "Bryan Ingle",
@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "@barchart/common-js": "^4.27.0",
-    "@barchart/marketdata-api-js": "^6.1.0",
+    "@barchart/marketdata-api-js": "^6.1.1",
     "uuid": "^8.3.2"
   },
   "devDependencies": {