Brainstorming the user-facing experience

[Arlen22]

This issue is primarily for condensing technical ideas into practical ones. If you want to discuss something you see here, feel free to open a new issue.

The try operator

• like any operator,

  • it takes a value and gives a value
  • it can be used pretty much anywhere
  • its result can be ignored
  • it cannot contain a statement

• like the yield operator,

  • it takes the highest precedence without a comma
  • it can contain itself, yield, or anything else

• like the try block,

  • it catches anything that throws inside it, including the await and yield keywords.
  • it transparently supports generator and async functions.
  • it clearly indicates whether or not the code it protects ran to completion.

• To maintain equivalence,

  • try {}: It must catch any exception thrown by a specific section of code.
  • catch (e) {}: It must allow different code to execute if an exception was caught and provide a reference to the exception thrown.
  • finally {}: It must allow code to execute regardless of whether or not an exception was caught.
  • It must not allow any value from that section of code to change or spoof these constraints.

• this gives us two more invariants

  • it must return a result that clearly indicates whether this is the normal completion (perhaps a boolean). Checking undefined is not enough since both normal and abrupt completions may return undefined.
  • it must not flatten its result. If the expression it protects returns or throws a Result, it must still wrap it in a new Result regardless. Otherwise, the user could not distinguish between returning Result(false) and actually throwing, or between throwing Result(true) and actually returning.

/**
 * (   try       something())
 * (<operator>  <expression>)
 */
operator try(expression) {
  try { 
    return TryResult.ok(exec(expression));
  } catch (inner) {
    return TryResult.error(inner);
  }
}

does this

const a = try something()
const [[ok, err, val]] = [try something()]
const [ok, err, val] = try something()
files.map(file => try JSON.parse(file))
yield try something()
try yield something()
try await something()
try a instanceof b
(try a) instanceof TryResult
const a = try try try try try try 1

[arthurfiorette]

About the TryResult or any naming alternative:

https://chatgpt.com/share/67a29276-f474-8001-8cf8-ecb53b6a7b2d

[arthurfiorette]

Rust lang uses Result<()>...

[Arlen22]

Pseudo-code representing the try expression.

const [ok, error, value] = try something();
if(!ok) console.log(error);

operator try(expression) {
  try { 
    return [true, undefined, eval(expression)]
  } catch (inner) {
    return [false, inner, undefined]
  }
}

OR the other plausible variation: "always wrapped"

const [error, value] = try something();
if(error) console.log(error.inner);

operator try(expression) {
  try { 
    return [undefined, eval(expression)]
  } catch (inner) {
    return [{ inner }, undefined]
  }
}

[Arlen22]

With the TryResult class

// tuple destructuring
const [ok, error, value] = try something();
if(!ok) console.log(error);

// object destructuring
const {ok, error, value} = try something();
if(!ok) console.log(error);

// variable assignment
const result = try something();
if(!result.ok) console.log(result.error);

operator try(expression) {
  try { 
    return TryResult.ok(execute(expression));
  } catch (inner) {
    return TryResult.error(inner);
  }
}

class TryResult {
  constructor(ok, error, value) {
    // this is for the object destructuring
    this.ok = ok
    this.error = error
    this.value = value
  }
  *[Symbol.iterator]() {
    // this is for the tuple destructuring
    yield this.ok
    yield this.error
    yield this.value
  }
  static ok(value) {
    return new TryResult(true, undefined, value)
  }
  static error(error) {
    return new TryResult(false, error, undefined)
  }
}

[Arlen22]

The way I see it from my limited understanding of the proposal process and my extensive experience using Javascript and Typescript, I think we only have two options that stand any chance of being accepted. Both of these can be strongly type-checked and give solid runtime guarantees with minimal code.

1. A three variable destructuring.

   const [ok, error, result] = try something();
   if(!ok) console.error(error);

