@lhncbc/ucum-lhc 7.1.6 → 7.1.9

package/README.md

@@ -1,75 +1,66 @@
 # ucum-lhc
-This is the LHC implementation of validation and conversion services based on
+This package provides APIs for validation and conversion of unit strings in
 the [Unified Code for Units of Measure](https://ucum.org) (UCUM) code
-system created by the Regenstrief Institute, Inc.  
+system created by the Regenstrief Institute, Inc.  ucum-lhc was created by the
+Lister Hill Center (LHC) at the U.S. National Library of Medicine.
 
 See our [overview page](https://ucum.nlm.nih.gov/ucum-lhc) for
 general information.
 
-This is a work in progress so more capabilities will probably be introduced.
+In addition to using this package from a JavaScript program, there is also a [web
+API service](https://ucum.nlm.nih.gov/ucum-service.html) which uses this library, so
+you can send HTTPS requests to validate and convert units if that is more
+convenient.
 
 ## Check out the Demo page
 
-We have a [demo page](https://ucum.nlm.nih.gov/ucum-lhc/demo.html) that 
+We have a [demo page](https://ucum.nlm.nih.gov/ucum-lhc/demo.html) that
 shows various capabilities.  That includes the validation and conversion
 functions described below.  You might want to try that out first.
 
 ## Get the code
 
-The ucum-lhc code is written as ES6 modules, but the npm package (see below)
-also contains CommonJS modules, as well as a "browser-dist" directory with files
-ready to use in a web browser.
-
-Currently we have code to serve multiple purposes.  The core code supports
-the validation and conversion of UCUM unit expressions as well as a function
-to search for commensurable units for a specified unit expression.  Other code is 
-concerned with importing and exporting the UCUM data, and in supporting the
-demo page (noted above).  If you are looking to include the ucum-lhc core code 
-in your application, download the code as an [npm](https://www.npmjs.com) package.
-
-### Getting the code as an npm package
-
-You can use the [npm](https://www.npmjs.com) package manager 
-to install the ucum-lhc npm package.  (npm is 
-[automatically installed](https://www.npmjs.com/get-npm) with Node.js.)
+You can use the [npm](https://www.npmjs.com) package manager
+to install the ucum-lhc npm package.  (npm is automatically installed with Node.js.)
 
     npm install @lhncbc/ucum-lhc --save
 
-This will install the @lhncbc/ucum-lhc directory in your node_modules diretory. 
-The browser-dist subdirectory will contain ucum-lhc.min.js for use directly in a
-browser.
+This will install the @lhncbc/ucum-lhc directory in your node_modules directory.
+If you are not building the code along with an app, you can use the
+browser-dist/ucum-lhc.min.js file which is already built for use directly in a
+browser without building.
 
-## Using the code 
+The ucum-lhc code is written as ES6 modules, but the npm package
+also contains CommonJS modules, which are used by default if you "require" or
+"import" the package.
 
-The ucum-lhc.min.js file includes the source code you need for the validation,
-conversion and commensurable units functions as well as the ucum code
-definitions file.  We assume that your main motivation for including the
-ucum-lhc code is to have those capabilities for units of measure on your system.  
+
+## Using the code
 
 ### Server side
-To access those capabilities from your server side code (or from client side
-code that goes through a build system), require the npm package
-and create a UcumLhcUtils object that contains those functions.
+Require (or import) the npm package and create a UcumLhcUtils object that
+contains those functions.
 
     const ucum = require('@lhncbc/ucum-lhc');
     const utils = ucum.UcumLhcUtils.getInstance();
 
- 
+See the API reference section below for the APIs on the utils object.
+
 ### Client side
 
-To access those capabilities from your client side code, include the 
-ucum-lhc.min.js package in your html file.  
+To access those capabilities from your client side code without building, include the
+pre-built ucum-lhc.min.js file in your HTML file.
 
     <script src="path-to-installed-package/browser-dist/ucum-lhc.min.js"></script>
 
-The validation, conversion and commensurable units functions are available from 
-the _ucumPkg.UcumLhcUtils_ class.  In your client side javascript code access 
-those functions via the ucumPkg object.  For example, 
+The validation, conversion and commensurable units functions are available from
+the _ucumPkg.UcumLhcUtils_ class.  In your client side JavaScript code access
+those functions via the ucumPkg object.  For example,
 
     var parseResp = ucumPkg.UcumLhcUtils.getInstance().validateUnitString(uStr, true);
-        
-### Function descriptions
-        
+
+### API reference
+
 Below is documentation for the public functions on the UcumLhcUtils instance.
 *  [validateUnitString](#validateunitstringustr-suggest)
 *  [convertUnitTo](#convertunittofromunitcode-fromval-tounitcode-options)
@@ -79,8 +70,8 @@ Below is documentation for the public functions on the UcumLhcUtils instance.
 
 #### validateUnitString(uStr, suggest)
 
-This method validates a unit string.  It first checks to see if the string passed 
-in is a unit code that is found in the unit codes table. If it is not found it 
+This method validates a unit string.  It first checks to see if the string passed
+in is a unit code that is found in the unit codes table. If it is not found it
 parses the string to see if it resolves to a valid unit string.
 
 If a valid unit cannot be found, the string is tested for some common errors,
@@ -107,17 +98,18 @@ unit names and synonyms.
         occurred);
    * 'ucumCode' the valid ucum code, which may differ from what was passed
         in (e.g., if 'Gauss' is passed in, this will contain 'G') OR null if
-        the string was flagged as invalid or an error occurred; 
+        the string was flagged as invalid or an error occurred;
    * 'msg' is an array of messages, if the string is invalid or an
         error occurred, indicating the problem, or an explanation of a
         substitution such as the substitution of 'G' for 'Gauss', or
-        an empty array if no messages were generated ;
-   * 'unit' which is null if no unit is found, or a hash for a unit found:
+        an empty array if no messages were generated;
+   * 'unit' which is null if no unit is found, or an object representing the found unit:
      * 'code' is the unit's ucum code (G in the above example);
      * 'name' is the unit's name (Gauss in the above example); and
      * 'guidance' is the unit's guidance/description data.
    * 'suggestions' if suggestions were requested and found, this is an array
-         of one or more hash objects.  Each hash contains three elements:
+         of one or more objects.  (Otherwise, it will not be present.)
+         Each object contains three elements:
      * 'msg' which is a message indicating what part of the uStr input
          parameter the suggestions are for;
      * 'invalidUnit' which is the unit expression the suggestions are
@@ -125,27 +117,25 @@ unit names and synonyms.
      * 'units' which is an array of data for each suggested unit found.
           Each array will contain the unit code, the unit name and the
           unit guidance (if any).
-        If no suggestions were requested and found, this property is not
-        returned.
 
 For example, to validate a unit string of m2/g4 (assuming you have created a
 utils object as described above):
 
      var returnObj = utils.validateUnitString('m2/g4');
-     if (returnObj['status'] === 'valid')
-       /* the string is valid; returnObj['ucumCode'] will contain the valid 
-          ucum code (may differ from what was entered), returnObj['msg'] may 
+     if (returnObj.status === 'valid')
+       /* the string is valid; returnObj.ucumCode will contain the valid
+          ucum code (may differ from what was entered), returnObj.msg may
           contain a message or messages describing substitution(s) for the
-          code entered, and retObj['unit'] will contain 3 pieces of data for the 
-          unit - code, name and guidance (provides information about the unit, 
+          code entered, and returnObj.unit will contain 3 pieces of data for the
+          unit - code, name and guidance (provides information about the unit,
           such as how the unit is used, etc.)*/
      else
-       /* returnObj['status'] will be 'invalid' and */
-       /* returnOb['msg'] will have a message describing the problem */
-       
-For information on unit string formatting, look at the _Ucum Unit Expression 
-Validation_ section on the [demo page](https://ucum.nlm.nih.gov/ucum-lhc/demo.html).  
-There is a button labeled "Show entry hints".  That will give you a short description 
+       /* returnObj.status will be 'invalid' and */
+       /* returnObj.msg will have a message describing the problem */
+
+For information on unit string formatting, look at the _Ucum Unit Expression
+Validation_ section on the [demo page](https://ucum.nlm.nih.gov/ucum-lhc/demo.html).
+There is a button labeled "Show entry hints".  That will give you a short description
 of unit strings, and includes a link to the [UCUM Specification](https://ucum.org/ucum).
 
 #### convertUnitTo(fromUnitCode, fromVal, toUnitCode, options)
@@ -160,9 +150,9 @@ using them in actual clinical settings.
 **Parameters**:
 1) fromUnitCode: the unit code/expression/string of the unit to be converted;
 2) fromVal: the number of "from" units to be converted to "to" units;
-3) toUnitCode: the unit code/expression/string of the unit that the from 
+3) toUnitCode: the unit code/expression/string of the unit that the from
   field is to be converted to;
-4) options: an optional hash of options that can be passed in:
+4) options: an optional object of options that can be passed in:
    * 'suggestions' a boolean to indicate whether or not suggestions are wanted
       for a string that cannot be resolved to a valid unit; true indicates
       suggestions are wanted; false indicates they are not, and is the default
@@ -172,13 +162,13 @@ using them in actual clinical settings.
       ignored if neither unit includes a measurement in moles.  In such cases
       the mole-based unit must have a single mole unit in the numerator and the
       mass-based unit must have a single mass unit in the numerator.
-   * 'charge' the absolute value of the charge of the substance in question when a conversion 
-      is being requested from mass/moles to equivalents and vice versa. It is required 
-      when one of the units represents a value in equivalents and the other in mass or moles. 
+   * 'charge' the absolute value of the charge of the substance in question when a conversion
+      is being requested from mass/moles to equivalents and vice versa. It is required
+      when one of the units represents a value in equivalents and the other in mass or moles.
       It is ignored if neither unit includes an equivalent unit
 
-**Returns**: a hash with six elements:
-   * 'status' the will be: 'succeeded' if the conversion was successfully
+**Returns**: an object with six properties:
+   * 'status' will be: 'succeeded' if the conversion was successfully
       calculated; 'failed' if the conversion could not be made, e.g., if
       the units are not commensurable; or 'error' if an error occurred;
    * 'toVal' the numeric value indicating the conversion amount (without any
@@ -188,11 +178,13 @@ using them in actual clinical settings.
       error occurred, indicating the problem, or an explanation of a
       substitution such as the substitution of 'G' for 'Gauss', or
       an empty array if no messages were generated;
-   * 'suggestions' if suggestions were requested and found, this is a hash
-        that contains at most two elements:
+   * 'suggestions' if suggestions were requested and found, this is an object
+        that contains at most the following two properties.  (If suggestions
+        were not requsted or found, the 'suggestions' property will not be
+        set.):
      * 'from' which, if the fromUnitCode input parameter or one or more of
-         its components could not be found, is an array one or more hash
-         objects.  Each hash contains three elements:
+         its components could not be found, is an array of one or more
+         objects.  Each object contains three elements:
        * 'msg' which is a message indicating what unit expression the
            suggestions are for;
        * 'invalidUnit' which is the unit expression the suggestions are
@@ -203,8 +195,8 @@ using them in actual clinical settings.
          If no suggestions were found for the fromUnitCode this element
          will not be included.
      * 'to' which, if the "to" unit expression or one or more of its
-         components could not be found, is an array one or more hash
-         objects.  Each hash contains three elements:
+         components could not be found, is an array of one or more
+         objects.  Each object contains three elements:
        * 'msg' which is a message indicating what part of the toUnitCode
            input parameter the suggestions are for;
        * 'invalidUnit' which is the unit expression the suggestions
@@ -214,61 +206,59 @@ using them in actual clinical settings.
            unit guidance (if any).
          If no suggestions were found for the toUnitCode this element will
          not be included.
-       No 'suggestions' element will be included in the returned hash
-       object if none were found, whether or not they were requested.
    * 'fromUnit' the unit object for the fromUnitCode passed in; returned
       in case it's needed for additional data from the object; and
    * 'toUnit' the unit object for the toUnitCode passed in; returned
       in case it's needed for additional data from the object.
 
-For example, to convert 27 U.S. fathoms to U.S. inches (assuming you have 
-created a utils object as described above): 
- 
+For example, to convert 27 U.S. fathoms to U.S. inches (assuming you have
+created a utils object as described above):
+
     var returnObj = utils.convertUnitTo('[fth_us]', 27, '[in_us]');
-    if (returnObj['status'] === 'succeeded')
+    if (returnObj.status === 'succeeded')
       /* the conversion was successful.
-         returnObj['toVal'] will contain the conversion result
+         returnObj.toVal will contain the conversion result
            (~1943.9999999999998 - number, not formatted string)
-         returnObj['msg'] will be null
-         returnObj['fromUnit'] will contain the unit object for [fth_us]
-         returnObj['toUnit'] will contain the unit object for [in_us]
+         returnObj.msg will be null
+         returnObj.fromUnit will contain the unit object for [fth_us]
+         returnObj.toUnit will contain the unit object for [in_us]
        */
-    else if (returnObj['status'] === 'failed')
+    else if (returnObj.status === 'failed')
       /* the conversion could not be made.
-         returnObj['toVal'] will be null
-         returnObj['msg'] will contain a message describing the failure
-         returnObj['fromUnit'] will be null
-         returnObj['toUnit'] will be null
+         returnObj.toVal will be null
+         returnObj.msg will contain a message describing the failure
+         returnObj.fromUnit will be null
+         returnObj.toUnit will be null
        */
-    else (returnObj['status'] === 'error)
+    else if (returnObj.status === 'error')
       /* the conversion encountered an error
-         returnObj['toVal'] will be null
-         returnObj['msg'] will contain a message describing the error
-         returnObj['fromUnit'] will be null
-         returnObj['toUnit'] will be null
+         returnObj.toVal will be null
+         returnObj.msg will contain a message describing the error
+         returnObj.fromUnit will be null
+         returnObj.toUnit will be null
        */
-      
-If you want to know what unit types a particular unit can be converted to, the 
+
+If you want to know what unit types a particular unit can be converted to, the
 checkSynonyms function will provide a list of commensurable units for a specified
 unit expression.
 
 #### checkSynonyms(theSyn)
 
 This method searches for units that include a single search term (theSyn) in the
-unit's synonyms data and/or the unit name.  It returns all units found with a 
+unit's synonyms data and/or the unit name.  It returns all units found with a
 match.  This is useful when an exact match for a term is not found.  For example,
-submitting the term "pound" to the _validUnitString_ method will result in a 
-"not found" response.   Submitting it to this method will return with a list 
+submitting the term "pound" to the _validateUnitString_ method will result in a
+"not found" response.   Submitting it to this method will return a list
 of possible pound units.
 
 **Parameters**:
 1) theSyn: the term to search for
 
-**Returns**: a hash with three elements:
+**Returns**: an object with three properties:
    * 'status' contains the status of the request, which can be 'error',
-      'failed' or 'succeeded'; 
-   * 'msg' contains a message for an error or if no units were found; and 
-   * 'units' which is an array that contains one hash for each unit found:
+      'failed' or 'succeeded';
+   * 'msg' contains a message for an error or if no units were found; and
+   * 'units' which is an array that contains one object for each unit found:
      * 'code' is the unit's code;
      * 'name' is the unit's name; and
      * 'guidance' is the guidance, or description, for the unit.
@@ -283,14 +273,14 @@ of possible pound units.
 (assuming you have created a utils object as described above):
 
     var returnObj = utils.checkSynonyms('pound');
-    if (returnObj['status'] === 'succeeded')
-      /* one or more units was found.  returnObj['msg'] will be null and the
-         returnObj['units'] array will contain the data listed above */
-    else if (returnObj['status'] === 'failed')
-      /* no units were found and the returnObj['msg'] string will indicate that
+    if (returnObj.status === 'succeeded')
+      /* one or more units were found.  returnObj.msg will be null and the
+         returnObj.units array will contain the data listed above */
+    else if (returnObj.status === 'failed')
+      /* no units were found and the returnObj.msg string will indicate that
       */
     else
-      /* returnObj['status'] will be 'error' and returnObj['msg'] will indicate
+      /* returnObj.status will be 'error' and returnObj.msg will indicate
          what the error was. */
 
 #### convertToBaseUnits(fromUnit, fromVal)
@@ -314,7 +304,7 @@ a magnitude, and returns that data.
        substitution such as the substitution of 'G' for 'Gauss', or
        an empty array if no messages were generated.  There can also be a
        message that is just informational or warning.
-* magnitude: the new value when fromVal units of fromUnits is expressed in the base units.
+* magnitude: the new value when fromVal units of fromUnit is expressed in the base units.
 * fromUnitIsSpecial: whether the input unit fromUnit is a "special unit"
         as defined in UCUM.  This means there is some function applied to convert
         between fromUnit and the base units, so the returned magnitude is likely not
@@ -324,10 +314,10 @@ a magnitude, and returns that data.
 
 #### commensurablesList(fromUnit[, categoryList])
 
-Retrieves a list of units commensurable, i.e., that can be converted from and
-to, a specified unit.  Returns an error if the "from" unit cannot be found.
-If necessary, you can filter the list of units by specifying a list of unit
-categories that should be in the resulting list.
+Retrieves a list of units that are commensurable with, i.e., that can be
+converted from and to, a specified unit.  Returns an error if the "from" unit
+cannot be found.  If necessary, you can filter the list of units by specifying a
+list of unit categories that should be in the resulting list.
 
 **Parameters**:
 1) fromUnit: the name/unit string
@@ -347,11 +337,10 @@ categories that should be in the resulting list.
 ### Download the GitHub repository
 
 The code available here on GitHub includes functions and scripts to perform
-additional functions, mainly to convert ucum data from various formats to 
+additional functions, mainly to convert ucum data from various formats to
 the data used by our code as well as the code that supports the demo page.
-Click on the green "Code" button above to download the repository.
 
-    
+
 ### Building the code and data
 If you wish to modify the code, the build process is simply:
 
@@ -364,11 +353,10 @@ Tests can be run with:
 
     npm run test
 
-Although package does not directly use the UCUM "Functional Tests"
+This will include tests from the UCUM "Functional Tests"
 (https://ucum.org/docs/functional-tests and
 https://github.com/FHIR/Ucum-java/blob/master/src/test/resources/UcumFunctionalTests.xml),
-we have run those tests using ucum-lhc, and we found that all but two tests pass.
-The two tests that do not pass are checking for rounding of values at the right
-number of signifant digits.  The package does not round to significant digits,
-since if you round too early in a calculation, you can lose accuracy.
-
+which pass with the exception of rounding differences.  That is, ucum-lhc does
+not round, while the UCUM Functional Tests assume rounding, which is not a part
+of the UCUM specification.  The reason this package does not round is that if
+you round too early in a calculation, you can lose accuracy.