fleet.cost-per-mile

export function costPerMile(costs: WholeLifeCosts, miles: number): CostPerMile

/** A vehicle's costs over one period, split the way fleet reports split them. */
export interface WholeLifeCosts {
  /** purchase price less resale value; negative if it gained value */
  readonly depreciation: Money;
  /** fuel or electricity */
  readonly fuel: Money;
  /** servicing, tyres and repairs */
  readonly maintenance: Money;
  readonly insurance: Money;
  /** vehicle excise duty and similar */
  readonly tax: Money;
}

/** Cost per mile in tenths of a minor unit (503 = 50.3p), each rounded half-up on its own. */
export interface CostPerMile {
  readonly totalCost: Money;
  readonly depreciationTenths: number;
  readonly fuelTenths: number;
  readonly maintenanceTenths: number;
  readonly insuranceTenths: number;
  readonly taxTenths: number;
  /** from the total cost, so not always the sum of the rounded parts */
  readonly totalTenths: number;
  /** totalTenths as text with one decimal place: "50.3" */
  readonly perMile: string;
}

import { costPerMile } from "#fune/fleet.cost-per-mile@^1";

import { roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { type Money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { sumMoney } from "./money_sum.ts";  ← from money.sum ^1.0.0 · built alongside by fune
import { type CostPerMile, type WholeLifeCosts } from "./fleet_cost_per_mile_types.ts";

function tenths(amount: Money, miles: number): number {
  return roundDiv(amount.minor * 10, miles, "half-up");
}

function display(value: number): string {
  const sign = value < 0 ? "-" : "";
  const magnitude = Math.abs(value);
  return `${sign}${Math.floor(magnitude / 10)}.${magnitude % 10}`;
}

/**
 * Whole-life cost per mile, in tenths of a penny, the unit fleet reports use.
 *
 * Each part is rounded on its own for the breakdown, and the total is rounded
 * from the total cost: adding up the rounded parts drifts by a tenth or two,
 * which is why the total is not their sum.
 */
export function costPerMile(costs: WholeLifeCosts, miles: number): CostPerMile {
  if (!Number.isInteger(miles) || miles <= 0) {
    throw new RangeError(`miles must be a whole number above zero, received ${miles}`);
  }
  const totalCost = sumMoney(
    [costs.depreciation, costs.fuel, costs.maintenance, costs.insurance, costs.tax],
    costs.depreciation.currency
  );
  const totalTenths = tenths(totalCost, miles);
  return {
    totalCost,
    depreciationTenths: tenths(costs.depreciation, miles),
    fuelTenths: tenths(costs.fuel, miles),
    maintenanceTenths: tenths(costs.maintenance, miles),
    insuranceTenths: tenths(costs.insurance, miles),
    taxTenths: tenths(costs.tax, miles),
    totalTenths,
    perMile: display(totalTenths),
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add fleet.cost-per-mile

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./fleet.cost-per-mile-1.0.0-typescript.fune, or fetch it from a terminal with fune pull fleet.cost-per-mile@1.0.0:typescript.

The whole function, every language, is one file too: fleet.cost-per-mile-1.0.0.fune, 17,753 bytes, sha256 eac59b91ed735bbe4b2d8f38c349e2f4b840cd26eeecb644a17f65ca12d6f05c. It installs into a project of any language.

// fune: before fleet.cost-per-mile

// fune: after fleet.cost-per-mile

// fune: replace math.round-div in fleet.cost-per-mile
// fune: replace money.amount in fleet.cost-per-mile
// fune: replace money.sum in fleet.cost-per-mile

// fune: step fleet.cost-per-mile after <n|label>

More from the author

The costs come in as one `WholeLifeCosts` record of `Money`, all in one currency; mixing currencies is an error. The result gives each part per mile, the total per mile, and the total as text (`"50.3"`), all as integers in tenths of a minor unit, rounded half-up (half a tenth away from zero).

## Rounding

Every figure is rounded on its own, and the total is rounded from the total cost, not added up from the rounded parts. 6,040.00 over 12,000 miles is 50.3p a mile; the rounded parts (25.0 + 15.0 + 5.0 + 3.8 + 1.6) add up to 50.4. A report whose columns must add up should show the parts to more places or footnote the difference.

## Edges

Depreciation can be negative (a vehicle sold for more than it cost), and the per-mile figures are then negative too. Miles must be a whole number above zero. This does not work out the costs themselves: see `fleet.fuel-cost`, `fleet.vehicle-depreciation` and `fleet.ev-charging-cost`.

Files