formulab 0.37.0 → 0.37.1

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.37.1] - 2026-09-09
+
+### Fixed
+
+- **`quality/mtbf()`** — availability and the failure rate were derived from the rounded
+  MTBF and MTTR the function reports rather than from the times it was given. Rounding a
+  mean to two decimals and then dividing by it is not a rounding whisker: when short times
+  are spread over many failures the rounded mean is a large fraction of its own value. One
+  hour of operating time with half an hour of repair over 34 failures reported 75%
+  availability against a true 66.67%, and across a swept grid of plausible inputs a third
+  of the cases differed in the reported digits. Availability now reduces to the time-based
+  ratio of up time to total time (the failure count cancels), and the failure rate is taken
+  from the unrounded mean. The reported MTBF and MTTR are unchanged.
+- **`quality/mtbf()`** — `reliabilityAtMtbf` returned 0 instead of e^-1 when the mean time
+  between failures rounded down to 0.00, and `totalRepairTime` was not validated. Reliability
+  at T = MTBF is e^-1 for any positive MTBF, and a negative repair time now throws
+  `RangeError` like the other invalid inputs.
+
+- **`machining/cuspHeight()`** — returned `NaN` instead of rejecting impossible input. A
+  stepover wider than the tool diameter drove the square root negative, and non-positive
+  radii and stepovers were not checked at all, so a caller received a silent `NaN` and
+  rendered it. All three now throw `RangeError`. A stepover of exactly the tool diameter
+  stays valid: the passes just touch and the ridge is a full tool radius high.
+
+### Changed
+
+- **`quality/mtbf()`** — documented which defined term each output corresponds to, with an
+  `@reference` to EN 13306:2017 (maintenance terminology): 11.3 mean time between failures,
+  11.2 mean operating time between failures, 11.4 mean repair time, 9.18 time between
+  failures, 4.9 time based availability. The function had carried no citation since an
+  earlier, incorrect attribution was removed. Dividing operating time by the failure count
+  is strictly the mean *operating* time between failures (11.2); the name MTBF is kept
+  because that is what the figure is called in practice, and the distinction is now stated
+  rather than left implicit.
+
 ## [0.37.0] - 2026-09-07
 
 ### Added

package/dist/machining/cuspHeight.d.ts

@@ -10,6 +10,9 @@ import type { CuspHeightInput, CuspHeightResult } from './types.js';
  *
  * @param input - Cusp height parameters
  * @returns CuspHeightResult with scallop height and approximate Ra
+ * @throws RangeError if toolRadius or stepover is not positive, or if stepover exceeds the
+ *   tool diameter (adjacent passes never meet, so the formula has no scallop to describe —
+ *   without the guard the square root goes negative and the result is silently NaN)
  */
 export declare function cuspHeight(input: CuspHeightInput): CuspHeightResult;
 //# sourceMappingURL=cuspHeight.d.ts.map

