Improve D3 TypeScript definitions using new String literal syntax

[matthew-rister]

Hello D3 Team,

I've recently been using D3 powered with static checking using TypeScript, however, there is one area in D3's TypeScript definitions which could be improved to provide an even better development experience. D3 manipulates SVG attributes and styles using strings which enables users to erroneously enter invalid values. TypeScript recently introduced a new String Literal syntax which will strictly enforce what string values can be accepted in an API. This would fix the scenario where someone could enter an invalid string attribute. I know that there are a lot of potential values to catalog based on the SVG spec, but doing something like this would enormously improve the development experience for D3.

Here is a link with more details: https://github.com/Microsoft/TypeScript/wiki/What's-new-in-TypeScript#string-literal-types

Thanks for all the great work you guys do,
Matt

[mbostock]

Thanks for the suggestion. I do not have the resources to maintain TypeScript definitions, but I am aware that @tomwanzek is working on TypeScript definitions for D3 4.0:

https://github.com/tomwanzek/d3-v4-definitelytyped

There is also a D3 TypeScript definition in DefinitelyTyped:

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/d3/d3.d.ts

I believe Tom is planning on merging his TypeScript definitions for 4.0 into DefinitelyTyped in the future, and it sounds like the new String Literal syntax would be useful in that regard.

[tomwanzek]

Mike is right, for version 3.x of D3, there are typescript definitions on DefinitelyTyped, which have been the traditional starting point.

My repo as mentioned by Mike, is co-evolving with D3 version 4. It draws on the D3 code/docs and the legacy v3 typings from DefinitelyTyped.

As for your comment regarding the string literal types, yes, in principle they are useful and they may add value to the typescript definitions for D3 as well. I started using them in other spots of the definitions I am drafting, than the ones you had in mind.
While valuable in principle, I suspect, it would not be practical due to the likely dictionary size and inherent conditionality. I.e. not only does D3 work with SVG, but also HTML elements. The permissible string literals, are conditional on the specifics of the element type being manipulated

There are a few reasons, why I did not yet contribute the content of my repo directly to DefinitelyTyped through a traditional pull-request process (beyond the dependency on version 4):

1. It uses a new feature of typescript (1.9.0-dev) which allows the typing of the this-context in functions. The primary use case for D3 is the ability to have compiler and editor support, whenever this is bound to a DOM element (HTMLElement, SVGElement or and the like), e.g. as done when modifying selected elements or in transitions.
2. D3 v3 was a single library with a global d3, this scenario is easy to handle with the DefinitelyTyped model of typescript definition files. D3 v4 is modular and uses mixins across modules (e.g. d3-selection and d3-transition), but more importantly:
   • it allows different bundling strategies, and
   • depending on the use case (vanilla vs modular loading/imports), there may be a global d3 or not.
3. There is some movement in how typings may be obtained and brought into the code base in the (near?) future. There is the approach by typings 1.x.x which is broader than DefinitelyTyped and then there are considerations related to @types.

As the above is not on the critical path for Mike, the discussion is probably easier continued closer to the typescript definition files for D3. I will open an issue in the DefinitelyTyped community shortly to raise the questions particularly related to items 2. and 3. above. I just wanted to have a better grasp on the mechanics of item 1 with respect to typescript and D3 v4, so it would not be an abstract flight of fancy.

@mjrister I will copy-mention you, when I open the issue as an FYI. But in the meantime, feel free to flag the question of string literals directly at DefinitelyTyped, as the above is just my personal take on the matter. The primary maintainers/contributors of d3.d.ts on DefinitelyTyped might have other insights.

[ocombe]

Hey @tomwanzek I'm interested in trying those v4 definitions, how can I install them ?

[tomwanzek]

@ocombe I am currently completing my first pass through what I dubbed the Core Modules in the repo. Which are the standard D3 bundle modules minus

• d3-geo,
• d3-request,
• d3-queue and
• d3-dsv
  for now.

