Move the assert module to userland

[papandreou]

I feel that maintaining the assert module as part of node has been an unnecessary distraction for the project for a long time. If you search for assert across issues and PRs, 2360 results turn up. Now major features are being added, such as diffs and colored error messages, so it seems like it's only getting worse.

At the same time the module is classified as "stable" and hasn't been able to correct all the weirdness of the original CommonJS spec, leading to surprises when users don't use the "strict" and "deep" versions of the methods.

Liberating the module from core would allow it to evolve, and hopefully new users would stop picking it up "by default" and being surprised by its quirks.

[BridgeAR]

I am surprised that adding new features is considered "bad". I would have expected it to be good that this module is finally getting in nice shape. And I personally have been involved a lot in further optimizing assert but I do not see that this has distracted Node.js.

There are some quirks that can not easily be removed due to historical reasons but that is what the new strict mode is about. That way it is safe to use any function without worrying about using the "correct" function.

assert was part of Node.js for a long time and it is heavily used and moving it out is not really viable as far as I see it.

[Munter]

Expanding the scope of assert to include diffs and colored error messages is a Pandora's box of style fixes and introduces a huge amount of subtle bugs that need to be fixed. Fixing those in node core on a slow release cycle seems like a quite painful flow.

Looking through the colored diff that just went in, this also means node core now includes hard coded knowledge of several specific terminals and CI environments. This is a quite rapidly changing landscape, so this code will get out of date. Also add a maintainer of environments that have not been blessed by node core I question why my specific thing is not deemed worthy of color.

Are these really discussions that belong in what keeps being referred to as a small core?

[BridgeAR]

@Munter color support and if assert should be in Node.js are two separate concerns. The first is something that is absolutely not limited to assert and opens up the possibility for more features.
Having a small core is also a topic on it's own because it is a general thing and not about having a specific module. Not to mention that there are different opinions about having a small core or not as well.

Speaking about bugs before there is an issue is somewhat surprising to me. If Node.js is good in one thing though, it is fixing bugs. That is done all the time and does not have a slow release cycle. That is done almost once a week. What is slow is breaking code.

The current color detection is something that will likely need some further work but having that in Node.js is important, otherwise using colors is not really an option. I am traveling this week though and am fairly busy, so I did not get back to it yet.

[alexjeffburke]

@BridgeAR I don't think anybody was suggesting new features in core are bad, but we are asking for the rationale behind this being included in core.

Of course colour detection would be required if colours are desired in core, but the underlying question is exactly whether this is this really territory for core or is rather much better solved in userland? At least from my perspective it has been encouraged to do user facing libraries in the ecosystem for a long time and there are some amazing solutions that already exist there.

Also, I'd really like to see a specific response to the point raised by @Munter about hard coding terminal knowledge in core - how will this be handled? If this went in, would there be flags or environment variables added to force coloured output for example in CI (this is well known to require a helping hand - see --color options to all the test runners) or if my system happens not to support it? There things would need to be addressed, though I stand by my reservations.

Again, any and all work done by folks on core is very much appreciated by those of us using the platform. In this case however there are well documented long standing issues with the assert API. I don't think further encouraging it's use is the right thing and, as someone who has written a library that aimed for bug-for-bug compatibility with assert to provide users an upgrade path, I would be pretty worried about introducing changes to the module.

[benjamingr]

Here is the thing:

• Assert is in core right now
• It is pretty well maintained
• For non-core usage, a ton of userland alternatives exist.
• Taking it out of core right now would require non-trivial work
• Maintainers don't see maintaining it as a burden - or at least no core collaborators have expressed frustration over having to maintain assert.

So I am -1 for removing assert, mostly because it will undoubtedly "break userland" in some subtle way, it would require more work than it would to keep things as they are - and people don't really feel this is a big maintenance burden.

If the discussion was about introducing assert I believe the barrier would have been different.

[SimenB]

(Tangentially related, happy to open up a separate issue if you want.)

While I don't have any opinions on whether assert should be outside of Node core or not; as a maintainer of Jest, changing the output of assert makes it harder to integrate properly. We've had requests to Just Work ™️ with assert because it's in core, which is fine (and useful), but if we're going to have to clean the default output things might get unwieldy (already pretty gnarly: https://github.com/facebook/jest/blob/358764dcc784028e5e2d231a0e40e02688fc532b/packages/jest-jasmine2/src/assert_support.js). So I'd appreciate if the plain error message, without diffs or colors, be added as a separate property to the thrown error.

EDIT: Or even better: having structured data in general on the error

[alexjeffburke]

@SimenB that's a really good point! I wrote a drop in replacement for assert (https://github.com/alexjeffburke/assert-the-unexpected) that emulates the API but runs assertions via the Unexpected assertion framework. Part of this emulation was to make sure thrown errors were still of type AssertionError and the messages matched in case anybody was checking the contents of the .message property and I'm not really what effect the colouring code will have (especially if it's on by default).

Finally, in the spirit of trying to share knowledge - there are some pitfalls with extending messages and at least a large number of mocha releases need "message" to equal the start of "stack" or things get printed twice.

[benjamingr]

@SimenB - hey, if you're up for it we're doing a session for user feedback and tooling folk - you're more than welcome to provide this feedback directly (it's welcome and will likely have an impact) nodejs/user-feedback#37

So I'd appreciate if the plain error message, without diffs or colors, be added as a separate property to the thrown error.

That can also be a feature request or a configuration set with an environment variable (CC @BridgeAR @addaleax ), there is no need to go on tangents you're welcome to open an issue and request it as a feature request.

[cjihrig]

Moving assert to userland isn't possible, as core uses it for its tests (not to mention the ecosystem breakage that would follow). For that reason, I'm going to close this issue, although I definitely sympathize with the motivation behind opening this issue.

[SimenB]

@benjamingr sounds good! I'll create an issue after Easter

[papandreou]

I'm a bit disappointed that this issue is closed before the discussion even started.

First off, the fact that core uses assert for its tests is not a good argument for also maintaining it as part of core, and especially not for exposing it to userland.

I agree that it would be unrealistic for core to stop exposing the module at this point, even with a long, well thought out deprecation strategy. Still, I hoped that we could have a strategic discussion about this and maybe even agree that:

1. Exposing assert was a mistake in the first place (check)
2. The more advanced assert becomes, the more hopeless it is to develop and version it along with node.js itself because of backwards compatibility
3. For the above reasons we should discourage new users from using assert

The new features are probably fine and well implemented, but I still think it's bad judgement to land them, thus further encouraging the use of assert. Please just keep that module as simple as possible, seeing that we cannot get rid of it. I maintain that it's a needless distraction for the project.

[ljharb]

Whether something is a distraction or not seems like something only the maintainers can judge.