doc: mark callback-based fs API as legacy

[aduh95]

A few folks have voiced support for bringing new features only to the Promise-based and sync APIs of fs in #37944. This PR marks the callback-API as "Legacy" to reflect this position.

@nodejs/fs wdyt?

---

For reference, "Legacy" status is defined by

node/doc/api/documentation.md

Lines 42 to 44 in ed6e8f6

	> Stability: 3 - Legacy. The feature is no longer recommended for use. While it
	> likely will not be removed, and is still covered by semantic-versioning
	> guarantees, use of the feature should be avoided.

[mscdex]

-1 I think this just adds unnecessary confusion, especially when it's only being applied for a single core module.

[jasnell]

I disagree with it adding confusion. It is a legacy api that is unlikely to evolve significantly. Marking it as legacy makes that clearer.

[addaleax]

🌶️

[benjamingr]

This is quite a position change, while I agree with the idea conceptually - this definitely need TSC eyes @nodejs/tsc

[ChALkeR]

+1 because new code should prefer using the promises based API instead of callback API.

Callback API is often not even used directly but is wrapped into something, also requires additional code or/and more complex structure which is more likely to contain bugs.

This change might give an (small) incentive to use the cleaner (as in: less prone to issues) API instead.

[mcollina]

I do not agree to use the legacy classification for these.

[addaleax]

@mcollina Could you give an explanation?

[mcollina]

I think that mixing errorbacks and promises is a source of bugs, crashes and leaks.

Marking fs errobacks methods as legacy is encouraging such mixed use in all those cases were a promise equivalent is not available.

I agree with the intent but we are not ready as there are still quite a few APIs that lack a promise equivalent both in Node.js and the ecosystem. As an example, all of our network stack is not compatible.

I think we should aim to mark all of the errorback methods as legacy in one single step.

[mscdex]

Additionally, with all of the issues (that we haven't encountered with callbacks) I've seen surrounding Promises (e.g. behavior with unhandled, unresolved, etc.) and with Promises able to incur measurable overhead compared to callbacks (last I saw), I think it's a bad idea to label these as legacy.

[benjamingr]

@mscdex

Additionally, with all of the issues (that we haven't encountered with callbacks) I've seen surrounding Promises

These issues have largely have already been worked on and have been solved. I see Matteo's point regarding networking though.

[mscdex]

These issues have largely have already been worked on and have been solved. I see Matteo's point regarding networking though.

My point is until Promises and their behaviors have been stable for a substantial amount of time, we shouldn't be promoting them as the official/recommended/non-legacy/etc. mechanism for async APIs.

[tniessen]

For reference, "Legacy" status is defined by

node/doc/api/documentation.md

Lines 42 to 44 in ed6e8f6

	> Stability: 3 - Legacy. The feature is no longer recommended for use. While it
	> likely will not be removed, and is still covered by semantic-versioning
	> guarantees, use of the feature should be avoided.

Personally, I think the disagreement here boils down to the interpretation of the definition.

The definition says "The feature is no longer recommended for use."

But, as @mcollina said, in this case, it is probably closer to "The feature is no longer recommended for use... unless you are using callbacks in related parts of your application anyway, as to avoid mixing callbacks and Promises."

[mhdawson]

I personally agree that it's too early to be marking individual APIs like this as legacy.

[Flarna]

Besides network APIs there is also crypto which uses callbacks only and a few new were added recently (refs: #37500).
How should we deal with PRs like #37500 in future if callbacks are considered legacy?

[mhdawson]

From the discussion in the TSC, the general feeling was

1. It's too early to mark them as legacy
2. A good alternative would be to update docs to discourage their use/explain the issue and how the promises based APIs solve them.

Taking off the TSC agenda, please re-add if there is another question/feedback needed.

[jasnell]

Given the TSC discussion, closing this PR