feat: add META symbol to exports (#84)

Two things to note:

- The key is the string `'META'`
- The value is `Symbol('proc-log.meta')`

So it could be used like the following. All of the following is up to
producers/consumers to implement with shared conventions. All `proc-log`
is doing to allowing them to share a unique `Symbol`.

```js
const { output, META } = require('../')

// An example of how consumers would see if a META object
// was the last argument from an event
const getMeta = (args) => {
  let meta = {}
  const last = args.at(-1)
  if (last && typeof last === 'object' && Object.hasOwn(last, META)) {
    meta = args.pop()
  }
  return [meta, ...args]
}

process.on('output', (level, ...rawArgs) => {
  const [{ force = false }, ...args] = getMeta(rawArgs)
  console.log(level, { force, args })
})

// in this implementation the value does not matter, just the key
output.standard('arg1', 'arg2', { [META]: null, force: true })
output.standard('arg1', 'arg2')
output.standard('arg1', null)
output.standard(null)
output.standard()

// Will log the following:
// standard { force: true, args: [ 'arg1', 'arg2' ] }
// standard { force: false, args: [ 'arg1', 'arg2' ] }
// standard { force: false, args: [ 'arg1', null ] }
// standard { force: false, args: [ null ] }
// standard { force: false, args: [] }
```

Closes: #81

lib/index.js

@@ -1,4 +1,6 @@
+const META = Symbol('proc-log.meta')
 module.exports = {
+ META: META,
  output: {
  LEVELS: [
  'standard',

test/index.js

@@ -2,9 +2,17 @@ const t = require('tap')
 const procLog = require('../')
 
 // This makes sure we are testing all known exported methods.
-t.plan(4)
+t.plan(5)
 
 for (const method in procLog) {
+ if (method === 'META') {
+ t.test(method, t => {
+ t.type(procLog[method], 'symbol')
+ t.end()
+ })
+ continue
+ }
+
  t.test(method, t => {
  const log = procLog[method]
  const { LEVELS, KEYS } = log

test/meta.js

@@ -0,0 +1,42 @@
+const t = require('tap')
+const { META, output } = require('../')
+
+// just to show how this would be implemented in consumers
+const getMeta = (...args) => {
+ let meta = {}
+ const lastArg = args[args.length - 1]
+ if (
+ lastArg &&
+ typeof lastArg === 'object' &&
+ Object.prototype.hasOwnProperty.call(lastArg, META)
+ ) {
+ meta = args.pop()
+ }
+ return [meta, ...args]
+}
+
+// an example of wrapping a handler
+const wrapMeta = (handler) => (level, ...args) => handler(level, ...getMeta(...args))
+
+t.test('meta', t => {
+ process.once('output', (level, ...rawArgs) => {
+ const [meta, ...args] = getMeta(...rawArgs)
+ t.equal(level, 'standard')
+ t.ok(meta.force)
+ t.strictSame(args, ['arg1', 'arg2'])
+ t.end()
+ })
+
+ output.standard('arg1', 'arg2', { [META]: 0, force: true })
+})
+
+t.test('wrap handler', t => {
+ process.once('output', wrapMeta((level, meta, ...args) => {
+ t.equal(level, 'standard')
+ t.ok(meta.force)
+ t.strictSame(args, ['arg1', { META: true }])
+ t.end()
+ }))
+
+ output.standard('arg1', { META: true }, { [META]: null, force: true })
+})