From 9ae367c3fd6205d809cb35caffa68ce631e365b4 Mon Sep 17 00:00:00 2001 From: Jeremy Roman Date: Wed, 31 Jul 2024 11:39:45 -0400 Subject: [PATCH 1/3] Allow users of "invoke a callback function" to report the exception This makes it more concise for users to, as is frequently desired for undefined-returning callbacks especially, immediately catch and report the exception rather than needing to handle it themselves. This isn't appropriate for other types of callback functions, where a result may be expected or the exception needs to be rethrown. Callers need to explicitly decide which behavior they want, unless the callback returns a promise type, in which case exceptions are turned into rejected promises implicitly. Fixes #1423. --- index.bs | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index e3549ebf..001f5725 100644 --- a/index.bs +++ b/index.bs @@ -14399,11 +14399,22 @@ described in the previous section).
To invoke a - [=callback function type=] value |callable| with a [=Web IDL arguments list=] |args| + [=callback function type=] value |callable| with a [=Web IDL arguments list=] |args|, + exception behavior |exceptionBehavior| (either "`report`" or "`rethrow`"), and an optional [=callback this value|callback this value=] |thisArg|, perform the following steps. These steps will either return an IDL value or throw an exception. + The |exceptionBehavior| argument must be supplied if, and only if, |callable|'s + [=return type=] is not a [=promise type=]. If |callable|'s return type is neither + {{undefined}} nor {{any}}, it may not be "`report`". + +
+ Until call sites are updated to respect this, specifications which fail to + provide a value here when it would be mandatory should be read to supply + "`rethrow`". +
+ 1. Let |completion| be an uninitialized variable. 1. If |thisArg| was not given, let |thisArg| be undefined. 1. Let |F| be the JavaScript object corresponding to |callable|. @@ -14433,8 +14444,13 @@ described in the previous section). 1. [=Clean up after running a callback=] with |stored settings|. 1. [=Clean up after running script=] with |relevant settings|. 1. If |completion| is an IDL value, return |completion|. - 1. If |completion| is an [=abrupt completion=] and the callback function has a - [=return type=] that is not a [=promise type=], throw |completion|.\[[Value]]. + 1. [=Assert=]: |completion| is an [=abrupt completion=]. + 1. If |exceptionBehavior| is "`rethrow`", throw |completion|.\[[Value]]. + 1. Otherwise, if |exceptionBehavior| is "`report`": + 1. [=Assert=]: |callable|'s [=return type=] is {{undefined}} or {{any}}. + 1. [=Report an exception=] |completion|.\[[Value]] for |realm|'s [=realm/global object=]. + 1. Return the unique {{undefined}} IDL value. + 1. [=Assert=]: |callable|'s [=return type=] is a [=promise type=]. 1. Let |rejectedPromise| be [=!=] Call({{%Promise.reject%}}, {{%Promise%}}, «|completion|.\[[Value]]»). 1. Return the result of [=converted to an IDL value|converting=] From 2387fdce2c234a293fde4a2023d345922b26a69a Mon Sep 17 00:00:00 2001 From: Jeremy Roman Date: Wed, 31 Jul 2024 11:46:46 -0400 Subject: [PATCH 2/3] fix formatting --- index.bs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/index.bs b/index.bs index 001f5725..d0a460a8 100644 --- a/index.bs +++ b/index.bs @@ -14400,19 +14400,19 @@ described in the previous section). To invoke a [=callback function type=] value |callable| with a [=Web IDL arguments list=] |args|, - exception behavior |exceptionBehavior| (either "`report`" or "`rethrow`"), + exception behavior |exceptionBehavior| (either "report" or "rethrow"), and an optional [=callback this value|callback this value=] |thisArg|, perform the following steps. These steps will either return an IDL value or throw an exception. The |exceptionBehavior| argument must be supplied if, and only if, |callable|'s [=return type=] is not a [=promise type=]. If |callable|'s return type is neither - {{undefined}} nor {{any}}, it may not be "`report`". + {{undefined}} nor {{any}}, it may not be "report".
Until call sites are updated to respect this, specifications which fail to - provide a value here when it would be mandatory should be read to supply - "`rethrow`". + provide a value here when it would be mandatory should be understood as + supplying "rethrow".
1. Let |completion| be an uninitialized variable. @@ -14445,8 +14445,8 @@ described in the previous section). 1. [=Clean up after running script=] with |relevant settings|. 1. If |completion| is an IDL value, return |completion|. 1. [=Assert=]: |completion| is an [=abrupt completion=]. - 1. If |exceptionBehavior| is "`rethrow`", throw |completion|.\[[Value]]. - 1. Otherwise, if |exceptionBehavior| is "`report`": + 1. If |exceptionBehavior| is "rethrow", throw |completion|.\[[Value]]. + 1. Otherwise, if |exceptionBehavior| is "report": 1. [=Assert=]: |callable|'s [=return type=] is {{undefined}} or {{any}}. 1. [=Report an exception=] |completion|.\[[Value]] for |realm|'s [=realm/global object=]. 1. Return the unique {{undefined}} IDL value. From 000a7097e6918bed3389c37a1020b7c43a7aafe5 Mon Sep 17 00:00:00 2001 From: Domenic Denicola Date: Fri, 2 Aug 2024 14:35:09 +0900 Subject: [PATCH 3/3] Slightly clearer preamble --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index d0a460a8..a3b7cdac 100644 --- a/index.bs +++ b/index.bs @@ -14407,7 +14407,7 @@ described in the previous section). The |exceptionBehavior| argument must be supplied if, and only if, |callable|'s [=return type=] is not a [=promise type=]. If |callable|'s return type is neither - {{undefined}} nor {{any}}, it may not be "report". + {{undefined}} nor {{any}}, it must be "rethrow".
Until call sites are updated to respect this, specifications which fail to