@fin.cx/opendata 4.3.1 → 4.4.0

package/ts/cpi/classes.bundesbankcpiclient.ts

@@ -0,0 +1,292 @@
+import { CpiError } from './classes.cpierror.js';
+import {
+  bundesbankCpiBaseUrl,
+  bundesbankVpiAnnualKey,
+  bundesbankVpiFirstMonth,
+  bundesbankVpiFirstYear,
+  bundesbankVpiMonthlyKey,
+  destatisLicence,
+} from './constants.js';
+import { parseDecimal } from './decimal.js';
+import { frequencyOf } from './indexmath.js';
+import type {
+  ICpiAnnualInput,
+  ICpiClientOptions,
+  ICpiMonthlyInput,
+  ICpiReading,
+  ICpiSeries,
+  ICpiSourceNote,
+  ICpiValue,
+  TCpiFrequency,
+  TCpiPeriod,
+} from './interfaces.js';
+import { getText, timeoutOf } from './request.js';
+
+/**
+ * The columns of the API's SDMX-CSV answer this client reads. The API leaves out a column that is empty
+ * in every row: `OBS_STATUS` appears only where a value carries a status.
+ */
+const COLUMNS = ['BBK_STD_FREQ', 'TIME_PERIOD', 'OBS_VALUE', 'BBK_DECIMALS', 'BBK_ID', 'BBK_UNIT', 'BBK_TITLE'] as const;
+const STATUS_COLUMN = 'OBS_STATUS';
+
+/** The key of the overall index for Germany on one base, as the answer names it. */
+const SERIES_KEY = /^BBDP1\.([MA])\.DE\.N\.VPI\.C\.A00000\.I(\d{2})\.A$/u;
+
+const UNIT = /^(\d{4})=100$/u;
+
+const FREQUENCY_CODES: Readonly<Record<TCpiFrequency, string>> = { monthly: 'M', annual: 'A' };
+
+/** What the API's `OBS_STATUS` says about a value; any other flag is not read. */
+const STATUSES: Readonly<Record<string, ICpiValue['status']>> = { '': 'final', E: 'estimated' };
+
+interface IRange {
+  frequency: TCpiFrequency;
+  from: TCpiPeriod;
+  to?: TCpiPeriod;
+}
+
+interface IReadSeries {
+  values: ICpiValue[];
+  estimates: ICpiValue[];
+  base: string;
+  baseYear: number;
+  key: string;
+  title: string;
+}
+
+/** One line of semicolon-separated values; a field in double quotes may hold separators and doubled quotes. */
+const splitLine = (lineArg: string): string[] | undefined => {
+  const fields: string[] = [];
+  let field = '';
+  let quoted = false;
+  for (let position = 0; position < lineArg.length; position++) {
+    const character = lineArg[position];
+    if (quoted) {
+      if (character === '"' && lineArg[position + 1] === '"') {
+        field += '"';
+        position++;
+      } else if (character === '"') {
+        quoted = false;
+      } else {
+        field += character;
+      }
+    } else if (character === '"' && field === '') {
+      quoted = true;
+    } else if (character === ';') {
+      fields.push(field);
+      field = '';
+    } else {
+      field += character;
+    }
+  }
+  if (quoted) {
+    return undefined;
+  }
+  fields.push(field);
+  return fields;
+};
+
+/**
+ * The Verbraucherpreisindex für Deutschland (overall index, unadjusted) of the Statistisches Bundesamt as
+ * the Deutsche Bundesbank republishes it in its time series API (`bundesbankCpiBaseUrl`), monthly and as
+ * annual averages. Each answer names its base, and the values the Bundesbank marks as its own estimate
+ * (the latest month at times) are kept apart from the published ones. Nothing is kept: each answer goes
+ * to the caller with the source note to show and the answer as it arrived.
+ */
+export class BundesbankCpiClient {
+  private readonly baseUrl: string;
+
+  constructor(private readonly options: ICpiClientOptions = {}) {
+    timeoutOf(options);
+    this.baseUrl = (options.baseUrl ?? bundesbankCpiBaseUrl).replace(/\/?$/u, '/');
+  }
+
+  /** The months from `from` to `to`, both included, or to the latest one when `to` is left out. */
+  public async getMonthly(inputArg: ICpiMonthlyInput): Promise<ICpiSeries> {
+    return this.getSeries({ frequency: 'monthly', from: inputArg.from, ...(inputArg.to !== undefined ? { to: inputArg.to } : {}) }, inputArg.signal);
+  }
+
+  /** The annual averages from `from` to `to`, both included, or to the latest one when `to` is left out. */
+  public async getAnnual(inputArg: ICpiAnnualInput): Promise<ICpiSeries> {
+    return this.getSeries({ frequency: 'annual', from: inputArg.from, ...(inputArg.to !== undefined ? { to: inputArg.to } : {}) }, inputArg.signal);
+  }
+
+  /**
+   * The published value of one month. A month with only the Bundesbank's estimate, or with nothing yet,
+   * ends in `not_published`, the estimate in the error where there is one.
+   */
+  public async getMonth(monthArg: string, optionsArg: { signal?: AbortSignal } = {}): Promise<ICpiReading> {
+    const series = await this.getSeries({ frequency: 'monthly', from: monthArg, to: monthArg }, optionsArg.signal);
+    const value = series.values[0];
+    if (!value) {
+      const estimate = series.estimates[0];
+      const message = estimate
+        ? `the index for ${monthArg} is not published yet; the Bundesbank gives only its own estimate (${estimate.value}).`
+        : `the index for ${monthArg} is not published yet.`;
+      throw new CpiError('not_published', message, {
+        service: 'bundesbank',
+        httpStatus: series.answer.httpStatus,
+        answer: series.answer,
+        period: monthArg,
+        ...(estimate ? { estimate } : {}),
+      });
+    }
+    return { ...value, source: series.source, answer: series.answer };
+  }
+
+  private async getSeries(rangeArg: IRange, signalArg: AbortSignal | undefined): Promise<ICpiSeries> {
+    checkRange(rangeArg);
+    const key = rangeArg.frequency === 'monthly' ? bundesbankVpiMonthlyKey : bundesbankVpiAnnualKey;
+    const uri = `${this.baseUrl}${key}?startPeriod=${rangeArg.from}${rangeArg.to !== undefined ? `&endPeriod=${rangeArg.to}` : ''}`;
+    const answer = await getText(this.options, uri, signalArg);
+    const refused = (codeArg: 'series_withdrawn' | 'busy' | 'unavailable' | 'unexpected_answer', messageArg: string): CpiError =>
+      new CpiError(codeArg, messageArg, { service: 'bundesbank', httpStatus: answer.httpStatus, answer });
+    if (answer.httpStatus === 404) {
+      throw refused('series_withdrawn', `the Bundesbank has no series ${key}: it answered 404.`);
+    }
+    if (answer.httpStatus === 429) {
+      throw refused('busy', 'the Bundesbank refused the request as one too many (429).');
+    }
+    if (answer.httpStatus >= 500 && answer.httpStatus <= 599) {
+      throw refused('unavailable', `the Bundesbank cannot answer now (${answer.httpStatus}).`);
+    }
+    if (answer.httpStatus !== 200) {
+      throw refused('unexpected_answer', `the Bundesbank answered ${answer.httpStatus}.`);
+    }
+    const read = readAnswer(answer.text, rangeArg, (messageArg) => refused('unexpected_answer', messageArg));
+    if (!read) {
+      throw new CpiError('not_published', `the Bundesbank has no value from ${rangeArg.from}${rangeArg.to !== undefined ? ` to ${rangeArg.to}` : ' on'} yet.`, {
+        service: 'bundesbank',
+        httpStatus: answer.httpStatus,
+        answer,
+        period: rangeArg.from,
+      });
+    }
+    return {
+      index: 'de-vpi',
+      frequency: rangeArg.frequency,
+      base: read.base,
+      baseYear: read.baseYear,
+      values: read.values,
+      estimates: read.estimates,
+      source: sourceNoteOf(read, uri),
+      answer,
+    };
+  }
+}
+
+/** A range of the series' periods, or the reason it is none. */
+const checkRange = (rangeArg: IRange): void => {
+  const written = rangeArg.frequency === 'monthly' ? 'YYYY-MM' : 'YYYY';
+  for (const period of [rangeArg.from, rangeArg.to]) {
+    if (period !== undefined && frequencyOf(period) !== rangeArg.frequency) {
+      throw new CpiError('invalid_input', `${JSON.stringify(period)} is no period written ${written}.`);
+    }
+  }
+  if (rangeArg.to !== undefined && rangeArg.to < rangeArg.from) {
+    throw new CpiError('invalid_input', `the range ends (${rangeArg.to}) before it begins (${rangeArg.from}).`);
+  }
+  const first = rangeArg.frequency === 'monthly' ? bundesbankVpiFirstMonth : bundesbankVpiFirstYear;
+  if (rangeArg.from < first) {
+    throw new CpiError('before_first_period', `${rangeArg.from} lies before ${first}, the first period of the series.`, { period: rangeArg.from });
+  }
+};
+
+/**
+ * The values of an SDMX-CSV answer, or `undefined` where it holds none. An answer is read only where every
+ * row is of the series and the frequency asked for, of one key and one base, inside the range asked for,
+ * once per period, with a value of the digits the answer states and a status this client knows.
+ */
+const readAnswer = (textArg: string, rangeArg: IRange, unreadableArg: (messageArg: string) => CpiError): IReadSeries | undefined => {
+  const lines = textArg.replace(/^/u, '').split(/\r?\n/u).filter((lineArg) => lineArg !== '');
+  const header = lines[0] === undefined ? undefined : splitLine(lines[0]);
+  if (!header || header[0] !== 'DATAFLOW') {
+    throw unreadableArg('the answer is no SDMX-CSV of the Bundesbank.');
+  }
+  const rows = lines.slice(1);
+  if (rows.length === 0) {
+    return undefined;
+  }
+  const missing = COLUMNS.filter((columnArg) => !header.includes(columnArg));
+  if (missing.length > 0) {
+    throw unreadableArg(`the answer has no column ${missing.join(', ')}.`);
+  }
+  const at = (fieldsArg: string[], columnArg: (typeof COLUMNS)[number] | typeof STATUS_COLUMN): string => {
+    const position = header.indexOf(columnArg);
+    return position < 0 ? '' : fieldsArg[position] ?? '';
+  };
+  const values: ICpiValue[] = [];
+  const estimates: ICpiValue[] = [];
+  const periods = new Set<string>();
+  let key: string | undefined;
+  let title = '';
+  let base = '';
+  let baseYear = 0;
+  for (const row of rows) {
+    const fields = splitLine(row);
+    if (!fields || fields.length !== header.length) {
+      throw unreadableArg(`a row is not of the answer's columns: ${row}`);
+    }
+    const rowKey = at(fields, 'BBK_ID');
+    const keyMatch = SERIES_KEY.exec(rowKey);
+    const unitMatch = UNIT.exec(at(fields, 'BBK_UNIT'));
+    const frequencyCode = FREQUENCY_CODES[rangeArg.frequency];
+    if (!keyMatch || keyMatch[1] !== frequencyCode || at(fields, 'BBK_STD_FREQ') !== frequencyCode) {
+      throw unreadableArg(`${JSON.stringify(rowKey)} is not the ${rangeArg.frequency} series of the overall index for Germany.`);
+    }
+    if (!unitMatch || unitMatch[1].slice(2) !== keyMatch[2]) {
+      throw unreadableArg(`${JSON.stringify(at(fields, 'BBK_UNIT'))} is no base of the series ${rowKey}.`);
+    }
+    if (key !== undefined && key !== rowKey) {
+      throw unreadableArg(`the answer holds more than one series or base: ${key} and ${rowKey}.`);
+    }
+    key = rowKey;
+    title = at(fields, 'BBK_TITLE');
+    base = unitMatch[0];
+    baseYear = Number(unitMatch[1]);
+    const period = at(fields, 'TIME_PERIOD');
+    if (frequencyOf(period) !== rangeArg.frequency || period < rangeArg.from || (rangeArg.to !== undefined && period > rangeArg.to)) {
+      throw unreadableArg(`${JSON.stringify(period)} is not a period asked for.`);
+    }
+    if (periods.has(period)) {
+      throw unreadableArg(`${period} is answered twice.`);
+    }
+    periods.add(period);
+    const flag = at(fields, STATUS_COLUMN);
+    if (!Object.hasOwn(STATUSES, flag)) {
+      throw unreadableArg(`${JSON.stringify(flag)} is no status this client knows, for ${period}.`);
+    }
+    const status = STATUSES[flag];
+    const written = at(fields, 'OBS_VALUE');
+    if (written === '' || written === 'NaN') {
+      // a period without a value has no observation
+      continue;
+    }
+    const decimals = Number(at(fields, 'BBK_DECIMALS'));
+    const decimal = parseDecimal(written);
+    if (!Number.isSafeInteger(decimals) || decimals < 0 || decimals > 6 || !decimal || decimal.units <= 0n || decimal.scale > decimals) {
+      throw unreadableArg(`${JSON.stringify(written)} is no index value of ${at(fields, 'BBK_DECIMALS')} decimals, for ${period}.`);
+    }
+    const value = decimal.scale === decimals ? written : `${written}${decimal.scale === 0 ? '.' : ''}${'0'.repeat(decimals - decimal.scale)}`;
+    (status === 'final' ? values : estimates).push({ index: 'de-vpi', period, value, base, status });
+  }
+  if (key === undefined || values.length + estimates.length === 0) {
+    return undefined;
+  }
+  const byPeriod = (leftArg: ICpiValue, rightArg: ICpiValue): number => leftArg.period.localeCompare(rightArg.period);
+  return { values: values.sort(byPeriod), estimates: estimates.sort(byPeriod), base, baseYear, key, title };
+};
+
+const sourceNoteOf = (readArg: IReadSeries, uriArg: string): ICpiSourceNote => ({
+  source: 'bundesbank',
+  provider: 'Deutsche Bundesbank',
+  dataOrigin: 'Statistisches Bundesamt (Destatis)',
+  title: readArg.title,
+  key: readArg.key,
+  uri: uriArg,
+  licence: destatisLicence.name,
+  licenceUri: destatisLicence.uri,
+  attribution:
+    `Quelle: Deutsche Bundesbank, Zeitreihe ${readArg.key}; Daten: Statistisches Bundesamt (Destatis), ` +
+    `Verbraucherpreisindex für Deutschland, ${readArg.base}; ${destatisLicence.name} (${destatisLicence.uri}); ${uriArg}`,
+});

