retail.price-rounding

export function roundPrice(price: Money, step: number, ending: number, direction: PriceDirection): Money

export type PriceDirection = "up" | "down" | "nearest";

import { roundPrice } from "#fune/retail.price-rounding@^1";

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

/**
 * Snap a price to the points k x step - ending.
 *
 * Shifting by `ending` turns every point into a multiple of `step`, so the
 * whole policy is one integer division with the right rounding mode.
 */
export function roundPrice(price: Money, step: number, ending: number, direction: PriceDirection): Money {
  if (!Number.isInteger(step) || step < 1) {
    throw new RangeError(`step must be 1 or more, received ${step}`);
  }
  if (!Number.isInteger(ending) || ending < 0 || ending >= step) {
    throw new RangeError(`ending must be from 0 to step - 1, received ${ending}`);
  }
  if (price.minor < 0) {
    throw new RangeError(`price must not be negative, received ${price.minor}`);
  }
  const shifted = price.minor + ending;
  let point: number;
  if (direction === "up") {
    point = roundDiv(shifted, step, "up") * step - ending;
  } else if (direction === "down") {
    point = roundDiv(shifted, step, "down") * step - ending;
    if (point < 0) throw new RangeError(`no price point at or below ${price.minor}`);
  } else if (direction === "nearest") {
    point = roundDiv(shifted, step, "half-up") * step - ending;
    // Below the first point the only candidate is above.
    if (point < 0) point = step - ending;
  } else {
    throw new RangeError(`unknown direction "${direction}"`);
  }
  return money(point, price.currency);
}

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 retail.price-rounding

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

The whole function, every language, is one file too: retail.price-rounding-1.0.0.fune, 13,055 bytes, sha256 d39029f0305ffe416736abd470d7272f7161efeb35839bc185a407b36c8df25e. It installs into a project of any language.

// fune: before retail.price-rounding

// fune: after retail.price-rounding

// fune: replace math.round-div in retail.price-rounding
// fune: replace money.amount in retail.price-rounding

// fune: step retail.price-rounding after <n|label>

More from the author

`up` gives the smallest point at or above the price, `down` the largest at or below, `nearest` whichever is closer. A tie (2.49 between 1.99 and 2.99) goes to the higher price, which is the usual retail choice and matches `math.round-div`'s half-up. A price already on a point is returned unchanged.

## Edge cases

- Points are never negative. `nearest` for a price below the first point (0.00 under charm .99) returns the first point, 0.99; `down` has no answer there and is an error. - The price must be 0 or more. Discounts and refunds are not rounded to price points. - Currency does not matter to the arithmetic, so the same rule works for yen (step 100, ending 20 gives ¥980, ¥1,080) as for pence.

This rounds a price someone is about to print on a shelf. It is not for tax or invoice arithmetic, which should use `math.round-div` or `money.apply-rate` directly.

Files