✨ feat(array-methods): add Array.Unshift method

changelog/next.md

@@ -48,12 +48,17 @@
 + Add a new method of `Array` namespace:
   + `Array.LastIndexOf<Arr, T>`
 
-### 2025-07--09 (feature/array-methods → main)
+### 2025-07-09 (feature/array-methods → main)
 
 + Add two new methods of `Array` namespace:
   + `Array.Reverse<Arr>`
   + `Array.Shift<Arr, Mode>`
 
+### 2025-07-10 (feature/array-methods → main)
+
++ Add a new method of `Array` namespace:
+  + `Array.Unshift<Arr, E>`
+
 ## ⚡ Improvements
 
 ## 🐦‍🔥 No longer broken

lib/Array/index.d.ts

@@ -411,6 +411,20 @@ export type Shift<
     ? ShiftElement
     : never;
 
+/**
+ * This method is like `Array.prototype.unshift`, it returns the new array that
+ * has been unshifted (which means pushing at the first) the new element.
+ * 
+ * @param Arr The array to be unshifted.
+ * @param E The new element to be unshifted into the `Arr`.
+ * @returns The new array.
+ * 
+ * @example
+ * type Unshift1 = Array.Unshift<[1, 2, 3], "1">; // ["1", 1, 2, 3]
+ * type Unshift2 = Array.Unshift<[], 1>;          // [1]
+ */
+export type Unshift<Arr extends unknown[], E extends unknown> = [E, ...Arr];
+
 }
 
 export default Array;

test/lib-Array.test.ts

@@ -17,6 +17,17 @@ type CaseLibArray = [
   Expect<Equal<Array.CreateArrayFromLength<0>, []>>,
   Expect<Equal<Array.CreateArrayFromLength<-1>, []>>,
 
+  // Array.Unshift
+  Expect<Equal<Array.Unshift<[1,2,3], 4>, [4,1,2,3]>>,
+  Expect<Equal<Array.Unshift<[], []>, [[]]>>,
+  Expect<Equal<Array.Unshift<[1], []>, [[],1]>>,
+  Expect<Equal<Array.Unshift<[], 1>, [1]>>,
+  Expect<Equal<Array.Unshift<[{a:1},{b:2}], {c:3}>, [{c:3},{a:1},{b:2}]>>,
+  Expect<Equal<Array.Unshift<[[1,2],[3,4]], [5,6]>, [[5,6],[1,2],[3,4]]>>,
+  Expect<Equal<Array.Unshift<[1|2,3], 4|5>, [4|5,1|2,3]>>,
+  Expect<Equal<Array.Unshift<[], {a:string,b:number}>, [{a:string,b:number}]>>,
+  Expect<Equal<Array.Unshift<[{x:number}], {y:boolean}>, [{y:boolean},{x:number}]>>,
+
   // Array.MultipleConcat
   Expect<Equal<Array.MultipleConcat<[[1,2,3],[4,2,3],[undefined,true]]>, [1,2,3,4,2,3,undefined,true]>>,
   Expect<Equal<Array.MultipleConcat<[[],[1],[],[2]]>, [1,2]>>,
@@ -51,6 +62,13 @@ type CaseLibArray = [
   Expect<Equal<Array.IndexOf<[1,2,3], 4>, -1>>,
   Expect<Equal<Array.IndexOf<[1,2,1], 1>, 0>>,
 
+  // Array.Shift
+  Expect<Equal<Array.Shift<[1,2,3]>, [2,3]>>,
+  Expect<Equal<Array.Shift<["1"]>, []>>,
+  Expect<Equal<Array.Shift<[], "get-rest">, never>>,
+  Expect<Equal<Array.Shift<[1,2,3], "get-shift-element">, 1>>,
+  Expect<Equal<Array.Shift<["1"], "get-shift-element">, "1">>,
+
   // Array.IsFlatten
   Expect<Equal<Array.IsFlatten<[1,2,3]>, true>>,
   Expect<Equal<Array.IsFlatten<[]>, true>>,

test/script/lib-gen.sh

@@ -36,6 +36,8 @@ declare -A test_cases=(
   ["Array.Join"]="[1,2,3]∷\"1,2,3\" [-1,\".\",9]‖\"-\"∷\"-1-.-9\" [1,2,3]‖\"\"∷\"123\""
   ["Array.Pop"]="[1,2,3]∷[1,2] [1]‖\"get-rest\"∷[] []‖\"get-rest\"∷never [1,2,3]‖\"get-pop-element\"∷3 [1]‖\"get-pop-element\"∷1 []‖\"get-pop-element\"∷never"
   ["Array.Push"]="[1,2,3]‖\"1\"∷[1,2,3,\"1\"] []‖1∷[1] []‖[]∷[[]]"
+  ["Array.Shift"]="[1,2,3]∷[2,3] [\"1\"]∷[] []‖\"get-rest\"∷never [1,2,3]‖\"get-shift-element\"∷1 [\"1\"]‖\"get-shift-element\"∷\"1\""
+  ["Array.Unshift"]="[1,2,3]‖4∷[4,1,2,3] []‖[]∷[[]] [1]‖[]∷[[],1] []‖1∷[1] [{a:1},{b:2}]‖{c:3}∷[{c:3},{a:1},{b:2}] [[1,2],[3,4]]‖[5,6]∷[[5,6],[1,2],[3,4]] [1|2,3]‖4|5∷[4|5,1|2,3] []‖{a:string,b:number}∷[{a:string,b:number}] [{x:number}]‖{y:boolean}∷[{y:boolean},{x:number}]"
 
   ["BigInteger.ToString"]="2n∷\"2\" -2n∷\"-2\" 0n∷\"0\""
   ["BigInteger.IsNegative"]="-23n∷true 26n∷false 0n∷false"