@barchart/portfolio-api-common 1.27.2 → 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);
@@ -615,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);
@@ -1103,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;
 			}
@@ -1165,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;
@@ -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/package.json

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