feat: NonEmptyArray utility type

.changeset/khaki-cobras-bathe.md

@@ -0,0 +1,5 @@
+---
+"@sv443-network/userutils": minor
+---
+
+Added utility type `NonEmptyArray` for typing an array with at least 1 item

README-summary.md

@@ -52,6 +52,7 @@ If you like using this library, please consider [supporting the development ❤
     - [tr.getLanguage()](https://github.com/Sv443-Network/UserUtils#trgetlanguage) - returns the currently active language
 - Utility types for TypeScript
     - [Stringifiable](https://github.com/Sv443-Network/UserUtils#stringifiable) - any value that is a string or can be converted to one (implicitly or explicitly)
+    - [NonEmptyArray](https://github.com/Sv443-Network/UserUtils#nonemptyarray) - any array that should have at least one item
 
 <br><br>
 

README.md

@@ -56,6 +56,7 @@ View the documentation of previous major releases: [2.0.1](https://github.com/Sv
     - [tr.getLanguage()](#trgetlanguage) - returns the currently active language
   - [**Utility types for TypeScript:**](#utility-types)
     - [Stringifiable](#stringifiable) - any value that is a string or can be converted to one (implicitly or explicitly)
+    - [NonEmptyArray](https://github.com/Sv443-Network/UserUtils#nonemptyarray) - any array that should have at least one item
 
 <br><br>
 
@@ -1380,6 +1381,32 @@ logSomething(barObject); // Type Error
 
 </details>
 
+<br>
+
+## NonEmptyArray
+This type describes an array that has at least one item.  
+Use the generic parameter to specify the type of the items in the array.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import type { NonEmptyArray } from "@sv443-network/userutils";
+
+function logFirstItem(array: NonEmptyArray<string>) {
+  console.log(parseInt(array[0]));
+}
+
+function somethingElse(array: NonEmptyArray) {
+  // array is typed as NonEmptyArray<unknown> when not passing a
+  // generic parameter, so this throws a TS error:
+  console.log(parseInt(array[0])); // Argument of type 'unknown' is not assignable to parameter of type 'string'
+}
+
+logFirstItem(["04abc", "69"]); // 4
+```
+
+</details>
+
 <br><br><br><br>
 
 <!-- #MARKER Footer -->

lib/array.ts

@@ -1,5 +1,8 @@
 import { randRange } from "./math";
 
+/** Describes an array with at least one item */
+export type NonEmptyArray<T = unknown> = [T, ...T[]];
+
 /** Returns a random item from the passed array */
 export function randomItem<T = unknown>(array: T[]) {
   return randomItemIndex<T>(array)[0];

lib/misc.ts

@@ -21,7 +21,7 @@ export function pauseFor(time: number) {
 
 /**
  * Calls the passed {@linkcode func} after the specified {@linkcode timeout} in ms (defaults to 300).  
- * Any subsequent calls to this function will reset the timer and discard previous calls.
+ * Any subsequent calls to this function will reset the timer and discard all previous calls.
  */
 export function debounce<TFunc extends (...args: TArgs[]) => void, TArgs = any>(func: TFunc, timeout = 300) { // eslint-disable-line @typescript-eslint/no-explicit-any
   let timer: number | undefined;