feat: add time and input

[lukekarrys]

This adds top-level time and input namespaces.

time is used to facilitate starting/ending timers including the ability to pass in a sync or async callback which will be timed. This is a pattern we already used in npm/cli and can be replaced with this code from proc-log instead.

input is used to send events indicating user input is being read. There are two ways to do this: start and end functions or a read function which will return a promise and emit the promise's resolvers to the consumer.

This also adds a KEYS to each namespace which is an enum for getting the levels by name. In npm/cli our consumer creates these with log.LEVELS.reduce((a, k) => (a[k] = k, a), {}) so that we don't need to type any string names in our handelrs.

[lukekarrys]

The reason I opted for two different ways to do input is in some specialized producers (eg libnpmexec) we will want to use input.read which will give us more control and also be a breaking change.

In more generic consumers we can just wrap the current code in input.start() and input.end(). Our consumer will be able to listen and respond to these events, but all others can ignore these events so it won't be a breaking change.

[wraithgar]

What about log.pause and log.resume? We've only ever documented that those take no args themselves. Should we make that a reality?

[lukekarrys]

Yeah that seems like a good idea now that we have separate functions for each method.

[wraithgar]

We're using node:readline in npm itself: https://github.com/npm/cli/blob/latest/lib/utils/open-url-prompt.js

[wraithgar]

Maybe I'll see it when I review again tomorrow but I don't understand the function of KEYS

[wraithgar]

This question applies to log.pause/unpause and input.start/end. Whose concern should it be if multiple starts/pauses are called and then multiple unpause/ends? How is a consumer to know when ALL interested parties have indicated that logs should unpause or input has truly ended? Obviously if two asynchronous operations are trying to do input they'll inevitably collide with each other so perhaps that's not a concern to solve. This is thinking out loud at this point.

[lukekarrys]

Maybe I'll see it when I review again tomorrow but I don't understand the function of KEYS

It is only there to avoid having to manually type strings in consumers. Here's a diff of what you would replace if KEYS were exported.

+ const { output } = require('proc-log')

 process.on('output', (level, ...args) => {
   switch (level) {
-    case 'standard':
+    case output.KEYS.standard:
       console.log(args)
       break
-    case 'error'
+    case output.KEYS.error:
       console.error(args)
       break
   }
 })

[wraithgar]

It is only there to avoid having to manually type strings in consumers

You still have to know and type the indices to KEYS, I don't get the difference. I'm willing to accept this is just me though.

[lukekarrys]

How is a consumer to know when ALL interested parties have indicated that logs should unpause or input has truly ended?

This is why I opted for time.start/end(name) to take a timer name. Multiple timers can be run and it's up to the consumer to handle all of them simultaneously. This is how lib/utils/timers.js in npm/cli works currently.

input.start/end/read() don't take a name argument since there is only one interface for user input. If there are multiple producers nested which are emitting input events, there will be other problems. So I didn't think it should be encouraged to try and namespace input events. Should this be added to input as an escape hatch for complex terminal UI scenarios I'm not envisioning?

[wraithgar]

Should this be added to input as an escape hatch for complex terminal UI scenarios I'm not envisioning?

No, you thought about this more than I did already. This is find as-is.

[wraithgar]

If you want to tweak log.pause and log.resume you still can, but I didn't want to block on that.

[wraithgar]

My remaining 3 comments (readline, log.pause, KEYS) are just those: comments. None of them are blockers but you can act on them if you choose.

[lukekarrys]

@wraithgar Pushed a commit removing args from log.pause() and `log.resume(). Leaving the rest as-is.