Typing renderable values

[patorpey]

I migrated an application to Lit 2.0 from the previous version when Lit 2.0 was released. One of the areas where we encountered some friction is related to changes in the return type for render() and TemplateResult. This project has the eslint rule @typescript-eslint/explicit-function-return-type enabled, which we find useful to ensure that we are returning a value of the expected type.

In the previous version of Lit, our render() methods and functions that render partial templates were typed as returning either TemplateResult or TemplateResult | nothing. This has proven adequate in Lit 2.0 for many of our elements, but quite problematic for some.

It took me a while to make sense of some of the types that were showing up in warnings during the migration, such as:

Type '(unique symbol | TemplateResult<1>)[]' is not assignable to type 'TemplateResult | unique symbol'.
Type '(unique symbol | TemplateResult<1>)[]' is not assignable to type 'unique symbol'.ts(2322)

I had to dive into the Lit source to fully appreciate what the now-parameterized TemlpateResult<1> referred to.

In the source and API documentation I see that the return type of render() is unknown. Certainly, using that type in our classes is a quick way to avoid the errors, but it feels like it undermines the type checking to ensure that a function returns a reasonable and expected type for a template.

Instead, I tried creating types that represent renderable values, but it gets quite hairy:

type Renderable = TemplateResult | DirectiveResult | string | nothing;
type RenderableGroup = Renderable | Renderable[];
type DirectiveRenderable = Renderable | noChange;
type DirectiveRenderableGroup = RenderableGroup | noChange;

public override render(): RenderableGroup { /* ... */}

There are very likely reasonable permutations that these unions overlook. I opted for just going with unknown, for now, and I assume that this complexity is the reason renderable values are unknown in many places in the Lit source.

I was wondering if there are any recommendations for typing the return value of render() functions or plans to, at some point, introduce a more unifying renderable type than unknown.

[kevinpschaaf]

The reason that render() is typed as unknown is that lit will happily render any value. For example, it's perfectly valid to pass {toString() { return 'hi!'; } as a value to an expression, and lit will end up rendering the toString() value of it. So there is not a specific narrowing of types that Lit requires be passed to an expression.

If in your codebase you'd like to exclude certain types from the universe of values lit will render, the approach of defining type aliases to that subset seems perfectly reasonable.