support node -r nodereport app.js as well as programmatic use via API

[sam-github]

ATM, nodereport works better via API, its clumsy if you want automatic hooking, see:

#23 (comment)

On the other hand, if you want to use nodereport to trigger a report manually, just using its public API, you don't want its (quite intrusive) hook mechanisms, which modify exit codes, behaviours, and even steal signals.

In summary, we need easy opt-in for default behaviour, but we also need easy opt-out, and I don't see any way to provide the two via a single require entry point that does not depend on env vars for configuration.

To make both use-cases easy, I suggest:

node -r nodereport/attach app.js

for the opt-in case, and

require("nodereport").triggerReport()

for the opt-out.

I'm OK with the require paths being switched, so node -r nodereport opts-in, and require("nodereport/api") or something of the like just requires the nodereport API without hooks.

Any other suggestions?

[rnchamberlain]

+1, with preference for 'paths being switched' because the API user is more likely to study the docs.

@sam-github do you have any documentation references for the 'module/option' syntax?

[Fishrock123]

I would prefer it to be as easy to use on an existing script out of the box as possible.

Maybe it's just me but I don't see the code hooks as being quite as valuable (and the feel a bit more invasive). IIRC this is the sort of reason -r exists in the first place.

FWIW tools like dprof have this similar behavior and I feel a previous precedent has already been set by similar modules that act upon requiring.

[sam-github]

So you two would prefer

node -r nodereport app.js

for the opt-in case, and

require("nodereport/api").triggerReport()

for opt-out of hooks, with the understanding that this works to get hooks, and have the API:

require("nodereport").triggerReport()

Above is fine by me.

[richardlau]

I think I'm also in favour of

node -r nodereport app.js

being opt-in and

require("nodereport/api").triggerReport()

for opt-out of hooks.

Since this would be a change in behaviour, would this be semver-major?

[sam-github]

yep, semver-major​

[mhdawson]

Given the consensus, I'm ok with node -r being opt in by default.

[rnchamberlain]

PR #33 landed.

node -r nodereport app.js now provides the "no application code change" functionality with hooks/signal on by default, and for api users, require("nodereport/api") is available, with hooks/signal off by default.

Not published in npm yet. Currently we are at 1.0.7, should this go up as 1.1.0 or 2.0.0?

[gibfahn]

2.0.0 as it's a semver-major change

[richardlau]

node-report v2.0.0 (including #33) has been released.

[rnchamberlain]

@sam-github OK to close this now?