@helpers4/number 2.0.2 → 2.0.4

package/meta/api.json

@@ -1,6 +1,6 @@
 {
   "category": "number",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "functions": [
     {
       "name": "clamp",
@@ -46,12 +46,12 @@
     {
       "name": "correctFloat",
       "kind": "function",
-      "description": "Corrects floating-point arithmetic errors by rounding to a given number\nof significant digits. Useful after calculations that accumulate binary\nfloating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).\n\nThe default precision of 14 significant digits eliminates typical\nrounding noise for values in the range used by most applications.\nNote: for values whose integer part already consumes 14 or more digits\n(i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal\ndigits and will silently truncate them. Increase `precision` if you\nneed to correct drift in very large numbers.",
+      "description": "Corrects floating-point arithmetic errors by rounding to a given number\nof significant digits. Useful after calculations that accumulate binary\nfloating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).\n\nThe default precision of 14 significant digits eliminates typical\nrounding noise for values in the range used by most applications.\nNote: for values whose integer part already consumes 14 or more digits\n(i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal\ndigits and will silently truncate them. Increase `precision` if you\nneed to correct drift in very large numbers.\n\nNote: IEEE-754 doubles carry at most ~17 significant decimal digits.\nPrecision values above 17 pad with digits that reflect the underlying\nbinary representation rather than correcting drift.",
       "since": "2.0.2",
       "signatures": [
         {
           "signature": "correctFloat(value: number, precision: number): number",
-          "description": "Corrects floating-point arithmetic errors by rounding to a given number\nof significant digits. Useful after calculations that accumulate binary\nfloating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).\n\nThe default precision of 14 significant digits eliminates typical\nrounding noise for values in the range used by most applications.\nNote: for values whose integer part already consumes 14 or more digits\n(i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal\ndigits and will silently truncate them. Increase `precision` if you\nneed to correct drift in very large numbers.",
+          "description": "Corrects floating-point arithmetic errors by rounding to a given number\nof significant digits. Useful after calculations that accumulate binary\nfloating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).\n\nThe default precision of 14 significant digits eliminates typical\nrounding noise for values in the range used by most applications.\nNote: for values whose integer part already consumes 14 or more digits\n(i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal\ndigits and will silently truncate them. Increase `precision` if you\nneed to correct drift in very large numbers.\n\nNote: IEEE-754 doubles carry at most ~17 significant decimal digits.\nPrecision values above 17 pad with digits that reflect the underlying\nbinary representation rather than correcting drift.",
           "params": [
             {
               "name": "value",
@@ -61,7 +61,7 @@
             {
               "name": "precision",
               "type": "number",
-              "description": "Integer number of significant digits (default: 14)",
+              "description": "Integer number of significant digits between 1 and 100\n  (default: 14). Values above 17 are valid but expose binary noise beyond\n  IEEE-754's meaningful range.",
               "defaultValue": "14"
             }
           ],
@@ -85,6 +85,43 @@
       ],
       "sourceFile": "correctFloat.ts"
     },
+    {
+      "name": "extractNumber",
+      "kind": "function",
+      "description": "Extracts the first number embedded anywhere in a string, or passes through a `number`.\n\nUnlike a plain `parseFloat`/`parseInt`, the number does not need to be at the start of\nthe string: digits are searched for anywhere, so leading/trailing text (units, labels, ...)\nis ignored. A `-` before the digits and a scientific-notation suffix (`e`/`E`) are\ndisambiguated with ExtractNumberOptions.sign and ExtractNumberOptions.exponent.\n\nReturns `undefined` if no number can be found.",
+      "since": "2.0.4",
+      "signatures": [
+        {
+          "signature": "extractNumber(value: unknown, options: ExtractNumberOptions): number | undefined",
+          "description": "Extracts the first number embedded anywhere in a string, or passes through a `number`.\n\nUnlike a plain `parseFloat`/`parseInt`, the number does not need to be at the start of\nthe string: digits are searched for anywhere, so leading/trailing text (units, labels, ...)\nis ignored. A `-` before the digits and a scientific-notation suffix (`e`/`E`) are\ndisambiguated with ExtractNumberOptions.sign and ExtractNumberOptions.exponent.\n\nReturns `undefined` if no number can be found.",
+          "params": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "description": "The value to extract a number from"
+            },
+            {
+              "name": "options",
+              "type": "ExtractNumberOptions",
+              "description": "Options controlling sign and exponent disambiguation",
+              "defaultValue": "{}"
+            }
+          ],
+          "returns": {
+            "type": "number | undefined",
+            "description": "The extracted number, or `undefined` if none was found"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "extractNumber",
+          "description": "",
+          "code": "```ts\nextractNumber('16.5px')        // => 16.5\nextractNumber('.5rem')         // => 0.5   (leading-dot decimal)\nextractNumber('-.5')           // => -0.5  (leading-dot with sign)\nextractNumber('Wafer 10')      // => 10\nextractNumber('xxx-111')       // => 111   ('-' glued to text → separator)\nextractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)\nextractNumber('x-.5')          // => 0.5   ('-' glued to 'x' → separator; leading-dot decimal follows)\nextractNumber('-111')          // => -111  ('-' at the start of the string → sign)\nextractNumber('1e5 mol')       // => 100000\nextractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)\nextractNumber('no number')     // => undefined\nextractNumber(42)              // => 42\n```"
+        }
+      ],
+      "sourceFile": "extractNumber.ts"
+    },
     {
       "name": "formatCompact",
       "kind": "function",
@@ -208,14 +245,141 @@
           "code": "inRange(5, 1, 10, { inclusive: 'none' })  // => true\ninRange(1, 1, 10, { inclusive: 'none' })  // => false\ninRange(10, 1, 10, { inclusive: 'none' }) // => false"
         }
       ],
-      "sourceFile": "inRange.ts",
-      "relatedTypes": [
+      "sourceFile": "inRange.ts"
+    },
+    {
+      "name": "isEven",
+      "kind": "function",
+      "description": "Checks if a value is an even integer.\n\nReturns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and odd integers.",
+      "since": "2.0.3",
+      "signatures": [
+        {
+          "signature": "isEven(value: unknown): value is number",
+          "description": "Checks if a value is an even integer.\n\nReturns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and odd integers.",
+          "params": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "description": "The value to check"
+            }
+          ],
+          "returns": {
+            "type": "value is number",
+            "description": "`true` if value is an integer divisible by 2"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Check if a number is even",
+          "description": "Returns true for integers divisible by 2, false otherwise.",
+          "code": "isEven(4)   // => true\nisEven(0)   // => true\nisEven(3)   // => false\nisEven(1.5) // => false  (not an integer)"
+        },
+        {
+          "title": "Filter even numbers from an array",
+          "description": "Use as a predicate in .filter() to extract even integers.",
+          "code": "const nums = [1, 2, 3, 4, 5, 6];\nnums.filter(isEven)\n// => [2, 4, 6]"
+        }
+      ],
+      "sourceFile": "isEven.ts"
+    },
+    {
+      "name": "isNegative",
+      "kind": "function",
+      "description": "Checks if a value is a number less than 0.\n\nReturns `false` for `NaN`, `0`, positive numbers, and non-number types.",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "isNegative(value: unknown): value is number",
+          "description": "Checks if a value is a number less than 0.\n\nReturns `false` for `NaN`, `0`, positive numbers, and non-number types.",
+          "params": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "description": "The value to check"
+            }
+          ],
+          "returns": {
+            "type": "value is number",
+            "description": "True if value is a negative number"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "isNegative",
+          "description": "",
+          "code": "```ts\nisNegative(-1)        // => true\nisNegative(-0.5)      // => true\nisNegative(-Infinity) // => true\nisNegative(0)         // => false\nisNegative(1)         // => false\nisNegative(NaN)       // => false\n```"
+        }
+      ],
+      "sourceFile": "isNegative.ts"
+    },
+    {
+      "name": "isOdd",
+      "kind": "function",
+      "description": "Checks if a value is an odd integer.\n\nReturns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and even integers.",
+      "since": "2.0.3",
+      "signatures": [
+        {
+          "signature": "isOdd(value: unknown): value is number",
+          "description": "Checks if a value is an odd integer.\n\nReturns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and even integers.",
+          "params": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "description": "The value to check"
+            }
+          ],
+          "returns": {
+            "type": "value is number",
+            "description": "`true` if value is an integer not divisible by 2"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Check if a number is odd",
+          "description": "Returns true for integers not divisible by 2, false otherwise.",
+          "code": "isOdd(3)   // => true\nisOdd(1)   // => true\nisOdd(2)   // => false\nisOdd(0)   // => false\nisOdd(1.5) // => false  (not an integer)"
+        },
         {
-          "name": "InRangeOptions",
-          "description": "Options for inRange.",
-          "typeDefinition": "interface InRangeOptions {\n  inclusive?: \"min\" | \"max\" | \"both\" | \"none\";\n}"
+          "title": "Filter odd numbers from an array",
+          "description": "Use as a predicate in .filter() to extract odd integers.",
+          "code": "const nums = [1, 2, 3, 4, 5, 6];\nnums.filter(isOdd)\n// => [1, 3, 5]"
         }
-      ]
+      ],
+      "sourceFile": "isOdd.ts"
+    },
+    {
+      "name": "isPositive",
+      "kind": "function",
+      "description": "Checks if a value is a number greater than 0.\n\nReturns `false` for `NaN`, `0`, negative numbers, and non-number types.",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "isPositive(value: unknown): value is number",
+          "description": "Checks if a value is a number greater than 0.\n\nReturns `false` for `NaN`, `0`, negative numbers, and non-number types.",
+          "params": [
+            {
+              "name": "value",
+              "type": "unknown",
+              "description": "The value to check"
+            }
+          ],
+          "returns": {
+            "type": "value is number",
+            "description": "True if value is a positive number"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "isPositive",
+          "description": "",
+          "code": "```ts\nisPositive(42)       // => true\nisPositive(0.1)      // => true\nisPositive(Infinity) // => true\nisPositive(0)        // => false\nisPositive(-1)       // => false\nisPositive(NaN)      // => false\n```"
+        }
+      ],
+      "sourceFile": "isPositive.ts"
     },
     {
       "name": "lerp",
@@ -263,37 +427,6 @@
       ],
       "sourceFile": "lerp.ts"
     },
