feat: add isSupported, isMaintenance, isSecurity, and modules

[wesleytodd]

Closes #19.

Adds new state flags and modules version. Also did a small refactor to simplify the logic in preparation for a refactor to make latestOfMajor and #39 work more correctly in the 1.0.0 branch after I rebase on top of this.

[ljharb]

What happens if node changes its release process and these start meaning different things? It might be better to make this a single string that people can check for, since they're all mutually exclusive

[wesleytodd]

What happens if node changes its release process and these start meaning different things?

That would necessitate a major version for this package. Now that you mention it, I think we should explicitly state that this package includes Node.js' release cadence and meaning as part of it's semver contract.

It might be better to make this a single string that people can check for, since they're all mutually exclusive

They are not mutually exclusive, right? This is the current results on this PR:

$ ./bin/nv ls supported | jq .version,.isMaintenance,.isSupported,.isLts
"20.19.5"
true
true
true
"22.19.0"
false
true
true
"24.8.0"
false
true
false

[ljharb]

ah, ok - so of those 3 then, 2 of them are constant over time, but "is supported" changes with time. Perhaps it should require providing a date?

[wesleytodd]

so of those 3 then, 2 of them are constant over time

Actually none of them are. There is 6 months after it enters isSupported before it goes isLTS. Per the docs:

After six months, odd-numbered releases (9, 11, etc.) become unsupported, and even-numbered releases (10, 12, etc.) move to Active LTS status and are ready for general use.

And then it stays isLTS when it enters isMaintenance, until .end and then all three turn off. So the only redundancy here is that if either isMaintenance or isLTS is true then isSupported must be true, but there is a 6 month period where only isSupported is true.

Perhaps it should require providing a date?

I think the use case is different for how you would use combinations of these and a date. For example, I often use the cli (like in that comment) just to run a quick check on specific things. For example when is the maintenance date:

$ ./bin/nv ls supported | jq .version,.isMaintenance,.maintenance,.end
"20.19.5"
true
"2024-10-22T00:00:00.000Z"
"2026-04-30T00:00:00.000Z"
"22.19.0"
false
"2025-10-21T00:00:00.000Z"
"2027-04-30T00:00:00.000Z"
"24.8.0"
false
"2026-10-20T00:00:00.000Z"
"2028-04-30T00:00:00.000Z"

So for this use case I am saying "what is the state now, and show me the dates as of now for when they plan to enter and leave maintenance". I think that --now (and the option by the same name) which defaults to Date.now() is the right API here, but let me know if maybe I also mis-understood your ask, because it feels sort of like I may have.

[ljharb]

But a specific version number is always, or never, LTS - v24.8.0 is never LTS, because it's the v24 release line, not that particular version, that enters LTS.

[wesleytodd]

Valid point, but the use case for this package is to get a specific version(s) based on certain qualities. It has no concept of "release lines", only "versions" and "aliases" (maybe better called "version sets" or something). This is why the aliases mean "head of line". But for these flags on specific versions, they really mean "are part of the set of an LTS line". Does that make sense?

So I could see this argument being a good one for changeing in 1.0.0 (aka not this PR since it would be breaking) such that:

1. only the HEAD of the major line which is LTS is set .isLTS = true
2. or, we change to an api that differentiates between "lines", "versions", and "sets"

Either way, that is not how this was originally written and my hope was to land this change on the pre-1.0 so that we could at least call the this "feature complete" for what we know about before we go 1.0. Are you alright with this, and then engaging on an api change to address this for 1.x?

[ljharb]

You can land whatever you like :-) i'm not blocking. But, for a more concrete example: v22.10.0 is not LTS and never will be. v22.11.0 is LTS, as is v22.19.0, and both forever will be. All v22 versions are "supported" until Jod goes EOL, and soon (October or November, I think?) all v22 versions will be supported, LTS, and maintenance.

I don't think it's correct to use these terms if the above does not hold, and the same applies to all post-v3 versions.

iow, "LTS" is a fixed status for a given version number; "maintenance" and "supported" (ie, "active LTS") are time-based properties.

[wesleytodd]

Ah, ok thanks for the example. Yeah, good point and I think this is what we should land for 1.x. Again, only because that would be a breaking change and despite it being pre-1.0 I still am trying not to ship breaking changes if possible. I guess basically with this in mind we are saying that the isLts flag on the returned version was always incorrect since it was based on the date and not on the lts key from https://nodejs.org/dist/index.json.

I for sure need to refactor the logic that sorts things into the aliases anyway, so if you could maybe give me a ✅ on this one I can then move on to fixing this for the 1.x branch?