formulab

Industrial & manufacturing calculation library for engineers

A comprehensive collection of engineering formulas and calculations for manufacturing, quality control, logistics, and industrial applications. Zero dependencies, fully typed, tree-shakeable.

Features

174 industrial calculations + 8 type guards — OEE, Cpk, SPC control charts, Gage R&R, Weibull, metal weight, CNC machining, GD&T, pipe flow, CBM, NIOSH lifting, PMV/PPD, arc flash, battery SOH, GHG emissions, PID tuning, and more
14 specialized domains — Quality, Metal, Chemical, Electronics, Construction, Automotive, Logistics, Energy, Safety, Food, Utility, Battery, Environmental, Machining
Zero dependencies — Lightweight and fast
TypeScript first — Full type definitions included
Tree-shakeable — Import only what you need
2,494 tests — Coverage thresholds: 90% lines, 95% functions, 85% branches (CI pipeline)
Research-based — Golden reference tests verified against NIOSH 94-110, AIAG/ASTM E2587, JIPM, ASME B16.5, ISO 22514-2, and more

Verification Status

Domain	Functions	Golden Tests	Key References
Quality	18	oee, cpk, controlChart, gageRR	ISO 22400-2, AIAG/ASTM E2587, JIPM, AIAG MSA
Metal	25	metalWeight	Machinery's Handbook, ASME B36.10/B16.5
Logistics	17	cbm	Physical formula
Safety	14	nioshLifting	NIOSH 94-110, ISO 7730, IEEE 1584, OSHA
Chemical	12	—	Darcy-Weisbach, Fourier, API 520, ISA
Electronics	11	—	IPC-2221
Construction	12	—	AISC, Timoshenko
Automotive	9	—	AASHTO, SAE J1772
Energy	15	—	NREL PVWatts, ISO 50001
Food	6	—	HACCP, ICH Q1A
Utility	16	—	—
Battery	10	—	IEEE 1188, IEC 62620, Battery University
Environmental	10	—	GHG Protocol, IPCC AR6, IEA 2023
Machining	12	—	Machinery's Handbook, ASME Y14.5, Sandvik Coromant

Functions with golden reference tests have been verified against authoritative engineering sources. See each function's JSDoc for specific references.

Numerical Accuracy & Testing

Floating-Point Handling

All calculations use a sign-aware roundTo() utility with epsilon correction to avoid IEEE 754 rounding artifacts:

roundTo(0.615, 2)   // → 0.62  (not 0.61)
roundTo(-2.555, 2)  // → -2.56 (sign-aware)

Non-finite values (NaN, Infinity) pass through unchanged. All validation errors throw RangeError — no function returns NaN or Infinity for invalid inputs. Each function's JSDoc specifies output precision (typically 2-4 decimal places) and @throws conditions.

Golden Reference Tests

The following functions include tests verified against published reference values:

Function	Standard / Source	What is verified
`nioshLifting()`	NIOSH Publication 94-110	LC=23kg ideal, FM/CM table values, RWL calculation
`oee()`	JIPM TPM Handbook	World-class OEE (A≥90%, P≥95%, Q≥99.9%), perfect 100%
`cpk()`	ISO 22514-2	Six Sigma Cpk=2.0, minimum capable Cpk≈1.33, off-center penalty
`controlChart()`	AIAG/ASTM E2587-16	A2, D3, D4, d2 constants for n=2, 3, 5
`cbm()`	Physical formula	20ft container 33.2m³, 1m³ cube reference
`metalWeight()`	Machinery's Handbook	Steel plate density 7.85 g/cm³
`flangeSpec()`	ASME B16.5	Class 150/300/600 flange dimensions
`pipeSpec()`	ASME B36.10	SCH40/80/160 wall thickness
`awgProperties()`	ANSI/AWG	AWG 0-40 diameter, resistance

Edge Case Handling

Functions validate or handle these boundary conditions:

Division by zero: cpk() with zero standard deviation, oee() with zero planned time
Out-of-range inputs: tolerance() rejects invalid IT grades, aql() validates lot sizes
Physical impossibility: pressFit() rejects negative interference, nioshLifting() clamps multipliers to [0, 1]
Extreme values: aql() handles 1M-unit lots, awgProperties() covers AWG 0-40

