Searching arrays

What searching an array means

An array is a list of values in order. Each value sits at a numbered position called an index. The first index is 0, the next is 1, and so on.

Searching an array means asking the list a question. There are two kinds of question:

• Search by value. You already know the exact value, like the string "draft". You ask: "Is it in the list? At which index?"
• Search by test. You don't know the exact value. You only know a rule, like "the first product that costs more than 20". You ask: "Which item passes this test?"

JavaScript has a method for each kind of question. Some read the list from left to right. Some read it from right to left. Some stop as soon as they know the answer.

const cart = ["tea", "bread", "tea"];
console.log(cart.includes("bread"));
console.log(cart.indexOf("tea"));

Line by line:

1. Line 1 makes a short list called cart. It holds "tea", "bread", and "tea" again.
2. Line 2 asks a yes-or-no question: is "bread" in the list? It is, so it prints true.
3. Line 3 asks for a position: where is "tea"? It prints 0, the index of the first "tea".

This lesson uses ideas from earlier lessons:

• Arrays and indexes.
• The strict equality check ===, from Comparisons.
• How objects are shared, from Objects & references.
• Functions you pass to other functions, from Function expressions & callbacks and Arrow functions.

Each idea is explained again when it shows up.

Use these three methods when you already know the exact value you want. You pass the value in. The method compares it with each item in the list.

• array.indexOf(value) gives the first index where the value is, or -1 if it is not there.
• array.lastIndexOf(value) gives the last index where the value is, or -1.
• array.includes(value) gives true if the value is there, and false if not.

Why -1 for "not found"? Because 0 is a real index: it means "the first item". No item can sit at index -1, so it is safe to use as "not found".

1const codes = ["A1", "B2", "A1", NaN];2const firstA1 = codes.indexOf("A1");3const lastA1 = codes.lastIndexOf("A1");4const hasNaN = codes.includes(NaN);5const nanIndex = codes.indexOf(NaN);6 7const saved = { id: 1 };8const objects = [saved, { id: 1 }];9const sameReference = objects.indexOf(saved);10const newObject = objects.indexOf({ id: 1 });11 12console.log(firstA1, lastA1, hasNaN, nanIndex);13console.log(sameReference, newObject);

Lines 1 to 5 search a list of codes:

1. Line 1 makes the list. "A1" is at index 0 and again at index 2. The last item is NaN.
2. Line 2: indexOf("A1") finds the first "A1", at index 0.
3. Line 3: lastIndexOf("A1") finds the last "A1", at index 2.
4. Line 4: includes(NaN) gives true.
5. Line 5: indexOf(NaN) gives -1, even though NaN is in the list.

Lines 4 and 5 need an explanation. NaN means "Not a Number". It is the special number you get from a failed math step, like 0 / 0. NaN is the one value where NaN === NaN is false.

indexOf compares items with ===, so it never finds NaN. includes uses a slightly different rule called SameValueZero. It works like ===, except that it treats NaN as equal to NaN. So includes(NaN) finds it.

Lines 7 to 10 search a list of objects:

1. Line 7 makes one object and keeps it in the variable saved.
2. Line 8 makes a list. It holds saved, then a second object that only looks the same.
3. Line 9 searches for saved. That exact object is at index 0, so the answer is 0.
4. Line 10 searches for a brand-new { id: 1 }. It is a third object, not in the list, so the answer is -1.

Each pair of curly braces { } makes a new object. An exact search asks "Is this the very same object?", not "Does it look the same?". That is the rule from Objects & references.

const statuses = ["draft", "sent", "draft"];
console.log(statuses.indexOf("draft", 1));
console.log(statuses.includes("draft", 2));

All three methods take an optional second argument. It is called fromIndex: the index where the search starts.

1. Line 1 makes a list: "draft" at index 0, "sent" at index 1, "draft" at index 2.
2. Line 2 starts at index 1, so it skips the first "draft". The next one is at index 2, so it prints 2.
3. Line 3 starts at index 2. The search includes index 2 itself, so it prints true.

