TPN Calculator
One engine, every center’s own protocol
Open source · MIT · June 2026 · v0.1.0
Parenteral nutrition for neonates and children is calculation-heavy, error-prone, and different at every center. TPN Calculator keeps the arithmetic in one tested engine and every clinical value in the center’s own profile.


Clinical decision-support tool — not a medical device. The shipped profile is guideline-based, not center-validated.
Different at every center
Total parenteral nutrition (TPN) for neonates and children is calculation-heavy, error-prone, and different at every center — different dose schedules, limits, product concentrations, and units. Most calculators bake one institution’s protocol into the code.
TPN is part of its author’s daily clinical routine as a pediatric surgery resident — exactly the kind of repetitive, high-stakes calculation that deserves better, safer tooling. So the project flips the usual approach: instead of hardcoding one hospital’s protocol, it pairs a pure, tested calculation engine with a per-center configuration profile. The same engine powers every center; only the profile changes.
An engine and a profile
The engine knows no clinical constants. It takes a patient input and a center profile, and returns a prescription plus safety warnings. A profile defines fluid schedules, energy targets, glucose/GIR limits, amino-acid and lipid dosing, electrolytes, additives, and safety rules (hard = block, soft = warn). Units (kcal/kJ, mmol/mEq) are configurable for international use.
The engine, @tpn/engine, is pure TypeScript and tied to no interface, so the same calculation runs in the phone app (Expo, iOS and Android), in the web app (React + Vite, on GitHub Pages) and in the tests. The interface layers hold no clinical logic.
The model, written down
Every formula is universal; every number comes from the profile. The project’s plan writes the model down, together with the choices a clinician should review:
- Advancement. GIR and macronutrient doses follow one pattern:
value(day) = min(start + advance × (day − 1), max). Day 1 yields the start. - Volume balance. The fluid total is the budget. Lipid is a separate emulsion drawn from it, leaving an aqueous admixture; amino acid, electrolytes and additives take their volumes from it, and the remaining water carries the dextrose — which fixes the final dextrose concentration.
- Glucose.
grams/day = GIR × weight × 1440 ÷ 1000. - Osmolarity. A linear estimate over the aqueous admixture, every coefficient from the profile; lipid is excluded.
- Calcium–phosphate. The simple solubility product (Ca × P) against a profile threshold — an approximation, not a curve.
- Safety. The profile’s rules are checked against the computed values. A hard violation does not stop the program; it comes back as a warning, and the interface decides whether to block. A built-in check flags components that overflow the total volume.
A reference that cites itself
The app ships one profile: a reference built from the 2018 European guidelines on pediatric parenteral nutrition (ESPGHAN/ESPEN/ESPR/CSPEN), for a preterm infant over 1500 g. Its dosing is traceable to the guidelines’ recommendation numbers, and the app shows them beside the values. What the guidelines do not give as a single number — dextrose limits, stock concentrations, product details, osmolarity coefficients — is marked representative: a center must replace and validate it. The peripheral-line osmolarity limit, 900 mOsm/L, follows A.S.P.E.N.; the profile lists it among the representative values too.
A center turns the reference into its own protocol inside the app: clone it, edit every field, export or import the result as JSON. The built-in reference itself cannot be edited or deleted.
How it was checked
- Engine tests. At the first release (v0.1.0, 17 June 2026) the engine had 87 tests with 98% coverage.
- Source-traceable cases. Regression tests against the ESPGHAN 2018 reference profile — the dosing trajectory by day of life, the energy target, line safety — so that every expected output can be traced to a citation.
- The apps. Integration and render tests for the phone app (jest-expo).
- Validation. Every profile, edited or imported, passes the engine’s
validateProfilebefore it can be used. - CI. On every change, lint and type-check on Node 22, build and coverage on Node 22 and 24; the web app is rebuilt and published from the same repository.
Limits
- A clinical decision-support tool, not a medical device: it has not been evaluated, cleared or registered by any authority (FDA, EU MDR, TİTCK). The ordering clinician is solely responsible; every result must be verified independently.
- The shipped profile is guideline-based, not center-validated; a center-validated profile is still pending. Each center must supply and validate its own numbers.
- Modelling gaps recorded in the project’s backlog: the phototherapy and radiant-warmer adjustments are absolute mL/kg, while the guideline gives a percentage; the fluid schedule has no birth-weight band; the guideline expresses calcium–phosphate risk as a molar Ca:P ratio and pharmacy-tested compatibility, not as a product threshold; the final dextrose concentration is computed over the aqueous phase only, and labelled so on screen.
- Early development: English only; other languages, a documentation site and community work are the next phase.
Documents
- Version
- v0.1.0 (17 June 2026). The web app and CI came after it and are not in a numbered release yet; live from the main branch: sahinparlak.github.io/tpn-calculator
- Licence
- MIT
- Engine
@tpn/engine— TypeScript, Vitest- Apps
- Phone: Expo (React Native), iOS and Android · Web: React + Vite, GitHub Pages
- Reference
- ESPGHAN/ESPEN/ESPR/CSPEN 2018; A.S.P.E.N. for safety thresholds
- Citation
CITATION.cffin the repository
Sources
- Repository: github.com/sahinparlak/tpn-calculator
- Disclaimer and terms of use: DISCLAIMER.md
- Plan and calculation model: docs/PLAN.md
- Profile authoring guide: docs/PROFILE.md
- Scientific basis and references: docs/REFERENCES.md
- The source of every value in the reference profile: profiles/espghan-2018-reference.sources.md
- Modelling gaps: docs/BACKLOG.md
- Changelog: CHANGELOG.md
- ESPGHAN — published guidelines: espghan.info/published-guidelines
- A.S.P.E.N. guideline for parenteral nutrition in preterm infants (Robinson et al., JPEN, 2023): DOI 10.1002/jpen.2550
Notes
- The phone screens are the repository README’s own images. The web screens were taken on 17 November 2026 from the web app built from the repository’s main branch, with the bundled reference profile and the app’s own example patient.
- The numbers in the screens are the output of a guideline reference for an example patient, not a prescription.
Compiled from the project’s own repository and documents; last checked 18 November 2026.