node-api: clarify enum value ABI stability · nodejs/node@65c870e

@@ -121,6 +121,32 @@ must use Node-API exclusively by restricting itself to using

121121

and by checking, for all external libraries that it uses, that the external

122122

library 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

125151126152

Unlike 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][]

44234449

of 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.