├── .npmrc ├── .gitattributes ├── .github └── workflows │ └── build.yml ├── package.json ├── spec.emu ├── .gitignore ├── LICENSE ├── INSTRUCTIONS.md ├── README.md └── index.html /.npmrc: -------------------------------------------------------------------------------- 1 | package-lock=false 2 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | index.html -diff merge=ours 2 | spec.js -diff merge=ours 3 | spec.css -diff merge=ours 4 | -------------------------------------------------------------------------------- /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | name: Deploy spec 2 | 3 | on: [push] 4 | 5 | jobs: 6 | build: 7 | runs-on: ubuntu-latest 8 | 9 | steps: 10 | - uses: actions/checkout@v2 11 | - uses: actions/setup-node@v1 12 | with: 13 | node-version: '12.x' 14 | - run: npm install 15 | - run: npm run build 16 | - name: commit changes 17 | uses: elstudio/actions-js-build/commit@v3 18 | with: 19 | commitMessage: "fixup: [spec] `npm run build`" 20 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "private": true, 3 | "name": "template-for-proposals", 4 | "description": "A repository template for ECMAScript proposals.", 5 | "scripts": { 6 | "start": "npm run build-loose -- --watch", 7 | "build": "npm run build-loose -- --strict", 8 | "build-loose": "ecmarkup --verbose spec.emu index.html" 9 | }, 10 | "homepage": "https://github.com/tc39/template-for-proposals#readme", 11 | "repository": { 12 | "type": "git", 13 | "url": "git+https://github.com/tc39/template-for-proposals.git" 14 | }, 15 | "license": "MIT", 16 | "devDependencies": { 17 | "ecmarkup": "^7.0.3" 18 | } 19 | } 20 | -------------------------------------------------------------------------------- /spec.emu: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 
 7 | title: Proposal Title Goes Here
 8 | stage: -1
 9 | contributors: Your Name(s) Here
10 |
11 | 12 | 13 |

This is an emu-clause

14 |

This is an algorithm:

