node-api: clarify enum value ABI stability · nodejs/node@65c870e
@@ -121,6 +121,32 @@ must use Node-API exclusively by restricting itself to using
121121and by checking, for all external libraries that it uses, that the external
122122library makes ABI stability guarantees similar to Node-API.
123123124+### Enum values in ABI stability
125+126+All enum data types defined in Node-API should be considered as a fixed size
127+`int32_t` value. Bit flag enum types should be explicitly documented, and they
128+work with bit operators like bit-OR (`|`) as a bit value. Unless otherwise
129+documented, an enum type should be considered to be extensible.
130+131+A new enum value will be added at the end of the enum definition. An enum value
132+will not be removed or renamed.
133+134+For an enum type returned from a Node-API function, or provided as an out
135+parameter of a Node-API function, the value is an integer value and an addon
136+should handle unknown values. New values are allowed to be introduced without
137+a version guard. For example, when checking `napi_status` in switch statements,
138+an addon should include a default branch, as new status codes may be introduced
139+in newer Node.js versions.
140+141+For an enum type used in an in-parameter, the result of passing an unknown
142+integer value to Node-API functions is undefined unless otherwise documented.
143+A new value is added with a version guard to indicate the Node-API version in
144+which it was introduced. For example, `napi_get_all_property_names` can be
145+extended with new enum value of `napi_key_filter`.
146+147+For an enum type used in both in-parameters and out-parameters, new values are
148+allowed to be introduced without a version guard.
149+124150## Building
125151126152Unlike modules written in JavaScript, developing and deploying Node.js
@@ -2203,7 +2229,7 @@ typedef enum {
22032229} napi_key_filter;
22042230```
220522312206-Property filter bits. They can be or'ed to build a composite filter.
2232+Property filter bit flag. This works with bit operators to build a composite filter.
2207223322082234#### `napi_key_conversion`
22092235@@ -4417,11 +4443,11 @@ typedef enum {
44174443} napi_property_attributes;
44184444```
441944454420-`napi_property_attributes` are flags used to control the behavior of properties
4421-set on a JavaScript object. Other than `napi_static` they correspond to the
4422-attributes listed in [Section property attributes][]
4446+`napi_property_attributes` are bit flags used to control the behavior of
4447+properties set on a JavaScript object. Other than `napi_static` they
4448+correspond to the attributes listed in [Section property attributes][]
44234449of the [ECMAScript Language Specification][].
4424-They can be one or more of the following bitflags:
4450+They can be one or more of the following bit flags:
4425445144264452* `napi_default`: No explicit attributes are set on the property. By default, a
44274453 property is read only, not enumerable and not configurable.