@ducatjs/money 0.2.1 → 0.3.0

package/dist/finance.js

@@ -0,0 +1,825 @@
+/**
+ * `@ducatjs/money/finance`: day counts, simple and compound interest, loan schedules, NPV and IRR,
+ * and subscription proration, in exact arithmetic. Every amount that is paid or booked is rounded
+ * once from its exact value; nothing in between is rounded, and no floats are used. Dates are
+ * calendar dates ('YYYY-MM-DD' or `{ year, month, day }`, so a `Temporal.PlainDate` works), never
+ * `Date`. Free functions only: nothing is added to Money.
+ */
+import { currencyExponent } from './currency.js';
+import { formatScaled, pow10n, ratio } from './decimal.js';
+import { ExactMoney, exact } from './exact.js';
+import { allocate, instalments } from './allocate.js';
+import { add, compare, CurrencyMismatchError, make, multiplyByRatio, subtract, sum, } from './money.js';
+import { DEFAULT_ROUNDING } from './rounding.js';
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+function isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+function daysInMonth(year, month) {
+    if (month === 2) {
+        return isLeapYear(year) ? 29 : 28;
+    }
+    // April, June, September and November have 30 days
+    return month === 4 || month === 6 || month === 9 || month === 11 ? 30 : 31;
+}
+function daysInYear(year) {
+    return isLeapYear(year) ? 366 : 365;
+}
+/** The fields of a calendar date, or a RangeError for anything that is not a real date. */
+function dateFields(date) {
+    let year;
+    let month;
+    let day;
+    if (typeof date === 'string') {
+        const match = DATE_RE.exec(date);
+        if (match === null) {
+            throw new RangeError(`Invalid date "${date}"; expected YYYY-MM-DD`);
+        }
+        year = Number(match[1]);
+        month = Number(match[2]);
+        day = Number(match[3]);
+    }
+    else {
+        // a Temporal.PlainDate in another calendar has that calendar's fields, not Gregorian ones
+        const calendar = date.calendarId;
+        if (calendar !== undefined && calendar !== 'iso8601') {
+            throw new RangeError(`Dates must be in the ISO calendar; got ${String(calendar)}`);
+        }
+        year = date.year;
+        month = date.month;
+        day = date.day;
+    }
+    // years 0-9999, as 'YYYY-MM-DD' writes them, keep every day and second count exact
+    const valid = Number.isInteger(year) &&
+        year >= 0 &&
+        year <= 9999 &&
+        Number.isInteger(month) &&
+        Number.isInteger(day) &&
+        month >= 1 &&
+        month <= 12 &&
+        day >= 1 &&
+        day <= daysInMonth(year, month);
+    if (!valid) {
+        throw new RangeError(`Invalid date ${formatFields(year, month, day)}`);
+    }
+    return { year, month, day };
+}
+function formatFields(year, month, day) {
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${String(year).padStart(4, '0')}-${pad(month)}-${pad(day)}`;
+}
+/**
+ * Days from 1970-01-01 to the date, in integers (Howard Hinnant's `days_from_civil`): the year is
+ * counted from March, so the leap day falls at the end of the counting year.
+ */
+function dayNumber({ year, month, day }) {
+    const shiftedYear = month <= 2 ? year - 1 : year;
+    const era = Math.floor(shiftedYear / 400);
+    const yearOfEra = shiftedYear - era * 400;
+    const monthFromMarch = month > 2 ? month - 3 : month + 9;
+    const dayOfYear = Math.floor((153 * monthFromMarch + 2) / 5) + day - 1;
+    const dayOfEra = yearOfEra * 365 + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100);
+    return era * 146_097 + dayOfEra + dayOfYear - 719_468;
+}
+/** Days from `start` to `end` (end exclusive): negative when `end` is earlier. */
+function daysBetween(start, end) {
+    return dayNumber(end) - dayNumber(start);
+}
+function assertNotBefore(start, end) {
+    if (dayNumber(end) < dayNumber(start)) {
+        throw new RangeError('The end date is before the start date');
+    }
+}
+function isLastDayOfFebruary({ year, month, day }) {
+    return month === 2 && day === daysInMonth(year, 2);
+}
+/** The 30/360 family's day count: 360 × years + 30 × months + days, after adjusting the days. */
+function thirty360Days(start, end, startDay, endDay) {
+    return 360 * (end.year - start.year) + 30 * (end.month - start.month) + (endDay - startDay);
+}
+/**
+ * The fraction of a year from `start` to `end` under `convention`, as an exact ratio. `end` may not
+ * be before `start`. This is not Excel's YEARFRAC: its basis 0 is the US (NASD) 30/360 with
+ * end-of-February rules rather than Bond Basis, its basis 1 divides by an average year length
+ * rather than splitting days by calendar year as ACT/ACT ISDA does, and it swaps reversed dates.
+ *
+ *     yearFraction('2026-01-15', '2026-07-15', 'ACT/360')   // 181/360
+ */
+export function yearFraction(start, end, convention, options) {
+    const from = dateFields(start);
+    const to = dateFields(end);
+    assertNotBefore(from, to);
+    switch (convention) {
+        case 'ACT/360':
+            return ratio(BigInt(daysBetween(from, to)), 360n);
+        case 'ACT/365F':
+            return ratio(BigInt(daysBetween(from, to)), 365n);
+        case 'ACT/ACT ISDA':
+            return actualActualIsda(from, to);
+        case '30/360': {
+            // §4.16(f): D1 = 31 becomes 30; D2 = 31 becomes 30 only when D1 is then 30 (or was 31)
+            const startDay = from.day === 31 ? 30 : from.day;
+            const endDay = to.day === 31 && startDay === 30 ? 30 : to.day;
+            return ratio(BigInt(thirty360Days(from, to, startDay, endDay)), 360n);
+        }
+        case '30E/360': {
+            // §4.16(g): a 31st on either side becomes the 30th
+            const startDay = from.day === 31 ? 30 : from.day;
+            const endDay = to.day === 31 ? 30 : to.day;
+            return ratio(BigInt(thirty360Days(from, to, startDay, endDay)), 360n);
+        }
+        case '30E/360 ISDA': {
+            // §4.16(h): the last day of a month becomes the 30th, except the last day of February when
+            // it is the termination date
+            const startDay = from.day === 31 || isLastDayOfFebruary(from) ? 30 : from.day;
+            let endDay = to.day === 31 ? 30 : to.day;
+            if (isLastDayOfFebruary(to)) {
+                const maturity = options?.maturity;
+                if (typeof maturity !== 'boolean') {
+                    throw new RangeError("'30E/360 ISDA' ending on the last day of February needs the option maturity: true or false");
+                }
+                endDay = maturity ? to.day : 30;
+            }
+            return ratio(BigInt(thirty360Days(from, to, startDay, endDay)), 360n);
+        }
+    }
+    return invalid('day count', convention);
+}
+/** ACT/ACT ISDA: the days in each calendar year over that year's length, summed exactly. */
+function actualActualIsda(from, to) {
+    if (from.year === to.year) {
+        return ratio(BigInt(daysBetween(from, to)), BigInt(daysInYear(from.year)));
+    }
+    const startYearEnd = { year: from.year + 1, month: 1, day: 1 };
+    const endYearStart = { year: to.year, month: 1, day: 1 };
+    const firstYearLength = BigInt(daysInYear(from.year));
+    const lastYearLength = BigInt(daysInYear(to.year));
+    const firstYearDays = BigInt(daysBetween(from, startYearEnd));
+    const lastYearDays = BigInt(daysBetween(endYearStart, to));
+    const wholeYears = BigInt(to.year - from.year - 1);
+    // firstYearDays/firstYearLength + wholeYears + lastYearDays/lastYearLength over one denominator
+    const denominator = firstYearLength * lastYearLength;
+    const numerator = firstYearDays * lastYearLength + wholeYears * denominator + lastYearDays * firstYearLength;
+    return ratio(numerator, denominator);
+}
+// ---------------------------------------------------------------------------------------------
+// Rounding helpers
+// ---------------------------------------------------------------------------------------------
+/**
+ * numerator / denominator major units (denominator > 0) rounded once: with a mode, to the
+ * currency's exponent; with a policy, to the policy's scale and increment. The fraction is not
+ * reduced first: rounding divides once either way, and a gcd of the thousands-of-bits integers a
+ * long schedule or NPV builds would cost more than everything else.
+ */
+function roundQuotient(currency, numerator, denominator, rounding) {
+    // one major unit times the fraction, so the rounding applies to the fraction itself
+    return multiplyAndRound(make(currency, 1, 0), unreducedRatio(numerator, denominator), rounding);
+}
+/** money × factor rounded once, at the currency's exponent or the policy's scale. */
+function multiplyAndRound(money, factor, rounding) {
+    return multiplyByRatio(money, factor, rounding, currencyExponent(money.currency));
+}
+/**
+ * A ratio built without a gcd, for rounding once: multiplyByRatio divides by it, which gives the
+ * same result for any representation of the fraction.
+ */
+function unreducedRatio(numerator, denominator) {
+    const toNumber = (value) => value <= 9007199254740991n && value >= -9007199254740991n ? Number(value) : NaN;
+    return { num: numerator, den: denominator, n: toNumber(numerator), d: toNumber(denominator) };
+}
+/**
+ * The most periods a schedule or compounding may have: (1 + r)^n has about n times the bits of
+ * 1 + r, so this bounds the integers (a 30-year daily schedule is about 11,000 periods).
+ */
+const MAX_PERIODS = 100_000;
+function assertPeriods(periods, minimum) {
+    if (!(Number.isInteger(periods) && periods >= minimum && periods <= MAX_PERIODS)) {
+        invalid('periods', periods);
+    }
+}
+/** Whether `money` is a whole number of `unit`s (both of one currency, unit positive). */
+function isMultipleOf(money, unit) {
+    const scale = Math.max(money.scale, unit.scale);
+    const minor = BigInt(money.minor) * pow10n(scale - money.scale);
+    const unitMinor = BigInt(unit.minor) * pow10n(scale - unit.scale);
+    return minor % unitMinor === 0n;
+}
+/** Throws a RangeError naming the option and the value it was given. */
+function invalid(name, value) {
+    throw new RangeError(`Invalid ${name} ${String(value)}`);
+}
+function assertPositiveInteger(value, name) {
+    if (!(Number.isSafeInteger(value) && value >= 1)) {
+        invalid(name, value);
+    }
+}
+function assertSameCurrency(money, other) {
+    if (money.currency !== other.currency) {
+        throw new CurrencyMismatchError(money.currency, other.currency);
+    }
+}
+/**
+ * Simple interest, `principal × rate × yearFraction`, exactly. `rate` is an annual rate as a
+ * `Factor` ('0.05' for 5%).
+ */
+export function interestExact(principal, rate, period) {
+    const fraction = yearFraction(period.from, period.to, period.dayCount, period);
+    return exact(principal).multiply(rate).multiply(fraction);
+}
+/**
+ * Simple interest, `principal × rate × yearFraction`, rounded once (to the currency's exponent with
+ * a mode, or to a policy's scale; default 'halfExpand').
+ *
+ *     interest(money('10000', 'EUR'), '0.05',
+ *       { from: '2026-01-15', to: '2026-07-15', dayCount: 'ACT/365F' }, 'halfEven')   // 247.95 EUR
+ */
+export function interest(principal, rate, period, rounding = DEFAULT_ROUNDING) {
+    const fraction = yearFraction(period.from, period.to, period.dayCount, period);
+    const rateRatio = ratio(rate);
+    return multiplyAndRound(principal, ratio(rateRatio.num * fraction.num, rateRatio.den * fraction.den), rounding);
+}
+/** (1 + rate/perYear) as a reduced ratio, checked to be positive. */
+function growthFactor(rate, perYear) {
+    assertPositiveInteger(perYear, 'perYear');
+    const rateRatio = ratio(rate);
+    const perYearBig = BigInt(perYear);
+    const growth = ratio(rateRatio.num + rateRatio.den * perYearBig, rateRatio.den * perYearBig);
+    if (growth.num <= 0n) {
+        throw new RangeError(`A rate of ${rate} per year loses everything in one period`);
+    }
+    return growth;
+}
+/**
+ * Periodic compounding: `principal × (1 + rate/perYear)^periods` (at most 100,000 periods), an
+ * exact integer power, rounded once. Fractional periods and continuous compounding are irrational, so they are not offered.
+ *
+ *     compound(money('1000', 'EUR'), '0.05', { periods: 12, perYear: 12 }, 'halfEven') // 1051.16 EUR
+ */
+export function compound(principal, rate, options, rounding = DEFAULT_ROUNDING) {
+    const periods = options.periods;
+    assertPeriods(periods, 0);
+    const growth = growthFactor(rate, options.perYear);
+    const exponent = BigInt(periods);
+    // a power of a reduced ratio is reduced, so no gcd is needed on the large integers
+    const power = unreducedRatio(growth.num ** exponent, growth.den ** exponent);
+    return multiplyAndRound(principal, power, rounding);
+}
+/** The minor unit a rounding produces, for loans whose parts must be multiples of it. */
+function roundingUnit(currency, rounding) {
+    if (typeof rounding === 'string') {
+        return make(currency, 1, currencyExponent(currency));
+    }
+    return make(currency, rounding.increment, rounding.scale ?? currencyExponent(currency));
+}
+/** The payment dates: monthly steps from the anchor date, clamped to month ends, or 7 or 14 days. */
+function paymentDates(first, perYear, count) {
+    const anchor = dateFields(first);
+    const dates = [];
+    if (perYear === 26 || perYear === 52) {
+        const step = perYear === 52 ? 7 : 14;
+        const anchorDay = dayNumber(anchor);
+        for (let i = 0; i < count; i++) {
+            dates.push(dateFromDayNumber(anchorDay + i * step));
+        }
+        return checkedDates(dates);
+    }
+    if (!(Number.isSafeInteger(perYear) && 12 % perYear === 0)) {
+        // payment dates step by whole months, or by 7 or 14 days
+        invalid('perYear for payment dates', perYear);
+    }
+    const monthStep = 12 / perYear;
+    for (let i = 0; i < count; i++) {
+        const monthIndex = anchor.month - 1 + i * monthStep;
+        const year = anchor.year + Math.floor(monthIndex / 12);
+        const month = (monthIndex % 12) + 1;
+        const day = Math.min(anchor.day, daysInMonth(year, month));
+        dates.push(formatFields(year, month, day));
+    }
+    return checkedDates(dates);
+}
+/** The dates, unless the last (and latest) is past the year 9999, which dates can't hold. */
+function checkedDates(dates) {
+    if (dates[dates.length - 1].length !== 10) {
+        throw new RangeError('The payment dates run past the year 9999');
+    }
+    return dates;
+}
+/** The inverse of `dayNumber` (Howard Hinnant's `civil_from_days`). */
+function dateFromDayNumber(days) {
+    const shifted = days + 719_468;
+    const era = Math.floor(shifted / 146_097);
+    const dayOfEra = shifted - era * 146_097;
+    const yearOfEra = Math.floor((dayOfEra -
+        Math.floor(dayOfEra / 1460) +
+        Math.floor(dayOfEra / 36_524) -
+        Math.floor(dayOfEra / 146_096)) /
+        365);
+    const dayOfYear = dayOfEra - (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100));
+    const monthFromMarch = Math.floor((5 * dayOfYear + 2) / 153);
+    const day = dayOfYear - Math.floor((153 * monthFromMarch + 2) / 5) + 1;
+    const month = monthFromMarch < 10 ? monthFromMarch + 3 : monthFromMarch - 9;
+    const year = yearOfEra + era * 400 + (month <= 2 ? 1 : 0);
+    return formatFields(year, month, day);
+}
+/**
+ * A loan's repayment schedule. Each period's interest is the balance times `rate / perYear`,
+ * rounded once; the principal part is the payment minus the interest. The principal parts sum
+ * exactly to the loan, the balance never goes negative, and it ends at exactly zero: the rounding
+ * residual goes to the last payment (or, with `residual: 'lastInterest'`, to the last interest). If
+ * rounded payments clear the loan early, the schedule ends with the payment that clears it, so it
+ * can have fewer rows than `periods`. With a zero rate, the payments are
+ * `instalments(loan, periods, { remainder: 'toLast' })` (there is no interest to take a residual).
+ * The loan and the balloon must be multiples of the rounding's unit (0.01 EUR, or a policy's
+ * increment), so that every amount in the schedule is too. At most 100,000 periods.
+ *
+ *     amortise(money('200000', 'EUR'), { rate: '0.045', perYear: 12, periods: 300 }).payment
+ *     // 1111.66 EUR
+ */
+export function amortise(loan, options) {
+    const periods = options.periods;
+    const perYear = options.perYear;
+    const method = options.method ?? 'annuity';
+    const rounding = options.rounding ?? DEFAULT_ROUNDING;
+    const residual = options.residual ?? 'lastPayment';
+    const currency = loan.currency;
+    const zeroAmount = make(currency, 0, currencyExponent(currency));
+    const balloon = options.balloon ?? zeroAmount;
+    assertPeriods(periods, 1);
+    assertPositiveInteger(perYear, 'perYear');
+    if (!(loan.minor > 0)) {
+        throw new RangeError(`The loan must be positive; got ${loan}`);
+    }
+    assertSameCurrency(loan, balloon);
+    if (balloon.minor < 0 || compare(balloon, loan) > 0) {
+        throw new RangeError(`The balloon must be between zero and the loan; got ${balloon}`);
+    }
+    if (options.balloon !== undefined && method === 'interestOnly') {
+        throw new RangeError("An 'interestOnly' loan repays all of it at the end; drop the balloon");
+    }
+    if (method !== 'annuity' && method !== 'linear' && method !== 'interestOnly') {
+        invalid('method', method);
+    }
+    if (residual !== 'lastPayment' && residual !== 'lastInterest') {
+        invalid('residual', residual);
+    }
+    const unit = roundingUnit(currency, rounding);
+    if (!isMultipleOf(loan, unit) || !isMultipleOf(balloon, unit)) {
+        throw new RangeError(`The loan and the balloon must be multiples of ${unit}`);
+    }
+    const rateRatio = ratio(options.rate);
+    if (rateRatio.num < 0n) {
+        throw new RangeError(`The rate must not be negative; got ${options.rate}`);
+    }
+    // with no interest to round, there is no residual to put in it
+    if (residual === 'lastInterest' && (method !== 'annuity' || rateRatio.num === 0n)) {
+        throw new RangeError("residual 'lastInterest' applies to annuities with a non-zero rate only");
+    }
+    const dates = options.firstPayment === undefined
+        ? undefined
+        : paymentDates(options.firstPayment, perYear, periods);
+    const periodicRate = ratio(rateRatio.num, rateRatio.den * BigInt(perYear));
+    const rows = [];
+    const pushRow = (payment, interestPart, principal, balance) => {
+        const period = rows.length + 1;
+        const row = dates === undefined
+            ? { period, payment, interest: interestPart, principal, balance }
+            : { period, date: dates[period - 1], payment, interest: interestPart, principal, balance };
+        rows.push(row);
+    };
+    // The principal parts of a linear loan, or of any loan at a zero rate: equal parts that sum to
+    // the loan exactly, each a multiple of the rounding's unit, the remainder in the last one.
+    const isZeroRate = rateRatio.num === 0n;
+    if (method === 'linear' || (method === 'annuity' && isZeroRate)) {
+        const parts = instalments(subtract(loan, balloon), periods, {
+            remainder: 'toLast',
+            unit,
+        });
+        let balance = loan;
+        for (let i = 0; i < periods; i++) {
+            const isLast = i === periods - 1;
+            const principal = isLast ? balance : parts[i];
+            const interestPart = multiplyAndRound(balance, periodicRate, rounding);
+            balance = subtract(balance, principal);
+            pushRow(add(principal, interestPart), interestPart, principal, balance);
+        }
+        return finish(rows, currency);
+    }
+    if (method === 'interestOnly') {
+        const interestPart = multiplyAndRound(loan, periodicRate, rounding);
+        for (let i = 0; i < periods; i++) {
+            const isLast = i === periods - 1;
+            const principal = isLast ? loan : zeroAmount;
+            const balance = isLast ? zeroAmount : loan;
+            pushRow(add(principal, interestPart), interestPart, principal, balance);
+        }
+        return { payment: interestPart, rows, totalInterest: sumInterest(rows, currency) };
+    }
+    // Annuity: payment = (P·g^n − B)·r / (g^n − 1), with r = a/b and g = 1 + r = (a + b)/b. With
+    // G = (a + b)^n and H = b^n that is (P·G − B·H)·a / (b·(G − H)), and P and B are minor units
+    // over 10^scale, so the exact payment is one fraction of integers, rounded once.
+    const scale = Math.max(loan.scale, balloon.scale);
+    const loanMinor = BigInt(loan.minor) * pow10n(scale - loan.scale);
+    const balloonMinor = BigInt(balloon.minor) * pow10n(scale - balloon.scale);
+    const exponent = BigInt(periods);
+    const growthPower = (periodicRate.num + periodicRate.den) ** exponent;
+    const basePower = periodicRate.den ** exponent;
+    const payment = roundQuotient(currency, (loanMinor * growthPower - balloonMinor * basePower) * periodicRate.num, pow10n(scale) * periodicRate.den * (growthPower - basePower), rounding);
+    let balance = loan;
+    for (let i = 0; i < periods; i++) {
+        const interestPart = multiplyAndRound(balance, periodicRate, rounding);
+        const isLast = i === periods - 1;
+        const owed = add(balance, interestPart);
+        // the last payment, or a regular payment that would clear more than is owed, settles the loan
+        if (isLast || compare(payment, owed) >= 0) {
+            if (isLast && residual === 'lastInterest') {
+                const lastPayment = add(payment, balloon);
+                const lastInterest = subtract(lastPayment, balance);
+                if (lastInterest.minor < 0) {
+                    throw new RangeError("The residual exceeds the last interest; use residual 'lastPayment'");
+                }
+                pushRow(lastPayment, lastInterest, balance, subtract(balance, balance));
+            }
+            else {
+                pushRow(owed, interestPart, balance, subtract(balance, balance));
+            }
+            break;
+        }
+        const principal = subtract(payment, interestPart);
+        balance = subtract(balance, principal);
+        pushRow(payment, interestPart, principal, balance);
+    }
+    return { payment, rows, totalInterest: sumInterest(rows, currency) };
+}
+function sumInterest(rows, currency) {
+    // the rows share one currency, which the generic C cannot show the type checker
+    const interestColumn = rows.map((row) => row.interest);
+    return sum(interestColumn, currency);
+}
+function finish(rows, currency) {
+    return { payment: rows[0].payment, rows, totalInterest: sumInterest(rows, currency) };
+}
+// ---------------------------------------------------------------------------------------------
+// NPV and IRR
+// ---------------------------------------------------------------------------------------------
+/** The flows' minor units at one common scale, checked to share a currency. */
+function flowMinors(flows) {
+    if (flows.length === 0) {
+        throw new RangeError('At least one cash flow is needed');
+    }
+    const first = flows[0];
+    let scale = 0;
+    for (const flow of flows) {
+        assertSameCurrency(first, flow);
+        if (flow.scale > scale) {
+            scale = flow.scale;
+        }
+    }
+    const minors = flows.map((flow) => BigInt(flow.minor) * pow10n(scale - flow.scale));
+    return { minors, scale };
+}
+/**
+ * Σ flowₜ · bᵗ · q^(n−t) for a rate of (q − b)/b: the NPV times q^n, by Horner's rule. q^n is
+ * positive for a rate above −1, so this has the NPV's sign.
+ */
+function scaledPresentValue(minors, growthNumerator, base) {
+    let accumulator = minors[0];
+    let basePower = 1n;
+    for (let i = 1; i < minors.length; i++) {
+        basePower *= base;
+        accumulator = accumulator * growthNumerator + minors[i] * basePower;
+    }
+    return accumulator;
+}
+/**
+ * The discounted sum of flows at periods 0, 1, 2…, `Σ flowₜ / (1 + rate)ᵗ`, exactly: the textbook
+ * NPV, with the first flow (an initial outlay, say) not discounted. `npvExact` is Excel's form. (Not
+ * Excel's PV, which is an annuity's present value.)
+ */
+export function discountedSumExact(rate, flows) {
+    const [numerator, denominator] = discountedValue(rate, flows, false);
+    return new ExactMoney(flows[0].currency, numerator, denominator);
+}
+/**
+ * The discounted sum of flows at periods 0, 1, 2…, exact and rounded once (to the currency's
+ * exponent with a mode, or to a policy's scale; default 'halfExpand'). The first flow is not
+ * discounted; this is `flows[0] + npv(rate, flows.slice(1))`.
+ *
+ *     discountedSum('0.08', [money('-1000', 'EUR'), money('300', 'EUR'), money('400', 'EUR'),
+ *       money('500', 'EUR')], 'halfEven')   // 17.63 EUR
+ */
+export function discountedSum(rate, flows, rounding = DEFAULT_ROUNDING) {
+    const [numerator, denominator] = discountedValue(rate, flows, false);
+    return roundQuotient(flows[0].currency, numerator, denominator, rounding);
+}
+/**
+ * Excel's NPV, exactly: `Σ flowᵢ / (1 + rate)ⁱ` for i = 1, 2…, so the first flow is at the end of
+ * period 1 and is discounted once. Like Excel, an initial outlay at period 0 goes outside:
+ * `flows[0] + npv(rate, rest)`, or use `discountedSumExact`.
+ */
+export function npvExact(rate, flows) {
+    const [numerator, denominator] = discountedValue(rate, flows, true);
+    return new ExactMoney(flows[0].currency, numerator, denominator);
+}
+/**
+ * Excel's NPV: flows at the ends of periods 1, 2…, exact and rounded once (to the currency's
+ * exponent with a mode, or to a policy's scale; default 'halfExpand'), so it matches Excel to the
+ * cent. Like Excel, an initial outlay at period 0 goes outside: `flows[0] + npv(rate, rest)`, or use
+ * `discountedSum`, which takes flows from period 0.
+ *
+ *     npv('0.1', [money('-10000', 'USD'), money('3000', 'USD'), money('4200', 'USD'),
+ *       money('6800', 'USD')])   // 1188.44 USD, as Excel's NPV(10%, -10000, 3000, 4200, 6800)
+ */
+export function npv(rate, flows, rounding = DEFAULT_ROUNDING) {
+    const [numerator, denominator] = discountedValue(rate, flows, true);
+    return roundQuotient(flows[0].currency, numerator, denominator, rounding);
+}
+/**
+ * The flows' discounted value in major units as an unreduced fraction (denominator positive), the
+ * first flow at period 0, or at period 1 when `fromPeriodOne`.
+ */
+function discountedValue(rate, flows, fromPeriodOne) {
+    const { minors, scale } = flowMinors(flows);
+    const rateRatio = ratio(rate);
+    const growthNumerator = rateRatio.num + rateRatio.den;
+    if (growthNumerator <= 0n) {
+        throw new RangeError(`The rate must be above -1; got ${rate}`);
+    }
+    let numerator = scaledPresentValue(minors, growthNumerator, rateRatio.den);
+    let denominator = growthNumerator ** BigInt(minors.length - 1) * pow10n(scale);
+    if (fromPeriodOne) {
+        // one more period: divide by 1 + rate = growthNumerator / den
+        numerator *= rateRatio.den;
+        denominator *= growthNumerator;
+    }
+    return [numerator, denominator];
+}
+function signOf(value) {
+    if (value > 0n) {
+        return 1;
+    }
+    if (value < 0n) {
+        return -1;
+    }
+    return 0;
+}
+/** Sign changes in the flows, zeros skipped, and the sign of the first non-zero flow. */
+function signChanges(minors) {
+    let changes = 0;
+    let firstSign = 0;
+    let previous = 0;
+    for (const minor of minors) {
+        const sign = signOf(minor);
+        if (sign === 0) {
+            continue;
+        }
+        if (firstSign === 0) {
+            firstSign = sign;
+        }
+        if (previous !== 0 && sign !== previous) {
+            changes++;
+        }
+        previous = sign;
+    }
+    return { changes, firstSign };
+}
+/**
+ * Excel's IRR, exactly: the rate at which the NPV of flows at periods 0, 1, 2… (the first value
+ * undiscounted, as in Excel's IRR) is zero. The rate is exact to `digits` decimal places (default
+ * 10), floored: `rate` is `lower`, the IRR rounded down, and the IRR lies between `lower` and
+ * `upper`, 10^−digits apart. It is a polynomial root, irrational in general, so it is found by
+ * bisection in exact integer arithmetic on the grid of `digits`-place decimals, with no floats and
+ * no Newton steps; each step checks the NPV's sign alone, by Horner's rule on integers.
+ *
+ * Where Excel guesses, this throws a RangeError. The flows never change sign: there is no IRR
+ * (Excel returns #NUM!). They change sign more than once: there can be several IRRs, and Excel
+ * returns whichever its Newton iteration from `guess` finds; here a `bracket`, which replaces
+ * `guess`, must select one, and the IRR returned is one inside it. The IRR is within 10^−digits of
+ * −1, where the NPV is undefined: ask for more digits.
+ *
+ *     irr([money('-1000', 'EUR'), money('300', 'EUR'), money('400', 'EUR'), money('500', 'EUR')],
+ *       { digits: 8 })   // { rate: '0.08896339', lower: '0.08896339', upper: '0.08896340' }
+ */
+export function irr(flows, options) {
+    const digits = options?.digits ?? 10;
+    if (!(Number.isInteger(digits) && digits >= 0 && digits <= 100)) {
+        invalid('digits', digits);
+    }
+    const { minors } = flowMinors(flows);
+    const { changes, firstSign } = signChanges(minors);
+    const bracket = options?.bracket;
+    if (changes === 0) {
+        throw new RangeError('The cash flows never change sign, so they have no IRR');
+    }
+    if (changes > 1 && bracket === undefined) {
+        throw new RangeError(`The cash flows change sign ${changes} times, so they can have several IRRs; pass a bracket`);
+    }
+    // A rate of m / 10^digits: its growth factor's numerator is 10^digits + m over 10^digits.
+    const unit = pow10n(digits);
+    const signAt = (grid) => signOf(scaledPresentValue(minors, unit + grid, unit));
+    const result = (grid) => {
+        // the NPV is undefined at -1, so a lower end there is no answer
+        if (grid <= -unit) {
+            throw new RangeError(`The IRR is within 10^-${digits} of -1; ask for more digits`);
+        }
+        const lower = formatScaled(grid, digits);
+        return { rate: lower, lower, upper: formatScaled(grid + 1n, digits) };
+    };
+    let low;
+    let high;
+    let lowSign;
+    if (bracket !== undefined) {
+        const bracketed = bracketToGrid(bracket, minors, unit, signAt);
+        if (typeof bracketed === 'bigint') {
+            return result(bracketed);
+        }
+        [low, high, lowSign] = bracketed;
+    }
+    else {
+        // One sign change: exactly one IRR above −1 (Descartes' rule in 1/(1 + rate)). The NPV has the
+        // first flow's sign for large rates and the last flow's sign near −1.
+        const zeroSign = signAt(0n);
+        if (zeroSign === 0) {
+            return result(0n);
+        }
+        if (zeroSign === firstSign) {
+            // the IRR is negative: between −1 (excluded, where the NPV has the last flow's sign) and 0
+            low = -unit;
+            high = 0n;
+            lowSign = -firstSign;
+        }
+        else {
+            // the IRR is positive: double the upper end until the NPV takes the first flow's sign
+            low = 0n;
+            high = unit;
+            lowSign = zeroSign;
+            for (;;) {
+                const highSign = signAt(high);
+                if (highSign === 0) {
+                    return result(high);
+                }
+                if (highSign !== lowSign) {
+                    break;
+                }
+                low = high;
+                high *= 2n;
+            }
+        }
+    }
+    // Bisection on the grid: the bracket's ends stay `digits`-place decimals, so the integers stay
+    // bounded by the digits asked for, and each step halves the bracket.
+    while (high - low > 1n) {
+        const middle = (low + high) / 2n;
+        const middleSign = signAt(middle);
+        if (middleSign === 0) {
+            return result(middle);
+        }
+        if (middleSign === lowSign) {
+            low = middle;
+        }
+        else {
+            high = middle;
+        }
+    }
+    return result(low);
+}
+/**
+ * The caller's bracket narrowed to the grid of `unit`ths: the NPV's signs are taken at the exact
+ * bracket ends first, so the root found is one inside the bracket. Returns the grid point at or
+ * below the root when the root is already pinned to one grid step, else the grid bracket to bisect
+ * and the sign at its lower end.
+ */
+function bracketToGrid(bracket, minors, unit, signAt) {
+    const lowRate = ratio(bracket[0]);
+    const highRate = ratio(bracket[1]);
+    if (!(lowRate.num * highRate.den < highRate.num * lowRate.den)) {
+        throw new RangeError('The bracket must be two increasing rates');
+    }
+    if (lowRate.num + lowRate.den <= 0n) {
+        throw new RangeError('The bracket must be above -1');
+    }
+    const signAtRate = (rate) => signOf(scaledPresentValue(minors, rate.num + rate.den, rate.den));
+    const lowSign = signAtRate(lowRate);
+    const highSign = signAtRate(highRate);
+    // an end that is itself a root: the grid point at or below it
+    if (lowSign === 0) {
+        return floorDivide(lowRate.num * unit, lowRate.den);
+    }
+    if (highSign === 0) {
+        return floorDivide(highRate.num * unit, highRate.den);
+    }
+    if (lowSign === highSign) {
+        throw new RangeError('The NPV has the same sign at both ends of the bracket');
+    }
+    // the grid points inside the bracket
+    const gridLow = -floorDivide(-lowRate.num * unit, lowRate.den);
+    const gridHigh = floorDivide(highRate.num * unit, highRate.den);
+    if (gridLow > gridHigh) {
+        // no grid point inside: the root is between the two around the bracket
+        return gridHigh;
+    }
+    const gridLowSign = signAt(gridLow);
+    if (gridLowSign === 0) {
+        return gridLow;
+    }
+    if (gridLowSign !== lowSign) {
+        // the sign changes between the bracket's low end and the first grid point
+        return gridLow - 1n;
+    }
+    const gridHighSign = gridHigh === gridLow ? gridLowSign : signAt(gridHigh);
+    if (gridHighSign === 0) {
+        return gridHigh;
+    }
+    if (gridHighSign === lowSign) {
+        // the sign changes between the last grid point and the bracket's high end
+        return gridHigh;
+    }
+    return [gridLow, gridHigh, lowSign];
+}
+function floorDivide(dividend, divisor) {
+    const quotient = dividend / divisor;
+    // bigint division truncates; step down when a negative quotient left a remainder
+    return dividend % divisor !== 0n && dividend < 0n !== divisor < 0n ? quotient - 1n : quotient;
+}
+const DATE_TIME_RE = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2}):(\d{2})Z$/;
+/** The instant as a count of `unit`s since 1970-01-01T00:00:00Z. */
+function instantCount(instant, unit) {
+    if (unit !== 'day' && unit !== 'second') {
+        invalid('unit', unit);
+    }
+    if (typeof instant === 'number') {
+        if (unit !== 'second' || !Number.isSafeInteger(instant)) {
+            throw new RangeError(`Unix time ${instant} needs whole seconds and unit 'second'`);
+        }
+        return instant;
+    }
+    if (typeof instant === 'string' && instant.length > 10) {
+        const match = DATE_TIME_RE.exec(instant);
+        if (unit !== 'second' || match === null) {
+            throw new RangeError(`Invalid instant "${instant}" (YYYY-MM-DDTHH:MM:SSZ, unit 'second')`);
+        }
+        const hours = Number(match[2]);
+        const minutes = Number(match[3]);
+        const seconds = Number(match[4]);
+        if (hours > 23 || minutes > 59 || seconds > 59) {
+            throw new RangeError(`Invalid instant "${instant}"`);
+        }
+        return dayNumber(dateFields(match[1])) * 86_400 + hours * 3600 + minutes * 60 + seconds;
+    }
+    const days = dayNumber(dateFields(instant));
+    return unit === 'day' ? days : days * 86_400;
+}
+function spanOf(period, unit) {
+    const start = instantCount(period.start, unit);
+    const end = instantCount(period.end, unit);
+    if (!(end > start)) {
+        throw new RangeError('A period must end after it starts');
+    }
+    return { start, end };
+}
+/**
+ * The part of `price` for the `used` part of a billing `period`: `price × used / period`, counted in
+ * days (or seconds), exact and rounded once (to the currency's exponent with a mode, or to a
+ * policy's scale; default 'halfExpand'). Periods are end-exclusive.
+ *
+ *     prorate(money('30', 'EUR'), {
+ *       period: { start: '2026-03-01', end: '2026-04-01' },
+ *       used: { start: '2026-03-11', end: '2026-04-01' },
+ *     }, 'halfEven')   // 20.32 EUR (21 of 31 days)
+ */
+export function prorate(price, options, rounding = DEFAULT_ROUNDING) {
+    const unit = options.unit ?? 'day';
+    const period = spanOf(options.period, unit);
+    const usedStart = instantCount(options.used.start, unit);
+    const usedEnd = instantCount(options.used.end, unit);
+    if (!(usedStart >= period.start && usedEnd <= period.end && usedEnd >= usedStart)) {
+        throw new RangeError('The used part must lie inside the period');
+    }
+    const fraction = ratio(BigInt(usedEnd - usedStart), BigInt(period.end - period.start));
+    return multiplyAndRound(price, fraction, rounding);
+}
+/**
+ * Splits one period's price at change points (plan changes), in proportion to the days (or seconds)
+ * in each piece, through `allocate`, so the pieces always sum exactly to the price.
+ *
+ *     splitPeriod(money('30', 'EUR'), {
+ *       period: { start: '2026-03-01', end: '2026-04-01' },
+ *       at: ['2026-03-11', '2026-03-20'],
+ *     })   // [9.68 EUR, 8.71 EUR, 11.61 EUR]
+ */
+export function splitPeriod(price, options) {
+    const unit = options.unit ?? 'day';
+    const period = spanOf(options.period, unit);
+    const weights = [];
+    let previous = period.start;
+    for (const point of options.at) {
+        const count = instantCount(point, unit);
+        if (!(count > previous && count < period.end)) {
+            throw new RangeError('Change points must increase and lie strictly inside the period');
+        }
+        weights.push(count - previous);
+        previous = count;
+    }
+    weights.push(period.end - previous);
+    return allocate(price, weights, { remainder: options.remainder ?? 'largest' });
+}
+//# sourceMappingURL=finance.js.map