charts.scale

/**
 * Where `value` lands on the range, as a straight-line map from the domain.
 * Outside the domain the line carries on, unless `clamp` stops it at the
 * range's ends.
 */
export function linearScale(domain: readonly number[], range: readonly number[], value: number, clamp: boolean): number {
  const [d0, d1] = pair(domain, "domain");
  const [r0, r1] = pair(range, "range");
  let t = normalise(d0, d1, value, "domain");
  if (clamp) t = Math.max(0, Math.min(1, t));
  return round6(interpolate(r0, r1, t));
}

// The helpers below are exported for invertLinear, which is the same line
// read the other way; they are not part of the group's contract.

/** The two ends of a domain or range, or an error naming which one is wrong. */
export function pair(values: readonly number[], what: string): [number, number] {
  if (values.length !== 2) throw new Error(`${what} must have exactly 2 values, [from, to]; got ${values.length}`);
  return [values[0], values[1]];
}

/** How far along [from, to] the value is: 0 at from, 1 at to. */
export function normalise(from: number, to: number, value: number, what: string): number {
  // Equal ends would divide by zero and answer NaN or Infinity, which then
  // draws nothing without saying why.
  if (from === to) throw new Error(`${what} has no width: both ends are ${from}`);
  return (value - from) / (to - from);
}

export function interpolate(from: number, to: number, t: number): number {
  return from + t * (to - from);
}

/** Half up to 6 decimal places, the same way in every language. */
export function round6(x: number): number {
  return Math.floor(x * 1e6 + 0.5) / 1e6;
}

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

import { interpolate, normalise, pair, round6 } from "./charts_scale_linear_scale.ts";  ← linearScale, another function of this group · built into the same file, even by a slim install

/**
 * The domain value at a position in the range: linearScale read backwards,
 * for turning a pointer coordinate into the value under it. Never clamped; a
 * position past the end of the axis is a value past the end of the data.
 */
export function invertLinear(domain: readonly number[], range: readonly number[], value: number): number {
  const [d0, d1] = pair(domain, "domain");
  const [r0, r1] = pair(range, "range");
  return round6(interpolate(d0, d1, normalise(r0, r1, value, "range")));
}

import type { NiceDomain } from "./charts_scale_types.ts";

/**
 * Widen a domain to multiples of a round tick step (1, 2 or 5 times a power
 * of ten) chosen for about `count` ticks. Widening can change the best step,
 * so it repeats until the step settles, as d3's nice() does.
 */
export function niceDomain(domain: readonly number[], count: number): NiceDomain {
  if (domain.length !== 2) throw new Error(`domain must have exactly 2 values, [from, to]; got ${domain.length}`);
  if (!Number.isInteger(count) || count < 1) throw new Error(`count must be a whole number of at least 1, got ${count}`);
  const reversed = domain[1] < domain[0];
  let lo = reversed ? domain[1] : domain[0];
  let hi = reversed ? domain[0] : domain[1];
  if (lo === hi) return { domain: [domain[0], domain[1]], step: 0 };

  let step = 0;
  for (let i = 0; i < 10; i++) {
    const next = tickStep(lo, hi, count);
    if (next === step) break;
    step = next;
    if (step >= 1) {
      lo = Math.floor(lo / step) * step;
      hi = Math.ceil(hi / step) * step;
    } else {
      // A fractional step divides badly (0.3 / 0.1 is 2.9999999999999996), so
      // multiply by its whole-number inverse instead.
      const inverse = Math.floor(1 / step + 0.5);
      lo = Math.floor(lo * inverse) / inverse;
      hi = Math.ceil(hi * inverse) / inverse;
    }
  }
  const ends = reversed ? [round6(hi), round6(lo)] : [round6(lo), round6(hi)];
  return { domain: ends, step: round6(step) };
}

function tickStep(lo: number, hi: number, count: number): number {
  const raw = (hi - lo) / count;
  // Powers of ten by repeated multiplication rather than log10, whose last
  // digit is not guaranteed to agree between languages.
  let power = 1;
  while (power * 10 <= raw) power *= 10;
  while (power > raw) power /= 10;
  const error = raw / power;
  const factor = error >= Math.sqrt(50) ? 10 : error >= Math.sqrt(10) ? 5 : error >= Math.sqrt(2) ? 2 : 1;
  return factor * power;
}

function round6(x: number): number {
  return Math.floor(x * 1e6 + 0.5) / 1e6;
}

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

import { roundFloat } from "./math_round_float.ts";  ← from math.round-float ^1.0.0 · built alongside by fune
import { ln } from "./math_ln.ts";  ← from math.ln ^1.0.0 · built alongside by fune
import { interpolate, pair } from "./charts_scale_linear_scale.ts";  ← linearScale, another function of this group · built into the same file, even by a slim install

/**
 * Where `value` lands on the range when the axis is logarithmic: equal ratios
 * (1 to 10, 10 to 100) take equal lengths. The base of the logarithm cancels
 * out, so there is no base argument; it only matters for ticks.
 *
 * ln comes from math.ln rather than Math.log, whose last bit may differ
 * between platforms, so every language lands on the same double.
 */
