RickKukiela/README.md

## README.md

      
    Raw
  

              README.md
            
          
    Metraflex Off-Center Seal Calculator

Created by Rick Kukiela rick@belniakmedia.com

Lead Developer at Belniak Media, Inc. (https://www.belniakmedia.com)
YOU MUST RUN THE BUILD COMMAND TO CREATE THE dist/ FOLDER AND COMPILED SCRIPTS!
Compiler Notes

This package was written in TypeScript under Node18. It is recommended that you use nvm (https://github.com/nvm-sh/nvm) to swap what node version you are using on a given terminal session. This software works on windows as long as you have GitBash or similar installed (this comes free with the windows version of git which you need to clone the repo.).
The actual Node version used at development time was node v18.9.0 and npm v8.19.1.
It is assumed that yarn could be used in place of node, but I don't use yarn so I cannot confirm this.

Installing the Project Locally


Use GIT to clone the repository.
Ensure your terminal session is using the correct version of node/npm. (See Compiler Notes for details)
From the project root (same folder as this README.md file.), in a terminal/bash session run the command npm i --save-dev (this will install all the script and compiler dependencies).


Back-Office / Demo Version

Note: Metraflex will want a copy of this demo to be hosted in a secure area for their internal office use.
An example of how to integrate the new calculator to a website form is located in the demo/ folder of the project. The demo uses a web-worker to ensure the browser is not locked up during a long calculation. For this reason you cannot access the demo/index.html file directly from your hard drive and must be "served" via a web server as browser CORS security measures will not allow the web-worker to function properly when running the file directly from your hard drive.
This project comes with a built in "hot-reloading" web server for serving the demo. Once the node dependencies are installed, you can run the following command to start a web server and launch a web browser tab to the demo automatically:
npm run demo


DEVELOPMENT NOTE:

If you are planning on using the demo as a way to test code changes during future development. Be advised that running the npm run build command is required for any code changes to the calculator to be imported or updated. The build command will copy the newly generated ocs-calc.min.js file to the demo directory automatically. If the demo server is running the page will reload automatically upon the new script file being installed.


Installation to the Production Website

After completing the build process below, copy the dist/_bundles/ocs-calc.min.js file to the production site and implement code to the calculator form that uses the new calculator code. See demo for example implementation. It is not necessary (or requested by Metraflex) to add any of the new options to the current off-center seal calculator form. You should not need to modify the input form html to install the new script.

Using it on the Command Line

There is a CLI script named index.ts that implements this functionality. To use the calculator on the command line (in a node environment) without needing to re-build after each edit during development, you can run the following command:
npm run exec -- --input=19.5,23.125,1

The -- portion separates the base command with the arguments so that node passes the following arguments to the script rather than attempting to use them directly on the node container.
The CLI script takes the following arguments:

NOTE: --input or --cfg is required, do not use both at the same time!
REQUIRED: (only one)

--cfg=<int>

Use the corresponding test config number from the tests/_config.ts file for input values and expected solution value. (E.g.: --cfg=4)
--input=<PipeOD:float>,<HoleID:float>,<SmallestSpace:float>

Directly provide the PipeOD, HoleID, and Smallest Space values via comma separated values in that exact order. (E.g.: --input=19.5,23.125,1)

OPTIONAL:

-d<debugLevel:int>

Enable debug output. The <debugLevel> must be an integer between 1 and 4 and indicates level of verbosity (1 being the lowest and 4 being the highest). (E.g.: -d4)
--deep

Enable deep search mode. All solutions will be found and will not be limited by maxTotalSolutions. This option may cause a significant increase in execution time. Does not apply to the explain method.
--explain or --explain="<SealList:string>"

Use the explain method instead of the normal calculate method. An expected solution "seal list" is required for this method. The --explain version can only be used with the --cfg input argument when the corresponding config object contains an expected (seal list) property, otherwise, use the --explain="\<SealList>" (expanded) version and provide a comma separated list of seal models that make up the expected solution. The expanded version can also be used to override the expected property when used with --cfg. (E.g.: --explain or --explain="200, 200, 200/360")
--fitTolerance=<float>

Enable deep search mode. All solutions will be found and will not be limited by maxTotalSolutions. This option may cause a significant increase in execution time. Does not apply to the explain method.
--maxTotalSolutions=<int>

Set the max number of total solutions to find and evaluate for the best solution. The total will be divided evenly across each valid starting seal. The default value is 10000.
--startAngleIncrement=<float>

Set the amount for which to increase the startDistance from the base start point denoted by the <SmallestSpace> at each increment when rotating the start point in order to find a valid solution. This is only used when valid solutions are not found using the standard calculation. This effects both the calculate and explain methods. The default value is .005. (E.g.: --startAngleIncrement=.01)
--startAngleMaxIncrements=<int>

Set the number of times the startDistance will be rotated using the startAngleIncrement before giving up after not finding a solution. The default value is 200. (E.g.: --startAngleMaxIncrements=200)


Run the Test Suite

It is recommended that you run the test suite before building after making changes to ensure the changes did not break the defined expected output. To perform the tests, run the following command:
npm run test

If you have problems you may need to install jest globally with npm i -g jest.
You can run specific tests with the following commands:

npx jest calc, npx jest explain and npx jest fail
or if jest is globally installed:

jest calc, jest explain and jest fail

Build/Transpile the Source Code

Since this is a TypeScript program, you will need to "build" this for use outside the NodeJs environment. The build script outputs 3 versions in the dist/ folder (which is created upon executing the build script).
To build the dist files, run the following command:

npm run build

Build Target

The current build target (defined in .tsconfig) is set to es6. The three output libraries will work in any environment that supports the given module target and EmacsScript 6 (ES 2016) or higher. Any modern web browser should meet the ES6 requirement. IE11 will probably not work, nor was it tested. (See: Can I Use (ES6) for more info). If you need older browser support you can edit the target property of the .tsconfig file and re-run the build command to try to get support for older browsers.
Build Outputs


UMD: dist/umd-bundles/

This is the UMD build which should be used in browsers / on the website. The included demo file shows how to use this version. The OffCenterCalc class is exposed as the property named OffCenterCalc on the global scoped object OffCenterSeal. A calculator instance can be created using new OffCenterSeal.OffCenterCalc().


CommonJS: dist/lib-commonjs/

This is the CommonJs library and can be used within NodeJs environments where commonjs style module imports are required.


ESM (EmacsScript Modules): dist/lib-esm/

This is the ESM library and can be used within environments where ESM modules are supported.