inventory.safety-stock

export function safetyStock(input: SafetyStockInput): number

export type SafetyStockMethod = "service-level" | "max-minus-average";

/** What each method needs; fields the chosen method does not use may be null. */
export interface SafetyStockInput {
  readonly method: SafetyStockMethod;
  /** service-level: cycle service level, 9500 = 95%; one of the levels in the z-score table */
  readonly serviceLevelBasisPoints: number | null;
  /** service-level: standard deviation of demand per period (a day, a week) */
  readonly demandStdDev: number | null;
  /** lead time in the same periods; the average lead time for max-minus-average */
  readonly leadTime: number;
  /** average demand per period; max-minus-average, and service-level when lead time varies */
  readonly averageDemand: number | null;
  /** service-level: standard deviation of lead time, in periods; null when lead time is fixed */
  readonly leadTimeStdDev: number | null;
  /** max-minus-average: the highest demand in one period */
  readonly maxDemand: number | null;
  /** max-minus-average: the longest lead time, in periods */
  readonly maxLeadTime: number | null;
}

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

import { Z_SCORES } from "./inventory_safety_stock_data.ts";  ← this capability’s own data, compiled from data/z-scores.json into the same file by fune build
import { type SafetyStockInput } from "./inventory_safety_stock_types.ts";

function amount(name: string, value: number | null, method: string): number {
  if (value === null || value === undefined) {
    throw new RangeError(`${method} needs ${name}`);
  }
  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
    throw new RangeError(`${name} must be a finite number, not negative, received ${value}`);
  }
  return value;
}

// Six decimal places, half away from zero, then up to whole units: float noise
// such as 55.00000000000001 must not cost a whole extra unit.
function wholeUnitsUp(x: number): number {
  const y = x * 1e6;
  let micro = Math.floor(y);
  if (y - micro >= 0.5) micro += 1;
  return Math.floor((micro + 999999) / 1e6);
}

/** Safety stock in whole units, by the service-level or max-minus-average method. */
export function safetyStock(input: SafetyStockInput): number {
  const leadTime = amount("leadTime", input.leadTime, input.method);
  if (input.method === "service-level") {
    const level = input.serviceLevelBasisPoints;
    if (level === null || level === undefined) throw new RangeError("service-level needs serviceLevelBasisPoints");
    const row = Z_SCORES.find((r) => r.serviceLevelBasisPoints === level);
    if (!row) {
      throw new RangeError(`no z-score for a service level of ${level} basis points: use one of ${Z_SCORES.map((r) => r.serviceLevelBasisPoints).join(", ")}`);
    }
    const sd = amount("demandStdDev", input.demandStdDev, input.method);
    let variance = leadTime * sd * sd;
    const sl = input.leadTimeStdDev ?? 0;
    amount("leadTimeStdDev", sl, input.method);
    if (sl > 0) {
      const d = amount("averageDemand", input.averageDemand, "service-level with a varying lead time");
      variance = variance + d * d * sl * sl;
    }
    return wholeUnitsUp((row.zTenThousandths / 10000) * Math.sqrt(variance));
  }
  if (input.method === "max-minus-average") {
    const maxDemand = amount("maxDemand", input.maxDemand, input.method);
    const maxLeadTime = amount("maxLeadTime", input.maxLeadTime, input.method);
    const averageDemand = amount("averageDemand", input.averageDemand, input.method);
    const worst = maxDemand * maxLeadTime;
    const usual = averageDemand * leadTime;
    if (worst < usual) {
      throw new RangeError(`maxDemand x maxLeadTime (${worst}) must not be less than averageDemand x leadTime (${usual})`);
    }
    return wholeUnitsUp(worst - usual);
  }
  throw new RangeError(`unknown safety stock method "${input.method}"`);
}

Install

fune build

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

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

The whole function, every language, is one file too: inventory.safety-stock-1.0.0.fune, 23,713 bytes, sha256 d75657642e13f1c5f479aa6efcabc22b9f8cbee52afacec946682c4e660bdb76. It installs into a project of any language.

// fune: before inventory.safety-stock

// fune: after inventory.safety-stock

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

More from the author

safety stock = z x sqrt(L x sd^2 + d^2 x sL^2)

where `z` is the standard normal quantile for the service level, `L` the average lead time, `sd` the standard deviation of demand per period, `d` the average demand per period and `sL` the standard deviation of the lead time. When lead time is fixed (`leadTimeStdDev` null or 0) this is the familiar `z x sd x sqrt(L)`, and `averageDemand` is not needed. Demand and lead time must be in the same period: a daily standard deviation with a lead time in days. `stats.standard-deviation` gives `sd` from a demand history.

The service level is the **cycle service level**: the chance of not running out during one replenishment cycle. It is not the fill rate. `z` comes from a table (`data/z-scores.json`) of the levels people actually use, 50% to 99.9%, rather than an inverse normal function, which would be approximated differently in each language. Each value is the quantile rounded to four decimal places, e.g. 95% is 1.6449 and 97.5% is 1.9600. A level not in the table is an error; round to one that is.

**`max-minus-average`** - the rule of thumb that needs no statistics:

safety stock = maxDemand x maxLeadTime - averageDemand x leadTime

It is an error for the worst case to be below the average case.

**Rounding.** Both methods compute in floating point, which is fine for a statistical estimate but can land a whisker above a whole number (`2.2 x 25` is `55.00000000000001`). The figure is rounded to 6 decimal places (half away from zero) and then **up** to whole units, so 50.000000000000014 is 50 and not 51, and 98.694 is 99. All values must be finite and not negative.

Sources: z values are the standard normal quantiles, checked against NIST/SEMATECH e-Handbook of Statistical Methods, section 1.3.6.7.1, "Cumulative Distribution Function of the Standard Normal Distribution" (https://www.itl.nist.gov/div898/handbook/eda/section3/eda3671.htm), and computed to four places with Python's `statistics.NormalDist().inv_cdf`. The combined-variability formula is the standard one in Silver, Pyke and Thomas, *Inventory and Production Management in Supply Chains*, 4th ed., ch. 6.

Files