Warning
After extensive discussion and feedback, the proposal was renamed from Safe Assignment Operator to Try Operator. Click here to view the original proposal.
This proposal addresses the ergonomic challenges of managing multiple, often nested, try/catch blocks necessary for handling operations that may fail at various points.
Only the catch (error) {} block represents actual control flow, while no program state inherently depends on being inside a try {} block. Therefore, forcing the successful flow into nested blocks is not ideal.
Stage: 0
Champion: Actively looking for one
For more information see the TC39 proposal process.
The try {} block often feels redundant because its scoping lacks meaningful conceptual significance. Rather than serving as an essential control flow construct, it mostly acts as a code annotation. Unlike loops or conditionals, a try {} block doesn’t encapsulate any distinct program state that requires isolation.
On the other hand, the catch {} block is genuine control flow, making its scoping relevant. According to Oxford Languages, an exception is defined as:
a person or thing that is excluded from a general statement or does not follow a rule.
Since catch explicitly handles exceptions, encapsulating exception-handling logic in a dedicated block makes sense. Following the same reasoning, there is no justification for also enclosing the non-exceptional flow in a block.
Consider a simple function like this:
function getPostInfo(session, postSlug, cache, db) {
const user = cache.getUser(session.userId)
const post = db.selectPost(postSlug, user)
const comments = db.selectComments(post.id, user)
return { post, comments }
}But production code is rarely this clean. Error handling quickly forces a messier structure:
function getPostInfo(session, postSlug, cache, db) {
let user
// Requires a dedicated error handler
try {
user = cache.getUser(session.userId)
} catch (error) {
otel.capture(error, Operations.GET_SELF)
session.logout()
throw new Error("Invalid session")
}
// No recovery if selectPost fails
try {
const post = db.selectPost(postSlug, user)
let comments = []
// The post must still be returned even if fetching comments fails
try {
comments = db.selectComments(post.id, user)
} catch (error) {
otel.capture(error, Operations.JOIN_POST_COMMENTS)
}
} catch (error) {
otel.capture(error, Operations.GET_POST)
throw new Error("Could not get post")
}
return { post, comments }
}The try blocks didn't provide much value beyond introducing unnecessary nesting.
Instead, using the proposed try operator simplifies the function:
function getPostInfo(session, postId, cache, db) {
const [userOk, userErr, user] = try cache.getUser(session.userId)
// Requires a dedicated error handler
if (!userOk) {
session.logout()
otel.capture(userErr, Operations.GET_SELF)
throw new Error("Invalid session")
}
const [postOk, postErr, post] = try db.selectPost(postId, user)
// No recovery if selectPost fails
if (!postOk) {
otel.capture(postErr, Operations.GET_POST)
throw new Error("Could not get post")
}
const [commentsOk, commentsErr, comments = []] = try db.selectComments(post.id, user)
// The post must still be returned even if fetching comments fails
if (!commentsOk) {
otel.capture(commentsErr, Operations.JOIN_POST_COMMENTS)
}
return { post, comments }
}This approach improves readability by cleanly separating the happy path from error handling.
Control flow remains linear, making it easier to follow, while only the "exceptions" in execution require explicit scoping.
The result is a more structured, maintainable function where failures are handled concisely without unnecessary indentation.
JavaScript has evolved over decades, with countless libraries and codebases built on top of one another. Any new feature that does not consider compatibility with existing code risks negatively impacting its adoption, as refactoring functional, legacy code simply to accommodate a new feature is often an unjustifiable cost.
With that in mind, improvements in error handling can be approached in two ways:
-
At the caller's level:
try { const value = work() } catch (error) { console.error(error) }
-
At the callee's level:
function work() { try { // Performs some operation return { ok: true, value } } catch (error) { return { ok: false, error } } }
Both approaches achieve the same goal, but the second one requires refactoring all implementations into a new format. This is how languages like Go and Rust handle errors, returning a tuple of an error and a value or a Result object, respectively. While the callee-based approach can arguably be better, it succeeded in those languages because it was adopted from the very beginning, rather than introduced as a later addition.
This proposal accounts for this by moving the transformation of errors into values to the caller level, preserving the familiar semantics and placement of try/catch. This approach ensures backward compatibility with existing code.
Breaking compatibility is unacceptable for platforms like Node.js or libraries. Consequently, a callee-based approach would likely never be adopted for functions like fetch or fs.readFile, as it would disrupt existing codebases.
Ironically, these are precisely the kinds of functions where improved error handling is most needed.
The throw statement in JavaScript can throw any type of value. This proposal does not impose nor propose any kind of safety around error handling.
- No generic error type for the proposed Result class will be added.
- No catch branching based on error type will be added. See GitHub Issue #43 for more information.
- No way to annotate a callable to specify the error type it throws will be added.
For more information, also see microsoft/typescript#13219.
While this proposal facilitates error handling, it does not automatically handle errors for you. You will still need to write the necessary code to manage errors the proposal simply aims to make this process easier and more consistent.
The try operator consists of the try keyword followed by an expression. It results in an instance of the Result.
All of its usages are just a combination of the above said rules.
const a = try something()
const [[ok, err, val]] = [try something()]
const [ok, err, val] = try something()
array.map(fn => try fn()) // Result[]
yield try something() // yields Result
try yield something() // Result<T> where T is iterator().next(T)
try await something() // Result<Awaited<T>>
try (a instanceof b) // catches TypeError: Right-hand side of 'instanceof' is not an object
(try a) instanceof Result
const a = try (try (try (try (try 1)))) // Result<Result<Result<Result<Result<number>>>const result = try expressionThis is "equivalent" to:
let _result
try {
_result = Result.ok(expression)
} catch (error) {
_result = Result.error(error)
}
const result = _resultSimilar to void, typeof, yield, and new:
array.map((fn) => try fn()).filter((result) => result.ok) // works :)const result = try data?.someProperty.anotherFunction?.(await someData()).andAnotherOne()This is "equivalent" to:
let _result
try {
_result = Result.ok(
data?.someProperty.anotherFunction?.(await someData()).andAnotherOne()
)
} catch (error) {
_result = Result.error(error)
}
const result = _resultconst result = try await fetch("https://api.example.com/data")This is "equivalent" to:
let _result
try {
_result = Result.ok(await fetch("https://api.example.com/data"))
} catch (error) {
_result = Result.error(error)
}
const result = _resultconst result = try throw new Error("Something went wrong") // Syntax error!
const result = try using resource = new Resource() // Syntax error!This is because their "equivalent" would also result in a syntax error:
let _result
try {
_result = Result.ok(throw new Error("Something went wrong")) // Syntax error!
} catch (error) {
_result = Result.error(error)
}
const result = _resultA detailed discussion about this topic is available at GitHub Issue #54 for those interested.
The try operator ensures that no error escapes its scope:
const [ok, error, result] = try some.thing()Regardless of the type of error that might occur, try will catch it. For example:
- If
someisundefined. - If
thingis not a function. - If accessing the
thingproperty onsomethrows an error. - Any other exception that can arise on that line of code.
All potential errors are safely caught and encapsulated within the try operator expression.
When using try with an object literal, the literal must be enclosed in parenthesis:
const result = try ({ data: await work() })This behavior mirrors how JavaScript differentiates blocks and object literals:
{ a: 1 } // empty block with a label
({ a: 1 }) // object with a key `a` and a number `1`A detailed discussion about this topic is available at GitHub Issue #55 for those interested.
In scenarios where the successful result of an operation is not needed, it can be safely ignored:
function work() {
try fs.unlinkSync("temp.txt")
}This behavior aligns with common patterns, such as using await on asynchronous operations where the result is not utilized:
await fs.promises.unlink("temp.txt")While it is valid to ignore the result, tools like TypeScript ESLint may introduce similar rules, such as no-floating-promises, to encourage developers to explicitly indicate that the result is being ignored. A common workaround to provide a visual cue is to use void alongside try:
function work() {
// This approach works without modification and provides a clear hint
void try fs.unlinkSync("temp.txt")
}Please see
polyfill.d.tsandpolyfill.jsfor a basic implementation of theResultclass.
The Result class represents the form of the value returned by the try operator.
A Result instance contains three properties:
ok: A boolean indicating whether the expression was executed successfully.error: The error thrown during execution, orundefinedif no error occurred.value: The data returned from the execution, orundefinedif an error occurred.
Example usage:
const result = try something()
if (result.ok) {
console.log(result.value)
} else {
console.error(result.error)
}A Result instance is iterable, enabling destructuring and different variable names:
const [success, validationError, user] = try User.parse(myJson)You can also create a Result instance manually using its constructor or static methods:
// Creating a successful result
const result = Result.ok(value)
// Creating an error result
const result = Result.error(error)In Go, the convention is to place the data variable first, and you might wonder why we don't follow the same approach in JavaScript. In Go, this is the standard way to call a function. However, in JavaScript, we already have the option to use const data = fn() and choose to ignore the error, which is precisely the issue this proposal seeks to address.
If someone is using a try statement, it is because they want to ensure they handle errors and avoid neglecting them. Placing the data first would undermine this principle by prioritizing the result over error handling.
// This line doesn't acknowledge the possibility of errors being thrown
const data = fn()
// It's easy to forget to add a second error parameter
const [data] = try fn()
// This approach gives all clues to the reader about the 2 possible states
const [ok, error, data] = try fn()If you want to suppress the error (which is different from ignoring the possibility of a function throwing an error), you can do the following:
// This suppresses a possible error (Ignores and doesn't re-throw)
const [ok, , data] = try fn()This approach is explicit and readable, as it acknowledges the possibility of an error while indicating that you do not care about it.
The above method, often referred to as "try-catch calaboca" (a Brazilian term), can also be written as:
let ok = true
let data
try {
data = fn()
} catch {
ok = false
}A detailed discussion about this topic is available at GitHub Issue #13 for those interested.
The idea of throw x doing anything other than throwing x is inherently flawed. Wrapping the error in an object disregards this principle and introduces unnecessary ambiguity.
Consider the following pseudocode, which might seem harmless but is actually risky:
function doWork() {
if (check) {
throw createException(Errors.SOMETHING_WENT_WRONG)
}
return work()
}
const [error, data] = try doWork()
if (!error) {
user.send(data)
}There is no guarantee that createException always returns an exception. Someone could even mistakenly write throw null or throw undefined, both of which are valid but undesired JavaScript code.
Even though such cases are uncommon, they can occur. The ok value is crucial to mitigate these runtime risks effectively.
For a more in-depth explanation of this decision, refer to GitHub Issue #30.
A proposal doesn’t need to introduce a feature that is entirely impossible to achieve otherwise. In fact, most recent proposals primarily reduce the complexity of tasks that are already achievable by providing built-in conveniences.
Optional chaining and nullish coalescing are examples of features that could have remained external libraries (e.g., Lodash's _.get() for optional chaining and _.defaultTo() for nullish coalescing). However, when implemented natively, their usage scales exponentially and becomes a natural part of developers’ workflows. This arguably improves code quality and productivity.
By providing such basic conveniences natively, we:
- Increase consistency across codebases (many NPM packages already implement variations of this proposal, each with its own API and lack of standardization).
- Reduce code complexity, making it more readable and less error-prone.
This proposal is in its early stages, and we welcome your input to help refine it. Please feel free to open an issue or submit a pull request with your suggestions.
Any contribution is welcome!
- This tweet from @LeaVerou
- The frequent oversight of error handling in JavaScript code.
- Effect TS Error Management
- The
tuple-itnpm package, which introduces a similar concept but modifies thePromiseandFunctionprototypes—an approach that is less ideal.
This proposal is licensed under the MIT License.