Optional Chaining

Playground

Optional chaining is issue #16 on our issue tracker. For context, there have been over 23,000 issues on the TypeScript issue tracker since then.

At its core, optional chaining lets us write code where TypeScript can immediately stop running some expressions if we run into a null or undefined.The star of the show in optional chaining is the new ?. operator for optional property accesses.When we write code like

  1. let x = foo?.bar.baz();

this is a way of saying that when foo is defined, foo.bar.baz() will be computed; but when foo is null or undefined, stop what we’re doing and just return undefined.”

More plainly, that code snippet is the same as writing the following.

  1. let x = (foo === null || foo === undefined) ?
  2.     undefined :
  3.     foo.bar.baz();

Note that if bar is null or undefined, our code will still hit an error accessing baz.Likewise, if baz is null or undefined, we’ll hit an error at the call site.?. only checks for whether the value on the left of it is null or undefined - not any of the subsequent properties.

You might find yourself using ?. to replace a lot of code that performs repetitive nullish checks using the && operator.

  1. // Before
  2. if (foo && foo.bar && foo.bar.baz) {
  3.     // ...
  4. }
  6. // After-ish
  7. if (foo?.bar?.baz) {
  8.     // ...
  9. }

Keep in mind that ?. acts differently than those && operations since && will act specially on “falsy” values (e.g. the empty string, 0, NaN, and, well, false), but this is an intentional feature of the construct.It doesn’t short-circuit on valid data like 0 or empty strings.

Optional chaining also includes two other operations.First there’s the optional element access which acts similarly to optional property accesses, but allows us to access non-identifier properties (e.g. arbitrary strings, numbers, and symbols):

  1. /**
  2.  * Get the first element of the array if we have an array.
  3.  * Otherwise return undefined.
  4.  */
  5. function tryGetFirstElement<T>(arr?: T[]) {
  6.     return arr?.[0];
  7.     // equivalent to
  8.     //   return (arr === null || arr === undefined) ?
  9.     //       undefined :
  10.     //       arr[0];
  11. }

There’s also optional call, which allows us to conditionally call expressions if they’re not null or undefined.

  1. async function makeRequest(url: string, log?: (msg: string) => void) {
  2.     log?.(`Request started at ${new Date().toISOString()}`);
  3.     // roughly equivalent to
  4.     //   if (log != null) {
  5.     //       log(`Request started at ${new Date().toISOString()}`);
  6.     //   }
  8.     const result = (await fetch(url)).json();
  10.     log?.(`Request finished at at ${new Date().toISOString()}`);
  12.     return result;
  13. }

The “short-circuiting” behavior that optional chains have is limited property accesses, calls, element accesses - it doesn’t expand any further out from these expressions.In other words,

  1. let result = foo?.bar / someComputation()

doesn’t stop the division or someComputation() call from occurring.It’s equivalent to

  1. let temp = (foo === null || foo === undefined) ?
  2.     undefined :
  3.     foo.bar;
  5. let result = temp / someComputation();

That might result in dividing undefined, which is why in strictNullChecks, the following is an error.

  1. function barPercentage(foo?: { bar: number }) {
  2.     return foo?.bar / 100;
  3.     //     ~~~~~~~~
  4.     // Error: Object is possibly undefined.
  5. }

More more details, you can read up on the proposal and view the original pull request.