Use Named Params, not Positional Params, in TypeScript

Functions with long positional signatures age poorly. doThing(a, b, c, d, e) invites mis-ordered args, booleans whose meanings drift, and painful refactors. Named Params fix that with better call-site clarity and safer evolution.

TL;DR? See the summary 👇 of when you should use named params.

What's a Positional Param?

Let's say we are calling a function to insert a user into the database.

createUser("Joan of Arc", "joan@arc.atlassian", false, 613, true);

Great, we've got a new user! However, what do true and false mean? And what is that 613? Looking at this call site, it's hard to tell.

This function uses Positional Params. Ordering is significant, and we cannot reorder the params when calling the function.

What's a Named Param?

Here's that same function, but this time using Named Params:

createUser({
  name: "Joan of Arc",
  email: "joan@arc.atlassian",
  isAdmin: true,
  age: 613,
  sendMarketingEmails: false,
});

Named Params do not have significant ordering, and instead are, you guessed in, named!

Why are Named Params Better?

1. Readable calls: arguments self-document.

In the createUser example, it would be really easy to accidentally swap name and email, or even isAdmin and sendMarketingEmails. They are of the same type, and the only thing that distinguishes them is their position.

createUser("joan@arc.atlassian", "Joan of Arc", true, 613, false); // oops

By using Named Params, we can very clearly tell which argument is which at the call site, which means there is much less chance we make a mistake.

createUser({
  name: "Joan of Arc", // Very clear
  email: "joan@arc.atlassian",
  isAdmin: false,
  sendMarketingEmails: true,
  age: 613
});

2. Refactor-safe: add/rename options without breaking call sites.

Let's say we want to add a new required param to this function phoneNumber.. If we used positional params, we might be able to add it at the end. However, sendMarketingEmails is already optional, so I guess we'll have to add undefined everywhere we don't pass sendMarketingEmails:

createUser(/*...*/, undefined,  "1207603802"); // 🤮

Instead, if we're using named params, this is easy!

createUser({
  name: "Joan of Arc",
  email: "joan@arc.atlassian",
  isAdmin: true,
  age: 613,
  phoneNumber: "1207603802"
});

And, if we decided to remove sendMarketingEmails later, none of the existing code needs to change! Win-win.

Real world example: next/router

In the Next.js Pages Router next/router, there is a method to imperitavely begin a page navigation.

router.push("/blog/do-more-with-run");

However, at some point a second optional argument was added, as. This was only used before Next.js 9.5.3 for dynamic routes

router.push(`/blog/[slug]`, `/blog/do-more-with-run`); // ok...

Then, they wanted to add more "options" to this function! But, because there was already something in the second position, it had to be:

router.push(`/blog/do-more-with-run`, undefined, { scroll: false }); // Again, 🤮

In order to fix this, a fully new API, next/navigation, was created that removed that middle param! However, next/router will live on for quite a while and that pesky unused and unneeded undefined will live on in many codebases.

3. Nicer UX: IDE autocomplete lists available options.

If you don't know which argument comes next, no problem! In many IDEs, you can just type " or ⌘-space to get a list of named params. Yes, you can always hover or go-to-definition when using positional params, but then you need to ensure your ordering is correct!

createUser({
  " /* completion shows: name, email, age, isAdmin, sendMarketingEmails ... */
})

...and more!

• Extract the arguments as an object type, and use satisfies to ensure your arguments match
• Use a union type to allow different combinations of arguments depending on the situation
• Can easily spread param into a function without worrying about ordering. Works just like React props.

Summary: When to Prefer Named Params

1. Any time you have more than one param. Really!
2. If there is clearly a "primary" param and then some options (optional), use the fn(primary, options) pattern.