@barchart/portfolio-api-common 1.26.1 → 1.27.0

package/lib/processing/PositionContainer.js

@@ -662,6 +662,7 @@ module.exports = (() => {
 		 *
 		 * @public
 		 * @param {String} symbol
+		 * @param {Boolean} display
 		 * @param {Object} data
 		 */
 		setPositionFundamentalData(symbol, display, data) {
@@ -718,7 +719,7 @@ module.exports = (() => {
 		 */
 		getGroup(name, keys) {
 			assert.argumentIsRequired(name, 'name', String);
-			assert.argumentIsArray(keys, 'keys', Number);
+			assert.argumentIsArray(keys, 'keys', String);
 
 			return findNode(this._trees[name], keys).getValue();
 		}
@@ -734,7 +735,7 @@ module.exports = (() => {
 		 */
 		getGroups(name, keys) {
 			assert.argumentIsRequired(name, 'name', String);
-			assert.argumentIsArray(keys, 'keys', Number);
+			assert.argumentIsArray(keys, 'keys', String);
 
 			return findNode(this._trees[name], keys).getChildren().map(node => node.getValue());
 		}
@@ -743,7 +744,7 @@ module.exports = (() => {
 		 * Returns the immediate parent {@link PositionGroup} of a {@link PositionGroup}.
 		 *
 		 * @public
-		 * @param {PositionGroup} position
+		 * @param {PositionGroup} group
 		 * @returns {PositionGroup|null}
 		 */
 		getParentGroup(group) {
@@ -756,7 +757,7 @@ module.exports = (() => {
 		 * Returns the a parent {@link PositionGroup} which represents a portfolio.
 		 *
 		 * @public
-		 * @param {PositionGroup} position
+		 * @param {PositionGroup} group
 		 * @returns {PositionGroup|null}
 		 */
 		getParentGroupForPortfolio(group) {

package/lib/processing/PositionGroup.js

@@ -265,7 +265,7 @@ module.exports = (() => {
 		 * The {@link PositionItem} instances which for which aggregated data is compiled.
 		 *
 		 * @public
-		 * @returns {Currency}
+		 * @returns {PositionItem[]}
 		 */
 		get items() {
 			return this._items;

package/lib/processing/definitions/PositionLevelDefinition.js

@@ -16,6 +16,7 @@ module.exports = (() => {
 	 *
 	 * @public
 	 * @param {String} name
+	 * @param {PositionLevelType} type
 	 * @param {PositionLevelDefinition~keySelector} keySelector
 	 * @param {PositionLevelDefinition~descriptionSelector} descriptionSelector
 	 * @param {PositionLevelDefinition~currencySelector} currencySelector
@@ -173,6 +174,15 @@ module.exports = (() => {
 			};
 		}
 
+		/**
+		 * Generates the key for a {@link PositionGroup}, representing a portfolio, held
+		 * within a {@link PositionContainer}.
+		 *
+		 * @public
+		 * @static
+		 * @param {Object} portfolio
+		 * @returns {String}
+		 */
 		static getKeyForPortfolioGroup(portfolio) {
 			assert.argumentIsRequired(portfolio, 'portfolio', Object);
 
@@ -217,6 +227,16 @@ module.exports = (() => {
 			};
 		}
 
+		/**
+		 * Generates the key for a {@link PositionGroup}, representing a grouping of positions
+		 * by asset class, held within a {@link PositionContainer}.
+		 *
+		 * @public
+		 * @static
+		 * @param {InstrumentType} type
+		 * @param {Currency} currency
+		 * @returns {String}
+		 */
 		static getKeyForAssetClassGroup(type, currency) {
 			assert.argumentIsRequired(type, 'type', InstrumentType, 'InstrumentType');
 			assert.argumentIsRequired(currency, 'currency', Currency, 'Currency');

package/lib/providers/InstrumentProvider.js

@@ -0,0 +1,98 @@
+const assert = require('@barchart/common-js/lang/assert'),
+	is = require('@barchart/common-js/lang/is'),
+	promise = require('@barchart/common-js/lang/promise');
+
+const EndpointBuilder = require('@barchart/common-js/api/http/builders/EndpointBuilder'),
+	ErrorInterceptor = require('@barchart/common-js/api/http/interceptors/ErrorInterceptor'),
+	Gateway = require('@barchart/common-js/api/http/Gateway'),
+	ProtocolType = require('@barchart/common-js/api/http/definitions/ProtocolType'),
+	ResponseInterceptor = require('@barchart/common-js/api/http/interceptors/ResponseInterceptor'),
+	VerbType = require('@barchart/common-js/api/http/definitions/VerbType');
+
+module.exports = (() => {
+	'use strict';
+
+	const MAXIMUM_WAIT_BEFORE_TIMEOUT_IN_MILLISECONDS = 3 * 1000;
+
+	const cache = { };
+
+	/**
+	 * A utility that downloads instrument metadata (i.e. instrument "profile" data).
+	 *
+	 * @public
+	 */
+	class InstrumentProvider {
+		constructor() {
+		}
+
+		/**
+		 * Returns a promise for instrument metadata (i.e. "profile" data). If no instrument
+		 * can be found with a matching symbol, the promise is rejected.
+		 *
+		 * @public
+		 * @async
+		 * @param {String} symbol
+		 * @returns {Promise<Object>}
+		 */
+		async getInstrument(symbol) {
+			return Promise.resolve()
+				.then(() => {
+					assert.argumentIsRequired(symbol, 'symbol', String);
+
+					return promise.timeout(Gateway.invoke(getInstrumentLookupEndpoint(), {symbol}), MAXIMUM_WAIT_BEFORE_TIMEOUT_IN_MILLISECONDS, 'instrument lookup')
+							.catch((e) => {
+								delete cache[symbol];
+
+								let message;
+
+								if (is.string(e) && e === 'timeout') {
+									message = `Instrument lookup for [ ${symbol} ] failed due to timed out`;
+								} else {
+									message = `Instrument lookup for [ ${symbol} ] failed due to an unspecified error`;
+								}
+
+								return Promise.reject(message);
+							}).then((result) => {
+								if (result.instrument === null) {
+									return Promise.reject(`Instrument lookup for [ ${symbol} ] failed, the instrument does not exist`);
+								}
+
+								return result;
+							});
+				});
+		}
+
+		toString() {
+			return '[InstrumentProvider]';
+		}
+	}
+
+	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);
+	}
+
+	return InstrumentProvider;
+})();

package/lib/providers/InstrumentProviderCache.js

@@ -0,0 +1,66 @@
+const assert = require('@barchart/common-js/lang/assert'),
+	TimeMap = require('@barchart/common-js/collections/specialized/TimeMap');
+
+const InstrumentProvider = require('./InstrumentProvider');
+
+module.exports = (() => {
+	'use strict';
+
+	const MAXIMUM_CACHE_AGE_IN_MILLISECONDS = 15 * 60 * 1000;
+
+	/**
+	 * A caching layer on top of the {@link InstrumentProvider}.
+	 *
+	 * @public
+	 * @param {InstrumentProvider} provider
+	 * @param {Number} cacheDuration - The maximum number of milliseconds to cache an instrument.
+	 */
+	class InstrumentProviderCache {
+		constructor(provider, cacheDuration) {
+			assert.argumentIsRequired(provider, 'provider', InstrumentProvider, 'InstrumentProvider');
+
+			this._provider = provider;
+			this._cache = new TimeMap(cacheDuration || MAXIMUM_CACHE_AGE_IN_MILLISECONDS);
+		}
+
+		/**
+		 * Returns a promise for instrument metadata from an internal cache. If the instrument
+		 * does not exist in the cache, or the data has expired, then a new request for the
+		 * instrument is made using the {@link InstrumentProvider}.
+		 *
+		 * @public
+		 * @async
+		 * @param {String} symbol
+		 * @returns {Promise<Object>}
+		 */
+		async getInstrument(symbol) {
+			return Promise.resolve()
+				.then(() => {
+					assert.argumentIsRequired(symbol, 'symbol', String);
+
+					let promise = this._cache.get(symbol);
+
+					if (promise !== null) {
+						return promise;
+					}
+
+					promise = this._provider.getInstrument(symbol)
+						.then((profile) => {
+							if (profile) {
+								this._cache.put(symbol, promise);
+
+								return profile;
+							}
+						});
+
+					return promise;
+				});
+		}
+
+		toString() {
+			return '[InstrumentProviderCache]';
+		}
+	}
+
+	return InstrumentProviderCache;
+})();

package/package.json

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