@jarenjs/core 0.9.2 → 0.34.0

package/src/finance/interest.js

@@ -0,0 +1,63 @@
+//@ts-check
+/**
+ * @file Interest math: simple and compound interest, nominal
+ * ↔ effective rate conversion, and continuous compounding. All pure.
+ */
+
+/**
+ * Simple interest accrued (not the total).
+ * @param {number} principal @param {number} rate per period @param {number} time periods
+ * @returns {number}
+ */
+export function simpleInterest(principal, rate, time) {
+  return principal * rate * time;
+}
+
+/**
+ * Compound amount (principal + interest) after `time` years compounded
+ * `periodsPerYear` times per year.
+ * @param {number} principal @param {number} annualRate @param {number} time years
+ * @param {number} [periodsPerYear]
+ * @returns {number}
+ */
+export function compoundAmount(principal, annualRate, time, periodsPerYear = 1) {
+  return principal * Math.pow(1 + annualRate / periodsPerYear, periodsPerYear * time);
+}
+
+/**
+ * Compound interest earned (amount − principal).
+ * @param {number} principal @param {number} annualRate @param {number} time
+ * @param {number} [periodsPerYear]
+ * @returns {number}
+ */
+export function compoundInterest(principal, annualRate, time, periodsPerYear = 1) {
+  return compoundAmount(principal, annualRate, time, periodsPerYear) - principal;
+}
+
+/**
+ * Effective annual rate (APY/EAR) from a nominal annual rate compounded
+ * `periodsPerYear` times.
+ * @param {number} nominal @param {number} periodsPerYear
+ * @returns {number}
+ */
+export function nominalToEffective(nominal, periodsPerYear) {
+  return Math.pow(1 + nominal / periodsPerYear, periodsPerYear) - 1;
+}
+
+/**
+ * Nominal annual rate from an effective annual rate.
+ * @param {number} effective @param {number} periodsPerYear
+ * @returns {number}
+ */
+export function effectiveToNominal(effective, periodsPerYear) {
+  return periodsPerYear * (Math.pow(1 + effective, 1 / periodsPerYear) - 1);
+}
+
+/**
+ * Continuously-compounded amount: `P·e^(rt)`.
+ * @param {number} principal @param {number} annualRate @param {number} time
+ * @returns {number}
+ */
+export function continuousCompound(principal, annualRate, time) {
+  return principal * Math.exp(annualRate * time);
+}

package/src/finance/returns.js

@@ -0,0 +1,90 @@
+//@ts-check
+/**
+ * @file Return & risk statistics: CAGR, holding-period
+ * return, volatility, Sharpe ratio and maximum drawdown. Pure.
+ */
+
+/**
+ * Compound annual growth rate.
+ * @param {number} begin @param {number} end @param {number} years
+ * @returns {number}
+ */
+export function cagr(begin, end, years) {
+  if (begin <= 0 || years <= 0) return NaN;
+  return Math.pow(end / begin, 1 / years) - 1;
+}
+
+/**
+ * Holding-period return, including any income.
+ * @param {number} begin @param {number} end @param {number} [income]
+ * @returns {number}
+ */
+export function holdingPeriodReturn(begin, end, income = 0) {
+  if (begin === 0) return NaN;
+  return (end - begin + income) / begin;
+}
+
+/**
+ * Convert a price series to a per-step simple-return series.
+ * @param {ArrayLike<number>} prices
+ * @returns {number[]}
+ */
+export function returnsOf(prices) {
+  const out = [];
+  for (let i = 1; i < prices.length; i++) {
+    out.push((prices[i] - prices[i - 1]) / prices[i - 1]);
+  }
+  return out;
+}
+
+/**
+ * Volatility: the (sample) standard deviation of a return series.
+ * @param {ArrayLike<number>} returns
+ * @param {boolean} [population] use population (÷N) instead of sample (÷N−1)
+ * @returns {number}
+ */
+export function volatility(returns, population = false) {
+  const n = returns.length;
+  if (n < 2) return 0;
+  let mean = 0;
+  for (let i = 0; i < n; i++) mean += returns[i];
+  mean /= n;
+  let variance = 0;
+  for (let i = 0; i < n; i++) variance += (returns[i] - mean) ** 2;
+  return Math.sqrt(variance / (population ? n : n - 1));
+}
+
+/**
+ * Sharpe ratio: mean excess return over its volatility.
+ * @param {ArrayLike<number>} returns
+ * @param {number} [riskFree] per-step risk-free rate
+ * @returns {number}
+ */
+export function sharpe(returns, riskFree = 0) {
+  const n = returns.length;
+  if (n === 0) return NaN;
+  let mean = 0;
+  for (let i = 0; i < n; i++) mean += returns[i];
+  mean /= n;
+  const vol = volatility(returns);
+  return vol === 0 ? NaN : (mean - riskFree) / vol;
+}
+
+/**
+ * Maximum drawdown of an equity curve: the largest peak-to-trough drop as
+ * a positive fraction (0.2 = a 20% drawdown).
+ * @param {ArrayLike<number>} values
+ * @returns {number}
+ */
+export function maxDrawdown(values) {
+  let peak = -Infinity;
+  let maxDd = 0;
+  for (let i = 0; i < values.length; i++) {
+    if (values[i] > peak) peak = values[i];
+    if (peak > 0) {
+      const dd = (peak - values[i]) / peak;
+      if (dd > maxDd) maxDd = dd;
+    }
+  }
+  return maxDd;
+}

