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 @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]

@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]

@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]

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