@fintekkers/ledger-models 0.4.19 → 0.4.20

package/node/wrappers/models/cost_basis.d.ts

@@ -0,0 +1,18 @@
+import Decimal from 'decimal.js';
+export interface Fill {
+    /** Signed quantity: positive is a buy. */
+    directedQuantity: Decimal;
+    /** Price in the security's price convention. */
+    price: Decimal;
+}
+/**
+ * Quantity-weighted mean price of the buys in `fills`. Sells never change it.
+ *
+ * A buy has directedQuantity > 0; sells, short sales and zero-quantity fills
+ * are skipped. The result is sum(quantity * price) / sum(quantity) over the
+ * buys, rounded to 12 decimal places half-even with trailing zeros removed.
+ * Returns null when there are no buys; it never divides by zero or returns NaN.
+ *
+ * Not the same as Java's TaxLotSummary.getAverageCostBasis, which nets sells.
+ */
+export declare function weightedAveragePurchasePrice(fills: ReadonlyArray<Fill>): Decimal | null;

package/node/wrappers/models/cost_basis.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.weightedAveragePurchasePrice = void 0;
+const decimal_js_1 = __importDefault(require("decimal.js"));
+/** Decimal places of the result. Same in Java, Python and Rust; see docs/adr/measure_semantics_and_purchase_price.md. */
+const SCALE = 12;
+// Local constructor: wide enough that sums and the quotient stay exact before
+// the final 12-place rounding. The global Decimal settings are never touched.
+const LocalDecimal = decimal_js_1.default.clone({ precision: 60, rounding: decimal_js_1.default.ROUND_HALF_EVEN });
+/**
+ * Quantity-weighted mean price of the buys in `fills`. Sells never change it.
+ *
+ * A buy has directedQuantity > 0; sells, short sales and zero-quantity fills
+ * are skipped. The result is sum(quantity * price) / sum(quantity) over the
+ * buys, rounded to 12 decimal places half-even with trailing zeros removed.
+ * Returns null when there are no buys; it never divides by zero or returns NaN.
+ *
+ * Not the same as Java's TaxLotSummary.getAverageCostBasis, which nets sells.
+ */
+function weightedAveragePurchasePrice(fills) {
+    let quantity = new LocalDecimal(0);
+    let totalCost = new LocalDecimal(0);
+    for (const { directedQuantity, price } of fills) {
+        if (!directedQuantity.greaterThan(0)) {
+            continue;
+        }
+        quantity = quantity.plus(directedQuantity);
+        totalCost = totalCost.plus(new LocalDecimal(directedQuantity).times(price));
+    }
+    if (quantity.isZero()) {
+        return null;
+    }
+    return totalCost.dividedBy(quantity).toDecimalPlaces(SCALE, decimal_js_1.default.ROUND_HALF_EVEN);
+}
+exports.weightedAveragePurchasePrice = weightedAveragePurchasePrice;
+//# sourceMappingURL=cost_basis.js.map

package/node/wrappers/models/cost_basis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost_basis.js","sourceRoot":"","sources":["cost_basis.ts"],"names":[],"mappings":";;;;;;AAAA,4DAAiC;AAEjC,yHAAyH;AACzH,MAAM,KAAK,GAAG,EAAE,CAAC;AAEjB,8EAA8E;AAC9E,8EAA8E;AAC9E,MAAM,YAAY,GAAG,oBAAO,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,oBAAO,CAAC,eAAe,EAAE,CAAC,CAAC;AASzF;;;;;;;;;GASG;AACH,SAAgB,4BAA4B,CAAC,KAA0B;IACnE,IAAI,QAAQ,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,SAAS,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC;IAEpC,KAAK,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,IAAI,KAAK,EAAE;QAC7C,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE;YAClC,SAAS;SACZ;QACD,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC3C,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,gBAAgB,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;KAC/E;IAED,IAAI,QAAQ,CAAC,MAAM,EAAE,EAAE;QACnB,OAAO,IAAI,CAAC;KACf;IAED,OAAO,SAAS,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,eAAe,CAAC,KAAK,EAAE,oBAAO,CAAC,eAAe,CAAC,CAAC;AACzF,CAAC;AAjBD,oEAiBC"}

package/node/wrappers/models/cost_basis.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node/wrappers/models/cost_basis.test.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const decimal_js_1 = __importDefault(require("decimal.js"));
+const cost_basis_1 = require("./cost_basis");
+const fill = (directedQuantity, price) => ({ directedQuantity: new decimal_js_1.default(directedQuantity), price: new decimal_js_1.default(price) });
+test('sells do not change the buys-only average', () => {
+    const result = (0, cost_basis_1.weightedAveragePurchasePrice)([fill('100', '10'), fill('100', '20'), fill('-50', '25')]);
+    expect(result).not.toBeNull();
+    expect(result.equals(15)).toBe(true);
+    expect(result.toFixed()).toBe('15');
+});
+test('no buys returns null', () => {
+    expect((0, cost_basis_1.weightedAveragePurchasePrice)([fill('-50', '25')])).toBeNull();
+});
+test('repeating result rounds to 12 places half-even', () => {
+    const result = (0, cost_basis_1.weightedAveragePurchasePrice)([fill('1', '1'), fill('2', '2')]);
+    expect(result.toFixed()).toBe('1.666666666667');
+});
+//# sourceMappingURL=cost_basis.test.js.map

