@barchart/portfolio-api-common 1.17.0 → 1.18.0

package/lib/api/failures/PortfolioFailureType.js

@@ -199,6 +199,29 @@ module.exports = (() => {
 			return transactionCreateFailedAfterTermination;
 		}
 
+		/**
+		 * A transaction cannot be created because the price is not a valid
+		 * multiple of the minimum tick size.
+		 *
+		 * @public
+		 * @static
+		 * @returns {FailureType}
+		 */
+		static get TRANSACTION_CREATE_FAILED_PRICE_INVALID_FOR_INSTRUMENT() {
+			return transactionCreateFailedInvalidPriceForInstrument;
+		}
+
+		/**
+		 * A transaction cannot be created  after the instrument's expiration date.
+		 *
+		 * @public
+		 * @static
+		 * @returns {FailureType}
+		 */
+		static get TRANSACTION_CREATE_FAILED_INSTRUMENT_EXPIRED() {
+			return transactionCreateFailedInstrumentExpired;
+		}
+
 		/**
 		 * The transaction (of this type) cannot be created by a user, instead,
 		 * it is created and managed by the system (e.g. dividends).
@@ -418,6 +441,8 @@ module.exports = (() => {
 	const transactionCreateFailedValuationNegative = new FailureType('TRANSACTION_CREATE_FAILED_VALUATION_NEGATIVE', 'Unable to process operation, valuations cannot be negative.', false);
 	const transactionCreateFailedInvalidTermination = new FailureType('TRANSACTION_CREATE_FAILED_INVALID_TERMINATION', 'Unable to process operation, a {U|transactionType.description} must be the final transaction in the position history.', false);
 	const transactionCreateFailedAfterTermination = new FailureType('TRANSACTION_CREATE_FAILED_AFTER_TERMINATION', 'Unable to process operation, one or more transactions would exist after {L|termination}, the final day of trading for this instrument', false);
+	const transactionCreateFailedInvalidPriceForInstrument = new FailureType('TRANSACTION_CREATE_FAILED_PRICE_INVALID_FOR_INSTRUMENT', 'Unable to process transaction, the trade price for {U|symbol} must be a multiple of {tick} (the minimum tick increment).', false);
+	const transactionCreateFailedInstrumentExpired = new FailureType('TRANSACTION_CREATE_FAILED_INSTRUMENT_EXPIRED', 'Unable to process transaction, the transaction date {date} is after the expiration date {expiration}.', false);
 
 	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.');
 	const transactionCreateFailedReinvestPriceUnavailable = new FailureType('TRANSACTION_CREATE_FAILED_REINVEST_PRICE_UNAVAILABLE', 'Unable to create transaction, a dividend was paid on {L|day}; however no historical price is available for this day. To successfully create this transaction, please turn off dividend reinvestment for this position.');

package/lib/data/CorporateActionType.js

@@ -105,6 +105,16 @@ module.exports = (() => {
 			return spinoff;
 		}
 
+		/**
+		 * @public
+		 * @static
+		 * @param {String} code
+		 * @returns {CorporateActionType|null}
+		 */
+		static parse(code) {
+			return Enum.fromCode(CorporateActionType, code);
+		}
+
 		toString() {
 			return `[CorporateActionType (code=${this.code})]`;
 		}

package/lib/data/InstrumentType.js

@@ -20,13 +20,14 @@ module.exports = (() => {
 	 * @param {Boolean} canSwitchDirection
 	 * @param {Boolean} usesSymbols
 	 * @param {Boolean} hasCorporateActions
+	 * @param {Boolean} allowFractional
 	 * @param {Boolean} closeFractional
 	 * @param {Boolean} roundQuantity
 	 * @param {Boolean} strictOrdering
 	 * @param {Function} generator
 	 */
 	class InstrumentType extends Enum {
-		constructor(code, description, alternateDescription, canExistEmpty, canReinvest, canShort, canSwitchDirection, usesSymbols, hasCorporateActions, closeFractional, roundQuantity, strictOrdering, generator) {
+		constructor(code, description, alternateDescription, canExistEmpty, canReinvest, canShort, canSwitchDirection, usesSymbols, hasCorporateActions, allowFractional, closeFractional, roundQuantity, strictOrdering, generator) {
 			super(code, description);
 
 			assert.argumentIsRequired(alternateDescription, 'alternateDescription', String);
@@ -36,9 +37,10 @@ module.exports = (() => {
 			assert.argumentIsRequired(canSwitchDirection, 'canSwitchDirection', Boolean);
 			assert.argumentIsRequired(usesSymbols, 'usesSymbols', Boolean);
 			assert.argumentIsRequired(hasCorporateActions, 'hasCorporateActions', Boolean);
+			assert.argumentIsRequired(allowFractional, 'allowFractional', Boolean);
 			assert.argumentIsRequired(closeFractional, 'closeFractional', Boolean);
 			assert.argumentIsRequired(roundQuantity, 'roundQuantity', Boolean);
-			assert.argumentIsRequired(roundQuantity, 'strictOrdering', Boolean);
+			assert.argumentIsRequired(strictOrdering, 'strictOrdering', Boolean);
 			assert.argumentIsRequired(generator, 'generator', Function);
 
 			this._alternateDescription = alternateDescription;
@@ -49,6 +51,7 @@ module.exports = (() => {
 			this._canSwitchDirection = canSwitchDirection;
 			this._usesSymbols = usesSymbols;
 			this._hasCorporateActions = hasCorporateActions;
+			this._allowFractional = allowFractional;
 			this._closeFractional = closeFractional;
 			this._roundQuantity = roundQuantity;
 			this._strictOrdering = strictOrdering;
@@ -127,6 +130,17 @@ module.exports = (() => {
 			return this._hasCorporateActions;
 		}
 
+		/**
+		 * Indicates if a position can have a fractional value; otherwise, only
+		 * integer values are allowed.
+		 *
+		 * @public
+		 * @returns {Boolean}
+		 */
+		get allowFractional() {
+			return this._allowFractional;
+		}
+
 		/**
 		 * Indicates if fractional shares should be closed when the position
 		 * size is less than one (or some of the fractional shares are closed).
@@ -209,6 +223,17 @@ module.exports = (() => {
 			return fund;
 		}
 
+		/**
+		 * A futures contract.
+		 *
+		 * @public
+		 * @static
+		 * @returns {InstrumentType}
+		 */
+		static get FUTURE() {
+			return future;
+		}
+
 		/**
 		 * An undefined asset (e.g. a house, or a collectible, or a salvaged alien spaceship).
 		 *
@@ -220,6 +245,16 @@ module.exports = (() => {
 			return other;
 		}
 
+		/**
+		 * @public
+		 * @static
+		 * @param {String} code
+		 * @returns {InstrumentType|null}
+		 */
+		static parse(code) {
+			return Enum.fromCode(InstrumentType, code);
+		}
+
 		/**
 		 * Generates an identifier for the instrument.
 		 *
@@ -229,7 +264,9 @@ module.exports = (() => {
 		 * @returns {String}
 		 */
 		static generateIdentifier(instrument) {
-			return map[instrument.type.code].generateIdentifier(instrument);
+			const type = Enum.fromCode(InstrumentType, instrument.type.code);
+
+			return type.generateIdentifier(instrument);
 		}
 
 		/**
@@ -246,6 +283,8 @@ module.exports = (() => {
 				return InstrumentType.EQUITY;
 			} else if (code === 5 || code == 15) {
 				return InstrumentType.FUND;
+			} else if (code === 2) {
+				return InstrumentType.FUTURE;
 			} else {
 				throw new Error(`Unable to determine InstrumentType for [ ${code} ]`);
 			}
@@ -256,17 +295,11 @@ module.exports = (() => {
 		}
 	}
 
-	const cash = new InstrumentType('CASH', 'cash', 'Cash', true, false, false, true, false, false, 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, (instrument) => `BARCHART-${instrument.type.code}-${instrument.symbol.barchart}`);
-	const fund = new InstrumentType('FUND', 'mutual fund', 'Funds', false, true, false, false, true, true, false, true, true, (instrument) => `BARCHART-${instrument.type.code}-${instrument.symbol.barchart}`);
-	const other = new InstrumentType('OTHER', 'other', 'Other', false, false, false, false, false, false, false, true, true, (instrument) => `BARCHART-${instrument.type.code}-${uuid.v4()}`);
-
-	const map = { };
-
-	map[cash.code] = cash;
-	map[equity.code] = equity;
-	map[fund.code] = fund;
-	map[other.code] = other;
+	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 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 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/PositionDirection.js

@@ -98,6 +98,16 @@ module.exports = (() => {
 			return even;
 		}
 
+		/**
+		 * @public
+		 * @static
+		 * @param {String} code
+		 * @returns {PositionDirection|null}
+		 */
+		static parse(code) {
+			return Enum.fromCode(PositionDirection, code);
+		}
+
 		/**
 		 * Given an open quantity, returns a {@link PositionDirection} that
 		 * describes the quantity.

package/lib/data/PositionSummaryFrame.js

@@ -174,6 +174,16 @@ module.exports = (() => {
 			return ytd;
 		}
 
+		/**
+		 * @public
+		 * @static
+		 * @param {String} code
+		 * @returns {PositionSummaryFrame|null}
+		 */
+		static parse(code) {
+			return Enum.fromCode(PositionSummaryFrame, code);
+		}
+
 		toString() {
 			return `[PositionSummaryFrame (code=${this.code})]`;
 		}

package/lib/data/TransactionType.js

@@ -493,6 +493,16 @@ module.exports = (() => {
 			return spinoffOpen;
 		}
 
+		/**
+		 * @public
+		 * @static
+		 * @param {String} code
+		 * @returns {TransactionType|null}
+		 */
+		static parse(code) {
+			return Enum.fromCode(TransactionType, code);
+		}
+
 		toString() {
 			return `[TransactionType (code=${this.code})]`;
 		}

package/lib/data/TransactionValidator.js

@@ -263,6 +263,11 @@ module.exports = (() => {
 	associateTypes(InstrumentType.FUND, TransactionType.SPINOFF, false);
 	associateTypes(InstrumentType.FUND, TransactionType.SPINOFF_OPEN, false);
 
+	associateTypes(InstrumentType.FUTURE, TransactionType.BUY, true, [ PositionDirection.LONG, PositionDirection.EVEN ]);
+	associateTypes(InstrumentType.FUTURE, TransactionType.SELL, true, [ PositionDirection.LONG ]);
+	associateTypes(InstrumentType.FUTURE, TransactionType.SELL_SHORT, true, [ PositionDirection.SHORT, PositionDirection.EVEN ]);
+	associateTypes(InstrumentType.FUTURE, 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 ]);
@@ -293,6 +298,10 @@ module.exports = (() => {
 	associateDirections(InstrumentType.FUND, PositionDirection.EVEN);
 	associateDirections(InstrumentType.FUND, PositionDirection.LONG);
 
+	associateDirections(InstrumentType.FUTURE, PositionDirection.EVEN);
+	associateDirections(InstrumentType.FUTURE, PositionDirection.LONG);
+	associateDirections(InstrumentType.FUTURE, PositionDirection.SHORT);
+
 	associateDirections(InstrumentType.OTHER, PositionDirection.EVEN);
 	associateDirections(InstrumentType.OTHER, PositionDirection.LONG);
 

package/lib/data/ValuationType.js

@@ -16,17 +16,6 @@ module.exports = (() => {
 			super(code, description);
 		}
 
-		/**
-		 * Given a code, returns the enumeration item.
-		 *
-		 * @public
-		 * @param {String} code
-		 * @returns {ValuationType|null}
-		 */
-		static parse(code) {
-			return Enum.fromCode(ValuationType, code);
-		}
-
 		/**
 		 * A valuation method that uses average costing.
 		 *
@@ -47,6 +36,17 @@ module.exports = (() => {
 			return fifo;
 		}
 
+		/**
+		 * Given a code, returns the enumeration item.
+		 *
+		 * @public
+		 * @param {String} code
+		 * @returns {ValuationType|null}
+		 */
+		static parse(code) {
+			return Enum.fromCode(ValuationType, code);
+		}
+
 		toString() {
 			return `[ValuationType (code=${this.code})]`;
 		}

package/lib/formatters/TransactionFormatter.js

@@ -50,7 +50,7 @@ module.exports = (() => {
 
 				if (instruments.hasOwnProperty(position)) {
 					let instrument = instruments[position];
-					let formatted = { instrument: instrument, raw: {} };
+					let formatted = { instrument, raw: {} };
 
 					const formatterFunctions = formatters.get(transaction.type);
 
@@ -139,7 +139,14 @@ module.exports = (() => {
 		let average;
 
 		if (basis && open && !open.getIsZero()) {
-			average = basis.divide(open).absolute();
+			if (f.instrument.type === InstrumentType.FUTURE) {
+				const minimumTick = f.instrument.future.tick;
+				const minimumTickValue = f.instrument.future.value;
+
+				average = basis.divide(open).multiply(minimumTick).divide(minimumTickValue).absolute();
+			} else {
+				average = basis.divide(open).absolute();
+			}
 		} else {
 			average = '';
 		}

package/lib/processing/PositionGroup.js

@@ -304,6 +304,22 @@ module.exports = (() => {
 			return this._excluded;
 		}
 
+		/**
+		 * Changes the group currency.
+		 *
+		 * @public
+		 * @param {Currency} currency
+		 */
+		changeCurrency(currency) {
+			assert.argumentIsRequired(currency, 'currency', Currency, 'Currency');
+
+			if (this._currency !== currency) {
+				this._currency = currency;
+
+				this.refresh();
+			}
+		}
+
 		/**
 		 * Sets the immediate parent group (allowing for calculation of relative
 		 * percentages).
@@ -442,6 +458,8 @@ module.exports = (() => {
 			}
 
 			this._dataFormat.portfolioType = portfolioType;
+
+			this.changeCurrency(this._definition.currencySelector({ portfolio }));
 		}
 
 		/**
@@ -605,6 +623,14 @@ module.exports = (() => {
 
 			this._dataActual.description = this._description;
 			this._dataFormat.description = this._description;
+
+			if (this._definition.type !== PositionLevelType.PORTFOLIO || this._key !== PositionLevelDefinition.getKeyForPortfolioGroup(portfolio)) {
+				return;
+			}
+
+			const currencySelector = this._definition.currencySelector;
+
+			this.changeCurrency(currencySelector({ portfolio }));
 		}));
 
 		this._disposeStack.push(fundamentalBinding);

package/lib/processing/PositionItem.js

@@ -464,9 +464,9 @@ module.exports = (() => {
 		data.marketPrevious2 = previousSummary2 === null ? Decimal.ZERO : previousSummary2.end.value;
 		data.quantityPrevious = previousSummary1 === null ? Decimal.ZERO : previousSummary1.end.open;
 
-		data.periodGain = calculatePeriodGain(position.instrument.type, data.initiate, currentSummary, previousSummary1);
-		data.periodGainPrevious = calculatePeriodGain(position.instrument.type, data.initiate, previousSummary1, previousSummary2);
-		data.periodGainPrevious2 = calculatePeriodGain(position.instrument.type, data.initiate, previousSummary2, previousSummary3);
+		data.periodGain = calculatePeriodGain(position.instrument, data.initiate, currentSummary, previousSummary1);
+		data.periodGainPrevious = calculatePeriodGain(position.instrument, data.initiate, previousSummary1, previousSummary2);
+		data.periodGainPrevious2 = calculatePeriodGain(position.instrument, data.initiate, previousSummary2, previousSummary3);
 
 		data.periodIncome = currentSummary !== null ? currentSummary.period.income : Decimal.ZERO;
 		data.periodRealized = currentSummary !== null ? currentSummary.period.realized : Decimal.ZERO;
@@ -478,6 +478,11 @@ module.exports = (() => {
 
 		if (snapshot.open.getIsZero()) {
 			data.basisPrice = Decimal.ZERO;
+		} else if (position.instrument.type === InstrumentType.FUTURE) {
+			const minimumTick = position.instrument.future.tick;
+			const minimumTickValue = position.instrument.future.value;
+
+			data.basisPrice = basis.divide(snapshot.open).divide(minimumTickValue).multiply(minimumTick);
 		} else {
 			data.basisPrice = basis.divide(snapshot.open);
 		}
@@ -509,6 +514,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);
@@ -544,7 +551,15 @@ module.exports = (() => {
 		let unrealizedTodayChange;
 
 		if (data.previousPrice && price) {
-			unrealizedToday = market.subtract(snapshot.open.multiply(data.previousPrice));
+			let unrealizedTodayBase;
+
+			if (position.instrument.type === InstrumentType.FUTURE) {
+				unrealizedTodayBase = getFuturesValue(position.instrument, snapshot.open, data.previousPrice);
+			} else {
+				unrealizedTodayBase = snapshot.open.multiply(data.previousPrice);
+			}
+
+			unrealizedToday = market.subtract(unrealizedTodayBase);
 
 			if (data.unrealizedToday !== null) {
 				unrealizedTodayChange = unrealizedToday.subtract(data.unrealizedToday);
@@ -576,7 +591,14 @@ module.exports = (() => {
 			}
 
 			if (priceToUse !== null) {
-				let unrealized = currentSummary.end.open.multiply(priceToUse).add(currentSummary.end.basis);
+				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);
+				}
+
 				let unrealizedChange;
 
 				if (data.unrealized !== null) {
@@ -588,7 +610,7 @@ module.exports = (() => {
 				data.unrealized = unrealized;
 				data.unrealizedChange = unrealizedChange;
 
-				let periodGain = calculatePeriodGain(position.instrument.type, data.initiate, currentSummary, previousSummary, priceToUse);
+				let periodGain = calculatePeriodGain(position.instrument, data.initiate, currentSummary, previousSummary, priceToUse);
 				let periodGainChange;
 
 				if (data.periodGain !== null) {
@@ -643,9 +665,11 @@ module.exports = (() => {
 		return direction || PositionDirection.LONG;
 	}
 
-	function calculatePeriodGain(type, direction, currentSummary, previousSummary, overridePrice) {
+	function calculatePeriodGain(instrument, direction, currentSummary, previousSummary, overridePrice) {
 		let returnRef;
 
+		const type = instrument.type;
+
 		if (currentSummary && type !== InstrumentType.CASH) {
 			let startValue;
 
@@ -658,7 +682,11 @@ module.exports = (() => {
 			let endValue;
 
 			if (overridePrice) {
-				endValue = currentSummary.end.open.multiply(overridePrice);
+				if (type === InstrumentType.FUTURE) {
+					endValue = getFuturesValue(instrument, currentSummary.end.open, overridePrice);
+				} else {
+					endValue = currentSummary.end.open.multiply(overridePrice);
+				}
 			} else {
 				endValue = currentSummary.end.value;
 			}
@@ -779,5 +807,18 @@ 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

@@ -91,6 +91,11 @@ module.exports = (() => {
 		.withField('instrument.type', DataType.forEnum(InstrumentType, 'InstrumentType'))
 		.withField('instrument.currency', DataType.forEnum(Currency, 'Currency'))
 		.withField('instrument.delist', DataType.DAY, true)
+		.withField('instrument.future.expiration', DataType.DAY, true)
+		.withField('instrument.future.tick', DataType.DECIMAL, true)
+		.withField('instrument.future.value', DataType.DECIMAL, true)
+		.withField('instrument.option.expiration', DataType.DAY, true)
+		.withField('instrument.option.strike', DataType.DECIMAL, true)
 		.withField('instrument.symbol.barchart', DataType.STRING, true)
 		.withField('instrument.symbol.display', DataType.STRING, true)
 		.withField('position', DataType.STRING)
@@ -127,6 +132,11 @@ module.exports = (() => {
 		.withField('instrument.type', DataType.forEnum(InstrumentType, 'InstrumentType'))
 		.withField('instrument.currency', DataType.forEnum(Currency, 'Currency'))
 		.withField('instrument.delist', DataType.DAY, true)
+		.withField('instrument.future.expiration', DataType.DAY, true)
+		.withField('instrument.future.tick', DataType.DECIMAL, true)
+		.withField('instrument.future.value', DataType.DECIMAL, true)
+		.withField('instrument.option.expiration', DataType.DAY, true)
+		.withField('instrument.option.strike', 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.17.0",
+  "version": "1.18.0",
   "description": "Common JavaScript code used by Barchart's Portfolio Service",
   "author": {
     "name": "Bryan Ingle",
@@ -16,6 +16,7 @@
   },
   "dependencies": {
     "@barchart/common-js": "^4.27.0",
+    "@barchart/marketdata-api-js": "^6.1.0",
     "uuid": "^8.3.2"
   },
   "devDependencies": {