@barchart/portfolio-api-common 1.27.1 → 1.28.0

package/lib/data/PositionSummaryFrame.js

@@ -14,6 +14,7 @@ module.exports = (() => {
 	 * @extends {Enum}
 	 * @param {String} code
 	 * @param {String} description
+	 * @param {Boolean} unique
 	 * @param {Function} rangeCalculator
 	 * @param {Function} startDateCalculator
 	 * @param {Function} descriptionCalculator
@@ -91,7 +92,7 @@ module.exports = (() => {
 		 *
 		 * @public
 		 * @param {Day} date
-		 * @return {PositionSummaryRange[]}
+		 * @returns {PositionSummaryRange[]}
 		 */
 		getRangesFromDate(date) {
 			assert.argumentIsRequired(date, 'date', Day, 'Day');
@@ -108,6 +109,7 @@ module.exports = (() => {
 		 * @public
 		 * @param {Day} date
 		 * @param {Number} periods
+		 * @returns {PositionSummaryRange[]}
 		 */
 		getPriorRanges(date, periods) {
 			assert.argumentIsRequired(date, 'date', Day, 'Day');
@@ -138,6 +140,7 @@ module.exports = (() => {
 		 * A summary for a calendar year.
 		 *
 		 * @public
+		 * @static
 		 * @returns {PositionSummaryFrame}
 		 */
 		static get YEARLY() {
@@ -148,6 +151,7 @@ module.exports = (() => {
 		 * A summary for a quarter.
 		 *
 		 * @public
+		 * @static
 		 * @returns {PositionSummaryFrame}
 		 */
 		static get QUARTERLY() {
@@ -158,6 +162,7 @@ module.exports = (() => {
 		 * A summary for a calendar month.
 		 *
 		 * @public
+		 * @static
 		 * @returns {PositionSummaryFrame}
 		 */
 		static get MONTHLY() {
@@ -168,6 +173,7 @@ module.exports = (() => {
 		 * A summary the current year (to date).
 		 *
 		 * @public
+		 * @static
 		 * @returns {PositionSummaryFrame}
 		 */
 		static get YTD() {
@@ -175,6 +181,9 @@ module.exports = (() => {
 		}
 
 		/**
+		 * Returns the {@link PositionSummaryFrame} instance that matches the code
+		 * provided.
+		 *
 		 * @public
 		 * @static
 		 * @param {String} code
@@ -214,10 +223,7 @@ module.exports = (() => {
 	 */
 
 	function getRange(start, end) {
-		return {
-			start: start,
-			end: end
-		};
+		return { start, end };
 	}
 
 	function getYearlyRanges(transactions) {

package/lib/processing/PositionContainer.js

@@ -87,6 +87,8 @@ module.exports = (() => {
 			}, { });
 
 			if (reportFrame) {
+				this._referenceDate = reportDate;
+
 				this._currentSummaryFrame = reportFrame;
 				this._currentSummaryRange = array.last(this._currentSummaryFrame.getPriorRanges(reportDate, 0));
 
@@ -95,6 +97,8 @@ module.exports = (() => {
 
 				this._previousSummaryRanges.pop();
 			} else {
+				this._referenceDate = Day.getToday();
+
 				this._currentSummaryFrame = PositionSummaryFrame.YTD;
 				this._currentSummaryRange = array.first(this._currentSummaryFrame.getRecentRanges(0));
 
@@ -507,7 +511,7 @@ module.exports = (() => {
 		 *
 		 * @public
 		 * @param {Object} position
-		 * @return {Boolean}
+		 * @returns {Boolean}
 		 */
 		getPositionLock(position) {
 			assert.argumentIsRequired(position, 'position', Object);
@@ -542,7 +546,7 @@ module.exports = (() => {
 		 *
 		 * @public
 		 * @param {Object} position
-		 * @return {Boolean}
+		 * @returns {Boolean}
 		 */
 		getPositionCalculating(position) {
 			assert.argumentIsRequired(position, 'position', Object);
@@ -583,7 +587,14 @@ module.exports = (() => {
 
 					if (symbol) {
 						const rate = Rate.fromPair(quote.lastPrice, symbol);
-						const index = this._forexQuotes.findIndex(existing => existing.formatPair() === rate.formatPair());
+
+						let index = this._forexQuotes.findIndex(existing => existing.formatPair() === rate.formatPair());
+
+						if (index < 0) {
+							const inverted = rate.invert();
+
+							index = this._forexQuotes.findIndex(existing => existing.formatPair() === inverted.formatPair());
+						}
 
 						if (index < 0) {
 							this._forexQuotes.push(rate);
@@ -591,13 +602,13 @@ module.exports = (() => {
 							this._forexQuotes[index] = rate;
 						}
 
-						Object.keys(this._trees).forEach((key) => {
-							this._trees[key].walk(group => group.setForexRates(this._forexQuotes), true, false);
-						});
-
 						recalculatePercentages.call(this);
 					}
 				});
+
+				Object.keys(this._trees).forEach((key) => {
+					this._trees[key].walk(group => group.setForexRates(this._forexQuotes), true, false);
+				});
 			}
 
 			if (positionQuotes.length !== 0 || forexQuotes.length !== 0) {
@@ -608,8 +619,9 @@ module.exports = (() => {
 		/**
 		 * Returns current price for symbol provided.
 		 *
+		 * @public
 		 * @param {String} symbol
-		 * @return {null|Number}
+		 * @returns {null|Number}
 		 */
 		getCurrentPrice(symbol) {
 			assert.argumentIsRequired(symbol, 'symbol', String);
@@ -1096,7 +1108,7 @@ module.exports = (() => {
 			const previousSummaries = this._summariesPrevious[ position.position ] || getSummaryArray(this._previousSummaryRanges);
 
 			if (!requireCurrentSummary || currentSummary !== null) {
-				returnRef = new PositionItem(portfolio, position, currentSummary, previousSummaries, this._reporting);
+				returnRef = new PositionItem(portfolio, position, currentSummary, previousSummaries, this._reporting, this._referenceDate);
 			} else {
 				returnRef = null;
 			}
@@ -1158,4 +1170,4 @@ module.exports = (() => {
 	}
 
 	return PositionContainer;
-})();
+})();

package/lib/processing/PositionGroup.js

@@ -76,6 +76,7 @@ module.exports = (() => {
 			this._dataFormat.invalid = false;
 			this._dataFormat.locked = false;
 			this._dataFormat.calculating = false;
+			this._dataFormat.expired = false;
 			this._dataFormat.newsExists = false;
 			this._dataFormat.quantity = null;
 			this._dataFormat.quantityPrevious = null;
@@ -292,7 +293,7 @@ module.exports = (() => {
 		}
 
 		/**
-		 * Indicates if the group will only contain one {@link PositionItem} -- that is,
+		 * Indicates if the group will only contain one {@link PositionItem} — that is,
 		 * indicates if the group represents a single position.
 		 *
 		 * @public
@@ -585,7 +586,7 @@ module.exports = (() => {
 								if (summary.count > 0) {
 									averageFormat = formatPercent(new Decimal(summary.total / summary.count), 2, true);
 								} else {
-									averageFormat = '--';
+									averageFormat = '—';
 								}
 
 								summary.averageFormat = averageFormat;
@@ -595,7 +596,7 @@ module.exports = (() => {
 
 					return sums;
 				}, fundamentalFields.reduce((sums, fieldName) => {
-					sums[fieldName] = { total: 0, count: 0, averageFormat: '--' };
+					sums[fieldName] = { total: 0, count: 0, averageFormat: '—' };
 
 					return sums;
 				}, { }));
@@ -876,6 +877,7 @@ module.exports = (() => {
 			format.invalid = definition.type === PositionLevelType.POSITION && item.invalid;
 			format.locked = definition.type === PositionLevelType.POSITION && item.data.locked;
 			format.calculating = definition.type === PositionLevelType.POSITION && item.data.calculating;
+			format.expired = definition.type === PositionLevelType.POSITION && item.data.expired;
 		}
 
 		let portfolioType = null;

package/lib/processing/PositionItem.js

@@ -25,9 +25,10 @@ module.exports = (() => {
 	 * @param {Object} currentSummary
 	 * @param {Object[]} previousSummaries
 	 * @param {Boolean} reporting
+	 * @param {Day} referenceDate
 	 */
 	class PositionItem extends Disposable {
-		constructor(portfolio, position, currentSummary, previousSummaries, reporting) {
+		constructor(portfolio, position, currentSummary, previousSummaries, reporting, referenceDate) {
 			super();
 
 			this._portfolio = portfolio;
@@ -107,6 +108,7 @@ module.exports = (() => {
 			this._data.fundamental = { };
 			this._data.calculating = getIsCalculating(position);
 			this._data.locked = getIsLocked(position);
+			this._data.expired = getIsExpired(position, referenceDate);
 
 			this._quoteChangedEvent = new Event(this);
 			this._newsExistsChangedEvent = new Event(this);
@@ -505,6 +507,13 @@ module.exports = (() => {
 
 		const data = item._data;
 
+		// 2023/11/28, BRI. Futures contracts do not have their value set to zero
+		// after expiration. At expiration, the contract would have been closed
+		// (but the price would not have been zero). On the other hand, option
+		// contracts can expire worthless and we attempt to represent that here.
+
+		const worthless = data.expired && (position.instrument.type === InstrumentType.EQUITY_OPTION || position.instrument.type === InstrumentType.FUTURE_OPTION);
+
 		let market;
 
 		if (position.instrument.type === InstrumentType.OTHER) {
@@ -512,7 +521,15 @@ module.exports = (() => {
 		} else if (position.instrument.type === InstrumentType.CASH) {
 			market = snapshot.open;
 		} else {
-			market = ValuationCalculator.calculate(position.instrument, price, snapshot.open) || snapshot.value;
+			let priceToUse;
+
+			if (worthless) {
+				priceToUse = Decimal.ZERO;
+			} else {
+				priceToUse = price;
+			}
+
+			market = ValuationCalculator.calculate(position.instrument, priceToUse, snapshot.open) || snapshot.value;
 		}
 
 		let marketChange;
@@ -565,7 +582,9 @@ module.exports = (() => {
 		if (currentSummary && position.instrument.type !== InstrumentType.CASH) {
 			let priceToUse;
 
-			if (price) {
+			if (worthless) {
+				priceToUse = Decimal.ZERO;
+			} else if (price) {
 				priceToUse = price;
 			} else if (data.previousPrice) {
 				priceToUse = new Decimal(data.previousPrice);
@@ -762,11 +781,29 @@ module.exports = (() => {
 	}
 
 	function getIsCalculating(position) {
-		assert.argumentIsRequired(position, 'position', Object);
+		assert.argumentIsRequired(position, 'position');
 
 		return is.object(position.system) && is.object(position.system.calculate) && is.number(position.system.calculate.processors) &&	position.system.calculate.processors > 0;
 	}
 
+	function getIsExpired(position, day) {
+		assert.argumentIsRequired(position, 'position');
+
+		const type = position.instrument.type;
+
+		let expiration;
+
+		if (type === InstrumentType.FUTURE) {
+			expiration = position.instrument.future.expiration;
+		} else if (type === InstrumentType.FUTURE_OPTION || type === InstrumentType.EQUITY_OPTION) {
+			expiration = position.instrument.option.expiration;
+		} else {
+			expiration = null;
+		}
+
+		return expiration !== null && expiration.getIsBefore(day);
+	}
+
 	function getSnapshot(position, currentSummary, reporting) {
 		let snapshot;
 

package/lib/providers/InstrumentProvider.js

@@ -37,7 +37,7 @@ module.exports = (() => {
 				.then(() => {
 					assert.argumentIsRequired(symbol, 'symbol', String);
 
-					return promise.timeout(Gateway.invoke(getInstrumentLookupEndpoint(), {symbol}), MAXIMUM_WAIT_BEFORE_TIMEOUT_IN_MILLISECONDS, 'instrument lookup')
+					return promise.timeout(Gateway.invoke(instrumentLookupEndpoint, { symbol }), MAXIMUM_WAIT_BEFORE_TIMEOUT_IN_MILLISECONDS, 'instrument lookup')
 							.catch((e) => {
 								let message;
 
@@ -63,32 +63,18 @@ module.exports = (() => {
 		}
 	}
 
-	function buildInstrumentLookupEndpoint(host) {
-		return EndpointBuilder.for('query-instrument', 'query instrument')
-			.withVerb(VerbType.GET)
-			.withProtocol(ProtocolType.HTTPS)
-			.withHost(host)
-			.withPort(443)
-			.withPathBuilder((pb) => {
-				pb.withLiteralParameter('instruments', 'instruments')
-					.withVariableParameter('symbol', 'symbol', 'symbol');
-			})
-			.withResponseInterceptor(ResponseInterceptor.DATA)
-			.withErrorInterceptor(ErrorInterceptor.GENERAL)
-			.endpoint;
-	}
-
-	const instrumentLookupEndpoints = new Map();
-
-	function getInstrumentLookupEndpoint() {
-		const host = 'instruments-prod.aws.barchart.com';
-
-		if (!instrumentLookupEndpoints.has(host)) {
-			instrumentLookupEndpoints.set(host, buildInstrumentLookupEndpoint(host));
-		}
-
-		return instrumentLookupEndpoints.get(host);
-	}
+	const instrumentLookupEndpoint = EndpointBuilder.for('query-instrument', 'query instrument')
+		.withVerb(VerbType.GET)
+		.withProtocol(ProtocolType.HTTPS)
+		.withHost('instruments-prod.aws.barchart.com')
+		.withPort(443)
+		.withPathBuilder((pb) => {
+			pb.withLiteralParameter('instruments', 'instruments')
+				.withVariableParameter('symbol', 'symbol', 'symbol');
+		})
+		.withResponseInterceptor(ResponseInterceptor.DATA)
+		.withErrorInterceptor(ErrorInterceptor.GENERAL)
+		.endpoint;
 
 	return InstrumentProvider;
 })();

package/lib/providers/InstrumentProviderCache.js

@@ -13,7 +13,7 @@ module.exports = (() => {
 	 *
 	 * @public
 	 * @param {InstrumentProvider} provider
-	 * @param {Number} cacheDuration - The maximum number of milliseconds to cache an instrument.
+	 * @param {Number=} cacheDuration - The maximum number of milliseconds to cache an instrument.
 	 */
 	class InstrumentProviderCache {
 		constructor(provider, cacheDuration) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barchart/portfolio-api-common",
-  "version": "1.27.1",
+  "version": "1.28.0",
   "description": "Common JavaScript code used by Barchart's Portfolio Service",
   "author": {
     "name": "Bryan Ingle",