make yargs' simple types available to community

[bcoe]

Problem

If yargs ships its types, which a significantly simpler (by design) from those defined in @types/yargs, it will break the existing TypeScript user-base.

Some users would like access to yargs' types.

Question

Is there a way we can provide yargs' types to the community, such that they're as easy to install as @types/yargs, and can be used as an alternative?

Refs: #1749, #1586

[bcoe]

@dalcde @AviVahl moved the conversation here. One thing I would be open to, would be publishing yargs' simplified types, if we could find a way to do so that's ergonomic.

Publishing them in the library itself, the way TypeScript resolves types, I believe breaks the existing community (also, it bloats the library size quite a bit).

[dalcde]

I personally believe this is what semver is designed for. Ultimately, you are going to break *something* by doing this. People who didn't import @types/yargs previously could have incorrectly typed code that now doesn't compile. And if you are eventually going to make a breaking change, might as well break now.

[bcoe]

@dalcde the thing is, I think a lot of folks wouldn't be happy making the switch to the types we're using for development. @types/yargs is more full featured from a type definition perspective. It does fancy things like typing yargs' outputs, based on the configuration.

[dalcde]

Is it impossible to produce such a typing via typescript?

[bcoe]

@dalcde the "perfect world" generics defined in @types/yargs are much more complex than the types in the library itself.

It would be a huge amount of work to make them match. We started down this path, but it honestly also makes the codebase very hard to read and update -- as generics are ugly.

[wemeetagain]

👍 for publishing the types alongside the source code.

Separately publishing manually crafted types can and does lead to type mismatches. Manually crafted types also require labor to keep the types in sync. The whole headache just not necessary when the library is already written with typescript, and types can be emitted that perfectly describe and naturally stay in sync with the implementation interface.

[shadowspawn]

I had a similar but inverse problem in Commander, where the widely used types are the simple ones and I wanted to make available some fancy generic types. The approach I came up with was to create a wrapper package which can be used in place of the original package, and just calls through to the original for the implementation (and has the original as a peer dependency). The sole purpose of the wrapper package is to transparently provide different TypeScript definitions.

Potentially the internally generated TypeScript definition file for Yargs could be copied into the wrapper project for each release of Yargs.

This is a bit clunky, but potentially meets the goals. Rather than installing alternative types, the end user installs an alternative package:

Is there a way we can provide yargs' types to the community, such that they're as easy to install as @types/yargs, and can be used as an alternative?

(May well be more maintenance work than justified by the demand!)

[steve-taylor]

@types/yargs is more full featured from a type definition perspective.

Those types leave a lot to be desired. They keep releasing breaking changes on patch versions. It would be a much better situation for yargs to be written in TypeScript, then the type definitions are always correct and in sync.

Publishing them in the library itself, the way TypeScript resolves types, I believe breaks the existing community

That's what major versions are for. Everyone on yargs <= 17 uses DefinitelyTyped. Everyone else gets the correct types.

[shadowspawn]

To clarify, Yargs is now written in TypeScript. But it uses straight-forward types and no type inferences, so the internal types are not directly equivalent to the DefinitelyTyped typings.

As a particular example, the parse results do not infer the argument names and types, they just include a map of [argName: string]: any. Does that still meet your desire for "correct types"?

yargs/lib/yargs-factory.ts

Lines 2407 to 2416 in e517318

	export interface Arguments {
	/** The script name or node command */
	$0: string;
	/** Non-option arguments */
	_: ArgsOutput;
	/** Arguments after the end-of-options flag `--` */
	'--'?: ArgsOutput;
	/** All remaining options */
	[argName: string]: any;
	}

[shadowspawn]

Jest has started making its own types available for direct import as an alternative to the ones from Definitely Typed:

• https://jestjs.io/docs/getting-started#type-definitions
• feat: add @jest/globals package for importing globals explicitly jestjs/jest#9801