Optimization Functions — Algorithms & Limitations

Three functions solve NP-hard combinatorial problems using heuristic algorithms. They provide good practical results but do not guarantee optimal solutions:

Function	Algorithm	Complexity	Optimality
`tsp()`	Nearest Neighbor + 2-Opt local search; brute force for n ≤ 10	O(n²) per NN start, O(n!) exact for n ≤ 10	Heuristic — no approximation ratio guarantee; exact only for n ≤ 10
`pallet3d()`	Bottom-Left-Fill + First Fit Decreasing with AABB collision & stability checks	O(m² × n) where m = placed boxes	Heuristic — greedy placement; enforces physical constraints (80% support, weight limit)
`cuttingStock()`	First Fit Decreasing (FFD) or Best Fit Decreasing (BFD), user-selectable	O(q²) worst case	FFD: ≤ 11/9 × OPT + 1 (proven bound); not optimal

For mission-critical optimization requiring proven-optimal solutions, use dedicated solvers (e.g., OR-Tools, Gurobi). These functions are designed for quick shop-floor estimates.

CI Pipeline

GitHub Actions runs on every push to main and every pull request:

Matrix: Node.js 18, 20
Steps: pnpm install → tsc (type check) → vitest run --coverage
Coverage enforcement: Fails if below thresholds (lines 90%, functions 95%, branches 85%, statements 90%)

# Run tests locally
pnpm test

# Run with coverage report
pnpm test:coverage

Installation

npm install formulab

pnpm add formulab

Quick Start

import { oee, metalWeight, cbm } from 'formulab';

// Calculate OEE (Overall Equipment Effectiveness)
const result = oee({
  rawData: {
    plannedTime: 480,      // minutes (8 hours)
    runTime: 432,          // minutes (90% availability)
    totalCount: 1000,
    goodCount: 990,        // 99% quality
    idealCycleTime: 0.456, // minutes per piece (95% performance)
  },
});
console.log(result.percentages.oee); // 84.6%

// Calculate metal weight
const weight = metalWeight({
  shape: 'plate',
  materialName: 'steel',
  length: 1000,    // mm
  width: 500,      // mm
  thickness: 10,   // mm
});
console.log(weight.weight); // 39.25 kg

// Calculate CBM (Cubic Meter)
const volume = cbm({
  length: 120,
  width: 80,
  height: 100,
  quantity: 1,
  unit: 'cm',
});
console.log(volume.totalCbm); // 0.96 m³

Domains

Quality & Production (18 functions)

import { oee, cpk, taktTime, dpmo, controlChart, gageRR, weibull } from 'formulab/quality';

Function	Description
`oee()`	Overall Equipment Effectiveness
`cpk()`	Process Capability Index
`controlChart()`	SPC X-bar/R and X-bar/S charts
`cycleTime()`	Cycle Time analysis
`taktTime()`	Takt Time calculation
`aql()`	AQL sampling inspection
`downtime()`	Downtime analysis
`dpmo()`	Defects Per Million Opportunities
`lineBalancing()`	Line balancing optimization
`mtbf()`	Mean Time Between Failures
`ppk()`	Process Performance Index
`ppm()`	Parts Per Million conversion
`rpn()`	Risk Priority Number (FMEA)
`yieldCalc()`	First Pass Yield / RTY
`gageRR()`	Gage R&R (AIAG MSA Average & Range)
`cmk()`	Machine capability index Cm/Cmk
`weibull()`	Weibull reliability analysis
`paretoAnalysis()`	Pareto 80/20 ABC classification

Metal & Machining (25 functions)

import { metalWeight, bendAllowance, cutting, bearing } from 'formulab/metal';

