Italian Translation Report: Node.js [Part 6 - 1003 words]

The environment that the API is invoked under.
representing the new scope.
Returns if the API succeeded
This API open a new scope.
representing the scope to be closed.
This API closes the scope passed in.
Scopes must be closed in the
reverse order from which they were created.
This API can be called even if there is a pending JavaScript exception.
This API open a new scope from which one object can be promoted
to the outer scope.
representing the current scope.
representing the JavaScript to be
escaped.
representing the handle to the escaped
in the outer scope.
This API promotes the handle to the JavaScript object so that it is valid
for the lifetime of the outer scope.
It can only be called once per scope.
If it is called more than once an error will be returned.
References to objects with a lifespan longer than that of the native method

In some cases an addon will need to be able to create and reference objects with a lifespan longer than that of a single native method invocation. For example, to create a constructor and later use that constructor in a request to creates instances, it must be possible to reference the constructor object across many different instance creation requests. This would not be possible with a normal handle returned as a as described in the earlier section. The lifespan of a normal handle is managed by scopes and all scopes must be closed before the end of a native method.
N-API provides methods to create persistent references to an object. Each persistent reference has an associated count with a value of 0 or higher. The count determines if the reference will keep the corresponding object live. References with a count of 0 do not prevent the object from being collected and are often called 'weak' references. Any count greater than 0 will prevent the object from being collected.
References can be created with an initial reference count. The count can then be modified through and. If an object is collected while the count for a reference is 0, all subsequent calls to get the object associated with the reference will return NULL for the returned napi_value. An attempt to call for a reference whose object has been collected will result in an error.
References must be deleted once they are no longer required by the addon. When a reference is deleted it will no longer prevent the corresponding object from being collected. Failure to delete a persistent reference will result in a 'memory leak' with both the native memory for the persistent reference and the corresponding object on the heap being retained forever.
There can be multiple persistent references created which refer to the same object, each of which will either keep the object live or not based on its individual count.

representing the to which we want
a reference.
Initial reference count for the new reference.
pointing to the new reference.
This API create a new reference with the specified reference count
to the passed in.
to be deleted.
This API deletes the reference passed in.
for which the reference count will be incremented.
The new reference count.
This API increments the reference count for the reference
passed in and returns the resulting reference count.
for which the reference count will be decremented.
This API decrements the reference count for the reference
passed in and returns the resulting reference count.
the in or out of these methods is a handle to the
object to which the reference is related.
for which we requesting the corresponding
The for the referenced by the
If still valid, this API returns the representing the
JavaScript associated with the
Otherwise, result will be NULL.

Module registration
N-API modules are registered in a manner similar to other modules
except that instead of using the macro the following
is used:
The next difference is the signature for the method.
For a N-API
module it is as follows:
The return value from is treated as the object for the module.
The method is passed an empty object via the parameter as a
convenience.
If returns NULL, the parameter passed as is
exported by the module.
N-API modules cannot modify the object but can
specify anything as the property of the module.
To add the method as a function so that it can be called as a method
provided by the addon:
To set a function to be returned by the for the addon:
To define a class so that new instances can be created (often used with):
NOTE: partial example, not all referenced code is included
If you expect that your module will be loaded multiple times during the lifetime
of the Node.js process, you can use the macro to initialize
your module:
This macro includes, and declares an function with a
special name and with visibility beyond the addon.
This will allow Node.js to
initialize the module even if it is loaded multiple times.
The variables and will be available inside the function body
following the macro invocation.
For more details on setting properties on objects, see the section on Working with JavaScript Properties.
For more details on building addon modules in general, refer to the existing
API.

Working with JavaScript Values
N-API exposes a set of APIs to create all types of JavaScript values. Some of these types are documented under Section 6 of the ECMAScript Language Specification.
Fundamentally, these APIs are used to do one of the following:
Create a new JavaScript object
Convert from a primitive C type to an N-API value
Convert from N-API value to a primitive C type
Get global instances including undefined and null
N-API values are represented by the type. Any N-API call that requires a JavaScript value takes in a. In some cases, the API does check the type of the. up-front. However, for better performance, it's better for the caller to make sure that the in question is of the JavaScript type expected by the API.