More precises return types for `Plot.plot` depending on the given `PlotOptions` parameter content

[eschalkargans]

First of all, thank you so much for having added types! I'm so happy to see that this lib is now TypeScript-friendly.

I'm creating this issue to share an issue that I encountered in my codebase, and is likely to be encountered by others, that could lead to an improvement of the type definitions.

My situation

I have functions that wrap the Plot's API, like such:

export const createBarYChart = (
  data: ChartDateIndexedNumberSample[],
  width: number,
  height: number,
  ordinate: string
): HTMLElement => {

There was no issue before the types were added, because the typing was not enforced by the Observable Plot lib. This means the typing was only informative, for me, and was not an actual contract.

Since the types addition, I know see that my function definitions were actually wrong!.

Here is the error I get, as shown in VSCode:

const plot: (HTMLElement | SVGSVGElement) & Plot.Plot
Type '(HTMLElement | SVGSVGElement) & Plot' is not assignable to type 'HTMLElement'.
  Type 'SVGSVGElement & Plot' is missing the following properties from type 'HTMLElement': accessKey, accessKeyLabel, autocapitalize, dir, and 20 more.ts(2322)

The cause

When navigating to the Plot.plot type definition, here is what I see:

/**
 * Renders a new plot given the specified *options* and returns the
 * corresponding SVG element, or an HTML figure element if a caption or legend
 * is requested.
 */
export function plot(
    options?: PlotOptions
): (SVGSVGElement | HTMLElement) & Plot;

So, the (SVGSVGElement | HTMLElement) part of the return type is conditional, and can be summarized like this (this is pseudocode, not corresponding to the actual type definitions):

ReturnType = HTMLElement if (caption in PlotOptions) or (legend in PlotOptions) else SVGSVGElement

I already know in my call to Plot.plot that I do not use a caption nor a legend, so it would be great to get a SVGSVGElement return type rather than the union, to avoid type assertions.

How TypeScript could help

If I know in advance, by only reading my code that I expect a SVGSVGElement, there must be a way to communicate it to the TypeScript compiler.

Maybe Conditional Types could help, or function overloads?

Regarding caption:
We can check the presence of the caption property immediately in the PlotOptions.

Regarding legend:
This one is more tricky as it can be present at multiple places, and on nested interfaces in PlotOptions (eg in ScaleOptions).

Note: I am really not sure how this "conditional return type" could be implemented, or if it is feasible in the first place. Anyway, I think that the interface can be more explicit about what kind of object it returns!

[Fil]

Plot says that it will return either an HTML or an SVG element.

Perhaps you can tell the compiler that you're pretty sure it will be a SVG element like so:

export const createBarYChart = () => Plot.plot({…}) as unknown as HTMLElement;

Then you know that it is an assumption that your code is making, and that it might be void when Plot’s implementation changes (maybe with #423, for example).

A more type safe approach might be to check the tagName of the returned plot, and assert that it is indeed a svg element:

export const createBarYChart = () => {
  const plot = Plot.plot({…});
  if (plot.tagName !== "svg") throw new Error("Plot changed! Do something about it.");
  return plot as unknown as HTMLElement & Plot.Plot;
}

Another way of seeing the issue is to accept Plot's types, and prepare your app for the case when what Plot returns is an HTML (figure) element.

[mbostock]

I do not think it will be possible (practical) to determine statically whether Plot.plot will return an SVG element or an HTML element.

It does not depend solely on the top-level caption option, and there is no top-level legend option—there is instead a scale.legend option on various scales (currently color, symbol, and opacity, but perhaps r and length will have the option in the future). Also checking caption in PlotOptions wouldn’t work because you can set this option to null (and likewise legend to false). And as @Fil says, the default behavior may change over time, and the number of options that affect whether Plot returns an HTML or SVG element will almost certainly increase over time.

If you want to guarantee an HTML element, you could always wrap Plot’s result in a figure element. Or you could change your types to return HTMLElement | SVGSVGElement. Or you could add a type assertion as @Fil describes (though it’d be good to confirm that you’re asserting the correct type if you do so!).