0
# lodash.difference
1

2
The modern build of lodash's `_.difference` as a modular npm package. Creates arrays of unique values from the first array that are not included in other provided arrays using SameValueZero equality comparisons.
3

4
## Package Information
5

6
- **Package Name**: lodash.difference
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash.difference`
10

11
## Core Imports
12

13
```javascript
14
const difference = require('lodash.difference');
15
```
16

17
For ES modules (if supported by your environment):
18

19
```javascript
20
import difference from 'lodash.difference';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const difference = require('lodash.difference');
27

28
// Basic array difference
29
const result1 = difference([1, 2, 3], [4, 2]);
30
// => [1, 3]
31

32
// Multiple comparison arrays
33
const result2 = difference([1, 2, 3, 4, 5], [2, 4], [1]);
34
// => [3, 5]
35

36
// With strings
37
const result3 = difference(['a', 'b', 'c'], ['b', 'd']);
38
// => ['a', 'c']
39

40
// With mixed types
41
const result4 = difference([1, '2', 3, '4'], [1, '4']);
42
// => ['2', 3]
43
```
44

45
## Capabilities
46

47
### Array Difference
48

49
Creates an array of unique values from the first array that are not included in the other provided arrays.
50

51
```javascript { .api }
52
/**
53
 * Creates an array of unique values from the first array that are not included in the other provided arrays.
54
 * Uses SameValueZero equality comparisons for determining inclusion.
55
 * 
56
 * @param {Array} array - The array to inspect
57
 * @param {...Array} [values] - The arrays of values to exclude
58
 * @returns {Array} Returns the new array of filtered values
59
 */
60
function difference(array, ...values);
61
```
62

63
**Behavior Details:**
64

65
- **Equality Comparison**: Uses SameValueZero equality (similar to `===` but treats `NaN` as equal to `NaN`)
66
- **Input Validation**: Returns empty array if first argument is not array-like
67
- **Array-like Support**: Accepts array-like objects (objects with numeric indices and `length` property)
68
- **Variable Arguments**: Accepts any number of comparison arrays as additional arguments
69
- **Flattening**: Comparison arrays are flattened before processing
70
- **Order Preservation**: Result maintains the order of elements from the original array
71

72
**Usage Examples:**
73

74
```javascript
75
const difference = require('lodash.difference');
76

77
// Empty array handling
78
difference(null, [1, 2]); // => []
79
difference(undefined, [1, 2]); // => []
80
difference('not-array', [1, 2]); // => []
81

82
// Array-like objects
83
difference({ 0: 'a', 1: 'b', 2: 'c', length: 3 }, ['b']);
84
// => ['a', 'c']
85

86
// Nested comparison arrays (flattened)
87
difference([1, 2, 3, 4], [[2, 3]], [4]);
88
// => [1] (comparison arrays are flattened: [2, 3, 4])
89

90
// NaN handling (SameValueZero equality)
91
difference([1, NaN, 3], [NaN]);
92
// => [1, 3]
93

94
// No comparison arrays
95
difference([1, 2, 3]);
96
// => [1, 2, 3]
97
```