package/dist/machining/cuspHeight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cuspHeight.d.ts","sourceRoot":"","sources":["../../src/machining/cuspHeight.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAUnE"}
+{"version":3,"file":"cuspHeight.d.ts","sourceRoot":"","sources":["../../src/machining/cuspHeight.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAoBnE"}

package/dist/machining/cuspHeight.js

@@ -10,9 +10,21 @@ import { roundTo } from '../utils.js';
  *
  * @param input - Cusp height parameters
  * @returns CuspHeightResult with scallop height and approximate Ra
+ * @throws RangeError if toolRadius or stepover is not positive, or if stepover exceeds the
+ *   tool diameter (adjacent passes never meet, so the formula has no scallop to describe —
+ *   without the guard the square root goes negative and the result is silently NaN)
  */
 export function cuspHeight(input) {
     const { toolRadius, stepover } = input;
+    if (!(toolRadius > 0)) {
+        throw new RangeError('toolRadius must be greater than 0');
+    }
+    if (!(stepover > 0)) {
+        throw new RangeError('stepover must be greater than 0');
+    }
+    if (stepover > 2 * toolRadius) {
+        throw new RangeError('stepover must not exceed the tool diameter (2 x toolRadius)');
+    }
     const halfStep = stepover / 2;
     const h = toolRadius - Math.sqrt(toolRadius * toolRadius - halfStep * halfStep);
     return {

package/dist/machining/cuspHeight.js.map

@@ -1 +1 @@
-{"version":3,"file":"cuspHeight.js","sourceRoot":"","sources":["../../src/machining/cuspHeight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAEvC,MAAM,QAAQ,GAAG,QAAQ,GAAG,CAAC,CAAC;IAC9B,MAAM,CAAC,GAAG,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC,CAAC;IAEhF,OAAO;QACL,UAAU,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;QACzB,gBAAgB,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,iCAAiC;KAChF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"cuspHeight.js","sourceRoot":"","sources":["../../src/machining/cuspHeight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAEvC,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,UAAU,CAAC,mCAAmC,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,UAAU,CAAC,iCAAiC,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,QAAQ,GAAG,CAAC,GAAG,UAAU,EAAE,CAAC;QAC9B,MAAM,IAAI,UAAU,CAAC,6DAA6D,CAAC,CAAC;IACtF,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,GAAG,CAAC,CAAC;IAC9B,MAAM,CAAC,GAAG,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC,CAAC;IAEhF,OAAO;QACL,UAAU,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;QACzB,gBAAgB,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,iCAAiC;KAChF,CAAC;AACJ,CAAC"}

package/dist/quality/mtbf.d.ts

@@ -6,6 +6,26 @@ import type { MtbfInput, MtbfResult } from './types.js';
  * MTTR = Total Repair Time / Number of Failures
  * Availability = MTBF / (MTBF + MTTR)
  *
+ * Each output maps to a defined term:
+ *   - `mtbf` — "average of the times between failures" (EN 13306:2017, 11.3). Note that a
+ *     time between failures (9.18) is the duration between consecutive failures and "may
+ *     include non-operating time after restoration"; when the input is operating time, as
+ *     here, the quantity computed is strictly the mean operating time between failures
+ *     (MOTBF, 11.2 — "average of the operating times between failures", applied to
+ *     repairable items). Industry practice calls this figure MTBF, and the name is kept for
+ *     that reason.
+ *   - `mttr` — mean repair time (MRT, 11.4: "average of the repair times"). MTTR is the
+ *     common industry spelling of the same average.
+ *   - `availability` — the time-based availability ratio of 4.9: up time over total time
+ *     (UT / (UT + DT)), expressed as a percentage.
+ *   - `failureRate`, `reliabilityAtMtbf` — the constant-failure-rate (exponential) model,
+ *     lambda = 1 / MTBF and R(t) = exp(-lambda·t). Not part of the terminology standard;
+ *     it holds only during a constant failure period, and R(MTBF) = e^-1 always.
+ *
+ * @reference EN 13306:2017 — Maintenance terminology. 11.3 (mean time between failures),
+ *   11.2 (mean operating time between failures), 11.4 (mean repair time), 9.18 (time
+ *   between failures), 4.9 (time based availability).
+ *
  * @param input - MTBF input parameters
  * @returns MTBF analysis result
  * @throws RangeError if totalOperatingTime is not positive, or if

package/dist/quality/mtbf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mtbf.d.ts","sourceRoot":"","sources":["../../src/quality/mtbf.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAoCjD"}
+{"version":3,"file":"mtbf.d.ts","sourceRoot":"","sources":["../../src/quality/mtbf.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CA8CjD"}

package/dist/quality/mtbf.js

@@ -6,6 +6,26 @@ import { roundTo } from '../utils.js';
  * MTTR = Total Repair Time / Number of Failures
  * Availability = MTBF / (MTBF + MTTR)
  *
+ * Each output maps to a defined term:
+ *   - `mtbf` — "average of the times between failures" (EN 13306:2017, 11.3). Note that a
+ *     time between failures (9.18) is the duration between consecutive failures and "may
+ *     include non-operating time after restoration"; when the input is operating time, as
+ *     here, the quantity computed is strictly the mean operating time between failures
+ *     (MOTBF, 11.2 — "average of the operating times between failures", applied to
+ *     repairable items). Industry practice calls this figure MTBF, and the name is kept for
+ *     that reason.
+ *   - `mttr` — mean repair time (MRT, 11.4: "average of the repair times"). MTTR is the
+ *     common industry spelling of the same average.
+ *   - `availability` — the time-based availability ratio of 4.9: up time over total time
+ *     (UT / (UT + DT)), expressed as a percentage.
+ *   - `failureRate`, `reliabilityAtMtbf` — the constant-failure-rate (exponential) model,
+ *     lambda = 1 / MTBF and R(t) = exp(-lambda·t). Not part of the terminology standard;
+ *     it holds only during a constant failure period, and R(MTBF) = e^-1 always.
+ *
+ * @reference EN 13306:2017 — Maintenance terminology. 11.3 (mean time between failures),
+ *   11.2 (mean operating time between failures), 11.4 (mean repair time), 9.18 (time
+ *   between failures), 4.9 (time based availability).
+ *
  * @param input - MTBF input parameters
  * @returns MTBF analysis result
  * @throws RangeError if totalOperatingTime is not positive, or if
@@ -20,19 +40,28 @@ export function mtbf(input) {
     if (numberOfFailures <= 0) {
         throw new RangeError('numberOfFailures must be greater than 0');
     }
+    if (totalRepairTime < 0) {
+        throw new RangeError('totalRepairTime must not be negative');
+    }
+    // Every derived figure below is computed from the raw times, never from the rounded
+    // values reported back. Rounding an intermediate to 2 decimals and then dividing by it
+    // is not a rounding whisker: with short times spread over many failures the rounded
+    // mean is a large fraction of its own value, and availability drifts by whole points
+    // (1 h operating / 0.5 h repair / 34 failures reads 75% that way, against a true 66.67%).
+    const mtbfExact = totalOperatingTime / numberOfFailures;
+    const mttrExact = totalRepairTime / numberOfFailures;
     // MTBF = Total Operating Time / Number of Failures
-    const mtbfValue = roundTo(totalOperatingTime / numberOfFailures, 2);
+    const mtbfValue = roundTo(mtbfExact, 2);
     // MTTR = Total Repair Time / Number of Failures
-    const mttr = numberOfFailures > 0 ? roundTo(totalRepairTime / numberOfFailures, 2) : 0;
-    // Availability = MTBF / (MTBF + MTTR)
-    const availability = mtbfValue + mttr > 0
-        ? roundTo((mtbfValue / (mtbfValue + mttr)) * 100, 2)
-        : 0;
+    const mttr = roundTo(mttrExact, 2);
+    // Availability = MTBF / (MTBF + MTTR). The failure count cancels, leaving the 4.9
+    // time-based ratio of up time to total time.
+    const availability = roundTo((totalOperatingTime / (totalOperatingTime + totalRepairTime)) * 100, 2);
     // Failure rate (lambda) = 1 / MTBF
-    const failureRate = mtbfValue > 0 ? roundTo(1 / mtbfValue, 6) : 0;
+    const failureRate = roundTo(1 / mtbfExact, 6);
     // Reliability at time T = e^(-lambda * T), where T = MTBF
-    // R(MTBF) = e^(-1) = 0.3679 = 36.79%
-    const reliabilityAtMtbf = mtbfValue > 0 ? roundTo(Math.exp(-1) * 100, 2) : 0;
+    // R(MTBF) = e^(-1) = 0.3679 = 36.79%, whatever the MTBF is
+    const reliabilityAtMtbf = roundTo(Math.exp(-1) * 100, 2);
     return {
         mtbf: mtbfValue,
         mttr,

package/dist/quality/mtbf.js.map

@@ -1 +1 @@
-{"version":3,"file":"mtbf.js","sourceRoot":"","sources":["../../src/quality/mtbf.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,IAAI,CAAC,KAAgB;IACnC,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAE,GAAG,KAAK,CAAC;IAExE,kBAAkB;IAClB,IAAI,kBAAkB,IAAI,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,UAAU,CAAC,2CAA2C,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,gBAAgB,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,UAAU,CAAC,yCAAyC,CAAC,CAAC;IAClE,CAAC;IAED,mDAAmD;IACnD,MAAM,SAAS,GAAG,OAAO,CAAC,kBAAkB,GAAG,gBAAgB,EAAE,CAAC,CAAC,CAAC;IAEpE,gDAAgD;IAChD,MAAM,IAAI,GAAG,gBAAgB,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,GAAG,gBAAgB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEvF,sCAAsC;IACtC,MAAM,YAAY,GAAG,SAAS,GAAG,IAAI,GAAG,CAAC;QACvC,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QACpD,CAAC,CAAC,CAAC,CAAC;IAEN,mCAAmC;IACnC,MAAM,WAAW,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAElE,0DAA0D;IAC1D,qCAAqC;IACrC,MAAM,iBAAiB,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7E,OAAO;QACL,IAAI,EAAE,SAAS;QACf,IAAI;QACJ,YAAY;QACZ,WAAW;QACX,iBAAiB;KAClB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"mtbf.js","sourceRoot":"","sources":["../../src/quality/mtbf.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,IAAI,CAAC,KAAgB;IACnC,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAE,GAAG,KAAK,CAAC;IAExE,kBAAkB;IAClB,IAAI,kBAAkB,IAAI,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,UAAU,CAAC,2CAA2C,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,gBAAgB,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,UAAU,CAAC,yCAAyC,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,eAAe,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC,sCAAsC,CAAC,CAAC;IAC/D,CAAC;IAED,oFAAoF;IACpF,uFAAuF;IACvF,oFAAoF;IACpF,qFAAqF;IACrF,0FAA0F;IAC1F,MAAM,SAAS,GAAG,kBAAkB,GAAG,gBAAgB,CAAC;IACxD,MAAM,SAAS,GAAG,eAAe,GAAG,gBAAgB,CAAC;IAErD,mDAAmD;IACnD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAExC,gDAAgD;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAEnC,kFAAkF;IAClF,6CAA6C;IAC7C,MAAM,YAAY,GAAG,OAAO,CAAC,CAAC,kBAAkB,GAAG,CAAC,kBAAkB,GAAG,eAAe,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;IAErG,mCAAmC;IACnC,MAAM,WAAW,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC,CAAC,CAAC;IAE9C,0DAA0D;IAC1D,2DAA2D;IAC3D,MAAM,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;IAEzD,OAAO;QACL,IAAI,EAAE,SAAS;QACf,IAAI;QACJ,YAAY;QACZ,WAAW;QACX,iBAAiB;KAClB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formulab",
-  "version": "0.37.0",
+  "version": "0.37.1",
   "description": "Manufacturing & Engineering calculation formulas library - 203 industrial calculations across 15 domains for OEE, Cpk, SPC, FMEA, Nelson Rules, metal weight, CNC machining, GD&T, battery, environmental, pipe flow, logistics, IE time study, and more",
   "type": "module",
   "main": "./dist/index.js",