Handy Script Array Documentation

This module contains extensions to the built-in Array object in TypeScript. It provides various sorting algorithms, array manipulation methods, and utility functions.

© HandyScript Array 5/21/23 - Last Update: 9/24/23:

• Handy Script Arrays Manipulation
  • Table of Contents
  • Sort Algorithms
    • Bubble Sort
    • Selection Sort
    • Insertion Sort
    • Merge Sort
    • Quick Sort
    • Heap Sort
    • Counting Sort
    • Bucket Sort
    • Radix Sort
    • Shell Sort
  • Array Manipulation Methods
    • Shuffle
    • Chunk
    • Compact
    • Filter Nullish
    • Unique
    • Clear
    • Copy
    • Sample
    • Count
    • Count By
    • Differ
  • Binary Search
  • Types
    • Sort Order
    • Comparable Data
    • Binary Sort Algorithms

Sorts an array using the Bubble Sort algorithm.

Array.prototype.bubbleSort(this: ComparableData[], order?: SortOrder): Array<ComparableData>;

Parameters:

• order - The order of the sorting SortOrder. Can be either asc or desc. Default is asc.
• this - The array to sort, must be an array of Comparable Data type.

Returns: The sorted array.

Example:

const arr = [5, 4, 3, 2, 1];
arr.bubbleSort(); // [1, 2, 3, 4, 5]
arr.bubbleSort("desc"); // [5, 4, 3, 2, 1]

Sorts an array using the Selection Sort algorithm.

Array.prototype.selectionSort(this: ComparableData[], order?: SortOrder): Array<ComparableData>;

Parameters:

• order - The order of the sorting SortOrder. Can be either asc or desc. Default is asc.
• this - The array to sort, must be an array of Comparable Data type.

Returns: The sorted array.

Example:

const arr = [5, 4, 3, 2, 1];
arr.selectionSort(); // [1, 2, 3, 4, 5]
arr.selectionSort("desc"); // [5, 4, 3, 2, 1]

Sorts an array using the Insertion Sort algorithm.

Array.prototype.insertionSort(this: ComparableData[], order?: SortOrder): Array<ComparableData>;

Parameters:

• order - The order of the sorting SortOrder. Can be either asc or desc. Default is asc.
• this - The array to sort, must be an array of Comparable Data type.

Returns: The sorted array.

Example:

const arr = [5, 4, 3, 2, 1];
arr.insertionSort(); // [1, 2, 3, 4, 5]
arr.insertionSort("desc"); // [5, 4, 3, 2, 1]

Sorts an array using the Merge Sort algorithm.

Array.prototype.mergeSort(this: ComparableData[], order?: SortOrder): Array<ComparableData>;

Parameters:

• order - The order of the sorting SortOrder. Can be either asc or desc. Default is asc.
• this - The array to sort, must be an array of Comparable Data type.

Returns: The sorted array.

Example:

const arr = [5, 4, 3, 2, 1];
arr.mergeSort(); // [1, 2, 3, 4, 5]
arr.mergeSort("desc"); // [5, 4, 3, 2, 1]

Sorts an array using the Quick Sort algorithm.

Array.prototype.quickSort(this: ComparableData[], order?: SortOrder): Array<ComparableData>;

Parameters:

• order - The order of the sorting SortOrder. Can be either asc or desc. Default is asc.
• this - The array to sort, must be an array of Comparable Data type.

Returns: The sorted array.

Example:

const arr = [5, 4, 3, 2, 1];
arr.quickSort(); // [1, 2, 3, 4, 5]
arr.quickSort("desc"); // [5, 4, 3, 2, 1]

Sorts an array using the Heap Sort algorithm.

Array.prototype.heapSort(this: ComparableData[], order?: SortOrder): Array<ComparableData>;

Parameters:

• order - The order of the sorting SortOrder. Can be either asc or desc. Default is asc.
• this - The array to sort, must be an array of Comparable Data type.

Returns: The sorted array.

Example:

