@fin.cx/opendata 4.3.1 → 4.5.0

package/ts/cpi/indexmath.ts

@@ -0,0 +1,230 @@
+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 reach options as the clause gives them; anything else is refused. */
+const requireReachOptions = (optionsArg: ICpiReachOptions): void => {
+  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.');
+  }
+};
+
+/**
+ * The first value after the reference period at or beyond the upper threshold or at or below the lower
+ * one, as the options say. The thresholds are units of 10^-scale; the lower one may be zero or less, which
+ * no index value reaches. 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.
+ */
+const firstReachingUnits = (
+  valuesArg: readonly ICpiValue[],
+  referenceArg: ICpiValue,
+  thresholdsArg: { upper: bigint; lower: bigint; scale: number },
+  optionsArg: ICpiReachOptions,
+): ICpiValue | undefined => {
+  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, thresholdsArg.scale);
+    const units = atScale(decimal, scale);
+    const upper = thresholdsArg.upper * powerOfTen(scale - thresholdsArg.scale);
+    const lower = thresholdsArg.lower * powerOfTen(scale - thresholdsArg.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;
+};
+
+/**
+ * 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 => {
+  requireReachOptions(optionsArg);
+  return firstReachingUnits(valuesArg, referenceArg, thresholdUnitsOf(referenceArg, percentArg), optionsArg);
+};
+
+/**
+ * The first value after the reference period whose change from the reference in index points
+ * (`cpiChangePoints`) reaches a points rule's threshold, or `undefined` while none does: a value at or
+ * above reference + points (`up`), at or below reference − points (`down`), or whichever comes first
+ * (`either`). The points are a decimal written with digits and a point, from 0 upward, with any number
+ * of digits (`'5'`, `'2.5'`); nothing is rounded, so a threshold with more digits than the values is
+ * compared exactly. Whether the threshold itself counts (`reached`) or only a value beyond it
+ * (`exceeded`) is the clause's to say. Points depend on the base, so all values must be published
+ * values of the reference value's series and base (`base_mismatch` otherwise); their order does not
+ * matter, a period given twice is refused.
+ */
+export const cpiFirstReachingPoints = (
+  valuesArg: readonly ICpiValue[],
+  referenceArg: ICpiValue,
+  pointsArg: string,
+  optionsArg: ICpiReachOptions,
+): ICpiValue | undefined => {
+  requireReachOptions(optionsArg);
+  const reference = publishedValueOf(referenceArg);
+  const points = parseDecimal(pointsArg);
+  if (!points) {
+    throw new CpiError('invalid_input', `${JSON.stringify(pointsArg)} is no number of index points from 0 upward, written with digits and a point.`);
+  }
+  const scale = Math.max(reference.scale, points.scale);
+  const referenceUnits = atScale(reference, scale);
+  const pointsUnits = atScale(points, scale);
+  return firstReachingUnits(valuesArg, referenceArg, { upper: referenceUnits + pointsUnits, lower: referenceUnits - pointsUnits, scale }, optionsArg);
+};
+
+/**
+ * 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;
+};

package/ts/cpi/interfaces.ts

@@ -0,0 +1,137 @@
+/** A calendar month, `YYYY-MM`. */
+export type TIsoMonth = string;
+
+/** A calendar year, `YYYY`. */
+export type TIsoYear = string;
+
+/** The period of an index value: a month (`YYYY-MM`) or a year (`YYYY`, the annual average). */
+export type TCpiPeriod = TIsoMonth | TIsoYear;
+
+/** Which price index a value belongs to: `de-vpi`, the Verbraucherpreisindex für Deutschland of the Statistisches Bundesamt. */
+export type TCpiIndex = 'de-vpi';
+
+export type TCpiFrequency = 'monthly' | 'annual';
+
+/**
+ * - `final`: the value as published, final until the next change of the base year;
+ * - `estimated`: a value the source marks as an estimate (the Bundesbank's `OBS_STATUS` `E`, for the
+ *   latest month at times). It is no published index value and is never used in a calculation.
+ */
+export type TCpiValueStatus = 'final' | 'estimated';
+
+/** One index value as its source states it. */
+export interface ICpiValue {
+  index: TCpiIndex;
+  period: TCpiPeriod;
+  /**
+   * The value as a decimal with a point and exactly the digits published, trailing zeros included
+   * (`'100.0'`, `'113.5'`). Never a float.
+   */
+  value: string;
+  /** the base the value is stated on, as the source writes it: `'2020=100'` */
+  base: string;
+  status: TCpiValueStatus;
+}
+
+/** A source's answer as it arrived: its HTTP status and its body as text. */
+export interface ICpiServiceAnswer {
+  httpStatus: number;
+  text: string;
+}
+
+/**
+ * Where a series comes from and how it must be credited. The figures are those of the Statistisches
+ * Bundesamt (Destatis) under the Datenlizenz Deutschland – Namensnennung – Version 2.0.
+ */
+export interface ICpiSourceNote {
+  source: 'bundesbank';
+  /** who delivered the figures: `'Deutsche Bundesbank'` */
+  provider: string;
+  /** whose figures they are: `'Statistisches Bundesamt (Destatis)'` */
+  dataOrigin: string;
+  /** the series' title as the answer gives it */
+  title: string;
+  /** the series key as the answer gives it, its base included: `'BBDP1.M.DE.N.VPI.C.A00000.I20.A'` */
+  key: string;
+  /** the request the figures were read from */
+  uri: string;
+  licence: string;
+  licenceUri: string;
+  /** the source note to show wherever the figures are shown */
+  attribution: string;
+}
+
+/** A range of index values of one series and one base, as one answer gave them. */
+export interface ICpiSeries {
+  index: TCpiIndex;
+  frequency: TCpiFrequency;
+  /** `'2020=100'` */
+  base: string;
+  /** `2020` */
+  baseYear: number;
+  /** the published values, oldest first */
+  values: ICpiValue[];
+  /** the values the source marks as estimates, oldest first; kept apart so that no calculation takes one */
+  estimates: ICpiValue[];
+  source: ICpiSourceNote;
+  answer: ICpiServiceAnswer;
+}
+
+/** One published value with where it comes from and the answer it was read from. */
+export interface ICpiReading extends ICpiValue {
+  source: ICpiSourceNote;
+  answer: ICpiServiceAnswer;
+}
+
+/** The thresholds of a percent rule: the reference value times (1 ± percent / 100), rounded to its digits. */
+export interface ICpiThresholds {
+  index: TCpiIndex;
+  base: string;
+  /** the percentage asked for, as given */
+  percent: string;
+  upper: string;
+  lower: string;
+}
+
+export interface ICpiReachOptions {
+  /** `up`: the upper threshold, `down`: the lower one, `either`: whichever comes first */
+  direction: 'up' | 'down' | 'either';
+  /** `reached`: the threshold itself counts; `exceeded`: only a value beyond it counts */
+  reach: 'reached' | 'exceeded';
+}
+
+export interface ICpiScaleOptions {
+  /**
+   * - `index_ratio` (default): amount × new index / old index, as the Statistisches Bundesamt writes it;
+   * - `rounded_percent`: amount × (100 + the change in percent rounded to one decimal) / 100.
+   */
+  basis?: 'index_ratio' | 'rounded_percent';
+}
+
+/** A `fetch` as the WHATWG standard defines it; injectable for tests and for a fetch that reaches only public addresses. */
+export type TCpiFetch = (input: string, init: RequestInit) => Promise<Response>;
+
+export interface ICpiClientOptions {
+  /** default: the runtime's `fetch` */
+  fetch?: TCpiFetch;
+  /** default: the official address (`bundesbankCpiBaseUrl`); a test's own server otherwise */
+  baseUrl?: string;
+  /** how long one request may take, the answer included; default `defaultCpiTimeoutMs` */
+  timeoutMs?: number;
+  /** sent as `User-Agent` where given */
+  userAgent?: string;
+}
+
+export interface ICpiMonthlyInput {
+  from: TIsoMonth;
+  /** default: whatever the source has published after `from` */
+  to?: TIsoMonth;
+  signal?: AbortSignal;
+}
+
+export interface ICpiAnnualInput {
+  from: TIsoYear;
+  /** default: whatever the source has published after `from` */
+  to?: TIsoYear;
+  signal?: AbortSignal;
+}

