@barchart/portfolio-api-common 1.7.0 → 1.10.0

package/.releases/1.10.0.md

@@ -0,0 +1,3 @@
+**New Features**
+
+* Added a new `PortfolioFailureType` for negative quantity.

package/.releases/1.8.0.md

@@ -0,0 +1,3 @@
+**New Features**
+
+* Added a new `PortfolioFailureType` for attempts to switch to dividend reinvestment when the position is short.

package/.releases/1.9.0.md

@@ -0,0 +1,4 @@
+**New Features**
+
+* Added `close` field to the `Sell` transaction schema.
+* Added `close` field to the `Buy Short` transaction schema.

package/.releases/1.9.1.md

@@ -0,0 +1,4 @@
+**Bug Fixes**
+
+* Made `quantity` field optional for the `Sell` transaction schema.
+* Made `quantity` field optional for the `Buy Short` transaction schema.

package/lib/api/failures/PortfolioFailureType.js

@@ -154,6 +154,17 @@ module.exports = (() => {
 			return transactionCreateFailedInvalidInitialType;
 		}
 
+		/**
+		 * A transaction quantity cannot have a negative amount.
+		 *
+		 * @public
+		 * @static
+		 * @returns {FailureType}
+		 */
+		static get TRANSACTION_CREATE_FAILED_QUANTITY_NEGATIVE() {
+			return transactionCreateFailedQuantityNegative;
+		}
+
 		/**
 		 * A valuation transaction cannot have a negative rate (or amount).
 		 *
@@ -349,6 +360,28 @@ module.exports = (() => {
 			return transactionEditFailedTypeChanged;
 		}
 
+		/**
+		 * Conversion of transaction type is unsupported.
+		 *
+		 * @public
+		 * @static
+		 * @returns {FailureType}
+		 */
+		static get TRANSACTION_SWITCH_FAILED_INVALID_CONVERSION() {
+			return transactionSwitchFailedInvalidConversion;
+		}
+
+		/**
+		 * Conversion of transaction type is not allowed. Dividends (or distributions)
+		 * cannot be reinvested when the position is short.
+		 *
+		 * @public
+		 * @static
+		 * @returns {FailureType}
+		 */
+		static get TRANSACTION_SWITCH_FAILED_INVALID_REINVEST() {
+			return transactionSwitchFailedInvalidReinvest;
+		}
 
 		toString() {
 			return '[PortfolioFailureType]';
@@ -370,6 +403,7 @@ module.exports = (() => {
 	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.', false);
+	const transactionCreateFailedQuantityNegative = new FailureType('TRANSACTION_CREATE_FAILED_QUANTITY_NEGATIVE', 'Unable to process transaction, quantity cannot be negative.');
 	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);
@@ -389,7 +423,10 @@ module.exports = (() => {
 	const transactionEditFailedInvalidDate = new FailureType('TRANSACTION_EDIT_FAILED_INVALID_DATE', 'Unable to edit transaction with given date.');
 	const transactionEditFailedNoTransaction = new FailureType('TRANSACTION_EDIT_FAILED_NO_TRANSACTION', 'Unable to edit transaction. The referenced transaction does not exist.', false);
 	const transactionEditFailedTypeReserved = new FailureType('TRANSACTION_EDIT_FAILED_TYPE_RESERVED', 'Unable to edit {U|type.description} transaction, this type of transaction is managed by the system.');
-	const transactionEditFailedTypeChanged = new FailureType('TRANSACTION_EDIT_FAILED_TYPE_CHANGED', 'Changing a transaction type is forbidden. You must delete the existing transaction then recreate it.');
+	const transactionEditFailedTypeChanged = new FailureType('TRANSACTION_EDIT_FAILED_TYPE_CHANGED', 'Changing a transaction type is forbidden. You must delete the existing transaction and then create a new transaction.');
+
+	const transactionSwitchFailedInvalidConversion = new FailureType('TRANSACTION_SWITCH_FAILED_INVALID_CONVERSION', 'Unable to convert transaction from {U|existing.description} to {U|desired.description}. This conversion is not supported.');
+	const transactionSwitchFailedInvalidReinvest = new FailureType('TRANSACTION_SWITCH_FAILED_INVALID_REINVEST', 'Unable to convert transaction from {U|existing.description} to {U|desired.description}. Reinvestment is not supported for short positions.');
 
 	return PortfolioFailureType;
 })();

package/lib/serialization/TransactionSchema.js

@@ -247,9 +247,10 @@ module.exports = (() => {
 		.withField('type', DataType.forEnum(TransactionType, 'TransactionType'))
 		.withField('date', DataType.DAY)
 		.withField('price', DataType.DECIMAL, true)
-		.withField('quantity', DataType.DECIMAL)
+		.withField('quantity', DataType.DECIMAL, true)
 		.withField('fee', DataType.DECIMAL, true)
 		.withField('force', DataType.BOOLEAN, true)
+		.withField('close', DataType.BOOLEAN, true)
 		.schema
 	);
 
@@ -260,9 +261,10 @@ module.exports = (() => {
 		.withField('type', DataType.forEnum(TransactionType, 'TransactionType'))
 		.withField('date', DataType.DAY)
 		.withField('price', DataType.DECIMAL)
-		.withField('quantity', DataType.DECIMAL)
+		.withField('quantity', DataType.DECIMAL, true)
 		.withField('fee', DataType.DECIMAL, true)
 		.withField('force', DataType.BOOLEAN, true)
+		.withField('close', DataType.BOOLEAN, true)
 		.schema
 	);
 

package/package.json

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

package/test/SpecRunner.js

@@ -5456,9 +5456,10 @@ module.exports = (() => {
 		.withField('type', DataType.forEnum(TransactionType, 'TransactionType'))
 		.withField('date', DataType.DAY)
 		.withField('price', DataType.DECIMAL, true)
-		.withField('quantity', DataType.DECIMAL)
+		.withField('quantity', DataType.DECIMAL, true)
 		.withField('fee', DataType.DECIMAL, true)
 		.withField('force', DataType.BOOLEAN, true)
+		.withField('close', DataType.BOOLEAN, true)
 		.schema
 	);
 
@@ -5469,9 +5470,10 @@ module.exports = (() => {
 		.withField('type', DataType.forEnum(TransactionType, 'TransactionType'))
 		.withField('date', DataType.DAY)
 		.withField('price', DataType.DECIMAL)
-		.withField('quantity', DataType.DECIMAL)
+		.withField('quantity', DataType.DECIMAL, true)
 		.withField('fee', DataType.DECIMAL, true)
 		.withField('force', DataType.BOOLEAN, true)
+		.withField('close', DataType.BOOLEAN, true)
 		.schema
 	);
 
@@ -5692,7 +5694,7 @@ module.exports = (() => {
 
 
     push(item) {
-      this._array.unshift(item);
+      this._array.push(item);
 
       return item;
     }
@@ -5709,7 +5711,7 @@ module.exports = (() => {
         throw new Error('Stack is empty');
       }
 
-      return this._array.shift();
+      return this._array.pop();
     }
     /**
      * Returns the next item in the stack (without removing it). Throws if the stack is empty.
@@ -5724,7 +5726,7 @@ module.exports = (() => {
         throw new Error('Stack is empty');
       }
 
-      return this._array[0];
+      return this._array[this._array.length - 1];
     }
     /**
      * Returns true if the queue is empty; otherwise false.
@@ -5748,10 +5750,12 @@ module.exports = (() => {
     scan(action) {
       assert.argumentIsRequired(action, 'action', Function);
 
-      this._array.forEach(x => action(x));
+      for (let i = this._array.length - 1; i >= 0; i--) {
+        action(this._array[i]);
+      }
     }
     /**
-     * Outputs an array of the stacks's items; without affecting the
+     * Outputs an array of the stack's items; without affecting the
      * queue's internal state;
      *
      * @public
@@ -5760,7 +5764,7 @@ module.exports = (() => {
 
 
     toArray() {
-      return this._array.slice(0);
+      return this._array.slice(0).reverse();
     }
 
     toString() {
@@ -8203,8 +8207,11 @@ const moment = require('moment-timezone');
 
 module.exports = (() => {
   'use strict';
+
+  const MILLISECONDS_PER_SECOND = 1000;
   /**
-   * A data structure encapsulates (and lazy loads) a moment (see https://momentjs.com/).
+   * An immutable data structure that encapsulates (and lazy loads)
+   * a moment (see https://momentjs.com/).
    *
    * @public
    * @param {Number} timestamp
@@ -8220,7 +8227,7 @@ module.exports = (() => {
       this._moment = null;
     }
     /**
-     * The timestamp.
+     * The timestamp (milliseconds since epoch).
      *
      * @public
      * @returns {Number}
@@ -8249,6 +8256,34 @@ module.exports = (() => {
 
       return this._moment;
     }
+    /**
+     * Returns a new {@link Timestamp} instance shifted forward (or backward)
+     * by a specific number of seconds.
+     *
+     * @public
+     * @param {Number} milliseconds
+     * @returns {Timestamp}
+     */
+
+
+    add(milliseconds) {
+      assert.argumentIsRequired(milliseconds, 'seconds', Number);
+      return new Timestamp(this._timestamp + milliseconds, this._timezone);
+    }
+    /**
+     * Returns a new {@link Timestamp} instance shifted forward (or backward)
+     * by a specific number of seconds.
+     *
+     * @public
+     * @param {Number} seconds
+     * @returns {Timestamp}
+     */
+
+
+    addSeconds(seconds) {
+      assert.argumentIsRequired(seconds, 'seconds', Number);
+      return this.add(seconds * MILLISECONDS_PER_SECOND);
+    }
     /**
      * Returns the JSON representation.
      *
@@ -8550,7 +8585,8 @@ module.exports = (() => {
     },
 
     /**
-     * Set difference operation (using strict equality).
+     * Set difference operation, returning any item in "a" that is not
+     * contained in "b" (using strict equality).
      *
      * @static
      * @param {Array} a
@@ -8562,7 +8598,8 @@ module.exports = (() => {
     },
 
     /**
-     * Set difference operation, where the uniqueness is determined by a delegate.
+     * Set difference operation, returning any item in "a" that is not
+     * contained in "b" (where the uniqueness is determined by a delegate).
      *
      * @static
      * @param {Array} a
@@ -9465,6 +9502,7 @@ module.exports = (() => {
   /**
    * An implementation of the observer pattern.
    *
+   * @public
    * @param {*} sender - The object which owns the event.
    * @extends {Disposable}
    */
@@ -9538,6 +9576,7 @@ module.exports = (() => {
     /**
      * Returns true, if no handlers are currently registered.
      *
+     * @public
      * @returns {boolean}
      */
 
@@ -17584,8 +17623,8 @@ describe('After the PositionSummaryFrame enumeration is initialized', () => {
 			ranges = PositionSummaryFrame.YEARLY.getRanges(transactions);
 		});
 
-		it('should have four ranges (assuming the current year is 2020)', () => {
-			expect(ranges.length).toEqual(5);
+		it('should have six ranges (assuming the current year is 2021)', () => {
+			expect(ranges.length).toEqual(6);
 		});
 
 		it('the first range should be from 12-31-2014 to 12-31-2015', () => {
@@ -17971,7 +18010,7 @@ describe('After the PositionSummaryFrame enumeration is initialized', () => {
 		});
 	});
 
-	describe('and a year-to-date position summary ranges are processed for a transaction set that opened last year and has not yet closed (assuming its 2020)', () => {
+	describe('and a year-to-date position summary ranges are processed for a transaction set that opened last year and has not yet closed (assuming its 2021)', () => {
 		let ranges;
 
 		beforeEach(() => {
@@ -17992,9 +18031,9 @@ describe('After the PositionSummaryFrame enumeration is initialized', () => {
 			expect(ranges.length).toEqual(1);
 		});
 
-		it('the first range should be from 12-31-2019 to 12-31-2020', () => {
-			expect(ranges[0].start.format()).toEqual('2019-12-31');
-			expect(ranges[0].end.format()).toEqual('2020-12-31');
+		it('the first range should be from 12-31-2020 to 12-31-2021', () => {
+			expect(ranges[0].start.format()).toEqual('2020-12-31');
+			expect(ranges[0].end.format()).toEqual('2021-12-31');
 		});
 	});
 
@@ -18004,14 +18043,14 @@ describe('After the PositionSummaryFrame enumeration is initialized', () => {
 		beforeEach(() => {
 			const transactions = [
 				{
-					date: new Day(2020, 1, 1),
+					date: new Day(2021, 1, 1),
 					snapshot: {
 						open: new Decimal(1)
 					},
 					type: TransactionType.BUY
 				},
 				{
-					date: new Day(2020, 1, 2),
+					date: new Day(2021, 1, 2),
 					snapshot: {
 						open: new Decimal(0)
 					},
@@ -18026,9 +18065,9 @@ describe('After the PositionSummaryFrame enumeration is initialized', () => {
 			expect(ranges.length).toEqual(1);
 		});
 
-		it('the first range should be from 12-31-2019 to 12-31-2020', () => {
-			expect(ranges[0].start.format()).toEqual('2019-12-31');
-			expect(ranges[0].end.format()).toEqual('2020-12-31');
+		it('the first range should be from 12-31-2020 to 12-31-2021', () => {
+			expect(ranges[0].start.format()).toEqual('2020-12-31');
+			expect(ranges[0].end.format()).toEqual('2021-12-31');
 		});
 	});
 

package/test/specs/data/PositionSummaryFrameSpec.js

@@ -31,8 +31,8 @@ describe('After the PositionSummaryFrame enumeration is initialized', () => {
 			ranges = PositionSummaryFrame.YEARLY.getRanges(transactions);
 		});
 
-		it('should have four ranges (assuming the current year is 2020)', () => {
-			expect(ranges.length).toEqual(5);
+		it('should have six ranges (assuming the current year is 2021)', () => {
+			expect(ranges.length).toEqual(6);
 		});
 
 		it('the first range should be from 12-31-2014 to 12-31-2015', () => {
@@ -418,7 +418,7 @@ describe('After the PositionSummaryFrame enumeration is initialized', () => {
 		});
 	});
 
-	describe('and a year-to-date position summary ranges are processed for a transaction set that opened last year and has not yet closed (assuming its 2020)', () => {
+	describe('and a year-to-date position summary ranges are processed for a transaction set that opened last year and has not yet closed (assuming its 2021)', () => {
 		let ranges;
 
 		beforeEach(() => {
@@ -439,9 +439,9 @@ describe('After the PositionSummaryFrame enumeration is initialized', () => {
 			expect(ranges.length).toEqual(1);
 		});
 
-		it('the first range should be from 12-31-2019 to 12-31-2020', () => {
-			expect(ranges[0].start.format()).toEqual('2019-12-31');
-			expect(ranges[0].end.format()).toEqual('2020-12-31');
+		it('the first range should be from 12-31-2020 to 12-31-2021', () => {
+			expect(ranges[0].start.format()).toEqual('2020-12-31');
+			expect(ranges[0].end.format()).toEqual('2021-12-31');
 		});
 	});
 
@@ -451,14 +451,14 @@ describe('After the PositionSummaryFrame enumeration is initialized', () => {
 		beforeEach(() => {
 			const transactions = [
 				{
-					date: new Day(2020, 1, 1),
+					date: new Day(2021, 1, 1),
 					snapshot: {
 						open: new Decimal(1)
 					},
 					type: TransactionType.BUY
 				},
 				{
-					date: new Day(2020, 1, 2),
+					date: new Day(2021, 1, 2),
 					snapshot: {
 						open: new Decimal(0)
 					},
@@ -473,9 +473,9 @@ describe('After the PositionSummaryFrame enumeration is initialized', () => {
 			expect(ranges.length).toEqual(1);
 		});
 
-		it('the first range should be from 12-31-2019 to 12-31-2020', () => {
-			expect(ranges[0].start.format()).toEqual('2019-12-31');
-			expect(ranges[0].end.format()).toEqual('2020-12-31');
+		it('the first range should be from 12-31-2020 to 12-31-2021', () => {
+			expect(ranges[0].start.format()).toEqual('2020-12-31');
+			expect(ranges[0].end.format()).toEqual('2021-12-31');
 		});
 	});