@bitbybit-dev/base 0.20.13 → 0.21.0

package/lib/api/services/logic.js

@@ -3,7 +3,8 @@
  */
 export class Logic {
     /**
-     * Creates a boolean value - true or false
+     * Creates and returns a boolean value (pass-through for boolean input).
+     * Example: true → true, false → false
      * @param inputs a true or false boolean
      * @returns boolean
      * @group create
@@ -14,7 +15,8 @@ export class Logic {
         return inputs.boolean;
     }
     /**
-     * Creates a random boolean list of predefined length
+     * Generates a random boolean list where each value has a threshold chance of being true.
+     * Example: length=5, threshold=0.7 → might produce [true, true, false, true, true]
      * @param inputs a length and a threshold for randomization of true values
      * @returns booleans
      * @group create
@@ -29,10 +31,10 @@ export class Logic {
         return booleans;
     }
     /**
-     * Creates a random boolean list of true and false values based on a list of numbers.
-     * All values between true threshold will be true, all values above false threshold will be false,
-     * and the rest will be distributed between true and false based on the number of levels in a gradient pattern.
-     * That means that the closer the number gets to the false threshold the bigger the chance will be to get random false value.
+     * Converts numbers to booleans using two thresholds with gradient randomization between them.
+     * Values below trueThreshold → always true, above falseThreshold → always false.
+     * Between thresholds → probability gradient (closer to false threshold = higher chance of false).
+     * Example: [0.1, 0.4, 0.6, 0.9] with thresholds [0.3, 0.7] → [true, gradient, gradient, false]
      * @param inputs a length and a threshold for randomization of true values
      * @returns booleans
      * @group create
@@ -65,7 +67,9 @@ export class Logic {
         return booleans;
     }
     /**
-     * Creates a boolean list based on a list of numbers and a threshold.
+     * Converts numbers to booleans based on a threshold (below threshold → true, above → false).
+     * Can be inverted to flip the logic.
+     * Example: [0.3, 0.7, 0.5] with threshold=0.6 → [true, false, true]
      * @param inputs a length and a threshold for randomization of true values
      * @returns booleans
      * @group create
@@ -88,7 +92,9 @@ export class Logic {
         return booleans;
     }
     /**
-     * Creates a boolean list based on a list of numbers and a gap thresholds. Gap thresholds are pairs of numbers that define a range of numbers that will be true.
+     * Converts numbers to booleans using multiple range thresholds (gaps define true ranges).
+     * Values within any gap range → true, outside all gaps → false. Can be inverted.
+     * Example: [0.2, 0.5, 0.8] with gaps [[0.3, 0.6], [0.7, 0.9]] → [false, true, true]
      * @param inputs a length and a threshold for randomization of true values
      * @returns booleans
      * @group create
@@ -117,7 +123,8 @@ export class Logic {
         return booleans;
     }
     /**
-     * Apply not operator on the boolean
+     * Applies NOT operator to flip a boolean value.
+     * Example: true → false, false → true
      * @param inputs a true or false boolean
      * @returns boolean
      * @group edit
@@ -128,7 +135,8 @@ export class Logic {
         return !inputs.boolean;
     }
     /**
-     * Apply not operator on a list of booleans
+     * Applies NOT operator to flip all boolean values in a list.
+     * Example: [true, false, true] → [false, true, false]
      * @param inputs a list of true or false booleans
      * @returns booleans
      * @group edit
@@ -139,7 +147,8 @@ export class Logic {
         return inputs.booleans.map(b => !b);
     }
     /**
-     * Does comparison between first and second values
+     * Compares two values using various operators (==, !=, ===, !==, <, <=, >, >=).
+     * Example: 5 > 3 → true, 'hello' === 'world' → false
      * @param inputs two values to be compared
      * @returns Result of the comparison
      * @group operations
@@ -169,7 +178,8 @@ export class Logic {
         }
     }
     /**
-     * Transmits a value if boolean provided is true and undefined if boolean provided is false
+     * Conditionally passes a value through if boolean is true, otherwise returns undefined.
+     * Example: value=42, boolean=true → 42, value=42, boolean=false → undefined
      * @param inputs a value and a boolean value
      * @returns value or undefined
      * @group operations
@@ -180,7 +190,8 @@ export class Logic {
         return inputs.boolean ? inputs.value : undefined;
     }
     /**
-     * Returns first defined value out of two
+     * Returns the first defined (non-undefined) value from two options (fallback pattern).
+     * Example: value1=42, value2=10 → 42, value1=undefined, value2=10 → 10
      * @param inputs two values
      * @returns value or undefined
      * @group operations

package/lib/api/services/math.d.ts

@@ -4,7 +4,8 @@ import * as Inputs from "../inputs";
  */
 export declare class MathBitByBit {
     /**
-     * Creates a number
+     * Creates and returns a number value (pass-through for number input).
+     * Example: Input 42 → 42, Input 3.14 → 3.14
      * @param inputs a number to be created
      * @returns number
      * @group create
@@ -13,7 +14,8 @@ export declare class MathBitByBit {
      */
     number(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Does basic math operations
+     * Performs basic arithmetic operations on two numbers (add, subtract, multiply, divide, power, modulus).
+     * Example: 5 + 3 → 8, 10 % 3 → 1, 2 ^ 3 → 8
      * @param inputs two numbers and operator
      * @returns Result of math operation action
      * @group operations
@@ -22,7 +24,8 @@ export declare class MathBitByBit {
      */
     twoNrOperation(inputs: Inputs.Math.ActionOnTwoNumbersDto): number;
     /**
-     * Does modulus operation
+     * Calculates the remainder after division (modulus operation).
+     * Example: 10 % 3 → 1, 17 % 5 → 2
      * @param inputs two numbers and operator
      * @returns Result of modulus operation
      * @group operations
@@ -31,7 +34,8 @@ export declare class MathBitByBit {
      */
     modulus(inputs: Inputs.Math.ModulusDto): number;
     /**
-     * Does rounding to decimals
+     * Rounds a number to specified decimal places.
+     * Example: 1.32156 with 3 decimals returns 1.322
      * @param inputs a number and decimal places
      * @returns Result of rounding
      * @group operations
@@ -40,7 +44,18 @@ export declare class MathBitByBit {
      */
     roundToDecimals(inputs: Inputs.Math.RoundToDecimalsDto): number;
     /**
-     * Does basic math operations on one number
+     * Rounds a number to specified decimal places and removes trailing zeros.
+     * Example: 1.32156 with 3 decimals returns 1.322, but 1.320000001 returns 1.32, and 1.000 returns 1
+     * @param inputs a number and decimal places
+     * @returns Result of rounding as a number without trailing zeros
+     * @group operations
+     * @shortname round trim zeros
+     * @drawable false
+     */
+    roundAndRemoveTrailingZeros(inputs: Inputs.Math.RoundToDecimalsDto): number;
+    /**
+     * Performs mathematical operations on a single number (absolute, negate, sqrt, trig functions, logarithms, etc.).
+     * Example: sqrt(5) → 2.236, abs(-3) → 3, sin(π/2) → 1
      * @param inputs one number and operator action
      * @returns Result of math operation
      * @group operations
@@ -49,7 +64,8 @@ export declare class MathBitByBit {
      */
     oneNrOperation(inputs: Inputs.Math.ActionOnOneNumberDto): number;
     /**
-    * Remaps a number from one range to another
+    * Maps a number from one range to another range proportionally.
+    * Example: 5 from [0,10] to [0,100] → 50, 0.5 from [0,1] to [-10,10] → 0
     * @param inputs one number and operator action
     * @returns Result of mapping
     * @group operations
@@ -58,7 +74,8 @@ export declare class MathBitByBit {
     */
     remap(inputs: Inputs.Math.RemapNumberDto): number;
     /**
-    * Creates a random number between 0 and 1
+    * Generates a random decimal number between 0 (inclusive) and 1 (exclusive).
+    * Example: Outputs like 0.342, 0.891, or any value in [0, 1)
     * @returns A random number between 0 and 1
     * @group generate
     * @shortname random 0 - 1
@@ -66,7 +83,8 @@ export declare class MathBitByBit {
     */
     random(): number;
     /**
-    * Creates a random number between low and high value
+    * Generates a random number within a specified range (low to high).
+    * Example: Range [0, 10] → outputs like 3.7, 8.2, or any value between 0 and 10
     * @param inputs low and high numbers
     * @returns A random number
     * @group generate
@@ -75,7 +93,8 @@ export declare class MathBitByBit {
     */
     randomNumber(inputs: Inputs.Math.RandomNumberDto): number;
     /**
-    * Creates random numbers between low and high values
+    * Generates multiple random numbers within a specified range.
+    * Example: Range [0, 10] with 3 items → [2.5, 7.1, 4.8]
     * @param inputs low and high numbers
     * @returns A list of random numbers
     * @group generate
@@ -84,7 +103,8 @@ export declare class MathBitByBit {
     */
     randomNumbers(inputs: Inputs.Math.RandomNumbersDto): number[];
     /**
-    * Creates a PI number
+    * Returns the mathematical constant π (pi) ≈ 3.14159.
+    * Example: Outputs 3.141592653589793
     * @returns A number PI
     * @group generate
     * @shortname π
@@ -92,7 +112,8 @@ export declare class MathBitByBit {
     */
     pi(): number;
     /**
-     * Rounds the number to decimal places
+     * Formats a number as a string with a fixed number of decimal places (always shows trailing zeros).
+     * Example: 3.14159 with 2 decimals → '3.14', 5 with 3 decimals → '5.000'
      * @param inputs a number to be rounded to decimal places
      * @returns number
      * @group operations
@@ -101,7 +122,8 @@ export declare class MathBitByBit {
      */
     toFixed(inputs: Inputs.Math.ToFixedDto): string;
     /**
-     * Adds two numbers
+     * Adds two numbers together.
+     * Example: 5 + 3 → 8, -2 + 7 → 5
      * @param inputs two numbers
      * @returns number
      * @group basics
@@ -110,7 +132,8 @@ export declare class MathBitByBit {
      */
     add(inputs: Inputs.Math.TwoNumbersDto): number;
     /**
-     * Subtracts two numbers
+     * Subtracts the second number from the first.
+     * Example: 10 - 3 → 7, 5 - 8 → -3
      * @param inputs two numbers
      * @returns number
      * @group basics
@@ -119,7 +142,8 @@ export declare class MathBitByBit {
      */
     subtract(inputs: Inputs.Math.TwoNumbersDto): number;
     /**
-     * Multiplies two numbers
+     * Multiplies two numbers together.
+     * Example: 5 × 3 → 15, -2 × 4 → -8
      * @param inputs two numbers
      * @returns number
      * @group basics
@@ -128,7 +152,8 @@ export declare class MathBitByBit {
      */
     multiply(inputs: Inputs.Math.TwoNumbersDto): number;
     /**
-     * Divides two numbers
+     * Divides the first number by the second.
+     * Example: 10 ÷ 2 → 5, 7 ÷ 2 → 3.5
      * @param inputs two numbers
      * @returns number
      * @group basics
@@ -137,7 +162,8 @@ export declare class MathBitByBit {
      */
     divide(inputs: Inputs.Math.TwoNumbersDto): number;
     /**
-     * Powers a number
+     * Raises the first number to the power of the second (exponentiation).
+     * Example: 2³ → 8, 5² → 25, 10⁻¹ → 0.1
      * @param inputs two numbers
      * @returns number
      * @group basics
@@ -146,7 +172,8 @@ export declare class MathBitByBit {
      */
     power(inputs: Inputs.Math.TwoNumbersDto): number;
     /**
-     * Gets the square root of a number
+     * Calculates the square root of a number.
+     * Example: √9 → 3, √2 → 1.414, √16 → 4
      * @param inputs a number
      * @returns number
      * @group basics
@@ -155,7 +182,8 @@ export declare class MathBitByBit {
      */
     sqrt(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Gets the absolute value of a number
+     * Returns the absolute value (removes negative sign, always positive or zero).
+     * Example: |-5| → 5, |3| → 3, |0| → 0
      * @param inputs a number
      * @returns number
      * @group basics
@@ -164,7 +192,8 @@ export declare class MathBitByBit {
      */
     abs(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Rounds a number
+     * Rounds a number to the nearest integer.
+     * Example: 3.7 → 4, 2.3 → 2, 5.5 → 6
      * @param inputs a number
      * @returns number
      * @group basics
@@ -173,7 +202,8 @@ export declare class MathBitByBit {
      */
     round(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Floors a number
+     * Rounds a number down to the nearest integer (toward negative infinity).
+     * Example: 3.7 → 3, -2.3 → -3, 5 → 5
      * @param inputs a number
      * @returns number
      * @group basics
@@ -182,7 +212,8 @@ export declare class MathBitByBit {
      */
     floor(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Ceils a number
+     * Rounds a number up to the nearest integer (toward positive infinity).
+     * Example: 3.2 → 4, -2.8 → -2, 5 → 5
      * @param inputs a number
      * @returns number
      * @group basics
@@ -191,7 +222,8 @@ export declare class MathBitByBit {
      */
     ceil(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Negates a number
+     * Negates a number (flips its sign: positive becomes negative, negative becomes positive).
+     * Example: 5 → -5, -3 → 3, 0 → 0
      * @param inputs a number
      * @returns number
      * @group basics
@@ -200,7 +232,8 @@ export declare class MathBitByBit {
      */
     negate(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Gets the natural logarithm of a number
+     * Calculates the natural logarithm (base e) of a number.
+     * Example: ln(2.718) → ~1, ln(7.389) → ~2, ln(1) → 0
      * @param inputs a number
      * @returns number
      * @group basics
@@ -209,7 +242,8 @@ export declare class MathBitByBit {
      */
     ln(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Gets the base 10 logarithm of a number
+     * Calculates the base 10 logarithm of a number.
+     * Example: log₁₀(100) → 2, log₁₀(1000) → 3, log₁₀(10) → 1
      * @param inputs a number
      * @returns number
      * @group basics
@@ -218,7 +252,8 @@ export declare class MathBitByBit {
      */
     log10(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Raises 10 to the power of a number
+     * Raises 10 to the power of the input number.
+     * Example: 10² → 100, 10³ → 1000, 10⁻¹ → 0.1
      * @param inputs a number
      * @returns number
      * @group basics
@@ -227,7 +262,8 @@ export declare class MathBitByBit {
      */
     tenPow(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Gets the sine of a number
+     * Calculates the sine of an angle in radians.
+     * Example: sin(0) → 0, sin(π/2) → 1, sin(π) → ~0
      * @param inputs a number
      * @returns number
      * @group basics
@@ -236,7 +272,8 @@ export declare class MathBitByBit {
      */
     sin(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Gets the cosine of a number
+     * Calculates the cosine of an angle in radians.
+     * Example: cos(0) → 1, cos(π/2) → ~0, cos(π) → -1
      * @param inputs a number
      * @returns number
      * @group basics
@@ -245,7 +282,8 @@ export declare class MathBitByBit {
      */
     cos(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Gets the tangent of a number
+     * Calculates the tangent of an angle in radians.
+     * Example: tan(0) → 0, tan(π/4) → ~1, tan(π/2) → infinity
      * @param inputs a number
      * @returns number
      * @group basics
@@ -254,7 +292,8 @@ export declare class MathBitByBit {
      */
     tan(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Gets the arcsine of a number
+     * Calculates the arcsine (inverse sine) in radians, returns angle whose sine is the input.
+     * Example: asin(0) → 0, asin(1) → π/2 (~1.57), asin(0.5) → π/6 (~0.524)
      * @param inputs a number
      * @returns number
      * @group basics
@@ -263,7 +302,8 @@ export declare class MathBitByBit {
      */
     asin(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Gets the arccosine of a number
+     * Calculates the arccosine (inverse cosine) in radians, returns angle whose cosine is the input.
+     * Example: acos(1) → 0, acos(0) → π/2 (~1.57), acos(-1) → π (~3.14)
      * @param inputs a number
      * @returns number
      * @group basics
@@ -272,7 +312,8 @@ export declare class MathBitByBit {
      */
     acos(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Gets the arctangent of a number
+     * Calculates the arctangent (inverse tangent) in radians, returns angle whose tangent is the input.
+     * Example: atan(0) → 0, atan(1) → π/4 (~0.785), atan(-1) → -π/4
      * @param inputs a number
      * @returns number
      * @group basics
@@ -281,7 +322,8 @@ export declare class MathBitByBit {
      */
     atan(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Gets the natural exponent of a number
+     * Calculates e raised to the power of the input (exponential function).
+     * Example: e⁰ → 1, e¹ → ~2.718, e² → ~7.389
      * @param inputs a number
      * @returns number
      * @group basics
@@ -290,7 +332,8 @@ export declare class MathBitByBit {
      */
     exp(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Converts degrees to radians
+     * Converts an angle from degrees to radians.
+     * Example: 180° → π (~3.14159), 90° → π/2 (~1.5708), 360° → 2π
      * @param inputs a number in degrees
      * @returns number
      * @group basics
@@ -299,7 +342,8 @@ export declare class MathBitByBit {
      */
     degToRad(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Converts radians to degrees
+     * Converts an angle from radians to degrees.
+     * Example: π → 180°, π/2 → 90°, 2π → 360°
      * @param inputs a number in radians
      * @returns number
      * @group basics
@@ -308,7 +352,9 @@ export declare class MathBitByBit {
      */
     radToDeg(inputs: Inputs.Math.NumberDto): number;
     /**
-     * Eases a number by providing x parameter 0-1 and a range of output values
+     * Applies an easing function to interpolate smoothly between min and max values.
+     * Example: x=0.5 from [0,100] with easeInQuad → applies quadratic acceleration curve
+     * Useful for smooth animations with various acceleration/deceleration curves.
      * @param inputs a number, min and max values, and ease type
      * @returns number
      * @group operations
@@ -316,6 +362,105 @@ export declare class MathBitByBit {
      * @drawable false
      */
     ease(inputs: Inputs.Math.EaseDto): number;
+    /**
+     * Constrains a value between a minimum and maximum value.
+     * Example: clamp(5, 0, 3) returns 3, clamp(-1, 0, 3) returns 0, clamp(1.5, 0, 3) returns 1.5
+     * @param inputs a number, min and max values
+     * @returns number clamped between min and max
+     * @group operations
+     * @shortname clamp
+     * @drawable false
+     */
+    clamp(inputs: Inputs.Math.ClampDto): number;
+    /**
+     * Linear interpolation between two values using parameter t (0 to 1).
+     * Example: From 0 to 100 at t=0.5 → 50, From 10 to 20 at t=0.25 → 12.5
+     * When t=0 returns start, when t=1 returns end. Useful for smooth transitions.
+     * @param inputs start value, end value, and interpolation parameter t
+     * @returns interpolated value
+     * @group operations
+     * @shortname lerp
+     * @drawable false
+     */
+    lerp(inputs: Inputs.Math.LerpDto): number;
+    /**
+     * Calculates the interpolation parameter t for a value between start and end (reverse of lerp).
+     * Example: Value 5 in range [0,10] → t=0.5, Value 2.5 in range [0,10] → t=0.25
+     * Returns what t value would produce the given value in a lerp. Useful for finding relative position.
+     * @param inputs start value, end value, and the value to find t for
+     * @returns interpolation parameter (typically 0-1)
+     * @group operations
+     * @shortname inverse lerp
+     * @drawable false
+     */
+    inverseLerp(inputs: Inputs.Math.InverseLerpDto): number;
+    /**
+     * Hermite interpolation with smooth acceleration and deceleration (smoother than linear lerp).
+     * Example: x=0 → 0, x=0.5 → 0.5, x=1 → 1 (but with smooth S-curve in between)
+     * Input is automatically clamped to [0,1]. Output eases in and out smoothly. Great for animations.
+     * @param inputs a number between 0 and 1
+     * @returns smoothly interpolated value
+     * @group operations
+     * @shortname smoothstep
+     * @drawable false
+     */
+    smoothstep(inputs: Inputs.Math.NumberDto): number;
+    /**
+     * Returns the sign of a number: -1 for negative, 0 for zero, 1 for positive.
+     * Example: -5 → -1, 0 → 0, 3.14 → 1
+     * Useful for determining direction or polarity.
+     * @param inputs a number
+     * @returns -1, 0, or 1
+     * @group operations
+     * @shortname sign
+     * @drawable false
+     */
+    sign(inputs: Inputs.Math.NumberDto): number;
+    /**
+     * Returns the fractional part of a number (removes integer part, keeps decimals).
+     * Example: 3.14 → 0.14, 5.9 → 0.9, -2.3 → 0.7
+     * Useful for wrapping values and creating repeating patterns.
+     * @param inputs a number
+     * @returns fractional part (always positive)
+     * @group operations
+     * @shortname fract
+     * @drawable false
+     */
+    fract(inputs: Inputs.Math.NumberDto): number;
+    /**
+     * Wraps a number within a specified range (creates repeating cycle).
+     * Example: 1.5 in range [0,1) → 0.5, -0.3 in range [0,1) → 0.7, 370° in range [0,360) → 10°
+     * Useful for angles, UVs, or any repeating domain. Like modulo but handles negatives properly.
+     * @param inputs a number, min and max values
+     * @returns wrapped value within range
+     * @group operations
+     * @shortname wrap
+     * @drawable false
+     */
+    wrap(inputs: Inputs.Math.WrapDto): number;
+    /**
+     * Creates a ping-pong (back-and-forth) effect that bounces a value between 0 and length.
+     * The value goes from 0→length, then back length→0, repeating this cycle.
+     * Example: With length=1: t=0→0, t=0.5→0.5, t=1→1 (peak), t=1.5→0.5, t=2→0, t=2.5→0.5 (repeats)
+     * Useful for creating bouncing animations like a ball or oscillating motion.
+     * @param inputs time value t and length
+     * @returns value bouncing between 0 and length
+     * @group operations
+     * @shortname ping pong
+     * @drawable false
+     */
+    pingPong(inputs: Inputs.Math.PingPongDto): number;
+    /**
+     * Moves a value toward a target by a maximum delta amount (never overshooting).
+     * Example: From 0 toward 10 by max 3 → 3, From 8 toward 10 by max 3 → 10 (reached)
+     * Useful for smooth movement with maximum speed limits.
+     * @param inputs current value, target value, and maximum delta
+     * @returns new value moved toward target
+     * @group operations
+     * @shortname move towards
+     * @drawable false
+     */
+    moveTowards(inputs: Inputs.Math.MoveTowardsDto): number;
     private easeInSine;
     private easeOutSine;
     private easeInOutSine;