Adding WriteUtf8V2() and SetPrototypeV2() methods to support v8 14.3 #1004

agracio · 2025-10-17T23:00:28Z

Reason for this PR

Adding compatibility with v8 version 14.3

WriteUtf8V2() method

WriteUtf8V2() method was introduced in v8 13.4 and has a slightly different signature compared to WriteUtf8().
Deprecated WriteUtf8() method and associated enum were removed in v8 14.3.

enum WriteOptions {
    NO_OPTIONS = 0,
    HINT_MANY_WRITES_EXPECTED = 1,
    NO_NULL_TERMINATION = 2,
    PRESERVE_ONE_BYTE_NULL = 4,
    // Used by WriteUtf8 to replace orphan surrogate code units with the
    // unicode replacement character. Needs to be set to guarantee valid UTF-8
    // output.
    REPLACE_INVALID_UTF8 = 8
  };

V8_DEPRECATED("Use WriteUtf8V2 instead.")
int WriteUtf8(Isolate* isolate, char* buffer, int length = -1,
              int* nchars_ref = nullptr, int options = NO_OPTIONS) const;

struct WriteFlags {
    enum {
      kNone = 0,
      // Indicates that the output string should be null-terminated. In that
      // case, the output buffer must include sufficient space for the
      // additional null character.
      kNullTerminate = 1,
      // Used by WriteUtf8 to replace orphan surrogate code units with the
      // unicode replacement character. Needs to be set to guarantee valid UTF-8
      // output.
      kReplaceInvalidUtf8 = 2
    };
  };
size_t WriteUtf8V2(Isolate* isolate, char* buffer, size_t capacity,
                   int flags = WriteFlags::kNone,
                   size_t* processed_characters_return = nullptr) const;

SetPrototypeV2() method

SetPrototypeV2() method was introduced in v8 14.0 with same signature as SetPrototype().
Deprecated SetPrototype() method was removed in v8 14.3.

  V8_DEPRECATED(
      "V8 will stop providing access to hidden prototype (i.e. "
      "JSGlobalObject). Use SetPrototypeV2() instead. "
      "See http://crbug.com/333672197.")
  V8_WARN_UNUSED_RESULT Maybe<bool> SetPrototype(Local<Context> context,
                                                 Local<Value> prototype);

  V8_WARN_UNUSED_RESULT Maybe<bool> SetPrototypeV2(Local<Context> context,
                                                   Local<Value> prototype);

CI Changes

GitHub actions: added Node.js 25 and Windows arm64 runner.
AppVeyor: removed Node.js 16 - 24 from build since it is tested on GitHub.

CI Results

GitHub: https://github.com/agracio/nan/actions/runs/18606064924.
AppVeyor: https://ci.appveyor.com/project/agracio/nan/builds/52928365.

agracio · 2025-10-17T23:09:22Z

CI on Node.js 17.x was not failing in my branch: https://github.com/agracio/nan/actions/runs/18606064924.
It is most likely an issue with GitHub runner and should clear on re-run.

kkoopa · 2025-10-20T15:27:54Z

Thank you. This looks fine to me, still need to look at the the WriteUtf8 bit in some more detail, since it is fairly complicated, but presumably all should be good.

agracio · 2025-10-22T13:56:42Z

Found another issue with v8 14.3, this one is trickier to address.

v8 12.8 - 14.2

enum V8_DEPRECATE_SOON(
    "This enum is no longer used and will be removed in V8 12.9.")
    AccessControl {
      DEFAULT V8_ENUM_DEPRECATE_SOON("not used") = 0,
    };

v8 14.3

enum V8_DEPRECATED(
    "This enum is no longer used and will be removed in V8 14.3.")
    AccessControl {
      DEFAULT V8_ENUM_DEPRECATED("not used") = 0,
    };

I am not sure how it manages to have a deprecation notice in v8 14.3 while being marked for deprecation in the same version. However don't think it is worth taking any chances.