2. A two variable destructuring with the error always wrapped (if it throws).

   const [error, result] = try something();
   // error would be undefined if it succeeds
   if(error) console.error(error.inner);

---

The next two options are the kinds of inconsistencies Javascript has been moving away from ever since ES5. These are NOT part of the proposal, they're included here because people keep asking about these two scenarios.

3. A two variable destructuring with the error conditionally wrapped (requiring instanceof Error).

   This one is annoying because it immediately requires you to conditionally unwrap it using a ternary and instanceof. Not only is this annoying, but instanceof can be unreliable in some cases. It would be much cleaner to just always wrap it.

   const [error, result] = try something();
   if (error) { console.log((error instanceof TryError) ? error.inner : error); }

4. A two variable destructuring with the error never wrapped is a very bad idea because there can be NO guarantees. The code may or may not have completed, and neither variable can actually tell you that for sure. This actually breaks fundamental laws of software development. Adding an ok variable to this is the perfect solution.

   // what if this somehow throws undefined
   // error is undefined if it doesn't throw, 
   // so now it would be undefined either way.
   const [error, result] = try somethingReallyImportant();
   if(error) { console.log(error); }
   // program now in an unknown state

---

A few other suggestions that are worth noting as already covered.

5. What about [{ok, error}, value]
   • Well, that's basically just option 2, but more expensive because you always create the wrap instead of only when it fails.
6. What about making TryResult an instance of Error to capture the stack trace at the try operator?
   • the try block doesn't create an error, and stack traces aren't actually in the ECMA spec. #67 (comment)
   • If you need one for any reason, you can just create it.
   • Creating one at the throw keyword is well outside the scope of this proposal.

[Arlen22]

This is the most technical description I can think of, apparently, short of the actual spec itself.

in pseudo-code

/**
 * (   try       something())
 * (<operator>  <expression>)
 */
operator try(expression) {
  try { 
    return TryResult.ok(eval(expression));
  } catch (inner) {
    return TryResult.error(inner);
  }
}

with the TryResult class

class TryResult {
  constructor(ok, error, value) {
    // this is for the object destructuring
    this.ok = ok
    this.error = error
    this.value = value
  }
  *[Symbol.iterator]() {
    // this is for the tuple destructuring
    yield this.ok
    yield this.error
    yield this.value
  }
  static ok(value) {
    return new TryResult(true, undefined, value)
  }
  static error(error) {
    return new TryResult(false, error, undefined)
  }
}

does this

const [ok, , files = []] = try await readdir("./");
if(!ok) return; // probably tell the user
const files2 = await Promise.all(files.map(async file => try await readFile(file, "utf8")))
const files3 = files2.filter(e => e.ok).map(e => try JSON.parse(e.value)).filter(e => e.ok).map(e => e.value);

const res = try await fetch("...");
if(!res.ok) return; // network error
const [,,json] = try JSON.parse(res.value.text()); //fetch.json throws
if(json === undefined) return; // it didn't return json

const a = try something()
const [[ok, err, val]] = [try something()]
const [ok, err, val] = try something()
yield try something()
try yield something()
try await something()
try a instanceof b // catches if b is not an object
(try a) instanceof TryResult
const a = try try try try try try 1
const a = try check ? something(1) : something(2);

and even works with Typescript

type TryResultInner<O,E,V> = [O, E, V] & { ok:O, error: E, value: V };
type TryResult<T> = TryResultInner<true, undefined, T> | TryResultInner<false, any, undefined>
const [ok, error, value]: TryResult<"hello"> = try something();
if(!ok) console.log(error, value);
//                  ^? const error: any, value: undefined
else console.log(error, value);
//                  ^? const error: undefined, value: "hello"

