N-API exposes a set of APIs to get and set properties on JavaScript objects. Some of these types are documented under [Section 7][] of the [ECMAScript Language Specification][].

    Properties in JavaScript are represented as a tuple of a key and a value. Fundamentally, all property keys in N-API can be represented in one of the following forms:

    • Named: a simple UTF8-encoded string
    • Integer-Indexed: an index value represented by uint32_t
    • JavaScript value: these are represented in N-API by napi_value. This can be a napi_value representing a String, Number, or Symbol.

    N-API values are represented by the type napi_value. Any N-API call that requires a JavaScript value takes in a napi_value. However, it’s the caller’s responsibility to make sure that the napi_value in question is of the JavaScript type expected by the API.

    The APIs documented in this section provide a simple interface to get and set properties on arbitrary JavaScript objects represented by napi_value.

    For instance, consider the following JavaScript code snippet:

    1. const obj = {};
    2. obj.myProp = 123;

    The equivalent can be done using N-API values with the following snippet:

    1. napi_status status = napi_generic_failure;
    3. // const obj = {}
    4. napi_value obj, value;
    5. status = napi_create_object(env, &obj);
    6. if (status != napi_ok) return status;
    8. // Create a napi_value for 123
    9. status = napi_create_int32(env, 123, &value);
    10. if (status != napi_ok) return status;
    12. // obj.myProp = 123
    13. status = napi_set_named_property(env, obj, "myProp", value);
    14. if (status != napi_ok) return status;

    Indexed properties can be set in a similar manner. Consider the following JavaScript snippet:

    1. const arr = [];
    2. arr[123] = 'hello';

    The equivalent can be done using N-API values with the following snippet:

    1. napi_status status = napi_generic_failure;
    3. // const arr = [];
    4. napi_value arr, value;
    5. status = napi_create_array(env, &arr);
    6. if (status != napi_ok) return status;
    8. // Create a napi_value for 'hello'
    9. status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &value);
    10. if (status != napi_ok) return status;
    12. // arr[123] = 'hello';
    13. status = napi_set_element(env, arr, 123, value);
    14. if (status != napi_ok) return status;

    Properties can be retrieved using the APIs described in this section. Consider the following JavaScript snippet:

    1. const arr = [];
    2. const value = arr[123];

    The following is the approximate equivalent of the N-API counterpart:

    1. napi_status status = napi_generic_failure;
    3. // const arr = []
    4. napi_value arr, value;
    5. status = napi_create_array(env, &arr);
    6. if (status != napi_ok) return status;
    8. // const value = arr[123]
    9. status = napi_get_element(env, arr, 123, &value);
    10. if (status != napi_ok) return status;

    Finally, multiple properties can also be defined on an object for performance reasons. Consider the following JavaScript:

    1. const obj = {};
    2. Object.defineProperties(obj, {
    3.   'foo': { value: 123, writable: true, configurable: true, enumerable: true },
    4.   'bar': { value: 456, writable: true, configurable: true, enumerable: true }
    5. });

    The following is the approximate equivalent of the N-API counterpart:

    1. napi_status status = napi_status_generic_failure;
    3. // const obj = {};
    4. napi_value obj;
    5. status = napi_create_object(env, &obj);
    6. if (status != napi_ok) return status;
    8. // Create napi_values for 123 and 456
    9. napi_value fooValue, barValue;
    10. status = napi_create_int32(env, 123, &fooValue);
    11. if (status != napi_ok) return status;
    12. status = napi_create_int32(env, 456, &barValue);
    13. if (status != napi_ok) return status;
    15. // Set the properties
    16. napi_property_descriptor descriptors[] = {
    17.   { "foo", NULL, NULL, NULL, NULL, fooValue, napi_writable | napi_configurable, NULL },
    18.   { "bar", NULL, NULL, NULL, NULL, barValue, napi_writable | napi_configurable, NULL }
    19. }
    20. status = napi_define_properties(env,
    21.                                 obj,
    22.                                 sizeof(descriptors) / sizeof(descriptors[0]),
    23.                                 descriptors);
    24. if (status != napi_ok) return status;