Built-in type definitions / JSDoc

[scripthunter7]

Built-in type definitions / JSDoc

[lahmatiy]

I tried to rewrite CSSTree in TypeScript a couple of times. Add typing for List and other utils is quite a trivial problem that does not cause difficulties. However, a complex parts, like parser, are very non-TypeScript friendly due to their flexibility. At the moment, there is a choice, either typings or flexibility. Flexibility means the posibility of fork() method and the ability to provide specialized entry points (like css-tree/selector-parser).

The fork() method allows create an altered instance of API. For instance, you can extend parser, lexer and generator to work with new types of AST nodes, or alter parsing/serialization rules. This feature is used by other libs to add new syntax support or some kind of support for preprocessor's syntax (for instance in stylelint-validator - Saas and Less).

I'm still thinking about how to add TS typing and keep it flexible. For now, flexibility is more important than typing or performance.

[scripthunter7]

Add typing for List and other utils is quite a trivial problem that does not cause difficulties. However, a complex parts, like parser, are very non-TypeScript friendly due to their flexibility

I can confirm this 😅

Another main topic of my issue is JSDoc. Unfortunately, the code is documented in very few places. For example, there is a lot of "this" that needs to be debugged to see where it comes from through which binding. For example, when creating types, I should know what the basic code does, but as I reach more and more "flexible" codes, this becomes an increasingly difficult task.

The use of "this" also occurs during fork implementation, although I could deduce what it is based on the core code.

At the moment I was "only" talking about documentation and .d.ts files. In my opinion, full TS porting is only possible by breaking change. I think flexibility can be maintained in TS as well, but in a completely different way.