Change Request: Spin out lib/unsupported-features as a standalone package?

[JoshuaKGoldberg]

eslint-plugin-n version

v17.23.2

What problem do you want to solve?

lib/unsupported-features is a treasure trove of info about which Node.js features were added in which Node.js versions. I'd like to use it in other tools that check for Node.js feature <> version compatibility. For example, the experimental flint-fyi/flint#932. And I'd be surprised if other linters such as Biome and Oxlint don't also end up including equivalents to n/no-unsupported-features/*.

But, lib/unsupported-features right now seems to be an internal implementation detail of the eslint-plugin-n package. There are no docs for it and the package doesn't export it in package.json or lib/index.js. There's no good, sanctioned way for us to intake that data that I can find.

What do you think is the correct solution?

Would the eslint-plugin-n team be open to publishing the data under lib/unsupported-features as a standalone package? Like a node-feature-support package or some similar name?

I imagine the two most common solutions to do so would be either:

• Switching this repository to a monorepo
• Creating a separate repository for the new package

Participation

• I am willing to submit a pull request for this change.

Additional comments

I'd of course be happy to help maintain this if you're up for it and would find my help useful.

If this request is declined (totally understandable) I'll likely end up making my own library for this.

Thanks! ❤️

[scagood]

I love this idea.

Of the two options, I would be in favour of a monorepo.

[MichaelDeBoey]

I would love this idea as well 👍
And also think the monorepo is the best way here, but would love to get @eslint-community/eslint-plugin-node's thoughts as well

@JoshuaKGoldberg I don't know if you wanted to keep the exact same API or not
But since extracting the lib is going to make that the code is used by a lot more people, I think we should also think about #359 and it's possible impact (and the possible impact of having @eslint-community/eslint-utils as its dependency)

[JoshuaKGoldberg]

Whoo boy, I hadn't read deep enough into the code to come across the HEAD/READ/etc symbols. Yeah I would hope the API in this standalone package wouldn't have any dependency on @eslint-community/eslint-utils. Those symbols do seem very ESLint-specific. Maybe the new package could expose things under plain string keys, and implementers could know to map those keys to whatever internal tracking (e.g. those symbols for ESLint) they need?

// in the new general package
createRequire: { read: { supported: ["12.2.0"] } },

// in a consumer
const symbols = { read: READ, ... };
const info = createRequre[symbols.read];

[patricktree]

I love this idea.

Of the two options, I would be in favour of a monorepo.

FYI if you need someone for the migration to a monorepo, I could do that (did it already a couple of times)

[MichaelDeBoey]

I'm not sure if these symbols are that specific to ESLint tbh.

But if I recall #359 correctly, it came from a problem that we weren't using CALL/READ in a consistent way.
I would have expected that READ would be used for variables and CALL would be used for functions, but as you can see in #358 (comment), we are using READ for functions as well.
Hence why we extracted the discussion into #359

Now that we are probably going to extract the unsupported-features lib, I think it would be wise to also take that discussion into mind and come up with a clear solution for all mentioned cases.

Although READ/CALL/CONSTRUCT currently live in @eslint-community/eslint-utils, I'm not sure it still should fully live there and I think we should rethink how both this plugin (eslint-plugin-n) & @eslint-community/eslint-utils should work with an extracted unsupported-features lib to find out which functionality should live where

[JoshuaKGoldberg]

I'm not sure if these symbols are that specific to ESLint tbh

I can't find any docs on them - why do they exist in the first place? Why not go with plain keys like { read: ... }?

From a medium-level inspection, the usage of symbols looks like an eslint-community-specific implementation detail that other consumers almost certainly won't want to take on. I see no reason for them in an arbitrary other linter. Unless I'm missing something?

READ/CALL/CONSTRUCT

I also don't follow why there needs to be a delineation between them. Every CALL and CONSTRUCT usage in userland code is, by definition, also a READ. You can't call or construct something without a reference to it! Are there some APIs that switched their read/call/construct characteristics between Node.js versions? Am I missing something here too?

[voxpelli]

Are we thinking that eslint-plugin-n will also depend on this module or that we add a publish step that spins out a separate module on release that contains the data?

In a monorepo, how will we approach versioning and releases for this? Will we release it in sync with and with same version number as the plugin? As such limiting the data module’s possibility to release breaking changes of it own.

