0
# Lodash Concat
1

2
Lodash concat creates a new array concatenating an array with any additional arrays and/or values. This function provides a reliable way to combine arrays without mutating the original array, handling edge cases gracefully.
3

4
## Package Information
5

6
- **Package Name**: lodash
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash` (concat is part of the main lodash library)
10

11
## Core Imports
12

13
```javascript
14
import { concat } from "lodash";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { concat } = require("lodash");
21
```
22

23
Alternative global usage:
24

25
```javascript
26
// If lodash is loaded globally
27
_.concat(array, ...values);
28
```
29

30
## Basic Usage
31

32
```javascript
33
import { concat } from "lodash";
34

35
// Basic concatenation
36
const array = [1];
37
const result = concat(array, 2, [3], [[4]]);
38
console.log(result);
39
// => [1, 2, 3, [4]]
40

41
// Original array is unchanged
42
console.log(array);
43
// => [1]
44

45
// Handling null/undefined input
46
const nullResult = concat(null, 1, 2);
47
console.log(nullResult);
48
// => [1, 2]
49

50
const undefinedResult = concat(undefined, 1, [2], [[3]]);
51
console.log(undefinedResult);
52
// => [1, 2, [3]]
53

54
// Non-array first parameter
55
const stringResult = concat("hello", " ", "world");
56
console.log(stringResult);
57
// => ["hello", " ", "world"]
58
```
59

60
## Capabilities
61

62
### Array Concatenation
63

64
Creates a new array by combining the input array with additional values, handling non-array inputs gracefully.
65

66
```javascript { .api }
67
/**
68
 * Creates a new array concatenating array with any additional arrays and/or values.
69
 * @param {Array} array - The array to concatenate  
70
 * @param {...*} [values] - The values to concatenate
71
 * @returns {Array} Returns the new concatenated array
72
 */
73
function concat(array, ...values);
74
```
75

76
**Behavior Details:**
77

78
- **Immutable Operation**: Never modifies the original array
79
- **Type Conversion**: If `array` is not an array:
80
  - `null` or `undefined` becomes an empty array `[]`
81
  - Other values become a single-element array `[Object(value)]`
82
- **Flattening**: Values are flattened by one level only
83
- **Variable Arguments**: Accepts any number of additional values after the first parameter
84
- **Sparse Arrays**: Treats sparse arrays as dense arrays (undefined values are preserved)
85

86
**Usage Examples:**
87

88
```javascript
89
import { concat } from "lodash";
90

91
// Multiple arrays and values
92
const arr1 = [1, 2];
93
const arr2 = [3, 4];
94
const result = concat(arr1, arr2, 5, [6, 7]);
95
console.log(result);
96
// => [1, 2, 3, 4, 5, 6, 7]
97

98
// Nested array handling (one level flattening)
99
const nested = concat([1], [[2, 3]], [[[4]]]);
100
console.log(nested);
101
// => [1, [2, 3], [[4]]]
102

103
// Empty array concatenation
104
const empty = concat([], 1, 2, 3);
105
console.log(empty);
106
// => [1, 2, 3]
107

108
// Mixed data types
109
const mixed = concat([1, 2], "hello", true, { key: "value" });
110
console.log(mixed);
111
// => [1, 2, "hello", true, { key: "value" }]
112

113
// Sparse arrays (treated as dense)
114
const sparse = concat(Array(2), Array(1));
115
console.log(sparse);
116
// => [undefined, undefined, undefined]
117
console.log('0' in sparse); // => true
118
```