@bitbybit-dev/base 0.20.13 → 0.20.14

package/lib/api/services/lists.js

@@ -7,7 +7,8 @@ import * as Inputs from "../inputs";
  */
 export class Lists {
     /**
-     * Gets an item from the list by using a 0 based index
+     * Gets an item from the list at a specific position using zero-based indexing.
+     * Example: From [10, 20, 30, 40], getting index 2 returns 30
      * @param inputs a list and an index
      * @returns item
      * @group get
@@ -28,7 +29,52 @@ export class Lists {
         return result;
     }
     /**
-     * Gets items randomly by using a threshold
+     * Gets the first item from the list.
+     * Example: From [10, 20, 30, 40], returns 10
+     * @param inputs a list
+     * @returns first item
+     * @group get
+     * @shortname first item
+     * @drawable false
+     */
+    getFirstItem(inputs) {
+        if (inputs.list.length === 0) {
+            throw new Error("List is empty");
+        }
+        let result;
+        if (inputs.clone) {
+            result = structuredClone(inputs.list[0]);
+        }
+        else {
+            result = inputs.list[0];
+        }
+        return result;
+    }
+    /**
+     * Gets the last item from the list.
+     * Example: From [10, 20, 30, 40], returns 40
+     * @param inputs a list
+     * @returns last item
+     * @group get
+     * @shortname last item
+     * @drawable false
+     */
+    getLastItem(inputs) {
+        if (inputs.list.length === 0) {
+            throw new Error("List is empty");
+        }
+        let result;
+        if (inputs.clone) {
+            result = structuredClone(inputs.list[inputs.list.length - 1]);
+        }
+        else {
+            result = inputs.list[inputs.list.length - 1];
+        }
+        return result;
+    }
+    /**
+     * Randomly keeps items from the list based on a probability threshold (0 to 1).
+     * Example: From [1, 2, 3, 4, 5] with threshold 0.5, might return [1, 3, 5] (50% chance for each item)
      * @param inputs a list and a threshold for randomization of items to remove
      * @returns list with remaining items
      * @group get
@@ -49,7 +95,8 @@ export class Lists {
         return newList;
     }
     /**
-       * Gets a sub list between start and end indexes
+       * Extracts a portion of the list between start and end positions (end is exclusive).
+       * Example: From [10, 20, 30, 40, 50] with start=1 and end=4, returns [20, 30, 40]
        * @param inputs a list and start and end indexes
        * @returns sub list
        * @group get
@@ -67,7 +114,9 @@ export class Lists {
         return result;
     }
     /**
-     * Gets nth item in the list
+     * Gets every nth item from the list, starting from an optional offset position.
+     * Example: From [0, 1, 2, 3, 4, 5, 6, 7, 8] with nth=3 and offset=0, returns [0, 3, 6]
+     * Example: From [0, 1, 2, 3, 4, 5, 6, 7, 8] with nth=2 and offset=1, returns [1, 3, 5, 7]
      * @param inputs a list and index
      * @returns list with filtered items
      * @group get
@@ -88,7 +137,8 @@ export class Lists {
         return result;
     }
     /**
-     * Gets elements by pattern
+     * Filters items from the list using a repeating true/false pattern.
+     * Example: From [0, 1, 2, 3, 4, 5] with pattern [true, true, false], returns [0, 1, 3, 4] (keeps items where pattern is true)
      * @param inputs a list and index
      * @returns list with filtered items
      * @group get
@@ -125,7 +175,8 @@ export class Lists {
         return result;
     }
     /**
-     * Merge elements of lists on a given level and flatten output if needed
+     * Merges elements from multiple lists at a specific nesting level, grouping elements by position.
+     * Example: From [[0, 1, 2], [3, 4, 5]] at level 0, returns [[0, 3], [1, 4], [2, 5]]
      * @param inputs lists, level and flatten data
      * @returns list with merged lists and flattened lists
      * @group get
@@ -175,7 +226,8 @@ export class Lists {
         return final;
     }
     /**
-     * Gets the longest list length from the list of lists
+     * Finds the length of the longest list among multiple lists.
+     * Example: From [[1, 2], [3, 4, 5, 6], [7]], returns 4 (length of [3, 4, 5, 6])
      * @param inputs a list of lists
      * @returns number of max length
      * @group get
@@ -197,7 +249,8 @@ export class Lists {
         }
     }
     /**
-     * Reverse the list
+     * Reverses the order of items in the list.
+     * Example: From [1, 2, 3, 4, 5], returns [5, 4, 3, 2, 1]
      * @param inputs a list and an index
      * @returns item
      * @group edit
@@ -212,7 +265,28 @@ export class Lists {
         return res.reverse();
     }
     /**
-     * Flip 2d lists - every nth element of each list will form a separate list
+     * Randomly rearranges all items in the list (using Fisher-Yates algorithm).
+     * Example: From [1, 2, 3, 4, 5], might return [3, 1, 5, 2, 4] (order varies each time)
+     * @param inputs a list
+     * @returns shuffled list
+     * @group edit
+     * @shortname shuffle
+     * @drawable false
+     */
+    shuffle(inputs) {
+        let res = inputs.list;
+        if (inputs.clone) {
+            res = structuredClone(inputs.list);
+        }
+        for (let i = res.length - 1; i > 0; i--) {
+            const j = Math.floor(Math.random() * (i + 1));
+            [res[i], res[j]] = [res[j], res[i]];
+        }
+        return res;
+    }
+    /**
+     * Transposes a 2D list by swapping rows and columns (all sublists must be equal length).
+     * Example: From [[0, 1, 2], [3, 4, 5]], returns [[0, 3], [1, 4], [2, 5]]
      * @param inputs a list of lists to flip
      * @returns item
      * @group edit
@@ -248,7 +322,9 @@ export class Lists {
         }
     }
     /**
-     * Group in lists of n elements
+     * Splits the list into smaller lists of n elements each.
+     * Example: From [0, 1, 2, 3, 4, 5, 6, 7, 8] with n=3, returns [[0, 1, 2], [3, 4, 5], [6, 7, 8]]
+     * Example: From [0, 1, 2, 3, 4] with n=2 and keepRemainder=true, returns [[0, 1], [2, 3], [4]]
      * @param inputs a list
      * @returns items grouped in lists of n elements
      * @group edit
@@ -276,7 +352,32 @@ export class Lists {
         return groupElements(inputs);
     }
     /**
-     * Get the depth of the list
+     * Checks whether the list contains a specific item.
+     * Example: List [10, 20, 30, 40] with item 30 returns true, with item 50 returns false
+     * @param inputs a list and an item
+     * @returns true if item is in list
+     * @group get
+     * @shortname contains item
+     * @drawable false
+     */
+    includes(inputs) {
+        return inputs.list.includes(inputs.item);
+    }
+    /**
+     * Finds the position (index) of the first occurrence of an item in the list.
+     * Example: In [10, 20, 30, 20, 40], finding 20 returns 1 (first occurrence), finding 50 returns -1 (not found)
+     * @param inputs a list and an item
+     * @returns index of the item or -1 if not found
+     * @group get
+     * @shortname find index
+     * @drawable false
+     */
+    findIndex(inputs) {
+        return inputs.list.indexOf(inputs.item);
+    }
+    /**
+     * Determines the maximum nesting level (depth) of a list structure.
+     * Example: [1, 2, 3] has depth 1, [[1, 2], [3, 4]] has depth 2, [[[1]]] has depth 3
      * @param inputs a list
      * @returns number of depth
      * @group get
@@ -306,7 +407,8 @@ export class Lists {
         return levels;
     }
     /**
-     * Gets the length of the list
+     * Returns the number of items in the list.
+     * Example: [10, 20, 30, 40, 50] returns 5, [] returns 0
      * @param inputs a length list
      * @returns a number
      * @group get
@@ -317,7 +419,8 @@ export class Lists {
         return inputs.list.length;
     }
     /**
-     * Add item to the list
+     * Inserts an item at a specific position in the list.
+     * Example: In [10, 20, 30, 40], adding 99 at index 2 gives [10, 20, 99, 30, 40]
      * @param inputs a list, item and an index
      * @returns list with added item
      * @group add
@@ -335,7 +438,8 @@ export class Lists {
         return res;
     }
     /**
-     * Adds item to the list of provided indexes
+     * Inserts the same item at multiple specified positions in the list.
+     * Example: In [10, 20, 30], adding 99 at indexes [0, 2] gives [99, 10, 20, 99, 30]
      * @param inputs a list, item and an indexes
      * @returns list with added item
      * @group add
@@ -358,7 +462,8 @@ export class Lists {
         return cloned;
     }
     /**
-     * Adds items to the list of provided indexes matching 1:1, first item will go to first index provided, etc.
+     * Inserts multiple items at corresponding positions (first item at first index, second item at second index, etc.).
+     * Example: In [10, 20, 30], adding items [88, 99] at indexes [1, 2] gives [10, 88, 20, 99, 30]
      * @param inputs a list, items and an indexes
      * @returns list with added items
      * @group add
@@ -390,7 +495,8 @@ export class Lists {
         return cloned;
     }
     /**
-     * Remove item from the list
+     * Removes the item at a specific position in the list.
+     * Example: From [10, 20, 30, 40, 50], removing index 2 gives [10, 20, 40, 50]
      * @param inputs a list and index
      * @returns list with removed item
      * @group remove
@@ -408,7 +514,66 @@ export class Lists {
         return res;
     }
     /**
-     * Remove items from the list of provided indexes
+     * Removes the first item from the list.
+     * Example: From [10, 20, 30, 40], returns [20, 30, 40]
+     * @param inputs a list
+     * @returns list with first item removed
+     * @group remove
+     * @shortname remove first item
+     * @drawable false
+     */
+    removeFirstItem(inputs) {
+        let res = inputs.list;
+        if (inputs.clone) {
+            res = structuredClone(inputs.list);
+        }
+        if (res.length > 0) {
+            res.shift();
+        }
+        return res;
+    }
+    /**
+     * Removes the last item from the list.
+     * Example: From [10, 20, 30, 40], returns [10, 20, 30]
+     * @param inputs a list
+     * @returns list with last item removed
+     * @group remove
+     * @shortname remove last item
+     * @drawable false
+     */
+    removeLastItem(inputs) {
+        let res = inputs.list;
+        if (inputs.clone) {
+            res = structuredClone(inputs.list);
+        }
+        if (res.length > 0) {
+            res.pop();
+        }
+        return res;
+    }
+    /**
+     * Removes an item counting from the end of the list (index 0 = last item, 1 = second-to-last, etc.).
+     * Example: From [10, 20, 30, 40, 50], removing index 1 from end gives [10, 20, 30, 50] (removes 40)
+     * @param inputs a list and index from end
+     * @returns list with removed item
+     * @group remove
+     * @shortname remove item from end
+     * @drawable false
+     */
+    removeItemAtIndexFromEnd(inputs) {
+        let res = inputs.list;
+        if (inputs.clone) {
+            res = structuredClone(inputs.list);
+        }
+        if (inputs.index >= 0 && inputs.index < res.length) {
+            const actualIndex = res.length - 1 - inputs.index;
+            res.splice(actualIndex, 1);
+        }
+        return res;
+    }
+    /**
+     * Removes items at multiple specified positions from the list.
+     * Example: From [10, 20, 30, 40, 50], removing indexes [1, 3] gives [10, 30, 50]
      * @param inputs a list and indexes
      * @returns list with removed items
      * @group remove
@@ -430,7 +595,8 @@ export class Lists {
         return res;
     }
     /**
-     * Remove all items from the list
+     * Clears all items from the list, resulting in an empty list.
+     * Example: From [10, 20, 30, 40], returns []
      * @param inputs a list
      * @returns The length is set to 0 and same array memory object is returned
      * @group remove
@@ -442,7 +608,8 @@ export class Lists {
         return inputs.list;
     }
     /**
-     * Remove item from the list
+     * Removes every nth item from the list, starting from an optional offset position.
+     * Example: From [0, 1, 2, 3, 4, 5, 6, 7, 8] with nth=3 and offset=0, returns [1, 2, 4, 5, 7, 8] (removes 0, 3, 6)
      * @param inputs a list and index
      * @returns list with removed item
      * @group remove
@@ -463,7 +630,8 @@ export class Lists {
         return result;
     }
     /**
-     * Removes items randomly by using a threshold
+     * Randomly removes items from the list based on a probability threshold (0 to 1).
+     * Example: From [1, 2, 3, 4, 5] with threshold 0.5, might return [2, 4] (50% chance to remove each item)
      * @param inputs a list and a threshold for randomization of items to remove
      * @returns list with removed items
      * @group remove
@@ -484,11 +652,12 @@ export class Lists {
         return newList;
     }
     /**
-     * remove duplicate numbers from the list
+     * Removes duplicate numbers from the list, keeping only the first occurrence of each value.
+     * Example: From [1, 2, 3, 2, 4, 3, 5], returns [1, 2, 3, 4, 5]
      * @param inputs a list of numbers
      * @returns list with unique numbers
      * @group remove
-     * @shortname remove duplicates
+     * @shortname remove duplicate numbers
      * @drawable false
      */
     removeDuplicateNumbers(inputs) {
@@ -499,7 +668,8 @@ export class Lists {
         return res.filter((value, index, self) => self.indexOf(value) === index);
     }
     /**
-     * remove duplicate numbers from the list with tolerance
+     * Removes duplicate numbers that are within a specified tolerance range of each other.
+     * Example: From [1.0, 1.001, 2.0, 2.002, 3.0] with tolerance 0.01, returns [1.0, 2.0, 3.0]
      * @param inputs a list of numbers and the tolerance
      * @returns list with unique numbers
      * @group remove
@@ -514,7 +684,24 @@ export class Lists {
         return res.filter((value, index, self) => self.findIndex(s => Math.abs(s - value) < inputs.tolerance) === index);
     }
     /**
-     * Add item to the end of the list
+     * Removes duplicate items from the list using strict equality comparison (works with any type).
+     * Example: From ['a', 'b', 'c', 'a', 'd', 'b'], returns ['a', 'b', 'c', 'd']
+     * @param inputs a list
+     * @returns list with unique items
+     * @group remove
+     * @shortname remove duplicates
+     * @drawable false
+     */
+    removeDuplicates(inputs) {
+        let res = inputs.list;
+        if (inputs.clone) {
+            res = structuredClone(inputs.list);
+        }
+        return res.filter((value, index, self) => self.indexOf(value) === index);
+    }
+    /**
+     * Appends an item to the end of the list.
+     * Example: To [10, 20, 30], adding 40 gives [10, 20, 30, 40]
      * @param inputs a list and an item
      * @returns list with added item
      * @group add
@@ -530,7 +717,8 @@ export class Lists {
         return res;
     }
     /**
-     * Add item to the beginning of the list
+     * Adds an item to the beginning of the list.
+     * Example: To [10, 20, 30], prepending 5 gives [5, 10, 20, 30]
      * @param inputs a list and an item
      * @returns list with added item
      * @group add
@@ -546,7 +734,8 @@ export class Lists {
         return res;
     }
     /**
-     * Add item to the beginning or the end of the list
+     * Adds an item either at the beginning or end of the list based on the position parameter.
+     * Example: To [10, 20, 30], adding 5 at 'first' gives [5, 10, 20, 30], at 'last' gives [10, 20, 30, 5]
      * @param inputs a list, item and an option for first or last position
      * @returns list with added item
      * @group add
@@ -567,7 +756,31 @@ export class Lists {
         return res;
     }
     /**
-     * Creates an empty list
+     * Combines multiple lists into a single list by joining them end-to-end.
+     * Example: From [[1, 2], [3, 4], [5, 6]], returns [1, 2, 3, 4, 5, 6]
+     * @param inputs lists to concatenate
+     * @returns concatenated list
+     * @group add
+     * @shortname concatenate lists
+     * @drawable false
+     */
+    concatenate(inputs) {
+        let result = [];
+        if (inputs.clone) {
+            inputs.lists.forEach(list => {
+                result = result.concat(structuredClone(list));
+            });
+        }
+        else {
+            inputs.lists.forEach(list => {
+                result = result.concat(list);
+            });
+        }
+        return result;
+    }
+    /**
+     * Creates a new empty list with no items.
+     * Example: Returns []
      * @returns an empty array list
      * @group create
      * @shortname empty list
@@ -577,7 +790,8 @@ export class Lists {
         return [];
     }
     /**
-     * Repeat the item and add it in the new list
+     * Creates a new list by repeating an item a specified number of times.
+     * Example: Repeating 5 three times returns [5, 5, 5]
      * @param inputs an item to multiply
      * @returns list
      * @group create
@@ -592,7 +806,8 @@ export class Lists {
         return result;
     }
     /**
-     * Repeat the list items by adding them in the new list till the certain length of the list is reached
+     * Repeats a pattern of items cyclically until reaching a target list length.
+     * Example: Pattern [1, 2, 3] with length 7 returns [1, 2, 3, 1, 2, 3, 1]
      * @param inputs a list to multiply and a length limit
      * @returns list
      * @group create
@@ -619,7 +834,8 @@ export class Lists {
         return res;
     }
     /**
-     * Sort the list of numbers in ascending or descending order
+     * Sorts numbers in ascending (lowest to highest) or descending (highest to lowest) order.
+     * Example: [5, 2, 8, 1, 9] ascending returns [1, 2, 5, 8, 9], descending returns [9, 8, 5, 2, 1]
      * @param inputs a list of numbers to sort and an option for ascending or descending order
      * @returns list
      * @group sorting
@@ -639,7 +855,8 @@ export class Lists {
         }
     }
     /**
-     * Sort the list of texts in ascending or descending order alphabetically
+     * Sorts text strings alphabetically in ascending (A to Z) or descending (Z to A) order.
+     * Example: ['dog', 'apple', 'cat', 'banana'] ascending returns ['apple', 'banana', 'cat', 'dog']
      * @param inputs a list of texts to sort and an option for ascending or descending order
      * @returns list
      * @group sorting
@@ -659,7 +876,8 @@ export class Lists {
         }
     }
     /**
-     * Sort by numeric JSON property value
+     * Sorts objects by comparing numeric values of a specified property.
+     * Example: [{age: 30}, {age: 20}, {age: 25}] sorted by 'age' ascending returns [{age: 20}, {age: 25}, {age: 30}]
      * @param inputs a list to sort, a property to sort by and an option for ascending or descending order
      * @returns list
      * @group sorting
@@ -678,4 +896,29 @@ export class Lists {
             return res.sort((a, b) => b[inputs.property] - a[inputs.property]);
         }
     }
+    /**
+     * Combines multiple lists by alternating elements from each list (first from list1, first from list2, second from list1, etc.).
+     * Example: From [[0, 1, 2], [3, 4, 5]], returns [0, 3, 1, 4, 2, 5]
+     * @param inputs Lists to interleave
+     * @returns Flattened interleaved list
+     * @group transform
+     * @shortname interleave lists
+     * @drawable false
+     */
+    interleave(inputs) {
+        const lists = inputs.clone ? structuredClone(inputs.lists) : inputs.lists;
+        if (!lists || lists.length === 0) {
+            throw new Error("Lists array is empty or does not exist");
+        }
+        const result = [];
+        const maxLength = Math.max(...lists.map(list => list.length));
+        for (let i = 0; i < maxLength; i++) {
+            for (const list of lists) {
+                if (i < list.length) {
+                    result.push(list[i]);
+                }
+            }
+        }
+        return result;
+    }
 }

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

@@ -4,7 +4,8 @@ import * as Inputs from "../inputs";
  */
 export declare 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
@@ -13,7 +14,8 @@ export declare class Logic {
      */
     boolean(inputs: Inputs.Logic.BooleanDto): 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
@@ -22,10 +24,10 @@ export declare class Logic {
      */
     randomBooleans(inputs: Inputs.Logic.RandomBooleansDto): boolean[];
     /**
-     * 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
@@ -34,7 +36,9 @@ export declare class Logic {
      */
     twoThresholdRandomGradient(inputs: Inputs.Logic.TwoThresholdRandomGradientDto): boolean[];
     /**
-     * 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
@@ -43,7 +47,9 @@ export declare class Logic {
      */
     thresholdBooleanList(inputs: Inputs.Logic.ThresholdBooleanListDto): boolean[];
     /**
-     * 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
@@ -52,7 +58,8 @@ export declare class Logic {
      */
     thresholdGapsBooleanList(inputs: Inputs.Logic.ThresholdGapsBooleanListDto): boolean[];
     /**
-     * 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
@@ -61,7 +68,8 @@ export declare class Logic {
      */
     not(inputs: Inputs.Logic.BooleanDto): 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
@@ -70,7 +78,8 @@ export declare class Logic {
      */
     notList(inputs: Inputs.Logic.BooleanListDto): boolean[];
     /**
-     * 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
@@ -79,7 +88,8 @@ export declare class Logic {
      */
     compare<T>(inputs: Inputs.Logic.ComparisonDto<T>): boolean;
     /**
-     * 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
@@ -88,7 +98,8 @@ export declare class Logic {
      */
     valueGate<T>(inputs: Inputs.Logic.ValueGateDto<T>): T | 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