chore: deprecate flat (#165)

Co-authored-by: Alec Larson <[email protected]>

docs/array/flat.mdx

@@ -3,6 +3,12 @@ title: flat
 description: Flatten an array of arrays into a single dimension
 ---
 
+:::caution[Deprecated]
+This function is deprecated. Use `Array.prototype.flat` instead, which is widely available and supports both deep and shallow flattening.
+
+[MDN: Array.prototype.flat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat)
+:::
+
 ### Usage
 
 Given an array that contains many arrays, return a new array where all items from the children are present at the top level.

src/array/flat.ts

@@ -2,6 +2,8 @@
  * Given an array of arrays, returns a single dimensional array with
  * all items in it.
  *
+ * @deprecated Use [Array.prototype.flat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat) instead.
+ *
  * @see https://radashi-org.github.io/reference/array/flat
  * @example
  * ```ts
@@ -10,8 +12,5 @@
  * ```
  */
 export function flat<T>(lists: readonly T[][]): T[] {
-  return lists.reduce((acc, list) => {
-    acc.push(...list)
-    return acc
-  }, [])
+  return lists.flat()
 }