package/ts/cpi/request.ts

@@ -0,0 +1,49 @@
+import { CpiError } from './classes.cpierror.js';
+import { defaultCpiTimeoutMs } from './constants.js';
+import type { ICpiClientOptions, ICpiServiceAnswer, TCpiFetch } from './interfaces.js';
+
+/** The time a client gives one request: its option, or the default; anything else than a positive whole number of milliseconds is refused. */
+export const timeoutOf = (optionsArg: ICpiClientOptions): number => {
+  const timeout = optionsArg.timeoutMs ?? defaultCpiTimeoutMs;
+  if (!Number.isSafeInteger(timeout) || timeout <= 0) {
+    throw new CpiError('invalid_input', `the time limit is a positive whole number of milliseconds, got ${String(optionsArg.timeoutMs)}`);
+  }
+  return timeout;
+};
+
+/**
+ * Sends one `GET` for CSV and reads the answer whole, within the client's time. The caller's signal
+ * ends it as `aborted`, the time as `timeout`, and a request that could not be sent or answered as
+ * `unreachable`; nothing is retried. The timer ends with the request, answered or not.
+ */
+export const getText = async (
+  optionsArg: ICpiClientOptions,
+  urlArg: string,
+  signalArg: AbortSignal | undefined,
+): Promise<ICpiServiceAnswer> => {
+  const fetchFn: TCpiFetch = optionsArg.fetch ?? ((inputArg, initArg) => fetch(inputArg, initArg));
+  if (signalArg?.aborted) {
+    throw new CpiError('aborted', 'the request was ended by its caller', { service: 'bundesbank' }, { cause: signalArg.reason });
+  }
+  const timeout = new AbortController();
+  const timer = setTimeout(() => timeout.abort(new Error('the client\'s time ran out')), timeoutOf(optionsArg));
+  const signal = signalArg ? AbortSignal.any([signalArg, timeout.signal]) : timeout.signal;
+  try {
+    const response = await fetchFn(urlArg, {
+      method: 'GET',
+      headers: { accept: 'text/csv', ...(optionsArg.userAgent ? { 'user-agent': optionsArg.userAgent } : {}) },
+      signal,
+    });
+    return { httpStatus: response.status, text: await response.text() };
+  } catch (error) {
+    if (signalArg?.aborted) {
+      throw new CpiError('aborted', 'the request was ended by its caller', { service: 'bundesbank' }, { cause: error });
+    }
+    if (timeout.signal.aborted) {
+      throw new CpiError('timeout', 'the source did not answer in time', { service: 'bundesbank' }, { cause: error });
+    }
+    throw new CpiError('unreachable', 'the source could not be reached', { service: 'bundesbank' }, { cause: error });
+  } finally {
+    clearTimeout(timer);
+  }
+};

package/ts/plugins.ts

@@ -6,7 +6,6 @@ export {
 }
 
 // @push.rocks scope
-import * as qenv from '@push.rocks/qenv';
 import * as smartpath from '@push.rocks/smartpath';
 import * as smartpromise from '@push.rocks/smartpromise';
 import * as smartrequest from '@push.rocks/smartrequest';
@@ -21,7 +20,6 @@ const getErrorMessage = (error: unknown) => {
 
 export {
   getErrorMessage,
-  qenv,
   smartpath,
   smartpromise,
   smartrequest,