-    {
-      "name": "mean",
-      "kind": "function",
-      "description": "Calculates the arithmetic mean (average) of an array of numbers.\nReturns `NaN` for an empty array.\n\nPairs with sum for aggregate operations.",
-      "since": "2.0.0",
-      "signatures": [
-        {
-          "signature": "mean(array: readonly number[]): number",
-          "description": "Calculates the arithmetic mean (average) of an array of numbers.\nReturns `NaN` for an empty array.\n\nPairs with sum for aggregate operations.",
-          "params": [
-            {
-              "name": "array",
-              "type": "readonly number[]",
-              "description": "The array of numbers to average"
-            }
-          ],
-          "returns": {
-            "type": "number",
-            "description": "The arithmetic mean, or `NaN` if the array is empty"
-          }
-        }
-      ],
-      "examples": [
-        {
-          "title": "Average a list of numbers",
-          "description": "Returns the arithmetic mean of the array; NaN for empty arrays.",
-          "code": "mean([1, 2, 3, 4])  // => 2.5\nmean([10, 20, 30])  // => 20\nmean([])            // => NaN"
-        }
-      ],
-      "sourceFile": "mean.ts"
-    },
     {
       "name": "randomBetween",
       "kind": "function",
@@ -405,42 +538,6 @@
         }
       ],
       "sourceFile": "roundTo.ts"
