Add a way for package maintainers to specify their own overrides

[jdalton]

In developing Socket Registry I have been noodling on giving package maintainers the ability to specify their own overrides. So we can include them where it makes sense (in our registry/manifest.json). \cc Jordan Harband (@ljharb)

I'd like the data to be accessible via the npm registry. We query the registry to create the manifest per package looking for things like "deprecated". Let's keep it simple. If a version is released with a prerelease of "override" we can defer to it for some category of overrides, like "cleanup".

[jdalton]

Jordan Harband (@ljharb) do you want to test the waters with this? Maybe pick an easier/simple package and try it out.

[ljharb]

The use cases I think are good to handle are:

• a different version of the same package is the replacement (either a prerelease range, or a major range, or a dist-tag)
• an entirely different package is the replacement (replace foo with bar@^1 eg)
• a scope is the replacement (replace foo with @ljharb-cleanups/foo, or something, same version numbers)

The third one is a bit too complex but I thought it was worth mentioning anyways.

A possible approach that could handle the first two is a new top-level key, say "variants". The LHS of this object is a category, like "cleanup", or an arbitrary string. The RHS is the same as the RHS of an overrides object.

So, for a concrete scenario:

• I have call-bind v1, which by default uses function-bind, grabs a bunch of intrinsics, and is CJS.
• I could create an ESM version that assumes bind and Object.defineProperty and Reflect.apply exist, and publish it as a prerelease of v2, like v2.0.0-cleanup.0
• then on v1, i publish package.json with variants: { cleanup: '^2.0.0-cleanup' } or similar, and this tool can automatically pick that up

Alternatively:

• I have call-bind v1, which by default uses function-bind, grabs a bunch of intrinsics, and is CJS.
• I could create an ESM version that assumes bind and Object.defineProperty and Reflect.apply exist, and publish it as call-bind-modern
• then on v1 of call-bind, i publish package.json with variants: { cleanup: 'call-bind-modern@^1' } or similar, and this tool can automatically pick that up

Thoughts?

[jdalton]

So the key is metadata in your package.json. Our socket overrides have a socket field in their package.json so I can dig that. I like storing it there so we can query and spot it. Enter bikeshed of what to call it. Let's say "variants" for now. A tag used for the name of the variant and a reference. I believe npm does it like npm:call-bind-modern@^1. That could work! Then any tool looking for a variant and a tag can do what they want with the info. We have a thing (cleanup) and a replacement (npm:call-bind-modern@^1).

[ljharb]

exactly - and i can make up my own variants if i want, and tools can choose to adopt them if they want.

[jdalton]

Okay. Let's roll with "variants". ChatGPT could not come up with a better name 🙃 🤣

[jdalton]

Jordan Harband (@ljharb) This is next on my plate to take on. There's an easy way and a less easy way to detect this. One is looking at the packages already in the node_modules folder and the other is querying the registry to get the latest version and extract the package.json to inspect.

Update: We’ll try going the packument route

[ljharb]

Presumably it'd be in the packument, so you wouldn't have to extract anything? (there's no risk here imo from packument confusion)

[jdalton]

From the outside looking in (so building something outside of npm) I don't think we'll get the info from the packument. Long-term if it becomes a thing then that would be nice for sure.

[ljharb]

Why wouldn't you want to, since it's much cheaper than extracting the archive?

[jdalton]

Oh I want to, it just requires moving npm I believe, unless we can already do this today without patching the packument format.

[ljharb]

Right, that's what I'm saying you can already do. I'm pretty sure every unknown field in package.json ends up in the packument automatically.

[jdalton]

Excellent

[jdalton]

Jordan Harband (@ljharb) Touching base on this, have you added the variants field to any packages?