package/ts/cpi/classes.cpierror.ts

@@ -0,0 +1,76 @@
+import type { ICpiServiceAnswer, ICpiValue, TCpiPeriod } from './interfaces.js';
+
+/**
+ * Why no index value or no result was given:
+ * - `invalid_input`: a period, a value, a percentage or an amount that is not one, or a range that ends
+ *   before it begins;
+ * - `before_first_period`: a period before the first one the series holds;
+ * - `not_published`: no published value for the period yet: nothing at all, or only an estimate
+ *   (`estimate`); a calculation given an estimate refuses it the same way;
+ * - `base_mismatch`: values of different bases, indices or frequencies, which are never compared;
+ * - `series_withdrawn`: the source no longer has the series asked for (HTTP 404), as happens to a
+ *   series key of an old base after the base year changed;
+ * - `busy`: the source refuses for too many requests (HTTP 429);
+ * - `unavailable`: the source cannot answer now (HTTP 5xx);
+ * - `unreachable`: no answer arrived: the name, the connection or TLS failed;
+ * - `timeout`: the answer did not arrive within the client's time;
+ * - `aborted`: the caller's signal ended the request;
+ * - `unexpected_answer`: an answer this client cannot read: another status, a missing column, a value or
+ *   a flag it does not know, a period it did not ask for, or more than one series or base.
+ */
+export type TCpiErrorCode =
+  | 'invalid_input'
+  | 'before_first_period'
+  | 'not_published'
+  | 'base_mismatch'
+  | 'series_withdrawn'
+  | 'busy'
+  | 'unavailable'
+  | 'unreachable'
+  | 'timeout'
+  | 'aborted'
+  | 'unexpected_answer';
+
+export interface ICpiErrorDetails {
+  /** the source asked, where a request was sent */
+  service?: 'bundesbank';
+  /** the HTTP status of the answer, where one arrived */
+  httpStatus?: number;
+  /** the answer as it arrived, where one did */
+  answer?: ICpiServiceAnswer;
+  /** the period the refusal is about */
+  period?: TCpiPeriod;
+  /** the estimate the source gave for that period, where it gave one (`not_published`) */
+  estimate?: ICpiValue;
+}
+
+/** The typed error of `@fin.cx/opendata/cpi`. */
+export class CpiError extends Error {
+  public readonly code: TCpiErrorCode;
+  public readonly service?: ICpiErrorDetails['service'];
+  public readonly httpStatus?: number;
+  public readonly answer?: ICpiServiceAnswer;
+  public readonly period?: TCpiPeriod;
+  public readonly estimate?: ICpiValue;
+
+  constructor(code: TCpiErrorCode, message: string, detailsArg: ICpiErrorDetails = {}, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'CpiError';
+    this.code = code;
+    if (detailsArg.service !== undefined) {
+      this.service = detailsArg.service;
+    }
+    if (detailsArg.httpStatus !== undefined) {
+      this.httpStatus = detailsArg.httpStatus;
+    }
+    if (detailsArg.answer !== undefined) {
+      this.answer = detailsArg.answer;
+    }
+    if (detailsArg.period !== undefined) {
+      this.period = detailsArg.period;
+    }
+    if (detailsArg.estimate !== undefined) {
+      this.estimate = detailsArg.estimate;
+    }
+  }
+}

