smath 1.1.8 → 1.3.0

package/README.md

@@ -1,8 +1,8 @@
-[Docs](https://npm.nicfv.com/smath/) | [GitHub](https://github.com/nicfv/npm/tree/main/smath/) | [npm](https://www.npmjs.com/package/smath) | [Changelog](https://github.com/nicfv/npm/blob/main/smath//CHANGELOG.md) | Small math function library
+[Home](/) | [Docs](https://npm.nicfv.com/smath/) | [GitHub](https://github.com/nicfv/npm/tree/main/smath/) | [npm](https://www.npmjs.com/package/smath) | [Changelog](https://github.com/nicfv/npm/blob/main/smath//CHANGELOG.md) | [YouTube](https://www.youtube.com/@nciv) | Small math function library
 
 ![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/1710904533)
+![Relative date](https://img.shields.io/date/1711134970)
 ![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.1.8
+npm i smath@1.3.0
 ```
 
 ## Bugs and Requests
@@ -28,31 +28,63 @@ Similar to JavaScript's builtin [`Math`](https://developer.mozilla.org/en-US/doc
 
 ## Example
 
-A temperature conversion tool using [`SMath.translate`](https://npm.nicfv.com/smath/classes/SMath.html#translate) to convert units and [`SMath.approx`](https://npm.nicfv.com/smath/classes/SMath.html#approx) to validate the result. The translation uses freezing and boiling points for 2 unit systems to linearly interpolate between them.
+Here are a few examples written in JavaScript for a quick start into `SMath`.
+
+### JavaScript Math Oddities
+
+```js
+import { SMath } from 'smath';
+
+// Determine the value of 0.1 + 0.2 using vanilla JavaScript and SMath
+console.log('0.1 + 0.2 == 0.3 is ' + (0.1 + 0.2 == 0.3));
+console.log('SMath.approx(0.1 + 0.2, 0.3) is ' + SMath.approx(0.1 + 0.2, 0.3));
+```
+
+```text
+0.1 + 0.2 == 0.3 is false
+SMath.approx(0.1 + 0.2, 0.3) is true
+```
+
+### Temperature Conversion
+
+A temperature conversion tool using [`SMath.translate`](https://npm.nicfv.com/smath/classes/SMath.html#translate) to convert units. The translation uses freezing and boiling points for 2 unit systems to linearly interpolate between them.
 
 ```js
 import { SMath } from 'smath';
 
+// Water always freezes at the
+// same temperature, but the
+// units might be different.
 // Define some constants to
-// define the number ranges
+// create two number ranges.
 const C_Freeze = 0,
     C_Boil = 100,
     F_Freeze = 32,
     F_Boil = 212;
 
 // Use the `SMath` class to
-// translate the temperature in the
+// generate an array of five
+// linearly spaced temperature
+// values from 0 to 20.
+const C = SMath.linspace(0, 20, 5);
+
+// Use the `SMath` class to linearly
+// interpolate the temperature in the
 // C number range to a temperature
-// in the F number range
-const C = 20,
-    F_expected = 68,
-    F_actual = SMath.translate(C, C_Freeze, C_Boil, F_Freeze, F_Boil);
-
-// Determine whether the
-// temperature conversion
-// is valid using `approx`
-const valid = SMath.approx(F_expected, F_actual);
-if (!valid) {
-    throw new Error('Invalid result.');
+// in the F number range.
+const F = C.map(c => SMath.translate(c, C_Freeze, C_Boil, F_Freeze, F_Boil));
+
+// Print out each temperature
+// in both units of C and F.
+for (let i = 0; i < C.length; i++) {
+    console.log(C[i].toFixed() + 'C is ' + F[i].toFixed() + 'F')
 }
 ```
+
+```text
+0C is 32F
+5C is 41F
+10C is 50F
+15C is 59F
+20C is 68F
+```

package/dist/src/bin.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+"use strict";
+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;
+    }
+    else {
+        console.error('Argument #' + index + ' is ' + arg + ' but a number was expected.');
+        process.exit(1);
+    }
+}
+if (args.length < 1 || args[0].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('  avg <c0> [c1] ... [cn]   : Take an average of `n` numbers');
+    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`');
+    console.log('  logspace <min> <max> <n> : Generate `n` logarithmically spaced numbers between `min` and `max`');
+    console.log('  normalize <n> <min> <max>');
+    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`');
+    process.exit(1);
+}
+switch (args[0]) {
+    case ('approx'): {
+        console.log(_1.SMath.approx(N(1), N(2), N(3, 1e-6)));
+        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));
+        break;
+    }
+    case ('clamp'): {
+        console.log(_1.SMath.clamp(N(1), N(2), N(3)));
+        break;
+    }
+    case ('expand'): {
+        console.log(_1.SMath.expand(N(1), N(2), N(3)));
+        break;
+    }
+    case ('linspace'): {
+        console.log(_1.SMath.linspace(N(1), N(2), N(3)));
+        break;
+    }
+    case ('logspace'): {
+        console.log(_1.SMath.logspace(N(1), N(2), N(3)));
+        break;
+    }
+    case ('normalize'): {
+        console.log(_1.SMath.normalize(N(1), N(2), N(3)));
+        break;
+    }
+    case ('translate'): {
+        console.log(_1.SMath.translate(N(1), N(2), N(3), N(4), N(5)));
+        break;
+    }
+    default: {
+        console.error('Unknown argument "' + args[0] + '". Use with "help" for a list of commands.');
+        process.exit(1);
+    }
+}

package/dist/src/index.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SMath = void 0;
+/**
+ * @packageDocumentation
+ * Small math function library
+ *
+ * Exports the public-facing API for `smath`
+ */
+/**
+ * Contains a small math function library including
+ * useful interpolation and extrapolation functions.
+ */
+var SMath = /** @class */ (function () {
+    function SMath() {
+    }
+    /**
+     * 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
+     * ```
+     */
+    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;
+    };
+    /**
+     * 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;
+    };
+    /**
+     * Check if two numbers are approximately equal with a maximum abolute error.
+     * @param a Any number
+     * @param b Any number
+     * @param epsilon Maximum absolute error
+     * @returns True if `a` is approximately `b`
+     * @example
+     * ```js
+     * const b1 = SMath.approx(1 / 3, 0.33, 1e-6), // false
+     *       b2 = SMath.approx(1 / 3, 0.33, 1e-2); // true
+     * ```
+     */
+    SMath.approx = function (a, b, epsilon) {
+        if (epsilon === void 0) { epsilon = 1e-6; }
+        return a - b < epsilon && b - a < epsilon;
+    };
+    /**
+     * Normalize the number `n` from the range `min, max` to the range `0, 1`
+     * @param n The number to normalize
+     * @param min The minimum value in the range
+     * @param max The maximum value in the range
+     * @returns A normalized value
+     * @example
+     * ```js
+     * const y = SMath.normalize(18, 9, 99); // 0.1
+     * ```
+     */
+    SMath.normalize = function (n, min, max) {
+        if (min === max) {
+            return 0;
+        }
+        return (n - min) / (max - min);
+    };
+    /**
+     * Expand a normalized number `n` to the range `min, max`
+     * @param n A normalized number
+     * @param min The minimum value in the range
+     * @param max The maximum value in the range
+     * @returns A value within the number range
+     * @example
+     * ```js
+     * const y = SMath.expand(0.25, 4, 6); // 4.5
+     * ```
+     */
+    SMath.expand = function (n, min, max) {
+        return (max - min) * n + min;
+    };
+    /**
+     * Translate a number `n` from the range `min1, max1` to the range `min2, max2`
+     * @param n The number to translate
+     * @param min1 The minimum value from the initial range
+     * @param max1 The maximum value from the initial range
+     * @param min2 The minimum value for the final range
+     * @param max2 The maximum value for the final range
+     * @returns A translated number in the final range
+     * @example
+     * ```js
+     * const C = 20,
+     *       F = SMath.translate(C, 0, 100, 32, 212); // 68
+     * ```
+     */
+    SMath.translate = function (n, min1, max1, min2, max2) {
+        return this.expand(this.normalize(n, min1, max1), min2, max2);
+    };
+    /**
+     * Generate an array of linearly spaced numbers.
+     * @param min The initial value of the linear space
+     * @param max The final value of the linear space
+     * @param count The number of values in the space
+     * @returns The linear space as an array of numbers
+     * @example
+     * ```js
+     * const space = SMath.linspace(1, 5, 6);
+     * // [ 1, 1.8, 2.6, 3.4, 4.2, 5 ]
+     * ```
+     */
+    SMath.linspace = function (min, max, count) {
+        var space = [];
+        for (var i = 0; i < count; i++) {
+            space[i] = this.translate(i, 0, count - 1, min, max);
+        }
+        return space;
+    };
+    /**
+     * Generate an array of logarithmically spaced numbers.
+     * @param min The initial magnitude of the space
+     * @param max The final magnitude of the space
+     * @param count The number of values in the space
+     * @returns The logarithmic space as an array of numbers
+     * @example
+     * ```js
+     * const space = SMath.logspace(0, 2, 5);
+     * // [ 1, 3.2, 10, 31.6, 100 ]
+     * ```
+     */
+    SMath.logspace = function (min, max, count) {
+        return this.linspace(min, max, count).map(function (n) { return Math.pow(10, n); });
+    };
+    return SMath;
+}());
+exports.SMath = SMath;

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "smath",
-  "version": "1.1.8",
+  "version": "1.3.0",
   "description": "Small math function library",
   "homepage": "https://npm.nicfv.com/smath",
-  "main": "dist/index.js",
-  "types": "types/index.d.ts",
+  "bin": "dist/src/bin.js",
+  "main": "dist/src/index.js",
+  "types": "types/src/index.d.ts",
   "files": [
-    "dist",
-    "types"
+    "dist/src",
+    "types/src"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc --removeComments",
-    "types": "rm -rf types && tsc --declaration --declarationDir types --emitDeclarationOnly",
-    "test": "tsc --noEmit",
+    "build": "rm -rf dist && tsc",
+    "test": "npm run build && node dist/test/index.js",
     "clean": "rm -rf node_modules package-lock.json dist types docs",
     "docs": "rm -rf docs && typedoc --includeVersion --disableSources --hideGenerator src",
-    "prepack": "npm run build && npm run types",
+    "prepack": "npm run build",
     "postpack": "rm -rf dist types"
   },
   "keywords": [
@@ -47,7 +47,9 @@
   "repository": "github:nicfv/npm",
   "license": "MIT",
   "devDependencies": {
+    "@types/node": "20.11.30",
     "typedoc": "0.25.12",
-    "typescript": "5.4.2"
+    "typescript": "5.4.3",
+    "xpt": "0.2.0"
   }
 }

package/types/src/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -1,51 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SMath = void 0;
-var SMath = (function () {
-    function SMath() {
-    }
-    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.clamp = function (n, min, max) {
-        if (n < min) {
-            return min;
-        }
-        if (n > max) {
-            return max;
-        }
-        return n;
-    };
-    SMath.approx = function (a, b, epsilon) {
-        if (epsilon === void 0) { epsilon = 1e-6; }
-        return a - b < epsilon && b - a < epsilon;
-    };
-    SMath.normalize = function (n, min, max) {
-        if (min === max) {
-            return 0;
-        }
-        return (n - min) / (max - min);
-    };
-    SMath.expand = function (n, min, max) {
-        return (max - min) * n + min;
-    };
-    SMath.translate = function (n, min1, max1, min2, max2) {
-        return this.expand(this.normalize(n, min1, max1), min2, max2);
-    };
-    SMath.linspace = function (min, max, count) {
-        var space = [];
-        for (var i = 0; i < count; i++) {
-            space[i] = this.translate(i, 0, count - 1, min, max);
-        }
-        return space;
-    };
-    SMath.logspace = function (min, max, count) {
-        return this.linspace(min, max, count).map(function (n) { return Math.pow(10, n); });
-    };
-    return SMath;
-}());
-exports.SMath = SMath;