Introduce new Promise API methods (#3186)

The new API methods make it possible to get a Promise object's result and it's state. JerryScript-DCO-1.0-Signed-off-by: Peter Gal pgal.u-szeged@partner.samsung.com
2019-10-28 14:07:37 +01:00
parent 351b88184c
commit eebbed143d
6 changed files with 440 additions and 3 deletions
@@ -595,6 +595,22 @@ typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p);

 - [jerry_set_vm_exec_stop_callback](#jerry_set_vm_exec_stop_callback)

+## jerry_promise_state_t
+
+Enum which describes the state of a Promise.
+
+Possible values:
+
+ - JERRY_PROMISE_STATE_NONE - Invalid/Unknown state (possibly called on a non-promise object).
+ - JERRY_PROMISE_STATE_PENDING - Promise is in "Pending" state.
+ - JERRY_PROMISE_STATE_FULFILLED - Promise is in "Fulfilled" state.
+ - JERRY_PROMISE_STATE_REJECTED - Promise is in "Rejected" state.
+
+*New in version [NEXT VERSION]*.
+
+**See also**
+
+- [jerry_get_promise_result](#jerry_get_promise_result)

 ## jerry_typedarray_type_t

@@ -3231,6 +3247,144 @@ jerry_value_to_string (const jerry_value_t value);

 These APIs all depend on the ES2015-subset profile (or on some build options).

+## jerry_get_promise_result
+
+**Summary**
+
+The function returns the result of a Promise object.
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+- This API depends on a build option (`JERRY_ES2015_BUILTIN_PROMISE`) and can be checked
+  in runtime with the `JERRY_FEATURE_PROMISE` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The ES2015-subset profile enables this by default.
+
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_get_promise_result (const jerry_value_t promise);
+```
+
+- `promise` - the input Promise object.
+- return
+  - The result of the Promise.
+  - If the Promise is not resolved yet the result is the 'undefined' value.
+  - A TypeError is returned if the input argument was not a Promise object or
+    the Promise support was not built into the library.
+
+*New in version [NEXT VERSION]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+
+static void
+example (void)
+{
+  // acquire/create a promise object.
+  jerry_value_t promise = jerry_create_promise ();
+  {
+    // prepare the argumnent for the resolve or reject.
+    jerry_value_t argument = jerry_create_number (33);
+
+    jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise,
+                                                           argument,
+                                                           true);
+    // 'is_ok' should be checked if it is an error or not.
+    // skipped in this example
+    jerry_release_value (is_ok);
+    jerry_release_value (argument);
+  }
+
+  jerry_value_t promise_result = jerry_get_promise_result (promise);
+  // 'promise_result' is now the number 33.
+
+  jerry_release_value (promise_result);
+  jerry_release_value (promise);
+}
+```
+
+**See also**
+
+- [jerry_create_promise](#jerry_create_promise)
+- [jerry_promise_state_t](#jerry_promise_state_t)
+
+## jerry_get_promise_state
+
+**Summary**
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+- This API depends on a build option (`JERRY_ES2015_BUILTIN_PROMISE`) and can be checked
+  in runtime with the `JERRY_FEATURE_PROMISE` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The ES2015-subset profile enables this by default.
+
+
+**Prototype**
+
+```c
+jerry_promise_state_t
+jerry_get_promise_state (const jerry_value_t promise);
+```
+
+- `promise` - the input promise object.
+- return
+  - [jerry_promise_state_t](#jerry_promise_state_t)
+  - `JERRY_PROMISE_STATE_NONE` is returned if the input argument was not a promise object or
+    the Promise support was not built into the library.
+
+*New in version [NEXT VERSION]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+
+static void
+example (void)
+{
+  // acquire/create a promise object.
+  jerry_value_t promise = jerry_create_promise ();
+
+  jerry_promise_state_t start_state = jerry_get_promise_state (promise);
+  // a Promise have a default state of JERRY_PROMISE_STATE_PENDING
+
+  {
+    // prepare the argumnent for the resolve or reject.
+    jerry_value_t argument = jerry_create_number (33);
+
+    jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise,
+                                                           argument,
+                                                           true);
+    // 'is_ok' should be checked if it is an error or not.
+    // skipped in this example
+    jerry_release_value (is_ok);
+    jerry_release_value (argument);
+  }
+
+  jerry_promise_state_t current_state = jerry_get_promise_state (promise);
+  // at this point the Promise should be in the JERRY_PROMISE_STATE_FULFILLED state.
+
+  jerry_release_value (promise);
+}
+```
+
+**See also**
+
+- [jerry_create_promise](#jerry_create_promise)
+- [jerry_promise_state_t](#jerry_promise_state_t)
+
 ## jerry_resolve_or_reject_promise

 **Summary**