Adding new `Nan::TryEncode()` wrapper for `node::TryEncode()` #1005

agracio · 2025-12-02T15:49:04Z

`Nan::Encode` and `Nan:TryEncode()` changes

Added new Nan:TryEncode() method for Node version 24 and higher
Added deprecation warning to Nan::Encode for Node version 24 and higher
Changed string_bytes.md to reflect changes and rebuilt README

Miscellaneous

Added missing NODE_MODULE_VERSION definition for all Node version to maintain consistency
Changed macos-13 to macos-15-intel to avoid deprecation

AppVeyor tests for older versions of nan that are currently disabled in this repo (https://ci.appveyor.com/project/agracio/nan)

…:TryEncode()`

kkoopa · 2025-12-02T16:16:28Z

I took a quick check and it looks alright, this is fine to merge as-is. However, I had a thought. Could not the old functions relying on the deprecated API be rewritten to use the new TryEncode where available, just by tacking on a ToLocalChecked() to get the old behavior? That way all deprecation warnings could be avoided. Like you pointed out, there does not seem to be a way of deprecating the old Nan::Encode functions, because of compatibility.

agracio · 2025-12-02T16:21:30Z

I think only Node version 24+ can use it but yes I could rewrite it to use TryEncode() only for those versions. Not sure what you mean by suggesting to use ToLocalChecked() since TryEncode() returns the same type of variable unless I misunderstand what you trying to do.

kkoopa · 2025-12-02T16:27:59Z

I was referring to a comment in the node.js commit that introduced the new MaybeEncode. Somewhere there it said that the old Encode did a ToLocalChecked at some point which would then cause an error. Conditioning Nan::Encode on NODE_VERSION >= 24, one that forwards to Nan::MaybeEncode and another with the current one sounds perfect.

…

On Tue, Dec 2, 2025, 18:21 agracio ***@***.***> wrote: *agracio* left a comment (nodejs/nan#1005) <#1005 (comment)> I think only Node version 24+ can use it but yes I could rewrite it to use TryEncode() only for those versions. Not sure what you mean by suggesting to use ToLocalChecked() since TryEncode() returns the same type of variable unless I misunderstand what you trying to do. — Reply to this email directly, view it on GitHub <#1005 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA7JXKKZIRE4BPD7HM4FIXT37W4B7AVCNFSM6AAAAACNZ6ELC6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMMBSHA4TENZYGY> . You are receiving this because you commented.Message ID: ***@***.***>

agracio · 2025-12-02T16:32:54Z

I made a mistake in code Nan::TryEncode() should return MaybeLocal<v8::Value>.

agracio · 2025-12-02T17:04:13Z

Question - since it's a direct call to node::TryEncode() should it return v8::MaybeLocal<> instead of Nan::MaybeLocal<>

kkoopa · 2025-12-02T17:15:33Z

Nan::MaybeLocal is just an alias for v8::MaybeLocal in all versions that have the Maybe-stuff. https://github.com/nodejs/nan/blob/4f2ac29d7f08a8f10b7dfb7f9e7f1b05932970dc/nan_maybe_43_inl.h#L13 I'd go with Nan::MaybeLocal

…

On Tue, Dec 2, 2025, 19:04 agracio ***@***.***> wrote: *agracio* left a comment (nodejs/nan#1005) <#1005 (comment)> Question - since it's a direct call to node::TryEncode() should it return v8::MaybeLocal<> instead of Nan::MaybeLocal<> — Reply to this email directly, view it on GitHub <#1005 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA7JXKJV6FC6K34WVNH3UL337XBCJAVCNFSM6AAAAACNZ6ELC6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMMBTGA4TKMRVGQ> . You are receiving this because you commented.Message ID: ***@***.***>

agracio · 2025-12-02T18:17:51Z

Have another question and also want to make clear that C++ is not really a language I am too familiar with.

I was not able to reuse or call TryEncode() method that I have added in Encode() and ended up with duplicated code.
Currently it looks like this and I am still not sure if it's completely correct.

#if NODE_MAJOR_VERSION >= 24
inline MaybeLocal<v8::Value> TryEncode(
    const char *buf, size_t len, enum Encoding encoding = BINARY) {
  v8::Isolate* isolate = v8::Isolate::GetCurrent();
  node::encoding node_enc = static_cast<node::encoding>(encoding);

  if (encoding == UCS2) {
    return node::TryEncode(
        isolate
      , reinterpret_cast<const uint16_t *>(buf)
      , len / 2);
  } else {
    return node::TryEncode(
        isolate
      , reinterpret_cast<const char *>(buf)
      , len
      , node_enc);
  }
}

NAN_DEPRECATED inline v8::Local<v8::Value> Encode(
    const void *buf, size_t len, enum Encoding encoding = BINARY){
  v8::Isolate* isolate = v8::Isolate::GetCurrent();
  node::encoding node_enc = static_cast<node::encoding>(encoding);

  if (encoding == UCS2) {
    return node::TryEncode(
        isolate
      , reinterpret_cast<const uint16_t *>(buf)
      , len / 2).ToLocalChecked();
  } else {
    return node::TryEncode(
        isolate
      , reinterpret_cast<const char *>(buf)
      , len
      , node_enc).ToLocalChecked();
  }
}

#else
...
#endif

What am I missing?

kkoopa · 2025-12-02T18:56:36Z

Your TryEncode takes a char *, the other takes a void *. In C++, unlike C, void pointers are not implicitly convertible to other pointers, so an explicit cast is required. I got it to compile like this:

diff --git a/nan.h b/nan.h
index fdfce0a..8d2948d 100644
--- a/nan.h
+++ b/nan.h
@@ -2420,7 +2420,7 @@ enum Encoding {ASCII, UTF8, BASE64, UCS2, BINARY, HEX, BUFFER};
 #endif
 
 #if NODE_MAJOR_VERSION >= 24
-inline v8::Local<v8::Value> TryEncode(
+inline v8::MaybeLocal<v8::Value> TryEncode(
     const char *buf, size_t len, enum Encoding encoding = BINARY) {
   v8::Isolate* isolate = v8::Isolate::GetCurrent();
   node::encoding node_enc = static_cast<node::encoding>(encoding);
@@ -2429,13 +2429,13 @@ inline v8::Local<v8::Value> TryEncode(
     return node::TryEncode(
         isolate
       , reinterpret_cast<const uint16_t *>(buf)
-      , len / 2).FromMaybe(v8::Local<v8::Value>());
+      , len / 2);
   } else {
     return node::TryEncode(
         isolate
       , reinterpret_cast<const char *>(buf)
       , len
-      , node_enc).FromMaybe(v8::Local<v8::Value>());
+      , node_enc);
   }
 }
 #endif
@@ -2449,21 +2449,7 @@ inline v8::Local<v8::Value> Encode(
 #endif
 {
 #if (NODE_MODULE_VERSION >= ATOM_0_21_MODULE_VERSION)
-  v8::Isolate* isolate = v8::Isolate::GetCurrent();
-  node::encoding node_enc = static_cast<node::encoding>(encoding);
-
-  if (encoding == UCS2) {
-    return node::Encode(
-        isolate
-      , reinterpret_cast<const uint16_t *>(buf)
-      , len / 2);
-  } else {
-    return node::Encode(
-        isolate
-      , reinterpret_cast<const char *>(buf)
-      , len
-      , node_enc);
-  }
+  return Nan::TryEncode(static_cast<const char *>(buf), len, encoding).ToLocalChecked();
 #elif (NODE_MODULE_VERSION > NODE_0_10_MODULE_VERSION)
   return node::Encode(
       v8::Isolate::GetCurrent()

kkoopa · 2025-12-02T19:00:13Z

I did not do the necessary ifdeffing, so it is obviously not right, but it compiles.

agracio · 2025-12-02T19:08:58Z

I do not know how I missed that and actually no idea where void came from in the first place. I copy/pasted Encode() and changed it to TryEncode(). 🤦‍♂️ 🤦‍♂️🤦‍♂️

Thank you!

kkoopa · 2025-12-02T19:12:33Z

I was wondering about the origin of the void pointer myself. The old node API also uses char pointers in the latest version. Either it used to be a void pointer a long time ago, or I changed it to a void pointer, because the data is not necessarily a char array at all (e.g. utf-16) making a char pointer semantically wrong.

agracio · 2025-12-02T19:25:18Z

In my code I marked Encode() as NAN_DEPRECATED for Node >=24 to make users aware of deprecation, is it not something you want to implement?

agracio · 2025-12-02T19:38:55Z

I was wondering about the origin of the void pointer myself. The old node API also uses char pointers in the latest version. Either it used to be a void pointer a long time ago, or I changed it to a void pointer, because the data is not necessarily a char array at all (e.g. utf-16) making a char pointer semantically wrong.

Your second assumption is correct, tests do not build with a non void parameter.

kkoopa · 2025-12-02T19:39:27Z

Yes and no. I care about the NAN API being consistent across versions. Since versions prior to Node 24 cannot achieve identical behavior to later versions, due to node::TryEncode not being available and the aforementioned ToLocalChecked in node::Encode not making it possible to wrap its output in case the option is empty, the only way to have it work everywhere is by using Nan::Encode. So, while I would like to deprecate Nan::Encode in favor of Nan::TryEncode, I do not see a way of doing it right without too much effort for a niche problem (replicating the entirety of node::TryEncode). Everyone was fine with the old variant for some ten years. Perhaps a note in the documentation about whether to use one or the other is sufficient.

…

On Tue, Dec 2, 2025, 21:25 agracio ***@***.***> wrote: *agracio* left a comment (nodejs/nan#1005) <#1005 (comment)> In my code I marked Encode() as NAN_DEPRECATED for Node >=24 to make users aware of deprecation, is it not something you want to implement? — Reply to this email directly, view it on GitHub <#1005 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA7JXKPVBCYKFRV4X5XRESL37XRTHAVCNFSM6AAAAACNZ6ELC6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMMBTGYZTCMZWHA> . You are receiving this because you commented.Message ID: ***@***.***>

agracio · 2025-12-02T19:44:04Z

I can do it either way, the only issue I see is that if it is not marked as deprecated and Node native warning is suppressed many users will not even be aware of the change and that they might want to look at it. Although flooding some users with warning is also not ideal.

…oved deprecation for `Encode()` in Node >= 24

agracio · 2025-12-02T20:21:35Z

Changes complete

kkoopa · 2025-12-03T13:04:10Z

Wonderful. Thank you very much for your effort. I will push a new release.

agracio added 4 commits December 2, 2025 13:56

Adding new method Nan::TryEncode() to serve as a wrapper for `Node:…

94cccca

…:TryEncode()`

Updating docs for new method Nan::TryEncode()

1dad900

updating #if condition

290ae80

updating macOS x64 ci runner

203eeba

agracio mentioned this pull request Dec 2, 2025

nan deprecation warnings with Node.js 24 #998

Closed

agracio added 2 commits December 2, 2025 19:50

changed TryEncode() signature to be consistent with Encode(), rem…

0c3d86d

…oved deprecation for `Encode()` in Node >= 24

cpplint fixes

c0f5157

kkoopa merged commit fd5ff3f into nodejs:main Dec 3, 2025
17 checks passed

Uh oh!

Adding new Nan::TryEncode() wrapper for node::TryEncode() #1005

Adding new Nan::TryEncode() wrapper for node::TryEncode() #1005

Uh oh!

Conversation

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

Uh oh!

Nan::Encode and Nan:TryEncode() changes

Miscellaneous

Uh oh!

kkoopa commented Dec 2, 2025

Uh oh!

agracio commented Dec 2, 2025

Uh oh!

kkoopa commented Dec 2, 2025 via email

Uh oh!

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

Uh oh!

Uh oh!

agracio commented Dec 2, 2025

Uh oh!

kkoopa commented Dec 2, 2025 via email

Uh oh!

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

Uh oh!

Uh oh!

kkoopa commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kkoopa commented Dec 2, 2025

Uh oh!

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

Uh oh!

Uh oh!

kkoopa commented Dec 2, 2025

Uh oh!

agracio commented Dec 2, 2025

Uh oh!

agracio commented Dec 2, 2025

Uh oh!

kkoopa commented Dec 2, 2025 via email

Uh oh!

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

Uh oh!

Uh oh!

agracio commented Dec 2, 2025

Uh oh!

Uh oh!

kkoopa commented Dec 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Adding new `Nan::TryEncode()` wrapper for `node::TryEncode()` #1005

Adding new `Nan::TryEncode()` wrapper for `node::TryEncode()` #1005

agracio commented Dec 2, 2025 •

edited

Loading

`Nan::Encode` and `Nan:TryEncode()` changes

agracio commented Dec 2, 2025 •

edited

Loading

agracio commented Dec 2, 2025 •

edited

Loading

kkoopa commented Dec 2, 2025 •

edited

Loading

agracio commented Dec 2, 2025 •

edited

Loading

agracio commented Dec 2, 2025 •

edited

Loading