@planet-matrix/mobius-model 0.3.0 → 0.4.0

package/src/basic/array.ts

@@ -0,0 +1,872 @@
+/**
+ * Convert an iterable target into an array using spread.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2, 3]
+ * const example1 = arrayFromSpread(new Set([1, 2, 3]))
+ * // Expect: []
+ * const example2 = arrayFromSpread([])
+ * ```
+ */
+export const arrayFromSpread = <T = unknown>(target: Iterable<T>): T[] => {
+  return [...target]
+}
+
+/**
+ * Returns the length of `targetArray`.
+ *
+ * @example
+ * ```
+ * // Expect: 3
+ * const example1 = arrayLength(["a", "b", "c"])
+ * // Expect: 0
+ * const example2 = arrayLength([])
+ * ```
+ */
+export const arrayLength = (targetArray: unknown[]): number => {
+  return targetArray.length
+}
+
+/**
+ * Returns a copy of `targetArray` in which last element has been removed.
+ * New array's length is `targetArray.length - 1`.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2]
+ * const example1 = arrayPop([1, 2, 3])
+ * // Expect: []
+ * const example2 = arrayPop(["only"])
+ * ```
+ */
+export const arrayPop = <T = unknown>(targetArray: T[]): T[] => {
+  return targetArray.slice(0, -1)
+}
+
+/**
+ * Returns a copy of `targetArray` in which inserts the given `item` as new last item.
+ * New array's length is `targetArray.length + 1`.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2, 3]
+ * const example1 = arrayPush(3, [1, 2])
+ * // Expect: ["a"]
+ * const example2 = arrayPush("a", [])
+ * ```
+ */
+export const arrayPush = <T = unknown>(item: T, targetArray: T[]): T[] => {
+  return [...targetArray, item]
+}
+
+/**
+ * Alias of {@link arrayPush}.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2]
+ * const example1 = arrayAppend(2, [1])
+ * // Expect: ["x"]
+ * const example2 = arrayAppend("x", [])
+ * ```
+ */
+export const arrayAppend: typeof arrayPush = arrayPush
+
+/**
+ * Returns a copy of `targetArray` in which inserts the given `item` as new fist item.
+ * New array's length is `targetArray`'s length + 1.
+ *
+ * @example
+ * ```
+ * // Expect: [0, 1, 2]
+ * const example1 = arrayUnshift(0, [1, 2])
+ * // Expect: ["a"]
+ * const example2 = arrayUnshift("a", [])
+ * ```
+ */
+export const arrayUnshift = <T = unknown>(item: T, targetArray: T[]): T[] => {
+  return [item, ...targetArray]
+}
+
+/**
+ * Alias of {@link arrayUnshift}.
+ *
+ * @example
+ * ```
+ * // Expect: ["first", "second"]
+ * const example1 = arrayPrepend("first", ["second"])
+ * // Expect: [true]
+ * const example2 = arrayPrepend(true, [])
+ * ```
+ */
+export const arrayPrepend: typeof arrayUnshift = arrayUnshift
+
+/**
+ * Returns a copy of `targetArray` in which first element has been removed.
+ * New array's length is `targetArray`'s length - 1.
+ *
+ * @example
+ * ```
+ * // Expect: [2, 3]
+ * const example1 = arrayShift([1, 2, 3])
+ * // Expect: []
+ * const example2 = arrayShift(["only"])
+ * ```
+ */
+export const arrayShift = <T = unknown>(targetArray: T[]): T[] => {
+  return targetArray.slice(1)
+}
+
+/**
+ * Returns the first element of `targetArray`.
+ *
+ * @example
+ * ```
+ * // Expect: 1
+ * const example1 = arrayHead([1, 2, 3])
+ * // Expect: undefined
+ * const example2 = arrayHead([])
+ * ```
+ *
+ * @see {@link arrayTail}， {@link arrayLast}
+ */
+export const arrayHead = <T = unknown>(targetArray: T[]): T | undefined => {
+  return targetArray[0]
+}
+
+/**
+ * Returns the tail of `targetArray`.
+ *
+ * @example
+ * ```
+ * // Expect: [2, 3]
+ * const example1 = arrayTail([1, 2, 3])
+ * // Expect: []
+ * const example2 = arrayTail(["only"])
+ * ```
+ *
+ * @see {@link arrayHead}, {@link arrayInit}
+ */
+export const arrayTail = <T = unknown>(targetArray: T[]): T[] => {
+  return targetArray.slice(1)
+}
+
+/**
+ * Returns the init of `targetArray`.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2]
+ * const example1 = arrayInit([1, 2, 3])
+ * // Expect: []
+ * const example2 = arrayInit(["only"])
+ * ```
+ *
+ * @see {@link arrayLast}, {@link arrayTail}
+ */
+export const arrayInit = <T = unknown>(targetArray: T[]): T[] => {
+  return targetArray.slice(0, -1)
+}
+
+/**
+ * Returns the last element of `targetArray`.
+ *
+ * @example
+ * ```
+ * // Expect: 3
+ * const example1 = arrayLast([1, 2, 3])
+ * // Expect: undefined
+ * const example2 = arrayLast([])
+ * ```
+ *
+ * @see {@link arrayInit}, {@link arrayHead}
+ */
+export const arrayLast = <T = unknown>(targetArray: T[]): T | undefined => {
+  return targetArray.at(-1)
+}
+
+/**
+ * Returns a copy of a section of an array.
+ *
+ * @example
+ * ```
+ * // Expect: ["b", "c"]
+ * const example1 = arraySlice(1, 3, ["a", "b", "c", "d"])
+ * // Expect: []
+ * const example2 = arraySlice(2, 2, [1, 2, 3])
+ * ```
+ *
+ * @see {@link arraySliceInit}, {@link arraySliceTail}
+ */
+export const arraySlice = <T = unknown>(
+  start: number,
+  end: number,
+  targetArray: T[],
+): T[] => {
+  return targetArray.slice(start, end)
+}
+
+/**
+ * Returns a copy of a section of an array.
+ *
+ * @example
+ * ```
+ * // Expect: [3, 4]
+ * const example1 = arraySliceTail(2, [1, 2, 3, 4])
+ * // Expect: []
+ * const example2 = arraySliceTail(1, ["only"])
+ * ```
+ *
+ * @see {@link arraySlice}, {@link arraySliceTail}
+ * @see {@link arrayDrop}
+ */
+export const arraySliceTail = <T = unknown>(
+  start: number,
+  targetArray: T[],
+): T[] => {
+  return targetArray.slice(start)
+}
+
+/**
+ * Returns a copy of a section of an array.
+ *
+ * @example
+ * ```
+ * // Expect: [3, 4]
+ * const example1 = arrayDrop(2, [1, 2, 3, 4])
+ * // Expect: []
+ * const example2 = arrayDrop(-2, [1, 2])
+ * ```
+ *
+ * @see {@link arraySliceTail}
+ */
+export const arrayDrop = <T = unknown>(
+  n: number,
+  targetArray: T[],
+): T[] => {
+  return targetArray.slice(Math.abs(Math.round(n)))
+}
+/**
+ * Returns a copy of a section of an array.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2]
+ * const example1 = arraySliceInit(2, [1, 2, 3, 4])
+ * // Expect: []
+ * const example2 = arraySliceInit(0, [1, 2])
+ * ```
+ *
+ * @see {@link arraySlice}, {@link arraySliceInit}
+ */
+export const arraySliceInit = <T = unknown>(
+  end: number,
+  targetArray: T[],
+): T[] => {
+  return targetArray.slice(0, Math.round(end))
+}
+
+/**
+ * Returns a copy of a section of an array.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2]
+ * const example1 = arrayDropLast(2, [1, 2, 3, 4])
+ * // Expect: []
+ * const example2 = arrayDropLast(3, [1, 2])
+ * ```
+ *
+ * @see {@link arraySliceInit}
+ */
+export const arrayDropLast = <T = unknown>(
+  n: number,
+  targetArray: T[],
+): T[] => {
+  return targetArray.slice(0, -Math.abs(Math.round(n)))
+}
+
+/**
+ * Returns a copy of `targetArray` with the elements between `start` (inclusive)
+ * and `end` (exclusive) removed.
+ *
+ * @example
+ * ```
+ * // Expect: ["a", "d"]
+ * const example1 = arrayRemove(1, 3, ["a", "b", "c", "d"])
+ * // Expect: [1, 2, 3]
+ * const example2 = arrayRemove(2, 2, [1, 2, 3])
+ * ```
+ */
+export const arrayRemove = <T = unknown>(
+  start: number, end: number, targetArray: T[]
+): T[] => {
+  let internalStart = Math.abs(Math.round(start))
+  let internalEnd = Math.abs(Math.round(end))
+
+  if (internalEnd < internalStart) {
+    [internalStart, internalEnd] = [internalEnd, internalStart]
+  }
+  return [...targetArray.slice(0, internalStart), ...targetArray.slice(internalEnd)]
+}
+
+/**
+ * Returns a copy of `targetArray` with the element at `index` removed.
+ *
+ * @example
+ * ```
+ * // Expect: ["a", "c"]
+ * const example1 = arrayRemoveIndex(1, ["a", "b", "c"])
+ * // Expect: []
+ * const example2 = arrayRemoveIndex(0, ["only"])
+ * ```
+ */
+export const arrayRemoveIndex = <T = unknown>(
+  index: number,
+  targetArray: T[],
+): T[] => {
+  return [...targetArray.slice(0, index), ...targetArray.slice(index + 1 === 0 ? Infinity : index + 1)]
+}
+
+/**
+ * Combines two array. `appendedArray` will be appended to the end of `targetArray`.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2, 3, 4]
+ * const example1 = arrayConcat([3, 4], [1, 2])
+ * // Expect: ["a"]
+ * const example2 = arrayConcat([], ["a"])
+ * ```
+ */
+export const arrayConcat = <T = unknown>(appendedArray: T[], targetArray: T[]): T[] => {
+  return [...targetArray, ...appendedArray]
+}
+
+/**
+ * Adds all the elements of an array into a string, separated by the specified
+ * separator string.
+ *
+ * @example
+ * ```
+ * // Expect: "a,b,c"
+ * const example1 = arrayJoin(",", ["a", "b", "c"])
+ * // Expect: ""
+ * const example2 = arrayJoin("-", [])
+ * ```
+ */
+export const arrayJoin = (separator: string, targetArray: unknown[]): string => {
+  return targetArray.join(separator)
+}
+
+/**
+ * Returns the first index at which a given element can be found in the array,
+ * or -1 if it is not present.
+ *
+ * @example
+ * ```
+ * // Expect: 1
+ * const example1 = arrayIndexOf("b", ["a", "b", "c"])
+ * // Expect: -1
+ * const example2 = arrayIndexOf(9, [1, 2, 3])
+ * ```
+ */
+export const arrayIndexOf = (searchElement: unknown, targetArray: unknown[]): number => {
+  return targetArray.indexOf(searchElement)
+}
+
+/**
+ * Returns the last index at which a given element can be found in the array,
+ * or -1 if it is not present.
+ *
+ * @example
+ * ```
+ * // Expect: 2
+ * const example1 = arrayLastIndexOf("a", ["a", "b", "a"])
+ * // Expect: -1
+ * const example2 = arrayLastIndexOf(9, [1, 2, 3])
+ * ```
+ */
+export const arrayLastIndexOf = (searchElement: unknown, targetArray: unknown[]): number => {
+  return targetArray.lastIndexOf(searchElement)
+}
+
+/**
+ * Predicate whether the target array includes the searchElement.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = arrayIncludes(2, [1, 2, 3])
+ * // Expect: false
+ * const example2 = arrayIncludes("x", ["a", "b"])
+ * ```
+ */
+export const arrayIncludes = <T = unknown>(searchElement: T, targetArray: T[]): boolean => {
+  return targetArray.includes(searchElement)
+}
+
+/**
+ * Predicate whether all elements in the target array satisfy the provided testing function.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = arrayEvery((item) => item > 0, [1, 2, 3])
+ * // Expect: false
+ * const example2 = arrayEvery((item) => item > 1, [1, 2, 3])
+ * ```
+ */
+export function arrayEvery<T = unknown, S extends T = T>(
+  predicate: (item: T, index: number, array: T[]) => item is S, targetArray: T[]
+): targetArray is S[]
+export function arrayEvery<T = unknown>(
+  predicate: (item: T, index: number, array: T[]) => boolean, targetArray: T[]
+): boolean
+export function arrayEvery<T = unknown>(
+  predicate: (item: T, index: number, array: T[]) => boolean,
+  targetArray: T[],
+): boolean {
+  return targetArray.every((item, index, array) => predicate(item, index, array))
+}
+
+/**
+ * Alias of {@link arrayEvery}.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = arrayAll((item) => item !== null, [1, 2])
+ * // Expect: false
+ * const example2 = arrayAll((item) => item === 0, [0, 1])
+ * ```
+ */
+export const arrayAll: typeof arrayEvery = arrayEvery
+
+/**
+ * Predicate whether at least one element in the target array satisfies the provided testing function.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = arraySome((item) => item > 2, [1, 2, 3])
+ * // Expect: false
+ * const example2 = arraySome((item) => item < 0, [1, 2, 3])
+ * ```
+ */
+export const arraySome = <T = unknown>(
+  predicate: (item: T, index: number, array: T[]) => boolean,
+  targetArray: T[],
+): boolean => {
+  return targetArray.some((item, index, array) => predicate(item, index, array))
+}
+
+/**
+ * Alias of {@link arraySome}.
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = arrayAny((item) => item === "b", ["a", "b"])
+ * // Expect: false
+ * const example2 = arrayAny((item) => item === "x", ["a", "b"])
+ * ```
+ */
+export const arrayAny: typeof arraySome = arraySome
+
+/**
+ * Applies a function to each element in the target array.
+ *
+ * @example
+ * ```
+ * const target: number[] = []
+ * arrayForEach((item) => target.push(item * 2), [1, 2, 3])
+ * // Expect: [2, 4, 6]
+ * const example1 = target
+ * ```
+ */
+export const arrayForEach = <T = unknown>(
+  eachDo: (item: T, index: number, array: T[]) => void,
+  targetArray: T[],
+): void => {
+  targetArray.forEach((item, index, array) => {
+    eachDo(item, index, array)
+  })
+}
+
+/**
+ * Returns a new array containing all elements of the target array that satisfy the provided testing function.
+ *
+ * @example
+ * ```
+ * // Expect: [2, 4]
+ * const example1 = arrayFilter((item) => item % 2 === 0, [1, 2, 3, 4])
+ * // Expect: []
+ * const example2 = arrayFilter((item) => item > 0, [])
+ * ```
+ *
+ * @see {@link arrayReject}
+ */
+export function arrayFilter<T = unknown, S extends T = T>(
+  predicate: (item: T, index: number, array: T[]) => item is S, targetArray: T[]
+): S[]
+export function arrayFilter<T = unknown>(
+  predicate: (item: T, index: number, array: T[]) => boolean, targetArray: T[]
+): T[]
+export function arrayFilter<T = unknown>(
+  predicate: (item: T, index: number, array: T[]) => boolean,
+  targetArray: T[],
+): T[] {
+  return targetArray.filter((item, index, array) => predicate(item, index, array))
+}
+
+/**
+ * Returns a new array containing all elements of the target array that do not satisfy the provided testing function.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 3]
+ * const example1 = arrayReject((item) => item % 2 === 0, [1, 2, 3, 4])
+ * // Expect: ["a"]
+ * const example2 = arrayReject((item) => item === "b", ["a", "b"])
+ * ```
+ *
+ * @see {@link arrayFilter}
+ */
+export const arrayReject = <T = unknown>(
+  predicate: (item: T, index: number, array: T[]) => boolean,
+  targetArray: T[],
+): T[] => {
+  return targetArray.filter((item, index, array) => !predicate(item, index, array))
+}
+
+/**
+ * Returns a tuple of two arrays: the first array contains the elements of the target array that satisfy the provided testing function, while the second array contains the elements that do not satisfy the testing function.
+ *
+ * @example
+ * ```
+ * // Expect: [[2, 4], [1, 3]]
+ * const example1 = arrayPartition((item) => item % 2 === 0, [1, 2, 3, 4])
+ * // Expect: [[], ["a"]]
+ * const example2 = arrayPartition((item) => item === "b", ["a"])
+ * ```
+ *
+ * @see {@link arrayFilter}, {@link arrayReject}
+ */
+export const arrayPartition = <T = unknown>(
+  predicate: (item: T, index: number, array: T[]) => boolean,
+  targetArray: T[],
+): [T[], T[]] => {
+  const truthyArray: T[] = []
+  const falsyArray: T[] = []
+  targetArray.forEach((item, index, array) => {
+    if (predicate(item, index, array)) {
+      truthyArray.push(item)
+    }
+    else {
+      falsyArray.push(item)
+    }
+  })
+  return [truthyArray, falsyArray]
+}
+
+/**
+ * Returns a new array containing the results of applying a provided function to every element in the target array.
+ *
+ * @example
+ * ```
+ * // Expect: [2, 4, 6]
+ * const example1 = arrayMap((item) => item * 2, [1, 2, 3])
+ * // Expect: []
+ * const example2 = arrayMap((item) => item, [])
+ * ```
+ */
+export const arrayMap = <T = unknown, R = unknown>(
+  transformation: (item: T, index: number, array: T[]) => R,
+  targetArray: T[],
+): R[] => {
+  return targetArray.map((item, index, array) => transformation(item, index, array))
+}
+
+/**
+ * Returns a new array with all sub-array elements concatenated into it recursively up to the specified depth.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2, 3, 4]
+ * const example1 = arrayFlat(1, [1, [2, 3], [4]])
+ * // Expect: [1, 2]
+ * const example2 = arrayFlat(2, [1, [[2]]])
+ * ```
+ *
+ * @see {@link arrayFlatMap}
+ */
+export const arrayFlat = <T = unknown, D extends number = number>(
+  depth: D,
+  targetArray: T[],
+): Array<FlatArray<T[], D>> => {
+  return targetArray.flat(depth)
+}
+
+/**
+ * Returns a new array containing the results of applying a provided function to every element in the target array, and then flattening the result by one level.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 1, 2, 2]
+ * const example1 = arrayFlatMap((item) => [item, item], [1, 2])
+ * // Expect: []
+ * const example2 = arrayFlatMap((item) => [item], [])
+ * ```
+ *
+ * @see {@link arrayMap}, {@link arrayFlat}
+ */
+export const arrayFlatMap = <T = unknown, R = unknown>(
+  transformation: (item: T, index: number, array: T[]) => (R | R[]),
+  targetArray: T[],
+): R[] => {
+  return targetArray.flatMap((item, index, array) => transformation(item, index, array))
+}
+
+/**
+ * Returns a single value that is the result of applying a provided function against an accumulator and each element in the target array (from left to right).
+ *
+ * @example
+ * ```
+ * // Expect: 6
+ * const example1 = arrayReduce((acc, item) => acc + item, 0, [1, 2, 3])
+ * // Expect: "abc"
+ * const example2 = arrayReduce((acc, item) => acc + item, "", ["a", "b", "c"])
+ * ```
+ *
+ * @see {@link arrayReduceLeft}, {@link arrayReduceRight}
+ */
+export const arrayReduce = <T = unknown, R = unknown>(
+  reducer: (accumulated: R, item: T, index: number, array: T[]) => R,
+  initialValue: R,
+  targetArray: T[],
+): R => {
+  return targetArray.reduce((accumulated, item, index, array) => reducer(accumulated, item, index, array), initialValue)
+}
+/**
+ * Alias of {@link arrayReduce}.
+ *
+ * @example
+ * ```
+ * // Expect: 6
+ * const example1 = arrayReduceLeft((acc, item) => acc + item, 0, [1, 2, 3])
+ * // Expect: "ab"
+ * const example2 = arrayReduceLeft((acc, item) => acc + item, "", ["a", "b"])
+ * ```
+ *
+ * @see {@link arrayReduce}
+ */
+export const arrayReduceLeft: typeof arrayReduce = arrayReduce
+
+/**
+ * Returns a single value that is the result of applying a provided function against an accumulator and each element in the target array (from right to left).
+ *
+ * @example
+ * ```
+ * // Expect: "cba"
+ * const example1 = arrayReduceRight((acc, item) => acc + item, "", ["a", "b", "c"])
+ * // Expect: 6
+ * const example2 = arrayReduceRight((acc, item) => acc + item, 0, [1, 2, 3])
+ * ```
+ *
+ * @see {@link arrayReduceLeft}, {@link arrayReduceRight}
+ */
+export const arrayReduceRight = <T = unknown, R = unknown>(
+  reducer: (accumulated: R, item: T, index: number, array: T[]) => R,
+  initialValue: R,
+  targetArray: T[],
+): R => {
+  return targetArray.reduceRight((accumulated, item, index, array) => reducer(accumulated, item, index, array), initialValue)
+}
+
+/**
+ * Returns a new array containing only one copy of each element in the original array.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2, 3]
+ * const example1 = arrayUnique([1, 2, 1, 3])
+ * // Expect: ["a"]
+ * const example2 = arrayUnique(["a", "a"])
+ * ```
+ */
+export const arrayUnique = <T = unknown>(targetArray: T[]): T[] => {
+  return Array.from(new Set(targetArray))
+}
+
+/**
+ * Returns a new array containing only one copy of each element in the original array,
+ * based on the provided unique function.
+ *
+ * @example
+ * ```
+ * // Expect: [{ id: 1 }, { id: 2 }]
+ * const example1 = arrayUniqueBy((item) => item.id, [{ id: 1 }, { id: 1 }, { id: 2 }])
+ * // Expect: []
+ * const example2 = arrayUniqueBy((item) => item, [])
+ * ```
+ */
+export const arrayUniqueBy = <T = unknown>(
+  uniqueFunction: (item: T) => unknown, targetArray: T[]
+): T[] => {
+  const uniqueMap = new Map<unknown, T>()
+  targetArray.forEach((item) => {
+    const uniqueKey = uniqueFunction(item)
+    if (!uniqueMap.has(uniqueKey)) {
+      uniqueMap.set(uniqueKey, item)
+    }
+  })
+  return Array.from(uniqueMap.values())
+}
+
+/**
+ * Combines two arrays into one array (no duplicates) composed of the elements of each array.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2, 3]
+ * const example1 = arrayUnion([1, 2], [2, 3])
+ * // Expect: ["a"]
+ * const example2 = arrayUnion(["a"], [])
+ * ```
+ *
+ * @see {@link arrayIntersection}
+ */
+export const arrayUnion = <T = unknown>(firstArray: T[], secondArray: T[]): T[] => {
+  return arrayUnique([...firstArray, ...secondArray])
+}
+
+type CompareArray = (arr1: unknown[], arr2: unknown[]) => unknown[]
+const _longer: CompareArray = (arr1, arr2) => arr1.length > arr2.length ? arr1 : arr2
+const _shorter: CompareArray = (arr1, arr2) => arr1.length > arr2.length ? arr2 : arr1
+/**
+ * Combines two arrays into one array (no duplicates) composed of those elements common to both arrays.
+ *
+ * @example
+ * ```
+ * // Expect: [2]
+ * const example1 = arrayIntersection([1, 2], [2, 3])
+ * // Expect: []
+ * const example2 = arrayIntersection(["a"], ["b"])
+ * ```
+ *
+ * @see {@link https://ramdajs.com/docs/#intersection}
+ * @see {@link arrayUnion}
+ */
+export const arrayIntersection = <T = unknown>(firstArray: T[], secondArray: T[]): T[] => {
+  // reference: ramda, it is more efficient when the array length gap is large
+  const lookupArr = _longer(firstArray, secondArray)
+  const filteredArr = _shorter(firstArray, secondArray)
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  return arrayUnique(filteredArr.filter(item => lookupArr.includes(item))) as T[]
+}
+
+/**
+ * Returns a new array with the elements in reverse order.
+ *
+ * @example
+ * ```
+ * // Expect: [3, 2, 1]
+ * const example1 = arrayReverse([1, 2, 3])
+ * // Expect: []
+ * const example2 = arrayReverse([])
+ * ```
+ */
+export const arrayReverse = <T = unknown>(targetArray: T[]): T[] => {
+  return targetArray.toReversed()
+}
+
+/**
+ * Returns a new array with the elements sorted according to the provided compare function.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 2, 3]
+ * const example1 = arraySort((a, b) => a - b, [3, 1, 2])
+ * // Expect: ["a", "b"]
+ * const example2 = arraySort((a, b) => a.localeCompare(b), ["b", "a"])
+ * ```
+ */
+export const arraySort = <T = unknown>(
+  compareFunction: (a: T, b: T) => number,
+  targetArray: T[],
+): T[] => {
+  return targetArray.toSorted(compareFunction)
+}
+
+/**
+ * Shuffle the target array.
+ *
+ * @see {@link https://github.com/mqyqingfeng/Blog/issues/51}
+ *
+ * @example
+ * ```
+ * const example1 = shuffle([1, 2, 3])
+ * const example2 = shuffle(["a", "b"])
+ * // Expect: example1.length === 3
+ * // Expect: example2.length === 2
+ * ```
+ */
+export const shuffle = <T = unknown>(target: T[]): T[] => {
+  const _target = [...target]
+  for (let i = _target.length; i !== 0; i = i - 1) {
+    const j = Math.floor(Math.random() * i);
+    // @ts-expect-error - ignore the error
+    [_target[i - 1], _target[j]] = [_target[j], _target[i - 1]]
+  }
+  return _target
+}
+
+/**
+ * Applies a function to the value at the given index of an array,
+ * returning a new copy of the array with the element at the given index
+ * replaced with the result of the function application.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 20, 3]
+ * const example1 = arrayAdjust(1, (item) => item * 10, [1, 2, 3])
+ * // Expect: ["a"]
+ * const example2 = arrayAdjust(0, (item) => item, ["a"])
+ * ```
+ *
+ * @see {@link https://ramdajs.com/docs/#adjust}
+ */
+export const arrayAdjust = <T = unknown>(
+  index: number,
+  transformation: (item: T) => T,
+  targetArray: T[],
+): T[] => {
+  const _targetArray = [...targetArray]
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  _targetArray[index] = transformation(_targetArray[index] as T)
+  return _targetArray
+}
+
+/**
+ * Returns a new copy of the array with the element
+ * at the provided index replaced with the given value.
+ *
+ * @example
+ * ```
+ * // Expect: [1, 9, 3]
+ * const example1 = arrayUpdate(1, 9, [1, 2, 3])
+ * // Expect: ["x"]
+ * const example2 = arrayUpdate(0, "x", ["a"])
+ * ```
+ *
+ * @see {@link arrayAdjust}
+ */
+export const arrayUpdate = <T = unknown>(
+  index: number,
+  newItem: T,
+  targetArray: T[],
+): T[] => {
+  return arrayAdjust(index, () => newItem, targetArray)
+}