tessl/npm-arr-diff
Returns an array with only the unique values from the first array, by excluding all values from additional arrays using strict equality for comparisons.
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-arr-diff@4.0.0index.mddocs/
arr-diff
arr-diff is a high-performance utility function for computing array differences by returning elements from the first array that are not present in any of the additional arrays. It uses strict equality (===) for comparisons and offers significant performance improvements over alternatives like array-differ.
Package Information
- Package Name: arr-diff
- Package Type: npm
- Language: JavaScript
- Installation:
npm install arr-diff
Core Imports
const diff = require('arr-diff');Basic Usage
const diff = require('arr-diff');
// Basic array difference
const result = diff(['a', 'b', 'c', 'd'], ['b', 'c']);
console.log(result); // => ['a', 'd']
// Multiple comparison arrays
const result2 = diff(['a', 'b', 'c', 'd'], ['a'], ['c']);
console.log(result2); // => ['b', 'd']
// With numbers
const numbers = diff([1, 2, 3, 4, 5], [2, 4], [5]);
console.log(numbers); // => [1, 3]Capabilities
Array Difference Calculation
Returns elements from the first array that are not present in any of the additional arrays using strict equality for comparisons.
/**
* Returns an array with only the unique values from the first array,
* by excluding all values from additional arrays using strict equality for comparisons.
*
* @param {Array} arr - The source array to compare against
* @param {...Array} arrays - Variable number of arrays to exclude from the first array
* @returns {Array} New array containing elements from arr that don't exist in any of the additional arrays
*/
function diff(arr/* , arrays */);Usage Examples:
const diff = require('arr-diff');
// Simple difference
diff(['a', 'b', 'c'], ['b', 'c']); // => ['a']
// Multiple arrays to exclude
diff(['a', 'b', 'c'], ['a'], ['b']); // => ['c']
// Preserves duplicates in source array
diff(['a', 'a', 'b'], ['b']); // => ['a', 'a']
// Empty comparison arrays
diff(['a', 'b'], []); // => ['a', 'b']
// No differences found
diff(['a'], ['a']); // => []
// Mixed data types (strict equality)
diff([1, '1', 2], [1]); // => ['1', 2]
// Objects and arrays (reference equality)
const obj1 = { id: 1 };
const obj2 = { id: 2 };
diff([obj1, obj2], [obj1]); // => [obj2]Behavior Details:
- Uses strict equality (
===) for all comparisons - Does not modify input arrays (pure function)
- Returns a new array instance
- Handles non-array arguments by treating them as empty arrays
- Preserves the order of elements from the first array
- Preserves duplicates in the first array unless they exist in comparison arrays
- Zero dependencies for lightweight deployment
- Optimized for performance with 2-10x speed improvement over similar libraries
Performance Characteristics:
- Highly optimized implementation with significant performance benefits
- Benchmarked against array-differ showing consistent performance improvements:
- Short arrays: ~7x faster
- Medium arrays: ~7x faster
- Long arrays: ~3x faster
- Long arrays with duplicates: ~3x faster
- Suitable for both small and large array operations
- Memory efficient with minimal overhead