Skip to main content

difference()

difference<T>(array, values): T[]

Creates an array of values from the first array that are not included in the second array.

note

Uses strict equality (===). Preserves duplicates from the source array.

Type Parameters​

T: T​

The type of elements in the arrays.

Parameters​

array: readonly T[]​

The source array to inspect.

values: readonly T[]​

The array of values to exclude.

Returns: T[]​

A new array of filtered values.

Since​

2.0.0

Performance​

O(n·m) for small exclusion sets (≤16), O(n + m) with hash map for larger ones.

Also known as​

diff (Radashi) · difference (Lodash, es-toolkit, Remeda, Ramda, Effect, Modern Dash) · ❌ (Antfu)

Example​

difference([1, 2, 3, 4, 5], [2, 4]);
// => [1, 3, 5]

difference([1, 1, 2, 2, 3], [2]);
// => [1, 1, 3]

How it works?​

Returns elements from the first array that are not present in the exclusion array. Uses a Set for O(1) lookups.

Use Cases​

Filter out unwanted items from a list 📌​

Remove specific elements from an array efficiently. Perfect for excluding blacklisted items, removing duplicates, or filtering selections.

const allFruits = ["apple", "banana", "orange", "grape", "mango"];
const dislikedFruits = ["banana", "grape"];

const favoriteFruits = difference(allFruits, dislikedFruits);
// => ["apple", "orange", "mango"]

Sync available options after user selection 📌​

Update available choices by removing already selected items from the pool. Perfect for multi-select forms, shopping carts, or team member assignments.

const allPermissions = ["read", "write", "delete", "admin", "export"];
const alreadyGranted = ["read", "write"];

const availablePermissions = difference(allPermissions, alreadyGranted);
// => ["delete", "admin", "export"]

Detect new entries in a dataset​

Compare two snapshots to find newly added elements. Perfect for tracking new users, detecting file changes, or monitoring inventory updates.

const previousUsers = ["alice", "bob", "charlie"];
const currentUsers = ["alice", "bob", "charlie", "david", "emma"];

const newUsers = difference(currentUsers, previousUsers);
// => ["david", "emma"]

Detect missing permissions for access control​

Compare required permissions against granted ones to identify gaps. Essential for role-based access control and security audit systems.

const requiredPermissions = ["read", "write", "deploy", "audit"];
const userPermissions = ["read", "write"];

const missingPermissions = difference(requiredPermissions, userPermissions);
// => ["deploy", "audit"]

if (missingPermissions.length > 0) {
  throw new Error(`Missing permissions: ${missingPermissions.join(", ")}`);
}

Find missing dependencies in a project​

Compare required packages against installed ones to detect missing dependencies. Useful for CI pipelines, project scaffolding, and dependency audit tools.

const requiredPackages = ["react", "react-dom", "typescript", "vitest", "eslint"];
const installedPackages = ["react", "react-dom", "typescript"];

const missingPackages = difference(requiredPackages, installedPackages);
// => ["vitest", "eslint"]

console.log(`Install missing: pnpm add -D ${missingPackages.join(" ")}`);