proposal-try-operator/spec.emu at main · arthurfiorette/proposal-try-operator · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
<!doctype html>
<meta charset="utf8">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/github.min.css">
<script src="https://bterlson.github.io/ecmarkup/ecmarkup.js"></script>
<link rel="stylesheet" href="https://bterlson.github.io/ecmarkup/elements.css">
<pre class="metadata">
title: ECMAScript Try Operator
status: proposal
stage: 0
contributors: Arthur Fiorette, Arlen Beiler
</pre>

<emu-biblio href="node_modules/@tc39/ecma262-biblio/biblio.json"></emu-biblio>

<emu-intro id="sec-intro">
  <h1>Introduction</h1>
  <emu-note>
    <p><strong>Important Notice:</strong> Until this proposal is accepted by ECMA, this spec.emu file might not reflect the latest updates to the proposal. Readers should base their understanding primarily on the current <a href="https://github.com/arthurfiorette/proposal-try-operator/blob/main/README.md">README.md</a> file, which serves as the authoritative source during the proposal stage. This specification is an imagination of what the final specification might look like and while it can be trusted as a reference, the README.md has higher importance at this stage of the project.</p>
  </emu-note>
  <p>This proposal introduces a `try` operator and `Result` class to JavaScript for improved error handling ergonomics. The `try` operator evaluates an expression within an implicit try-catch block and returns a `Result` instance containing either the successful value or the caught error.</p>
</emu-intro>

<emu-clause id="sec-assignment-operators">
  <h1>Assignment Operators</h1>
  <h2>Syntax</h2>
  <emu-grammar type="definition">
    AssignmentExpression[In, Yield, Await] :
      TryExpression[?In, ?Yield, ?Await]
    TryExpression[In, Yield, Await] :
      `try` [no LineTerminator here] [lookahead != `{`] AssignmentExpression[?In, ?Yield, ?Await]
  </emu-grammar>

  <emu-note>
    <p>Placing the `try` operator in assignment expression allows it to protect an entire assignment expression.</p>
  </emu-note>

  <emu-clause id="sec-comma-operator-runtime-semantics-evaluation" type="sdo">
    <h1>Runtime Semantics: Evaluation</h1>
    <emu-grammar>TryExpression : `try` AssignmentExpression</emu-grammar>
    <emu-alg>
      1. Let _A_ be Completion(Evaluation of |Expression|).
      1. If _A_ is an abrupt completion, return ? TryExpressionResult(_A_).
      1. Let _B_ be Completion(GetValue(_A_)).
      1. Return ? TryExpressionResult(_B_).
    </emu-alg>
    <emu-note>
      <p>GetValue must be called even though its value is not used because it may have observable side-effects.</p>
    </emu-note>
    <emu-note>
      <p>This is identical to <emu-xref href="#sec-try-statement-runtime-semantics-evaluation">evaluation of a try statement</emu-xref>.</p>
    </emu-note>
  </emu-clause>

  <emu-clause id="sec-try-expression-result" type="abstract operation">
    <h1>
      TryExpressionResult (
        _result_: a Completion Record,
      ): either a normal completion containing a Result or an abrupt completion
    </h1>
    <dl class="header">
    </dl>
    <emu-alg>
      1. If _result_ is a normal completion, return Result.ok(_result_.[[VALUE]]).
      1. If _result_ is a throw completion, return Result.error(_result_.[[VALUE]]).
      1. Return ? _result_.
    </emu-alg>
  </emu-clause>
  <emu-clause id="sec-try-expression-result-ok" type="abstract operation">
    <h1>
      Result.ok (
        _value_: an ECMAScript language value,
      ): a Result
    </h1>
    <dl class="header">
      <dt>description</dt>
      <dd>It is the abstract equivalent of calling `Result.ok(value)`</dd>
    </dl>
  </emu-clause>
  <emu-clause id="sec-try-expression-result-error" type="abstract operation">
    <h1>
      Result.error (
        _value_: an ECMAScript language value,
      ): a Result
    </h1>
    <dl class="header">
      <dt>description</dt>
      <dd>It is the abstract equivalent of calling `Result.error(value)`</dd>
    </dl>
  </emu-clause>
</emu-clause>

<emu-clause id="sec-result-constructor">
  <h1>The Result Constructor</h1>
<pre><code class="javascript">
class Result {
  constructor(ok, error, value) {
    ok = Boolean(ok)
    this.ok = ok
    if (ok) {
      this.value = value
    } else {
      this.error = error
    }
  }
  *[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)
  }
}
</code></pre>
</emu-clause>