doc: Mention --experimental-top-level-await flag

[dfabulich]

Checklist

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

[juanarbol]

I don't want to be against this change, but is it currently documented here

[dfabulich]

I didn't mean to say that it's not documented, but the changelog should mention that it's behind the flag, I think.

[devsnek]

this will also require a change to https://github.com/nodejs/nodejs.org/blob/master/locale/en/blog/release/v14.3.0.md

[dfabulich]

I filed a separate PR for nodejs.org.

[samceena]

The changelog does not mention that it's behind a flag if it needs to be, so it's confusing.
If it try: node --harmony-top-level-await 1.mjs it works, but if i try node 1.mjs, its not working, even if i have "type": "module" in the package.json file, so it's a little ambiguous. Can we write more about this in the doc?

[zombieleet]

@dfabulich it is also not specified in the cli doc https://nodejs.org/api/cli.html

[dfabulich]

Good catch! I added documentation to cli.md.

[dfabulich]

While updating cli.md, I briefly incorrectly claimed that --experimental-top-level-await works in NODE_OPTIONS, but then I realized it doesn't, so I filed PR #33495 to add it.

[dfabulich]

These tests were passing before I added that whitespace change; I'm about 99% sure this is a flaky build issue. (I don't see any way to rerun the build myself.)

[dfabulich]

I'm about 99.999% sure this documentation PR didn't cause this failing test.

not ok 844 parallel/test-http-destroyed-socket-write2
  ---
  duration_ms: 0.125
  severity: fail
  exitcode: 1
  stack: |-
    assert.js:103
      throw new AssertionError(obj);
      ^
    
    AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
    + actual - expected
    
    + 'ERR_STREAM_DESTROYED'
    - 'ECONNRESET'
        at ClientRequest.<anonymous> (/Users/runner/runners/2.262.1/work/node/node/node-v15.0.0-nightly2020-05-22xxxx/test/parallel/test-http-destroyed-socket-write2.js:66:16)
        at ClientRequest.<anonymous> (/Users/runner/runners/2.262.1/work/node/node/node-v15.0.0-nightly2020-05-22xxxx/test/common/index.js:363:15)
        at ClientRequest.emit (events.js:315:20)
        at emitErrorNt (_http_outgoing.js:666:43)
        at processTicksAndRejections (internal/process/task_queues.js:85:21) {
      generatedMessage: true,
      code: 'ERR_ASSERTION',
      actual: 'ERR_STREAM_DESTROYED',
      expected: 'ECONNRESET',
      operator: 'strictEqual'
    }

[BridgeAR]

@dfabulich we have multiple flaky tests. It is some times difficult to get the tests passing consistently on the amount of different systems and settings we support.

If you stumble upon one of those, you might want to check if there's a corresponding issue and if not, to open a new issue for the failure.

[BridgeAR]

Landed in c39467c 🎉