Strings have methods with the same names, such as "banana".indexOf("na") and "banana".includes("na"). This lesson is only about the array methods. The String methods lesson covers searching text.

Real lists often hold objects, and you rarely know the exact object you want. You know a rule instead. For example:

• the first product that is out of stock,
• the first bill that costs more than 100,
• the first user with no profile picture.

For these, you write the rule as a small function. You pass that function to the search method. A function you pass to another function is called a callback. The method calls it for you, once per item, and hands it the item. Your callback returns true for "this one matches" or false for "keep looking".

• find(callback) gives the first item that passes the test, or undefined if none does.
• findIndex(callback) gives the index of the first item that passes, or -1.

The callback does not have to return exactly true. Any truthy value counts as a pass. Truthy means a value that if treats as true, like 1 or "yes".

const products = [
  { name: "Tea", inStock: true },
  { name: "Tent", inStock: false },
];
const firstOut = products.find((product) => !product.inStock);
console.log(firstOut.name);

1. Lines 1 to 4 make a list of two products. Tea is in stock. Tent is not.
2. Line 5 calls find with a callback. The callback gets one product and returns !product.inStock. The ! flips the value, so the test is true when the product is not in stock.
3. Tea fails the test. Tent passes, so find returns the Tent object and keeps it in firstOut.
4. Line 6 prints firstOut.name, which is Tent.

Once Tent passes, find stops. It does not check any later products. This is called stopping early (programmers also say short-circuiting).

Now step through a recording of a real run. Pick a test, then press Step. Watch two things:

• The callback gets one product at a time.
• find stops as soon as one product passes.

1const products = [Run2  { name: "Tea", price: 8, inStock: true },3  { name: "Tent", price: 55, inStock: false },4  { name: "Torch", price: 24, inStock: true },5];6 7const match = products.find((product) => {8  return product.price > 20;9});10 11console.log(match?.name);

1const products = [2  { name: "Tea", price: 8, inStock: true },3  { name: "Tent", price: 55, inStock: false },4  { name: "Torch", price: 24, inStock: true },5  { name: "Notebook", price: 12, inStock: false },6];7products.find((product) => product.price > 20);

The lab also has filter, so you can compare. find returns the first match only. filter checks every item and returns all the matches in a new array. The next lesson, map, filter & reduce, teaches filter fully.

Sometimes the answer you want is near the end of the list. For example:

• the newest error in a log,
• the most recent unpaid bill,
• the last message from one person.

findLast and findLastIndex take the same kind of callback as find. The only difference is the direction: they start at the last item and move left.

const logs = ["ok", "error", "ok", "error"];
const latestError = logs.findLast((entry) => entry === "error");
const latestErrorIndex = logs.findLastIndex((entry) => entry === "error");
console.log(latestError, latestErrorIndex);

1. Line 1 makes a log list. "error" is at index 1 and at index 3.
2. Line 2: findLast starts at index 3. That item is "error", so it returns "error".
3. Line 3: findLastIndex runs the same test from the same end and returns the index, 3.
4. Line 4 prints both answers: error 3.

1const logs = ["info", "error", "warn", "error"];2const lastError = logs.findLast((entry) => entry === "error");3const lastErrorIndex = logs.findLastIndex((entry) => entry === "error");4 5console.log(lastError);6console.log(lastErrorIndex);7console.log(typeof Array.prototype.findLast === "function");

These two methods were added in ES2023, the 2023 edition of JavaScript. All modern browsers have them. If your site must work in older browsers, check first with a feature check: typeof Array.prototype.findLast === "function". Array.prototype is the shared object that every array gets its methods from. If the check is false, the browser does not have the method. Your project can then add it with a polyfill: a small piece of code that adds a missing method to older browsers.

Some questions don't need the item or its index. They only need yes or no. A yes-or-no value is called a boolean: true or false.

• some(callback) asks: "Does at least one item pass?" It returns true at the first pass.
• every(callback) asks: "Do all items pass?" It returns false at the first fail.

