@cranberry-money/shared-utils 8.1.0 → 8.2.0

package/dist/holdings.d.ts

@@ -0,0 +1,79 @@
+import type { AssetHolding } from '@cranberry-money/shared-types';
+import { type SortDirection } from '@cranberry-money/shared-constants';
+/**
+ * Calculates the total portfolio value based on holdings and instrument prices
+ *
+ * @param holdings - Array of asset holdings
+ * @param prices - Map of instrument UUIDs to their current prices
+ * @returns Total portfolio value
+ *
+ * @example
+ * const holdings = [
+ *   { instrument: { uuid: '123' }, quantity: 100 },
+ *   { instrument: { uuid: '456' }, quantity: 50 }
+ * ];
+ * const prices = { '123': 10.50, '456': 25.00 };
+ * calculatePortfolioValue(holdings, prices); // returns 2300
+ */
+export declare const calculatePortfolioValue: (holdings: readonly AssetHolding[], prices: Record<string, number>) => number;
+/**
+ * Calculates holding allocation percentages within a portfolio
+ *
+ * @param holdings - Array of asset holdings
+ * @returns Map of instrument UUIDs to their percentage allocations
+ *
+ * @example
+ * const holdings = [
+ *   { instrument: { uuid: '123' }, quantity: 100 },
+ *   { instrument: { uuid: '456' }, quantity: 100 }
+ * ];
+ * calculateHoldingAllocations(holdings); // returns { '123': 50, '456': 50 }
+ */
+export declare const calculateHoldingAllocations: (holdings: readonly AssetHolding[]) => Record<string, number>;
+/**
+ * Groups holdings by instrument UUID for aggregated view
+ *
+ * @param holdings - Array of asset holdings to group
+ * @returns Map of instrument UUIDs to their holdings arrays
+ *
+ * @example
+ * const holdings = [
+ *   { instrument: { uuid: '123' }, quantity: 100 },
+ *   { instrument: { uuid: '123' }, quantity: 50 },
+ *   { instrument: { uuid: '456' }, quantity: 200 }
+ * ];
+ * groupHoldingsByInstrument(holdings);
+ * // returns { '123': [holding1, holding2], '456': [holding3] }
+ */
+export declare const groupHoldingsByInstrument: (holdings: readonly AssetHolding[]) => Record<string, AssetHolding[]>;
+/**
+ * Filters holdings with quantities above a threshold
+ *
+ * @param holdings - Array of asset holdings
+ * @param minQuantity - Minimum quantity threshold
+ * @returns Filtered array of holdings
+ *
+ * @example
+ * const holdings = [
+ *   { quantity: 100 },
+ *   { quantity: 50 },
+ *   { quantity: 200 }
+ * ];
+ * filterHoldingsByMinQuantity(holdings, 75); // returns holdings with quantity >= 75
+ */
+export declare const filterHoldingsByMinQuantity: (holdings: readonly AssetHolding[], minQuantity: number) => AssetHolding[];
+/**
+ * Sorts holdings by various criteria
+ *
+ * @param holdings - Array of asset holdings to sort
+ * @param sortBy - Field to sort by
+ * @param direction - Sort direction (ascending or descending)
+ * @returns Sorted array of holdings
+ *
+ * @example
+ * const holdings = [...];
+ * sortHoldings(holdings, 'quantity', 'desc'); // Sort by quantity descending
+ * sortHoldings(holdings, 'symbol', 'asc'); // Sort by symbol ascending
+ */
+export declare const sortHoldings: (holdings: readonly AssetHolding[], sortBy: "quantity" | "symbol" | "name" | "createdAt", direction?: SortDirection) => AssetHolding[];
+//# sourceMappingURL=holdings.d.ts.map

package/dist/holdings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"holdings.d.ts","sourceRoot":"","sources":["../src/holdings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAiE,KAAK,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAGtI;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,GAAI,UAAU,SAAS,YAAY,EAAE,EAAE,QAAQ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAK3G,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B,GAAI,UAAU,SAAS,YAAY,EAAE,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAWpG,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB,GAAI,UAAU,SAAS,YAAY,EAAE,KAAG,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAS1G,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B,GAAI,UAAU,SAAS,YAAY,EAAE,EAAE,aAAa,MAAM,KAAG,YAAY,EAEhH,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,GACvB,UAAU,SAAS,YAAY,EAAE,EACjC,QAAQ,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,EACpD,YAAW,aAAmC,KAC7C,YAAY,EA0Cd,CAAC"}

