retail.volumetric-weight

export function chargeableWeight(lengthMm: number, widthMm: number, heightMm: number, actualGrams: number, divisor: number, roundUpToGrams: number): ChargeableWeight

/** Both weights, which one won, and the weight to charge on. */
export interface ChargeableWeight {
  readonly actualGrams: number;
  /** length x width x height / divisor, rounded up to the gram */
  readonly volumetricGrams: number;
  /** the greater of the two, rounded up to the billing step */
  readonly chargeableGrams: number;
  /** volumetric only when it is strictly greater */
  readonly basis: WeightBasis;
}

export type WeightBasis = "actual" | "volumetric";

import { chargeableWeight } from "#fune/retail.volumetric-weight@^1";

import { roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { type ChargeableWeight } from "./retail_volumetric_weight_types.ts";

/**
 * The weight a carrier charges on: the greater of actual and volumetric,
 * rounded up to the carrier's billing step.
 *
 * mm³ / (cm³ per kg) is exactly grams, so everything stays in integers.
 */
export function chargeableWeight(
  lengthMm: number,
  widthMm: number,
  heightMm: number,
  actualGrams: number,
  divisor: number,
  roundUpToGrams: number,
): ChargeableWeight {
  for (const d of [lengthMm, widthMm, heightMm]) {
    if (!Number.isInteger(d) || d < 1) throw new RangeError(`dimensions must be 1 mm or more, received ${d}`);
  }
  if (!Number.isInteger(actualGrams) || actualGrams < 0) {
    throw new RangeError(`actualGrams must not be negative, received ${actualGrams}`);
  }
  if (!Number.isInteger(divisor) || divisor < 1) throw new RangeError(`divisor must be 1 or more, received ${divisor}`);
  if (!Number.isInteger(roundUpToGrams) || roundUpToGrams < 1) {
    throw new RangeError(`roundUpToGrams must be 1 or more, received ${roundUpToGrams}`);
  }
  const volumetricGrams = roundDiv(lengthMm * widthMm * heightMm, divisor, "up");
  const heavier = Math.max(actualGrams, volumetricGrams);
  return {
    actualGrams,
    volumetricGrams,
    chargeableGrams: roundDiv(heavier, roundUpToGrams, "up") * roundUpToGrams,
    basis: volumetricGrams > actualGrams ? "volumetric" : "actual",
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 1 dependency, 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.volumetric-weight

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

The whole function, every language, is one file too: retail.volumetric-weight-1.0.0.fune, 12,793 bytes, sha256 aae507e675957ea20e4a1fa476747be9fc726667d41008986e4e2dedfe705a4d. It installs into a project of any language.

// fune: before retail.volumetric-weight

// fune: after retail.volumetric-weight

// fune: replace math.round-div in retail.volumetric-weight

// fune: step retail.volumetric-weight after <n|label>

More from the author

## Rounding

Two roundings, both up, both documented because both move money:

1. The volumetric weight is rounded up to the whole gram (7385.2 g is 7386 g). Carriers never round a parcel's size down. 2. The chargeable weight is rounded up to `roundUpToGrams`, the carrier's billing step (most bill in 500 g or 1 kg steps). Pass 1 to leave it at the gram.

When the two weights are equal the basis is `actual`.

## Inputs

Measure the longest, widest and tallest points of the packed parcel, bulges included; that is what the carrier's scanner will do. The order of the three dimensions does not matter. Carriers that measure in centimetres and round each dimension first need that rounding done before calling this.

Files