Attempting to exclude string literals from string is a no-op. This would be best left as the catch-all signature that already exists.

Actually, using type parameter will make it work. See https://tsplay.dev/mpdeMm.

And the original discussion points out that

When using chacha20-poly1305 without setting authTagLength, TypeScript incorrectly reports that getAuthTag does not exist on the Cipher type.

This is because with original plain string type, when none the above overloads get passed, the function call would get into the last one. There, the last options argument is allowed to be omitted, and hence Cipher return type is inferred, hence causing the issue.

If you checkout the branch locally and switch it back to the original plain string type, you will see the newly added tests fail like the original post suggests.

To resolve the issue, I think original plain string type has to be modified.

Your added overload solves the linked issue by itself, without any need to alter the catch-all here.

Unrelated to the linked issue, the separate behaviour that you're trying to address here is the notion of permissive catch-all signatures within the library, which is much wider than this one specific example.

In general, @types/node goes for a permissive approach when it comes to overloaded function signatures and catch-alls. Given that changing this behaviour is breaking, and that the existing catch-all behaviour of createCipherIv() has existed ever since the narrowed overloads were first added (over 6 years ago) with no complaints from consumers, I think the best approach is to leave this as-is.

(Let me move the discussion back to this thread...}

Given that changing this behaviour is breaking, and that the existing catch-all behaviour of createCipherIv() has existed ever since the narrowed overloads were first added (over 6 years ago) with no complaints from consumers, I think the best approach is to leave this as-is.

I would say I kind of disagree with this.

With the current behaviour, createCipherIv() types basically does not fully reflect the intention of its respective source code. Just like in this case, one working with CipherCCMTypes for sure expect tsc to pick up the corresponding function signature to typecheck.

function createCipheriv(
    algorithm: CipherCCMTypes,
    key: CipherKey,
    iv: BinaryLike,
    options: CipherCCMOptions,
): CipherCCM;

Hence a missing options will simply fails, instead of going to the catch-all fallback one, which is both misleading and incorrect in nodejs source code's point of view.

I would argue that, doing it in the way you mentioned simply brings unneeded confusion to typescript consumers (especially those who are not familiar enough with the "permissive approach" you suggest). Like in this case, without reading till the end of all the overload typedefs, it is not even easy to see the exact cause of the issue raised by the original post.

Given that changing this behaviour is breaking

It should be fair to say that, any breaking behaviour caused by this change is due to insufficient typescript familiarity on consumer side.

From the notion of discriminated unions in typescript, together with the fact that the function overloads are basically "partitioned" by the algorithm parameter, it should be natural for anyone to reach to the same understanding and expectation on the typing behaviour as I do.

Hence if any unfortunate breaking behaviour indeed happens, it would be those consumers' fault on not observing basic principle in typescript.

@types/node prioritises allowing valid practice over being restrictive – it has to be this way, as a dependency of hundreds of millions of projects.

Yes, this slightly hacky overload might seem like it does what you want it to do, but then the day after pushing it, someone will come along with usage like the following:

function encrypt(
  data: crypto.BinaryLike,
  key: crypto.CipherKey,
  algorithm: crypto.CipherCCMTypes | crypto.CipherGCMTypes
) {
  // ...
  const cipher = crypto.createCipheriv(algorithm, key, iv);
  // ...
}

and come here to report that their case, which previously worked just fine (and is valid usage as far as the Node API goes), now results in a compiler error. There aren't a huge number of examples of this sort of usage that I can see for a brief search through Github, but the point is that there's no compelling motivation to break them.

Ok... I have reverted this change of using template. Please help review again.

Your added overload solves the linked issue by itself, without any need to alter the catch-all here.

Unrelated to the linked issue, the separate behaviour that you're trying to address here is the notion of permissive catch-all signatures within the library, which is much wider than this one specific example.

In general, @types/node goes for a permissive approach when it comes to overloaded function signatures and catch-alls. Given that changing this behaviour is breaking, and that the existing catch-all behaviour of createCipherIv() has existed ever since the narrowed overloads were first added (over 6 years ago) with no complaints from consumers, I think the best approach is to leave this as-is.

Nit: This type is probably semantically unnecessary – by definition, the only type that would ever fit the definition of a ChaCha20Poly1305 type is chacha20-poly1305. This can probably be removed, in favour of just using the string literal in the function parameter.

Extracting it is better I think. Repeatedly working with string literal may result in typo in string content, but CipherChaCha20Poly1305Types as a ts type under tsc typecheck won't have such issue.