@helpers4/number 2.0.0-alpha.1 → 2.0.0-alpha.11

package/README.md

@@ -9,12 +9,13 @@ A set of helpers for working with URLs.
 
 ## Documentation
 
-[https://helpers4.js.org/number](https://helpers4.js.org/number)
+[https://helpers4.dev/typescript/categories/number/](https://helpers4.dev/typescript/categories/number/)
 
 <!-- AUTOMATIC-METHODS -->
+- clamp
 - random
 - roundTo
-- clamp
+- sum
 <!-- /AUTOMATIC-METHODS -->
 
 ## See
@@ -23,6 +24,7 @@ A set of helpers for working with URLs.
 - [array](../array)
 - [date](../date)
 - [function](../function)
+- [math](../math)
 - [object](../object)
 - [observable](../observable)
 - [promise](../promise)
@@ -40,6 +42,7 @@ A set of helpers for working with URLs.
 | array | [@helpers4/array](https://www.npmjs.com/package/@helpers4/array) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/array) | Array manipulation utilities |
 | date | [@helpers4/date](https://www.npmjs.com/package/@helpers4/date) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/date) | date utilities |
 | function | [@helpers4/function](https://www.npmjs.com/package/@helpers4/function) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/function) | Function utilities and type guards |
+| math | [@helpers4/math](https://www.npmjs.com/package/@helpers4/math) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/math) | math utilities |
 | number | [@helpers4/number](https://www.npmjs.com/package/@helpers4/number) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/number) | number utilities |
 | object | [@helpers4/object](https://www.npmjs.com/package/@helpers4/object) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/object) | Object manipulation utilities |
 | observable | [@helpers4/observable](https://www.npmjs.com/package/@helpers4/observable) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/observable) | Observable utilities and combinators |

package/lib/index.d.ts

@@ -1,3 +1,68 @@
-export * from './random';
-export * from './roundTo';
-export * from './clamp';
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Clamps a number between min and max values
+ * @param value - The value to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Clamped value
+ * @since 1.9.0
+ */
+declare function clamp(value: number, min: number, max: number): number;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Generates a random number between min and max (inclusive)
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Random number between min and max
+ * @since 1.9.0
+ */
+declare function randomBetween(min: number, max: number): number;
+/**
+ * Generates a random integer between min and max (inclusive)
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Random integer between min and max
+ * @since 1.9.0
+ */
+declare function randomIntBetween(min: number, max: number): number;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Rounds a number to specified decimal places
+ * @param value - The number to round
+ * @param decimals - Number of decimal places
+ * @returns Rounded number
+ * @since 1.9.0
+ */
+declare function roundTo(value: number, decimals: number): number;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Calculates the sum of an array of numbers.
+ * @param array - The array of numbers to sum
+ * @returns The sum of all values
+ * @example
+ * sum([1, 2, 3, 4])
+ * // => 10
+ * @since 2.0.0
+ */
+declare function sum(array: readonly number[]): number;
+
+export { clamp, randomBetween, randomIntBetween, roundTo, sum };

package/lib/index.js

@@ -1,4 +1,85 @@
-// helpers/number/index.ts
-export * from "./random";
-export * from "./roundTo";
-export * from "./clamp";
+//#region helpers/number/clamp.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Clamps a number between min and max values
+* @param value - The value to clamp
+* @param min - Minimum value
+* @param max - Maximum value
+* @returns Clamped value
+* @since 1.9.0
+*/
+function clamp(value, min, max) {
+	return Math.min(Math.max(value, min), max);
+}
+//#endregion
+//#region helpers/number/random.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Generates a random number between min and max (inclusive)
+* @param min - Minimum value
+* @param max - Maximum value
+* @returns Random number between min and max
+* @since 1.9.0
+*/
+function randomBetween(min, max) {
+	return Math.random() * (max - min) + min;
+}
+/**
+* Generates a random integer between min and max (inclusive)
+* @param min - Minimum value
+* @param max - Maximum value
+* @returns Random integer between min and max
+* @since 1.9.0
+*/
+function randomIntBetween(min, max) {
+	return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+//#endregion
+//#region helpers/number/roundTo.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Rounds a number to specified decimal places
+* @param value - The number to round
+* @param decimals - Number of decimal places
+* @returns Rounded number
+* @since 1.9.0
+*/
+function roundTo(value, decimals) {
+	const multiplier = Math.pow(10, decimals);
+	return Math.round(value * multiplier) / multiplier;
+}
+//#endregion
+//#region helpers/number/sum.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Calculates the sum of an array of numbers.
+* @param array - The array of numbers to sum
+* @returns The sum of all values
+* @example
+* sum([1, 2, 3, 4])
+* // => 10
+* @since 2.0.0
+*/
+function sum(array) {
+	return array.reduce((acc, n) => acc + n, 0);
+}
+//#endregion
+export { clamp, randomBetween, randomIntBetween, roundTo, sum };
+
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../helpers/number/clamp.ts","../../../helpers/number/random.ts","../../../helpers/number/roundTo.ts","../../../helpers/number/sum.ts"],"sourcesContent":["/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Clamps a number between min and max values\n * @param value - The value to clamp\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Clamped value\n * @since 1.9.0\n */\nexport function clamp(value: number, min: number, max: number): number {\n  return Math.min(Math.max(value, min), max);\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Generates a random number between min and max (inclusive)\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Random number between min and max\n * @since 1.9.0\n */\nexport function randomBetween(min: number, max: number): number {\n  return Math.random() * (max - min) + min;\n}\n\n/**\n * Generates a random integer between min and max (inclusive)\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Random integer between min and max\n * @since 1.9.0\n */\nexport function randomIntBetween(min: number, max: number): number {\n  return Math.floor(Math.random() * (max - min + 1)) + min;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Rounds a number to specified decimal places\n * @param value - The number to round\n * @param decimals - Number of decimal places\n * @returns Rounded number\n * @since 1.9.0\n */\nexport function roundTo(value: number, decimals: number): number {\n  const multiplier = Math.pow(10, decimals);\n  return Math.round(value * multiplier) / multiplier;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Calculates the sum of an array of numbers.\n * @param array - The array of numbers to sum\n * @returns The sum of all values\n * @example\n * sum([1, 2, 3, 4])\n * // => 10\n * @since 2.0.0\n */\nexport function sum(array: readonly number[]): number {\n  return array.reduce((acc, n) => acc + n, 0);\n}\n"],"mappings":";;;;;;;;;;;;;;AAcA,SAAgB,MAAM,OAAe,KAAa,KAAqB;AACrE,QAAO,KAAK,IAAI,KAAK,IAAI,OAAO,IAAI,EAAE,IAAI;;;;;;;;;;;;;;;;ACF5C,SAAgB,cAAc,KAAa,KAAqB;AAC9D,QAAO,KAAK,QAAQ,IAAI,MAAM,OAAO;;;;;;;;;AAUvC,SAAgB,iBAAiB,KAAa,KAAqB;AACjE,QAAO,KAAK,MAAM,KAAK,QAAQ,IAAI,MAAM,MAAM,GAAG,GAAG;;;;;;;;;;;;;;;;ACZvD,SAAgB,QAAQ,OAAe,UAA0B;CAC/D,MAAM,aAAa,KAAK,IAAI,IAAI,SAAS;AACzC,QAAO,KAAK,MAAM,QAAQ,WAAW,GAAG;;;;;;;;;;;;;;;;;;ACA1C,SAAgB,IAAI,OAAkC;AACpD,QAAO,MAAM,QAAQ,KAAK,MAAM,MAAM,GAAG,EAAE"}

package/meta/api.json

@@ -0,0 +1,195 @@
+{
+  "category": "number",
+  "version": "2.0.0-alpha.11",
+  "functions": [
+    {
+      "name": "clamp",
+      "kind": "function",
+      "description": "Clamps a number between min and max values",
+      "since": "1.9.0",
+      "signatures": [
+        {
+          "signature": "clamp(value: number, min: number, max: number): number",
+          "description": "Clamps a number between min and max values",
+          "params": [
+            {
+              "name": "value",
+              "type": "number",
+              "description": "The value to clamp"
+            },
+            {
+              "name": "min",
+              "type": "number",
+              "description": "Minimum value"
+            },
+            {
+              "name": "max",
+              "type": "number",
+              "description": "Maximum value"
+            }
+          ],
+          "returns": {
+            "type": "number",
+            "description": "Clamped value"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Clamp a value within range",
+          "description": "Restricts a number to be within a min/max range.",
+          "code": "clamp(15, 0, 10)  // => 10\nclamp(-5, 0, 10)  // => 0\nclamp(5, 0, 10)   // => 5"
+        }
+      ],
+      "sourceFile": "clamp.ts"
+    },
+    {
+      "name": "randomBetween",
+      "kind": "function",
+      "description": "Generates a random number between min and max (inclusive)",
+      "since": "1.9.0",
+      "signatures": [
+        {
+          "signature": "randomBetween(min: number, max: number): number",
+          "description": "Generates a random number between min and max (inclusive)",
+          "params": [
+            {
+              "name": "min",
+              "type": "number",
+              "description": "Minimum value"
+            },
+            {
+              "name": "max",
+              "type": "number",
+              "description": "Maximum value"
+            }
+          ],
+          "returns": {
+            "type": "number",
+            "description": "Random number between min and max"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Generate a random float in range",
+          "description": "Returns a random number between min and max (inclusive).",
+          "code": "randomBetween(1, 10)\n// => e.g. 5.327..."
+        },
+        {
+          "title": "Generate a random integer in range",
+          "description": "Returns a random integer between min and max (inclusive).",
+          "code": "randomIntBetween(1, 6)\n// => e.g. 4"
+        }
+      ],
+      "sourceFile": "random.ts"
+    },
+    {
+      "name": "randomIntBetween",
+      "kind": "function",
+      "description": "Generates a random integer between min and max (inclusive)",
+      "since": "1.9.0",
+      "signatures": [
+        {
+          "signature": "randomIntBetween(min: number, max: number): number",
+          "description": "Generates a random integer between min and max (inclusive)",
+          "params": [
+            {
+              "name": "min",
+              "type": "number",
+              "description": "Minimum value"
+            },
+            {
+              "name": "max",
+              "type": "number",
+              "description": "Maximum value"
+            }
+          ],
+          "returns": {
+            "type": "number",
+            "description": "Random integer between min and max"
+          }
+        }
+      ],
+      "examples": [],
+      "sourceFile": "random.ts"
+    },
+    {
+      "name": "roundTo",
+      "kind": "function",
+      "description": "Rounds a number to specified decimal places",
+      "since": "1.9.0",
+      "signatures": [
+        {
+          "signature": "roundTo(value: number, decimals: number): number",
+          "description": "Rounds a number to specified decimal places",
+          "params": [
+            {
+              "name": "value",
+              "type": "number",
+              "description": "The number to round"
+            },
+            {
+              "name": "decimals",
+              "type": "number",
+              "description": "Number of decimal places"
+            }
+          ],
+          "returns": {
+            "type": "number",
+            "description": "Rounded number"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Round to 2 decimal places",
+          "description": "Rounds a floating-point number to the specified number of decimals.",
+          "code": "roundTo(3.14159, 2)\n// => 3.14"
+        },
+        {
+          "title": "Round to 0 decimal places",
+          "description": "Effectively rounds to the nearest integer.",
+          "code": "roundTo(3.7, 0)\n// => 4"
+        }
+      ],
+      "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

@@ -0,0 +1,60 @@
+{
+  "category": "number",
+  "functions": [
+    {
+      "name": "clamp",
+      "examples": [
+        {
+          "title": "Clamp a value within range",
+          "description": "Restricts a number to be within a min/max range.",
+          "code": "clamp(15, 0, 10)  // => 10\nclamp(-5, 0, 10)  // => 0\nclamp(5, 0, 10)   // => 5"
+        }
+      ]
+    },
+    {
+      "name": "randomBetween",
+      "examples": [
+        {
+          "title": "Generate a random float in range",
+          "description": "Returns a random number between min and max (inclusive).",
+          "code": "randomBetween(1, 10)\n// => e.g. 5.327..."
+        },
+        {
+          "title": "Generate a random integer in range",
+          "description": "Returns a random integer between min and max (inclusive).",
+          "code": "randomIntBetween(1, 6)\n// => e.g. 4"
+        }
+      ]
+    },
+    {
+      "name": "roundTo",
+      "examples": [
+        {
+          "title": "Round to 2 decimal places",
+          "description": "Rounds a floating-point number to the specified number of decimals.",
+          "code": "roundTo(3.14159, 2)\n// => 3.14"
+        },
+        {
+          "title": "Round to 0 decimal places",
+          "description": "Effectively rounds to the nearest integer.",
+          "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/meta/licenses.json

@@ -0,0 +1,4 @@
+{
+  "category": "number",
+  "dependencies": []
+}

package/meta/native-alternatives.json

@@ -0,0 +1,37 @@
+{
+  "category": "number",
+  "functions": [
+    {
+      "name": "min / max",
+      "libraries": [
+        "lodash",
+        "radashi",
+        "ramda"
+      ],
+      "native": "Math.min(...arr) / Math.max(...arr)",
+      "since": "ES1",
+      "example": "Math.min(...numbers)\nMath.max(...numbers)",
+      "notes": "For large arrays, prefer reduce to avoid stack overflow"
+    },
+    {
+      "name": "ceil / floor",
+      "libraries": [
+        "lodash"
+      ],
+      "native": "Math.ceil() / Math.floor()",
+      "since": "ES1",
+      "example": "Math.ceil(4.2)  // 5\nMath.floor(4.8)  // 4",
+      "notes": "No precision param natively; use roundTo from helpers4 for decimal precision"
+    },
+    {
+      "name": "toInt / toFloat",
+      "libraries": [
+        "radashi"
+      ],
+      "native": "parseInt(str, 10) / parseFloat(str)",
+      "since": "ES1",
+      "example": "parseInt('42px', 10)  // 42\nparseFloat('3.14')  // 3.14",
+      "notes": "Radashi adds default-value fallback on NaN"
+    }
+  ]
+}

package/package.json

@@ -1,35 +1,46 @@
 {
   "name": "@helpers4/number",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.11",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for number.",
   "author": "baxyz <baxy@etik.com>",
-  "license": "AGPL-3.0",
+  "license": "LGPL-3.0",
+  "homepage": "https://helpers4.dev/typescript/categories/number/",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/helpers4/helpers4.git"
+    "url": "git+https://github.com/helpers4/typescript.git"
   },
   "type": "module",
+  "sideEffects": false,
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
       "import": "./lib/index.js"
-    }
+    },
+    "./meta/api.json": "./meta/api.json",
+    "./meta/examples.json": "./meta/examples.json",
+    "./meta/licenses.json": "./meta/licenses.json",
+    "./package.json": "./package.json"
   },
   "keywords": [
     "helpers",
     "number",
+    "clamp",
     "random",
     "roundTo",
-    "clamp"
+    "sum"
   ],
   "files": [
     "lib/index.js",
     "lib/index.d.ts",
     "lib/index.js.map",
+    "meta/",
     "LICENSE.md",
     "package.json",
     "README.md"
-  ]
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }