periop-calculators

Evidence-based perioperative risk assessment calculators for healthcare professionals. Built with TypeScript for type safety and modern JavaScript environments.

Features

• 🏥 Clinical Accuracy: Implements validated perioperative risk assessment tools
• 🔍 Type Safe: Full TypeScript support with comprehensive type definitions
• 📋 Well Tested: Extensive test coverage for reliability
• 📚 Documented: Detailed API documentation with clinical references
• 🚀 Lightweight: No external dependencies, small bundle size
• 🔧 Flexible: Works in Node.js and browser environments

Installation

npm install periop-calculators

or

yarn add periop-calculators

Quick Start

import { calculateStopBang } from 'periop-calculators';

const result = calculateStopBang({
  snoring: true,
  tiredness: true,
  observed: false,
  pressure: true,
  bmi: 36,
  age: 55,
  neckCircumference: 43,
  gender: 'male'
});

console.log(result);
// {
//   score: 6,
//   risk: 'high',
//   interpretation: 'STOP-BANG score of 6 indicates high risk...',
//   components: { S: true, T: true, O: false, ... },
//   recommendations: [...]
// }

Available Calculators

1. STOP-BANG Score

Screening tool for obstructive sleep apnea (OSA) in surgical patients.

import { calculateStopBang, StopBangInput, StopBangResult } from 'periop-calculators';

const input: StopBangInput = {
  snoring: true,           // Snoring loudly
  tiredness: true,         // Daytime tiredness
  observed: false,         // Observed apnea
  pressure: true,          // Hypertension
  bmi: 36,                // BMI > 35
  age: 55,                // Age > 50
  neckCircumference: 43,  // Neck > 40cm
  gender: 'male'          // Male gender
};

const result: StopBangResult = calculateStopBang(input);

With Patient Demographics

The calculator can derive values from patient demographics:

import { calculateStopBang, PatientDemographics } from 'periop-calculators';

const demographics: PatientDemographics = {
  age: 55,
  sex: 'male',
  weight: 100,  // kg
  height: 180,  // cm
  neckCircumference: 43
};

const result = calculateStopBang(
  {
    snoring: true,
    tiredness: true,
    observed: false,
    pressure: true
  },
  demographics  // BMI, age, and gender will be calculated
);

Risk Stratification

• Low Risk (0-2): Low probability of moderate to severe OSA
• Intermediate Risk (3-4): Further evaluation may be warranted
• High Risk (5-8): High probability of moderate to severe OSA

2. RCRI (Revised Cardiac Risk Index)

Estimates risk of cardiac complications for patients undergoing non-cardiac surgery.

import { calculateRCRI, RCRIInput, RCRIResult } from 'periop-calculators';

const input: RCRIInput = {
  highRiskSurgery: true,          // Intraperitoneal, intrathoracic, or suprainguinal vascular
  ischemicHeartDisease: false,    // History of MI, positive stress test, angina, nitrate use
  congestiveHeartFailure: false,  // History of CHF, pulmonary edema, or dyspnea
  cerebrovascularDisease: false,  // History of stroke or TIA
  insulinDependentDiabetes: true, // Diabetes requiring insulin therapy
  renalInsufficiency: false       // Creatinine > 2.0 mg/dL
};

const result: RCRIResult = calculateRCRI(input);

console.log(result);
// {
//   score: 2,
//   riskClass: 'III',
//   estimatedRisk: '6.6%',
//   riskPercentage: 6.6,
//   interpretation: 'RCRI Class III with 2 risk factors...',
//   riskFactors: { ... },
//   recommendations: [...]
// }

Risk Classification

• Class I (0 points): 0.4% risk of major cardiac complications
• Class II (1 point): 0.9% risk of major cardiac complications
• Class III (2 points): 6.6% risk of major cardiac complications
• Class IV (≥3 points): ≥11% risk of major cardiac complications

Helper Function

import { isHighRiskSurgery } from 'periop-calculators';

// Check if a surgery type is considered high risk
const isHighRisk = isHighRiskSurgery('aortic aneurysm repair'); // true
const isLowRisk = isHighRiskSurgery('cataract surgery');        // false

