nodejs / nodejs/TSC

Plan of process.binding() deprecation

Open
#1,482 18 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
693
Forks
142
PR merge metrics
No merged PRs in 30d

Description

This issue is not new but motivated by https://github.com/nodejs/node/pull/50687, which proposed to

  1. Ship the runtime deprecation in Node.js v22 --deprecated-process-binding on by default.
  2. --no-deprecated-process-binding becomes the default in Node.js v23
  3. process.binding(...) is removed entirely in Node.js v24, with the CLI option becoming a no-op

For background in 2021 the plan suggested in https://github.com/nodejs/node/pull/37485#pullrequestreview-600060802 and followed since https://github.com/nodejs/node/pull/37819 was:

  1. Do comprehensive research into what exact features ecosystem modules get through process.binding() (this isn't actually going to be a huge API surface!)
  2. Patch process.binding() so that it returns objects that cover those use cases, implemented in terms of public APIs
  3. Optionally, runtime-deprecate process.binding() only for the cases that users aren't commonly encountering
  4. Eventually, remove support for those cases specifically
  5. Leave it at that, don't runtime-deprecate process.binding() as a whole and leave the shim in place forever

I am opening this issue trying to slice the issue into different questions instead of bundling all together into just two different plans, in the hope of figuring out a better compromise.

There are several questions to the deprecation of process.binding():

  1. What's our end-goal when the deprecation reaches EOL?
    a) Delete process.binding completely so that when trying to invoke it, users get an error.
    b) A function that does no more than emitting a warning and returning empty objects. Users almost always get an error when they try to access an unsupported property, but if the code path is unused, e.g. only loading a process.binding() from the top-level but never actually hit the code path using anything from it, it would not fail.
    c) Leave a low-maintenance and harmless shim in place forever. Users get an error only when they try to use a specific unsupported property.
  2. How should the list of bindings (currently 20) be deprecated?
    a) Individually, based on how problematic they are/how difficult it is to provide alternatives
    b) Together at once
  3. Should the runtime deprecation start before or after alternatives/shims are completed
    a) We investigate the impact (e.g. through CITGM), develop and release alternatives on the way, monitor the changes in the impact, before deciding when it's ready to runtime-deprecate it (individually or all together).
    b) Runtime-deprecate it directly and mitigate the impact afterwards based on the bug reports/feature requests we receive.
  4. How should the warnings be rolled out when we start to emit warnings (there are a few more combination possibilities with 2)
    a) Emit runtime warnings unconditionally
    c) Non-node_module warnings first, node_module warnings in the next cycle

I think we as @nodejs/tsc need to take a deeper look into these questions and make some decisions before finishing a plan of the deprecation.

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

Start by reviewing the referenced Node.js pull requests and the questions about end-state behavior, binding rollout, alternatives, and warning timing. Done means the TSC has resolved these questions and documented an agreed deprecation plan; no implementation files or tests are named.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js
Domain
backend
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.