export function logScale(domain: readonly number[], range: readonly number[], value: number, clamp: boolean): number {
  const [d0, d1] = pair(domain, "domain");
  const [r0, r1] = pair(range, "range");
  if (!(d0 > 0) || !(d1 > 0)) throw new Error(`log scale domain must be positive; got [${d0}, ${d1}]`);
  if (d0 === d1) throw new Error(`domain has no width: both ends are ${d0}`);
  if (!(value > 0)) throw new Error(`value must be positive for a log scale; got ${value}`);
  const l0 = ln(d0);
  let t = (ln(value) - l0) / (ln(d1) - l0);
  if (clamp) t = Math.max(0, Math.min(1, t));
  return roundFloat(interpolate(r0, r1, t), 6);
}

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

import { roundFloat } from "./math_round_float.ts";  ← from math.round-float ^1.0.0 · built alongside by fune
import { daysBetween } from "./dates_days_between.ts";  ← from dates.days-between ^1.0.0 · built alongside by fune
import { interpolate, pair } from "./charts_scale_linear_scale.ts";  ← linearScale, another function of this group · built into the same file, even by a slim install

/**
 * Where an ISO date lands on the range, linearly by calendar days: 2026-01-16
 * is halfway along a January axis. Dates are counted as whole days with
 * dates.days-between, never through a Date object, so no time zone can move
 * a point by a day.
 */
export function timeScale(domain: readonly string[], range: readonly number[], value: string, clamp: boolean): number {
  if (domain.length !== 2) throw new Error(`domain must have exactly 2 values, [from, to]; got ${domain.length}`);
  const [r0, r1] = pair(range, "range");
  const span = daysBetween(domain[0], domain[1]);
  if (span === 0) throw new Error(`domain has no width: both ends are ${domain[0]}`);
  let t = daysBetween(domain[0], value) / span;
  if (clamp) t = Math.max(0, Math.min(1, t));
  return roundFloat(interpolate(r0, r1, t), 6);
}

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

import { type Band } from "./charts_scale_types.ts";
import { roundFloat } from "./math_round_float.ts";  ← from math.round-float ^1.0.0 · built alongside by fune
import { pair } from "./charts_scale_linear_scale.ts";  ← linearScale, another function of this group · built into the same file, even by a slim install

/**
 * The band a category occupies, as d3.scaleBand lays it out (without
 * rounding to whole pixels): the range is divided into equal steps, each
 * band is a step less the inner padding, and the outer padding is shared out
 * by `align`. A reversed range reverses the order of the bands, not their
 * direction, so `start` is always the lower coordinate.
 */
export function bandScale(
  domain: readonly string[],
  range: readonly number[],
  value: string,
  paddingInner: number,
  paddingOuter: number,
  align: number,
): Band {
  if (!(paddingInner >= 0 && paddingInner <= 1)) throw new Error(`paddingInner must be between 0 and 1; got ${paddingInner}`);
  checkOuter(paddingOuter, "paddingOuter");
  checkAlign(align);
  const [start, width] = bandPosition(domain, range, value, paddingInner, paddingOuter, align);
  return { start: roundFloat(start, 6), center: roundFloat(start + width / 2, 6), width: roundFloat(width, 6) };
}

// Exported for pointScale, which is a band scale whose bands have no width.

export function checkOuter(padding: number, what: string): void {
  if (!(padding >= 0)) throw new Error(`${what} must be 0 or more; got ${padding}`);
}

export function checkAlign(align: number): void {
  if (!(align >= 0 && align <= 1)) throw new Error(`align must be between 0 and 1; got ${align}`);
}

/** The unrounded lower coordinate of value's band, and the band width. */
export function bandPosition(
  domain: readonly string[],
  range: readonly number[],
  value: string,
  paddingInner: number,
  paddingOuter: number,
  align: number,
): [number, number] {
  const [r0, r1] = pair(range, "range");
  const n = domain.length;
  if (n === 0) throw new Error("domain must not be empty");
  let index = -1;
  for (let i = 0; i < n; i++) {
    for (let j = 0; j < i; j++) {
      if (domain[j] === domain[i]) throw new Error(`domain has a repeated value: "${domain[i]}"`);
    }
    if (domain[i] === value) index = i;
  }
  if (index < 0) throw new Error(`value is not in the domain: "${value}"`);
  const reverse = r1 < r0;
  let start = reverse ? r1 : r0;
  const stop = reverse ? r0 : r1;
  const step = (stop - start) / Math.max(1, n - paddingInner + paddingOuter * 2);
  start += (stop - start - step * (n - paddingInner)) * align;
  const slot = reverse ? n - 1 - index : index;
  return [start + step * slot, step * (1 - paddingInner)];
}

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

import { roundFloat } from "./math_round_float.ts";  ← from math.round-float ^1.0.0 · built alongside by fune
import { bandPosition, checkAlign, checkOuter } from "./charts_scale_band_scale.ts";  ← bandScale, another function of this group · built into the same file, even by a slim install

/**
 * The position of a category on an axis of evenly spaced points, as
 * d3.scalePoint: a band scale whose bands have no width (inner padding 1), so
 * the first and last points sit `padding` steps in from the ends.
 */
export function pointScale(domain: readonly string[], range: readonly number[], value: string, padding: number, align: number): number {
  checkOuter(padding, "padding");
  checkAlign(align);
  return roundFloat(bandPosition(domain, range, value, 1, padding, align)[0], 6);
}