package/ts/cpi/constants.ts

@@ -0,0 +1,28 @@
+/**
+ * The Deutsche Bundesbank's time series API (SDMX REST), dataflow `BBDP1`, where the Bundesbank
+ * republishes the Verbraucherpreisindex für Deutschland of the Statistisches Bundesamt ("Quelle:
+ * Statistisches Bundesamt, Wiesbaden."). Read on 2026-10-05; it answers without registration.
+ */
+export const bundesbankCpiBaseUrl = 'https://api.statistiken.bundesbank.de/rest/data/BBDP1/';
+
+/**
+ * The series keys of the overall index for Germany, monthly and annual average, unadjusted. The base
+ * dimension is left open (`..A`): the answer names the current base (`BBDP1.M.DE.N.VPI.C.A00000.I20.A`,
+ * 2020=100), and when the Statistisches Bundesamt changes the base year the Bundesbank withdraws the
+ * key of the old one (the `I15` key of 2015=100 answers 404).
+ */
+export const bundesbankVpiMonthlyKey = 'M.DE.N.VPI.C.A00000..A';
+export const bundesbankVpiAnnualKey = 'A.DE.N.VPI.C.A00000..A';
+
+/** The first month and year of the series (January 1991, the first one the API answers). */
+export const bundesbankVpiFirstMonth = '1991-01';
+export const bundesbankVpiFirstYear = '1991';
+
+/** The licence under which the Statistisches Bundesamt publishes its figures. */
+export const destatisLicence = {
+  name: 'Datenlizenz Deutschland – Namensnennung – Version 2.0',
+  uri: 'https://www.govdata.de/dl-de/by-2-0',
+} as const;
+
+/** How long one request may take by default, the answer included. */
+export const defaultCpiTimeoutMs = 30_000;