const scores = [72, 55, 90];
const hasFailingScore = scores.some((score) => score < 60);
const allAtLeastFifty = scores.every((score) => score >= 50);
console.log(hasFailingScore, allAtLeastFifty);

1. Line 1 makes a list of three scores: 72, 55, and 90.
2. Line 2 asks: is at least one score below 60? 55 is, so hasFailingScore is true.
3. Line 3 asks: is every score 50 or more? All three are, so allAtLeastFifty is true.
4. Line 4 prints true true.

Both answers are true, but the two methods asked different questions.

1const scores = [84, 91, 77];2const hasPerfect = scores.some((score) => score === 100);3const allPassing = scores.every((score) => score >= 60);4 5const none = [];6console.log(hasPerfect);7console.log(allPassing);8console.log(none.some(Boolean));9console.log(none.every(Boolean));

The empty list gives answers that look odd at first:

• [].some(Boolean) is false. some needs one item that passes, and an empty list has none.
• [].every(Boolean) is true. every only says false when it finds an item that fails, and an empty list has none.

(Boolean here is the built-in function that turns any value into true or false. It is used as the callback.) Mathematicians call the second rule vacuous truth: "all items pass" is true when there are no items to fail.

Read each row as one method. The columns say what you get back, when to use it, and when it stops.

Small habits that prevent bugs

• The callback gets three things: the current item, its index, and the whole array. If you need the position, use findIndex. Don't find the item and then search again for its index.
• Search methods only read the array. They don't sort it, remove items, or replace items. Keep your callback a simple test that changes nothing.
• Make values match before an exact search. For example, if stored statuses are lowercase, turn the text a user typed into lowercase before you search.
• Plan for "not found". find gives undefined, and the index methods give -1. Reading a property of undefined throws an error. So check the result first, or use optional chaining: match?.name gives undefined instead of an error when match is undefined.
• The callback's answer only needs to be truthy, but a clear comparison is easier to read. Write item.quantity > 1, which is plainly true or false.
• Each search reads the array from one end, one item at a time. If your code checks the same long list for exact values many times, a Set may be better. A Set is a collection of unique values whose has() check doesn't read every item.

Before you type a method name, decide what kind of answer you need: an exact value's position, a first match, a last match, or just yes or no. Sort the cards below by that answer.

Where you'll use this

You'll search arrays whenever a page holds a list of real data. For example:

• A shopping cart checks whether an item is already in it before adding another row.
• A settings form finds the first field that is filled in wrong.
• A dashboard shows the newest error from a log.
• A permission check asks whether a user has one needed role, or all needed roles.

const cart = [
  { name: "Tea", quantity: 1 },
  { name: "Notebook", quantity: 2 },
];
const hasNotebook = cart.some((item) => item.name === "Notebook");
const firstMany = cart.find((item) => item.quantity > 1);
console.log(hasNotebook, firstMany.name);

1. Lines 1 to 4 make a cart with one Tea and two Notebooks.
2. Line 5 uses some to ask: is there a Notebook in the cart? Yes, so hasNotebook is true.
3. Line 6 uses find to get the first item with a quantity above 1. That is the Notebook item.
4. Line 7 prints true Notebook.

Neither method changes the cart. That makes them safe to use while a page is being drawn on screen.

All the methods in this lesson read the array and give back an answer. Later lessons cover methods that build new arrays, sort arrays, and copy arrays safely.

Common misconceptions

For each question, first ask: does this method give back an index, an item, or a boolean? Try an answer before you read the explanations. Many wrong answers are real bugs people write.

Key takeaways

• indexOf and lastIndexOf give an index, or -1 if the value is not there. includes gives true or false.
• includes(NaN) finds NaN. indexOf(NaN) never does.
• An exact search for an object looks for that very object. To match by a property, like an id, use a callback method.
• find and findIndex stop at the first item that passes the test. findLast and findLastIndex do the same, starting from the end.
• some asks "at least one?" and every asks "all?". Both stop as soon as they know the answer.
• Never write if (arr.indexOf(x)). Use includes, or compare the index with -1.

Up next: map, filter & reduce.