Plugin authoring: Combine @inline and @interface

[LekoArts]

Hello!

In context of #2923 I've got another question that I decided to pull out since I think it can be interesting for others (including people finding this through Google).

Basically, my problem is that I want to combine @inline and @interface.

I have a union type like so:

/**
 * @interface
 */
export type UseExampleReturn = 
| {
  /**
   * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
   */
  isLoaded: false;
  /**
   * A boolean that indicates whether a user is currently signed in.
   */
  isSignedIn: undefined;
  /**
   * The current user's role in their active organization.
   */
  orgRole: undefined;
}
| {
  isLoaded: true;
  isSignedIn: false;
  orgRole: null;
}
| {
  isLoaded: true;
  isSignedIn: true;
  orgRole: null;
}
| {
  isLoaded: true;
  isSignedIn: true;
  orgRole: OrganizationCustomRoleKey;
};

With this I get my desired behavior of @interface to discard properties and converting "dynamic" values. However, when I add an @inline to the code block they are not combined.

/**
 * @interface
 * @inline
 */
// ...

I suppose it's intended behavior and I'm fine with creating a custom plugin that looks for a custom tag like @inlineInterface.

I found #2654 and created this so far:

// @ts-check
import * as td from "typedoc";

const INLINE_EXPAND_TAG = '@inlineInterface'

/** @param {td.Application} app */
export function load(app) {
  app.on(td.Application.EVENT_BOOTSTRAP_END, () => {
    const tags = [...app.options.getValue("modifierTags")]
    if (!tags.includes(INLINE_EXPAND_TAG)) {
      tags.push(INLINE_EXPAND_TAG)
    }
    app.options.setValue("modifierTags", tags)
  })

  app.converter.on(td.Converter.EVENT_CREATE_DECLARATION, (context, decl) => {
    const symbol = context.getSymbolFromReflection(decl)

    if (!symbol || !decl.comment?.hasModifier(INLINE_EXPAND_TAG)) {
      return
    }

    decl.comment.removeModifier(INLINE_EXPAND_TAG)

    const type = context.checker.getDeclaredTypeOfSymbol(symbol)
    decl.type = context.converter.convertType(context.withScope(decl), type)
  })
}

Inside the source code I think I found the code paths I'd want to use:

• convertTypeInlined is getting called when shouldInline is true. Which is the case when @inline modifier tag is set
• convertTypeAliasAsInterface is getting I used (afaik) with @interface to get my desired behavior of turning "dynamic" unions into one.

I'm not quite understanding how I could use convertTypeAliasAsInterface in the @inline codepaths. Is the EVENT_CREATE_DECLARATION event even the correct event?

I'd be super happy if you could give me guidance on putting the pieces together 😊 I don't need the finished plugin necessarily, pseudo-code or instructions on what to use would already be great!

[Gerrit0]

Ick! These tags were never intended to be combined in any way. @interface is a directive for the symbol converter, while @inline is a directive for the type converter.

Inlined types will not use the converted type from when the type alias is converted, it will convert the type directly there (to handle generic types), so your plugin can't just replace the contents of the type, so listening to EVENT_CREATE_DECLARATION for the UseExampleReturn type and replacing it's type won't be sufficient for what you want.

TypeDoc does not expose an API for plugins to change how it converts types, and also doesn't expose anything for easily replacing components of types, so doing this in a generic way isn't exactly easy... given that your code likely uses this type as a top level type, however, you can just check the converted types after TypeDoc has converted it. In that case, since this is for a function return type, you want EVENT_CREATE_SIGNATURE (function/method signatures live inside of declarations so that overloads can have multiple cases)

In that event, you should check things like your example code already does, but instead of the call to convertType, do something similar to the typeLiteralConverter to construct a ReflectionType.

The createSignature and convertIndexSignatures calls there are not exposed today... I'm not sure I want to expose them without thinking about the API more either. TypeDoc's type converter was really intended to be a black box, not something that plugins do things with...

[LekoArts]

Thank you for the detailed response, appreciate it!

When writing the post I knew it's not really supposed to be combined but that the time that was what I wanted as an output 😅 The combination of this challenge and reflecting a bit more on concise vs. verbosity, my approach has changed a bit. Most probably I'll not need that plugin after all as others on my team noted, too, that we should lean towards verbosity.

I think I'll try it anyways just for fun though and to get more familiar with Typedoc plugins. If time allows I'll afterwards add some more examples to the docs on how to create a plugin 😊