package/node/wrappers/models/cost_basis.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost_basis.test.js","sourceRoot":"","sources":["cost_basis.test.ts"],"names":[],"mappings":";;;;;AAAA,4DAAiC;AACjC,6CAA4D;AAE5D,MAAM,IAAI,GAAG,CAAC,gBAAwB,EAAE,KAAa,EAAE,EAAE,CACrD,CAAC,EAAE,gBAAgB,EAAE,IAAI,oBAAO,CAAC,gBAAgB,CAAC,EAAE,KAAK,EAAE,IAAI,oBAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAErF,IAAI,CAAC,2CAA2C,EAAE,GAAG,EAAE;IACnD,MAAM,MAAM,GAAG,IAAA,yCAA4B,EAAC,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAEvG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC9B,MAAM,CAAC,MAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,CAAC,MAAO,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,sBAAsB,EAAE,GAAG,EAAE;IAC9B,MAAM,CAAC,IAAA,yCAA4B,EAAC,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;AACzE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,gDAAgD,EAAE,GAAG,EAAE;IACxD,MAAM,MAAM,GAAG,IAAA,yCAA4B,EAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAE9E,MAAM,CAAC,MAAO,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;AACrD,CAAC,CAAC,CAAC"}

package/node/wrappers/models/cost_basis.test.ts

@@ -0,0 +1,23 @@
+import Decimal from 'decimal.js';
+import { weightedAveragePurchasePrice } from './cost_basis';
+
+const fill = (directedQuantity: string, price: string) =>
+    ({ directedQuantity: new Decimal(directedQuantity), price: new Decimal(price) });
+
+test('sells do not change the buys-only average', () => {
+    const result = weightedAveragePurchasePrice([fill('100', '10'), fill('100', '20'), fill('-50', '25')]);
+
+    expect(result).not.toBeNull();
+    expect(result!.equals(15)).toBe(true);
+    expect(result!.toFixed()).toBe('15');
+});
+
+test('no buys returns null', () => {
+    expect(weightedAveragePurchasePrice([fill('-50', '25')])).toBeNull();
+});
+
+test('repeating result rounds to 12 places half-even', () => {
+    const result = weightedAveragePurchasePrice([fill('1', '1'), fill('2', '2')]);
+
+    expect(result!.toFixed()).toBe('1.666666666667');
+});

package/node/wrappers/models/cost_basis.ts

@@ -0,0 +1,44 @@
+import Decimal from 'decimal.js';
+
+/** Decimal places of the result. Same in Java, Python and Rust; see docs/adr/measure_semantics_and_purchase_price.md. */
+const SCALE = 12;
+
+// Local constructor: wide enough that sums and the quotient stay exact before
+// the final 12-place rounding. The global Decimal settings are never touched.
+const LocalDecimal = Decimal.clone({ precision: 60, rounding: Decimal.ROUND_HALF_EVEN });
+
+export interface Fill {
+    /** Signed quantity: positive is a buy. */
+    directedQuantity: Decimal;
+    /** Price in the security's price convention. */
+    price: Decimal;
+}
+
+/**
+ * Quantity-weighted mean price of the buys in `fills`. Sells never change it.
+ *
+ * A buy has directedQuantity > 0; sells, short sales and zero-quantity fills
+ * are skipped. The result is sum(quantity * price) / sum(quantity) over the
+ * buys, rounded to 12 decimal places half-even with trailing zeros removed.
+ * Returns null when there are no buys; it never divides by zero or returns NaN.
+ *
+ * Not the same as Java's TaxLotSummary.getAverageCostBasis, which nets sells.
+ */
+export function weightedAveragePurchasePrice(fills: ReadonlyArray<Fill>): Decimal | null {
+    let quantity = new LocalDecimal(0);
+    let totalCost = new LocalDecimal(0);
+
+    for (const { directedQuantity, price } of fills) {
+        if (!directedQuantity.greaterThan(0)) {
+            continue;
+        }
+        quantity = quantity.plus(directedQuantity);
+        totalCost = totalCost.plus(new LocalDecimal(directedQuantity).times(price));
+    }
+
+    if (quantity.isZero()) {
+        return null;
+    }
+
+    return totalCost.dividedBy(quantity).toDecimalPlaces(SCALE, Decimal.ROUND_HALF_EVEN);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fintekkers/ledger-models",
   "todo": "Replace the version with build script version number",
-  "version": "0.4.19",
+  "version": "0.4.20",
   "description": "ledger model protos ",
   "authors": [
     "David Doherty",