Context: initially I had another issue masking this warning and only saw it yesterday, v8 14.3 modules currently compile but with a warning.

This enum is used in nan.h SetAccessor() method making it much harder to remove.
Give me a day or so to figure it out or we can have it in separate PR, up to you.

agracio · 2025-10-22T14:49:46Z

@kkoopa apologies for direct ping, but could you confirm that nan is currently targeting Node.js version 8 and above and no longer officially support earlier versions in latest release? There are some inconsistences in SetAccessor() methods and one of them (only one for some reason) has a Node.js version dependency >=6 that I believe is no longer needed.

Unfortunately I do not think it would be possible to address AccessControl enum deprecation issue without having multiple SetAccessor() methods depending on v8 version.

Example of code inconsistency SetNativeDataProperty() is invoked for v8 >=12.5, but settings property is passed for v8 >11.

// ... SetAccessor() code
#if defined(V8_MAJOR_VERSION) && (V8_MAJOR_VERSION > 12 \
            || (V8_MAJOR_VERSION == 12 && defined(V8_MINOR_VERSION) \
            && V8_MINOR_VERSION >= 5))
  tpl->SetNativeDataProperty(
#else
  tpl->SetAccessor(
#endif
      name
    , getter_
    , setter_
    , obj
#if !defined(V8_MAJOR_VERSION) || V8_MAJOR_VERSION < 12
    , settings
#endif
    , attribute
  );

kkoopa · 2025-10-22T14:56:31Z

Multiple definitions but transparent to the user of the API? While it would be extra work, it would atill work nicely in that case. It is still all old versions being supported, but that could change if strictly necessary. I do not remember when Node 6.0 was released, but it was probably around 10 years ago.

…

On Wed, Oct 22, 2025, 17:50 agracio ***@***.***> wrote: *agracio* left a comment (nodejs/nan#1004) <#1004 (comment)> @kkoopa <https://github.com/kkoopa> apologies for direct ping, but could you confirm that nan is currently targeting Node.js version 8 and above and no longer officially support earlier versions in latest release? There are some inconsistences in SetAccessor() methods and one of them (only one for some reason) has a Node.js version dependency >=6 that I believe is no longer needed. Unfortunately I do not think it would be possible to address AccessControl enum deprecation issue without having multiple SetAccessor() methods depending on v8 version. — Reply to this email directly, view it on GitHub <#1004 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA7JXKKYVBI5J3VTG4AZOJ33Y6KSXAVCNFSM6AAAAACJQWTRKGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTIMZSG43DOMJRHE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

agracio · 2025-10-22T15:01:48Z

I would not say removing older versions is strictly necessary just makes the code considerably more convoluted. One of the changes I already pushed in this PR did make an assumption that 0.x versions are no longer supported.

kkoopa · 2025-10-22T15:08:17Z

I am out and about on my phone right now, so can't dig in much, only speculate. What does the git blame history say on those lines? My first guess is that it could be a slightly miss-hedged fix supposed to also cover some then current version of Electron.

…

On Wed, Oct 22, 2025, 18:02 agracio ***@***.***> wrote: *agracio* left a comment (nodejs/nan#1004) <#1004 (comment)> I would not say removing older versions is strictly necessary just makes the code considerably more convoluted. One of the changes I already pushed in this PR did make an assumption that 0.x versions are no longer supported. Node.js version 6 check is strange since it only done in one of 3 SetAccessor() methods. — Reply to this email directly, view it on GitHub <#1004 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA7JXKMZQEHQ3SVZKKZY5CT3Y6MA5AVCNFSM6AAAAACJQWTRKGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTIMZSHA2DCOBSGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

agracio · 2025-10-22T15:21:50Z

For this code it is part of PR #977.

// void SetAccessor()

#if defined(V8_MAJOR_VERSION) && (V8_MAJOR_VERSION > 12 \
            || (V8_MAJOR_VERSION == 12 && defined(V8_MINOR_VERSION) \
            && V8_MINOR_VERSION >= 5))
  tpl->SetNativeDataProperty(
#else
  tpl->SetAccessor(
#endif
      name
    , getter_
    , setter_
    , obj
#if !defined(V8_MAJOR_VERSION) || V8_MAJOR_VERSION < 12
    , settings
#endif
    , attribute
  );

However as part of the same PR the 3rd bool SetAccessor() has a different logic that appears to be more consistent.

// bool SetAccessor()

#if (NODE_MODULE_VERSION >= NODE_6_0_MODULE_VERSION)
#if defined(V8_MAJOR_VERSION) &&                                               \
    (V8_MAJOR_VERSION > 12 ||                                                  \
     (V8_MAJOR_VERSION == 12 && defined(V8_MINOR_VERSION) &&                   \
      V8_MINOR_VERSION >= 5))
  return obj->SetNativeDataProperty(
      GetCurrentContext()
    , name
    , getter_
    , setter_
    , dataobj
    , attribute).FromMaybe(false);
#else
  return obj->SetAccessor(
      GetCurrentContext()
    , name
    , getter_
    , setter_
    , dataobj
    , settings
    , attribute).FromMaybe(false);
#endif
#else
  return obj->SetAccessor(
      name
    , getter_
    , setter_
    , dataobj
    , settings
    , attribute);
#endif

For v8 14.3 and above SetAccessor() method signature will change because v8::AccessControl settings is deprecated and has to be removed, I am not sure how this is going to affect any modules that are rely on nan, will check my own modules.

Current signature of one of the methods:

inline void SetAccessor(
    v8::Local<v8::ObjectTemplate> tpl
  , v8::Local<v8::String> name
  , GetterCallback getter
  , SetterCallback setter = 0
  , v8::Local<v8::Value> data = v8::Local<v8::Value>()
  , v8::AccessControl settings = v8::DEFAULT // v8::AccessControl has to be removed
  , v8::PropertyAttribute attribute = v8::None)

kkoopa · 2025-10-22T15:31:27Z

Oh look, I myself am the culprit... Don't remember why it was done that way, best guess is just repeating a local ifdef pattern. As for remocing the defaulted argument, yes, rhe way I have solved that in the past is by adding a bunch of overloads to redo the effects of dedault aeguments. I blame part on C++ default arguments which are unfortunately broken beyond repair and should not be used in any well-designed API, for these and similar reasons.

…

On Wed, Oct 22, 2025, 18:22 agracio ***@***.***> wrote: *agracio* left a comment (nodejs/nan#1004) <#1004 (comment)> For this part of code it is part of PR #977 <#977>. // void SetAccessor() #if defined(V8_MAJOR_VERSION) && (V8_MAJOR_VERSION > 12 \ || (V8_MAJOR_VERSION == 12 && defined(V8_MINOR_VERSION) \ && V8_MINOR_VERSION >= 5)) tpl->SetNativeDataProperty( #else tpl->SetAccessor( #endif name , getter_ , setter_ , obj #if !defined(V8_MAJOR_VERSION) || V8_MAJOR_VERSION < 12 , settings #endif , attribute ); However as part of the same PR the 3rd bool SetAccessor() has a different logic that appears to be more consistent. // bool SetAccessor() #if (NODE_MODULE_VERSION >= NODE_6_0_MODULE_VERSION) #if defined(V8_MAJOR_VERSION) && \ (V8_MAJOR_VERSION > 12 || \ (V8_MAJOR_VERSION == 12 && defined(V8_MINOR_VERSION) && \ V8_MINOR_VERSION >= 5)) return obj->SetNativeDataProperty( GetCurrentContext() , name , getter_ , setter_ , dataobj , attribute).FromMaybe(false); #else return obj->SetAccessor( GetCurrentContext() , name , getter_ , setter_ , dataobj , settings , attribute).FromMaybe(false); #endif #else return obj->SetAccessor( name , getter_ , setter_ , dataobj , settings , attribute); #endif For v8 14.3 and above SetAccessor() method signature will change because v8::AccessControl settings is deprecated and has to be removed, I am not sure how this is going to affect any modules that are rely on nan, will check my own modules. Current signature of one of the methods: inline void SetAccessor( v8::Local<v8::ObjectTemplate> tpl , v8::Local<v8::String> name , GetterCallback getter , SetterCallback setter = 0 , v8::Local<v8::Value> data = v8::Local<v8::Value>() , v8::AccessControl settings = v8::DEFAULT // v8::AccessControl has to be removed , v8::PropertyAttribute attribute = v8::None) — Reply to this email directly, view it on GitHub <#1004 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA7JXKJYJQDY7WFHLHC4TJ33Y6OKLAVCNFSM6AAAAACJQWTRKGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTIMZSHE4DIOJYHE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

agracio · 2025-10-22T15:42:35Z

So should I proceed with changes to SetAccessor() signature for v8 >=14.3?
I do not see any possibility to keep method signature backward compatible.

kkoopa · 2025-10-22T15:50:03Z

Backwards compatible how? Having to change existing code is mostly fine (although the impact ahould be minimized) as long as it then builds correctly for all supported versions. If this cannot be done, I guess proceeding with the largest possible version coverage is the second best thing.

…

On Wed, Oct 22, 2025, 18:42 agracio ***@***.***> wrote: *agracio* left a comment (nodejs/nan#1004) <#1004 (comment)> So should I proceed with changes to SetAccessor() signature for v8 >=14.3? I do not see any possibility to keep method signature backward compatible. — Reply to this email directly, view it on GitHub <#1004 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA7JXKPX5J4FZVVGVKARAJL3Y6QYDAVCNFSM6AAAAACJQWTRKGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTIMZTGA3TKNJYGY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

agracio · 2025-10-22T16:00:43Z

Sorry maybe I have not explained the change properly.

Current nan SetAccessor() method parameters include parameter v8::AccessControl settings = v8::DEFAULT. When this enum is removed from v8 the parameter can no longer be part of the method signature.
Removing this parameter will change the signature of this method unless I am missing something and there is some kind of way to preserve it.
My proposal would be to create new SetAccessor() methods with new signatures for v8 >= 14.3 while keeping the old methods for older versions of v8.

nan SetAccessor() current signature

inline void SetAccessor(
    v8::Local<v8::ObjectTemplate> tpl
  , v8::Local<v8::String> name
  , GetterCallback getter
  , SetterCallback setter = 0
  , v8::Local<v8::Value> data = v8::Local<v8::Value>()
  , v8::AccessControl settings = v8::DEFAULT // v8::AccessControl has to be removed
  , v8::PropertyAttribute attribute = v8::None)

kkoopa · 2025-10-22T16:09:42Z

Is v8::AccessControl is still a plain enum? That makes it an int, so the enum itself could be replicated as enum Nan::AccessControl if needed. As for the default arguments, can't they be dealt with by adding a bunch of overloads with varying number of arguments instead? In general, int foo(int bar, int baz=0); can be replaced with int foo(int bar, int baz); int foo(int bar) { foo(bar, 0); }

…

On Wed, Oct 22, 2025, 19:01 agracio ***@***.***> wrote: *agracio* left a comment (nodejs/nan#1004) <#1004 (comment)> Sorry maybe I have not explained the change properly. Current *nan* SetAccessor() method parameters include parameter v8::AccessControl settings = v8::DEFAULT. When this enum is removed from v8 the parameter can no longer be part of the method signature. Removing this parameter will change the signature of this method unless I am missing something and there is some kind of way to preserve it. My proposal would be to create new SetAccessor() methods with new signatures for v8 >= 14.3 while keeping the old methods for older versions of v8. nan SetAccessor() current signature inline void SetAccessor( v8::Local<v8::ObjectTemplate> tpl , v8::Local<v8::String> name , GetterCallback getter , SetterCallback setter = 0 , v8::Local<v8::Value> data = v8::Local<v8::Value>() , v8::AccessControl settings = v8::DEFAULT // v8::AccessControl has to be removed , v8::PropertyAttribute attribute = v8::None) — Reply to this email directly, view it on GitHub <#1004 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA7JXKJJ4H7PM5VME5FMBEL3Y6S4BAVCNFSM6AAAAACJQWTRKGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTIMZTGE2DENZUHE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

agracio · 2025-10-22T16:26:31Z

Not sure that I am 100% following you but do you mean something along these lines?

#if defined(V8_MAJOR_VERSION) && (V8_MAJOR_VERSION > 14 \
            || (V8_MAJOR_VERSION == 14 && defined(V8_MINOR_VERSION) \
            && V8_MINOR_VERSION >= 3))

// v8::AccessControl settings = v8::DEFAULT parameter is not defined in signature
inline void SetAccessor(
    v8::Local<v8::ObjectTemplate> tpl
  , v8::Local<v8::String> name
  , GetterCallback getter
  , SetterCallback setter = 0
  , v8::Local<v8::Value> data = v8::Local<v8::Value>()
  , v8::PropertyAttribute attribute = v8::None) {

	SetAccessor(
		tpl,
		name,
		getter,
		setter,
		data, 
		0, // v8::AccessControl settings = v8::DEFAULT - v8::DEFAULT equals 0 according to the docs, 
		attribute);
}

#else

inline void SetAccessor(
    v8::Local<v8::ObjectTemplate> tpl
  , v8::Local<v8::String> name
  , GetterCallback getter
  , SetterCallback setter = 0
  , v8::Local<v8::Value> data = v8::Local<v8::Value>()
  , v8::AccessControl settings = v8::DEFAULT
  , v8::PropertyAttribute attribute = v8::None) {

  // original code
}

#endif

agracio · 2025-10-22T16:30:31Z

Nvm this does not work.

agracio added 6 commits July 10, 2025 18:59

using WriteUtf8V2() method for v8 version 13.4 and higher

9e1106a

using SetPrototypeV2() method for v8 version 14.0 and higher

982c0c8

using SetPrototypeV2() method for v8 version 14.0 and higher

d8337b0

adding Node.js 25 to CI

3716df9

updating WriteUtf8V2 method

ca2fd3c

splitting line to satisfy cpplint requirements

a44a998

agracio changed the title ~~Adding WriteUtf8V2() and SetPrototypeV2() methods~~ Adding WriteUtf8V2() and SetPrototypeV2() methods to support v8 14.3 Oct 18, 2025

Uh oh!

Adding WriteUtf8V2() and SetPrototypeV2() methods to support v8 14.3 #1004

Are you sure you want to change the base?

Adding WriteUtf8V2() and SetPrototypeV2() methods to support v8 14.3 #1004

Conversation

agracio commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reason for this PR

WriteUtf8V2() method

SetPrototypeV2() method

CI Changes

CI Results

Uh oh!

agracio commented Oct 17, 2025

Uh oh!

kkoopa commented Oct 20, 2025

Uh oh!

agracio commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

agracio commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kkoopa commented Oct 22, 2025 via email

Uh oh!

agracio commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kkoopa commented Oct 22, 2025 via email

Uh oh!

agracio commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kkoopa commented Oct 22, 2025 via email

Uh oh!

agracio commented Oct 22, 2025

Uh oh!

kkoopa commented Oct 22, 2025 via email

Uh oh!

agracio commented Oct 22, 2025

Uh oh!

kkoopa commented Oct 22, 2025 via email

Uh oh!

agracio commented Oct 22, 2025

Uh oh!

agracio commented Oct 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

agracio commented Oct 17, 2025 •

edited

Loading

agracio commented Oct 22, 2025 •

edited

Loading

agracio commented Oct 22, 2025 •

edited

Loading

agracio commented Oct 22, 2025 •

edited

Loading

agracio commented Oct 22, 2025 •

edited

Loading