Which is to say, I am currently working through d3-hierarchy definitions draft locally. I would expect a first draft today/tomorrow depending on timezone. Will work on 'shape tests' as well.

There is a key issue related to production deployment, which I flagged on the repo.

The code in the master branch, is currently predicated on typescript@next primarily because I wanted to test out the this typing. If that is your primary interest, let me know, so I know what you are aiming at. The primary use should be come clear, when I push some of the local shape test files d3-selection and d3-transition.

I track a second milestone for definitions that are typescript 1.8.10 compilable, Core Modules (Standard) Milestone. My current though process for migration path protection was to complete the enhanced version and then strip out this typing.

These could be pull-requested into DefinitelyTyped (give or take ambient declarations of the modules.)

Let me know which 'version' you are after. I might add a 'play with the enhanced typings' installation section to the repo.

[ocombe]

I would use whatever is available, if the best way is to use TS 1.9 then I don't mind, as long as it stills works with my webpack setup (which I think it does). Anyway TS 1.9 will probably be released before D3 v4 (TS 2.0 is complete at 95%).

I'd be happy to help you by reporting any bug that I find since I will probably use this extensively for a long time (this is central for my job).

[ocombe]

Well, looks like I stand corrected, D3 4.0 was out first :D

[tomwanzek]

Never had a doubt about that 😄

[mattma]

@ocombe Did you get v4 definitions working in your Angular2 app? What version of Typescript do you use? TS 1.9? Can you share how did you get it to work with the typing?

@tomwanzek , can I use typings install github~d3-v4-definitelytyped --global --save to do so? Need help on this, please. thanks a lot.

[tomwanzek]

@mattma The majority of definitions is finished in their TypeScript 2 versions. As far as the standard bundle is concerned, d3-geo is in progress (@Ledragon is contributing to it), d3-request is just awaiting a PR thumbs-up. (There are a couple of very specific issues, which are tracked in my repo. The rest is housekeeping chores).

The bulk of the definitions have already been submitted as a PR to DefinitelyTyped (types-2.0 branch which feeds the @types org). Here is the issue on DefinititelyTyped which discusses the migration progress and is referenced in the initial PR. My repo also contains the aspirational roadmap and migration status info.

Once this migration is complete, getting the definitions should be as easy as, e.g:

npm install @types/d3-selection --save

There are a couple of logistical 'opportunities' having to do with the migration of DefinitelyTyped to TypeScript 2 and the adjustments in the eco system supporting that. I flagged these items in the aforementioned issue. Hopefully, they get resolved quickly.

We are going to wrap up the outstanding definitions (and probably throw in d3-selection-multi and d3-scale-chromatic for good measure). I will see, if I can get some more action going to have the issues addressed which were flagged to the DT and TypeScript powers that be. 😄

[mattma]

@tomwanzek Great work and thank you very much for taking the initiative for D3 Typescript community.

[seansfkelley]

@tomwanzek awesome work! Would you and @mbostock consider merging the type definitions directly into d3 proper as the canonical place to have those definitions, or would you prefer to keep them separate and published under @types? I know that moment.js does this as well, and it is Very Convenient.

[tomwanzek]

@seansfkelley @mbostock I am open to the consideration, ultimately I defer to Mike's perspective.

When I started developing the definitions, D3 v4 was pre-release and TypeScript 2 was pre-release. So the initial rationale for separating it out was three-fold:

• not holding up Mike's efforts to finalize and release D3 v4 with extra dependencies
• be free to experiment with some of the new TS 2 features
• not knowing in advance, if the definitions would be de-coupled in the same way as the D3 modules are (I.e. would the definitions create dependencies that do not mandatorily exist in the corresponding modules.)

The above items are essentially addressed as of now.

With that being said, at this point it boils down to questions of:

• syncing maintenance cycles with the right community support
• Considerations related to definitions testing (at a minimum shape tests comparable to the ones in DefinitelyTyped)