feat: add concat function (#388)

Author: aleclarson

.github/next-minor.md

@@ -4,7 +4,9 @@ The `####` headline should be short and descriptive of the new functionality. In
 
 ## New Functions
 
-####
+#### Add `concat` function
+
+https://github.com/radashi-org/radashi/pull/388
 
 ## New Features
 

benchmarks/array/concat.bench.ts

@@ -0,0 +1,13 @@
+import * as _ from 'radashi'
+
+bench('concat with simple values', () => {
+  _.concat('a', null, 'b', undefined, 'c')
+})
+
+bench('concat with nested arrays', () => {
+  _.concat(1, [2, 3], null, 4, [5, [6, 7]])
+})
+
+bench('concat with mixed types', () => {
+  _.concat('a', 1, [true, { x: 2 }], null)
+})

docs/array/concat.mdx

@@ -0,0 +1,21 @@
+---
+title: concat
+description: Flattens and filters nullish values from arguments
+---
+
+### Usage
+
+The `concat` function combines multiple values and arrays into a single array, while:
+
+- Flattening nested arrays one level deep
+- Filtering out `null` and `undefined` values
+- Preserving the type information of the remaining values
+
+Other falsy values (e.g. `0`, `false`, `''`, `NaN`) are preserved.
+
+```ts
+import { concat } from 'radashi'
+
+const result = concat('a', null, ['b', undefined], 'c')
+// => ['a', 'b', 'c']
+```

src/array/concat.ts

@@ -0,0 +1,37 @@
+export type Concat<T extends readonly any[]> = T[number] extends infer TElement
+  ? (TElement extends readonly (infer TNestedElement)[]
+      ? Exclude<TNestedElement, undefined | null>
+      : Exclude<TElement, undefined | null>)[]
+  : unknown[]
+
+/**
+ * Flattens and filters nullish values from arguments, returning a new
+ * array containing only the non-nullish elements. Nested arrays are
+ * flattened one level deep.
+ *
+ * @see https://radashi.js.org/reference/array/concat
+ * @example
+ * ```ts
+ * const result = _.concat('', ['a'], undefined, [null, 'b'])
+ * // => ['', 'a', 'b']
+ * ```
+ * @example
+ * ```ts
+ * const result = _.concat(1, [2, [3]], null)
+ * // => [1, 2, [3]] // Note: only flattens one level
+ * ```
+ */
+export function concat<T extends readonly [any, any, ...any[]]>(
+  ...values: T
+): Concat<T> {
+  const result: any[] = []
+  const append = (value: unknown) => value != null && result.push(value)
+  for (const value of values) {
+    if (Array.isArray(value)) {
+      value.forEach(append)
+    } else {
+      append(value)
+    }
+  }
+  return result as Concat<T>
+}

src/mod.ts

@@ -4,6 +4,7 @@ export * from './array/cartesianProduct.ts'
 export * from './array/castArray.ts'
 export * from './array/castArrayIfExists.ts'
 export * from './array/cluster.ts'
+export * from './array/concat.ts'
 export * from './array/counting.ts'
 export * from './array/diff.ts'
 export * from './array/first.ts'

tests/array/concat.test-d.ts

@@ -0,0 +1,13 @@
+import * as _ from 'radashi'
+
+describe('concat', () => {
+  test('preserve non-nullish types', () => {
+    const result = _.concat([] as readonly (string | null)[], false, 0)
+    expectTypeOf(result).toEqualTypeOf<(string | boolean | number)[]>()
+  })
+
+  test('preserve const types', () => {
+    const result = _.concat([1, 2, null] as const, 3 as const)
+    expectTypeOf(result).toEqualTypeOf<(1 | 2 | 3)[]>()
+  })
+})

tests/array/concat.test.ts

@@ -0,0 +1,28 @@
+import * as _ from 'radashi'
+
+describe('concat', () => {
+  test('nullish values are filtered out', () => {
+    const result = _.concat('a', null, ['b', undefined], 'c')
+    expect(result).toEqual(['a', 'b', 'c'])
+  })
+
+  test('deeply nested arrays', () => {
+    const result = _.concat(1, [2, [3, 4]], null)
+    expect(result).toEqual([1, 2, [3, 4]])
+  })
+
+  test('empty inputs', () => {
+    expect(_.concat(null, undefined)).toEqual([])
+    expect(_.concat([], null)).toEqual([])
+  })
+
+  test('mixed types', () => {
+    const result = _.concat(1, 'two', [true, { a: 1 }], null)
+    expect(result).toEqual([1, 'two', true, { a: 1 }])
+  })
+
+  test('other falsy values are preserved', () => {
+    const result = _.concat(false, ['', 0], [null, undefined])
+    expect(result).toEqual([false, '', 0])
+  })
+})