Function	Description
`metalWeight()`	Weight calculation for various shapes
`bendAllowance()`	Sheet metal bend allowance
`flatPattern()`	Flat pattern length calculation
`kFactorReverse()`	K-factor reverse engineering
`pressTonnage()`	Press brake tonnage
`bearing()`	L10 bearing life calculation
`bolt()`	Bolt torque and preload
`cutting()`	Cutting speed, feed rate, RPM
`cuttingStock()`	1D cutting stock heuristic (FFD/BFD)
`gear()`	Gear module calculation
`hardness()`	Hardness conversion (HRC, HB, HV)
`material()`	Material properties lookup
`pressFit()`	Press fit interference
`roughness()`	Surface roughness conversion
`screw()`	Screw specification
`spring()`	Spring design calculation
`tap()`	Tap drill size
`thread()`	Thread dimensions
`tolerance()`	ISO tolerance (IT grades)
`vibration()`	Natural frequency analysis
`weldHeat()`	Weld heat input calculation
`welding()`	Welding parameters
`materialGradeConverter()`	ASTM/EN/JIS/GB/KS grade cross-reference
`pipeSpec()`	ANSI/ASME pipe dimensions lookup
`flangeSpec()`	ASME B16.5 flange dimensions lookup

Chemical & Process (12 functions)

import { dilution, concentration, ph, reactor, pipeFlow, heatTransfer, flowControl, pid } from 'formulab/chemical';

Function	Description
`batch()`	Batch scaling calculation
`concentration()`	Concentration conversion
`dilution()`	Dilution (C1V1 = C2V2)
`heatTransfer()`	Conduction/convection/radiation heat transfer
`ph()`	pH and buffer calculations
`pipeFlow()`	Darcy-Weisbach pipe flow pressure drop
`reactor()`	Reactor sizing
`shelfLife()`	Shelf life prediction (Arrhenius)
`injectionCycle()`	Injection molding cycle time
`flowControl()`	Control valve Cv/Kv sizing (ISA/IEC 60534)
`reliefValve()`	Safety relief valve sizing (API 520/526)
`pid()`	PID controller tuning (Z-N / Cohen-Coon)

Electronics & SMT (11 functions)

import { traceWidth, solderPaste, resistorDecode, ohmsLaw } from 'formulab/electronics';

Function	Description
`ohmsLaw()`	Ohm's Law V/I/R/P calculator
`reflowProfile()`	Reflow temperature profile
`resistorDecode()`	Resistor color code decoder
`smtTakt()`	SMT line takt time
`solderPaste()`	Solder paste volume calculation
`traceWidth()`	PCB trace width (IPC-2221)
`awgProperties()`	AWG wire properties
`capacitorDecode()`	Capacitor code decoder
`ledResistor()`	LED resistor calculation
`stencilAperture()`	Stencil aperture design
`viaCurrent()`	Via current capacity

Construction (12 functions)

import { concreteMix, rebarWeight, slope, stair, momentOfInertia } from 'formulab/construction';

Function	Description
`momentOfInertia()`	Section properties (Ix, Sx, rx) for 7 shapes
`beamLoad()`	Beam load calculation
`concreteMix()`	Concrete mix ratio
`earthwork()`	Earthwork volume
`formwork()`	Formwork area calculation
`rebarWeight()`	Rebar weight by size
`slope()`	Slope conversion (%, degree, ratio)
`aggregate()`	Aggregate volume calculation
`brick()`	Brick quantity estimation
`pert()`	PERT schedule analysis
`roof()`	Roof calculation
`stair()`	Stair dimension calculation

Automotive (9 functions)

import { batteryRuntime, evCharging, torque, brakingDistance, chargingLoss } from 'formulab/automotive';

Function	Description
`brakingDistance()`	Stopping distance (AASHTO method)
`batteryRuntime()`	Battery capacity/runtime
`evCharging()`	EV charging time estimation
`fuelEconomy()`	Fuel economy conversion
`gearRatio()`	Gear ratio calculation
`tireCompare()`	Tire size comparison
`torque()`	Torque conversion
`power()`	Power conversion (HP, kW)
`chargingLoss()`	EV charging loss/efficiency

Logistics & Inventory (17 functions)

import { cbm, eoq, safetyStock, kanban, inventoryTurnover, abcAnalysis } from 'formulab/logistics';

