doc: explain differences in console.assert between node and browsers

[jasnell]

Checklist

• documentation is changed or added
• the commit message follows commit guidelines

Affected core subsystem(s)

doc, console

Description of change

Provide an example for implementing browser like behavior for console.assert.

This "fixes" #5340 by providing an alternative to changing Node.js' implemented behavior. Instead, we document the differences and show how to work around them if browser like semantics are desired.

Fixes: #5340

[jasnell]

@nodejs/documentation

[benjamingr]

Why do we need a setPrototypeOf call here?

[jasnell]

actually, the example is incomplete... just noticed... it should be:

const myConsole = Object.setPrototypeOf({
   assert(assertion, message, ...args) {
     try {
      console.assert(assertion, message, ...args);
     } catch (err) {
       console.error(err.stack);
    }
   }
 }, console);

Essentially, this creates a simple extension of the existing console object without monkey-patching it.

[jasnell]

Fixed the example in updated commit

[benjamingr]

Not sure we should be encouraging such liberal use of setPrototypeOf. A lot of people have strong feelings against it and it sort of lumped in the language by mistake (it's a funny story really).

If we are using it though, why not just:

const myConsole = { __proto__: console,
                    assert: ... }

[jasnell]

Not sure encouraging use of __proto__ is any better.

[jasnell]

ping @nodejs/documentation

[techjeffharris]

perhaps a link to https://developer.mozilla.org/en-US/docs/Web/API/Console

[eljefedelrodeodeljefe]

LGTM with a nit.

[techjeffharris]

A couple links suggested, but LGTM

[jasnell]

@eljefedelrodeodeljefe @techjeffharris ... updated, PTAL!

[techjeffharris]

Though this PR is only targeting a clarification of console.assert, as log as there's a link to the browser console.assert maybe we should have a link to the general browser console API in the following section: (sorry, not in a place to easily see which line)

While the API for the Console class is designed fundamentally around the browser console object, the Console in Node.js is not intended to duplicate the browser's functionality exactly.

Might be more appropriate in another PR...?

[techjeffharris]

The most recent changes LGTM, regardless.

[eljefedelrodeodeljefe]

LGTM. Thx @jasnell. @techjeffharris let's collect those in the wake of nodejs/docs#100 (?)

[jasnell]

Landed in 40a5761

[qfox]

This definitely NOT fixes #5340. Sad news everyone.
Can you please explain why you prefer non-standard behaviour?

[jasnell]

The way browsers implement console is not standard (see: https://developer.mozilla.org/en-US/docs/Web/API/Console). This has been discussed before and it has been decided that it is not a priority for Node.js to align with the browsers on the non-standardized behavior of console.

[qfox]

Thank you.