API Reference

Types

STOP-BANG Types

interface StopBangInput {
  snoring: boolean;
  tiredness: boolean;
  observed: boolean;
  pressure: boolean;
  bmi?: number;
  age?: number;
  neckCircumference?: number;
  gender?: 'male' | 'female';
}

interface StopBangResult {
  score: number;
  risk: 'low' | 'intermediate' | 'high';
  interpretation: string;
  components: {
    S: boolean;  // Snoring
    T: boolean;  // Tiredness
    O: boolean;  // Observed apnea
    P: boolean;  // Pressure (hypertension)
    B: boolean;  // BMI > 35
    A: boolean;  // Age > 50
    N: boolean;  // Neck circumference > 40cm
    G: boolean;  // Gender (male)
  };
  recommendations: string[];
}

RCRI Types

interface RCRIInput {
  highRiskSurgery: boolean;
  ischemicHeartDisease: boolean;
  congestiveHeartFailure: boolean;
  cerebrovascularDisease: boolean;
  insulinDependentDiabetes: boolean;
  renalInsufficiency: boolean;
}

interface RCRIResult {
  score: number;
  riskClass: 'I' | 'II' | 'III' | 'IV';
  estimatedRisk: string;
  riskPercentage: number;
  interpretation: string;
  riskFactors: {
    highRiskSurgery: boolean;
    ischemicHeartDisease: boolean;
    congestiveHeartFailure: boolean;
    cerebrovascularDisease: boolean;
    insulinDependentDiabetes: boolean;
    renalInsufficiency: boolean;
  };
  recommendations: string[];
}

MELD Score Types

interface MELDScoreInput {
  bilirubin: number;    // Serum bilirubin in mg/dL
  creatinine: number;   // Serum creatinine in mg/dL
  inr: number;          // International normalized ratio
  dialysis?: boolean;   // Dialysis twice within past week (optional)
}

interface MELDScoreResult {
  score: number;              // MELD score (6-40)
  mortalityRisk: string;      // 3-month mortality estimate
  mortalityPercentage: number; // Mortality percentage
  risk: 'low' | 'moderate' | 'high' | 'very-high';
  interpretation: string;     // Clinical interpretation
  labValues: {
    bilirubin: number;
    creatinine: number;
    inr: number;
    dialysis: boolean;
  };
  recommendations: string[];
}

Utility Functions

import { calculateBMI } from 'periop-calculators';

const bmi = calculateBMI(80, 175); // weight in kg, height in cm
// Returns: 26.1

3. MELD Score (Model for End-Stage Liver Disease)

Assesses liver disease severity and predicts short-term mortality in patients with end-stage liver disease.

import { calculateMELDScore, MELDScoreInput, MELDScoreResult } from 'periop-calculators';

const input: MELDScoreInput = {
  bilirubin: 2.5,      // Serum bilirubin in mg/dL
  creatinine: 1.8,     // Serum creatinine in mg/dL  
  inr: 1.6,            // International normalized ratio
  dialysis: false      // Dialysis twice in past week (optional)
};

const result: MELDScoreResult = calculateMELDScore(input);

console.log(result);
// {
//   score: 21,
//   mortalityRisk: '19.6%',
//   mortalityPercentage: 19.6,
//   risk: 'high',
//   interpretation: 'MELD score of 21 indicates high risk...',
//   labValues: { bilirubin: 2.5, creatinine: 1.8, inr: 1.6, dialysis: false },
//   recommendations: [...]
// }

Risk Stratification

• Low Risk (6-9): 1.9% 3-month mortality risk
• Moderate Risk (10-19): 6.0% 3-month mortality risk
• High Risk (20-29): 19.6% 3-month mortality risk
• Very High Risk (30-40): 52.6% 3-month mortality risk

Helper Functions

import { isHighRiskMELD, getMELDRiskCategory } from 'periop-calculators';

// Check if MELD score indicates high surgical risk
const isHighRisk = isHighRiskMELD(25); // true (score ≥ 20)
const isLowRisk = isHighRiskMELD(15);  // false

