abi-stable-node | Repository used by the Node-API team | Runtime Evironment library

For an explanation of what HandleScopes are and what to use them for, see V8's documentation, e.g. for the class Local:

There are two types of handles: local and persistent handles.

Local handles are light-weight and transient and typically used in local operations. They are managed by HandleScopes. That means that a HandleScope must exist on the stack when they are created and that they are only valid inside of the HandleScope active during their creation. For passing a local handle to an outer HandleScope, an EscapableHandleScope and its Escape() method must be used.

And for the class HandleScope:

A stack-allocated class that governs a number of local handles. After a handle scope has been created, all local handles will be allocated within that handle scope until either the handle scope is deleted or another handle scope is created. If there is already a handle scope and a new one is created, all allocations will take place in the new handle scope until it is deleted. After that, new handles will again be allocated in the original handle scope.

After the handle scope of a local handle has been deleted the garbage collector will no longer track the object stored in the handle and may deallocate it. The behavior of accessing a handle for which the handle scope has been deleted is undefined.

Pragmatically:

• When calling from JavaScript into C++, you'll need at least one HandleScope if the C++ code creates any Local<>s. Usually exactly one HandleScope is the right number.
• There's a cost to creating and destroying HandleScopes, so if you have many fine-grained HandleScopes, you're wasting time. On the other hand, a HandleScope (by design, that's its purpose!) keeps all objects alive (in the GC sense) that the handles contained in it are referring to, so for very long-running code, or loops with many iterations, you may want to introduce short-lived HandleScopes so that temporary objects you're done with can be freed.
• As the documentation says, you need an EscapableHandleScope if you want to return an object beyond the end of the lifetime of the scope.