Typescript Definitions and Usage Examples

[jmfirth]

This pull request adds annotated TypeScript definitions and usage examples. Changes include:

• TypeScript definitions, strictly defined, with comments.
• TypeScript usage examples in strict mode showing inferred use with commented types, with invalid usage examples.
• Package script to validate TypeScript definitions and usage examples instrumented to run concurrent to existing unit tests.

Notably, the definitions were created to prevent invalid usage. So, the following constraints were encoded in the type system:

• Filter properties should not be used when canFilter is not set to true. (example)
• onChange is properly typed based on value of simpleValues. (example)

Unfortunately of these constraints depend on a feature called conditional types which is slated to be released along with TypeScript 2.8 in March. This is why [email protected] was added as a development dependency. I tried to type these constraints in other ways, such as combining the property groups as intersections of discriminated unions, or using mapped types to map the value of canFilter and simpleValues to an index I could leverage to provide types for other properties, but I was not able to satisfy TypeScript 2.7.1 and the conditions properly.

Obviously this isn't something you'll want to ship today, and the TypeScript semver range will need to be adjusted when 2.8 is released, but they will be here for then. If these constraints were unwanted, or otherwise removed, these definitions would be compatible with (I believe) at least TypeScript 2+.

[jakezatecky]

Thanks for the PR. I'll look into merging this then when the March release comes along. I have effectively no experience with TypeScript, but I have no issue adding support definitions to help other developers use this library.

[nystromb]

I am working on a project that could use this. Are there still plans for this to be released?

[Kimahriman]

If the maintainer doesn't have TypeScript experience it makes more sense to put these in DefinitelyTyped. Unless @jakezatecky wants to learn about it and start maintaining the TypeScript definitions