// Get risk category without full calculation
const riskCategory = getMELDRiskCategory(22); // 'high'

4. Apfel Score for PONV

Predicts risk of postoperative nausea and vomiting (PONV) in adult patients undergoing general anesthesia.

import { calculateApfelScore, ApfelScoreInput, ApfelScoreResult } from 'periop-calculators';

const input: ApfelScoreInput = {
  female: true,                   // Female gender
  nonSmoker: true,               // Non-smoking status
  historyOfPONV: false,          // History of PONV or motion sickness
  postoperativeOpioids: true     // Expected postoperative opioid use
};

const result: ApfelScoreResult = calculateApfelScore(input);

console.log(result);
// {
//   score: 3,
//   riskPercentage: 61,
//   risk: 'very-high',
//   interpretation: 'Apfel Score of 3 with 3 risk factors...',
//   riskFactors: { ... },
//   recommendations: [...]
// }

Risk Stratification

• 0 points: 10% risk of PONV (low risk)
• 1 point: 21% risk of PONV (moderate risk)
• 2 points: 39% risk of PONV (high risk)
• 3 points: 61% risk of PONV (very high risk)
• 4 points: 79% risk of PONV (very high risk)

Helper Function

import { getApfelRiskFactorInfo } from 'periop-calculators';

// Get detailed information about a specific risk factor
const info = getApfelRiskFactorInfo('female');
// Returns: "Female gender is associated with 2-3 times higher risk of PONV compared to males"

Clinical References

STOP-BANG References

1. Chung F, et al. STOP-Bang Questionnaire: A Tool to Screen Patients for Obstructive Sleep Apnea. Anesthesiology. 2008;108(5):812-821.

2. Chung F, et al. High STOP-Bang score indicates a high probability of obstructive sleep apnoea. Br J Anaesth. 2012;108(5):768-775.

RCRI References

1. Lee TH, et al. Derivation and prospective validation of a simple index for prediction of cardiac risk of major noncardiac surgery. Circulation. 1999;100(10):1043-1049.

2. Duceppe E, et al. Canadian Cardiovascular Society Guidelines on Perioperative Cardiac Risk Assessment and Management for Patients Who Undergo Noncardiac Surgery. Can J Cardiol. 2017;33(1):17-32.

MELD Score References

1. Kamath PS, et al. A model to predict survival in patients with end-stage liver disease. Hepatology. 2001;33(2):464-470.

2. Wiesner R, et al. Model for end-stage liver disease (MELD) and allocation of donor livers. Gastroenterology. 2003;124(1):91-96.

3. Teh SH, et al. Risk factors for mortality after surgery in patients with cirrhosis. Gastroenterology. 2007;132(4):1261-1269.

Apfel Score References

1. Apfel CC, et al. A simplified risk score for predicting postoperative nausea and vomiting: conclusions from cross-validations between two centers. Anesthesiology. 1999;91(3):693-700.

2. Apfel CC, et al. Evidence-based analysis of risk factors for postoperative nausea and vomiting. Br J Anaesth. 2012;109(5):742-753.

Development

# Install dependencies
npm install

# Run tests
npm test

# Build the package
npm run build

# Run linting
npm run lint

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/new-calculator)
3. Commit your changes (git commit -m 'Add RCRI calculator')
4. Push to the branch (git push origin feature/new-calculator)
5. Open a Pull Request

Future Calculators

Planned additions to this package:

• [x] RCRI (Revised Cardiac Risk Index) ✅
• [x] MELD Score ✅
• [ ] P-POSSUM Score
• [x] Apfel Score for PONV ✅
• [ ] Caprini Score for VTE Risk
• [ ] ASA Physical Status Calculator

License

MIT © Syed Haider Hasan Rizvi, MD

Author

Dr. Syed Haider Hasan Rizvi

• Board-certified anesthesiologist and physician-developer
• Creator of CoagRX and PeriopAI
• GitHub | LinkedIn

Built with ❤️ by a physician who codes