(although, to be fair, that's just a bonus).

[Arlen22]

The Helper Function alternative

(combining these four into one function is not possible)

/**
 * @example
 * // const result = try something();
 * const result = try_(() => {
 *   something();
 * });
 */
function try_(callback, thisarg) {
  try {
    return Result.ok(callback.apply(thisarg));
  } catch(e) {
    return Result.error(e);
  }
}

/**
 * @example
 * // const result = try await something();
 * const result = await try_await_(async () => {
 *  await something();
 * });
 */
async function try_await_(callback, thisarg) {
  try {
    return Result.ok(await callback.apply(thisarg));
  } catch(e) {
    return Result.error(e);
  }
}

/**
 * @example
 * // const result = try yield something();
 * const result = yield* try_yield_(function*() {
 *   yield something();
 * }, this);
 */
function* try_yield_(callback, thisarg) {
  try {
    return Result.ok(yield* callback.apply(thisarg));
  } catch(e) {
    return Result.error(e);
  }
}

/** 
 * @example
 * // const result = try yield await something();
 * const result = yield* try_await_yield_(async function*() {
 *   yield await something();
 * }, this);
 */
async function* try_await_yield_(callback, thisarg) {
  try {
    return Result.ok(yield* callback.apply(thisarg));
  } catch(e) {
    return Result.error(e);
  }
}

class Result {
  constructor(ok, error, value) {
    this.ok = ok
    this.error = error
    this.value = value
  }
  *[Symbol.iterator]() {
    yield this.ok
    yield this.error
    yield this.value
  }
  static ok(value) {
    return new Result(true, undefined, value)
  }
  static error(error) {
    return new Result(false, error, undefined)
  }
}

[Arlen22]

This example changes its behavior based on whether or not the try call was awaited. It makes the usage completely transparent (if you forget await, you get the same problems at the same place you would otherwise), but the behavior is somewhat unexpected. So while this version allows a promise to be transparently passed through, it's rare for this to be what you actually want.

In other words, this version is technically better, but also no.

I was trying to match the declarative simplicity of the try operator.

const [ok, err, res] = await Result.try(() => Promise.resolve(1));
const [ok, err, res] = Result.try(() => Promise.resolve(1));

class Result {
  constructor(ok, error, value) {
    this.ok = ok
    this.error = error
    this.value = value
    this.then = (resolve /*, reject*/) => {
      // if the value isn't then-able we have to delete then to avoid infinite recursion
      if(!this.ok) {
        // if it errored syncly, just return that result
        delete this.then;
        resolve(this);
      } else if(typeof this.value?.then === "function") {
        // call then on our value then chain the result to the resolve callback
        this.value.then(Result.ok, Result.error).then(resolve);
      } else {
        // it's not a promise, so just return the current result
        delete this.then;
        resolve(this);
      }
    }
  }

  *[Symbol.iterator]() {
    yield this.ok
    yield this.error
    yield this.value
  }

  static ok(value) {
    return new Result(true, undefined, value)
  }

  static error(error) {
    return new Result(false, error, undefined)
  }

  static try(callback, thisArg) {
    if(typeof callback !== "function") return Result.ok(callback);
    try {
      const result = callback.apply(thisArg)
      return Result.ok(result)
    } catch(error) {
      return Result.error(error)
    }
  }
};

[Arlen22]

The try operator must not flatten either value or error result.

If the inner expression returned a Result (instead of throwing), that would represent code that completed successfully.

If the Result returned was an error Result, flattening would make it appear that the expression had thrown instead of running to completion.

Just like the discussion about the ok boolean, this would make it impossible to tell whether the expression ran to completion, breaking the most fundamental guarantee of the try operator.

If flattening is desired, the caller can flatten it with the following code. Note that ok does not need to be checked because either error or value will always be undefined and if value is defined, then this is always a successful result.

type FlatResult<T> = T extends Result<infer R> ? FlatResult<R> : Result<T>;
/** Recursively unwrap the success branch of a result. */
function Result.flatten<T>(t: Result<T>): FlatResult<T> {
  while (t.value instanceof Result) { t = t.value; }
  return t;
}