package/src/finance/tvm.js

@@ -0,0 +1,94 @@
+//@ts-check
+/**
+ * @file Time Value of Money. The five TVM quantities — N,
+ * I/Y, PV, PMT, FV — obey one identity; each function here solves for its
+ * own variable. Sign convention follows the standard cash-flow model
+ * (money in is positive, money out negative), matching Excel/HP-12C:
+ *
+ *   PV·(1+i)^n + PMT·(1 + i·type)·((1+i)^n − 1)/i + FV = 0
+ *
+ * `type` is 0 for an ordinary annuity (payment at period end) or 1 for an
+ * annuity-due (payment at period begin). Rates are per period; a caller
+ * with an annual rate and monthly periods passes `rate/12`.
+ *
+ * Pure and zero-dep except `math/solve` for the iterative `rate`.
+ */
+
+import { newtonRaphson, bisect } from '../math/solve.js';
+
+/**
+ * Future value.
+ * @param {number} rate @param {number} nper @param {number} pmt
+ * @param {number} [pv] @param {number} [type]
+ * @returns {number}
+ */
+export function fv(rate, nper, pmt, pv = 0, type = 0) {
+  if (rate === 0) return -(pv + pmt * nper);
+  const g = Math.pow(1 + rate, nper);
+  return -(pv * g + pmt * (1 + rate * type) * (g - 1) / rate);
+}
+
+/**
+ * Present value.
+ * @param {number} rate @param {number} nper @param {number} pmt
+ * @param {number} [fval] @param {number} [type]
+ * @returns {number}
+ */
+export function pv(rate, nper, pmt, fval = 0, type = 0) {
+  if (rate === 0) return -(fval + pmt * nper);
+  const g = Math.pow(1 + rate, nper);
+  return -(fval + pmt * (1 + rate * type) * (g - 1) / rate) / g;
+}
+
+/**
+ * Payment per period.
+ * @param {number} rate @param {number} nper @param {number} pval
+ * @param {number} [fval] @param {number} [type]
+ * @returns {number}
+ */
+export function pmt(rate, nper, pval, fval = 0, type = 0) {
+  if (nper === 0) return NaN;
+  if (rate === 0) return -(pval + fval) / nper;
+  const g = Math.pow(1 + rate, nper);
+  return -(pval * g + fval) / ((1 + rate * type) * (g - 1) / rate);
+}
+
+/**
+ * Number of periods.
+ * @param {number} rate @param {number} pmtv @param {number} pval
+ * @param {number} [fval] @param {number} [type]
+ * @returns {number}
+ */
+export function nper(rate, pmtv, pval, fval = 0, type = 0) {
+  if (rate === 0) {
+    if (pmtv === 0) return NaN;
+    return -(pval + fval) / pmtv;
+  }
+  const a = pmtv * (1 + rate * type);
+  const num = a - fval * rate;
+  const den = a + pval * rate;
+  return Math.log(num / den) / Math.log(1 + rate);
+}
+
+/**
+ * Periodic interest rate, solved iteratively (Newton, bisection
+ * fallback). Returns `NaN` if no rate is found.
+ * @param {number} nperv @param {number} pmtv @param {number} pval
+ * @param {number} [fval] @param {number} [type] @param {number} [guess]
+ * @returns {number}
+ */
+export function rate(nperv, pmtv, pval, fval = 0, type = 0, guess = 0.1) {
+  const f = (r) => {
+    if (r === 0) return pval + pmtv * nperv + fval;
+    const g = Math.pow(1 + r, nperv);
+    return pval * g + pmtv * (1 + r * type) * (g - 1) / r + fval;
+  };
+  const df = (r) => {
+    const h = 1e-6;
+    return (f(r + h) - f(r - h)) / (2 * h);
+  };
+  const n = newtonRaphson(f, df, guess, { tol: 1e-9, maxIter: 100 });
+  if (n.converged && isFinite(n.root)) return n.root;
+  const b = bisect(f, -0.9999, 1e6, { tol: 1e-9, maxIter: 200 });
+  return b.converged ? b.root : NaN;
+}

