node: --run requires an argument

[lydell]

Affected URL(s)

https://nodejs.org/api/cli.html#--run

Description of the problem

The docs for node --run say:

If no "command" is provided, it will list the available scripts.

I thought that meant that if I run node --run, I’ll get a print of all available scripts (similar to how npm run works when not given a script name). But that results in an error:

❯ node --version
v22.5.0
❯ node --run
node: --run requires an argument

It’s still possible to get a listing of all available scripts, by passing a script name that does not exist:

❯ node --run .
ExperimentalWarning: Task runner is an experimental feature and might change at any time

Missing script: "."

Available scripts are:
  test: whatever

I’m not sure what the exact problem is though:

• Am I just misunderstanding the docs?
• Are the docs wrong, and the quoted sentence should be removed?
• Is the implementation wrong, and node --run should in fact print the available scripts?

Thing I found while messing around with this that is probably out of scope in this issue:

❯ node --run ''
Welcome to Node.js v22.5.0.
Type ".help" for more information.
>

Giving the empty string to --run does not try to execute { "scripts": { "": "echo hi" } }. Neither does npm run '' though :)

[RedYetiDev]

Reproductions:

$ node --run ''
Welcome to Node.js v22.5.0.
Type ".help" for more information.
>

$ node --run
node: --run requires an argument

$ node --run .
ExperimentalWarning: Task runner is an experimental feature and might change at any time

Missing script: "."

Available scripts are:
<...>

[aduh95]

If someone sends a PR to fix the docs, it will probably be accepted.

[tniessen]

What about the first example from @RedYetiDev's last comment? What's the expected behavior? Why is there a REPL being started?

[RedYetiDev]

What about the first example from @RedYetiDev's last comment? What's the expected behavior? Why is there a REPL being started?

My reproductions were a bit out of order, but at the end of the issue, the author notes:

Giving the empty string to --run does not try to execute { "scripts": { "": "echo hi" } }. Neither does npm run '' though :)

[lydell]

That doesn’t explain why the repl is started, though? I was surprised when that happened 😄

[RedYetiDev]

That doesn’t explain why the repl is started, though? I was surprised when that happened 😄

FWIW my assumption is that it treats an empty string as if the flag wasn't there, so it performs the action as if that flag wasn't applied, in this case, trigging the REPL.

[tniessen]

That's still quite odd and hardly seems desirable... I am wondering if it's intentional. @anonrig

[richardlau]

Reproductions:

$ node --run ''
Welcome to Node.js v22.5.0.
Type ".help" for more information.
>

That's odd behaviour. This is valid JSON:

{
        "name": "nodejs_run_test",
        "scripts": {
                "hello": "echo hello",
                "world": "echo world",
                "": "echo !"
        }
}

i.e. it's valid to have an empty string as a JSON key. So I would expect node --run '' to behave the same as if a non-existent script was specified (unless of course a "" script was defined as in the example above).

FWIW as reference, npm can't run a "" named script:

$ npm run-script ''
npm error valid event not provided to runScript
npm error A complete log of this run can be found in: /home/rlau/.npm/_logs/2024-07-22T12_39_38_822Z-debug-0.log
$

so Node.js could choose to do the same (but should probably be documented to do so, given that "" is a valid JSON key).

[tniessen]

Since npm compatibility clearly wasn't a priority, I think it's reasonable for Node.js to implement some reasonable behavior instead.

[richardlau]

Since npm compatibility clearly wasn't a priority, I think it's reasonable for Node.js to implement some reasonable behavior instead.

Agreed, I'm just not sure the current behaviour is reasonable 🙂.