const arr = [5, 4, 3, 2, 1];
arr.heapSort(); // [1, 2, 3, 4, 5]
arr.heapSort("desc"); // [5, 4, 3, 2, 1]

Sorts an array using the Counting Sort algorithm.

⚠️ Note: This algorithm only works on arrays of numbers.

Array.prototype.countingSort(this: number[], order?: SortOrder): Array<number>;

Parameters:

• order - The order of the sorting SortOrder. Can be either asc or desc. Default is asc.
• this - The array to sort, must be an array of numbers.

Returns: The sorted array.

Example:

const arr = [5, 4, 3, 2, 1];
arr.countingSort(); // [1, 2, 3, 4, 5]
arr.countingSort("desc"); // [5, 4, 3, 2, 1]

Sorts an array using the Bucket Sort algorithm.

Array.prototype.bucketSort(this: ComparableData[], order?: SortOrder): Array<ComparableData>;

Parameters:

• order - The order of the sorting SortOrder. Can be either asc or desc. Default is asc.
• this - The array to sort, must be an array of Comparable Data type.

Returns: The sorted array.

Example:

const arr = [5, 4, 3, 2, 1];
arr.bucketSort(); // [1, 2, 3, 4, 5]
arr.bucketSort("desc"); // [5, 4, 3, 2, 1]

Sorts an array using the Radix Sort algorithm.

⚠️ Note: This algorithm only works on arrays of numbers.

Array.prototype.radixSort(this: number[], radix?: number, order?: SortOrder): Array<number>;

Parameters:

• radix - The radix to use for the sorting. The default is 10.
• order - The order of the sorting SortOrder. Can be either asc or desc. Default is asc.
• this - The array to sort, must be an array of numbers.

Returns: The sorted array.

Example:

const arr = [5, 4, 3, 2, 1];
arr.radixSort(); // [1, 2, 3, 4, 5]
arr.radixSort(2); // [1, 2, 3, 4, 5]
arr.radixSort(2, "desc"); // [5, 4, 3, 2, 1]

Sorts an array using the Shell Sort algorithm.

Array.prototype.shellSort(this: ComparableData[], order?: SortOrder): Array<ComparableData>;

Parameters:

• order - The order of the sorting SortOrder. Can be either asc or desc. Default is asc.
• this - The array to sort, must be an array of Comparable Data type.

Returns: The sorted array.

Example:

const arr = [5, 4, 3, 2, 1];
arr.shellSort(); // [1, 2, 3, 4, 5]
arr.shellSort("desc"); // [5, 4, 3, 2, 1]

Shuffles the elements in the given array in a random order.

Array.prototype.shuffle(): Array<T>; // T is the type of the array

Returns: The shuffled array.

Example:

const arr = [1, 2, 3, 4, 5];
arr.shuffle(); // [3, 1, 5, 2, 4]
arr.shuffle().bubbleSort(); // [1, 2, 3, 4, 5]

Splits the array into chunks of the given size.

Array.prototype.chunk(size?: number): T[][]; // T is the type of the array

Parameters:

• size - The size of each chunk. Default is 1.

Returns: The array of chunks.

Example:

const arr = [1, 2, 3, 4, 5];
arr.chunk(); // [[1], [2], [3], [4], [5]]
arr.chunk(2); // [[1, 2], [3, 4], [5]]
arr.chunk(3); // [[1, 2, 3], [4, 5]]

Removes all falsy values from the array.

Array.prototype.compact(): Array<T>; // T is the type of the array

Returns: The compacted array.

Example:

const arr = [1, 2, 3, 4, 5, 0, false, "", null, undefined];
arr.compact(); // [1, 2, 3, 4, 5]

Removes all nullish values from the array.

Array.prototype.filterNullish(): Array<T>; // T is the type of the array

Returns: The filtered array.

Example:

const arr = [1, 2, 3, 4, 5, 0, false, "", null, undefined];
arr.filterNullish(); // [1, 2, 3, 4, 5, 0, false, ""]

Removes all duplicate values from the array.

