Remove legacy status from querystring

[mcollina]

The node:querystring module is significantly faster than URLSearchParams (ref. https://github.com/anonrig/fast-querystring). Given that querystring is marked as legacy, quite a few people are continuosly opening issues on some modules I maintain asking to replace querystring with URLSearchParams... however, we really can't as there is a significant performance drop.

Therefore... can we remove the legacy status?

[mcollina]

cc @nodejs/tsc

[RaisinTen]

Given that querystring is marked as legacy, quite a few people are continuosly opening issues on some modules I maintain asking to replace querystring with URLSearchParams

Why? Only new code should use URLSearchParams (our docs already say that) -

node/doc/api/querystring.md

Lines 18 to 19 in 6475a87

	The `querystring` API is considered Legacy. While it is still maintained,
	new code should use the {URLSearchParams} API instead.

. It's fine if existing code keeps using the legacy APIs.

[mcollina]

I do not know why it is a problem for folks, but it happens a few times a month and is quite annoying.

[RaisinTen]

I wonder if it's more of a visibility issue. Maybe we should highlight this statement in the docs or rephrase it to better express that it's okay to use legacy APIs?

[Trott]

I do not know why it is a problem for folks, but it happens a few times a month and is quite annoying.

@mcollina Can I open PRs on your projects adding code comments explaining that querystring is being used because it is more performant than URLSearchParams and to please not open PRs trying to change it unless benchmarks can show equivalent or better performance? 😀

I wonder if it's more of a visibility issue. Maybe we should highlight this statement in the docs or rephrase it to better express that it's okay to use legacy APIs?

@RaisinTen I'm not opposed to trying that, but my inclination is to remove the Legacy status but leave a statement explaining that people should consider using URLSearchParams instead if they want to use something identical to browser APIs (or whatever the reason is--clearly performance is not one of them).

I've never liked the Legacy status, although I understand why it was created.

[mcollina]

This is just a few days ago: nodejs/undici#1682.
Then fastify/fastify#4239, fastify/fastify#3645.

Possibly a few more.

My take is that we are not doing a good service to the community: if I didn't know URLSearchParams was significantly slower then querystring, I would have caved in. There is no good reason to switch.

(This is not the same of new URL(), which is slower than url.parse() but it's correct and secure).

(Note: TypeScript signals all legacy marked APIs as @deprecated.

[Trott]

Note: TypeScript signals all legacy marked APIs as @deprecated.

Another reason to get rid of Legacy entirely. The distinction between Legacy and Deprecated has never been clear. (Supposedly, Legacy is "we don't plan to remove it ever" but that's also true of Deprecated APIs like sys and domain. So the existence of Legacy is more confusing than enlightening in my opinion.)

[gireeshpunathil]

from the linked issues, it is evident that folks misunderstand legacy to be same as deprecated, or moving towards deprecated.

Potential options are:

• disambiguate legacy and deprecated
• remove legacy entirely, and make the incumbent APIs some sub-type of deprecated

[Trott]

#44912

[Trott]

Potential options are:

• disambiguate legacy and deprecated
• remove legacy entirely, and make the incumbent APIs some sub-type of deprecated

I think, when possible, it is better to have fewer categories that are intuitively understood. In that regard, I think we should remove Legacy. Some of the Legacy APIs (notably url.parse()) can be doc-deprecated. Others can be returned to Stable with a note explaining when to use something else instead. (Thats' the approach I took in #44912.)

[mcollina]

I'd be ok in doc-deprecating url.parse().

[GeoffreyBooth]

I wonder how much of this is TypeScript’s treating “legacy” as deprecated. We could reach out to the @types maintainers to ask them to revise that.

Ultimately we do need a status that means “not getting removed, but closed to further development.” Most of CommonJS falls under that category. If not “legacy,” perhaps “frozen”?

[Trott]

Ultimately we do need a status that means “not getting removed, but closed to further development.”

I mean, the proper term for that is "deprecated". It's unfortunate, though, that "deprecated" for most people means "will be removed". I don't know how/when that shift happened, but it's unfortunate, because "deprecated" is a useful term made less useful that way.

We could go with something very explicit: "Usage discouraged." But that's literally the English language definition of "deprecated" so I'm not sure that won't result in more confusion.

Ultimately, I question whether we really need a term for "not getting removed, but closed to further development".