health.dose-weight-based Unreviewed

export function weightBasedDose(weightGrams: number, dosePerKgMicrograms: number, maxSingleDoseMicrograms: number | null, strengthMicrograms: number, strengthVolumeMicrolitres: number, measuringIncrementMicrolitres: number): WeightBasedDose

/** The dose worked out, the volume to give, and how far the measurable volume is from the dose. */
export interface WeightBasedDose {
  /** weight × dose per kg, half-up to a whole microgram, before any cap */
  readonly calculatedMicrograms: number;
  /** true when the calculated dose was above the maximum single dose */
  readonly cappedAtMaximum: boolean;
  /** the dose aimed for: the maximum when capped, else the calculated dose; half-up */
  readonly targetMicrograms: number;
  /** the volume to give, a whole number of measuring increments */
  readonly volumeMicrolitres: number;
  /** what that volume contains, half-up to a whole microgram */
  readonly deliveredMicrograms: number;
  /** delivered against target, signed; -65 = 0.65% under; half away from zero */
  readonly differenceBasisPoints: number;
}

import { weightBasedDose } from "#fune/health.dose-weight-based@^1";

import { type WeightBasedDose } from "./health_dose_weight_based_types.ts";

function checkRange(name: string, value: number, low: number, high: number): void {
  if (!Number.isInteger(value) || value < low || value > high) {
    throw new RangeError(`${name} must be a whole number from ${low} to ${high}, received ${value}`);
  }
}

/** num / den rounded half-up, for num >= 0 and den > 0. */
function halfUp(num: bigint, den: bigint): bigint {
  return (2n * num + den) / (2n * den);
}

/** num / den rounded half away from zero, for den > 0. */
function halfAwayFromZero(num: bigint, den: bigint): bigint {
  const magnitude = halfUp(num < 0n ? -num : num, den);
  return num < 0n ? -magnitude : magnitude;
}

/**
 * A weight-based dose, capped at the maximum single dose and turned into a
 * volume the measuring device can show. Every quantity is a whole number of
 * micrograms, microlitres or grams and every step is an exact fraction, so a
 * 0.1 mL step never drifts to 0.30000000000000004 mL. The volume is the
 * nearest whole number of increments, a tie going down, and never one that
 * would deliver more than the maximum single dose.
 */
export function weightBasedDose(
  weightGrams: number,
  dosePerKgMicrograms: number,
  maxSingleDoseMicrograms: number | null,
  strengthMicrograms: number,
  strengthVolumeMicrolitres: number,
  measuringIncrementMicrolitres: number,
): WeightBasedDose {
  checkRange("weightGrams", weightGrams, 200, 500000);
  checkRange("dosePerKgMicrograms", dosePerKgMicrograms, 1, 1000000);
  if (maxSingleDoseMicrograms !== null) checkRange("maxSingleDoseMicrograms", maxSingleDoseMicrograms, 1, 100000000);
  checkRange("strengthMicrograms", strengthMicrograms, 1, 100000000);
  checkRange("strengthVolumeMicrolitres", strengthVolumeMicrolitres, 1, 1000000);
  checkRange("measuringIncrementMicrolitres", measuringIncrementMicrolitres, 1, 100000);

  const perKg = BigInt(weightGrams) * BigInt(dosePerKgMicrograms); // micrograms × 1000
  const max = maxSingleDoseMicrograms === null ? null : BigInt(maxSingleDoseMicrograms);
  const capped = max !== null && perKg > max * 1000n;
  // The target dose as the exact fraction targetNum / targetDen micrograms.
  const targetNum = capped ? (max as bigint) : perKg;
  const targetDen = capped ? 1n : 1000n;

  const strength = BigInt(strengthMicrograms);
  const volume = BigInt(strengthVolumeMicrolitres);
  const increment = BigInt(measuringIncrementMicrolitres);
  // Increments needed: target × volume / (strength × increment), nearest, a tie down.
  const stepsNum = targetNum * volume;
  const stepsDen = targetDen * strength * increment;
  let steps = stepsNum / stepsDen;
  if (2n * (stepsNum % stepsDen) > stepsDen) steps += 1n;
  // Rounding up to the nearest step must not take the dose over the maximum.
  if (max !== null && steps * increment * strength > max * volume) steps -= 1n;
  if (steps === 0n) {
    throw new RangeError("dose is less than one measuring increment; use a more dilute product or a finer measure");
  }

  const deliveredNum = steps * increment * strength; // micrograms × volume
  return {
    calculatedMicrograms: Number(halfUp(perKg, 1000n)),
    cappedAtMaximum: capped,
    targetMicrograms: Number(halfUp(targetNum, targetDen)),
    volumeMicrolitres: Number(steps * increment),
    deliveredMicrograms: Number(halfUp(deliveredNum, volume)),
    differenceBasisPoints: Number(
      halfAwayFromZero((deliveredNum * targetDen - targetNum * volume) * 10000n, targetNum * volume),
    ),
  };
}

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 health.dose-weight-based

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

