Lodash _.pullAllBy() method
What you’ll learn
- How
_.pullAllBy(array, values, iteratee)compares mapped keys instead of whole object references. - Why this extends _.pullAll() when rows carry ids, codes, or other stable fields.
- How string shorthand paths differ from custom iteratee functions for the projection step.
- Try each example in the editor (
?tryit=1,2,3) with Lodash from a CDN.
Prerequisites
Read _.pullAll() and _.pull() first; you should be comfortable with iteratees as in _.differenceBy()-style APIs.
- You understand that in-place array helpers affect every reference to that array.
- You can run snippets in Node or open the Try-it labs in a browser.
Overview
_.pullAllBy removes elements from the first array when their projected value matches the projection of any entry in the values array. It is the pull-family counterpart to other “By” helpers: same mutation story, but comparisons happen after your iteratee runs.
Project first
Compare ids, codes, or numeric features instead of whole object identity.
In place
The target array is mutated; the return value is the same reference.
Shorthand paths
Pass a string path such as groupId for simple property access on plain objects.
Syntax
_.pullAllBy(array, values, [iteratee=_.identity])- array: collection to mutate.
- values: array of reference values; each is mapped with
iterateeto build the exclusion set. - iteratee: string path, function, or built-in shorthand applied to elements of both
arrayandvalues. - Returns: the same
arrayreference after removals (SameValueZero on mapped results).
Property path shorthand
A string iteratee picks a field from every row; any row whose x matches a value entry’s x is removed.
import pullAllBy from "lodash/pullAllBy";
const points = [{ x: 1 }, { x: 2 }, { x: 3 }, { x: 1 }];
pullAllBy(points, [{ x: 1 }, { x: 3 }], "x");
// points is now [{ x: 2 }]Rows keyed by id
The values array only needs enough shape for the iteratee—lightweight stubs with the same id field are enough to ban every matching row.
import pullAllBy from "lodash/pullAllBy";
const users = [
{ id: 1, name: "Ada" },
{ id: 2, name: "Bob" },
{ id: 1, role: "admin" }
];
pullAllBy(users, [{ id: 1 }], "id");
// users is now [{ id: 2, name: "Bob" }]Function iteratee
Use a function when the comparison key is derived—for example bucketing floats with Math.floor.
import pullAllBy from "lodash/pullAllBy";
const samples = [2.5, 2.1, 3.7];
pullAllBy(samples, [2.2], Math.floor);
// samples is now [3.7]📋 _.pullAllBy vs _.pullAll vs _.differenceBy
| API | Mutation | Note |
|---|---|---|
_.pullAllBy(array, values, iteratee) | Mutates array | Removes in place when projections match the ban list |
_.pullAll(array, values) | Mutates array | Compares raw elements only |
_.differenceBy(array, values, iteratee) | Returns a new array | Use when you must keep the original untouched |
Pitfalls to avoid
Colliding projections
If the iteratee maps different rows to the same primitive, pulling one criterion can remove more rows than you visually associate with a single value object.
Deep paths
String shorthand covers simple property names; deeply nested access usually belongs to a function iteratee or get-style helpers before pulling.
Need richer equality
When projections are not enough, use _.pullAllWith() and supply an explicit comparator.
❓ FAQ
Summary
- Purpose:
_.pullAllBy(array, values, iteratee)removes elements whose iteratee result matches any mapped value entry (SameValueZero). - Mutation: the first array is updated in place; clone before calling when isolation matters.
- Next: Lodash _.pullAllWith(), _.pullAll() (earlier in this track), or the array methods hub.
When mapped primitives are not enough, use _.pullAllWith() so a comparator function can decide each (arrVal, othVal) pair.
About the author
6 people found this page helpful