TypeScript typings

[sgratzl]

Feature Proposal

follow up from #6598 (comment)_

Feature Use Case

provide typescript typings directly as part of chart.js (3)

Possible Implementation

starting points are:

• https://github.com/sgratzl/chartjs-esm-facade/blob/master/src/index.d.ts
• https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/chart.js/index.d.ts

open questions:

• which directory structure should the typings follow: one huge file, per existing source file, in a separate directory, next to the source, ...
• where is a documentation which options are available for different elements/controllers?

[benmccann]

Thanks for leading the charge on this!

which directory structure should the typings follow

I personally don't have a strong opinion on this except to say that I'd like it if we could also add tests for the typings and consider the directory structure of where the tests will go

where is a documentation which options are available for different elements/controllers?

The code might be the best source for this. The only other thing we have is https://www.chartjs.org/docs/master and https://www.chartjs.org/docs/master/typedoc. I believe @stockiNail has been going through and trying to identify places where the docs do not match the code

[sgratzl]

honestly, now sure how to test the typings. There is

• https://github.com/Microsoft/dtslint which tests whether the typings will make sense.
• https://github.com/SamVerschueren/tsd does a similar thing

However, I don't know how to test whether JavaScript matches the TypeScript typings

[benmccann]

I'm not an expert in this area, but here's what I've seen done in one of the plugins: https://github.com/chartjs/chartjs-plugin-datalabels/tree/master/types/test

[jonrimmer]

Awesome that this is happening!

This is my sketch of how the types could potentially be structured: https://github.com/jonrimmer/Chart.js/tree/types-experiment

• Add an index.d.ts to each level of the src hierarchy defining and exporting the equivalent types from that directory's index.js.
• Using rollup-plugin-dts to bundle those .d.ts files into a single index.d.ts file in the dist folder and the package.json's files.

For this I more or less copied-and-pasted and the types from @types/chart.js into src/core/index.d.ts.

[etimberg]

One thing that would be nice in the typings would be to allow templating the data object type. If I know my data is x/y points of numbers, I wouldn't want to have to guard that everywhere. We'd want to provide a good default, but it'd be pretty verbose since we allow a lot as evidenced by data?: Array<number | null | undefined | number[]> | ChartPoint[]; in the existing type definitions. I'm sure this complicates things, but would really help with the usage.

type DataPoint = {
  x: number;
  y: number;
};
type MyDataset = {
  label: string;
  data: DataPoint[];
};
type MyChartData = {
  datasets: MyDataset[];
};

...

const chart = new Chart<MyChartData>(ctx, {
  data,
});

// Now chart.data is of type MyChartData

Another problem I ran into with the existing types is that a lot of things are marked as potentially undefined (e.g. ChartTooltipItem.dataIndex) but I'm pretty sure a number of those can never be undefined given how the code is written.

[etimberg]

In terms of getting types into master, rollup-plugin-dts looks pretty good. My only concern would be with how the options type definition is composed. src/plugins/plugin.tooltip.d.ts would need to define all of the config options for tooltips, but something else would compose them together into the overall chart options by importing the types. I suppose the plugin handles that case, but would be good to confirm

[jonrimmer]

That's a good point. I see three options:

1. Just use a single definition file and no bundling. Simple but a bit unwieldy.
2. Compose the types as suggested. I don't see any reason why this wouldn't work, although it would require breaking things up beyond just the directory-level in order to avoid circular dependencies. I.e. core/Chart.options.legend using plugins/ChartLegendOptions, which in turn imports types like ChartColor from core.
3. Use Declaration merging. So, different files would declare the same interface:

// core/index.d.ts
interface ChartOptions {
  responsive?: boolean;
  // ...
}

// plugins/index.d.ts
interface ChartOptions {
  legend?: ChartLegendOptions;
}

And since these are both bundled into the same file, declaration merging would create a unified interface. Unfortunately, rollup detects the duplicate names and mangles one of them, because it's really intended for bundling JS, where this kind of a collision is a problem.

A workaround is to use module augmentation:

// plugins/index.d.ts
declare module "./chart.js" {
  interface ChartOptions {
    legend?: ChartLegendOptions;
  }
}

The augmentation is emitted as-is into the defs bundle. It's a bit weird for a module to augment itself like this, but it does seem to work.

Another possibility would be to use a non-rollup based tool such as dts-bundle-generator, as I believe it leaves duplicates unchanged.

[sgratzl]

my current state: https://github.com/sgratzl/Chart.js/tree/sgratzl/types/types went through the code and now looking at the documentation for different options

[stockiNail]

@sgratzl I'm working on animation options for another project.

If I may provide a first feedack, having a look to the https://github.com/sgratzl/Chart.js/blob/sgratzl/types/types/core/index.d.ts, I see that the onProgress and onComplete callbacks are defined intoIAnimationPropertySpec but as far as I have tested, you can set them only into IAnimationOptions.
Maybe I'm wrong.

[stockiNail]

@sgratzl another feedback, always about animation.

debug, loop and delay can be set at IAnimationOptions as well, not only at IAnimationPropertySpec.

[sgratzl]

thx, it is work in progress and I appreciate any hints

[kurkle]

Noticed a typo there: (data vs date)

export const _adapters: {
    _data: DateAdapter;
};

[etimberg]

@sgratzl I like the type structure. What do you think the best way to collaborate on the types? We could split the initial types into separate modules + add the build steps then PR that followed by PRs for improvements. Or we could work and get the types all ready in one branch and merge at the end

[sgratzl]

I should be able to finish going through the documentation by the end of today. Unfortunately, I don't get supported financially by anyone for doing things like that. Then I should have a list of all the properties. However, there are still open questions regarding how to mix the options and so on together. Like in the best case, as soon as I say it is a 'bar' controller, it should just suggest me the options that are valid.

Another big questions is how to handle new plugins such that they can contribute to the configuration / options, ...