package/dist/holdings.js

@@ -0,0 +1,139 @@
+import { DEFAULT_NUMERIC_ZERO, SORT_DIRECTION_ASC, SORT_DIRECTION_DESC } from '@cranberry-money/shared-constants';
+import { sortByStringField } from './collections';
+/**
+ * Calculates the total portfolio value based on holdings and instrument prices
+ *
+ * @param holdings - Array of asset holdings
+ * @param prices - Map of instrument UUIDs to their current prices
+ * @returns Total portfolio value
+ *
+ * @example
+ * const holdings = [
+ *   { instrument: { uuid: '123' }, quantity: 100 },
+ *   { instrument: { uuid: '456' }, quantity: 50 }
+ * ];
+ * const prices = { '123': 10.50, '456': 25.00 };
+ * calculatePortfolioValue(holdings, prices); // returns 2300
+ */
+export const calculatePortfolioValue = (holdings, prices) => {
+    return holdings.reduce((total, holding) => {
+        const price = prices[holding.instrument.uuid] || DEFAULT_NUMERIC_ZERO;
+        return total + holding.quantity * price;
+    }, 0);
+};
+/**
+ * Calculates holding allocation percentages within a portfolio
+ *
+ * @param holdings - Array of asset holdings
+ * @returns Map of instrument UUIDs to their percentage allocations
+ *
+ * @example
+ * const holdings = [
+ *   { instrument: { uuid: '123' }, quantity: 100 },
+ *   { instrument: { uuid: '456' }, quantity: 100 }
+ * ];
+ * calculateHoldingAllocations(holdings); // returns { '123': 50, '456': 50 }
+ */
+export const calculateHoldingAllocations = (holdings) => {
+    const totalQuantity = holdings.reduce((sum, holding) => sum + holding.quantity, 0);
+    if (totalQuantity === 0)
+        return {};
+    const allocations = {};
+    holdings.forEach((holding) => {
+        allocations[holding.instrument.uuid] = (holding.quantity / totalQuantity) * 100;
+    });
+    return allocations;
+};
+/**
+ * Groups holdings by instrument UUID for aggregated view
+ *
+ * @param holdings - Array of asset holdings to group
+ * @returns Map of instrument UUIDs to their holdings arrays
+ *
+ * @example
+ * const holdings = [
+ *   { instrument: { uuid: '123' }, quantity: 100 },
+ *   { instrument: { uuid: '123' }, quantity: 50 },
+ *   { instrument: { uuid: '456' }, quantity: 200 }
+ * ];
+ * groupHoldingsByInstrument(holdings);
+ * // returns { '123': [holding1, holding2], '456': [holding3] }
+ */
+export const groupHoldingsByInstrument = (holdings) => {
+    return holdings.reduce((groups, holding) => {
+        const instrumentUuid = holding.instrument.uuid;
+        if (!groups[instrumentUuid]) {
+            groups[instrumentUuid] = [];
+        }
+        groups[instrumentUuid].push(holding);
+        return groups;
+    }, {});
+};
+/**
+ * Filters holdings with quantities above a threshold
+ *
+ * @param holdings - Array of asset holdings
+ * @param minQuantity - Minimum quantity threshold
+ * @returns Filtered array of holdings
+ *
+ * @example
+ * const holdings = [
+ *   { quantity: 100 },
+ *   { quantity: 50 },
+ *   { quantity: 200 }
+ * ];
+ * filterHoldingsByMinQuantity(holdings, 75); // returns holdings with quantity >= 75
+ */
+export const filterHoldingsByMinQuantity = (holdings, minQuantity) => {
+    return holdings.filter((holding) => holding.quantity >= minQuantity);
+};
+/**
+ * Sorts holdings by various criteria
+ *
+ * @param holdings - Array of asset holdings to sort
+ * @param sortBy - Field to sort by
+ * @param direction - Sort direction (ascending or descending)
+ * @returns Sorted array of holdings
+ *
+ * @example
+ * const holdings = [...];
+ * sortHoldings(holdings, 'quantity', 'desc'); // Sort by quantity descending
+ * sortHoldings(holdings, 'symbol', 'asc'); // Sort by symbol ascending
+ */
+export const sortHoldings = (holdings, sortBy, direction = SORT_DIRECTION_DESC) => {
+    // Use shared utility for string field sorting
+    if (sortBy === 'symbol') {
+        const sorted = sortByStringField([...holdings], 'instrumentSymbol');
+        return direction === SORT_DIRECTION_ASC ? sorted : sorted.reverse();
+    }
+    if (sortBy === 'name') {
+        const sorted = sortByStringField([...holdings], 'instrumentName');
+        return direction === SORT_DIRECTION_ASC ? sorted : sorted.reverse();
+    }
+    // Custom logic for non-string fields
+    return [...holdings].sort((a, b) => {
+        let valueA;
+        let valueB;
+        switch (sortBy) {
+            case 'quantity':
+                valueA = a.quantity;
+                valueB = b.quantity;
+                break;
+            case 'createdAt':
+                valueA = a.createdAt;
+                valueB = b.createdAt;
+                break;
+            default:
+                return 0;
+        }
+        if (typeof valueA === 'string' && typeof valueB === 'string') {
+            const comparison = valueA.localeCompare(valueB);
+            return direction === SORT_DIRECTION_ASC ? comparison : -comparison;
+        }
+        if (typeof valueA === 'number' && typeof valueB === 'number') {
+            const comparison = valueA - valueB;
+            return direction === SORT_DIRECTION_ASC ? comparison : -comparison;
+        }
+        return 0;
+    });
+};

