WC Toolkit Type Parser

Using type aliases to define the types for your component’s APIs, can be helpful for keeping your code clean and organized as well as making your types reusable.

The down-side is that it can be difficult to integrate with other tooling or communicate in documentation what the available options are. This plugin parses the types so they available in a more usable format.

Installation

npm i -D @wc-toolkit/type-parser

Usage

Using type aliases to define the types for your component's APIs, can be helpful for keeping your code clean and organized as well as making your types reusable.

// my-component.ts

type Target = "_blank" | "_self" | "_parent" | "_top";

class MyLink extends HTMLElement {
  target?: Target;
}

This plugin parses the types for your component APIs in Custom Elements Manifest using the Custom Element Manifest Analyzer.

If a type cannot be safely expanded, such as a recursive or overly complex external type, the plugin keeps the original type text and logs a warning with the type name, declaration location, and reason it was skipped.

// custom-elements-manifest.config.js

import { getTsProgram, typeParserPlugin } from "@wc-toolkit/type-parser";

export default {
  ...
  // Give the plugin access to the TypeScript type checker
  overrideModuleCreation({ts, globs}) {
    const program = getTsProgram(ts, globs, "tsconfig.json");
    return program
      .getSourceFiles()
      .filter((sf) => globs.find((glob) => sf.fileName.includes(glob)));
  },

  // Add the plugin to the config
  plugins: [typeParserPlugin()],
};

Options

The plugin accepts a configuration object:

plugins: [
  typeParserPlugin({
    // 'none' (default), 'partial', or 'full'
    parseObjectTypes: "full",
    // Whether to parse method parameter types (default: false)
    parseParameters: true,
    // Name of the property that stores the parsed type (default: "parsedType")
    propertyName: "parsedType",
    // Maximum depth to expand nested types before bailing (default: 8)
    maxParseDepth: 8,
    // Maximum number of properties a type can have before bailing (default: 50)
    maxParseProperties: 50,
    // Shows output logs used for debugging
    debug: false,
    // Prevents the plugin from executing
    skip: false,
  }),
];

Result

It doesn't overwrite the existing property, but will create a new property with the parsed type value.

// custom-elements.json

{
  "kind": "field",
  "name": "target",
  "description": "A lookup type for example",
  "attribute": "target",
  "type": {
    "text": "Target | undefined"
  },
  "parsedType": {
    "text": "'_blank' | '_self' | '_parent' | '_top' | undefined"
  }
}

Be sure to check out the official docs for more information on how to use this.