Function	Description
`abcAnalysis()`	ABC inventory classification by annual value
`cbm()`	Cubic meter calculation
`containerFit()`	Container capacity estimation
`dimWeight()`	Dimensional weight
`eoq()`	Economic Order Quantity
`fillRate()`	Fill rate calculation
`freightClass()`	NMFC freight class
`inventoryTurnover()`	Inventory turnover ratio & days of supply
`kanban()`	Kanban quantity
`loadCapacity()`	Forklift load capacity derating
`pallet3d()`	3D pallet loading heuristic (BLF + FFD)
`palletStack()`	Pallet stacking calculation
`pickTime()`	Picking time estimation
`safetyStock()`	Safety stock calculation
`serviceLevel()`	Service level calculation
`shipping()`	Shipping cost estimation
`tsp()`	TSP heuristic (NN + 2-Opt; exact for n ≤ 10)

Energy & Utilities (15 functions)

import { powerCost, motorEfficiency, carbonFootprint, solarOutput, boilerEfficiency, heatPump, cusum } from 'formulab/energy';

Function	Description
`boilerEfficiency()`	Boiler thermal efficiency (direct method)
`carbonFootprint()`	Scope 2 emissions
`compressedAirCost()`	Compressed air cost
`cusum()`	CUSUM energy anomaly detection
`degreeDay()`	Heating/Cooling degree days (HDD/CDD)
`heatPump()`	Heat pump COP & Carnot efficiency
`insulationRoi()`	Insulation ROI & payback
`ledRoi()`	LED lighting retrofit ROI
`motorEfficiency()`	Motor upgrade ROI
`pfCorrection()`	Power factor correction
`powerCost()`	Electricity cost with demand
`solarOutput()`	Solar panel output estimation (PVWatts-based)
`transformerLoss()`	Transformer loss & efficiency
`vfdSavings()`	VFD energy savings
`windOutput()`	Wind turbine output with Rayleigh CF

Safety & Ergonomics (14 functions)

import { nioshLifting, noiseExposure, wbgtCalculate, ventilationRate, thermalComfort, arcFlash, lel } from 'formulab/safety';

