@augment-vir/common 31.20.1 → 31.21.0

package/dist/augments/number/wrap-number.d.ts

@@ -1,8 +1,11 @@
-import { type MinMax } from '@augment-vir/core';
+import { type MinMax, type PartialWithUndefined } from '@augment-vir/core';
 /**
  * If the given value is outside the given min/max bounds, instead of clamping the number (as the
  * `clamp` function does), this function wraps the value around to the next bound (inclusive).
  *
+ * If `takeOverflow` is set to `true`, then any excess after wrapping is continually iterated over
+ * and wrapped again, potentially resulting in wrapping through the min/max bounds multiple times.
+ *
  * @category Number
  * @category Package : @augment-vir/common
  * @example
@@ -10,10 +13,19 @@ import { type MinMax } from '@augment-vir/core';
  * ```ts
  * import {wrapNumber} from '@augment-vir/common';
  *
- * wrapNumber({min: 0, max: 100, value: 101}); // 0
- * wrapNumber({min: 0, max: 100, value: -1}); // 100
+ * wrapNumber(101, {min: 0, max: 100}); // 0
+ * wrapNumber(-1, {min: 0, max: 100}); // 100
+ * wrapNumber(-7, {min: 0, max: 3, takeOverflow: true}); // 1
+ * wrapNumber(13, {min: 0, max: 3, takeOverflow: true}); // 1
  * ```
  *
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
-export declare function wrapNumber(value: number, minMax: Readonly<MinMax>): number;
+export declare function wrapNumber(value: number, minMax: Readonly<MinMax> & PartialWithUndefined<{
+    /**
+     * If `true`, the overflow of the wrap is added to the bound wrapped to.
+     *
+     * @default false
+     */
+    takeOverflow: boolean;
+}>): number;

package/dist/augments/number/wrap-number.js

@@ -3,6 +3,9 @@ import { ensureMinMax } from '@augment-vir/core';
  * If the given value is outside the given min/max bounds, instead of clamping the number (as the
  * `clamp` function does), this function wraps the value around to the next bound (inclusive).
  *
+ * If `takeOverflow` is set to `true`, then any excess after wrapping is continually iterated over
+ * and wrapped again, potentially resulting in wrapping through the min/max bounds multiple times.
+ *
  * @category Number
  * @category Package : @augment-vir/common
  * @example
@@ -10,19 +13,33 @@ import { ensureMinMax } from '@augment-vir/core';
  * ```ts
  * import {wrapNumber} from '@augment-vir/common';
  *
- * wrapNumber({min: 0, max: 100, value: 101}); // 0
- * wrapNumber({min: 0, max: 100, value: -1}); // 100
+ * wrapNumber(101, {min: 0, max: 100}); // 0
+ * wrapNumber(-1, {min: 0, max: 100}); // 100
+ * wrapNumber(-7, {min: 0, max: 3, takeOverflow: true}); // 1
+ * wrapNumber(13, {min: 0, max: 3, takeOverflow: true}); // 1
  * ```
  *
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function wrapNumber(value, minMax) {
     const { min, max } = ensureMinMax(minMax);
-    if (value > max) {
-        return min;
+    if (minMax.takeOverflow) {
+        const diff = max - min + 1;
+        const offset = (value - min) % diff;
+        if (offset < 0) {
+            return min + diff + offset;
+        }
+        else {
+            return min + offset;
+        }
     }
-    else if (value < min) {
-        return max;
+    else {
+        if (value > max) {
+            return min;
+        }
+        else if (value < min) {
+            return max;
+        }
+        return value;
     }
-    return value;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/common",
-    "version": "31.20.1",
+    "version": "31.21.0",
     "description": "A collection of augments, helpers types, functions, and classes for any JavaScript environment.",
     "keywords": [
         "augment",
@@ -40,8 +40,8 @@
         "test:web": "virmator --no-deps test web"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.20.1",
-        "@augment-vir/core": "^31.20.1",
+        "@augment-vir/assert": "^31.21.0",
+        "@augment-vir/core": "^31.21.0",
         "@date-vir/duration": "^7.3.1",
         "ansi-styles": "^6.2.1",
         "json5": "^2.2.3",
@@ -50,7 +50,7 @@
     },
     "devDependencies": {
         "@web/dev-server-esbuild": "^1.0.4",
-        "@web/test-runner": "^0.20.1",
+        "@web/test-runner": "^0.20.2",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.0",
         "@web/test-runner-visual-regression": "^0.10.0",