mechanical-tolerance-calculator 1.1.5 → 1.1.7

package/README.md

@@ -22,132 +22,205 @@ const { getAllTolerancesFor } = require("mechanical-tolerance-calculator");
 // ES module
 // import { getAllTolerancesFor } from "mechanical-tolerance-calculator";
 
-// Example: Housing Bore Toelrances
+// Example: Housing Bore Tolerances
 const housingTolerances = getAllTolerancesFor("housing");
 console.log(housingTolerances["housingBoresTolerances"]);
+
+// Example: Checking Shaft Toleranace for a Measurement
+const result = checkOneMeasurementFor('shaft', 179.91); 
+console.log(result);
+
+// Exmaple: Checking Housing Specification Tolerance for a Collection of Measurements
+const result = checkMultipleMeasurementsFor('housing', [240.05, 240.07, 240.09, 240.05, 240.06, 240.02, 240.09]); 
+console.log(result);
+
 ```
+# API Documentation
+
+This section documents the exported public methods of the **Mechanical Tolerance Calculator** library.
 
 ---
 
-## API EXACPLES
-
-### `getAllTolerancesFor(materialType: String)`
-
-**Parameters**
-
-- `materialType` (`string`) — Type of material to check tolerances for (e.g. `"housing"`, `"shaft"`, `"shell"`).
-
-**Returns**
-
-An object with the following shape (example):
-
-```json
-{
-  "type": "housing bore" | "shaft" | "shell bore",
-  "specifications": {
-     "H6": [
-      {
-        "minimum_diameter": 0,
-        "maximum_diameter": 3,
-        "upper_deviation": 0.006,
-        "lower_deviation": 0,
-        "IT6": 0.006,
-        "IT5": 0.004
-      },
-      {
-        "minimum_diameter": 3,
-        "maximum_diameter": 6,
-        "upper_deviation": 0.008,
-        "lower_deviation": 0,
-        "IT6": 0.008,
-        "IT5": 0.005
-      }
-     ],
-
-     "H7": [
-      {
-        "minimum_diameter": 0,
-        "maximum_diameter": 3,
-        "upper_deviation": 0.01,
-        "lower_deviation": 0,
-        "IT7": 0.01,
-        "IT6": 0.006,
-        "IT5": 0.004
-      },
-      {
-        "minimum_diameter": 3,
-        "maximum_diameter": 6,
-        "upper_deviation": 0.012,
-        "lower_deviation": 0,
-        "IT7": 0.012,
-        "IT6": 0.008,
-        "IT5": 0.005
-      },
-     ]
-  }
-}
+## getAllTolerancesFor(materialType: String)
+
+Returns all available ISO/ANSI tolerance specifications for a given material type.
+
+### Description
+Determines the material category from the provided string and returns the full set of tolerance specifications associated with that category.  
+Supported material types include **housing**, **shaft**, and **shell** (case-insensitive and partial matches allowed, e.g. `"housing bore"`).
+
+### Parameters
+- **materialType** (`string`)  
+  The type of material to retrieve tolerances for.  
+  Valid values (or substrings):
+  - `"housing"`
+  - `"shaft"`
+  - `"shell"`
+
+### Returns
+- **object**
+
+  **On success**
+  ```json
+  {
+    "type": "housingBores" | "shafts" | "shellBores",
+    "specifications": {
+      "H6": [ { ... } ],
+      "H7": [ { ... } ],
+      "...": [ { ... } ]
+    }
+  } ```
+
+ -  **On failure**
+    ```json
+    {
+      "error": "Unknown material type: <value>. Valid types are 'housing', 'shaft', or 'shell'."
+    }
+    ```
+
+### Example
+```js
+const { getAllTolerancesFor } = require("mechanical-tolerance-calculator");
+
+const tolerances = getAllTolerancesFor("housing");
+console.log(tolerances.specifications.H7);
 ```
 
-- `type`: `"housing bore"` or `"shaft"` or `"shell bore"` inferred from the materialType parameter.
-- `specifications`: ISO or ANSI fit/tolerance designation associated with the entry (e.g., H7, h6, etc.).
+## checkOneMeasurementFor(materialType: String, measurement: Number)
+
+Checks whether a single measurement complies with the WA standard tolerance and IT grade for the given material type.
+
+### Description
+- Uses WA standard specifications:
+  - Housing → H8 / IT6
+  - Shell → H9 / IT6
+  - Shaft → h9 / IT5
+- Infers the nominal size from the measurement.
+- Calculates upper and lower bounds.
+- Evaluates whether the measurement meets specification and IT tolerance.
+
+### Parameters
+- **materialType** (`string`)  
+  The type of material to check tolerance and specification for.  
+  Valid values (or substrings):
+  - `"housing"`
+  - `"shaft"`
+  - `"shell"`
+- **measurement** (`number`)  
+  The measured diameter (must be between 0 and 1000).
+
+### Returns
+- **object**
+
+  **On success**
+  ```json
+  {
+    "measurement": 24.982,
+    "nominal": 25,
+    "specification": "h9",
+    "IT_grade": "IT5",
+    "computed_specification_bounds": {
+      "upperBound": "25.000",
+      "lowerBound": "24.970"
+    },
+    "uncomputed_specification_bounds": {
+      "upperBound": "25.000 + 0.000",
+      "lowerBound": "25.000 - 0.030"
+    },
+    "matched_spec": { ... },
+    "meets_specification": {
+      "meetsSpec": true,
+      "reason": "24.982 falls between 24.970 and 25.000",
+      "concludedReason": "shaft is in acceptable size."
+    },
+    "meets_IT_tolerance": true
+  }
+  ```
 
-- `maximum_diameter`: The upper bound of the nominal diameter range (in millimetres) for which the tolerance values apply.
-- `minimum_diameter`: The upper bound of the nominal diameter range (in millimetres) for which the tolerance values apply.
-- `upper_deviation` / `lower_deviation`: The positive / negative deviation limit from the basic size (in millimetres).
-- `IT5` / `IT6` / `IT8`, etc: International Tolerance (IT) grades defining standard tolerance magnitudes for each grade level.
+ -  **On failure**
+    ```json
+    {
+      "error": "Measurement must be between 0 to 1000."
+    }
+    ```
 
