Include metadata that can be emitted along with events

[lukekarrys]

proc-log is designed to be Just an Event Emitter ™️ with some well known event names.

This means it passes along all arguments when emitting to consumers. This is a good approach because there are rarely changes that proc-log needs to make outside of adding new methods. If a producer sends arguments then it is the consumers responsibility to consume them somehow.

Our primary use case is displaying things in a terminal. So all arguments are passed to util.format which can take anything as input. We might be displaying a string, number, plain function or custom class with a [util.inspect.custom] method.

BUT most of the examples I wrote out in npm/statusboard#810 rely on some kind of well-known metadata to be useful. This is why I think proc-log should have some way to indicate "this event contains an argument that is special and belongs to proc-log. It will have data in it that you should look at differently than the rest"

Possible Solutions

Producers

proc-log itself should have some sort of ergonomic API to send this metadata.

meta() function on each method

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

// Each function gets an additional `meta` function which indicates
// the first parameter is special
output.standard.meta(
  { colors: false, template: './arbitrary' },
  'anything', 'else', new You(), { want: new Set() }
)

// could also be the last parameter
output.standard.meta('anything', 'else', new You(), { want: new Set() }, {
  colors: false,
  template: './arbitrary'
})

top level meta() function

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

// Wrap an object in the meta function which will somehow mark it as special
output.standard(
  meta({ colors: false, template: './arbitrary' }),
  'anything', 'else', new You(), { want: new Set() }
)

// Can't enforce which location its used in, which seems bad
output.standard('anything', 'else', new You(), { want: new Set() }, meta({
  colors: false,
  template: './arbitrary'
}))

use a symbol to set a key

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

// Still need to figure out which position the argument goes in
output.standard('anything', 'else', new You(), { want: new Set() }, {
  [META]: true,
  colors: false,
  template: './arbitrary'
}))

Consumers

Consumers listening with process.on(eventName) should have some ergonomic way to know that an argument is metadata.

level argument is metadata too

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

// This would be a breaking change
process.on('output', ({ level, ...metadata }, ...args) => 
  if (level === 'standard' && metadata.templates) {
    // It is a template
  }
})

helper to find metadata in args

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

process.on('output', (level, ...rawArgs) => {
  const [args, metadata] = meta.getMeta(rawArgs)
  if (level === 'standard' && metadata.templates) {
    // It is a template
  }
})

[wraithgar]

The only thing I have even approaching the level of an opinion is that proc-log should export a meta symbol that consumers can use. I don't even know if I like having proc-log look for that symbol. There's an argument that could be made that the consumer is responsible for all of that. The symbol is what's needed to have some "thing" that all proc-log consumers can use as a signal so that we don't have to go back down the path of sharing some stateful object w/ everything that needs to log or output.

This brings us to the nature of the symbol. If it's Symbol('proc-log.META') then if somehow in the future folks have duplicated versions of proc-log in their tree, the consumer could get confused if it has to compare it. If it's `Symbol.for('proc-log.META') then we are free of that particular issue

> x = Symbol.for('test')
Symbol(test)
> y = Symbol.for('test')
Symbol(test)
> x === y
true

I don't know if this is more an argument for Symbol.for or if it's evidence that proc-log DOES need to be looking for that symbol in a well-known place. Sorry, I've more questions than answers at this phase.