15 | 16 | 1. Let _proposal_ be *undefined*. 17 | 1. If IsAccepted(_proposal_), 18 | 1. Let _stage_ be *0*. 19 | 1. Else, 20 | 1. Let _stage_ be *-1*. 21 | 1. Return ? ToString(_proposal_). 22 | 23 | 24 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | 6 | # Runtime data 7 | pids 8 | *.pid 9 | *.seed 10 | 11 | # Directory for instrumented libs generated by jscoverage/JSCover 12 | lib-cov 13 | 14 | # Coverage directory used by tools like istanbul 15 | coverage 16 | 17 | # nyc test coverage 18 | .nyc_output 19 | 20 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 21 | .grunt 22 | 23 | # node-waf configuration 24 | .lock-wscript 25 | 26 | # Compiled binary addons (http://nodejs.org/api/addons.html) 27 | build/Release 28 | 29 | # Dependency directories 30 | node_modules 31 | jspm_packages 32 | 33 | # Optional npm cache directory 34 | .npm 35 | 36 | # Optional REPL history 37 | .node_repl_history 38 | 39 | # Only apps should have lockfiles 40 | yarn.lock 41 | package-lock.json 42 | npm-shrinkwrap.json 43 | pnpm-lock.yaml 44 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2017 ECMA TC39 and contributors 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /INSTRUCTIONS.md: -------------------------------------------------------------------------------- 1 | # template-for-proposals 2 | 3 | A repository template for ECMAScript proposals. 4 | 5 | ## Before creating a proposal 6 | 7 | Please ensure the following: 8 | 1. You have read the [process document](https://tc39.github.io/process-document/) 9 | 1. You have reviewed the [existing proposals](https://github.com/tc39/proposals/) 10 | 1. You are aware that your proposal requires being a member of TC39, or locating a TC39 delegate to "champion" your proposal 11 | 12 | ## Create your proposal repo 13 | 14 | Follow these steps: 15 | 1. Click the green ["use this template"](https://github.com/tc39/template-for-proposals/generate) button in the repo header. (Note: Do not fork this repo in GitHub's web interface, as that will later prevent transfer into the TC39 organization) 16 | 1. Go to your repo settings “Options” page, under “GitHub Pages”, and set the source to the **main branch** under the root (and click Save, if it does not autosave this setting) 17 | 1. check "Enforce HTTPS" 18 | 1. On "Options", under "Features", Ensure "Issues" is checked, and disable "Wiki", and "Projects" (unless you intend to use Projects) 19 | 1. Under "Merge button", check "automatically delete head branches" 20 | 32 | 3. ["How to write a good explainer"][explainer] explains how to make a good first impression. 33 | 34 | > Each TC39 proposal should have a `README.md` file which explains the purpose 35 | > of the proposal and its shape at a high level. 36 | > 37 | > ... 38 | > 39 | > The rest of this page can be used as a template ... 40 | 41 | Your explainer can point readers to the `index.html` generated from `spec.emu` 42 | via markdown like 43 | 44 | ```markdown 45 | You can browse the [ecmarkup output](https://ACCOUNT.github.io/PROJECT/) 46 | or browse the [source](https://github.com/ACCOUNT/PROJECT/blob/HEAD/spec.emu). 47 | ``` 48 | 49 | where *ACCOUNT* and *PROJECT* are the first two path elements in your project's Github URL. 50 | For example, for github.com/**tc39**/**template-for-proposals**, *ACCOUNT* is "tc39" 51 | and *PROJECT* is "template-for-proposals". 52 | 53 | 54 | ## Maintain your proposal repo 55 | 56 | 1. Make your changes to `spec.emu` (ecmarkup uses HTML syntax, but is not HTML, so I strongly suggest not naming it ".html") 57 | 1. Any commit that makes meaningful changes to the spec, should run `npm run build` and commit the resulting output. 58 | 1. Whenever you update `ecmarkup`, run `npm run build` and commit any changes that come from that dependency. 59 | 60 | [explainer]: https://github.com/tc39/how-we-work/blob/HEAD/explainer.md 61 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ECMAScript Catch Guards 2 | 3 | This proposal adds the catch guards to the language, enabling developers to catch 4 | exceptions only when they match a specific class or set of classes. 5 | 6 | This proposal draws heavily from similar features available in 7 | [Java](https://docs.oracle.com/javase/specs/jls/se7/html/jls-14.html#jls-14.20), 8 | [C#](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/try-catch), 9 | [Ruby](http://rubylearning.com/satishtalim/ruby_exceptions.html), and 10 | [Python](https://docs.python.org/3/tutorial/errors.html#handling-exceptions). 11 | 12 | ## Problem statement 13 | Javascript doesn't provide an ergonomic way of treating different types of errors. 14 | 15 | ## Status 16 | 17 | **Champion**: 18 | Willian Martins (Netflix, [@wmsbill](https://twitter.com/wmsbill)), 19 | 20 | 21 | **Stage**: 0 22 | 23 | **Lastest update**: draft created 24 | 25 | ## Motivation 26 | 27 | - **Developer ergonomics**: 28 | 29 | Today, developers have to catch all Errors, add an `if` or `switch` statement and 30 | rethrow even when they want to catch one particular type of error: 31 | 32 | ```javascript 33 | class ConflictError extends Error {} 34 | 35 | try { 36 | something(); 37 | } catch (err) { 38 | if (err instanceOf ConflictError) { 39 | // handle it... 40 | } 41 | throw err; 42 | } 43 | ``` 44 | 45 | - **Parity with other languages**: 46 | 47 | Scoping error handling to specific types is a common construct in several programming 48 | languges, as: 49 | [Java](https://docs.oracle.com/javase/specs/jls/se7/html/jls-14.html#jls-14.20), 50 | [C#](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/try-catch), 51 | [Ruby](http://rubylearning.com/satishtalim/ruby_exceptions.html), and 52 | [Python](https://docs.python.org/3/tutorial/errors.html#handling-exceptions). 53 | 54 | 55 | - **Code/Engine Optimization**: 56 | 57 | Engines can skip the block entirely if the error doesn't match the correct type. 58 | 59 | ## Syntax options 60 | 61 | The current implementation uses the following syntax: 62 | ``` 63 | catch ( CatchParameter[?Yield, ?Await] ) { block } 64 | ``` 65 | 66 | Where `CatchParameter` is: 67 | * `BindingIdentifier[?Yield, ?Await]` 68 | * `BindingPattern` 69 | 70 | 71 | ### Option 1 (New Catch Statement): 72 | 73 | This proposal introduces a new Binding type for the CatchParameter called `BindingGuard`; this new bind type's shape and semantics are subject to stage 1 development. 74 | 75 | ```javascript 76 | 77 | try { 78 | something(); 79 | } catch (BindingGuard) { 80 | // handle it one way... 81 | } catch(BindingGuard) { 82 | // handle the other way... 83 | } catch (err) { 84 | // catch all... 85 | } 86 | ``` 87 | 88 | ### Option 2 (New CatchPatten statement): 89 | 90 | This option can be used in conjunction with option one or leveraged on the Pattern Matching proposal to bind different error patterns (syntax and semantics are subject to stage 1 development), making the catch statement keep its current syntax. 91 | 92 | 93 | ```javascript 94 | 95 | try { 96 | something(); 97 | } CatchPatten (BindingGuard) { 98 | // handle it one way... 99 | } CatchPatten (BindingGuard) { 100 | // handle the other way... 101 | } catch (err) { 102 | // catch all... 103 | } 104 | ``` 105 | 106 | ## Implementations 107 | 108 | * Babel Plugin //TBD 109 | 110 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | Proposal Title Goes Here

Stage -1 Draft / April 20, 2021

Proposal Title Goes Here

2212 | 2213 | 2214 |

1 This is an emu-clause

2215 |

This is an algorithm:

2216 |
  1. Let proposal be undefined.
  2. If IsAccepted(proposal),
    1. Let stage be 0.
  3. Else,
    1. Let stage be -1.
  4. Return ? ToString(proposal).
 2217 | 2218 |

A Copyright & Software License

2219 | 2220 |

Copyright Notice

2221 |

© 2021 Your Name(s) Here

2222 | 2223 |

Software License

2224 |

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

2225 | 2226 |

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

2227 | 2228 |
    2229 |
  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    2. 2230 |
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    3. 2231 |
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.
    4. 2232 |
2233 | 2234 |

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

2235 | 2236 | 2237 |
--------------------------------------------------------------------------------