-    },
-    {
-      "name": "sum",
-      "kind": "function",
-      "description": "Calculates the sum of an array of numbers.",
-      "since": "2.0.0",
-      "signatures": [
-        {
-          "signature": "sum(array: readonly number[]): number",
-          "description": "Calculates the sum of an array of numbers.",
-          "params": [
-            {
-              "name": "array",
-              "type": "readonly number[]",
-              "description": "The array of numbers to sum"
-            }
-          ],
-          "returns": {
-            "type": "number",
-            "description": "The sum of all values"
-          }
-        }
-      ],
-      "examples": [
-        {
-          "title": "Sum numbers",
-          "description": "Calculates the sum of an array of numbers.",
-          "code": "sum([1, 2, 3, 4])\n// => 10"
-        },
-        {
-          "title": "Sum with negative numbers",
-          "description": "Handles negative numbers correctly.",
-          "code": "sum([10, -3, 5, -2])\n// => 10"
-        }
-      ],
-      "sourceFile": "sum.ts"
     }
   ]
 }

package/meta/examples.json

@@ -26,6 +26,16 @@
         }
       ]
     },
+    {
+      "name": "extractNumber",
+      "examples": [
+        {
+          "title": "extractNumber",
+          "description": "",
+          "code": "```ts\nextractNumber('16.5px')        // => 16.5\nextractNumber('.5rem')         // => 0.5   (leading-dot decimal)\nextractNumber('-.5')           // => -0.5  (leading-dot with sign)\nextractNumber('Wafer 10')      // => 10\nextractNumber('xxx-111')       // => 111   ('-' glued to text → separator)\nextractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)\nextractNumber('x-.5')          // => 0.5   ('-' glued to 'x' → separator; leading-dot decimal follows)\nextractNumber('-111')          // => -111  ('-' at the start of the string → sign)\nextractNumber('1e5 mol')       // => 100000\nextractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)\nextractNumber('no number')     // => undefined\nextractNumber(42)              // => 42\n```"
+        }
+      ]
+    },
     {
       "name": "formatCompact",
       "examples": [
@@ -66,6 +76,56 @@
         }
       ]
     },
