inventory.stock-turnover

export function stockTurnover(openingStock: Money, closingStock: Money, costOfSales: Money, periodDays: number): StockTurnover

/** How fast stock moves, three ways. */
export interface StockTurnover {
  /** (opening + closing) / 2, half-up to minor units */
  readonly averageStock: Money;
  /** cost of sales / average stock, to 2 decimal places; null when average stock is zero */
  readonly turns: number | null;
  /** average stock / cost of sales x periodDays, to 1 decimal place; null when cost of sales is zero */
  readonly daysInventoryOutstanding: number | null;
  /** closing stock / cost of sales x periodDays, to 1 decimal place; null when cost of sales is zero */
  readonly daysOfCover: number | null;
}

import { stockTurnover } from "#fune/inventory.stock-turnover@^1";

import { roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { type Money, assertSameCurrency, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { type StockTurnover } from "./inventory_stock_turnover_types.ts";

function notNegative(name: string, amount: Money): void {
  if (amount.minor < 0) throw new RangeError(`${name} must not be negative, received ${amount.minor}`);
}

/**
 * Turns, days inventory outstanding and days of cover. Each is one exact
 * division rounded half-up, then made a float, so every language agrees.
 */
export function stockTurnover(openingStock: Money, closingStock: Money, costOfSales: Money, periodDays: number): StockTurnover {
  assertSameCurrency(openingStock, closingStock);
  assertSameCurrency(openingStock, costOfSales);
  notNegative("openingStock", openingStock);
  notNegative("closingStock", closingStock);
  notNegative("costOfSales", costOfSales);
  if (!Number.isInteger(periodDays) || periodDays < 1) {
    throw new RangeError(`periodDays must be a whole number of days, at least 1, received ${periodDays}`);
  }
  const both = openingStock.minor + closingStock.minor;
  const cogs = costOfSales.minor;
  return {
    averageStock: money(roundDiv(both, 2, "half-up"), openingStock.currency),
    turns: both === 0 ? null : roundDiv(cogs * 200, both, "half-up") / 100,
    daysInventoryOutstanding: cogs === 0 ? null : roundDiv(both * periodDays * 10, cogs * 2, "half-up") / 10,
    daysOfCover: cogs === 0 ? null : roundDiv(closingStock.minor * periodDays * 10, cogs, "half-up") / 10,
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 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 inventory.stock-turnover

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

The whole function, every language, is one file too: inventory.stock-turnover-1.0.0.fune, 14,658 bytes, sha256 9155bb345cfebcc9171de07f32cb2dbca138e4b611c2e5f980f793cbbc978314. It installs into a project of any language.

// fune: before inventory.stock-turnover

// fune: after inventory.stock-turnover

// fune: replace math.round-div in inventory.stock-turnover
// fune: replace money.amount in inventory.stock-turnover

// fune: step inventory.stock-turnover after <n|label>

More from the author

**Exact, then rounded once.** Each ratio is a single division of whole minor units, rounded half-up with `math.round-div` to hundredths (turns) or tenths (days), and only then turned into a float. So 0.005 turns is 0.01 in every language, where `Math.round(x * 100) / 100` and Python's `round(x, 2)` disagree. `averageStock` is rounded half-up to a minor unit for display; the ratios use the exact sum, not the rounded average.

**No answer is null, not zero or infinity.** Turns is null when average stock is zero; the two day counts are null when cost of sales is zero (stock that does not move has no cover horizon).

Use cost values throughout: turnover on sales value against stock at cost overstates it by the margin. Stock values and cost of sales may not be negative, the three amounts must share a currency, and periodDays must be at least 1.

Source: the standard definitions, e.g. CIMA Official Terminology (inventory turnover, inventory days).

Files