package/ts/cpi/decimal.ts

@@ -0,0 +1,45 @@
+/** A non-negative decimal as integer units of 10^-scale: `'113.5'` is 1135 at scale 1. */
+export interface IScaledDecimal {
+  units: bigint;
+  scale: number;
+}
+
+/** A decimal written with digits and at most one point between them; no sign, no exponent, no comma, no leading zero. */
+const DECIMAL = /^(0|[1-9]\d*)(?:\.(\d+))?$/u;
+
+const TEN = 10n;
+
+export const powerOfTen = (exponentArg: number): bigint => TEN ** BigInt(exponentArg);
+
+export const parseDecimal = (textArg: unknown): IScaledDecimal | undefined => {
+  const match = typeof textArg === 'string' ? DECIMAL.exec(textArg) : null;
+  if (!match) {
+    return undefined;
+  }
+  const fraction = match[2] ?? '';
+  return { units: BigInt(`${match[1]}${fraction}`), scale: fraction.length };
+};
+
+/** The units of a decimal at a scale at least its own. */
+export const atScale = (decimalArg: IScaledDecimal, scaleArg: number): bigint =>
+  decimalArg.units * powerOfTen(scaleArg - decimalArg.scale);
+
+/** numerator / denominator, rounded half away from zero ("kaufmännisch"); the denominator is positive. */
+export const divideRounded = (numeratorArg: bigint, denominatorArg: bigint): bigint => {
+  const negative = numeratorArg < 0n;
+  const magnitude = negative ? -numeratorArg : numeratorArg;
+  let quotient = magnitude / denominatorArg;
+  if ((magnitude % denominatorArg) * 2n >= denominatorArg) {
+    quotient += 1n;
+  }
+  return negative ? -quotient : quotient;
+};
+
+/** Units of 10^-scale written as a decimal with exactly `scaleArg` digits after the point: `-22` at 1 is `'-2.2'`. */
+export const formatUnits = (unitsArg: bigint, scaleArg: number): string => {
+  const negative = unitsArg < 0n;
+  const digits = (negative ? -unitsArg : unitsArg).toString().padStart(scaleArg + 1, '0');
+  const whole = digits.slice(0, digits.length - scaleArg);
+  const fraction = digits.slice(digits.length - scaleArg);
+  return `${negative ? '-' : ''}${whole}${scaleArg > 0 ? `.${fraction}` : ''}`;
+};

