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.

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()],
};

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"
  }
}

Complex types

The plugin parses complex types, such as union, intersection, and generic types. It also supports Enums and TypeScript’s utility types.

type Test1 = "value1" | "value2" | "value3";
type Test2 = "value4" | "value5" | "value6";

type UnionType = Test1 | Test2; // "value1" | "value2" | "value3" | "value4" | "value5" | "value6"
type ExcludeUnionType = Exclude<Test1 | Test2, "value1">; // "value2" | "value3" | "value4" | "value5" | "value6"
type GenericType<T> = T | Test1; // T | "value1" | "value2" | "value3"
type MyGeneric = GenericType<Test2>; // "value4" | "value5" | "value6" | "value1" | "value2" | "value3"
enum DirectionEnum {
  Up,
  Down,
  Left,
  Right,
}; // 0 | 1 | 2 | 3
type DirectionOptions = keyof typeof DirectionEnum; // "Up" | "Down" | "Left" | "Right"

Limitations

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.

Configuration

There are a few ways you can configure the plugin to meet your environment.

type Options = {
  /** Determines the name of the property used in the manifest to store the parsed type */
  propertyName?: string;
  /** Shows process logs */
  debug?: boolean;
  /** Prevents plugin from executing when true */
  skip?: boolean;
}

Property Name

The default property name that the values are assigned to is parsedType. If you want to change that, you can do so by passing the propertyName option.

custom-elements-manifest.config.js

export default {
  ...

  /** Provide custom plugins */
  plugins: [typeParserPlugin({ propertyName: "expandedType" })],
};

Once that has been updated, the parsed type will appear under the new property name.

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

NOTE: As you can see in the example above, the structure will follow the same pattern as the type object in that your custom name will have a property called text.