docs: add explanation about `LogObject` and `raw` method

[baronyoung]

Environment

consola v3.2.3 nodeJS v 19.4.0

Reproduction

https://stackblitz.com/edit/stackblitz-starters-9gyjzk?file=index.js

import consola from 'consola'

const logger = consola.withTag('scratch.ts')
logger.level = 5

class testConsola {
    private getParams() {
        return Array.from(arguments)
    }
    count(arg1, arg2) {
        let methodName = 'count'
        return {method: methodName, args: this.getParams.apply(this, arguments)}
    }
}
let test = new testConsola()

logger.info(test.count('a', 'b'))
 // returns a b

console.info(test.count('a', 'b'))
// returns { method: 'count', args: [ 'a', 'b' ] }

Describe the bug

I'm getting different results from consola vs console - consola isn't correct.

Additional context

No response

Logs

No response

[NozomuIkuta]

Would you provide a minimal reproduction, so that everyone can see what's happening actually?

[baronyoung]

I'd be happy to if I knew a site where I could specify packages. Could you suggest one?

[NozomuIkuta]

@baronyoung

Stackblitz or CodeSandbox are commonly used by many OSS projects. You can choose Node.js empty project template to set up a minimal reproduction and share the link.

[baronyoung]

Ok, I added a stackblitz link to the OP.

[NozomuIkuta]

@baronyoung

Sorry to reply late. I was sick.

It doesn't seem to be well documented, Consola's logging methods have a signature for which an object of LogObject interface is passed as first and only argument.

Consola determines whether LogObject is passed or not by isLogObj function, according to which the passed object is treated as LogObject if it has either message and args property.

This is why your code

logger.info(test.count('a', 'b'))

shows ℹ a b instead of formatted whole object.

---

Fortunately, Consola provides a bypass. You can call instance.method.raw() to skip LogObject detection (this isn't either well documented at the moment).

So, the code below will show what you want (I tested in my local).

logger.info.raw(test.count('a', 'b'))

---

By the way, would you keep this issue open so that we can handle documentation issue later?

[baronyoung]

Got it. Thank you. Yes, I will keep it open.

[baronyoung]

What would be nice is if when creating my 'logger' instance: 'const logger = consola.withTag('x')' there would be another method which would cause the default usage to use 'raw' on everything. For example: const logger = consola.withTag('x').alwaysRaw It's rare I want special behavior based on what object I pass as opposed to just wanting to log output.