The whole function, every language, is one file too: health.dose-weight-based-1.0.1.fune, 26,519 bytes, sha256 fb3a319fd96fe97fc55f9f76484cb17fd73dfdd268483893ef40cb6d90639fa5. It installs into a project of any language.

// fune: before health.dose-weight-based

// fune: after health.dose-weight-based

// fune: step health.dose-weight-based after <n|label>

More from the author

## Units

Everything is a whole number in small units, so no step drifts. In floating point, three 0.1 mL steps are 0.30000000000000004 mL. Here they are 300 µL.

| you have | pass | |----------|---------------------------| | 1 kg | 1000 g | | 1 mg | 1000 µg | | 1 mL | 1000 µL | | 120 mg/5 mL | strength 120000 µg in 5000 µL | | 1 g in 3 mL | strength 1000000 µg in 3000 µL (no 333.33… mg/mL rounding) |

A weight of 12.4 is refused, not read as grams, because a slip between kilograms and grams is a thousand-fold error.

## Worked example

15 mg/kg for a 12.4 kg child is 186 mg. At 120 mg in 5 mL that is 7.75 mL. The syringe is marked in 0.1 mL, and 7.75 lies exactly between 7.7 and 7.8. The tie goes down, so the answer is 7.7 mL, which holds 184.8 mg. `differenceBasisPoints` is -65, meaning the given dose is 0.65% below the calculated dose.

## Rounding rules

- **Cap first.** When weight × dose per kg is more than the maximum single dose, the maximum becomes the target and `cappedAtMaximum` is true. A dose exactly at the maximum is not capped. - **Nearest measurable volume, a tie goes down.** When the dose is exactly halfway between two steps, the smaller one is chosen, because that is the more cautious choice. - **Never over the maximum.** If rounding to the nearest step would deliver more than the maximum single dose, the volume drops one step. - **Never zero.** If the dose rounds to no increments at all, the function raises an error. The fix is a more dilute product or a finer measure, not silently giving nothing.

Local policy may round differently. For example, some policies always round down, and some allow up to ±10%. `differenceBasisPoints` compares the delivered dose with the target (signed, 100 = 1%), so a caller can enforce its own tolerance. The integer outputs (`calculatedMicrograms`, `targetMicrograms`, `deliveredMicrograms`) are rounded half-up to a whole microgram for display. The comparisons and the difference use the exact fractions.

## Limits (refused, not clamped)

weightGrams 200 to 500000; dosePerKgMicrograms 1 to 1000000; maxSingleDoseMicrograms 1 to 100000000 or null for none; strengthMicrograms 1 to 100000000; strengthVolumeMicrolitres 1 to 1000000; measuringIncrementMicrolitres 1 to 100000.

It does not check that the dose per kg, the maximum or the product are right for the drug, the patient's age or renal function, or the route. It does not convert to dosing by body surface area, and it does not cap by a daily maximum.

## Before you rely on this

**Not professional advice.** This capability calculates health figures from published rules. It is a software component for developers, not medical advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a pharmacist review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Not a medical device.** It is not intended to diagnose, treat or support clinical decisions about any individual. Anyone building it into clinical software is responsible for that software's regulatory status, and must validate it under their own clinical governance.

**Not for clinical use; regulatory review pending.** Whether publishing this capability makes it a medical device is under regulatory review. Until that is settled it is a developer library only.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified pharmacist has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed (not for clinical use; regulatory review pending). The code and the tests are unchanged.

Files