----
+### Example
+```js
+const { checkOneMeasurementFor } = require("mechanical-tolerance-calculator");
 
-## Example Output
-
-```json
-{
-  "type": "housing bore",
-  "specifications": {
-    "H6": [
-      {
-        "minimum_diameter": 0,
-        "maximum_diameter": 3,
-        "upper_deviation": 0.006,
-        "lower_deviation": 0,
-        "IT6": 0.006,
-        "IT5": 0.004
-      },
-      {
-        "minimum_diameter": 3,
-        "maximum_diameter": 6,
-        "upper_deviation": 0.008,
-        "lower_deviation": 0,
-        "IT6": 0.008,
-        "IT5": 0.005
-      }
-    ],
-
-    "H7": [
-      {
-        "minimum_diameter": 0,
-        "maximum_diameter": 3,
-        "upper_deviation": 0.01,
-        "lower_deviation": 0,
-        "IT7": 0.01,
-        "IT6": 0.006,
-        "IT5": 0.004
-      },
-      {
-        "minimum_diameter": 3,
-        "maximum_diameter": 6,
-        "upper_deviation": 0.012,
-        "lower_deviation": 0,
-        "IT7": 0.012,
-        "IT6": 0.008,
-        "IT5": 0.005
-      }
-    ]
-  }
-}
+const result = checkOneMeasurementFor("shaft", 179.91);
+console.log(result.meets_IT_tolerance);
 ```
 
----
+## checkMultipleMeasurementsFor(materialType: String, measurements: Numbers[])
+
+Evaluates multiple measurements against WA standard tolerances and IT limits as a group.
+
+### Description
+- Validates all measurements.
+- Computes:
+  - Nominal size distribution
+  - Maximum and minimum measurements
+  - IT difference (max − min)
+- Determines:
+  - Whether all measurements meet specification
+  - Whether the IT tolerance band is satisfied
+  - Overall compliance status
+
+### Parameters
+- **materialType** (`string`)  
+  The type of material to check tolerance and specification for.  
+  Valid values (or substrings):
+  - `"housing"`
+  - `"shaft"`
+  - `"shell"`
+- **measurement** (`number[]`)  
+  An array of measured diameters (each between 0 and 1000).
+
+### Returns
+- **object**
+
+  **On success**
+  ```json
+  {
+    "measurement": [24.982, 24.990, 24.975],
+    "nominal": 25,
+    "specification": "h9",
+    "IT_grade": "IT5",
+    "computed_specification_bounds": {
+      "upperBound": "25.000",
+      "lowerBound": "24.970"
+    },
+    "matched_spec": { ... },
+    "meets_specification": {
+      "meetsSpec": true,
+      "reason": "24.990 falls between 24.970 and 25.000"
+    },
+    "meets_IT_Tolerance": {
+      "meetsIT": true,
+      "reason": "The difference between 24.990 and 24.975 is less than or equal to 0.021."
+    },
+    "meets_final_compliance": true
+  }
+  ```
+
+ -  **On Validation Error**
+    ```json
+    {
+      "error": "Some measurements are invalid.",
+      "details": [
+        { "index": 1, "value": -5, "error": "Invalid measurement: must be 0–1000" }
+      ]
+    }
+    ```
+
+### Example
+```js
+const { checkMultipleMeasurementsFor } = require("mechanical-tolerance-calculator");
+
+const result = checkMultipleMeasurementsFor('housing', [240.05, 240.07, 240.09, 240.05, 240.06, 240.02, 240.09]); 
+console.log(result.meets_final_compliance);
+```
 
 ## Features
 

package/index.js

@@ -80,7 +80,7 @@ function returnTolerancesFor(executableMaterialType, spec = "") {
     if (!Object.keys(allTolerances).includes(spec)) {
       return {
         error: `Currently available specifications are ${Object.keys(
-          allTolerances
+          allTolerances,
         )}`,
       };
     }
@@ -97,14 +97,14 @@ function returnTolerancesFor(executableMaterialType, spec = "") {
 }
 
 function isValidMeasurement(measurement) {
-  const num = Number(measurement);
+  const num = parseFloat(measurement);
   return !isNaN(num) && num >= 0 && num < 1000;
 }
 
 function parseNominalFromMeasurement(
   measurement,
   materialType,
-  THRESHOLD = 0.9
+  THRESHOLD = 0.9,
 ) {
   if (!isValidMeasurement(measurement)) {
     return { error: "Measurement must be between 0 to 1000." };
@@ -208,7 +208,7 @@ function processMeasurement(materialType, measurement, tolerances) {
   const matchedSpec = findMatchingSpec(
     nominal,
     tolerances.specification,
-    config.rangeMatch
+    config.rangeMatch,
   );
 
   if (!matchedSpec) {
@@ -230,16 +230,16 @@ function processMeasurement(materialType, measurement, tolerances) {
     meetsSpec,
     measurement,
     computedBounds.lowerBound,
-    computedBounds.upperBound
+    computedBounds.upperBound,
   );
 
   const outcome =
     measurement > computedBounds.upperBound
       ? `${materialType} is over-sized.`
       : measurement >= computedBounds.lowerBound &&
-        measurement <= computedBounds.upperBound
-      ? `${materialType} is in acceptable size.`
-      : `${materialType} is under-sized.`;
+          measurement <= computedBounds.upperBound
+        ? `${materialType} is in acceptable size.`
+        : `${materialType} is under-sized.`;
 
   return {
     measurement: parseStringFloat(measurement),
@@ -265,7 +265,7 @@ function processOneMeasurement(materialType, measurement, tolerances) {
   const processedMeasurement = processMeasurement(
     materialType,
     measurement,
-    tolerances
+    tolerances,
   );
   return {
     ...processedMeasurement,
@@ -293,7 +293,7 @@ function checkOneMeasurementFor(materialType, measurement) {
   return processOneMeasurement(
     camcoStandardTolerances.type,
     measurement,
-    camcoStandardTolerances
+    camcoStandardTolerances,
   );
 }
 
@@ -357,7 +357,7 @@ function processIndividualMeasurement(materialType, measurement, tolerances) {
   const processedMeasurement = processMeasurement(
     materialType,
     measurement,
-    tolerances
+    tolerances,
   );
   return processedMeasurement;
 }
@@ -389,7 +389,7 @@ function checkMultipleMeasurementsFor(materialType, measurements) {
   let largestMeasurement = Math.max(...measurements);
   let smallestMeasurement = Math.min(...measurements);
   let ITDifference = parseToFixedThreeString(
-    largestMeasurement - smallestMeasurement
+    largestMeasurement - smallestMeasurement,
   );
 
   let mostFarMeasurement = largestMeasurement;
@@ -400,10 +400,13 @@ function checkMultipleMeasurementsFor(materialType, measurements) {
     const result = processIndividualMeasurement(
       camcoStandardTolerances.type,
       measurement,
-      camcoStandardTolerances
+      camcoStandardTolerances,
     );
     withInSpecs.push(result.meets_specification.meetsSpec);
-    nominals[result.nominal] = count++;
+    const nominal = result.nominal;
+
+    // count occurrences
+    nominals[nominal] = (nominals[nominal] || 0) + 1;
 
     if (
       Math.abs(result.nominal - result.measurement) >
@@ -414,15 +417,17 @@ function checkMultipleMeasurementsFor(materialType, measurements) {
 
     return result;
   });
+  console.log("nominals: " + JSON.stringify(nominals));
+  console.log("within spec: " + withInSpecs);
 
   let countOfMostOccuredNominal = Math.max(...Object.values(nominals));
 
   let mostOccuredNominal = Object.keys(nominals).find(
-    (nominal) => nominals[nominal] === countOfMostOccuredNominal
+    (nominal) => nominals[nominal] === countOfMostOccuredNominal,
   );
 
   const baseSpec = results.find(
-    (result) => result.nominal === parseInt(mostOccuredNominal)
+    (result) => result.nominal === parseInt(mostOccuredNominal),
   );
   const baseITValue = baseSpec.matched_spec[baseSpec.IT_grade];
 
@@ -431,7 +436,7 @@ function checkMultipleMeasurementsFor(materialType, measurements) {
     meetsIT,
     largestMeasurement,
     smallestMeasurement,
-    baseITValue
+    baseITValue,
   );
 
   const meetsSpec = withInSpecs.every((v) => v === true);
@@ -439,7 +444,7 @@ function checkMultipleMeasurementsFor(materialType, measurements) {
     meetsSpec,
     mostFarMeasurement,
     baseSpec.computed_specification_bounds.lowerBound,
-    baseSpec.computed_specification_bounds.upperBound
+    baseSpec.computed_specification_bounds.upperBound,
   );
 
   const isOverSized =
@@ -451,44 +456,44 @@ function checkMultipleMeasurementsFor(materialType, measurements) {
     (isWithinSizeRange
       ? `${materialType} is acceptable in size`
       : isOverSized
-      ? `${materialType} is over-sized`
-      : `${materialType} is under-sized`) +
+        ? `${materialType} is over-sized`
+        : `${materialType} is under-sized`) +
     (isWithinSizeRange && meetsIT
       ? `, and `
       : !meetsIT && isWithinSizeRange
-      ? `, but `
-      : `, and `) +
+        ? `, but `
+        : `, and `) +
     (meetsIT ? `meets IT tolerance.` : `doesn't meet IT tolerance.`);
   return {
     ...baseSpec,
     measurement: measurements,
     meets_specification: { meetsSpec, reason: specMeetingReason },
     meets_IT_Tolerance: { meetsIT, reason: itMeetingReason },
-    meets_final_compliance: meetsIT && baseSpec?.meets_specification?.meetsSpec,
+    meets_final_compliance: meetsIT === true && meetsSpec === true,
   };
 }
 
 function generateReasonForSpecs(spec, measurement, base1, base2) {
   if (spec === true) {
     return `${parseToFixedThreeString(
-      measurement
+      measurement,
     )} falls between ${base1} and ${base2}`;
   }
   return `${parseToFixedThreeString(
-    measurement
+    measurement,
   )} doesn't fall between ${base1} and ${base2}`;
 }
 
 function generateReasonForTolerances(spec, measurement1, measurement2, base) {
   if (spec === true) {
     return `The difference between ${parseToFixedThreeString(
-      measurement1
+      measurement1,
     )} and ${parseToFixedThreeString(
-      measurement2
+      measurement2,
     )} is less than or equal to ${base}.`;
   }
   return `The difference between ${parseToFixedThreeString(
-    measurement1
+    measurement1,
   )} and ${parseToFixedThreeString(measurement2)} is greater than ${base}.`;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mechanical-tolerance-calculator",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Calculates international standard specification and  tolerances for bores, round bars and metals of mechanical units. For examples; H7, H8, H9, h8, h9 specifications and IT5/IT6 tolerances.",
   "main": "index.js",
   "scripts": {

package/test.js

@@ -0,0 +1,6 @@
+const { checkMultipleMeasurementsFor } = require("./index");
+console.log(checkMultipleMeasurementsFor("housing", [100.04, 100.05]));
+console.log(checkMultipleMeasurementsFor("housing", [100.04, 100.05, 95.06]));
+console.log(
+  checkMultipleMeasurementsFor("housing", [100.04, 100.05, 95.06, 80.09]),
+);