math.basis-points

import { type RateUnit } from "./math_basis_points_types.ts";

const DECIMAL = /^-?[0-9]+(\.[0-9]+)?$/;

/** Powers of ten between each unit and basis points. */
function exponent(unit: RateUnit): number {
  switch (unit) {
    case "basis-points":
      return 0;
    case "percent":
      return 2;
    case "ratio":
      return 4;
    default:
      throw new RangeError(`unknown rate unit "${unit}"`);
  }
}

/**
 * Convert a rate between percent, basis points and a ratio.
 *
 * The units differ by powers of ten, so this moves the decimal point in the
 * text itself: exact for any input, with no float anywhere.
 */
export function convertRate(value: string, fromUnit: RateUnit, toUnit: RateUnit): string {
  if (typeof value !== "string" || !DECIMAL.test(value)) {
    throw new RangeError(`"${value}" is not a decimal number`);
  }
  const shift = exponent(fromUnit) - exponent(toUnit);

  const negative = value.startsWith("-");
  const body = negative ? value.slice(1) : value;
  const point = body.indexOf(".");
  let digits = point < 0 ? body : body.slice(0, point) + body.slice(point + 1);
  let position = (point < 0 ? body.length : point) + shift;

  if (position > digits.length) digits = digits + "0".repeat(position - digits.length);
  if (position < 0) {
    digits = "0".repeat(-position) + digits;
    position = 0;
  }

  const whole = digits.slice(0, position).replace(/^0+/, "") || "0";
  const fraction = digits.slice(position).replace(/0+$/, "");
  const text = fraction ? `${whole}.${fraction}` : whole;
  return negative && text !== "0" ? "-" + text : text;
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { convertRate } from "./math_basis_points_convert_rate.ts";  ← convertRate, another function of this group · built into the same file, even by a slim install
import { type RateUnit } from "./math_basis_points_types.ts";

/**
 * A rate as whole basis points, the unit the registry keeps rates in.
 * Refuses a rate that is not a whole number of basis points (12.345% is
 * 1234.5) rather than round it: which way to round a rate is the caller's
 * policy, not a conversion's.
 */
export function toBasisPoints(value: string, unit: RateUnit): number {
  const text = convertRate(value, unit, "basis-points");
  if (text.includes(".")) {
    throw new RangeError(`${value} ${unit} is not a whole number of basis points`);
  }
  const bp = Number(text);
  // Past 2^53 - 1, Number() has already rounded, so it is refused, not returned.
  if (!Number.isSafeInteger(bp)) {
    throw new RangeError(`${value} ${unit} is too large for integer basis points`);
  }
  return bp;
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { convertRate } from "./math_basis_points_convert_rate.ts";  ← convertRate, another function of this group · built into the same file, even by a slim install
import { type RateUnit } from "./math_basis_points_types.ts";

/** Integer basis points as the shortest exact decimal in another unit. */
export function fromBasisPoints(basisPoints: number, unit: RateUnit): string {
  if (!Number.isInteger(basisPoints)) {
    throw new TypeError(`basisPoints must be an integer, received ${basisPoints}`);
  }
  if (!Number.isSafeInteger(basisPoints)) {
    throw new RangeError("basisPoints is outside the safe integer range (±9007199254740991)");
  }
  return convertRate(String(basisPoints), "basis-points", unit);
}