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

Author: galpeter

docs/02.API-REFERENCE.md

@@ -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**

jerry-core/api/jerry.c

@@ -71,6 +71,14 @@ JERRY_STATIC_ASSERT ((int) RE_FLAG_GLOBAL == (int) JERRY_REGEXP_FLAG_GLOBAL
                      re_flags_t_must_be_equal_to_jerry_regexp_flags_t);
 #endif /* ENABLED (JERRY_BUILTIN_REGEXP) */
 
+#if ENABLED (JERRY_ES2015_BUILTIN_PROMISE)
+/* The internal ECMA_PROMISE_STATE_* values are "one byte away" from the API values */
+JERRY_STATIC_ASSERT (((ECMA_PROMISE_STATE_PENDING + 1) == JERRY_PROMISE_STATE_PENDING)
+                     && ((ECMA_PROMISE_STATE_FULFILLED + 1) == JERRY_PROMISE_STATE_FULFILLED)
+                     && ((ECMA_PROMISE_STATE_REJECTED + 1) == JERRY_PROMISE_STATE_REJECTED),
+                     promise_internal_state_matches_external);
+#endif /* ENABLED (JERRY_ES2015_BUILTIN_PROMISE) */
+
 #if !ENABLED (JERRY_PARSER) && !ENABLED (JERRY_SNAPSHOT_EXEC)
 #error "JERRY_SNAPSHOT_EXEC must be enabled if JERRY_PARSER is disabled!"
 #endif /* !ENABLED (JERRY_PARSER) && !ENABLED (JERRY_SNAPSHOT_EXEC) */
@@ -3084,6 +3092,60 @@ jerry_resolve_or_reject_promise (jerry_value_t promise, /**< the promise value *
 #endif /* ENABLED (JERRY_ES2015_BUILTIN_PROMISE) */
 } /* jerry_resolve_or_reject_promise */
 
+/**
+ * Get the result of a promise.
+ *
+ * @return - Promise result
+ *         - Type error if the promise support was not enabled or the input was not a promise object
+ */
+jerry_value_t
+jerry_get_promise_result (const jerry_value_t promise) /**< promise object to get the result from */
+{
+  jerry_assert_api_available ();
+
+#if ENABLED (JERRY_ES2015_BUILTIN_PROMISE)
+  if (!jerry_value_is_promise (promise))
+  {
+    return jerry_throw (ecma_raise_type_error (ECMA_ERR_MSG (wrong_args_msg_p)));
+  }
+
+  return ecma_promise_get_result (ecma_get_object_from_value (promise));
+#else /* !ENABLED (JERRY_ES2015_BUILTIN_PROMISE) */
+  JERRY_UNUSED (promise);
+  return jerry_throw (ecma_raise_type_error (ECMA_ERR_MSG ("Promise not supported.")));
+#endif /* ENABLED (JERRY_ES2015_BUILTIN_PROMISE) */
+} /* jerry_get_promise_result */
+
+/**
+ * Get the state of a promise object.
+ *
+ * @return - the state of the promise (one of the jerry_promise_state_t enum values)
+ *         - JERRY_PROMISE_STATE_NONE is only returned if the input is not a promise object
+ *           or the promise support was not enabled.
+ */
+jerry_promise_state_t
+jerry_get_promise_state (const jerry_value_t promise) /**< promise object to get the state from */
+{
+  jerry_assert_api_available ();
+
+#if ENABLED (JERRY_ES2015_BUILTIN_PROMISE)
+  if (!jerry_value_is_promise (promise))
+  {
+    return JERRY_PROMISE_STATE_NONE;
+  }
+
+  uint8_t state = ecma_promise_get_state (ecma_get_object_from_value (promise));
+
+  JERRY_ASSERT (state < ECMA_PROMISE_STATE__COUNT);
+
+  /* Static assert above guarantees the mapping from internal type to external type. */
+  return (jerry_promise_state_t) (state + 1);
+#else /* !ENABLED (JERRY_ES2015_BUILTIN_PROMISE) */
+  JERRY_UNUSED (promise);
+  return JERRY_PROMISE_STATE_NONE;
+#endif /* ENABLED (JERRY_ES2015_BUILTIN_PROMISE) */
+} /* jerry_get_promise_state */
+
 /**
  * Call the SymbolDescriptiveString ecma builtin operation on the symbol value.
  *

jerry-core/ecma/operations/ecma-promise-object.c

@@ -53,7 +53,7 @@ ecma_is_promise (ecma_object_t *obj_p) /**< points to object */
  * @return ecma value of the promise result.
  *         Returned value must be freed with ecma_free_value
  */
-static inline ecma_value_t
+ecma_value_t
 ecma_promise_get_result (ecma_object_t *obj_p) /**< points to promise object */
 {
   JERRY_ASSERT (ecma_is_promise (obj_p));
@@ -84,7 +84,7 @@ ecma_promise_set_result (ecma_object_t *obj_p, /**< points to promise object */
  *
  * @return the state's enum value
  */
-static inline uint8_t JERRY_ATTR_ALWAYS_INLINE
+uint8_t
 ecma_promise_get_state (ecma_object_t *obj_p) /**< points to promise object */
 {
   JERRY_ASSERT (ecma_is_promise (obj_p));

jerry-core/ecma/operations/ecma-promise-object.h

@@ -71,6 +71,8 @@ typedef struct
 bool ecma_is_promise (ecma_object_t *obj_p);
 ecma_value_t
 ecma_op_create_promise_object (ecma_value_t executor, ecma_promise_executor_type_t type);
+uint8_t ecma_promise_get_state (ecma_object_t *promise_p);
+ecma_value_t ecma_promise_get_result (ecma_object_t *promise_p);
 ecma_value_t ecma_promise_new_capability (void);
 ecma_value_t
 ecma_promise_then (ecma_value_t promise,

jerry-core/include/jerryscript-core.h

@@ -555,10 +555,24 @@ bool jerry_foreach_object_property (const jerry_value_t obj_val, jerry_object_pr
                                     void *user_data_p);
 
 /**
- * Promise resolve/reject functions.
+ * Promise functions.
  */
 jerry_value_t jerry_resolve_or_reject_promise (jerry_value_t promise, jerry_value_t argument, bool is_resolve);
 
+/**
+ * Enum values representing various Promise states.
+ */
+typedef enum
+{
+  JERRY_PROMISE_STATE_NONE = 0u, /**< 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. */
+} jerry_promise_state_t;
+
+jerry_value_t jerry_get_promise_result (const jerry_value_t promise);
+jerry_promise_state_t jerry_get_promise_state (const jerry_value_t promise);
+
 /**
  * Symbol functions.
  */