+    {
+      "name": "isEven",
+      "examples": [
+        {
+          "title": "Check if a number is even",
+          "description": "Returns true for integers divisible by 2, false otherwise.",
+          "code": "isEven(4)   // => true\nisEven(0)   // => true\nisEven(3)   // => false\nisEven(1.5) // => false  (not an integer)"
+        },
+        {
+          "title": "Filter even numbers from an array",
+          "description": "Use as a predicate in .filter() to extract even integers.",
+          "code": "const nums = [1, 2, 3, 4, 5, 6];\nnums.filter(isEven)\n// => [2, 4, 6]"
+        }
+      ]
+    },
+    {
+      "name": "isNegative",
+      "examples": [
+        {
+          "title": "isNegative",
+          "description": "",
+          "code": "```ts\nisNegative(-1)        // => true\nisNegative(-0.5)      // => true\nisNegative(-Infinity) // => true\nisNegative(0)         // => false\nisNegative(1)         // => false\nisNegative(NaN)       // => false\n```"
+        }
+      ]
+    },
+    {
+      "name": "isOdd",
+      "examples": [
+        {
+          "title": "Check if a number is odd",
+          "description": "Returns true for integers not divisible by 2, false otherwise.",
+          "code": "isOdd(3)   // => true\nisOdd(1)   // => true\nisOdd(2)   // => false\nisOdd(0)   // => false\nisOdd(1.5) // => false  (not an integer)"
+        },
+        {
+          "title": "Filter odd numbers from an array",
+          "description": "Use as a predicate in .filter() to extract odd integers.",
+          "code": "const nums = [1, 2, 3, 4, 5, 6];\nnums.filter(isOdd)\n// => [1, 3, 5]"
+        }
+      ]
+    },
+    {
+      "name": "isPositive",
+      "examples": [
+        {
+          "title": "isPositive",
+          "description": "",
+          "code": "```ts\nisPositive(42)       // => true\nisPositive(0.1)      // => true\nisPositive(Infinity) // => true\nisPositive(0)        // => false\nisPositive(-1)       // => false\nisPositive(NaN)      // => false\n```"
+        }
+      ]
+    },
     {
       "name": "lerp",
       "examples": [
@@ -81,16 +141,6 @@
         }
       ]
     },
-    {
-      "name": "mean",
-      "examples": [
-        {
-          "title": "Average a list of numbers",
-          "description": "Returns the arithmetic mean of the array; NaN for empty arrays.",
-          "code": "mean([1, 2, 3, 4])  // => 2.5\nmean([10, 20, 30])  // => 20\nmean([])            // => NaN"
-        }
-      ]
-    },
     {
       "name": "randomBetween",
       "examples": [
@@ -120,21 +170,6 @@
           "code": "roundTo(3.7, 0)\n// => 4"
         }
       ]
-    },
-    {
-      "name": "sum",
-      "examples": [
-        {
-          "title": "Sum numbers",
-          "description": "Calculates the sum of an array of numbers.",
-          "code": "sum([1, 2, 3, 4])\n// => 10"
-        },
-        {
-          "title": "Sum with negative numbers",
-          "description": "Handles negative numbers correctly.",
-          "code": "sum([10, -3, 5, -2])\n// => 10"
-        }
-      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/number",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for number.",
   "author": "baxyz <baxy@etik.com>",
   "license": "LGPL-3.0",
@@ -29,14 +29,17 @@
     "number",
     "clamp",
     "correctFloat",
+    "extractNumber",
     "formatCompact",
     "formatSize",
     "inRange",
+    "isEven",
+    "isNegative",
+    "isOdd",
+    "isPositive",
     "lerp",
-    "mean",
     "random",
-    "roundTo",
-    "sum"
+    "roundTo"
   ],
   "files": [
     "lib/index.js",