package/ts/cpi/index.ts

@@ -0,0 +1,16 @@
+// This entry point stands alone: it imports nothing from the rest of the package and has no
+// dependencies. It keeps nothing: every answer goes to the caller, with the source's answer as it
+// arrived, which the caller keeps as the evidence of an index adjustment.
+export * from './interfaces.js';
+export { CpiError, type ICpiErrorDetails, type TCpiErrorCode } from './classes.cpierror.js';
+export {
+  bundesbankCpiBaseUrl,
+  bundesbankVpiAnnualKey,
+  bundesbankVpiFirstMonth,
+  bundesbankVpiFirstYear,
+  bundesbankVpiMonthlyKey,
+  defaultCpiTimeoutMs,
+  destatisLicence,
+} from './constants.js';
+export { cpiChangePercent, cpiChangePoints, cpiFirstReaching, cpiScaleAmount, cpiThresholds } from './indexmath.js';
+export { BundesbankCpiClient } from './classes.bundesbankcpiclient.js';

package/ts/cpi/indexmath.ts

@@ -0,0 +1,182 @@
+import { CpiError } from './classes.cpierror.js';
+import { atScale, divideRounded, formatUnits, parseDecimal, powerOfTen, type IScaledDecimal } from './decimal.js';
+import type { ICpiReachOptions, ICpiScaleOptions, ICpiThresholds, ICpiValue, TCpiFrequency } from './interfaces.js';
+
+// The arithmetic of index clauses as the Statistisches Bundesamt describes it ("Anleitung für die
+// Berechnung von Schwellenwerten und Veränderungsraten für Wertsicherungsklauseln", Stand Januar 2024;
+// "Allgemeine Informationen zum Verbraucherpreisindex"). Every calculation is exact: values are integers
+// of their published digits, and every rounding is half away from zero ("kaufmännisch").
+
+const MONTH = /^\d{4}-(0[1-9]|1[0-2])$/u;
+const YEAR = /^\d{4}$/u;
+
+/** The frequency a period is written in, or `undefined` for something that is no period. */
+export const frequencyOf = (periodArg: unknown): TCpiFrequency | undefined => {
+  if (typeof periodArg !== 'string') {
+    return undefined;
+  }
+  return MONTH.test(periodArg) ? 'monthly' : YEAR.test(periodArg) ? 'annual' : undefined;
+};
+
+/** A published value, read as an exact decimal; an estimate or something that is no index value is refused. */
+const publishedValueOf = (valueArg: ICpiValue): IScaledDecimal => {
+  if (!frequencyOf(valueArg.period)) {
+    throw new CpiError('invalid_input', `${JSON.stringify(valueArg.period)} is no period written YYYY-MM or YYYY.`);
+  }
+  const decimal = parseDecimal(valueArg.value);
+  if (!decimal || decimal.units <= 0n) {
+    throw new CpiError('invalid_input', `${JSON.stringify(valueArg.value)} is no index value: a positive decimal written with a point.`, { period: valueArg.period });
+  }
+  if (valueArg.status !== 'final') {
+    throw new CpiError('not_published', `the value for ${valueArg.period} is an estimate, not a published index value.`, { period: valueArg.period, estimate: valueArg });
+  }
+  return decimal;
+};
+
+/** Values of one index, one base and one frequency; anything else is never compared. */
+const requireComparable = (leftArg: ICpiValue, rightArg: ICpiValue): void => {
+  if (leftArg.index !== rightArg.index || leftArg.base !== rightArg.base || frequencyOf(leftArg.period) !== frequencyOf(rightArg.period)) {
+    throw new CpiError(
+      'base_mismatch',
+      `${leftArg.index} ${leftArg.period} (${leftArg.base}) and ${rightArg.index} ${rightArg.period} (${rightArg.base}) are not values of one series and one base; read both on the current base.`,
+    );
+  }
+};
+
+/** The change in percent, in tenths of a percent: ((new / old) × 100) − 100, rounded to one decimal. */
+const changeTenthsOf = (oldArg: ICpiValue, newArg: ICpiValue): bigint => {
+  const oldDecimal = publishedValueOf(oldArg);
+  const newDecimal = publishedValueOf(newArg);
+  requireComparable(oldArg, newArg);
+  const scale = Math.max(oldDecimal.scale, newDecimal.scale);
+  const oldUnits = atScale(oldDecimal, scale);
+  return divideRounded((atScale(newDecimal, scale) - oldUnits) * 1000n, oldUnits);
+};
+
+/**
+ * The change from one value to another in percent, as the Statistisches Bundesamt computes it:
+ * ((new / old) × 100) − 100, rounded half away from zero to one decimal (`'13.0'`, `'-2.2'`).
+ * It does not depend on the base, but both values must be read on the same one.
+ */
+export const cpiChangePercent = (oldArg: ICpiValue, newArg: ICpiValue): string => formatUnits(changeTenthsOf(oldArg, newArg), 1);
+
+/**
+ * The change from one value to another in index points (new − old), with the digits of the more
+ * precise value (`'12.2'`, `'-1.0'`). Points depend on the base, so they are only given within one.
+ */
+export const cpiChangePoints = (oldArg: ICpiValue, newArg: ICpiValue): string => {
+  const oldDecimal = publishedValueOf(oldArg);
+  const newDecimal = publishedValueOf(newArg);
+  requireComparable(oldArg, newArg);
+  const scale = Math.max(oldDecimal.scale, newDecimal.scale);
+  return formatUnits(atScale(newDecimal, scale) - atScale(oldDecimal, scale), scale);
+};
+
+/** The units of the thresholds at the reference value's digits. */
+const thresholdUnitsOf = (referenceArg: ICpiValue, percentArg: string): { upper: bigint; lower: bigint; scale: number } => {
+  const reference = publishedValueOf(referenceArg);
+  const percent = parseDecimal(percentArg);
+  const hundred = percent ? 100n * powerOfTen(percent.scale) : 0n;
+  if (!percent || percent.units >= hundred) {
+    throw new CpiError('invalid_input', `${JSON.stringify(percentArg)} is no percentage from 0 to below 100, written with digits and a point.`);
+  }
+  return {
+    upper: divideRounded(reference.units * (hundred + percent.units), hundred),
+    lower: divideRounded(reference.units * (hundred - percent.units), hundred),
+    scale: reference.scale,
+  };
+};
+
+/**
+ * The thresholds of a percent rule: reference × (1 + percent / 100) and reference × (1 − percent / 100),
+ * rounded half away from zero to the reference value's digits (99.7 and 5 % give 104.7 and 94.7).
+ */
+export const cpiThresholds = (referenceArg: ICpiValue, percentArg: string): ICpiThresholds => {
+  const { upper, lower, scale } = thresholdUnitsOf(referenceArg, percentArg);
+  return {
+    index: referenceArg.index,
+    base: referenceArg.base,
+    percent: percentArg,
+    upper: formatUnits(upper, scale),
+    lower: formatUnits(lower, scale),
+  };
+};
+
+/**
+ * The first value after the reference period that reaches a threshold of a percent rule
+ * (`cpiThresholds`), or `undefined` while none does. Whether the threshold itself counts (`reached`) or
+ * only a value beyond it (`exceeded`), and which direction, is the clause's to say. All values must be
+ * published values of the reference value's series and base; their order does not matter, a period
+ * given twice is refused.
+ */
+export const cpiFirstReaching = (
+  valuesArg: readonly ICpiValue[],
+  referenceArg: ICpiValue,
+  percentArg: string,
+  optionsArg: ICpiReachOptions,
+): ICpiValue | undefined => {
+  if (!['up', 'down', 'either'].includes(optionsArg.direction) || !['reached', 'exceeded'].includes(optionsArg.reach)) {
+    throw new CpiError('invalid_input', 'the direction is up, down or either, and the reach is reached or exceeded.');
+  }
+  const thresholds = thresholdUnitsOf(referenceArg, percentArg);
+  const periods = new Set<string>();
+  const candidates: { value: ICpiValue; decimal: IScaledDecimal }[] = [];
+  for (const value of valuesArg) {
+    const decimal = publishedValueOf(value);
+    requireComparable(referenceArg, value);
+    if (periods.has(value.period)) {
+      throw new CpiError('invalid_input', `${value.period} is given twice.`, { period: value.period });
+    }
+    periods.add(value.period);
+    if (value.period > referenceArg.period) {
+      candidates.push({ value, decimal });
+    }
+  }
+  candidates.sort((leftArg, rightArg) => leftArg.value.period.localeCompare(rightArg.value.period));
+  const exceeding = optionsArg.reach === 'exceeded';
+  for (const { value, decimal } of candidates) {
+    const scale = Math.max(decimal.scale, thresholds.scale);
+    const units = atScale(decimal, scale);
+    const upper = atScale({ units: thresholds.upper, scale: thresholds.scale }, scale);
+    const lower = atScale({ units: thresholds.lower, scale: thresholds.scale }, scale);
+    const up = exceeding ? units > upper : units >= upper;
+    const down = exceeding ? units < lower : units <= lower;
+    if ((optionsArg.direction !== 'down' && up) || (optionsArg.direction !== 'up' && down)) {
+      return value;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * An amount in cents scaled from one index value to another, rounded half away from zero to whole cents:
+ * by the index ratio (amount × new / old, the default, as the Statistisches Bundesamt writes it) or by
+ * the change in percent rounded to one decimal (`basis: 'rounded_percent'`). Which one applies is the
+ * contract's to say. The amount and the result are safe integers; a negative amount (a credit) scales
+ * the same way.
+ */
+export const cpiScaleAmount = (amountCentsArg: number, oldArg: ICpiValue, newArg: ICpiValue, optionsArg: ICpiScaleOptions = {}): number => {
+  const basis = optionsArg.basis ?? 'index_ratio';
+  if (!Number.isSafeInteger(amountCentsArg)) {
+    throw new CpiError('invalid_input', `${amountCentsArg} is no amount in whole cents.`);
+  }
+  if (basis !== 'index_ratio' && basis !== 'rounded_percent') {
+    throw new CpiError('invalid_input', `${JSON.stringify(basis)} is no basis; it is index_ratio or rounded_percent.`);
+  }
+  const amount = BigInt(amountCentsArg);
+  let scaled: bigint;
+  if (basis === 'rounded_percent') {
+    scaled = divideRounded(amount * (1000n + changeTenthsOf(oldArg, newArg)), 1000n);
+  } else {
+    const oldDecimal = publishedValueOf(oldArg);
+    const newDecimal = publishedValueOf(newArg);
+    requireComparable(oldArg, newArg);
+    const scale = Math.max(oldDecimal.scale, newDecimal.scale);
+    scaled = divideRounded(amount * atScale(newDecimal, scale), atScale(oldDecimal, scale));
+  }
+  const result = Number(scaled);
+  if (!Number.isSafeInteger(result)) {
+    throw new CpiError('invalid_input', `the scaled amount of ${amountCentsArg} cents is beyond the safe integers.`);
+  }
+  return result;
+};