I think I would go for a new repository that can have its own release cadence and its own PR:s and issues as well as possibly an extended or different set of maintainers.

[aladdin-add]

Will we release it in sync with and with same version number as the plugin?

I don't think so - we can use the independent mode, something like: https://lerna.js.org/docs/features/version-and-publish#independent-mode

[MichaelDeBoey]

I can't find any docs on them

@JoshuaKGoldberg eslint-utils' tracker.iterateGlobalReferences docs seems to be the only place I could find explaining these 3 symbols

The reference type. If this is ReferenceTracker.READ then it read the variable (or property). If this is ReferenceTracker.CALL then it called the variable (or property). If this is ReferenceTracker.CONSTRUCT then it called the variable (or property) with the new operator.

why do they exist in the first place? Why not go with plain keys like { read: ... }?

From the way I currently understand what's going on, that's definitely a possibility if you ask me

From a medium-level inspection, the usage of symbols looks like an eslint-community-specific implementation detail

I don't think it's that specific to these ESLint-related packages tbh, but I agree it's currently something that probably only @mysticatea (the original creator of both eslint-plugin-node & eslint-utils) knows the exact (implementation) details about

that other consumers almost certainly won't want to take on. I see no reason for them in an arbitrary other linter. Unless I'm missing something?

From what I currently understand what's going on, I 100% agree that we should work towards a version that's easy to understand by a wider group of people and should be documented properly, so other arbitrary linters can just use it as well 💯
For that reason, I wanted to make sure to mention #359, so we're not just blindly copy/pasting the current implementation into a new lib

I also don't follow why there needs to be a delineation between them. Every CALL and CONSTRUCT usage in userland code is, by definition, also a READ. You can't call or construct something without a reference to it!

Apart from the brief mention in the tracker.iterateGlobalReferences docs, this was indeed not really clear to me either how these 3 symbols should be used, hence the creation of #359

There's for instance node:event's CustomEvent that has class next to it, but the global CustomerEvent doesn't 🤔

Apart from that, @scagood also mentioned in #359 (comment) some more uncommon cases for

• CONSTRUCT

  if (event instanceof CustomEvent) {}
  class MyEvent extends CustomEvent {}

• CALL

  module.enableCompileCache.call(module); // or `bind`/`apply`
  process.nextTick(module.enableCompileCache);

@fisker also mentioned in #359 (comment) cases like delete foo & delete globalThis.foo, which actually don't fit in any of these 3 symbols I would say

So as you can see, there's a lot of unclear things about this API 😢

Are there some APIs that switched their read/call/construct characteristics between Node.js versions?

I can't seem to find which one it was, but I vaguely remember a variable that turned into a function when going from experimental to stable
The other way around could also be the case, but feels less likely tbh

---

Are we thinking that eslint-plugin-n will also depend on this module or that we add a publish step that spins out a separate module on release that contains the data?

@voxpelli I would say that eslint-plugin-n (and maybe even eslint-utils) would (both) depend on this new lib

In a monorepo, how will we approach versioning and releases for this? Will we release it in sync with and with same version number as the plugin? As such limiting the data module’s possibility to release breaking changes of it own.

I definitely think the new lib should get it's own version number

[voxpelli]

Will we release it in sync with and with same version number as the plugin?

I don't think so - we can use the independent mode, something like: https://lerna.js.org/docs/features/version-and-publish#independent-mode

Then we would have to swap release-please for Lerna, right? That sounds like much extra work and complexity compared to just splitting

[patricktree]

Will we release it in sync with and with same version number as the plugin?

I don't think so - we can use the independent mode, something like: https://lerna.js.org/docs/features/version-and-publish#independent-mode

Then we would have to swap release-please for Lerna, right? That sounds like much extra work and complexity compared to just splitting

I think options are:

1. Keep release-please and configure it for monorepo (https://github.com/googleapis/release-please/blob/main/docs/manifest-releaser.md) - set the packages, enable "node-workspace" plugin.
2. Switch to lerna.
3. Switch to changesets (used e.g. by https://github.com/TanStack/query)

All of this brings complexity, question is if the benefits of a monorepo are worth it.
If there is no plan or perspective that this repo will have more than the 2 packages (eslint-plugin-n and the new node-feature-support), than maybe a new repo for the new package is better to keep things simple.
(I'm a big fan of monorepos, but still...)