Explicit documentation of mutable function parameters

[danvk]

JavaScript makes it easy to mutate Object parameters:

interface User {
    name: string;
    age: number;
} 
function foo(user: User) {
    user.age = 32;
}

Mutating an argument is somewhat unusual, so mutable parameters are typically documented in comments. But it would be better if this documentation were part of the function declaration, ala const in C++. That way inadvertent mutations could be caught with tsc.

For example:

function bad(user: User) {
  user.age = 32;  // error: user is immutable
}
function ok(mutable user: User) {
  user.age = 32;  // ok
}

To preserve compatibility, function parameters would all be mutable by default unless a new strictMutableChecks flag were set.

Scalar parameters could always be modified, since these changes wouldn't be visible outside the function:

// with strictMutableChecks=true
function foo(x: number): number {
  x += 1;  // ok; not visible outside of foo().
  return x;
}

There would have to be some way for declaration files to indicate whether they were explicitly documenting mutable parameters or using the standard mutable-by-default.

It would also be nice if there were a way to mark constants as immutable. This could help catch whole classes of bugs, e.g. forgetting that _.extend mutates its first parameter in addition to returning a combined Object:

declare module _ {
  'strictMutableChecks';  // Make parameters read-only by default in this module.
  function extend(mutable destination: any, ...sources: any[]): any;
}

const readonly BASE_STYLE = {
  font: 'Times',
  fontWeight: 'bold'
};

const myStyle = _.extend(BASE_STYLE, { font: 'Comic Sans' });  // error: BASE_STYLE is readonly
// should be: _.extend({}, BASE_STYLE, { font: 'Comic Sans' });

This is related to #7770 but is less ambitious, since it would only apply to function parameters.

It may be related to #8575 but there's not much context there.

[poke]

It’s difficult (if not impossible?) to detect mutation though. Think about this:

function doSomething(user: User) {
    user.updateSomething();
}

Here, updateSomething() would modify the user object, requiring the user argument to be “mutable”. In order to track that, updateSomething would require some information that it updates the object. While this might still be possible, it gets really complicated if updateSomething does not mutate user directly but mutates an object that exists as a member on user.

[danvk]

@poke Classes are tricky for sure. There could be a way to mark that method as mutating the class in the definition of User. Perhaps:

class User {
  mutable updateSomething() { ... }
}

Unless TypeScript could infer that the updateSomething method mutates this, it would have to assume that it doesn't, much as function parameters are assumed to have an any type unless TS can deduce something more precise.

In other words: I think this is analogous to optional typing. If you pass an immutable parameter to a function which mutates it, that's unfortunate. But you're no worse off than in plain JS. But if TS knows that it will mutate it, it can warn you. And that's tremendously helpful!

[mhegazy]

We have discussed in the past supporting const on function parameters.

[danvk]

@mhegazy were there any conclusions? Having a way to make parameters const-by-default would make this a more useful check, but it would be a more radical change.

[mhegazy]

I do not think making arguments immutable by default is an option. You can always have a lint rule to make all parameters immutable if you so chose.

[ethanresnick]

Related/context: #9998

[SamuelMarks]

Bumping this issue as making argument explicitly const would be useful. Even if it were fake in the way const is already (see const vs Object.freeze for example).

[RyanCavanaugh]

We're investigating behavior like this as part of a larger effort. See #17502 for some preliminary notes, but closing this one for housekeeping purposes since the overall readonly picture will be more all-encompassing (if it happens). For backcompat purposes, mutable would likely be the default and you'd need to opt in to readonly

[wizarrc]

We have discussed in the past supporting const on function parameters.

@mhegazy What is the status on that discussion? Is there an issue being tracked? I was going to open a new issue till I searched and found this topic. The link mentioned above covers mostly immutable/mutable stuff but not shallow immutable like const. I really want something in the lines of this:

function(const index: number) {
  index++; // Same compile error message as declaring a new const inside the body
}