Function	Description
`arcFlash()`	Arc flash incident energy & PPE (IEEE 1584)
`confinedSpace()`	Confined space atmospheric assessment (OSHA)
`ergonomicRisk()`	REBA ergonomic risk scoring
`fallClearance()`	Fall protection clearance
`havsCalculate()`	Hand-arm vibration exposure
`illuminance()`	Workplace illuminance (Lumen Method)
`ladderAngle()`	Ladder safety angle (OSHA 4:1)
`lel()`	Mixed gas LEL (Le Chatelier's rule)
`nioshLifting()`	NIOSH lifting equation
`noiseExposure()`	TWA/Dose calculation
`respiratorCalculate()`	Respirator MUC calculation
`thermalComfort()`	PMV/PPD thermal comfort (ISO 7730)
`ventilationRate()`	Required ventilation ACH/CFM (ASHRAE/OSHA)
`wbgtCalculate()`	WBGT heat stress index

Food & HACCP (6 functions)

import { calorie, nutrition, haccp, waterActivity, stabilityStudy } from 'formulab/food';

Function	Description
`calorie()`	Calorie requirement (BMR/TDEE)
`expiry()`	Expiry date calculation
`nutrition()`	Nutrition facts calculation
`haccp()`	HACCP checklist generation
`waterActivity()`	Water activity microbial risk (HACCP)
`stabilityStudy()`	Accelerated stability (Arrhenius, ICH Q1A)

Utility (16 functions)

import { solveAssignment, calculateUnit, statistics, regression, npv } from 'formulab/utility';

Function	Description
`solveAssignment()`	Hungarian algorithm optimization
`calculateUnit()`	Unit conversion (7 categories)
`getUnitCategories()`	Get unit categories
`statistics()`	Descriptive statistics (mean, median, stdDev, etc.)
`percentile()`	Percentile/quantile calculation
`correlation()`	Pearson correlation coefficient
`regression()`	Simple linear regression
`movingAverage()`	SMA/EMA/WMA moving average
`linearInterpolation()`	1D linear interpolation
`bilinearInterpolation()`	2D bilinear interpolation
`roi()`	Return on Investment
`npv()`	Net Present Value
`depreciation()`	Asset depreciation (SL/DDB/SYD)
`lcc()`	Life Cycle Cost analysis
`normalize()`	Data normalization (min-max/z-score)
`histogram()`	Frequency distribution histogram
`weightedScore()`	Weighted scoring model

Battery (10 functions)

import { energyDensity, cRate, stateOfHealth, cycleLife } from 'formulab/battery';

Function	Description
`energyDensity()`	Wh/kg and Wh/L energy density
`cRate()`	C-rate ↔ current/time conversion
`stateOfHealth()`	SOH % with degradation status
`batteryPackConfig()`	Series/parallel cell configuration
`cycleLife()`	Cycle life estimation (chemistry/DOD/temp)
`internalResistance()`	DCIR from OCV and load voltage
`selfDischarge()`	Self-discharge rate calculation
`thermalRunaway()`	Thermal safety margin analysis
`bmsBalancing()`	BMS cell balancing time estimation
`chargingProfile()`	CC-CV charging profile timing

Environmental (10 functions)

import { scope1Emissions, scope2Emissions, gwpCalculator, esgSummary } from 'formulab/environmental';

Function	Description
`scope1Emissions()`	Fuel combustion direct emissions (6 fuels)
`scope2Emissions()`	Purchased electricity emissions (12 regions)
`scope3Emissions()`	Supply chain spend-based emissions (8 categories)
`vocEmissions()`	VOC emissions with capture/destruction
`productCarbonFootprint()`	Product lifecycle carbon footprint
`gwpCalculator()`	GWP conversion (8 gases × 3 time horizons)
`energyIntensity()`	Energy intensity (MJ/unit, kWh/unit)
`waterFootprint()`	Water footprint (blue/green/grey)
`emissionsIntensity()`	Emissions intensity per unit/revenue/employee
`esgSummary()`	ESG reduction tracking and projections

Machining & CNC (12 functions)

import { truePosition, boltCircle, toolDeflection, threadOverWires } from 'formulab/machining';

Function	Description
`truePosition()`	GD&T True Position (diametral, MMC bonus)
`boltCircle()`	Bolt hole pattern coordinates
`sineBarHeight()`	Sine bar gauge block height
`radialChipThinning()`	Chip load compensation for light radial cuts
`toolDeflection()`	End mill cantilever deflection
`cuspHeight()`	Ball mill scallop height
`effectiveDiameter()`	Ball mill effective cutting diameter
`boringBarDeflection()`	Boring bar deflection with L/D guidance
`threadOverWires()`	3-wire thread measurement
`gaugeBlockStack()`	Gauge block combination (47/88/81-pc sets)
`triangleSolver()`	Triangle solver (SSS/SAS/ASA/SSA)
`cycleTimeEstimator()`	CNC cycle time estimation

API Examples

OEE Calculation

import { oee } from 'formulab/quality';

const result = oee({
  rawData: {
    plannedTime: 480,      // minutes
    runTime: 420,          // actual running time
    totalCount: 1000,      // total pieces produced
    goodCount: 990,        // good pieces
    idealCycleTime: 0.4,   // minutes per piece
  },
});

console.log(result);
// {
//   factors: { availability: 0.875, performance: 0.952, quality: 0.99, oee: 0.825 },
//   percentages: { availability: 87.5, performance: 95.2, quality: 99, oee: 82.5 }
// }

NIOSH Lifting Equation

import { nioshLifting } from 'formulab/safety';

const result = nioshLifting({
  loadWeight: 23,           // kg
  horizontalDistance: 25,   // cm
  verticalDistance: 75,     // cm (height at lift origin)
  verticalTravel: 25,       // cm (vertical travel distance)
  asymmetryAngle: 0,        // degrees
  coupling: 'good',         // 'good' | 'fair' | 'poor'
  frequency: 1,             // lifts per minute
  duration: 'short',        // 'short' | 'medium' | 'long'
});

console.log(result);
// {
//   rwl: 21.62,             // Recommended Weight Limit (kg)
//   liftingIndex: 1.06,     // LI = Load / RWL
//   riskLevel: 'moderate',
//   hm: 1.0, vm: 1.0, dm: 1.0, am: 1.0, fm: 0.94, cm: 1.0
// }

Dimensional Weight

import { dimWeight } from 'formulab/logistics';

const result = dimWeight({
  length: 60,
  width: 40,
  height: 30,
  unit: 'cm',
  carrier: 'international',
});

console.log(result);
// {
//   dimWeight: 14.4,
//   actualVolume: 0.072,
//   cbm: 0.072,
// }

Type Guards for Discriminated Unions

formulab provides runtime type guard functions for all discriminated union input types. These enable type-safe integration when working with dynamic data (e.g., form inputs, API responses):

import { isCRateInput, cRate } from 'formulab/battery';

// Form data from user input (Record<string, unknown>)
const formData: unknown = { mode: 'currentToRate', capacityAh: 100, currentA: 50 };

if (isCRateInput(formData)) {
  const result = cRate(formData); // Type-safe, no 'as any' needed
}

Available Type Guards

Guard	Domain	Discriminant	Variants
`isCRateInput()`	battery	`mode`	currentToRate, rateToCurrent
`isDilutionInput()`	chemical	`solveFor`	c1, v1, c2, v2
`isReactorInput()`	chemical	`shape`	cylindrical, spherical
`isHeatTransferInput()`	chemical	`mode`	conduction, convection, radiation
`isMomentOfInertiaInput()`	construction	`shape`	rectangle, circle, hollowRectangle, hollowCircle, iBeam, tSection, cChannel
`isOhmsLawInput()`	electronics	`solveFor`	voltage, current, resistance, power
`isMetalWeightInput()`	metal	`shape`	plate, round, pipe, angle
`isBoltInput()`	metal	`mode`	torqueToPreload, preloadToTorque

Error Handling

See ERRORS.md for the complete error behavior specification. Key points:

All validation failures throw RangeError with descriptive messages
No silent NaN/Infinity — every function guarantees finite outputs for valid inputs
Every @throws condition is documented in each function's JSDoc

import { metalWeight } from 'formulab/metal';

try {
  const result = metalWeight({ shape: 'plate', materialName: 'steel', length: 0, width: 100, thickness: 10 });
} catch (e) {
  if (e instanceof RangeError) {
    console.log(e.message); // "length must be positive"
  }
}

Tree Shaking

Import only what you need to minimize bundle size:

// Recommended - domain-specific import
import { oee } from 'formulab/quality';
import { metalWeight } from 'formulab/metal';

// Also works - main entry point (tree-shakeable)
import { oee, metalWeight } from 'formulab';

// Avoid - imports entire module
import * as formulab from 'formulab';

TypeScript Support

Full TypeScript support with detailed type definitions:

import type {
  OeeInput,
  OeeResult,
  CpkInput,
  CpkResult,
  MetalWeightInput,
  MetalWeightResult,
} from 'formulab';

Browser Support

formulab works in all modern browsers and Node.js:

Node.js 18+
Chrome 80+
Firefox 75+
Safari 13+
Edge 80+

Contributing

Contributions are welcome! Please see our GitHub repository.

# Clone the repository
git clone https://github.com/iyulab/formulab.git

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build
pnpm build

License

MIT © iyulab

Made with engineering precision by iyulab

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
.github/workflows		.github/workflows
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
ERRORS.md		ERRORS.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

formulab

Features

Verification Status

Numerical Accuracy & Testing

Floating-Point Handling

Golden Reference Tests

Edge Case Handling

Optimization Functions — Algorithms & Limitations

CI Pipeline

Installation

Quick Start

Domains

Quality & Production (18 functions)

Metal & Machining (25 functions)

Chemical & Process (12 functions)

Electronics & SMT (11 functions)

Construction (12 functions)

Automotive (9 functions)

Logistics & Inventory (17 functions)

Energy & Utilities (15 functions)

Safety & Ergonomics (14 functions)

Food & HACCP (6 functions)

Utility (16 functions)

Battery (10 functions)

Environmental (10 functions)

Machining & CNC (12 functions)

API Examples

OEE Calculation

NIOSH Lifting Equation

Dimensional Weight

Type Guards for Discriminated Unions

Available Type Guards

Error Handling

Tree Shaking

TypeScript Support

Browser Support

Contributing

License

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages