Node-API Part-1: Introduction to Node-API & Wrapping Native C++ Objects in ArkTS on HarmonyOSNext

{
  "apiType": "stageMode",
  "buildOption": {
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt",
      "arguments": "",
      "cppFlags": "",
      "abiFilters": [
        "arm64-v8a",
        "x86_64"
      ]
    }
  },
  "buildOptionSet": [
    {
      "name": "release",
      "arkOptions": {
        "obfuscation": {
          "ruleOptions": {
            "enable": false,
            "files": [
              "./obfuscation-rules.txt"
            ]
          }
        }
      },
      "nativeLib": {
        "debugSymbol": {
          "strip": true,
          "exclude": []
        }
      }
    },
  ],
  "targets": [
    {
      "name": "default"
    },
    {
      "name": "ohosTest",
    }
  ]
}

export class MyObject {
  constructor(arg: number);
  plusOne: () => number;

  public get value();
  public set value(newVal: number);
}

// napi_init.cpp

#include "napi/native_api.h"
#include "hilog/log.h"

// A native C++ class that will be wrapped into an ArkTS (JavaScript) object
class MyObject {
 public:
  // Initializes the class and exports it to ArkTS
  static napi_value Init(napi_env env, napi_value exports);
  // Destructor called when the native object is garbage collected
  static void Destructor(napi_env env, void* nativeObject, void* finalize_hint);

 private:
  // Constructor and Destructor
  explicit MyObject(double value_ = 0);
  ~MyObject();

  // Class methods accessible from ArkTS
  static napi_value New(napi_env env, napi_callback_info info);
  static napi_value GetValue(napi_env env, napi_callback_info info);
  static napi_value SetValue(napi_env env, napi_callback_info info);
  static napi_value PlusOne(napi_env env, napi_callback_info info);

  // Member variables
  double value_;           // internal numeric value
  napi_env env_;           // N-API environment pointer
  napi_ref wrapper_;       // Reference to the wrapped JS object
};

// Global reference to the constructor function, used for instance creation
static thread_local napi_ref g_ref = nullptr;

// Constructor implementation
MyObject::MyObject(double value)
    : value_(value), env_(nullptr), wrapper_(nullptr) {}

// Destructor implementation
MyObject::~MyObject()
{
  napi_delete_reference(env_, wrapper_);
}

// This function is called when the JS object is garbage collected
void MyObject::Destructor(napi_env env, void* nativeObject, [[maybe_unused]] void* finalize_hint)
{
  OH_LOG_INFO(LOG_APP, "MyObject::Destructor called");
  delete reinterpret_cast<MyObject*>(nativeObject);
}

// Initializes and exports the MyObject class to the ArkTS runtime
napi_value MyObject::Init(napi_env env, napi_value exports)
{
  // Define class methods and properties exposed to ArkTS
  napi_property_descriptor properties[] = {
      { "value", 0, 0, GetValue, SetValue, 0, napi_default, 0 },
      { "plusOne", nullptr, PlusOne, nullptr, nullptr, nullptr, napi_default, nullptr }
  };

  napi_value cons;
  napi_define_class(env, "MyObject", NAPI_AUTO_LENGTH, New, nullptr, 2, properties, &cons);

  // Store a reference to the constructor for later use
  napi_create_reference(env, cons, 1, &g_ref);

  // Export the class as a property of the module
  napi_set_named_property(env, exports, "MyObject", cons);
  return exports;
}

// Export function that will be called when the module is loaded
EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports)
{
    MyObject::Init(env, exports);
    return exports;
}
EXTERN_C_END

// Native module definition
static napi_module nativeModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "entry",
    .nm_priv = nullptr,
    .reserved = { 0 },
};

// This function is automatically called when the native module is loaded
extern "C" __attribute__((constructor)) void RegisterObjectWrapModule()
{
    napi_module_register(&nativeModule);
}

// Class constructor callable from ArkTS
napi_value MyObject::New(napi_env env, napi_callback_info info)
{
  OH_LOG_INFO(LOG_APP, "MyObject::New called");

  napi_value newTarget;
  napi_get_new_target(env, info, &newTarget);

  if (newTarget != nullptr) {
    // Called using `new MyObject(...)`
    size_t argc = 1;
    napi_value args[1];
    napi_value jsThis;
    napi_get_cb_info(env, info, &argc, args, &jsThis, nullptr);

    double value = 0.0;
    napi_valuetype valuetype;
    napi_typeof(env, args[0], &valuetype);
    if (valuetype != napi_undefined) {
      napi_get_value_double(env, args[0], &value);
    }

    // Create the native object
    MyObject* obj = new MyObject(value);
    obj->env_ = env;

    // Wrap native C++ object with JS object
    napi_status status = napi_wrap(env,
                                   jsThis,
                                   reinterpret_cast<void*>(obj),
                                   MyObject::Destructor,
                                   nullptr,
                                   &obj->wrapper_);

    // Check for wrap failure
    if (status != napi_ok) {
      OH_LOG_INFO(LOG_APP, "Failed to bind native object to js object, return code: %{public}d", status);
      delete obj;
      return jsThis;
    }

    // Convert reference to weak to avoid memory leaks
    uint32_t refCount = 0;
    napi_reference_unref(env, obj->wrapper_, &refCount);

    return jsThis;
  } else {
    // Called as a function: `MyObject(...)` instead of `new MyObject(...)`
    size_t argc = 1;
    napi_value args[1];
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);

    // Create a new instance using the constructor reference
    napi_value cons;
    napi_get_reference_value(env, g_ref, &cons);
    napi_value instance;
    napi_new_instance(env, cons, argc, args, &instance);

    return instance;
  }
}

// Getter: Returns the value_ field to ArkTS
napi_value MyObject::GetValue(napi_env env, napi_callback_info info)
{
  OH_LOG_INFO(LOG_APP, "MyObject::GetValue called");

  napi_value jsThis;
  napi_get_cb_info(env, info, nullptr, nullptr, &jsThis, nullptr);

  // Unwrap native object from JS
  MyObject* obj;
  napi_unwrap(env, jsThis, reinterpret_cast<void**>(&obj));

  // Create JS number from native value
  napi_value num;
  napi_create_double(env, obj->value_, &num);

  return num;
}

// Setter: Updates the native value_ field from ArkTS
napi_value MyObject::SetValue(napi_env env, napi_callback_info info)
{
  OH_LOG_INFO(LOG_APP, "MyObject::SetValue called");

  size_t argc = 1;
  napi_value value;
  napi_value jsThis;

  napi_get_cb_info(env, info, &argc, &value, &jsThis, nullptr);

  // Unwrap native object from JS
  MyObject* obj;
  napi_unwrap(env, jsThis, reinterpret_cast<void**>(&obj));

  // Set internal value_
  napi_get_value_double(env, value, &obj->value_);

  return nullptr;
}

// Adds 1 to the internal value_ and returns it
napi_value MyObject::PlusOne(napi_env env, napi_callback_info info)
{
  OH_LOG_INFO(LOG_APP, "MyObject::PlusOne called");

  napi_value jsThis;
  napi_get_cb_info(env, info, nullptr, nullptr, &jsThis, nullptr);

  // Unwrap native object from JS
  MyObject* obj;
  napi_unwrap(env, jsThis, reinterpret_cast<void**>(&obj));

  // Increment value_ and return
  obj->value_ += 1;
  napi_value num;
  napi_create_double(env, obj->value_, &num);

  return num;
}

# the minimum version of CMake.
cmake_minimum_required(VERSION 3.5.0)
project(NDKBasics)

set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})

if(DEFINED PACKAGE_FIND_FILE)
    include(${PACKAGE_FIND_FILE})
endif()

include_directories(${NATIVERENDER_ROOT_PATH}
                    ${NATIVERENDER_ROOT_PATH}/include)

add_definitions("-DLOG_DOMAIN=0x0000")
add_definitions("-DLOG_TAG=\"testTag\"")

add_library(entry SHARED napi_init.cpp)
target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so)

import hilog from '@ohos.hilog';
import { MyObject } from 'libentry.so';

let object: MyObject = new MyObject(0);
object.value = 1023;

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {

            hilog.info(0x0000, 'testTag', 'MyObject value after set: %{public}d', object.value);
            hilog.info(0x0000, 'testTag', 'MyObject plusOne: %{public}d', object.plusOne());

            this.message = object.value.toString() + " " + object.plusOne()
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}