How to handle types

When documenting a field of a custom element, we definitely want to describe it’s type. Before TypeScript came along we almost would have certainly would have use JSDoc-style type annotation syntax, but TypeScript’s type syntax might be more commonly known by now though.

So we could use that in the descriptor, for example:

{
  "members": {
    "foo": {
      "kind": "property",
      "type": "Array<number|string>"
    }
  }
}

But at the limit you need to support many TS-specific, non-concrete entries like interfaces and type aliases so that you can use them in types. Does this mean we should leave types completely out of the format and up to .d.ts files? That would degrade the usefulness for documentation tools that don’t process type declaration files. TS declaration files are also harder to parse than JSON, requiring the whole TypeScript compiler.

Another option is to include much of the type-related information parsed by Microsoft’s API Extractor: https://github.com/microsoft/rushstack/tree/master/apps/api-extractor

Since this tool produces JSON, it would be relatively easy for custom-elements.json generators to use it to parse TypeScript, then merge with it’s own custom element specific parsed metadata.

[daKmoR]

For documentation purposes, it would be good enough to keep types more as “type hints”. e.g. to give an idea of what it should be… it does not need to be a “real” type.

Examples:

• String (e.g. foo, bar, …)
• Number (e.g. 1, 4342, …)
• Color (e.g. #fff, orange, rgb(255,0,0), …)
• Css Length (e.g. 10px, 10rem, …
• Array (does NOT type content)
• Object (does NOT type content)

REAL type support I would consider out of scope and should be handled separately by searching for *.d.ts files.

So many tools will be fine with only custome-elements.json. e.g. documentation, playgrounds, catalog, …

Some tools will need to “gather” more data to also give type safety. e.g. linters, editor plugins, …

[thepassle]

What about making a type declaration type,

I’d really prefer to stay as far from this as possible and avoid becoming an alternative/substitute for type declaration files.

iirc, if useSubscription is a function, that means the CEM should already list its return type, right? Function params/return types are supported by the current schema?