Let me try presenting a hypothetical API for a result type, so we have something tangible to discuss. I'll just start by showing it's implementation, since it's pretty simple:
const privateConstructorSentinel = Symbol()
class Result {
#isResult = true
constructor(privateConstructorSentinel_, { isOk, value, error }) {
if (privateConstructorSentinel_ !== privateConstructorSentinel) {
throw new Error('This constructor is private')
}
Object.assign(this, { isOk, value, error })
Object.freeze(this)
}
static ok(value = undefined) {
return new Result(privateConstructorSentinel, { isOk: true, value, error: null })
}
static error(error) {
return new Result(privateConstructorSentinel, { isOk: false, value: null, error })
}
static unwrap(result) {
if (!(#isResult in result)) {
throw new TypeError('You must supply an instance of Result as an argument.')
}
if (result.isOk) {
return result.value
} else {
throw new Error('Unwrapped a result object that was in an error state.', { cause: result.error })
}
}
static assertOk(result) {
Result.unwrap(result)
}
static throwReturnedErrors(fn) {
return function(...args) {
const result = fn.call(this, ...args)
if (!(#isResult in result)) {
throw new TypeError('A function wrapped by throwReturnedErrors returned a value that was not an instance of Result.')
}
if (result.isOk) {
return result.value
} else {
throw result.error
}
}
}
}
So, all result-based logic is placed in a class called Result. You can't instantiate it directly, but you can use the ok() and error() static factory functions to create result instances.
> Result.ok('Hi there!')
Result { value: 'Hi there!', error: null, isOk: true }
> Result.ok()
Result { value: undefined, error: null, isOk: true }
> Result.error('Whoops!')
Result { value: null, error: 'Whoops!, isOk: false }
Additionally, there's a handful of static helper functions that are provided for convenience.
Result.unwrap() is used when you know the result does not contain an error. When you unwrap a result, it's value property will be returned. If there was a bug in your program, and the result actually contained an error, then a different error will be thrown stating that something went wrong, and will use the result's error value as the error's cause.
> Result.unwrap(Result.ok('Hi there!'))
'Hi there!'
> Result.unwrap(Result.ok())
undefined
> class MyError extends Error {}
> Result.unwrap(Result.error(new MyError('Whoops!')))
Error: Unwrapped a result object that was in an error state.
...
[cause]: MyError: Whoops!
Result.assertOk() is just a nice helper function I like to have. Sometimes, I write side-effect functions that don't need to return any particular value (so they return a Result with undefined), but I still want to assert that the returned result doesn't contain an error. unwrap() just feels like it doesn't describe what I'm doing very well, so I like to have another function, assertOk(), that describes this objective.
> Result.unwrap(Result.ok('Hi there!'))
undefined // It always returned undefined
> Result.unwrap(Result.ok())
undefined
> class MyError extends Error {}
> Result.unwrap(Result.error(new MyError('Whoops!')))
Error: Unwrapped a result object that was in an error state.
...
[cause]: MyError: Whoops!
Finally, Result.throwReturnedErrors() is used to transition between result-based logic and traditional error-handling logic. Say, for example, you want to take your existing API and convert it so it uses result types internally, but you still want to keep your public-facing API the same (or, you may wish to design new APIs to do this as well). You might design all of your internal functions to return result objects, then, at the point where you would export a function for the end-user to use, you'd first wrap it using Result.throwReturnedErrors() to cause all all errors from results to automatically be thrown, and all "ok" values to automatically be returned.
As a concrete example:
class DivisionByZero extends Error {}
function divide_(x, y) {
if (y === 0) return Result.error(new DivisionByZero('You divided by zero!'))
return x / y
}
// Other internal functions might call divide_() directly, and want to receive an instance
// of Result. This is why we wait until we export it to wrap this function, instead
// of doing it on the spot.
export const divide = Result.throwReturnedErrors(divide_)
// elsewhere
import { divide } from './wherever'
divide(3, 6) // 2
divide(3, 0) // Uncaught DivisionByZero [Error]: You divided by zero!
This is why Result.unwrap() throws an instance of Error() with the result's error value as a cause, instead of throwing the result's error value directly - you don't want someone further up to accidentally catch that error when it was never intended to be thrown at that specific point in time.
Anyways, there's a potential concrete API that could be added to JavaScript. Hopefully this gives us something tangible to discuss in this thread besides "yeah, it would be nice to have result types in the language".