fix: typescript types

[Zamiell]

Fixes #1782

The PR causes an error in one of the existing tests:

It's line 312 in "pino.test-d.ts". I don't understand the error or what it is supposed to be testing. Can anyone shed some light on this?

EDIT:

• See THIS COMMENT if you are here about logging in try / catch blocks or logging unknown.
• See THIS COMMENT if you are here about providing the first generic type param to the logger in order to validate an object.

[Zamiell]

Oh, I think I understand the error, due to my changes the TypeScript compiler is actually catching the runtime error that the code is intentionally performing, LOL.

[Zamiell]

There is a "breaking" change in this PR (depending on how exactly you want to define breaking) such that you can no longer use the first generic type parameter as a means to validate the object that you are passing. Users should be directed to use the satisfies operator instead in the patch notes for the next release.

(satisfies was released as part of TypeScript 4.9 on November 15th, 2022. Now that it exists, it makes sense to validate your objects with satisfies like you would with any other TypeScript code and to not provide library-specific hacks to do it.)

[mcollina]

lgtm, good work!

[Zamiell]

Oh, looks like the tests are failing because the version of TypeScript is too old to have the satisfies operator. Do you want me to do a separate PR that upgrades TypeScript?

[kibertoad]

@Zamiell yes, please!

[Zamiell]

Actually, on second thought, the version of TypeScript is really recent.

Can someone click the button to re-run CI for me (since I'm a first time contributor)?

[Zamiell]

From the CI logs:

 ✖  278:2   Cannot find name satisfies.     

But according to the package.json file at the root of the repository, the version of TypeScript is 5.1.3, which should have the satisfies operator, which was introduced in TypeScript version 4.9.0. Thus, I conclude that the CI is running on an old version of the dependencies, so something in this repo is broken with respect to caching and/or node_modules, which is outside of the scope of my types PR.

Can a maintainer take a look at this please?

[mcollina]

lgtm

[Zamiell]

@mcollina Can we work to get this merged? It's been sitting for a while.

[mcollina]

I don't have time to investigate at the moment Happy to land with a green CI.

[Zamiell]

@mcollina Can we get another maintainer to investigate? I'm fairly certain that the errors in CI are not related to my PR.

[mcollina]

CI is passing on master, please rebase

[Zamiell]

CI is passing on master, please rebase

I'm aware of that, I am talking about the CI errors inside of this pull request. Can we get another maintainer to investigate?

[jsumners]

You need to rebase this PR.

[Zamiell]

@jsumners I rebased this PR onto master just now. Let me know if anything additional is required.

[mcollina]

CI is failing

[Zamiell]

@mcollina Sorry, I think we are looping. Yes, CI is failing for the same reason that I posted in my reply on October 4th here: #1783 (comment)

This reply explains why the errors are not part of my PR and why I think that a maintainer needs to investigate: #1783 (comment)

To recap, in response to asking for a maintainer to look at the logs, it was requested that I rebase the PR on main, which I have now done, but CI still gives the same error, so we are back to square 1, and I would ask again that a maintainer please take a look at these logs, as they do not seem related to my PR!

[jsumners]

What I can tell you is that npm run test-ci works locally on the main branch, but it fails on this branch.

[Zamiell]

@jsumners It fails on this branch because I am using TypeScript's satisfies operator in my PR, which is not present in the codebase otherwise. As I explained in a previous comment in this thread, the satisfies operator was added in TypeScript version 4.9.0, and the version of TypeScript that is used by this package is 5.1.3. Thus, CI should not be throwing an error about the satisfies operator, so I conclude that your CI is drunk. Possibly a caching issue of some kind?

[kibertoad]

I can take a look on Monday

[Zamiell]

Looks like CI is green now, finally.

The fact that tsd uses its own version of TypeScript seems really weird. Naively I would expect it to be a peer dep and let the user bring their own version. But I'm seeing that it supports testing against multiple versions of TypeScript, so I guess that is the justification.

[beemdvp]

fyi these typing changes really should've been a major bump even if they're a "fix". This has broken an app in pipeline for production use. Guess we shouldnt really trust any package to respect semantic versioning but still

[kibertoad]

@mcollina I think we should revert.

@beemdvp can you share the code example that got broken? we need to expand our testsuite, it seems.

[beemdvp]

@kibertoad it was a minor thing but I'd rather deal with updating types in a separate story I'm working on. Previously we were allowed to log unknown (default type in catch block) types as well but as you can imagine, I had to find that out from this release and its a pain to change every single line in the same PR im working on at work

[mcollina]

Given that typescript or DefinitelyTyped does not support semantic versioning, how could anybody expect types to stay stable?

[kibertoad]

@mcollina Fair point.

Not being able to log unknown anymore sounds like a regression to me, as it's a very common and very useful use-case.

@beemdvp would you be open to send a fix PR for it?

[mcollina]

Not being able to log unknown anymore sounds like a regression to me, as it's a very common and very useful use-case.

Generically this seems like a bad idea. Basically you want to log something that you know nothing about, and expect everything to be safe. This seems a good case for a warning, because... who knows what's in that unknown?

[arijnr]

Hi everyone.

I wanted to let you know that I also had problems during a deployment to production due to changes in this PR that are now available in version 8.17.0.

For now I will have to use the previous version.

[kibertoad]

@mcollina realistically in 99.9% cases catch block will return an error. in 0.1% it'll be a string. pino can log both of them just fine.

obviosly people can log unknown in other cases too, but I'd say that it shouldn't be on pino to hand-hold against it

[mcollina]

Agreed. However I don't think it's possible to support unknown while validating the interpolation arguments.

[Zamiell]

However I don't think it's possible to support unknown while validating the interpolation arguments.

To give more context here, currently the LogFn is typed as a bunch of overloads. Adding an overload to handle unknown at the top would match everything, making all the overloads below it useless (at least for one arg). And adding an overload for unknown at the bottom would match everything, resulting in 0 type errors. So in either case, the following code would not error, because it would be caught by the unknown overload:

// We want this to be a type error, because we forgot to supply the string corresponding to "%s",
// but it matches: `(arg: unknown) => void`
logger.info("hello, %s");

in 99.9% cases catch block will return an error. in 0.1% it'll be a string. pino can log both of them just fine.

You're right. In these cases, I recommend changing the following code:

try {
  dangerousFunc();
} catch (err) {
  logger.error(err)
}

To this:

try {
  dangerousFunc();
} catch (err) {
  logger.error(err as never)
}

But we should remember that the whole point of unknown is that you are supposed to type-narrow it. So the more-correct and more-safe solution is to abstract the check into a new helper function that you can use throughout your codebase. Something along the lines of:

/**
 * Helper function to narrow an unknown value to an object (i.e. a TypeScript record).
 *
 * Under the hood, this checks for `typeof variable === "object"`, `variable !== null`, and
 * `!Array.isArray(variable)`.
 */
export function isObject(
  variable: unknown,
): variable is Record<string, unknown> {
  return (
    typeof variable === "object" &&
    variable !== null &&
    !Array.isArray(variable)
  );
}

/** Helper function to log an `unknown` value in a type-safe way using type-narrowing. */
export function logError(err: unknown) {
  if (typeof err === "boolean" || typeof err === "number") {
    logger.error(err);
  } else if (typeof err === "string") {
    logger.error(err);
  } else if (isObject(err)) {
    logger.error(err);
  } else {
    // Pino only supports booleans, numbers, strings, and objects, so convert this to a string.
    const msg = `${typeof err} - ${err}`;
    logger.error(msg);
  }
}

// --------------------------------------------------------

try {
  dangerousFunc();
} catch (err) {
  logError(err);
}