Choosing a data structure

Pick the right container for your data

JavaScript gives you several ways to keep a group of values. This lesson compares five of them:

• An array keeps values in a numbered list.
• An object keeps values under names, such as theme.
• A Map keeps values under keys, and a key can be any value.
• A Set keeps each value only once.
• A WeakMap sticks extra data onto objects. The data goes away when its object is no longer used.

Each of these is a data structure: a way to arrange data so that some jobs are easy. Your choice also tells other people what your data is. It says "this is a list", or "look this up by name", or "no repeats here".

This lesson builds on earlier lessons: arrays, objects, Map and Set, Set methods, WeakMap and WeakSet, and JSON. You don't need any math. When we talk about speed, we only ask one question: how much more work does the code do when the data gets bigger?

const cart = ["tea", "tea"];
console.log(cart.length, cart[0]);

Line 1 makes an array called cart that holds "tea" twice. Line 2 prints the number of items and the first item: 2 tea. The cart keeps both copies, in the order they were added. For this data, order and repeats matter, so an array fits.

The next sections cover four things:

• Finding a value versus keeping things in order.
• Keys, and values that appear more than once.
• How the work grows as the data grows.
• Splitting a list into groups with Object.groupBy and Map.groupBy.

An array is like a numbered line of people. It is great when position matters: the first task, the last message, or scores sorted from high to low. But say you ask, "Is Ada in the line?" The array may have to check each person, one by one, until it finds Ada.

A Set is like a guest list. It answers one question: is this value in, or not? A Map or an object is like a phone book. You give it a key, and it goes straight to the value for that key. There is no magic here. JavaScript arranges the values inside a Set, a Map, or an object so it can find a key quickly.

const todos = ["buy tea", "buy tea"];
console.log(todos.includes("buy tea"), todos.length);

Line 1 makes a to-do list with the same task twice. On line 2, todos.includes("buy tea") checks whether the task is in the list. It gives true. todos.length gives 2, because the list still has both entries. So line 2 prints true 2. If you only cared whether the task is there, a Set would say that more clearly.

1const blockedNames = ["bot", "scraper", "bot"];Run2const blockedSet = new Set(blockedNames);3const name = "bot";4const arrayAnswer = blockedNames.includes(name);5const setAnswer = blockedSet.has(name);6console.log(arrayAnswer, setAnswer);

Both checks give the same answer. So the choice is not about the answer. It is about the rule you mean, and how often your program repeats the check.

A duplicate is a value that appears more than once. Duplicates are not always a mistake. A shopping cart can hold two of the same mug. A search history can hold the same search twice. Arrays allow duplicates, because each entry has its own position. Sets do not: a value is either in the Set or not.

Keys have rules too. A plain object's keys are always strings (text) or Symbols. That makes objects a great fit for JSON-style records such as { theme: "dark" }. But it also means the number 1 and the string "1" become the same key. A Map keeps each key as it is. A number stays a number, and an object key stays that exact object.

const prices = {};
prices[1] = "number key";
prices["1"] = "text key";
console.log(prices[1]);

Line 1 makes an empty object. Line 2 stores a value under the number key 1. Line 3 stores a value under the string key "1". Both become the same property name, "1", so line 3 replaces the value from line 2. Line 4 prints text key. If the difference between 1 and "1" matters, use a Map.

1const objectKey = { id: 1 };Run2const plain = {};3plain[1] = "number one";4plain["1"] = "string one";5const typed = new Map();6typed.set(1, "number one");7typed.set("1", "string one");8typed.set(objectKey, "object key");9console.log(plain[1], typed.size, typed.get(objectKey));

The table below compares all five structures. Each row is one structure. Each column answers one question about it.

To think about speed, start with growth: how much more work happens when the data gets bigger? Say a loop checks blocked.includes(user) for every user. Each check may walk through the whole blocked array again. Instead, make a Set from the array once. Then each check can be blockedSet.has(user), which goes straight to the answer.

You may see this written as O(n) and O(1). This way of writing is called Big-O notation:

• O(n) means the work grows with the number of items, n. Searching an array is usually like this.
• O(1) means the work stays about the same, however many items there are. A Set check is built to be like this.

For now, think of it as "walking the line" versus "checking the guest list".

const blocked = ["bot", "spam"];
const blockedSet = new Set(blocked);
console.log(blocked.includes("bot"), blockedSet.has("bot"));

Line 1 is the list you start with. Line 2 makes a Set from it. That takes some work, but only once. Line 3 prints true true, because both answer the same question. For one small check, the array alone is simpler. For many checks, reusing the Set saves walking the array again and again.

1const items = Array.from({ length: 1000 }, (_, i) => "item-" + i);2const set = new Set(items);3items.includes("item-999"); // may scan many items4set.has("item-999");       // asks the Set lookup table