⚠️ Note: This method does not work on arrays of objects.

Array.prototype.unique(): Array<T>; // T is the type of the array

Returns: The filtered array.

Example:

const arr = [1, 2, 3, 4, 5, 1, 2, 3, 4, 5];
arr.unique(); // [1, 2, 3, 4, 5]

const arr = ["a", "b", "c", "A", "b", "C"];
arr.unique(); // ["a", "b", "c"]

Clears the array. empties it.

Array.prototype.clear(): void;

Example:

const arr = [1, 2, 3, 4, 5];
arr.clear(); // []

Copies the array. Return a true copy of the array.

Array.prototype.copy(): Array<T>; // T is the type of the array

Returns: The copied array.

Example:

const arr = [1, 2, 3, 4, 5];
const copy = arr.copy(); // [1, 2, 3, 4, 5]

Returns a random element or an array of random elements from the array based on the given quantity.

⚠️ Note: If the quantity is less than or equal to 1 or greater than the length of the array, the method will return a single random element from the array.

Array.prototype.sample(quantity?: number): T | T[]; // T is the type of the array

Parameters:

• quantity - The quantity of random elements to return. The default is 1.

Returns: The random element or an array of random elements.

Example:

const arr = [1, 2, 3, 4, 5];
arr.sample(); // 3
arr.sample(2); // [1, 4]
arr.sample(3); // [2, 3, 5]

Count the occurrences of a value in an array.

⚠️ Note: If the target is not found, the method will return 0.

Array.prototype.count(target: T): number; // T is the type of the array

Parameters:

• target - The value to count its occurrences.

Returns: The number of occurrences.

Example:

const arr = [1, 2, 3, 3, 5, 1, 1, 3, 4, 5];
arr.count(1); // 3
arr.count(2); // 1
arr.count(3); // 2

Counts the occurrences of each element in an array based on a callback

Array.prototype.countBy(callback: (item: T) => string): Record<string, number>; // T is the type of the array

Parameters:

• callback - The callback function to use for counting the occurrences.
• item - The current item in the array.

Returns: An object with the occurrences of each element.

Example:

const arr = [1, 2, 3, 4, 5];
arr.countBy(x => x % 2 === 0 ? 'even' : 'odd') // { odd: 3, even: 2 }

Returns the difference between two arrays. in a new array

Array.prototype.differ(other: unknown[]): unknown[];

Parameters:

• other - The other array to compare with.

Returns the difference between two arrays

Example:

const arr = [1, 2, 3, 4, 5];
arr.differ([1, 2, 3]); // [4, 5]
arr.differ([1, 2, 3, 4, 5]); // []

Searches for an element in a sorted array using the Binary Search algorithm.

⚠️ Note: This method only works on sorted & Comparable Data arrays.

Array.prototype.binarySearch(this: ComparableData[], target: ComparableData, sortalgo?: BinarySortAlgorithms): number;

Parameters:

• target - The element to search for, should be the type of Comparable Data.
• sortalgo - The sorting algorithm to use from Binary Sort Algorithms to sort the array before proceeding in the search process. Default is Array.prototype.sort().
• this - The array to search in, must be an array of Comparable Data type.

Returns: The index of the element if found, otherwise -1.

Example:

const arr = [1, 2, 3, 4, 5];
arr.binarySearch(3); // 2
arr.binarySearch(3, "bubble"); // 2
arr.binarySearch(6); // -1

The order of the sorting. by default, it is asc.

type SortOrder = "asc" | "desc";

The data can be compared in javascript number | string | boolean | Date.

type ComparableData = number | string | boolean | Date;

The Explicit sort algorithms are used with binary search to sort the array before proceeding in the search process.

type BinarySortAlgorithms =
  | "bubble"
  | "selection"
  | "insertion"
  | "merge"
  | "quick"
  | "heap"
  | "radix" //it supports only numbers
  | "counting" //it supports only numbers
  | "bucket"
  | "shell";

© HandyScript Array 5/21/23