charts.format

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

import { formatDecimal } from "./text_format_decimal.ts";  ← from text.format-decimal ^1.0.0 · built alongside by fune
import { roundFloat } from "./math_round_float.ts";  ← from math.round-float ^1.0.0 · built alongside by fune

/** The fewest decimal places (0 to 12) that write x exactly; 12 if none do. */
export function placesFor(x: number): number {
  const a = Math.abs(x);
  for (let d = 0; d < 12; d++) {
    if (roundFloat(a, d) === a) return d;
  }
  return 12;
}

/**
 * A tick label, with as many decimal places as the tick step needs, so every
 * label on an axis has the same number of places: with a step of 0.5 the
 * ticks read "0.0", "0.5", "1.0". String(0.1 + 0.2) would print
 * 0.30000000000000004; this prints "0.3". Thousands are grouped with commas.
 * A step of 0 (a single tick) uses the places the value itself needs.
 */
export function formatTick(value: number, step: number): string {
  if (typeof step !== "number" || !Number.isFinite(step)) {
    throw new RangeError(`step must be a finite number, received ${step}`);
  }
  const places = step === 0 ? placesFor(value) : placesFor(step);
  return formatDecimal(value, places, false, ",");
}

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

import { formatDecimal } from "./text_format_decimal.ts";  ← from text.format-decimal ^1.0.0 · built alongside by fune
import { roundFloat } from "./math_round_float.ts";  ← from math.round-float ^1.0.0 · built alongside by fune

// yocto to yotta, as d3-format writes them (micro is U+00B5).
const PREFIXES = ["y", "z", "a", "f", "p", "n", "µ", "m", "", "k", "M", "G", "T", "P", "E", "Z", "Y"];
const THOUSANDS = [1, 1e3, 1e6, 1e9, 1e12, 1e15, 1e18, 1e21, 1e24];
const TENS = [1, 10, 100];

/**
 * A number with an SI prefix and a given number of significant digits:
 * 1200 is "1.2k", 3400000 is "3.4M", 0.0015 is "1.5m". Trailing zeros are
 * dropped, so 1000 is "1k". The exponent is found by comparing against exact
 * powers of ten rather than log10, and a value that rounds up into the next
 * prefix (999.96 to 3 digits) moves to it: "1k", not "1000".
 */
export function formatSi(value: number, significant: number): string {
  if (!Number.isInteger(significant) || significant < 1 || significant > 15) {
    throw new RangeError(`significant must be a whole number from 1 to 15, received ${significant}`);
  }
  if (typeof value !== "number" || !Number.isFinite(value)) {
    throw new RangeError(`value must be a finite number, received ${value}`);
  }
  if (value === 0) return "0";
  const a = Math.abs(value);
  let exponent = 0;
  if (a >= 1) {
    let p = 1;
    while (p * 10 <= a) {
      p *= 10;
      exponent += 1;
    }
  } else {
    let q = 1;
    while (a * q < 1) {
      q *= 10;
      exponent -= 1;
    }
  }
  let group = Math.floor(exponent / 3);
  if (group < -8) group = -8;
  if (group > 8) group = 8;
  let rounded = scaleAndRound(value, group, significant - 1 - (exponent - 3 * group));
  if (Math.abs(rounded.value) >= 1000 && group < 8) {
    group += 1;
    rounded = scaleAndRound(value, group, significant - 1);
  }
  return formatDecimal(rounded.value, rounded.places, true, "") + PREFIXES[group + 8];
}

function scaleAndRound(value: number, group: number, places: number): { value: number; places: number } {
  const scaled = group >= 0 ? value / THOUSANDS[group] : value * THOUSANDS[-group];
  if (places < 0) {
    // Fewer significant digits than the whole part has: round to tens or hundreds.
    const unit = TENS[-places];
    return { value: roundFloat(scaled / unit, 0) * unit, places: 0 };
  }
  const p = places > 12 ? 12 : places;
  return { value: roundFloat(scaled, p), places: p };
}

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

import { formatDecimal } from "./text_format_decimal.ts";  ← from text.format-decimal ^1.0.0 · built alongside by fune
import { roundFloat } from "./math_round_float.ts";  ← from math.round-float ^1.0.0 · built alongside by fune

/**
 * A fraction as a percentage with fixed places: 0.123 to 1 place is "12.3%".
 * Multiplying by 100 adds binary noise (0.145 * 100 is 14.499999999999998),
 * so the product is first cleaned at 12 places and only then rounded to the
 * places asked for: 0.145 is "15%", as anyone reading it expects, not "14%".
 */
export function formatPercent(value: number, decimals: number): string {
  if (typeof value !== "number" || !Number.isFinite(value)) {
    throw new RangeError(`value must be a finite number, received ${value}`);
  }
  const percent = roundFloat(value * 100, 12);
  return formatDecimal(percent, decimals, false, "") + "%";
}

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

import { parseIsoDate } from "./dates_add_days.ts";  ← from dates.add-days ^1.0.0 · built alongside by fune
import { type DateLabel } from "./charts_format_types.ts";

const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];

/**
 * A date as a tick label for the interval it stands for: a day or week tick
 * "23 Sep", a month "Sep 2026", a quarter "Q3 2026", a year "2026". English
 * month abbreviations, no locale lookup, so every language agrees.
 */
export function formatDate(iso: string, label: DateLabel): string {
  const date = parseIsoDate(iso);
  const year = iso.slice(0, 4);
  const month = MONTHS[date.month - 1];
  if (label === "day" || label === "week") return `${date.day} ${month}`;
  if (label === "month") return `${month} ${year}`;
  if (label === "quarter") return `Q${Math.floor((date.month - 1) / 3) + 1} ${year}`;
  if (label === "year") return year;
  throw new RangeError(`unknown date label "${label}"; use day, week, month, quarter or year`);
}

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

import { formatMoney } from "./money_format.ts";  ← from money.format ^1.0.0 · built alongside by fune
import { money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { roundFloat } from "./math_round_float.ts";  ← from math.round-float ^1.0.0 · built alongside by fune

/**
 * A tick on an axis of money, where the chart's data are integer minor units
 * but a tick can land between them. The tick is rounded half away from zero
 * to a whole minor unit and printed by money.format, with the currency's own
 * digits and symbol.
 */
export function formatMoneyTick(minor: number, currency: string): string {
  if (typeof minor !== "number" || !Number.isFinite(minor)) {
    throw new RangeError(`minor must be a finite number, received ${minor}`);
  }
  return formatMoney(money(roundFloat(minor, 0), currency));
}