node-addon-api 1.6.3 → 2.0.0

package/doc/class_property_descriptor.md

@@ -1,4 +1,4 @@
-# Class propertry and descriptor
+# Class property and descriptor
 
 Property descriptor for use with `Napi::ObjectWrap::DefineClass()`.
 This is different from the standalone `Napi::PropertyDescriptor` because it is
@@ -6,6 +6,87 @@ specific to each `Napi::ObjectWrap<T>` subclass.
 This prevents using descriptors from a different class when defining a new class
 (preventing the callbacks from having incorrect `this` pointers).
 
+## Example
+
+```cpp
+#include <napi.h>
+
+class Example : public Napi::ObjectWrap<Example> {
+  public:
+    static Napi::Object Init(Napi::Env env, Napi::Object exports);
+    Example(const Napi::CallbackInfo &info);
+
+  private:
+    static Napi::FunctionReference constructor;
+    double _value;
+    Napi::Value GetValue(const Napi::CallbackInfo &info);
+    void SetValue(const Napi::CallbackInfo &info, const Napi::Value &value);
+};
+
+Napi::Object Example::Init(Napi::Env env, Napi::Object exports) {
+    Napi::Function func = DefineClass(env, "Example", {
+        // Register a class instance accessor with getter and setter functions.
+        InstanceAccessor("value", &Example::GetValue, &Example::SetValue),
+        // We can also register a readonly accessor by passing nullptr as the setter.
+        InstanceAccessor("readOnlyProp", &Example::GetValue, nullptr)
+    });
+
+    constructor = Napi::Persistent(func);
+    constructor.SuppressDestruct();
+    exports.Set("Example", func);
+
+    return exports;
+}
+
+Example::Example(const Napi::CallbackInfo &info) : Napi::ObjectWrap<Example>(info) {
+    Napi::Env env = info.Env();
+    // ...
+    Napi::Number value = info[0].As<Napi::Number>();
+    this->_value = value.DoubleValue();
+}
+
+Napi::FunctionReference Example::constructor;
+
+Napi::Value Example::GetValue(const Napi::CallbackInfo &info) {
+    Napi::Env env = info.Env();
+    return Napi::Number::New(env, this->_value);
+}
+
+void Example::SetValue(const Napi::CallbackInfo &info, const Napi::Value &value) {
+    Napi::Env env = info.Env();
+    // ...
+    Napi::Number arg = value.As<Napi::Number>();
+    this->_value = arg.DoubleValue();
+}
+
+// Initialize native add-on
+Napi::Object Init (Napi::Env env, Napi::Object exports) {
+    Example::Init(env, exports);
+    return exports;
+}
+
+// Register and initialize native add-on
+NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
+```
+
+The above code can be used from JavaScript as follows:
+
+```js
+'use strict';
+
+const { Example } = require('bindings')('addon');
+
+const example = new Example(11);
+console.log(example.value);
+// It prints 11
+example.value = 19;
+console.log(example.value);
+// It prints 19
+example.readOnlyProp = 500;
+console.log(example.readOnlyProp);
+// Unchanged. It prints 19
+```
+
 ## Methods
 
 ### Constructor

package/doc/cmake-js.md

@@ -1,19 +1,68 @@
 # CMake.js
 
-**CMake.js** is a build tool that allow native addon developer to compile their
-C++ code into executable form. It works like **[node-gyp](node-gyp.md)** but
-instead of Google's **gyp** format it is base on **CMake** build system.
+[**CMake.js**](https://github.com/cmake-js/cmake-js) is a build tool that allow native addon developers to compile their
+C or C++ code into executable form. It works like **[node-gyp](node-gyp.md)** but
+instead of Google's [**gyp**](https://gyp.gsrc.io) tool it is based on the [**CMake**](https://cmake.org) build system.
 
-## **CMake** reference
+## Quick Start
 
-  - [Installation](https://www.npmjs.com/package/cmake-js#installation)
-  - [How to use](https://www.npmjs.com/package/cmake-js#usage)
+### Install CMake
+
+CMake.js requires that CMake be installed. Installers for a variety of platforms can be found on the [CMake website](https://cmake.org).
+
+### Install CMake.js
+
+For developers, CMake.js is typically installed as a global package:
+
+```bash
+npm install -g cmake-js
+cmake-js --help
+```
+
+> For *users* of your native addon, CMake.js should be configured as a dependency in your `package.json` as described in the [CMake.js documentation](https://github.com/cmake-js/cmake-js).
+
+### CMakeLists.txt
+
+Your project will require a `CMakeLists.txt` file. The [CMake.js README file](https://github.com/cmake-js/cmake-js#usage) shows what's necessary.
+
+### NAPI_VERSION
+
+When building N-API addons, it's crucial to specify the N-API version your code is designed to work with. With CMake.js, this information is specified in the `CMakeLists.txt` file:
+
+```
+add_definitions(-DNAPI_VERSION=3)
+```
+
+Since N-API is ABI-stable, your N-API addon will work, without recompilation, with the N-API version you specify in `NAPI_VERSION` and all subsequent N-API versions.
+
+In the absence of a need for features available only in a specific N-API version, version 3 is a good choice as it is the version of N-API that was active when N-API left experimental status.
+
+### NAPI_EXPERIMENTAL
+
+The following line in the `CMakeLists.txt` file will enable N-API experimental features if your code requires them:
+
+```
+add_definitions(-DNAPI_EXPERIMENTAL)
+```
+
+### node-addon-api
+
+If your N-API native add-on uses the optional [**node-addon-api**](https://github.com/nodejs/node-addon-api#node-addon-api-module) C++ wrapper, the `CMakeLists.txt` file requires additional configuration information as described on the [CMake.js README file](https://github.com/cmake-js/cmake-js#n-api-and-node-addon-api).
+
+## Example
+
+A working example of an N-API native addon built using CMake.js can be found on the [node-addon-examples repository](https://github.com/nodejs/node-addon-examples/tree/master/build_with_cmake#building-n-api-addons-using-cmakejs).
+
+## **CMake** Reference
+
+  - [Installation](https://github.com/cmake-js/cmake-js#installation)
+  - [How to use](https://github.com/cmake-js/cmake-js#usage)
   - [Using N-API and node-addon-api](https://github.com/cmake-js/cmake-js#n-api-and-node-addon-api)
-  - [Tutorials](https://www.npmjs.com/package/cmake-js#tutorials)
-  - [Use case in the works - ArrayFire.js](https://www.npmjs.com/package/cmake-js#use-case-in-the-works---arrayfirejs)
+  - [Tutorials](https://github.com/cmake-js/cmake-js#tutorials)
+  - [Use case in the works - ArrayFire.js](https://github.com/cmake-js/cmake-js#use-case-in-the-works---arrayfirejs)
 
 Sometimes finding the right settings is not easy so to accomplish at most
 complicated task please refer to:
 
 - [CMake documentation](https://cmake.org/)
-- [CMake.js wiki](https://github.com/cmake-js/cmake-js/wiki)
+- [CMake.js wiki](https://github.com/cmake-js/cmake-js/wiki)

package/doc/date.md

@@ -0,0 +1,68 @@
+# Date
+
+`Napi::Date` class is a representation of the JavaScript `Date` object. The
+`Napi::Date` class inherits its behavior from `Napi::Value` class
+(for more info see [`Napi::Value`](value.md))
+
+## Methods
+
+### Constructor
+
+Creates a new _empty_ instance of a `Napi::Date` object.
+
+```cpp
+Napi::Date::Date();
+```
+
+Creates a new _non-empty_ instance of a `Napi::Date` object.
+
+```cpp
+Napi::Date::Date(napi_env env, napi_value value);
+```
+
+ - `[in] env`: The environment in which to construct the `Napi::Date` object.
+ - `[in] value`: The `napi_value` which is a handle for a JavaScript `Date`.
+
+### New
+
+Creates a new instance of a `Napi::Date` object.
+
+```cpp
+static Napi::Date Napi::Date::New(Napi::Env env, double value);
+```
+
+ - `[in] env`: The environment in which to construct the `Napi::Date` object.
+ - `[in] value`: The time value the JavaScript `Date` will contain represented
+  as the number of milliseconds since 1 January 1970 00:00:00 UTC.
+
+Returns a new instance of `Napi::Date` object.
+
+### ValueOf
+
+```cpp
+double Napi::Date::ValueOf() const;
+```
+
+Returns the time value as `double` primitive represented as the number of
+ milliseconds since 1 January 1970 00:00:00 UTC.
+
+## Operators
+
+### operator double
+
+Converts a `Napi::Date` value to a `double` primitive.
+
+```cpp
+Napi::Date::operator double() const;
+```
+
+### Example
+
+The following shows an example of casting a `Napi::Date` value to a `double`
+ primitive.
+
+```cpp
+double operatorVal = Napi::Date::New(Env(), 0); // Napi::Date to double
+// or
+auto instanceVal = info[0].As<Napi::Date>().ValueOf();
+```

package/doc/object.md

@@ -23,12 +23,12 @@ Void Init(Env env) {
 
   // Assign values to properties
   obj.Set("hello", "world");
-  obj.Set(42, "The Answer to Life, the Universe, and Everything");
+  obj.Set(uint32_t(42), "The Answer to Life, the Universe, and Everything");
   obj.Set("Douglas Adams", true);
 
   // Get properties
   Value val1 = obj.Get("hello");
-  Value val2 = obj.Get(42);
+  Value val2 = obj.Get(uint32_t(42));
   Value val3 = obj.Get("Douglas Adams");
 
   // Test if objects have properties.
@@ -137,6 +137,40 @@ Returns a `bool` that is true if the `Napi::Object` is an instance created by th
 
 Note: This is equivalent to the JavaScript instanceof operator.
 
+### AddFinalizer()
+```cpp
+template <typename Finalizer, typename T>
+inline void AddFinalizer(Finalizer finalizeCallback, T* data);
+```
+
+- `[in] finalizeCallback`: The function to call when the object is garbage-collected.
+- `[in] data`: The data to associate with the object.
+
+Associates `data` with the object, calling `finalizeCallback` when the object is garbage-collected. `finalizeCallback`
+has the signature
+```cpp
+void finalizeCallback(Napi::Env env, T* data);
+```
+where `data` is the pointer that was passed into the call to `AddFinalizer()`.
+
+### AddFinalizer()
+```cpp
+template <typename Finalizer, typename T, typename Hint>
+inline void AddFinalizer(Finalizer finalizeCallback,
+                         T* data,
+                         Hint* finalizeHint);
+```
+
+- `[in] data`: The data to associate with the object.
+- `[in] finalizeCallback`: The function to call when the object is garbage-collected.
+
+Associates `data` with the object, calling `finalizeCallback` when the object is garbage-collected. An additional hint
+may be given. It will also be passed to `finalizeCallback`, which has the signature
+```cpp
+void finalizeCallback(Napi::Env env, T* data, Hint* hint);
+```
+where `data` and `hint` are the pointers that were passed into the call to `AddFinalizer()`.
+
 ### DefineProperty()
 
 ```cpp

package/doc/object_wrap.md

@@ -78,7 +78,7 @@ Napi::Object Init (Napi::Env env, Napi::Object exports) {
     return exports;
 }
 
-// Regisgter and initialize native add-on
+// Register and initialize native add-on
 NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
 ```
 
@@ -161,7 +161,7 @@ static Napi::Function Napi::ObjectWrap::DefineClass(Napi::Env env,
 JavaScript constructor function.
 * `[in] properties`: Initializer list of class property descriptor describing
 static and instance properties and methods of the class.
-See: [`Class propertry and descriptor`](class_property_descriptor.md).
+See: [`Class property and descriptor`](class_property_descriptor.md).
 * `[in] data`: User-provided data passed to the constructor callback as `data`
 property of the `Napi::CallbackInfo`.
 
@@ -184,12 +184,23 @@ static Napi::Function Napi::ObjectWrap::DefineClass(Napi::Env env,
 JavaScript constructor function.
 * `[in] properties`: Vector of class property descriptor describing static and
 instance properties and methods of the class.
-See: [`Class propertry and descriptor`](class_property_descriptor.md).
+See: [`Class property and descriptor`](class_property_descriptor.md).
 * `[in] data`: User-provided data passed to the constructor callback as `data`
 property of the `Napi::CallbackInfo`.
 
 Returns a `Napi::Function` representing the constructor function for the class.
 
+### Finalize
+
+Provides an opportunity to run cleanup code that requires access to the `Napi::Env`
+before the wrapped native object instance is freed.  Override to implement.
+
+```cpp
+virtual void Finalize(Napi::Env env);
+```
+
+- `[in] env`: `Napi::Env`.
+
 ### StaticMethod
 
 Creates property descriptor that represents a static method of a JavaScript class.

package/doc/prebuild_tools.md

@@ -2,14 +2,14 @@
 
 The distribution of a native add-on is just as important as its implementation.
 In order to install a native add-on it's important to have all the necessary
-dependencies installed and well configured (see the [setup](doc/setum.md) section).
+dependencies installed and well configured (see the [setup](setup.md) section).
 The end-user will need to compile the add-on when they will do an `npm install`
 and in some cases this could create problems. To avoid the compilation process it's
 possible to ditribute the native add-on in pre-built form for different platform
 and architectures. The prebuild tools help to create and distrubute the pre-built
 form of a native add-on.
 
-The following list report two of the tools that are compatible with **N-API**:
+The following list report known tools that are compatible with **N-API**:
 
 - **[node-pre-gyp](https://www.npmjs.com/package/node-pre-gyp)**
 - **[prebuild](https://www.npmjs.com/package/prebuild)**

package/doc/string.md

@@ -56,6 +56,8 @@ Napi::String::New(napi_env env, const std::string& value);
 Napi::String::New(napi_env env, const std::u16::string& value);
 Napi::String::New(napi_env env, const char* value);
 Napi::String::New(napi_env env, const char16_t* value);
+Napi::String::New(napi_env env, const char* value, size_t length);
+Napi::String::New(napi_env env, const char16_t* value, size_t length);
 ```
 
 - `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object.
@@ -64,6 +66,7 @@ Napi::String::New(napi_env env, const char16_t* value);
   - `std::u16string&` - represents a UTF16-LE string.
   - `const char*` - represents a UTF8 string.
   - `const char16_t*` - represents a UTF16-LE string.
+- `[in] length`: The length of the string (not necessarily null-terminated) in code units.
 
 Returns a new `Napi::String` that represents the passed in C++ string.
 

package/doc/threadsafe_function.md

@@ -0,0 +1,320 @@
+# ThreadSafeFunction
+
+JavaScript functions can normally only be called from a native addon's main
+thread. If an addon creates additional threads, then node-addon-api functions
+that require a `Napi::Env`, `Napi::Value`, or `Napi::Reference` must not be
+called from those threads.
+
+When an addon has additional threads and JavaScript functions need to be invoked
+based on the processing completed by those threads, those threads must
+communicate with the addon's main thread so that the main thread can invoke the
+JavaScript function on their behalf. The thread-safe function APIs provide an
+easy way to do this.
+
+These APIs provide the type `Napi::ThreadSafeFunction` as well as APIs to
+create, destroy, and call objects of this type.
+`Napi::ThreadSafeFunction::New()` creates a persistent reference that holds a
+JavaScript function which can be called from multiple threads. The calls happen
+asynchronously. This means that values with which the JavaScript callback is to
+be called will be placed in a queue, and, for each value in the queue, a call
+will eventually be made to the JavaScript function.
+
+`Napi::ThreadSafeFunction` objects are destroyed when every thread which uses
+the object has called `Release()` or has received a return status of
+`napi_closing` in response to a call to `BlockingCall()` or `NonBlockingCall()`.
+The queue is emptied before the `Napi::ThreadSafeFunction` is destroyed. It is
+important that `Release()` be the last API call made in conjunction with a given
+`Napi::ThreadSafeFunction`, because after the call completes, there is no
+guarantee that the `Napi::ThreadSafeFunction` is still allocated. For the same
+reason it is also important that no more use be made of a thread-safe function
+after receiving a return value of `napi_closing` in response to a call to
+`BlockingCall()` or `NonBlockingCall()`. Data associated with the
+`Napi::ThreadSafeFunction` can be freed in its `Finalizer` callback which was
+passed to `ThreadSafeFunction::New()`.
+
+Once the number of threads making use of a `Napi::ThreadSafeFunction` reaches
+zero, no further threads can start making use of it by calling `Acquire()`. In
+fact, all subsequent API calls associated with it, except `Release()`, will
+return an error value of `napi_closing`.
+
+## Methods
+
+### Constructor
+
+Creates a new empty instance of `Napi::ThreadSafeFunction`.
+
+```cpp
+Napi::Function::ThreadSafeFunction();
+```
+
+### Constructor
+
+Creates a new instance of the `Napi::ThreadSafeFunction` object.
+
+```cpp
+Napi::ThreadSafeFunction::ThreadSafeFunction(napi_threadsafe_function tsfn);
+```
+
+- `tsfn`: The `napi_threadsafe_function` which is a handle for an existing
+  thread-safe function.
+
+Returns a non-empty `Napi::ThreadSafeFunction` instance. When using this
+constructor, only use the `Blocking(void*)` / `NonBlocking(void*)` overloads;
+the `Callback` and templated `data*` overloads should _not_ be used. See below
+for additional details.
+
+### New
+
+Creates a new instance of the `Napi::ThreadSafeFunction` object. The `New`
+function has several overloads for the various optional parameters: skip the
+optional parameter for that specific overload.
+
+```cpp
+New(napi_env env,
+    const Function& callback,
+    const Object& resource,
+    ResourceString resourceName,
+    size_t maxQueueSize,
+    size_t initialThreadCount,
+    ContextType* context,
+    Finalizer finalizeCallback,
+    FinalizerDataType* data);
+```
+
+- `env`: The `napi_env` environment in which to construct the
+  `Napi::ThreadSafeFunction` object.
+- `callback`: The `Function` to call from another thread.
+- `[optional] resource`: An object associated with the async work that will be
+  passed to possible async_hooks init hooks.
+- `resourceName`: A JavaScript string to provide an identifier for the kind of
+  resource that is being provided for diagnostic information exposed by the
+  async_hooks API.
+- `maxQueueSize`: Maximum size of the queue. `0` for no limit.
+- `initialThreadCount`: The initial number of threads, including the main
+  thread, which will be making use of this function.
+- `[optional] context`: Data to attach to the resulting `ThreadSafeFunction`.
+- `[optional] finalizeCallback`: Function to call when the `ThreadSafeFunction`
+  is being destroyed.  This callback will be invoked on the main thread when the
+  thread-safe function is about to be destroyed. It receives the context and the
+  finalize data given during construction (if given), and provides an
+  opportunity for cleaning up after the threads e.g. by calling
+  `uv_thread_join()`. It is important that, aside from the main loop thread,
+  there be no threads left using the thread-safe function after the finalize
+  callback completes. Must implement `void operator()(Env env, DataType* data,
+  Context* hint)`, skipping `data` or `hint` if they are not provided.
+  Can be retreived via `GetContext()`.
+- `[optional] data`: Data to be passed to `finalizeCallback`.
+
+Returns a non-empty `Napi::ThreadSafeFunction` instance.
+
+### Acquire
+
+Add a thread to this thread-safe function object, indicating that a new thread
+will start making use of the thread-safe function. 
+
+```cpp
+napi_status Napi::ThreadSafeFunction::Acquire()
+```
+
+Returns one of:
+- `napi_ok`: The thread has successfully acquired the thread-safe function
+for its use. 
+- `napi_closing`: The thread-safe function has been marked as closing via a
+previous call to `Abort()`.
+
+### Release
+
+Indicate that an existing thread will stop making use of the thread-safe
+function. A thread should call this API when it stops making use of this
+thread-safe function. Using any thread-safe APIs after having called this API
+has undefined results in the current thread, as it may have been destroyed.
+
+```cpp
+napi_status Napi::ThreadSafeFunction::Release()
+```
+
+Returns one of:
+- `napi_ok`: The thread-safe function has been successfully released.
+- `napi_invalid_arg`: The thread-safe function's thread-count is zero.
+- `napi_generic_failure`: A generic error occurred when attemping to release
+the thread-safe function.
+
+### Abort
+
+"Abort" the thread-safe function. This will cause all subsequent APIs associated
+with the thread-safe function except `Release()` to return `napi_closing` even
+before its reference count reaches zero. In particular, `BlockingCall` and
+`NonBlockingCall()` will return `napi_closing`, thus informing the threads that
+it is no longer possible to make asynchronous calls to the thread-safe function.
+This can be used as a criterion for terminating the thread. Upon receiving a
+return value of `napi_closing` from a thread-safe function call a thread must
+make no further use of the thread-safe function because it is no longer
+guaranteed to be allocated.
+
+```cpp
+napi_status Napi::ThreadSafeFunction::Abort()
+```
+
+Returns one of:
+- `napi_ok`: The thread-safe function has been successfully aborted.
+- `napi_invalid_arg`: The thread-safe function's thread-count is zero.
+- `napi_generic_failure`: A generic error occurred when attemping to abort
+the thread-safe function.
+
+### BlockingCall / NonBlockingCall
+
+Calls the Javascript function in either a blocking or non-blocking fashion.
+- `BlockingCall()`: the API blocks until space becomes available in the queue.
+  Will never block if the thread-safe function was created with a maximum queue
+  size of `0`.
+- `NonBlockingCall()`: will return `napi_queue_full` if the queue was full,
+  preventing data from being successfully added to the queue.
+
+There are several overloaded implementations of `BlockingCall()` and
+`NonBlockingCall()` for use with optional parameters: skip the optional
+parameter for that specific overload.
+
+**These specific function overloads should only be used on a `ThreadSafeFunction`
+created via `ThreadSafeFunction::New`.**
+
+```cpp
+napi_status Napi::ThreadSafeFunction::BlockingCall(DataType* data, Callback callback) const
+
+napi_status Napi::ThreadSafeFunction::NonBlockingCall(DataType* data, Callback callback) const
+```
+
+- `[optional] data`: Data to pass to `callback`.
+- `[optional] callback`: C++ function that is invoked on the main thread. The
+  callback receives the `ThreadSafeFunction`'s JavaScript callback function to
+  call as an `Napi::Function` in its parameters and the `DataType*` data pointer
+  (if provided). Must implement `void operator()(Napi::Env env, Function
+  jsCallback, DataType* data)`, skipping `data` if not provided. It is not
+  necessary to call into JavaScript via `MakeCallback()` because N-API runs
+  `callback` in a context appropriate for callbacks.
+
+**These specific function overloads should only be used on a `ThreadSafeFunction`
+created via `ThreadSafeFunction(napi_threadsafe_function)`.**
+
+```cpp
+napi_status Napi::ThreadSafeFunction::BlockingCall(void* data) const
+
+napi_status Napi::ThreadSafeFunction::NonBlockingCall(void* data) const
+```
+- `data`: Data to pass to `call_js_cb` specified when creating the thread-safe
+  function via `napi_create_threadsafe_function`.
+
+Returns one of:
+- `napi_ok`: The call was successfully added to the queue.
+- `napi_queue_full`: The queue was full when trying to call in a non-blocking
+  method.
+- `napi_closing`: The thread-safe function is aborted and cannot accept more
+  calls.
+- `napi_invalid_arg`: The thread-safe function is closed.
+- `napi_generic_failure`: A generic error occurred when attemping to add to the
+  queue.
+
+## Example
+
+```cpp
+#include <chrono>
+#include <thread>
+#include <napi.h>
+
+using namespace Napi;
+
+std::thread nativeThread;
+ThreadSafeFunction tsfn;
+
+Value Start( const CallbackInfo& info )
+{
+  Napi::Env env = info.Env();
+
+  if ( info.Length() < 2 )
+  {
+    throw TypeError::New( env, "Expected two arguments" );
+  }
+  else if ( !info[0].IsFunction() )
+  {
+    throw TypeError::New( env, "Expected first arg to be function" );
+  }
+  else if ( !info[1].IsNumber() )
+  {
+    throw TypeError::New( env, "Expected second arg to be number" );
+  }
+
+  int count = info[1].As<Number>().Int32Value();
+
+  // Create a ThreadSafeFunction
+  tsfn = ThreadSafeFunction::New(
+      env,
+      info[0].As<Function>(),  // JavaScript function called asynchronously
+      "Resource Name",         // Name
+      0,                       // Unlimited queue
+      1,                       // Only one thread will use this initially
+      []( Napi::Env ) {        // Finalizer used to clean threads up
+        nativeThread.join();
+      } );
+
+  // Create a native thread
+  nativeThread = std::thread( [count] {
+    auto callback = []( Napi::Env env, Function jsCallback, int* value ) {
+      // Transform native data into JS data, passing it to the provided 
+      // `jsCallback` -- the TSFN's JavaScript function.
+      jsCallback.Call( {Number::New( env, *value )} );
+      
+      // We're finished with the data.
+      delete value;
+    };
+
+    for ( int i = 0; i < count; i++ )
+    {
+      // Create new data
+      int* value = new int( clock() );
+
+      // Perform a blocking call
+      napi_status status = tsfn.BlockingCall( value, callback );
+      if ( status != napi_ok )
+      {
+        // Handle error
+        break;
+      }
+
+      std::this_thread::sleep_for( std::chrono::seconds( 1 ) );
+    }
+
+    // Release the thread-safe function
+    tsfn.Release();
+  } );
+
+  return Boolean::New(env, true);
+}
+
+Napi::Object Init( Napi::Env env, Object exports )
+{
+  exports.Set( "start", Function::New( env, Start ) );
+  return exports;
+}
+
+NODE_API_MODULE( clock, Init )
+```
+
+The above code can be used from JavaScript as follows:
+
+```js
+const { start } = require('bindings')('clock');
+
+start(function () {
+    console.log("JavaScript callback called with arguments", Array.from(arguments));
+}, 5);
+```
+
+When executed, the output will show the value of `clock()` five times at one
+second intervals:
+
+```
+JavaScript callback called with arguments [ 84745 ]
+JavaScript callback called with arguments [ 103211 ]
+JavaScript callback called with arguments [ 104516 ]
+JavaScript callback called with arguments [ 105104 ]
+JavaScript callback called with arguments [ 105691 ]
+```