A benchmark is a test that times your code. Be careful with its numbers. Timings change with your computer, your browser, battery saving, and whatever else is running. The playground only runs when you click. It does five short runs and shows the median, which is the middle result. The numbers are true for this device only. That's why the lesson's tests check that the code is correct, not how fast it is.

Grouping splits one list into smaller lists, called groups. Each item goes into a group based on a key. JavaScript added two tools for this in 2024 (ES2024):

• Object.groupBy(items, callback) gives back a plain object. Use it when each group's key is a string (or a Symbol), such as "paid".
• Map.groupBy(items, callback) gives back a Map. Use it when the keys are objects, or other values that are not strings.

The callback is a function you pass in. JavaScript calls it once for each item. It returns the key of the group that item belongs in.

const orders = [
  { id: 1, status: "paid" },
  { id: 2, status: "new" },
  { id: 3, status: "paid" },
];
const byStatus = Object.groupBy(orders, order => order.status);
console.log(byStatus.paid.length);

The callback on line 6, order => order.status, returns each order's status. JavaScript makes one array for each status it sees: paid and new. Line 7 reads the paid group and prints 2. Inside each group, the orders keep the order they had in the first list.

Does your browser have these tools? Checking your browser once the page has loaded…

1const products = [Run2  { name: "Notebook", category: "stationery" },3  { name: "Pen", category: "stationery" },4  { name: "Tea", category: "pantry" },5];6const byCategory = Object.groupBy(products, item => item.category);7const prototype = Object.getPrototypeOf(byCategory);8console.log(byCategory.stationery.map(item => item.name).join(", "));9console.log(prototype === null);

When the group key is an object, use Map.groupBy. Here, each product's owner is an object.

1const kitchen = { team: "kitchen" };2const office = { team: "office" };3const products = [4  { name: "Tea", owner: kitchen },5  { name: "Notebook", owner: office },6];7const byOwner = Map.groupBy(products, item => item.owner);8console.log(byOwner.get(kitchen).map(item => item.name));

Line 7 groups the products by their owner object. Line 8 asks for the group of the exact kitchen object. It prints an array with one name in it, "Tea".

One more detail about Object.groupBy. Most objects borrow methods, such as hasOwnProperty, from a shared object called Object.prototype. That shared object is the object's prototype. The result of Object.groupBy has no prototype, so it borrows nothing. This keeps it clean: a group named toString can't clash with a built-in method. But it also means result.hasOwnProperty(key) doesn't work. Use Object.hasOwn(result, key) instead.

You don't have to choose from memory. Ask yourself these questions:

• Does the order of the values matter?
• Do I find values by a key?
• Can the same value appear twice?
• Are the keys objects?
• Should the extra data go away when its object is no longer used?
• Do I need to save the data as JSON?

The helper's answer is a first guess, not a rule. You can also use two structures together. For example, a Set can remove duplicates, and then an array can show the values in order. Pick the structure that makes the next job easy. Switch to another structure when the job changes, such as just before you save.

1recommendStructure({2  ordered: true,3  keyed: false,4  duplicates: true,5  objectKeys: false,6  weakLifetime: false,7  json: false,8});

const tasks = ["plan", "build", "ship"];

Where you'll use this

These five choices show up in everyday app code:

1// 1. Ordered UI state2const tasks = ["write", "review", "ship"];3 4// 2. JSON-friendly settings5const settings = { theme: "dark", density: "compact" };6 7// 3. Counting with a Map8const counts = new Map();9counts.set("bug", (counts.get("bug") ?? 0) + 1);10 11// 4. Fast membership with a Set12const selectedIds = new Set([101, 104, 108]);13 14// 5. Metadata for objects you do not own15const measurements = new WeakMap();

• Line 2: an array keeps tasks in the order the page shows them.
• Line 5: an object holds settings that you save as JSON.
• Line 9: a Map counts things. counts.get("bug") ?? 0 gives 0 the first time, because the key isn't there yet.
• Line 12: a Set holds the IDs a user has selected, so you can check them quickly.
• Line 15: a WeakMap sticks measurements onto objects that other code made.

It is normal to switch between structures. For example, you get JSON as objects and arrays. You build a Map from it, so repeated lookups are quick. Then you turn it back into an array or an object before you save it. The structure you save doesn't have to be the structure you work with.

Common misconceptions

Key takeaways

• An array is a list in order. Use it when position, sorting, or repeated values matter.
• An object is a record with string keys. It is easy to save as JSON.
• A Map keeps every key as it is, even objects. A Set keeps each value once and checks for a value quickly.
• A WeakMap sticks data onto objects. It doesn't keep those objects alive, and you can't loop over it.
• Use Object.groupBy when group keys are strings, and Map.groupBy when they are objects or other values.

Up next: Date & time.