smath 1.3.5 → 1.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 ![NPM Downloads](https://img.shields.io/npm/dt/smath)
 ![NPM Version](https://img.shields.io/npm/v/smath)
-![Relative date](https://img.shields.io/date/1711226964)
+![Relative date](https://img.shields.io/date/1711423325)
 ![GitHub watchers](https://img.shields.io/github/watchers/nicfv/npm)
 ![GitHub forks](https://img.shields.io/github/forks/nicfv/npm)
 ![GitHub Repo stars](https://img.shields.io/github/stars/nicfv/npm)
@@ -12,7 +12,7 @@
 smath can be installed from the official [npm package repository](https://www.npmjs.com/package/smath). It is highly recommended to install the latest version, which is installed by default with the following command.
 
 ```shell
-npm i smath@1.3.5
+npm i smath@1.4.0
 ```
 
 ## Bugs and Requests
@@ -25,6 +25,26 @@ Thank you for your interest in contributing to smath! smath is an open source so
 ## Getting Started
 
 Small math? Simple math? Or supplemental math? Canonically, "SMath" is pronounced "smath" and stands for "small math (library.)" Similar to JavaScript's builtin [`Math`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math) object, `SMath` exports one global object with several math-related helper functions. There is no need to instantiate the class, just call functions directly. See the examples below to get started using SMath!
+
+## Executables
+
+SMath is also packaged with an executabe that can be run directly through `npx` in the terminal - even outside of a NodeJS project! In fact, open your terminal now, and type the following to show a list of valid `npx smath` commands!
+
+```shell
+npx smath
+```
+
+Commands are all structured like this.
+
+```shell
+npx smath [cmd] [args]
+```
+
+This example command returns the value 0.4.
+
+```shell
+npx smath normalize 4 0 10
+```
 ## Examples
 Here are a few quickstart examples written in JavaScript that showcase some out-of-box features of the `smath` package.
 ### JavaScript Math Oddities

package/dist/bin.js

@@ -43,6 +43,7 @@ if (args.length < 1 || args[0].includes('help')) {
     console.log('                           : Normalize `n` between `min` and `max`');
     console.log('  translate <n> <min1> <max1> <min2> <max2>');
     console.log('                           : Linearly interpolate `n` from `min1`, `max1` to `min2`, `max2`');
+    console.log('  error <exp> <act>        : Calculate the normaized percent error between `exp` and `act`');
     process.exit(1);
 }
 switch (args[0]) {
@@ -86,6 +87,10 @@ switch (args[0]) {
         console.log(_1.SMath.translate(N(1), N(2), N(3), N(4), N(5)));
         break;
     }
+    case ('error'): {
+        console.log(_1.SMath.error(N(1), N(2)));
+        break;
+    }
     default: {
         console.error('Unknown argument "' + args[0] + '". Use with "help" for a list of commands.');
         process.exit(1);

package/dist/index.js

@@ -14,6 +14,40 @@ exports.SMath = void 0;
 var SMath = /** @class */ (function () {
     function SMath() {
     }
+    /**
+     * Add up all the inputs.
+     * If none are present, returns 0.
+     * @param n Any amount of numeric inputs
+     * @returns The sum total
+     * @example
+     * ```js
+     * const sum = SMath.sum(1, 2, 3); // 6
+     * ```
+     */
+    SMath.sum = function () {
+        var n = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            n[_i] = arguments[_i];
+        }
+        return n.reduce(function (a, b) { return a + b; }, 0);
+    };
+    /**
+     * Multiply all the inputs.
+     * If none are present, returns 1.
+     * @param n Any amount of numeric inputs
+     * @returns The product
+     * @example
+     * ```js
+     * const prod = SMath.prod(2, 2, 3, 5); // 60
+     * ```
+     */
+    SMath.prod = function () {
+        var n = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            n[_i] = arguments[_i];
+        }
+        return n.reduce(function (a, b) { return a * b; }, 1);
+    };
     /**
      * Compute the average, or mean, of a set of numbers.
      * @param n Any amount of numeric inputs
@@ -28,7 +62,41 @@ var SMath = /** @class */ (function () {
         for (var _i = 0; _i < arguments.length; _i++) {
             n[_i] = arguments[_i];
         }
-        return n.reduce(function (prev, curr) { return prev + curr; }) / n.length;
+        return this.sum.apply(this, n) / n.length;
+    };
+    /**
+     * Compute the variance of a **complete population**.
+     * @param n Any amount of numeric inputs
+     * @returns The population variance
+     * @example
+     * ```js
+     * const pvar = SMath.pvar(1, 2, 3, 4); // 1.25
+     * ```
+     */
+    SMath.pvar = function () {
+        var n = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            n[_i] = arguments[_i];
+        }
+        var mean = this.avg.apply(this, n), squares = n.map(function (x) { return Math.pow((x - mean), 2); });
+        return this.sum.apply(this, squares) / n.length;
+    };
+    /**
+     * Compute the variance of a **sample**.
+     * @param n Any amount of numeric inputs
+     * @returns The sample variance
+     * @example
+     * ```js
+     * const svar = SMath.svar(1, 2, 3, 4); // 1.666...
+     * ```
+     */
+    SMath.svar = function () {
+        var n = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            n[_i] = arguments[_i];
+        }
+        var mean = this.avg.apply(this, n), squares = n.map(function (x) { return Math.pow((x - mean), 2); });
+        return this.sum.apply(this, squares) / (n.length - 1);
     };
     /**
      * Clamp a number within a range.
@@ -149,6 +217,47 @@ var SMath = /** @class */ (function () {
     SMath.logspace = function (min, max, count) {
         return this.linspace(min, max, count).map(function (n) { return Math.pow(10, n); });
     };
+    /**
+     * Compute the factorial of `n`.
+     * @param n Any positive integer
+     * @returns `n!`
+     * @example
+     * ```js
+     * const factorial = SMath.factorial(5); // 120
+     * ```
+     */
+    SMath.factorial = function (n) {
+        if (n < 0 || (n | 0) !== n) {
+            throw new Error('Input must be a positive integer.');
+        }
+        else if (n === 0) {
+            return 0;
+        }
+        else if (n <= 2) {
+            return n;
+        }
+        else {
+            return n * this.factorial(n - 1);
+        }
+    };
+    /**
+     * Calculate the relative normalized error or deviation from any
+     * value to an accepted value. An error of 0 indicates that the
+     * two values are identical. An error of -0.1 indicates that the
+     * experimental value is 10% smaller than (90% of) the accepted
+     * value. An error of 1.0 indicates that the experimental value
+     * is 100% greater (or twice the size) of the accepted value.
+     * @param experimental The value observed or produced by a test
+     * @param actual The accepted or theoretical value
+     * @returns The relative (normalized) error
+     * @example
+     * ```js
+     * const error = SMath.error(22.5, 25); // -0.1
+     * ```
+     */
+    SMath.error = function (experimental, actual) {
+        return (experimental - actual) / actual;
+    };
     return SMath;
 }());
 exports.SMath = SMath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smath",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "Small math function library",
   "homepage": "https://npm.nicfv.com/smath",
   "bin": "dist/bin.js",
@@ -48,7 +48,7 @@
   "license": "MIT",
   "devDependencies": {
     "@types/node": "20.11.30",
-    "exray": "1.0.0",
+    "exray": "1.0.1",
     "typedoc": "0.25.12",
     "typescript": "5.4.3"
   }

package/types/index.d.ts

@@ -9,6 +9,28 @@
  * useful interpolation and extrapolation functions.
  */
 export declare abstract class SMath {
+    /**
+     * Add up all the inputs.
+     * If none are present, returns 0.
+     * @param n Any amount of numeric inputs
+     * @returns The sum total
+     * @example
+     * ```js
+     * const sum = SMath.sum(1, 2, 3); // 6
+     * ```
+     */
+    static sum(...n: Array<number>): number;
+    /**
+     * Multiply all the inputs.
+     * If none are present, returns 1.
+     * @param n Any amount of numeric inputs
+     * @returns The product
+     * @example
+     * ```js
+     * const prod = SMath.prod(2, 2, 3, 5); // 60
+     * ```
+     */
+    static prod(...n: Array<number>): number;
     /**
      * Compute the average, or mean, of a set of numbers.
      * @param n Any amount of numeric inputs
@@ -19,6 +41,26 @@ export declare abstract class SMath {
      * ```
      */
     static avg(...n: Array<number>): number;
+    /**
+     * Compute the variance of a **complete population**.
+     * @param n Any amount of numeric inputs
+     * @returns The population variance
+     * @example
+     * ```js
+     * const pvar = SMath.pvar(1, 2, 3, 4); // 1.25
+     * ```
+     */
+    static pvar(...n: Array<number>): number;
+    /**
+     * Compute the variance of a **sample**.
+     * @param n Any amount of numeric inputs
+     * @returns The sample variance
+     * @example
+     * ```js
+     * const svar = SMath.svar(1, 2, 3, 4); // 1.666...
+     * ```
+     */
+    static svar(...n: Array<number>): number;
     /**
      * Clamp a number within a range.
      * @param n The number to clamp
@@ -110,4 +152,30 @@ export declare abstract class SMath {
      * ```
      */
     static logspace(min: number, max: number, count: number): Array<number>;
+    /**
+     * Compute the factorial of `n`.
+     * @param n Any positive integer
+     * @returns `n!`
+     * @example
+     * ```js
+     * const factorial = SMath.factorial(5); // 120
+     * ```
+     */
+    static factorial(n: number): number;
+    /**
+     * Calculate the relative normalized error or deviation from any
+     * value to an accepted value. An error of 0 indicates that the
+     * two values are identical. An error of -0.1 indicates that the
+     * experimental value is 10% smaller than (90% of) the accepted
+     * value. An error of 1.0 indicates that the experimental value
+     * is 100% greater (or twice the size) of the accepted value.
+     * @param experimental The value observed or produced by a test
+     * @param actual The accepted or theoretical value
+     * @returns The relative (normalized) error
+     * @example
+     * ```js
+     * const error = SMath.error(22.5, 25); // -0.1
+     * ```
+     */
+    static error(experimental: number, actual: number): number;
 }