package/dist/index.d.ts

@@ -20,4 +20,5 @@ export { downloadBlob, downloadTextFile, downloadJsonFile, generateTimestampedFi
 export { capitalizeFirstLetter, formatStatus, formatRiskLevel, capitalizeFirst, formatLabel, camelToTitle, } from './formatting';
 export { formatQuantityWithSuffix, formatLargeNumber, formatAsPercentage, formatWithSeparators, roundToDecimals, clampNumber, } from './numbers';
 export { validateAllocations } from './allocations';
+export { calculatePortfolioValue, calculateHoldingAllocations, groupHoldingsByInstrument, filterHoldingsByMinQuantity, sortHoldings, } from './holdings';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAGjF,OAAO,EACL,8BAA8B,EAC9B,qCAAqC,EACrC,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGnE,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGhH,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,EACzB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,QAAQ,EACR,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,EACnB,UAAU,EAEV,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,qBAAqB,EAErB,0BAA0B,EAC1B,4BAA4B,EAC5B,qBAAqB,EACrB,uBAAuB,EACvB,2BAA2B,EAC3B,6BAA6B,EAC7B,2BAA2B,EAC3B,6BAA6B,GAC9B,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,QAAQ,CAAC;AAGhB,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,YAAY,EACZ,aAAa,GACd,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,2BAA2B,EAC3B,eAAe,EACf,eAAe,GAChB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,eAAe,EACf,eAAe,EACf,WAAW,EACX,YAAY,GACb,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,WAAW,GACZ,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -40,3 +40,5 @@ export { capitalizeFirstLetter, formatStatus, formatRiskLevel, capitalizeFirst,
 export { formatQuantityWithSuffix, formatLargeNumber, formatAsPercentage, formatWithSeparators, roundToDecimals, clampNumber, } from './numbers';
 // Allocation utilities
 export { validateAllocations } from './allocations';
+// Holdings utilities
+export { calculatePortfolioValue, calculateHoldingAllocations, groupHoldingsByInstrument, filterHoldingsByMinQuantity, sortHoldings, } from './holdings';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cranberry-money/shared-utils",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "description": "Shared utility functions for MyPortfolio platform",
   "type": "module",
   "main": "dist/index.js",