-
Notifications
You must be signed in to change notification settings - Fork 29.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: mark callback-based fs API as legacy #37948
Conversation
-1 I think this just adds unnecessary confusion, especially when it's only being applied for a single core module. |
I disagree with it adding confusion. It is a legacy api that is unlikely to evolve significantly. Marking it as legacy makes that clearer. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🌶️
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is quite a position change, while I agree with the idea conceptually - this definitely need TSC eyes @nodejs/tsc
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
+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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do not agree to use the legacy classification for these.
@mcollina Could you give an explanation? |
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. |
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. |
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. |
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." |
I personally agree that it's too early to be marking individual APIs like this as legacy. |
From the discussion in the TSC, the general feeling was
Taking off the TSC agenda, please re-add if there is another question/feedback needed. |
Given the TSC discussion, closing this PR |
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