smath 1.3.5 → 1.5.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/1711484161)
 ![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.5.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

@@ -1,40 +1,28 @@
 #!/usr/bin/env node
 "use strict";
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 var _1 = require(".");
-var args = process.argv.slice(2);
-/**
- * Try to convert an argument into a numeric value.
- */
-function N(index, defaultVal) {
-    if (defaultVal === void 0) { defaultVal = NaN; }
-    if (index >= args.length) {
-        if (Number.isFinite(defaultVal)) {
-            return defaultVal;
-        }
-        else {
-            console.error('Required argument ' + index + ' is missing!');
-            process.exit(1);
-        }
-    }
-    var arg = Number.parseFloat(args[index]);
-    if (Number.isFinite(arg)) {
-        return arg;
-    }
-    else if (Number.isFinite(defaultVal)) {
-        return defaultVal;
+var func = process.argv[2].toLowerCase(), nums = process.argv.slice(3).map(function (arg, i) {
+    var num = Number.parseFloat(arg);
+    if (Number.isFinite(num)) {
+        return num;
     }
     else {
-        console.error('Argument #' + index + ' is ' + arg + ' but a number was expected.');
+        console.error('Argument #' + i + ' is "' + arg + '" but a number was expected.');
         process.exit(1);
     }
-}
-if (args.length < 1 || args[0].includes('help')) {
+});
+if (func.includes('help')) {
     console.log('Key: <required> [optional]');
     console.log('Arguments:');
     console.log('  help                     : Show this page');
-    console.log('  approx <a> <b> [eps]     : Check if `a` and `b` are approximately equal');
+    console.log('  sum <c0> [c1] ... [cn]   : Compute a total of `n` numbers');
+    console.log('  prod <c0> [c1] ... [cn]  : Compute a product of `n` numbers');
     console.log('  avg <c0> [c1] ... [cn]   : Take an average of `n` numbers');
+    console.log('  varp <c0> [c1] ... [cn]  : Compute the population variance of `n` numbers');
+    console.log('  vars <c0> [c1] ... [cn]  : Compute the sample variance of `n` numbers');
+    console.log('  approx <a> <b> [eps]     : Check if `a` and `b` are approximately equal');
     console.log('  clamp <n> <min> <max>    : Clamp `n` between `min` and `max`');
     console.log('  expand <n> <min> <max>   : Expand normalized `n` between `min` and `max`');
     console.log('  linspace <min> <max> <n> : Generate `n` linearly spaced numbers between `min` and `max`');
@@ -43,51 +31,69 @@ 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('  factorial <n>            : Compute `n!` (factorial)');
+    console.log('  error <exp> <act>        : Calculate the normaized percent error between `exp` and `act`');
     process.exit(1);
 }
-switch (args[0]) {
-    case ('approx'): {
-        console.log(_1.SMath.approx(N(1), N(2), N(3, 1e-6)));
+switch (func) {
+    case ('sum'): {
+        console.log(_1.SMath.sum(nums));
+        break;
+    }
+    case ('prod'): {
+        console.log(_1.SMath.prod(nums));
         break;
     }
     case ('avg'): {
-        if (args.length < 2) {
-            console.error('Need at least 1 argument.');
-            process.exit(1);
-        }
-        var operands = [];
-        for (var i = 1; i < args.length; i++) {
-            operands.push(N(i));
-        }
-        console.log(_1.SMath.avg.apply(_1.SMath, operands));
+        console.log(_1.SMath.avg(nums));
+        break;
+    }
+    case ('varp'): {
+        console.log(_1.SMath.varp(nums));
+        break;
+    }
+    case ('vars'): {
+        console.log(_1.SMath.vars(nums));
+        break;
+    }
+    case ('approx'): {
+        console.log(_1.SMath.approx(nums[0], nums[1], (_a = nums[2]) !== null && _a !== void 0 ? _a : 1e-6));
         break;
     }
     case ('clamp'): {
-        console.log(_1.SMath.clamp(N(1), N(2), N(3)));
+        console.log(_1.SMath.clamp(nums[0], nums[1], nums[2]));
         break;
     }
     case ('expand'): {
-        console.log(_1.SMath.expand(N(1), N(2), N(3)));
+        console.log(_1.SMath.expand(nums[0], nums[1], nums[2]));
         break;
     }
     case ('linspace'): {
-        console.log(_1.SMath.linspace(N(1), N(2), N(3)));
+        console.log(_1.SMath.linspace(nums[0], nums[1], nums[2]));
         break;
     }
     case ('logspace'): {
-        console.log(_1.SMath.logspace(N(1), N(2), N(3)));
+        console.log(_1.SMath.logspace(nums[0], nums[1], nums[2]));
         break;
     }
     case ('normalize'): {
-        console.log(_1.SMath.normalize(N(1), N(2), N(3)));
+        console.log(_1.SMath.normalize(nums[0], nums[1], nums[2]));
         break;
     }
     case ('translate'): {
-        console.log(_1.SMath.translate(N(1), N(2), N(3), N(4), N(5)));
+        console.log(_1.SMath.translate(nums[0], nums[1], nums[2], nums[3], nums[4]));
+        break;
+    }
+    case ('factorial'): {
+        console.log(_1.SMath.factorial(nums[0]));
+        break;
+    }
+    case ('error'): {
+        console.log(_1.SMath.error(nums[0], nums[1]));
         break;
     }
     default: {
-        console.error('Unknown argument "' + args[0] + '". Use with "help" for a list of commands.');
+        console.error('Unknown argument "' + func + '". Use with "help" for a list of commands.');
         process.exit(1);
     }
 }

package/dist/index.js

@@ -14,42 +14,69 @@ 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 y = SMath.sum([1, 2, 3]); // 6
+     * ```
+     */
+    SMath.sum = function (n) {
+        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 y = SMath.prod([2, 2, 3, 5]); // 60
+     * ```
+     */
+    SMath.prod = function (n) {
+        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
      * @returns The average, or mean
      * @example
      * ```js
-     * const mean = SMath.avg(1, 2, 3, 4); // 2.5
+     * const y = SMath.avg([1, 2, 4, 4]); // 2.75
      * ```
      */
-    SMath.avg = function () {
-        var n = [];
-        for (var _i = 0; _i < arguments.length; _i++) {
-            n[_i] = arguments[_i];
-        }
-        return n.reduce(function (prev, curr) { return prev + curr; }) / n.length;
+    SMath.avg = function (n) {
+        return this.sum(n) / n.length;
     };
     /**
-     * Clamp a number within a range.
-     * @param n The number to clamp
-     * @param min The minimum value of the range
-     * @param max The maximum value of the range
-     * @returns A clamped number
+     * Compute the variance of a **complete population**.
+     * @param n Any amount of numeric inputs
+     * @returns The population variance
      * @example
      * ```js
-     * const n1 = SMath.clamp(5, 0, 10),  // 5
-     *       n2 = SMath.clamp(-2, 0, 10); // 0
+     * const y = SMath.varp([1, 2, 4, 4]); // 1.6875
      * ```
      */
-    SMath.clamp = function (n, min, max) {
-        if (n < min) {
-            return min;
-        }
-        if (n > max) {
-            return max;
-        }
-        return n;
+    SMath.varp = function (n) {
+        var mean = this.avg(n), squares = n.map(function (x) { return Math.pow((x - mean), 2); });
+        return this.sum(squares) / n.length;
+    };
+    /**
+     * Compute the variance of a **sample**.
+     * @param n Any amount of numeric inputs
+     * @returns The sample variance
+     * @example
+     * ```js
+     * const y = SMath.vars([1, 2, 4, 4]); // 2.25
+     * ```
+     */
+    SMath.vars = function (n) {
+        var mean = this.avg(n), squares = n.map(function (x) { return Math.pow((x - mean), 2); });
+        return this.sum(squares) / (n.length - 1);
     };
     /**
      * Check if two numbers are approximately equal with a maximum abolute error.
@@ -67,6 +94,27 @@ var SMath = /** @class */ (function () {
         if (epsilon === void 0) { epsilon = 1e-6; }
         return a - b < epsilon && b - a < epsilon;
     };
+    /**
+     * Clamp a number within a range.
+     * @param n The number to clamp
+     * @param min The minimum value of the range
+     * @param max The maximum value of the range
+     * @returns A clamped number
+     * @example
+     * ```js
+     * const n1 = SMath.clamp(5, 0, 10),  // 5
+     *       n2 = SMath.clamp(-2, 0, 10); // 0
+     * ```
+     */
+    SMath.clamp = function (n, min, max) {
+        if (n < min) {
+            return min;
+        }
+        if (n > max) {
+            return max;
+        }
+        return n;
+    };
     /**
      * Normalize the number `n` from the range `min, max` to the range `0, 1`
      * @param n The number to normalize
@@ -149,6 +197,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 y = 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 1;
+        }
+        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 e = 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.5.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.2",
     "typedoc": "0.25.12",
     "typescript": "5.4.3"
   }

package/types/index.d.ts

@@ -9,29 +9,58 @@
  * 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 y = 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 y = 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
      * @returns The average, or mean
      * @example
      * ```js
-     * const mean = SMath.avg(1, 2, 3, 4); // 2.5
+     * const y = SMath.avg([1, 2, 4, 4]); // 2.75
      * ```
      */
-    static avg(...n: Array<number>): number;
+    static avg(n: Array<number>): number;
     /**
-     * Clamp a number within a range.
-     * @param n The number to clamp
-     * @param min The minimum value of the range
-     * @param max The maximum value of the range
-     * @returns A clamped number
+     * Compute the variance of a **complete population**.
+     * @param n Any amount of numeric inputs
+     * @returns The population variance
      * @example
      * ```js
-     * const n1 = SMath.clamp(5, 0, 10),  // 5
-     *       n2 = SMath.clamp(-2, 0, 10); // 0
+     * const y = SMath.varp([1, 2, 4, 4]); // 1.6875
      * ```
      */
-    static clamp(n: number, min: number, max: number): number;
+    static varp(n: Array<number>): number;
+    /**
+     * Compute the variance of a **sample**.
+     * @param n Any amount of numeric inputs
+     * @returns The sample variance
+     * @example
+     * ```js
+     * const y = SMath.vars([1, 2, 4, 4]); // 2.25
+     * ```
+     */
+    static vars(n: Array<number>): number;
     /**
      * Check if two numbers are approximately equal with a maximum abolute error.
      * @param a Any number
@@ -45,6 +74,19 @@ export declare abstract class SMath {
      * ```
      */
     static approx(a: number, b: number, epsilon?: number): boolean;
+    /**
+     * Clamp a number within a range.
+     * @param n The number to clamp
+     * @param min The minimum value of the range
+     * @param max The maximum value of the range
+     * @returns A clamped number
+     * @example
+     * ```js
+     * const n1 = SMath.clamp(5, 0, 10),  // 5
+     *       n2 = SMath.clamp(-2, 0, 10); // 0
+     * ```
+     */
+    static clamp(n: number, min: number, max: number): number;
     /**
      * Normalize the number `n` from the range `min, max` to the range `0, 1`
      * @param n The number to normalize
@@ -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 y = 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 e = SMath.error(22.5, 25); // -0.1
+     * ```
+     */
+    static error(experimental: number, actual: number): number;
 }