formulab 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +72 -5
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -3,6 +3,7 @@
3
3
  > Industrial & manufacturing calculation library for engineers
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/formulab.svg)](https://www.npmjs.com/package/formulab)
6
+ [![CI](https://github.com/iyulab/formulab/actions/workflows/ci.yml/badge.svg)](https://github.com/iyulab/formulab/actions/workflows/ci.yml)
6
7
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
8
  [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
8
9
 
@@ -15,8 +16,8 @@ A comprehensive collection of engineering formulas and calculations for manufact
15
16
  - **Zero dependencies** — Lightweight and fast
16
17
  - **TypeScript first** — Full type definitions included
17
18
  - **Tree-shakeable** — Import only what you need
18
- - **Well tested** — Comprehensive test coverage
19
- - **Research-based** — Built on industry standards (ISO, OSHA, NIOSH, IPC)
19
+ - **1,956 tests** — Coverage thresholds: 90% lines, 95% functions, 85% branches ([CI pipeline](https://github.com/iyulab/formulab/actions/workflows/ci.yml))
20
+ - **Research-based** — Golden reference tests verified against NIOSH 94-110, AIAG/ASTM E2587, JIPM, ASME B16.5, ISO 22514-2, and more
20
21
 
21
22
  ## Verification Status
22
23
 
@@ -40,6 +41,72 @@ A comprehensive collection of engineering formulas and calculations for manufact
40
41
  > Functions with golden reference tests have been verified against authoritative engineering sources.
41
42
  > See each function's JSDoc for specific references.
42
43
 
44
+ ## Numerical Accuracy & Testing
45
+
46
+ ### Floating-Point Handling
47
+
48
+ All calculations use a sign-aware `roundTo()` utility with epsilon correction to avoid IEEE 754 rounding artifacts:
49
+
50
+ ```typescript
51
+ roundTo(0.615, 2) // → 0.62 (not 0.61)
52
+ roundTo(-2.555, 2) // → -2.56 (sign-aware)
53
+ ```
54
+
55
+ Non-finite values (`NaN`, `Infinity`) pass through unchanged. Each function's JSDoc specifies output precision (typically 2-4 decimal places).
56
+
57
+ ### Golden Reference Tests
58
+
59
+ The following functions include tests verified against published reference values:
60
+
61
+ | Function | Standard / Source | What is verified |
62
+ |----------|-------------------|------------------|
63
+ | `nioshLifting()` | NIOSH Publication 94-110 | LC=23kg ideal, FM/CM table values, RWL calculation |
64
+ | `oee()` | JIPM TPM Handbook | World-class OEE (A≥90%, P≥95%, Q≥99.9%), perfect 100% |
65
+ | `cpk()` | ISO 22514-2 | Six Sigma Cpk=2.0, minimum capable Cpk≈1.33, off-center penalty |
66
+ | `controlChart()` | AIAG/ASTM E2587-16 | A2, D3, D4, d2 constants for n=2, 3, 5 |
67
+ | `cbm()` | Physical formula | 20ft container 33.2m³, 1m³ cube reference |
68
+ | `metalWeight()` | Machinery's Handbook | Steel plate density 7.85 g/cm³ |
69
+ | `flangeSpec()` | ASME B16.5 | Class 150/300/600 flange dimensions |
70
+ | `pipeSpec()` | ASME B36.10 | SCH40/80/160 wall thickness |
71
+ | `awgProperties()` | ANSI/AWG | AWG 0-40 diameter, resistance |
72
+
73
+ ### Edge Case Handling
74
+
75
+ Functions validate or handle these boundary conditions:
76
+
77
+ - **Division by zero**: `cpk()` with zero standard deviation, `oee()` with zero planned time
78
+ - **Out-of-range inputs**: `tolerance()` rejects invalid IT grades, `aql()` validates lot sizes
79
+ - **Physical impossibility**: `pressFit()` rejects negative interference, `nioshLifting()` clamps multipliers to [0, 1]
80
+ - **Extreme values**: `aql()` handles 1M-unit lots, `awgProperties()` covers AWG 0-40
81
+
82
+ ### Optimization Functions — Algorithms & Limitations
83
+
84
+ Three functions solve NP-hard combinatorial problems using **heuristic** algorithms. They provide good practical results but **do not guarantee optimal solutions**:
85
+
86
+ | Function | Algorithm | Complexity | Optimality |
87
+ |----------|-----------|-----------|-----------|
88
+ | `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 |
89
+ | `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) |
90
+ | `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 |
91
+
92
+ > 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.
93
+
94
+ ### CI Pipeline
95
+
96
+ GitHub Actions runs on every push to `main` and every pull request:
97
+
98
+ - **Matrix**: Node.js 18, 20
99
+ - **Steps**: `pnpm install` → `tsc` (type check) → `vitest run --coverage`
100
+ - **Coverage enforcement**: Fails if below thresholds (lines 90%, functions 95%, branches 85%, statements 90%)
101
+
102
+ ```bash
103
+ # Run tests locally
104
+ pnpm test
105
+
106
+ # Run with coverage report
107
+ pnpm test:coverage
108
+ ```
109
+
43
110
  ## Installation
44
111
 
45
112
  ```bash
@@ -129,7 +196,7 @@ import { metalWeight, bendAllowance, cutting, bearing } from 'formulab/metal';
129
196
  | `bearing()` | L10 bearing life calculation |
130
197
  | `bolt()` | Bolt torque and preload |
131
198
  | `cutting()` | Cutting speed, feed rate, RPM |
132
- | `cuttingStock()` | 1D cutting optimization |
199
+ | `cuttingStock()` | 1D cutting stock heuristic (FFD/BFD) |
133
200
  | `gear()` | Gear module calculation |
134
201
  | `hardness()` | Hardness conversion (HRC, HB, HV) |
135
202
  | `material()` | Material properties lookup |
@@ -238,13 +305,13 @@ import { cbm, eoq, safetyStock, kanban } from 'formulab/logistics';
238
305
  | `fillRate()` | Fill rate calculation |
239
306
  | `freightClass()` | NMFC freight class |
240
307
  | `kanban()` | Kanban quantity |
241
- | `pallet3d()` | 3D pallet optimization |
308
+ | `pallet3d()` | 3D pallet loading heuristic (BLF + FFD) |
242
309
  | `palletStack()` | Pallet stacking calculation |
243
310
  | `pickTime()` | Picking time estimation |
244
311
  | `safetyStock()` | Safety stock calculation |
245
312
  | `serviceLevel()` | Service level calculation |
246
313
  | `shipping()` | Shipping cost estimation |
247
- | `tsp()` | Traveling salesman problem |
314
+ | `tsp()` | TSP heuristic (NN + 2-Opt; exact for n ≤ 10) |
248
315
 
249
316
  ### Energy & Utilities (7 functions)
250
317
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "formulab",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "Manufacturing & Engineering calculation formulas library - 146 industrial calculations across 14 domains for OEE, Cpk, SPC, metal weight, CNC machining, GD&T, battery, environmental, pipe flow, logistics, and more",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",