@svgrid/enterprise 3.0.2 → 3.1.0

package/dist/sheet/packs/database.js

@@ -0,0 +1,142 @@
+/**
+ * Excel's Database family: the twelve aggregates that read a labelled
+ * block of records through a labelled block of criteria.
+ *
+ * All twelve share one shape, `D<agg>(database, field, criteria)`, and all
+ * the interesting behaviour is in how the criteria block is read:
+ *
+ *   - Its first row is header names, matched against the database's own
+ *     headers by text, ignoring case. A header the database does not have
+ *     matches nothing.
+ *   - Every row UNDER the header is one alternative: the conditions across
+ *     a row are ANDed, and the rows are ORed. That is Excel's advanced
+ *     filter grammar, and it is why the criteria block is two-dimensional
+ *     rather than a list.
+ *   - An empty criteria cell places no condition, so a criteria block that
+ *     is nothing but headers matches every record.
+ *
+ * `field` is either a header's text or its one-based position. Excel takes
+ * both, and a model built by hand usually holds the text while one built
+ * by a formula holds the number.
+ *
+ * These are the only aggregates that need the 2-D shape of their range
+ * rather than its flattened values, so they read `a.grids` throughout.
+ */
+import { err, isError } from '../ast.js';
+import { toText, matchesCriterion, numericOnly, isBlank } from '../coerce.js';
+const nth = (a, i) => a.args[i]?.[0] ?? '';
+/** A header row into a lookup from its lower-cased label to its column. */
+function headerIndex(header) {
+    const out = new Map();
+    header.forEach((label, i) => {
+        const key = toText(label).trim().toLowerCase();
+        // The first of a duplicated label wins, as Excel's own resolution does.
+        if (key !== '' && !out.has(key))
+            out.set(key, i);
+    });
+    return out;
+}
+/** The column `field` names, or -1 when it names none. */
+function fieldColumn(field, header) {
+    if (typeof field === 'number') {
+        const at = Math.trunc(field) - 1;
+        return at >= 0 && at < header.length ? at : -1;
+    }
+    const key = toText(field).trim().toLowerCase();
+    return headerIndex(header).get(key) ?? -1;
+}
+/**
+ * The records that satisfy the criteria block, as rows of the database.
+ *
+ * A criteria row with every cell blank matches everything, which is what
+ * Excel does and what makes a criteria block of headers alone a no-op.
+ */
+function selected(database, criteria) {
+    const dbHeader = database[0] ?? [];
+    const index = headerIndex(dbHeader);
+    const critHeader = criteria[0] ?? [];
+    const records = database.slice(1);
+    const rules = criteria.slice(1);
+    if (rules.length === 0)
+        return [...records];
+    // Each criteria row becomes a list of (column, condition) pairs once,
+    // rather than once per record.
+    const alternatives = rules.map((row) => critHeader.flatMap((label, c) => {
+        const condition = row[c];
+        if (condition === undefined || isBlank(condition))
+            return [];
+        const column = index.get(toText(label).trim().toLowerCase());
+        // A criteria header the database does not carry can never match.
+        return [{ column: column ?? -1, condition }];
+    }));
+    return records.filter((record) => alternatives.some((row) => row.every(({ column, condition }) => column >= 0 && matchesCriterion(record[column] ?? '', condition))));
+}
+/** The values of `field` across the records that match. */
+function column(a) {
+    const database = a.grids[0];
+    const criteria = a.grids[2];
+    if (!database || !criteria)
+        return err('#VALUE!');
+    const header = database[0] ?? [];
+    const at = fieldColumn(nth(a, 1), header);
+    if (at < 0)
+        return err('#VALUE!');
+    const out = [];
+    for (const record of selected(database, criteria)) {
+        const v = record[at] ?? '';
+        if (isError(v))
+            return v;
+        out.push(v);
+    }
+    return out;
+}
+/** Wrap an aggregate so it sees only the matching values. */
+const over = (agg) => (a) => {
+    const values = column(a);
+    return Array.isArray(values) ? agg(values) : values;
+};
+/** The same, over the numbers among them, with Excel's empty-set answer. */
+const overNumbers = (agg, empty = err('#NUM!')) => over((values) => {
+    const ns = numericOnly(values);
+    return ns.length === 0 ? empty : agg(ns);
+});
+function variance(values, sample) {
+    const n = values.length;
+    if (n < (sample ? 2 : 1))
+        return err('#DIV/0!');
+    const mean = values.reduce((x, y) => x + y, 0) / n;
+    const ss = values.reduce((acc, v) => acc + (v - mean) ** 2, 0);
+    return ss / (sample ? n - 1 : n);
+}
+const stdev = (values, sample) => {
+    const v = variance(values, sample);
+    return typeof v === 'number' ? Math.sqrt(v) : v;
+};
+export const DATABASE_FUNCTIONS = {
+    DSUM: overNumbers((ns) => ns.reduce((x, y) => x + y, 0), 0),
+    DPRODUCT: overNumbers((ns) => ns.reduce((x, y) => x * y, 1), 0),
+    DAVERAGE: overNumbers((ns) => ns.reduce((x, y) => x + y, 0) / ns.length, err('#DIV/0!')),
+    DMAX: overNumbers((ns) => Math.max(...ns), 0),
+    DMIN: overNumbers((ns) => Math.min(...ns), 0),
+    // DCOUNT counts the numbers; DCOUNTA counts anything that is not blank.
+    DCOUNT: over((values) => numericOnly(values).length),
+    DCOUNTA: over((values) => values.filter((v) => !isBlank(v)).length),
+    DSTDEV: overNumbers((ns) => stdev(ns, true), err('#DIV/0!')),
+    DSTDEVP: overNumbers((ns) => stdev(ns, false), err('#DIV/0!')),
+    DVAR: overNumbers((ns) => variance(ns, true), err('#DIV/0!')),
+    DVARP: overNumbers((ns) => variance(ns, false), err('#DIV/0!')),
+    // DGET is the odd one: it wants exactly one match, and says so when the
+    // count is anything else.
+    DGET: over((values) => {
+        const found = values.filter((v) => !isBlank(v));
+        if (found.length === 0)
+            return err('#VALUE!');
+        if (found.length > 1)
+            return err('#NUM!');
+        return found[0];
+    }),
+};
+/** Exported for the tests, which check the criteria grammar on its own. */
+export const __selectRecords = selected;
+/** Exported for the tests: `field` resolution takes text or a position. */
+export const __fieldColumn = fieldColumn;

package/dist/sheet/packs/engineering.d.ts

@@ -0,0 +1,2 @@
+import type { SheetFunction } from '../functions.js';
+export declare const ENGINEERING_FUNCTIONS: Record<string, SheetFunction>;

package/dist/sheet/packs/engineering.js

@@ -0,0 +1,296 @@
+/**
+ * Excel's Engineering family: base conversion, the bitwise set, the unit
+ * converter, the two step functions and the error integrals.
+ *
+ * Base conversion is where Excel is least like a programming language, and
+ * the differences are the whole reason this module is careful:
+ *
+ *   - A negative number is TWO'S COMPLEMENT in a fixed ten digits, so
+ *     `=DEC2BIN(-1)` is "1111111111" and not "-1". Ten digits means ten
+ *     bits for binary, thirty for octal and forty for hex, which is where
+ *     each function's range comes from.
+ *   - `places` pads with leading zeros and is IGNORED for a negative
+ *     number, since the two's complement already fills the width. Too few
+ *     places for the digits needed is `#NUM!`, not a truncation.
+ *   - The bitwise functions work on unsigned integers below 2^48, which is
+ *     past what JavaScript's own bitwise operators can hold, so they run
+ *     through BigInt rather than `&` and `|`.
+ */
+import { err } from '../ast.js';
+import { toNumber, toText } from '../coerce.js';
+import { erf, erfc } from './special.js';
+const nth = (a, i) => a.args[i]?.[0] ?? '';
+const num = (a, i) => toNumber(nth(a, i));
+const text = (a, i) => toText(nth(a, i));
+const given = (a, i) => {
+    const v = a.args[i]?.[0];
+    return v !== undefined && v !== '';
+};
+/** Ten digits of this base is how many bits. */
+const WIDTH = { 2: 10, 8: 30, 16: 40 };
+/** Excel's ten-digit window for a base, as [min, max]. */
+function range(base) {
+    const half = Math.pow(2, WIDTH[base] - 1);
+    return [-half, half - 1];
+}
+/** A number into `base`, ten-digit two's complement for a negative. */
+function toBase(value, base, places) {
+    const n = Math.trunc(value);
+    const [lo, hi] = range(base);
+    if (n < lo || n > hi)
+        return err('#NUM!');
+    if (n < 0) {
+        // Two's complement fills the full width, so `places` has no say.
+        const wrapped = n + Math.pow(2, WIDTH[base]);
+        return wrapped.toString(base).toUpperCase();
+    }
+    const digits = n.toString(base).toUpperCase();
+    if (places === undefined || places === '')
+        return digits;
+    const want = Math.trunc(toNumber(places));
+    if (want < 0 || want > 10 || want < digits.length)
+        return err('#NUM!');
+    return digits.padStart(want, '0');
+}
+/** A string of `base` digits back to a number, reading the top bit as a sign. */
+function fromBase(raw, base) {
+    const s = raw.trim().toUpperCase();
+    if (s === '')
+        return 0;
+    if (s.length > 10)
+        return err('#NUM!');
+    const valid = base === 2 ? /^[01]+$/ : base === 8 ? /^[0-7]+$/ : /^[0-9A-F]+$/;
+    if (!valid.test(s))
+        return err('#NUM!');
+    const value = parseInt(s, base);
+    // Only a full-width word carries a sign bit, which is why "11" is 3 and
+    // "1111111111" is -1.
+    if (s.length === 10 && value >= Math.pow(2, WIDTH[base] - 1)) {
+        return value - Math.pow(2, WIDTH[base]);
+    }
+    return value;
+}
+/** A base-to-base conversion, which Excel routes through the decimal. */
+const convert = (from, to) => (a) => {
+    const value = fromBase(text(a, 0), from);
+    if (typeof value !== 'number')
+        return value;
+    return toBase(value, to, given(a, 1) ? nth(a, 1) : undefined);
+};
+/** The bitwise set's shared guard: a non-negative integer below 2^48. */
+function bitOperand(value) {
+    if (!Number.isFinite(value))
+        return null;
+    const n = Math.trunc(value);
+    if (n !== value || n < 0 || n > 281474976710655)
+        return null;
+    return BigInt(n);
+}
+const bitwise = (op) => (a) => {
+    const x = bitOperand(num(a, 0));
+    const y = bitOperand(num(a, 1));
+    if (x === null || y === null)
+        return err('#NUM!');
+    return Number(op(x, y));
+};
+/**
+ * CONVERT's unit table, as a factor into each measure's base unit.
+ *
+ * Temperature is the exception and is handled separately, because it is an
+ * affine conversion rather than a scaling: Celsius to Fahrenheit is not a
+ * multiplication.
+ */
+const UNITS = {};
+const unit = (measure, factor, ...names) => {
+    for (const n of names)
+        UNITS[n] = { measure, factor };
+};
+// Mass, base kilogram.
+unit('mass', 0.001, 'g');
+unit('mass', 1, 'kg');
+unit('mass', 0.45359237, 'lbm');
+unit('mass', 0.45359237 / 16, 'ozm');
+unit('mass', 1.6605402e-27, 'u');
+unit('mass', 0.0000647989, 'grain');
+unit('mass', 907.18474, 'ton');
+unit('mass', 1016.0469088, 'uk_ton', 'LTON', 'brton');
+unit('mass', 6.35029318, 'stone');
+unit('mass', 0.0000020, 'sg');
+// Distance, base metre.
+unit('distance', 1, 'm');
+unit('distance', 0.0254, 'in');
+unit('distance', 0.3048, 'ft');
+unit('distance', 0.9144, 'yd');
+unit('distance', 1609.344, 'mi');
+unit('distance', 1852, 'Nmi');
+unit('distance', 1e-10, 'ang');
+unit('distance', 0.0037, 'pica');
+unit('distance', 0.0254 / 72, 'Pica');
+unit('distance', 9.46073047258e15, 'ly');
+unit('distance', 3.08567758149137e16, 'parsec', 'pc');
+unit('distance', 201.168, 'survey_mi');
+// Time, base second.
+unit('time', 31557600, 'yr');
+unit('time', 86400, 'day', 'd');
+unit('time', 3600, 'hr');
+unit('time', 60, 'mn', 'min');
+unit('time', 1, 'sec', 's');
+// Pressure, base pascal.
+unit('pressure', 1, 'Pa', 'p');
+unit('pressure', 101325, 'atm', 'at');
+unit('pressure', 133.322368421, 'mmHg');
+unit('pressure', 6894.75729317, 'psi');
+unit('pressure', 100000, 'Torr');
+// Force, base newton.
+unit('force', 1, 'N');
+unit('force', 0.00001, 'dyn', 'dy');
+unit('force', 4.4482216152605, 'lbf');
+unit('force', 9.80665, 'pond');
+// Energy, base joule.
+unit('energy', 1, 'J');
+unit('energy', 0.0000001, 'e');
+unit('energy', 1.05505585262e3, 'BTU', 'btu');
+unit('energy', 4.1868, 'c');
+unit('energy', 4.184, 'cal');
+unit('energy', 1.60217733e-19, 'eV', 'ev');
+unit('energy', 1.3558179483314, 'flb');
+unit('energy', 3600000, 'Wh', 'wh');
+unit('energy', 101.3252, 'HPh', 'hh');
+// Power, base watt.
+unit('power', 1, 'W', 'w');
+unit('power', 745.69987158227, 'HP', 'h');
+unit('power', 0.73549875, 'PS');
+// Magnetism, base tesla.
+unit('magnetism', 1, 'T');
+unit('magnetism', 0.0001, 'ga');
+// Volume, base litre.
+unit('volume', 1, 'l', 'L', 'lt');
+unit('volume', 0.0000163870640693, 'in3', 'in^3');
+unit('volume', 28.316846592, 'ft3', 'ft^3');
+unit('volume', 764.554857984, 'yd3', 'yd^3');
+unit('volume', 1000, 'm3', 'm^3');
+unit('volume', 3.785411784, 'gal');
+unit('volume', 0.94635295, 'qt');
+unit('volume', 0.473176473, 'pt', 'us_pt');
+unit('volume', 0.5682612532, 'uk_pt');
+unit('volume', 0.2365882365, 'cup');
+unit('volume', 0.0295735295625, 'oz');
+unit('volume', 0.01478676478125, 'tbs');
+unit('volume', 0.00492892159375, 'tsp');
+unit('volume', 0.00492892159375, 'tspm');
+unit('volume', 158.987294928, 'barrel', 'bbl');
+unit('volume', 119240.471196, 'MTON');
+unit('volume', 158.987294928 * 6.28981, 'GRT', 'regton');
+// Area, base square metre.
+unit('area', 1, 'm2', 'm^2');
+unit('area', 4046.8564224, 'acre', 'uk_acre', 'us_acre');
+unit('area', 0.00064516, 'in2', 'in^2');
+unit('area', 0.09290304, 'ft2', 'ft^2');
+unit('area', 0.83612736, 'yd2', 'yd^2');
+unit('area', 2589988.110336, 'mi2', 'mi^2');
+unit('area', 10000, 'ha');
+unit('area', 1e-28, 'ang2', 'ang^2');
+// Information, base bit.
+unit('information', 1, 'bit');
+unit('information', 8, 'byte');
+// Speed, base metres per second.
+unit('speed', 1, 'm/s', 'm/sec');
+unit('speed', 1 / 3.6, 'm/h', 'm/hr');
+unit('speed', 1609.344 / 3600, 'mph');
+unit('speed', 1852 / 3600, 'kn', 'admkn');
+/** The SI prefixes CONVERT accepts in front of a metric unit. */
+const PREFIXES = {
+    Y: 1e24, Z: 1e21, E: 1e18, P: 1e15, T: 1e12, G: 1e9, M: 1e6, k: 1e3, h: 1e2,
+    e: 1e1, d: 1e-1, c: 1e-2, m: 1e-3, u: 1e-6, n: 1e-9, p: 1e-12, f: 1e-15,
+    a: 1e-18, z: 1e-21, y: 1e-24,
+};
+/** A unit name into its measure and its factor, prefix allowed for. */
+function lookup(name) {
+    const direct = UNITS[name];
+    if (direct)
+        return direct;
+    // A prefix only counts when what follows it is a unit in its own right.
+    const head = name.slice(0, 1);
+    const rest = name.slice(1);
+    const scale = PREFIXES[head];
+    const base = scale === undefined ? undefined : UNITS[rest];
+    if (scale !== undefined && base)
+        return { measure: base.measure, factor: base.factor * scale };
+    return null;
+}
+/** Temperature, which scales AND shifts, so it sits outside the table. */
+const TEMPERATURE = {
+    C: { toK: (v) => v + 273.15, fromK: (v) => v - 273.15 },
+    F: { toK: (v) => ((v - 32) * 5) / 9 + 273.15, fromK: (v) => ((v - 273.15) * 9) / 5 + 32 },
+    K: { toK: (v) => v, fromK: (v) => v },
+    Rank: { toK: (v) => (v * 5) / 9, fromK: (v) => (v * 9) / 5 },
+    Reau: { toK: (v) => v * 1.25 + 273.15, fromK: (v) => (v - 273.15) * 0.8 },
+};
+TEMPERATURE.cel = TEMPERATURE.C;
+TEMPERATURE.fah = TEMPERATURE.F;
+TEMPERATURE.kel = TEMPERATURE.K;
+export const ENGINEERING_FUNCTIONS = {
+    // ---- Base conversion -------------------------------------------------
+    DEC2BIN: (a) => toBase(num(a, 0), 2, given(a, 1) ? nth(a, 1) : undefined),
+    DEC2OCT: (a) => toBase(num(a, 0), 8, given(a, 1) ? nth(a, 1) : undefined),
+    DEC2HEX: (a) => toBase(num(a, 0), 16, given(a, 1) ? nth(a, 1) : undefined),
+    BIN2DEC: (a) => fromBase(text(a, 0), 2),
+    OCT2DEC: (a) => fromBase(text(a, 0), 8),
+    HEX2DEC: (a) => fromBase(text(a, 0), 16),
+    BIN2OCT: convert(2, 8),
+    BIN2HEX: convert(2, 16),
+    OCT2BIN: convert(8, 2),
+    OCT2HEX: convert(8, 16),
+    HEX2BIN: convert(16, 2),
+    HEX2OCT: convert(16, 8),
+    // ---- Bitwise ---------------------------------------------------------
+    BITAND: bitwise((x, y) => x & y),
+    BITOR: bitwise((x, y) => x | y),
+    BITXOR: bitwise((x, y) => x ^ y),
+    BITLSHIFT: (a) => {
+        const x = bitOperand(num(a, 0));
+        const by = Math.trunc(num(a, 1));
+        if (x === null || Math.abs(by) > 53)
+            return err('#NUM!');
+        const out = by >= 0 ? x << BigInt(by) : x >> BigInt(-by);
+        return out > 281474976710655n ? err('#NUM!') : Number(out);
+    },
+    BITRSHIFT: (a) => {
+        const x = bitOperand(num(a, 0));
+        const by = Math.trunc(num(a, 1));
+        if (x === null || Math.abs(by) > 53)
+            return err('#NUM!');
+        const out = by >= 0 ? x >> BigInt(by) : x << BigInt(-by);
+        return out > 281474976710655n ? err('#NUM!') : Number(out);
+    },
+    // ---- Step functions --------------------------------------------------
+    DELTA: (a) => (num(a, 0) === (given(a, 1) ? num(a, 1) : 0) ? 1 : 0),
+    GESTEP: (a) => (num(a, 0) >= (given(a, 1) ? num(a, 1) : 0) ? 1 : 0),
+    // ---- Error integrals -------------------------------------------------
+    // ERF with two arguments is the integral BETWEEN the limits.
+    ERF: (a) => (given(a, 1) ? erf(num(a, 1)) - erf(num(a, 0)) : erf(num(a, 0))),
+    'ERF.PRECISE': (a) => erf(num(a, 0)),
+    ERFC: (a) => erfc(num(a, 0)),
+    'ERFC.PRECISE': (a) => erfc(num(a, 0)),
+    // ---- Units -----------------------------------------------------------
+    CONVERT: (a) => {
+        const value = num(a, 0);
+        const from = text(a, 1);
+        const to = text(a, 2);
+        const tFrom = TEMPERATURE[from];
+        const tTo = TEMPERATURE[to];
+        if (tFrom || tTo) {
+            // Both sides have to be temperatures, or the measures do not agree.
+            if (!tFrom || !tTo)
+                return err('#N/A');
+            return tTo.fromK(tFrom.toK(value));
+        }
+        const f = lookup(from);
+        const t = lookup(to);
+        if (!f || !t)
+            return err('#N/A');
+        if (f.measure !== t.measure)
+            return err('#N/A');
+        return (value * f.factor) / t.factor;
+    },
+};

package/dist/sheet/packs/financial.d.ts

@@ -0,0 +1,5 @@
+import type { SheetFunction } from '../functions.js';
+export declare function pmt(rate: number, nper: number, pv: number, fv: number, type: 0 | 1): number;
+export declare function fv(rate: number, nper: number, pmt: number, pv: number, type: 0 | 1): number;
+export declare function pv(rate: number, nper: number, pmt: number, fv: number, type: 0 | 1): number;
+export declare const FINANCIAL_FUNCTIONS: Record<string, SheetFunction>;

package/dist/sheet/packs/financial.js

@@ -0,0 +1,220 @@
+/**
+ * Excel's time-value-of-money functions: PMT and its parts, PV, FV, NPER,
+ * RATE, NPV, IRR and straight-line depreciation.
+ *
+ * All of them share Excel's sign convention, which is the thing to get
+ * right: money you pay out is negative, money you receive is positive, so
+ * `=PMT(5%/12, 360, 200000)` is a negative payment on a positive loan and
+ * `=FV(6%/12, 120, -100)` is a positive balance from negative deposits.
+ * The closed forms below are the ones Excel documents; RATE and IRR have
+ * no closed form and are solved by Newton's method with a bisection
+ * fallback, returning `#NUM!` when neither converges, as Excel does.
+ */
+import { err } from '../ast.js';
+import { toNumber, numericOnly } from '../coerce.js';
+const num = (a, i) => toNumber(a.args[i]?.[0] ?? '');
+/** An optional argument: absent, or left empty between commas, reads as
+ *  `fallback`. A typed 0 is 0. */
+function opt(a, i, fallback) {
+    const v = a.args[i]?.[0];
+    return v === undefined || v === '' ? fallback : toNumber(v);
+}
+/** `type` is 0 for payments at the end of the period, 1 for the start. */
+const paymentType = (a, i) => (opt(a, i, 0) === 0 ? 0 : 1);
+export function pmt(rate, nper, pv, fv, type) {
+    if (rate === 0)
+        return -(pv + fv) / nper;
+    const f = Math.pow(1 + rate, nper);
+    return -(rate * (pv * f + fv)) / ((1 + rate * type) * (f - 1));
+}
+export function fv(rate, nper, pmt, pv, type) {
+    if (rate === 0)
+        return -(pv + pmt * nper);
+    const f = Math.pow(1 + rate, nper);
+    return -(pv * f + (pmt * (1 + rate * type) * (f - 1)) / rate);
+}
+export function pv(rate, nper, pmt, fv, type) {
+    if (rate === 0)
+        return -(fv + pmt * nper);
+    const f = Math.pow(1 + rate, nper);
+    return -(fv + (pmt * (1 + rate * type) * (f - 1)) / rate) / f;
+}
+function nper(rate, pmt, pv, fv, type) {
+    if (rate === 0)
+        return pmt === 0 ? err('#NUM!') : -(pv + fv) / pmt;
+    const p = pmt * (1 + rate * type);
+    const ratio = (p - fv * rate) / (p + pv * rate);
+    if (!(ratio > 0))
+        return err('#NUM!');
+    return Math.log(ratio) / Math.log(1 + rate);
+}
+/**
+ * Find a root of `f` near `guess`: Newton with a numerical derivative, then
+ * a bracketing scan and bisection when Newton wanders off. Both RATE and
+ * IRR are smooth enough for this, and the fallback is what keeps a loan
+ * with an odd guess from coming back `#NUM!` when Excel finds it.
+ */
+function solve(f, guess, low, high) {
+    let x = guess;
+    for (let i = 0; i < 100; i += 1) {
+        const y = f(x);
+        if (!Number.isFinite(y))
+            break;
+        if (Math.abs(y) < 1e-10)
+            return x;
+        const h = Math.max(1e-7, Math.abs(x) * 1e-6);
+        const slope = (f(x + h) - f(x - h)) / (2 * h);
+        if (!Number.isFinite(slope) || slope === 0)
+            break;
+        const next = x - y / slope;
+        if (!Number.isFinite(next) || next <= low || next >= high)
+            break;
+        if (Math.abs(next - x) < 1e-12)
+            return next;
+        x = next;
+    }
+    // Bracket a sign change on a grid, then bisect it.
+    const steps = 400;
+    let a = low;
+    let fa = f(a);
+    for (let i = 1; i <= steps; i += 1) {
+        const b = low + ((high - low) * i) / steps;
+        const fb = f(b);
+        if (Number.isFinite(fa) && Number.isFinite(fb) && Math.sign(fa) !== Math.sign(fb)) {
+            let lo = a;
+            let hi = b;
+            let flo = fa;
+            for (let k = 0; k < 200; k += 1) {
+                const mid = (lo + hi) / 2;
+                const fm = f(mid);
+                if (Math.abs(fm) < 1e-10 || hi - lo < 1e-14)
+                    return mid;
+                if (Math.sign(fm) === Math.sign(flo)) {
+                    lo = mid;
+                    flo = fm;
+                }
+                else
+                    hi = mid;
+            }
+            return (lo + hi) / 2;
+        }
+        a = b;
+        fa = fb;
+    }
+    return null;
+}
+function npv(rate, flows) {
+    let total = 0;
+    for (let i = 0; i < flows.length; i += 1)
+        total += flows[i] / Math.pow(1 + rate, i + 1);
+    return total;
+}
+/** The balance a loan carries into period `per`, which IPMT charges
+ *  interest on and PPMT pays down: the future value after per-1 payments. */
+function balanceBefore(rate, per, payment, present, type) {
+    if (per === 1)
+        return type === 1 ? 0 : -present;
+    if (type === 1)
+        return fv(rate, per - 2, payment, present, 1) - payment;
+    return fv(rate, per - 1, payment, present, 0);
+}
+export const FINANCIAL_FUNCTIONS = {
+    PMT: (a) => {
+        const rate = num(a, 0);
+        const n = num(a, 1);
+        if (n === 0 || rate <= -1)
+            return err('#NUM!');
+        return pmt(rate, n, num(a, 2), opt(a, 3, 0), paymentType(a, 4));
+    },
+    FV: (a) => {
+        const rate = num(a, 0);
+        if (rate <= -1)
+            return err('#NUM!');
+        return fv(rate, num(a, 1), num(a, 2), opt(a, 3, 0), paymentType(a, 4));
+    },
+    PV: (a) => {
+        const rate = num(a, 0);
+        if (rate <= -1)
+            return err('#NUM!');
+        return pv(rate, num(a, 1), num(a, 2), opt(a, 3, 0), paymentType(a, 4));
+    },
+    NPER: (a) => {
+        const rate = num(a, 0);
+        if (rate <= -1)
+            return err('#NUM!');
+        return nper(rate, num(a, 1), num(a, 2), opt(a, 3, 0), paymentType(a, 4));
+    },
+    // IPMT(rate, per, nper, pv, [fv], [type]): the interest part of the
+    // payment in period `per`, the balance carried into it times the rate.
+    IPMT: (a) => {
+        const rate = num(a, 0);
+        const per = num(a, 1);
+        const n = num(a, 2);
+        const present = num(a, 3);
+        const type = paymentType(a, 5);
+        if (per < 1 || per > n || n === 0 || rate <= -1)
+            return err('#NUM!');
+        const payment = pmt(rate, n, present, opt(a, 4, 0), type);
+        return balanceBefore(rate, per, payment, present, type) * rate;
+    },
+    PPMT: (a) => {
+        const rate = num(a, 0);
+        const per = num(a, 1);
+        const n = num(a, 2);
+        const present = num(a, 3);
+        const type = paymentType(a, 5);
+        if (per < 1 || per > n || n === 0 || rate <= -1)
+            return err('#NUM!');
+        const payment = pmt(rate, n, present, opt(a, 4, 0), type);
+        return payment - balanceBefore(rate, per, payment, present, type) * rate;
+    },
+    RATE: (a) => {
+        const n = num(a, 0);
+        const payment = num(a, 1);
+        const present = num(a, 2);
+        const future = opt(a, 3, 0);
+        const type = paymentType(a, 4);
+        const guess = opt(a, 5, 0.1);
+        if (n <= 0)
+            return err('#NUM!');
+        const f = (r) => {
+            if (r === 0)
+                return present + payment * n + future;
+            const g = Math.pow(1 + r, n);
+            return present * g + (payment * (1 + r * type) * (g - 1)) / r + future;
+        };
+        const root = solve(f, guess, -0.999999, 10);
+        return root === null ? err('#NUM!') : root;
+    },
+    // NPV(rate, value1, ...): the first flow is discounted one period, as in
+    // Excel, so an investment made today goes outside the call: =NPV(...)+A1.
+    NPV: (a) => {
+        const rate = num(a, 0);
+        if (rate <= -1)
+            return err('#NUM!');
+        return npv(rate, numericOnly(a.args.slice(1).flat()));
+    },
+    // IRR(values, [guess]): the rate at which the flows, the first one at
+    // time zero, sum to nothing. Needs at least one inflow and one outflow.
+    IRR: (a) => {
+        const flows = numericOnly(a.args[0] ?? []);
+        const guess = opt(a, 1, 0.1);
+        if (!flows.some((v) => v > 0) || !flows.some((v) => v < 0))
+            return err('#NUM!');
+        const f = (r) => {
+            let total = 0;
+            for (let i = 0; i < flows.length; i += 1)
+                total += flows[i] / Math.pow(1 + r, i);
+            return total;
+        };
+        const root = solve(f, guess, -0.999999, 10);
+        return root === null ? err('#NUM!') : root;
+    },
+    // SLN(cost, salvage, life): straight-line depreciation for one period.
+    SLN: (a) => {
+        const life = num(a, 2);
+        if (life === 0)
+            return err('#DIV/0!');
+        return (num(a, 0) - num(a, 1)) / life;
+    },
+};

package/dist/sheet/packs/math-stats.d.ts

@@ -0,0 +1,2 @@
+import type { SheetFunction } from '../functions.js';
+export declare const MATH_STATS_FUNCTIONS: Record<string, SheetFunction>;