lolite.add 1.1.7 → 1.1.9

package/README.md

@@ -1,16 +1,259 @@
-# lolite.add
-
-### add(augend, addend)
+## add(augend, addend)
 Calculates the arithmetic sum of two values. 
 Non-finite or non-numeric values are coerced to zero.
 
 ```javascript
-const add = require("lolite.add")
+const lolite = require("lolite.add")
 const sum = add(5, 2)
 // sum: 7
 
 const coercedSum = add(Infinity, "garbage")
 // result: 0 (0 + 0)
-```
-
-This utility is part of the [LoLite](https://github.com/enterprise-npm-ai/lolite) utility suite.
+```
+
+### subtract(minuend, subtrahend)
+Calculates the arithmetic difference between two values.
+Non-finite or non-numeric values are coerced to zero.
+
+```javascript
+const lolite = require("lolite.add")
+const diff = lolite.subtract(10, 3)
+// diff: 7
+
+const coercedDiff = lolite.subtract(Infinity, NaN)
+// result: 0 (0 - 0)
+```
+
+### multiply(multiplier, multiplicand)
+Calculates the product of two values.
+Non-finite or non-numeric values are coerced to zero.
+
+```javascript
+const lolite = require("lolite.add")
+const product = lolite.multiply(6, 7)
+// product: 42
+
+const coercedProduct = lolite.multiply(NaN, "garbage")
+// result: 0 (0 * 0)
+```
+
+### divide(dividend, divisor)
+Calculates the quotient of two values. 
+Non-finite or non-numeric values are coerced to zero. Division by positive zero returns infinity, and divison by negative zero returns negative infinity. If you divide zero by zero it returns NaN.
+
+```javascript
+const lolite = require("lolite.add")
+const quotient = lolite.divide(20, 5)
+// quotient: 4
+
+const divisonByZero = lolite.divide(10, 0)
+// result: Infinity
+
+const coercedDivide = lolite.divide("garbage", Infinity)
+// result: NaN (0 / 0)
+```
+
+### power(base, exponent)
+Calculates the exponentiation of a base to a power. Non-finite or non-numeric values are coerced to zero.
+
+```javascript
+const lolite = require("lolite.add")
+const result = lolite.power(2, 3)
+// result: 8
+
+const fractional = lolite.power(2, -1)
+// result: 0.5
+
+const zeroPower = lolite.power(10, 0)
+// result: 1
+
+const coercedPower = lolite.power(Infinity, "garbage")
+// result: 1 (0^0)
+```
+
+### modulo(dividend, divisor)
+Calculates the remainder of division.
+Non-finite or non-numeric values are coerced to zero.
+
+Note on Negative Arithmetic: LoLite implements Floored Modulo logic ($a \pmod b$). Unlike the native JavaScript `%` operator which truncates toward zero, LoLite follows the mathematical standard where the result takes the sign of the divisor. For example, `lolite.modulo(-10, 3)` returns 2.
+
+If the divisor is zero, it will return `NaN`.
+
+```javascript
+const lolite = require("lolite.add")
+const remainder = lolite.modulo(10, 3)
+// remainder: 1
+
+const negativeModuloResult = lolite.modulo(10, 3)
+// result: 2
+
+const coercedModulo = lolite.modulo(Infinity, "garbage")
+// result: NaN (0 % 0)
+```
+
+### abs(value)
+Gets the absolute value of a number.
+Non-finite or non-numeric values are coerced to zero.
+
+```javascript
+const lolite = require("lolite.add")
+const result = lolite.abs(-42)
+// result: 42
+
+const coercedAbs = lolite.abs("garbage")
+// result: 0
+```
+
+### invert(value)
+Inverts the sign of a value. Zero becomes negative zero.
+Non-numeric values are coerced to zero.
+Infinity is negated to -Infinity, and vice versa.
+
+```javascript
+const lolite = require("lolite.add")
+const inverted = lolite.invert(10)
+// inverted: -10
+
+const doubleNegative = lolite.invert(-5)
+// result: 5
+
+const negativeInfinity = lolite.invert(Infinity)
+// result: -Infinity
+
+const coercedNegative = lolite.invert("garbage")
+// result: -0 (0 inverted)
+```
+
+### floor(value)
+Round a number down to the nearest whole integer.
+Non-finite or non-numeric values are coerced to zero.
+
+```javascript
+const lolite = require("lolite.add")
+const positiveResult = lolite.floor(2.1)
+// result: 2
+
+const negativeResult = lolite.floor(-2.1)
+// result: 3
+
+const coercedResult = lolite.floor("garbage")
+// result: 0 (0 floored)
+```
+
+### ceil(value)
+Round a number up to the nearest whole integer.
+Non-finite or non-numeric values are coerced to zero.
+
+```javascript
+const lolite = require("lolite.add")
+const positiveResult = lolite.ceil(2.1)
+// result: 3
+
+const negativeResult = lolite.ceil(-2.1)
+// result: 2
+
+const coercedResult = lolite.ceil("garbage")
+// result: 0 (0 ceiled)
+```
+
+### round(value)
+Round a number either up to the nearest whole integer, unless the number is less than `0.5`, then it rounds down.
+Non-finite or non-numeric values are coerced to zero.
+
+```javascript
+const lolite = require("lolite.add")
+
+const flooredResult = lolite.round(2.1)
+// result: 2
+
+const ceiledResult = lolite.round(2.9)
+// result: 3
+
+const coercedResult = lolite.round("garbage")
+// result: 0 (0 ceiled)
+```
+
+### trunc(value)
+Truncates the decimal portion of a number, returning only the integer part. Truncation moves toward zero for both positive and negative numbers.
+Non-finite or non-numeric values are coerced to zero.
+
+```javascript
+const lolite = require("lolite.add")
+
+const positiveResult = lolite.trunc(2.9)
+// result: 2
+
+const negativeResult = lolite.trunc(-2.9)
+// result: -2
+
+const zeroPreservation = lolite.trunc(-0)
+// result: -0
+
+const coercedResult = lolite.trunc("garbage")
+// result: 0
+```
+
+### sign(value)
+Returns the sign of a number, indicating whether the number is positive, negative, or zero, or negative zero.
+Non-finite values are coerced to zero.
+
+```javascript
+const lolite = require("lolite.add")
+
+lolite.sign(42)        // result: 1
+lolite.sign(Infinity)  // result: 1
+lolite.sign(-42)       // result: -1
+lolite.sign(-Infinity) // result: -1
+lolite.sign(0)         // result: 0
+lolite.sign(-0)        // result: -0
+
+lolite.sign("garbage") // result: 0
+lolite.sign(NaN) // result: 0
+```
+
+### max(a, b)
+Returns the largest of two numbers.
+Non-finite or non-numeric values are coerced to zero.
+
+```javascript
+const lolite = require("lolite.add")
+const result = lolite.max(5, 10)
+// result: 10
+
+const coercedMax = lolite.max(-5, Infinity)
+// result: 0 (comparing -5 and 0)
+```
+
+### min(a, b)
+Returns the smallest of two numbers.
+Non-finite or non-numeric values are coerced to zero.
+
+```javascript
+const lolite = require("lolite.add")
+const result = lolite.min(5, 10)
+// result: 5
+
+const coercedMin = lolite.min(5, "garbage")
+// result: 0 (comparing 5 and 0)
+```
+
+### clamp(value, lower, upper)
+Restricts a value to be within the specified bounds.
+Non-finite or non-numeric values are coerced to zero.
+
+Note: If lower bound exceeds upper bound after coercion, the function prioritizes the lower bound.
+```javascript
+const lolite = require("lolite.add")
+const result = lolite.clamp(5, 1, 10)
+// result: 5
+
+const capped = lolite.clamp(15, 1, 10)
+// result: 10
+
+const raised = lolite.clamp(-5, 1, 10)
+// result: 1
+
+const coercedClamp = lolite.clamp(Infinity, "garbage", NaN)
+// result: 0 (0 clamped between 0 and 0)
+```
+

package/package.json

@@ -1,59 +1,50 @@
 {
   "name": "lolite.add",
-  "version": "1.1.7",
-  "description": "Enterprise-grade add utility from the LoLite suite",
-  "main": "index.js",
-  "author": "10x'ly Made Software Ventures AB",
+  "version": "1.1.9",
+  "main": "src/lib/add.js",
   "license": "EGPSL10X-1.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/enterprise-npm-ai/lolite.git"
-  },
-  "bugs": {
-    "url": "https://github.com/enterprise-npm-ai/lolite/issues"
-  },
-  "homepage": "https://github.com/enterprise-npm-ai/lolite#readme",
   "dependencies": {
-    "lodash.multiply": "^4.9.0",
-    "immediate-error": "^7.1.0",
-    "integer-values": "^2.0.0",
-    "is-not-integer": "^1.0.2",
-    "logtoconsole": "^1.0.7",
+    "get-intrinsic": "^1.3.1",
+    "construct-new": "^2.0.4",
+    "while2": "^2.0.2",
+    "iszero": "^1.0.0",
+    "countingup": "^0.3.0",
+    "@10xly/strict-equals": "^1.0.0",
+    "add-two-numbers2": "^1.0.0",
+    "array-includes": "^3.1.9",
+    "object.values": "^1.2.1",
+    "map-values": "^1.0.1",
     "false-value": "^2.0.6",
     "true-value": "^2.0.5",
-    "@is-(unknown)/is-false": "^1.5.0",
+    "for-each": "^0.3.5",
+    "yanoop": "^1.0.0",
+    "important-extremely-useful-classes": "^3.1.0",
+    "is-not-integer": "^1.0.2",
+    "immediate-error": "^7.1.0",
+    "core-js-pure": "^3.47.0",
+    "logtoconsole": "^1.0.7",
+    "lodash.multiply": "^4.9.0",
+    "integer-values": "^2.0.0",
+    "@not-js/not": "^1.1.0",
+    "es-logical-or-operator": "^1.0.0",
     "@is-(unknown)/is-true": "^1.5.0",
+    "@is-(unknown)/is-false": "^1.5.0",
     "array-filter": "^1.0.0",
-    "@10xly/strict-equals": "^1.0.0",
+    "pkg-with-failing-optional-dependency": "^1.0.1",
+    "is-positive": "^3.1.0",
+    "es-typeof": "^1.0.0",
     "@extremejs/utils": "^1.0.0-beta.22",
     "@positive-numbers/zero": "^3.0.0",
-    "es-typeof": "^1.0.0",
-    "get-intrinsic": "^1.3.1",
+    "hasown": "^2.0.2",
     "has-symbol-support-x": "^1.4.2",
     "has-tostringtag": "^1.0.2",
-    "hasown": "^2.0.2",
     "es-object-atoms": "^1.1.1",
-    "@not-js/not": "^1.1.0",
-    "array-includes": "^3.1.9",
-    "construct-new": "^2.0.4",
-    "es-logical-or-operator": "^1.0.0",
-    "for-each": "^0.3.5",
-    "important-extremely-useful-classes": "^3.1.0",
     "infinities": "^1.0.1",
-    "is-positive": "^3.1.0",
-    "iszero": "^1.0.0",
-    "map-values": "^1.0.1",
-    "object.values": "^1.2.1",
-    "pkg-with-failing-optional-dependency": "^1.0.1",
-    "yanoop": "^1.0.0",
     "@is-(unknown)/is-finite": "^1.0.0",
-    "es-logical-not-operator": "^1.0.0",
+    "@positive-numbers/one": "^3.0.0",
     "is-integer": "^1.0.7",
-    "literally": "^1.0.0",
+    "es-logical-not-operator": "^1.0.0",
     "not-not": "^1.0.2",
-    "@positive-numbers/one": "^3.0.0",
-    "add-two-numbers2": "^1.0.0",
-    "countingup": "^0.3.0",
-    "while2": "^2.0.2"
+    "literally": "^1.0.0"
   }
 }

package/{index.js → src/lib/add.js}

@@ -18,7 +18,7 @@ const number0 = require("@positive-numbers/zero")
 const number1 = require("@positive-numbers/one")
 const falseValue = require("false-value")
 
-const isNotInteger = require("./isNotInteger")
+const isNotInteger = require("../private/isNotInteger")
 
 function add(augend, addend) {
   // eslint-disable-next-line no-underscore-dangle

package/{and.js → src/lib/and.js}

@@ -1,5 +1,5 @@
 // eslint-disable-next-line camelcase
-const crash_program = require("./crash")
+const crash_program = require("../private/crash")
 const not = require("./not")
 
 function and(firstCondition, secondCondition) {

package/{isNumber.js → src/lib/isNumber.js}

@@ -11,7 +11,7 @@ const {
 } = require("important-extremely-useful-classes")
 const construct = require("construct-new")
 // eslint-disable-next-line camelcase
-const crash_program = require("./crash")
+const crash_program = require("../private/crash")
 const equal = require("@10xly/strict-equals"),
   notEqual = require("@not-js/not")(equal)
 // eslint-disable-next-line sonarjs/no-globals-shadowing

package/{not.js → src/lib/not.js}

@@ -2,7 +2,7 @@ const isTrue = require("@is-(unknown)/is-true")
 const isFalse = require("@is-(unknown)/is-false")
 const arrayFilter = require("array-filter")
 const trueValue = require("true-value")
-const possibilities = require("./arrayOfAllBooleans")
+const possibilities = require("../private/arrayOfAllBooleans")
 
 function not(value) {
   const result = arrayFilter(possibilities, (maybe) => {

package/{or.js → src/lib/or.js}

@@ -5,7 +5,7 @@
 const not = require("./not")
 const and = require("./and")
 // eslint-disable-next-line camelcase
-const crash_program = require("./crash")
+const crash_program = require("../private/crash")
 
 // eslint-disable-next-line init-declarations, no-unassigned-vars
 let cdefghijklmnopqrstuvwxyz