nodejs / nodejs/node-addon-api

Enforce callback signatures with C++ Concepts

Open
#1,746 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

blocked SemVer-major
Dominant language
C++
Stars
2.4k
Forks
499
Avg merge
2d 11h
Merged PRs (30d)
2

Description

#1738 documented the required signature of the templated finalizer callback parameters as inline comment hints.

These are human-only annotations. The compiler does not enforce them, so a mismatched callable fails deep inside the template instantiation with an unhelpful error.

Once C++20 is the minimum supported standard, we should replace these hints with C++ Concepts that constrain the Finalizer/FinalizerType template parameters. This gives compiler-enforced contracts and clear diagnostics at the call site.

Finalizer candidates:

  • BasicEnv::PostFinalizer
  • Object::AddFinalizer
  • External::New
  • Buffer::New / Buffer::NewOrCopy
  • ThreadSafeFunction::New
  • TypedThreadSafeFunction::New

Callback candidates:

  • Function::New — the JS callback (Callable)
  • PropertyDescriptor::AccessorGetter / Setter
  • PropertyDescriptor::FunctionCallable
  • ThreadSafeFunction::BlockingCall / NonBlockingCallCallback
  • TypedThreadSafeFunction::BlockingCall / NonBlockingCallCallback
  • TypedThreadSafeFunction — the CallJs callback

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the inline signature annotations from #1738 and the listed template entry points, including BasicEnv::PostFinalizer, Object::AddFinalizer, External::New, Buffer::New, and the ThreadSafeFunction APIs. Determine the constraints needed for each Finalizer, Callable, Getter, Setter, and Callback candidate. Done means C++20 Concepts enforce the documented signatures and produce diagnostics at the call site.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
api
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.