package/src/function.js

@@ -14,7 +14,6 @@ import {
  * @param {string | string[] | undefined} _key a key or an array of keys
  * @returns {boolean} returns always true
  */
-// eslint-disable-next-line no-unused-vars
 export function trueThat(whatever, _path = undefined, _root = undefined, _key = undefined) {
   const that = true;
   return whatever === true || that;
@@ -29,7 +28,6 @@ export function trueThat(whatever, _path = undefined, _root = undefined, _key =
  * @param {string | string[] | undefined} _key a key or an array of keys
  * @returns {boolean} returns always true
  */
-// eslint-disable-next-line no-unused-vars
 export function falseThat(whatever, _path = undefined, _root = undefined, _key = undefined) {
   // eslint-disable-next-line no-constant-binary-expression
   return false && whatever;

package/src/geo/angle.js

@@ -0,0 +1,12 @@
+//@ts-check
+
+// Degree↔radian conversion factors shared by every geo module that
+// trades between RFC 7946's decimal degrees and the radians the
+// trigonometry needs. Internal to the kernel: the barrel does not
+// re-export them, because callers hold degrees end to end.
+
+/** Radians per degree — multiply degrees by this to get radians. */
+export const DEG = Math.PI / 180;
+
+/** Degrees per radian — multiply radians by this to get degrees. */
+export const RAD = 180 / Math.PI;

package/src/geo/bbox.js

@@ -0,0 +1,80 @@
+//@ts-check
+
+//#region Bounding boxes
+// A GeoJSON `bbox` is a flat array `[west, south, east, north]` (RFC
+// 7946 section 5): all axes of the most south-westerly position, then
+// all axes of the most north-easterly. It stays a plain array here, so a
+// computed box can be written straight into a document as its `bbox`
+// member.
+//
+// Boxes are the cheap half of every spatial test. Overlap between two
+// boxes is four comparisons, so it rejects the overwhelming majority of
+// candidate pairs before any real geometry runs — the same role
+// `equirectDistance` plays for distance, and the shape a spatial index
+// ultimately accelerates.
+
+/**
+ * The bounding box of a list of positions, as `[west, south, east, north]`.
+ * Returns null for an empty list — there is no box that bounds nothing,
+ * and an all-Infinity placeholder would silently intersect everything.
+ * @param {Array<number[]>} positions
+ * @returns {number[] | null}
+ */
+export function bboxOfPositions(positions) {
+  const n = positions.length;
+  if (n === 0)
+    return null;
+  let west = Infinity;
+  let south = Infinity;
+  let east = -Infinity;
+  let north = -Infinity;
+  for (let i = 0; i < n; i++) {
+    const x = positions[i][0];
+    const y = positions[i][1];
+    if (x < west) west = x;
+    if (x > east) east = x;
+    if (y < south) south = y;
+    if (y > north) north = y;
+  }
+  return [west, south, east, north];
+}
+
+/**
+ * Whether two bounding boxes share any area. Boxes that merely touch
+ * along an edge count as intersecting, matching `pointInRing`'s
+ * treatment of a boundary as inside.
+ * @param {number[]} a - [west, south, east, north]
+ * @param {number[]} b
+ * @returns {boolean}
+ */
+export function bboxIntersects(a, b) {
+  return a[0] <= b[2] && b[0] <= a[2] && a[1] <= b[3] && b[1] <= a[3];
+}
+
+/**
+ * Whether a bounding box contains a position (edges included).
+ * @param {number[]} box - [west, south, east, north]
+ * @param {number} x - longitude
+ * @param {number} y - latitude
+ * @returns {boolean}
+ */
+export function bboxContains(box, x, y) {
+  return x >= box[0] && x <= box[2] && y >= box[1] && y <= box[3];
+}
+
+/**
+ * The smallest box containing both inputs.
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {number[]}
+ */
+export function bboxUnion(a, b) {
+  return [
+    a[0] < b[0] ? a[0] : b[0],
+    a[1] < b[1] ? a[1] : b[1],
+    a[2] > b[2] ? a[2] : b[2],
+    a[3] > b[3] ? a[3] : b[3],
+  ];
+}
+
+//#endregion

package/src/geo/distance.js

@@ -0,0 +1,155 @@
+//@ts-check
+
+//#region Geodesic measurement
+// Distance, bearing and destination on the WGS 84 sphere, over GeoJSON
+// positions: `[longitude, latitude]` in decimal degrees, in that order
+// (RFC 7946 section 3.1.1 — the order everyone gets backwards).
+//
+// Why this module has to exist at all: longitude degrees are not a fixed
+// distance. A degree of longitude spans ~111 km at the equator and ~68 km
+// at 52°N, so treating a position as a planar x/y point and taking the
+// Euclidean norm is **64% wrong over 1 km at 52°N**. There is no
+// "close enough" version of that mistake.
+//
+// Two formulas, because they trade accuracy against cost differently:
+//
+//   haversine     13.6 ns/op, <0.5% error anywhere on the sphere
+//   equirectangular 2.0 ns/op, 0.02% at 430 km, 12.4% intercontinental
+//
+// So `equirectDistance` is the screening form — the cheap test that
+// decides which candidates deserve the real one — and `haversineDistance`
+// is the answer. That is the same build-then-probe shape the query
+// engine's hash join uses, and the reason both are exported rather than
+// one being hidden.
+//
+// The ellipsoid is deliberately not modelled. Vincenty is accurate to
+// 0.5 mm but fails to converge near antipodal points, and Karney's 2013
+// algorithm that fixes that is a much larger body of code; the sphere is
+// within half a percent everywhere and is what GeoJSON consumers expect.
+// A caller needing survey accuracy needs a geodesy library, and this
+// says so rather than pretending.
+
+import { DEG, RAD } from './angle.js';
+
+/** IUGG mean Earth radius in metres — the sphere GeoJSON distances use. */
+export const EARTH_RADIUS = 6371008.8;
+
+/**
+ * Great-circle distance between two positions, in metres.
+ *
+ * @param {number} lon1 - longitude of the first position, degrees
+ * @param {number} lat1 - latitude of the first position, degrees
+ * @param {number} lon2 - longitude of the second position, degrees
+ * @param {number} lat2 - latitude of the second position, degrees
+ * @param {number} [radius] - sphere radius, to answer in other units
+ * @returns {number} distance in metres (or in `radius`'s unit)
+ * @example
+ * haversineDistance(4.9041, 52.3676, 2.3522, 48.8566); // 429_862 (Amsterdam-Paris)
+ */
+export function haversineDistance(lon1, lat1, lon2, lat2, radius = EARTH_RADIUS) {
+  const p1 = lat1 * DEG;
+  const p2 = lat2 * DEG;
+  const dp = (lat2 - lat1) * DEG;
+  const dl = (lon2 - lon1) * DEG;
+  const sdp = Math.sin(dp * 0.5);
+  const sdl = Math.sin(dl * 0.5);
+  const a = sdp * sdp + Math.cos(p1) * Math.cos(p2) * sdl * sdl;
+  // asin form rather than atan2: same result, one fewer transcendental
+  return 2 * radius * Math.asin(Math.sqrt(a < 1 ? a : 1));
+}
+
+/**
+ * Equirectangular approximation of the distance between two positions,
+ * in metres — the **screening** form.
+ *
+ * Accurate to about 0.02% over a few hundred kilometres and roughly 12%
+ * across a hemisphere, for about a seventh of the cost. Use it to reject
+ * candidates that cannot be within a radius, then confirm the survivors
+ * with `haversineDistance`; do not report it as a measurement.
+ *
+ * @param {number} lon1
+ * @param {number} lat1
+ * @param {number} lon2
+ * @param {number} lat2
+ * @param {number} [radius]
+ * @returns {number} approximate distance
+ */
+export function equirectDistance(lon1, lat1, lon2, lat2, radius = EARTH_RADIUS) {
+  // the longitude difference is scaled by the cosine of the mean
+  // latitude, which is the whole correction the planar form is missing
+  const x = (lon2 - lon1) * DEG * Math.cos((lat1 + lat2) * 0.5 * DEG);
+  const y = (lat2 - lat1) * DEG;
+  return radius * Math.sqrt(x * x + y * y);
+}
+
+/**
+ * Initial bearing from one position to another: degrees clockwise from
+ * true north, in `[0, 360)`.
+ *
+ * This is the bearing at the *start* of the great circle, and it changes
+ * along the path — a course of constant bearing is a rhumb line, which
+ * is a different curve.
+ *
+ * @param {number} lon1
+ * @param {number} lat1
+ * @param {number} lon2
+ * @param {number} lat2
+ * @returns {number} degrees in [0, 360)
+ */
+export function initialBearing(lon1, lat1, lon2, lat2) {
+  const p1 = lat1 * DEG;
+  const p2 = lat2 * DEG;
+  const dl = (lon2 - lon1) * DEG;
+  const y = Math.sin(dl) * Math.cos(p2);
+  const x = Math.cos(p1) * Math.sin(p2) - Math.sin(p1) * Math.cos(p2) * Math.cos(dl);
+  const deg = Math.atan2(y, x) * RAD;
+  return (deg + 360) % 360;
+}
+
+/**
+ * The position reached by travelling `distance` metres from a position
+ * along a constant initial bearing (a great-circle course).
+ *
+ * @param {number} lon - starting longitude, degrees
+ * @param {number} lat - starting latitude, degrees
+ * @param {number} bearing - degrees clockwise from true north
+ * @param {number} distance - metres
+ * @param {number} [radius]
+ * @returns {[number, number]} the destination as a GeoJSON position
+ */
+export function destinationPoint(lon, lat, bearing, distance, radius = EARTH_RADIUS) {
+  const d = distance / radius;
+  const b = bearing * DEG;
+  const p1 = lat * DEG;
+  const l1 = lon * DEG;
+  const sinP1 = Math.sin(p1);
+  const cosP1 = Math.cos(p1);
+  const sinD = Math.sin(d);
+  const cosD = Math.cos(d);
+  const sinP2 = sinP1 * cosD + cosP1 * sinD * Math.cos(b);
+  const p2 = Math.asin(sinP2 < -1 ? -1 : sinP2 > 1 ? 1 : sinP2);
+  const l2 = l1 + Math.atan2(
+    Math.sin(b) * sinD * cosP1,
+    cosD - sinP1 * sinP2);
+  // normalize longitude back into [-180, 180]
+  return [((l2 * RAD + 540) % 360) - 180, p2 * RAD];
+}
+
+/**
+ * Total great-circle length of a line of positions, in metres. An empty
+ * or single-position line has length 0.
+ * @param {Array<number[]>} positions - GeoJSON positions
+ * @param {number} [radius]
+ * @returns {number}
+ */
+export function lineLength(positions, radius = EARTH_RADIUS) {
+  let total = 0;
+  for (let i = 1; i < positions.length; i++) {
+    const a = positions[i - 1];
+    const b = positions[i];
+    total += haversineDistance(a[0], a[1], b[0], b[1], radius);
+  }
+  return total;
+}
+
+//#endregion