Read a YEARFRAC span the way Excel does, on every basis

[habdelra]

YEARFRAC is the day-count primitive DISC and PRICEDISC divide by. It read its arguments in four ways Excel does not, so this fixes all four in the one function, and closes three argument-checking holes in the callers.

What it read wrong

Basis 4 was a raw 30/360, not the European 30/360 it names. The convention moves a day-31 endpoint onto the 30th at both ends before differencing. The arm reached the day numbers untouched, so neither moved — and the error is a day in whichever direction the 31 sits, since pulling the start back lengthens a span while pulling the end back shortens it.

span	before ×360	now ×360
2021-07-31 → 2022-09-04	393	394
2023-06-29 → 2023-08-31	62	61
2023-01-31 → 2023-08-31	210	210

That last row is the span that agrees either way — 31 at both ends shifts twice and the two shifts cancel — which is every coupon-period span on a month-end schedule.

Basis 0 had no February rule. The US 30/360 counts a February that a span opens on as a whole 30-day month, and closes the same way only when the span also ends on a February month end. YEARFRAC(DATE(2025, 2, 28), DATE(2026, 9, 12), 0) counted 554 days where it should count 552.

The arguments were read in the order given rather than as a span. A start later than the end returned a negative fraction, and because bases 0 and 1 read their two endpoints asymmetrically, the magnitude was wrong too — basis 0 pulled the wrong end onto the 30th, and basis 1 fell into its multi-year branch and averaged over a year count of zero, so YEARFRAC(DATE(2019, 5, 30), DATE(2018, 6, 29), 1) returned NaN. That one is worse than a wrong number: NaN sits outside the Excel error model, so ISNUMBER answers false, arithmetic propagates it, and it is not JSON-representable.

A time of day counted as part of a day count. A partial day was carried up to a whole one, so YEARFRAC(TODAY(), NOW(), 1) was a day rather than nothing. This is the shape any call reading the clock arrives in.

The callers

DISC and PRICEDISC now raise #NUM! unless settlement precedes maturity, as their TBILL siblings already did — a year fraction measures how long a span is rather than which way it runs, so it cannot report a transposed pair on their behalf. Before, a transposed pair answered a negative discount, a settlement on the maturity date answered Infinity, and PRICEDISC answered a price above redemption. Both also parse their basis instead of coercing it, so a non-numeric basis is a #VALUE! rather than a silent US 30/360; and ACCRINT truncates its frequency and basis, as every other function taking them does.

What settles the rules

Four independent Excel-compatible implementations agree on every rule here — the two clamps, the February clauses, the swap, and the truncation:

• LibreOffice scaddins/source/analysis/analysishelper.cxx, GetYearFrac
• Apache POI YearFracCalculator, whose algorithm follows Wheeler's spec and whose expectations come from Excel-produced spreadsheets
• fsprojects/ExcelFinancialFunctions daycountbasis.fs, COM-tested against Excel
• David Wheeler's YEARFRAC specification, reverse-engineered from a 32.9-million-case cross-product against Excel itself, which states the truncation and the swap outright and notes for basis 4 that February 28th and 29th are not to be touched at all

Cross-checked against a headless LibreOffice recalc over 800 spans biased toward February and month ends, on all five bases: 0 disagreements, against 405–458 per basis before.

One caution recorded in UPSTREAM-DIFFS.md for whoever runs that differential next: on basis 4 LibreOffice's own getDisc divides by the clamped count while its getPricedisc and getAccrint multiply by the unclamped one, so PRICEDISC and ACCRINT part from LibreOffice on basis 4. ExcelFinancialFunctions uses its clamped counter throughout, which is the shape here.

Against main

Merged rather than rebased. ACCRINT's own work landed on main meanwhile, and the two arrived at the same reading of these conventions from opposite ends: its bond-schedule US 30/360 carries the last-day-of-February rules and its European 30/360 does not, which is exactly what basis 0 and basis 4 do here. The code merged without conflict, and basis 0 agrees with that schedule's couponDays360 on every one of 3,270,403 ordered date pairs — two implementations written independently, landing on the same count.

That also means the rule was written out twice, so basis 4 now counts through the days360 helper main introduced rather than keeping its own copy of the clamp. Basis 0 keeps its ladder: unifying it as well would have to move couponDays360 and lastDayOfMonth out of financial.ts and past their other callers, which is more than a merge should carry.

Only the two markdown files conflicted, both additively. The changelog entry claiming this reading carries into ACCRINT is corrected there — ACCRINT no longer divides by a year fraction at all.

Cases

Seventeen coverage cases, and each is mutation-checked — nine mutations, every one caught by exactly the cases meant to catch it:

mutation	caught by
no basis-4 clamp	day-31 start, day-31 end
clamp only one end	the other end's case, and the both-ends case
basis 4 reads month ends, not day 31	the two February basis-4 cases
no February clauses on basis 0	the February start, February-to-February, February-to-March-31 cases
February end clamp made unconditional	the ordinary-start-to-February-end case
arguments read in order	the three reversed spans, one per asymmetric basis
no truncation	the two time-of-day cases
DAYS360 European drift	the paired 61-day case
basis coerced / ACCRINT untruncated	the #VALUE! and fractional-basis cases

Expected values are written as the arithmetic they come from (394 / 360, 1000 * 0.1 * (75 / 360)) rather than as decimals, so the derivation is visible and no tolerance is needed. The suite is at 1150 cases across 6 time zones, 829 of 830 functions, and the one remaining known defect is ACCRINT on basis 1.

The markdown tables in UPSTREAM-DIFFS.md re-pad their columns when the pre-commit hook runs prettier over them; the only content changes there are the two new rows and the two notes.

[Copilot]

Pull request overview

This PR fixes YEARFRAC basis 4 to correctly implement the European 30/360 convention by clamping day-31 to day-30 at both ends of the span before differencing, aligning behavior with Excel-compatible implementations and ensuring downstream financial functions that rely on YEARFRAC (e.g., DISC, PRICEDISC, ACCRINT) inherit the corrected behavior.

Changes:

• Correct yearFrac(..., basis=4) to clamp start/end day 31 → 30 before computing the 30/360 difference.
• Add function-coverage fixture cases covering basis 4 (start=31, end=31, both ends=31) and contrasting with basis 0 behavior.
• Document the upstream divergence and note the fix in changelog and upstream-diffs documentation.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
packages/bxl/src/formulajs/dateSerial.ts	Fixes YEARFRAC basis 4 by applying European 30/360 clamping rules before computing the fraction.
packages/bxl/tests/unit/fixtures/function-coverage/formula-date.ts	Adds coverage cases that distinguish European 30/360 basis 4 behavior from raw 30/360 and from US 30/360 basis 0.
packages/bxl/src/formulajs/UPSTREAM-DIFFS.md	Records the YEARFRAC (basis 4) divergence from upstream and explains the corrected behavior.
packages/bxl/CHANGELOG.md	Adds a changelog entry for the basis 4 fix (but includes a small indentation regression to address).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.