/
n_api_version_matrix.md
195 lines (174 loc) · 6.1 KB
/
n_api_version_matrix.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
N-API versions are additive and versioned independently from Node.js.
Version 4 is an extension to version 3 in that it has all of the APIs
from version 3 with some additions. This means that it is not necessary
to recompile for new versions of Node.js which are
listed as supporting a later version.
<!-- For accessibility purposes, this table needs row headers. That means we
can't do it in markdown. Hence, the raw HTML. -->
<table>
<tr>
<td></td>
<th scope="col">1</th>
<th scope="col">2</th>
<th scope="col">3</th>
</tr>
<tr>
<th scope="row">v6.x</th>
<td></td>
<td></td>
<td>v6.14.2*</td>
</tr>
<tr>
<th scope="row">v8.x</th>
<td>v8.6.0**</td>
<td>v8.10.0*</td>
<td>v8.11.2</td>
</tr>
<tr>
<th scope="row">v9.x</th>
<td>v9.0.0*</td>
<td>v9.3.0*</td>
<td>v9.11.0*</td>
</tr>
<tr>
<th scope="row">≥ v10.x</th>
<td>all releases</td>
<td>all releases</td>
<td>all releases</td>
</tr>
</table>
<table>
<tr>
<td></td>
<th scope="col">4</th>
<th scope="col">5</th>
<th scope="col">6</th>
<th scope="col">7</th>
</tr>
<tr>
<th scope="row">v10.x</th>
<td>v10.16.0</td>
<td>v10.17.0</td>
<td>v10.20.0</td>
<td></td>
</tr>
<tr>
<th scope="row">v11.x</th>
<td>v11.8.0</td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<th scope="row">v12.x</th>
<td>v12.0.0</td>
<td>v12.11.0</td>
<td>v12.17.0</td>
<td>v12.19.0</td>
</tr>
<tr>
<th scope="row">v13.x</th>
<td>v13.0.0</td>
<td>v13.0.0</td>
<td></td>
<td></td>
</tr>
<tr>
<th scope="row">v14.x</th>
<td>v14.0.0</td>
<td>v14.0.0</td>
<td>v14.0.0</td>
<td>v14.12.0</td>
</tr>
</table>
\* N-API was experimental.
\*\* Node.js 8.0.0 included N-API as experimental. It was released as N-API
version 1 but continued to evolve until Node.js 8.6.0. The API is different in
versions prior to Node.js 8.6.0. We recommend N-API version 3 or later.
Each API documented for N-API will have a header named `added in:`, and APIs
which are stable will have the additional header `N-API version:`.
APIs are directly usable when using a Node.js version which supports
the N-API version shown in `N-API version:` or higher.
When using a Node.js version that does not support the
`N-API version:` listed or if there is no `N-API version:` listed,
then the API will only be available if
`#define NAPI_EXPERIMENTAL` precedes the inclusion of `node_api.h`
or `js_native_api.h`. If an API appears not to be available on
a version of Node.js which is later than the one shown in `added in:` then
this is most likely the reason for the apparent absence.
The N-APIs associated strictly with accessing ECMAScript features from native
code can be found separately in `js_native_api.h` and `js_native_api_types.h`.
The APIs defined in these headers are included in `node_api.h` and
`node_api_types.h`. The headers are structured in this way in order to allow
implementations of N-API outside of Node.js. For those implementations the
Node.js specific APIs may not be applicable.
The Node.js-specific parts of an addon can be separated from the code that
exposes the actual functionality to the JavaScript environment so that the
latter may be used with multiple implementations of N-API. In the example below,
`addon.c` and `addon.h` refer only to `js_native_api.h`. This ensures that
`addon.c` can be reused to compile against either the Node.js implementation of
N-API or any implementation of N-API outside of Node.js.
`addon_node.c` is a separate file that contains the Node.js specific entry point
to the addon and which instantiates the addon by calling into `addon.c` when the
addon is loaded into a Node.js environment.
```c
// addon.h
#ifndef _ADDON_H_
#define _ADDON_H_
#include <js_native_api.h>
napi_value create_addon(napi_env env);
#endif // _ADDON_H_
```
```c
// addon.c
#include "addon.h"
#define NAPI_CALL(env, call) \
do { \
napi_status status = (call); \
if (status != napi_ok) { \
const napi_extended_error_info* error_info = NULL; \
napi_get_last_error_info((env), &error_info); \
bool is_pending; \
napi_is_exception_pending((env), &is_pending); \
if (!is_pending) { \
const char* message = (error_info->error_message == NULL) \
? "empty error message" \
: error_info->error_message; \
napi_throw_error((env), NULL, message); \
return NULL; \
} \
} \
} while(0)
static napi_value
DoSomethingUseful(napi_env env, napi_callback_info info) {
// Do something useful.
return NULL;
}
napi_value create_addon(napi_env env) {
napi_value result;
NAPI_CALL(env, napi_create_object(env, &result));
napi_value exported_function;
NAPI_CALL(env, napi_create_function(env,
"doSomethingUseful",
NAPI_AUTO_LENGTH,
DoSomethingUseful,
NULL,
&exported_function));
NAPI_CALL(env, napi_set_named_property(env,
result,
"doSomethingUseful",
exported_function));
return result;
}
```
```c
// addon_node.c
#include <node_api.h>
#include "addon.h"
NAPI_MODULE_INIT() {
// This function body is expected to return a `napi_value`.
// The variables `napi_env env` and `napi_value exports` may be used within
// the body, as they are provided by the definition of `NAPI_MODULE_INIT()`.
return create_addon(env);
}
```