Request for d3.js API update from v3 to v4.1.0 #9936
Comments
|
You are correct, I took a stab at writing new definitions for the wonderful D3 version 4.x.x by @mbostock. Mike has obviously been very generous with the modularization and features 🎉 I built on his documentation and code as well as the hard work by @gustavderdrache, @borisyankov and all the other contributors to the previous D3 v3 definitions on DefinitelyTyped. I would love to bring it into the community process in short order for peer-review/general use. I experimented with some new typescript 1.9/2.0-dev features related to typing the I just finished a pass of the following new D3 modules including an initial set of shape tests (alphabetical order):
Furthermore, there are some (as yet untested) draft definitions for the following modules:
With regard to what D3 version considers to be the standard bundle, I have deferred the following:
There is an actively maintained issues log on the repo. Later today, I intend to post a follow-up to this brief status. There I will frame some of the specific questions I came across on how to move the above into pull-request(s) for DefinitelyTyped. At the core this will be about migration path from typescript 1.8 to 2.0 including the future with UMD and @types. cc: @ocombe, @mjrister |
|
Thanks for the patience as I managed most of the status of the drafting in my repo in the interim. Here is an update or rather a suggested roadmap. I broke it out as follows:
Wherever, I am looking for specific input, I have tried to @ mention the right individuals to the best of my abilities in no particular order. Of course, all comments are welcome! d3 version 4.1.x definitions using Typescript 2.0.0+The definitions and tests for the modules of the D3v4 in the d3-v4-definitelytyped repo were written based on TS 2 from the get go. As I understand it from the Support Typescript 2.0 issue #10072, the way to bring those into DefinitelyTyped and by propagation the @types organization is through a pull request against the Completed ModulesI am ready to submit a first PR for the following first batch of completed D3 modules with corresponding tests: d3-array, d3-axis, d3-brush, d3-chord, d3-collection, d3-color, d3-dispatch, d3-drag, d3-ease, d3-format, d3-hierarchy, d3-interpolate, d3-path, d3-polygon, d3-quadtree, d3-random, d3-scale, d3-selection, d3-shape, d3-time, d3-time-format, d3-timer, d3-transition, d3-voronoi, d3-zoom Known Issues related to the completed modules:
Modules in ProgressThe following D3 modules are in progress in the d3-v4-definitelytyped repo:
We could submit those as follow-on PRs to Modules PendingThe following modules of the standard D3 bundle are not yet started with new definitions:
For d3-dsv there is some legacy material already on DefinitelyTyped, which may or may not be a good starting point. Did not have a chance to look at it yet. Standard D3 Bundle DefinitionsD3v4 provides a standard bundle which comprises all the individual modules mentioned in the previous sections. The d3-v4-definitelytyped repo contains a UMD definition file which (a) re-exports the individual modules to support I would add this one into one of the PRs against Question: What would be the preferred approach to versioning the v4 Release (i.e. latest) against the older definitions and tests related to D3 v3.x? d3 version 4.1.x definitions using Typescript 1.8.10My intent was to convert the new TS 2 definitions from above into definitions for the current
The versioning issue for the old @vvakame, @mhegazy, @gustavderdrache, @borisyankov your perspective would be appreciated. Further ItemsSynchronization/Conflicts between
|
|
Super awesome. I really like that you've included the Element in the selection generics. Is it somehow possible to make these definitions coalesce on a re-exported module that contains a bundle of d3 modules? That is, if I do: import * as d3 from "d3-selection";
import * as d3Drag from "d3-drag";
import * as d3Scale from "d3-scale";
Object.assign(d3, d3Drag, d3Scale);
export default d3;then the re-exported I have two specific, minor comments about a def that I'll open in your repo as well. |
|
that is a really good idea @zbjornson, I agree that it would help a lot to have everything available under d3 namespace :) |
|
Thanks for the feedback. @zbjornson and @ocombe. As for the bundling of D3 modules let me answer in two parts (Standard D3v4 Bundle and Custom Choice of Modules) . Standard D3v4 BundleI already have a standard bundle file definition file here. It is ready to be added to the PR, but I wanted to get some guidance as per above on how to keep the legacy D3v3.x definitions available (e.g. under versioned filename or folder name, whatever is best for the tooling used to acquire definitions.) The definition is written as a UMD module definition and supports the two use scenarios of the D3 standard bundle: (a) Module import: et voila... (b) Vanilla Script Note that, this is the D3 behavior, in a vanilla context it exports to the Custom Choice of ModulesThis should be more what you are aiming at. (a) Module import: If you are using (some of) the separate D3 module in a project using module imports, you simple create a barrel module comparable to: This is in line with how D3 is written and supported by the current definitions. You can re-export only relevant properties/methods of the individual d3-modules. If you use d3-selection and d3-transition, be mindful that d3-transition augments d3-selection. And, using whatever relative path you have to your custom_bundled_d3 module, you simply use your barrel as: (b) Vanilla Script When using only a subset of the modules as vanilla scripts, D3's individual UMD modules are written to each export to the This is currently, where the first known issue 'UMD global exports' under the Completed Modules section comes in. Ideally, this scenario should be supported so that you can consume the shared Ideally, I would have hoped that this is readily supportable by simple adding This is why I opened the issue referenced above on TypeScript, but have not seen any activity on it since I opened it. I am hoping to have this simple way supported, rather than having to write global augmentations into each module. Hope this explains... |
|
Ah yes, I'd like the one with custom module import/export :) |
|
Oooh, now this is exciting! I'll definitely give this a look-over this weekend. As for managing v3 and v4 -- my gut says that we should keep them side-by-side, at least for a while. It'll take a while for projects (especially larger ones) to change over since the name changes are fairly breaking. |
|
@tomwanzek another epic response, thank you. The |
|
Here is a non-epic simple one 😄 : @gustavderdrache I agree that we need a way to keep the 3.x definitions up and accessible in a well-defined way. I started the whole tour de force partly out of gratitude for the work of others before me and partly to ease the impact assessment for my own code base. |
|
I have added d3-force to the completed modules and pushed it to the already existing PR #10228 |
|
I have added d3-queue to the completed modules and pushed it to the already existing PR #10228 |
|
@tomwanzek According to the contribution guide,
It seems like once you get the standard v4 bundle, you can just rename the old |
|
With the merge of PR #10228 the vast majority of individual D3 standard bundle modules now has a TypeScript 2 definition in the Here is an interim status update. With respect to open items, I will focus on the structural questions rather than definition specific questions. @mhegazy @RyanCavanaugh @andy-ms I think for the first few of issues, you might be best positioned to guide us quickly down the right path...So a huge thanks in advance.
For the chores discussed just before the merge of #10228. I will simply create a follow-up PR to The same will be with the remaining/additional modules already on the way with contributions from @Ledragon and @gustavderdrache, we can migrate them to DT by PR. Again, thanks to everyone who is helping to get this off the ground!!! |
|
As a brief check point: Between the PRs linked to this issue, the module coverage for D3 now includes all modules in the standard D3 bundle, as well as two additional modules (d3-selection-multi and d3-hsv) in at least an initial version of TypeScript 2 definitions. |
|
Updated Status Summary: In the collaborative development repo for D3v4 definitions, I have created a more official release candidate 2.0.0-rc.2 of the reference definitions which are still the primary source for migration into DefinitelyTyped/types-2.0. Thanks as well to the PR contributions from @Ledragon, @gustavderdrache and @arrayjam , the definitions are now baseline complete from a functional perspective. 🎉 The PRs submitted (and partially merged) against the While there are no definition-level functional issues open, the following still applies:
Those module definitions which have seen a successful merge are now also available through The relevant questions have since been opened as a distinct issue #10711. Solution proposals to get the open items to resolution are more than welcome. |
|
Status Update: (1) PR #10741 has been ready to merge for way over 2 weeks. Even accounting for the fix to the version parsing in types-publisher this should have been done over a week ago. (2) PR #10947 has been spun off from the now closed PR #10453 to move d3-dsv and d3-request through. This was done right after receiving clarification that maintaining a definition for the d3 version 4 bundle and the legacy definitions for d3 is not yet supported in Despite several attempts to expedite the merging of these straightforward PRs there has been no success. The structural solution to allows the d3 version 4 bundle definitions in is sorely needed. It has already led to some confusion in with angular-cli users. Not the least, because the version number in @types does not reflect v3.5.x. To paraphrase the Hitchhiker's Guide to the Galaxy: Persistence is futile... at least, apparently so, in this case. Contributions to escalate a resolution would be most appreciated. |
|
Milestone Update Thanks @RyanCavanaugh for merging the the two open PRs yesterday 😄 With that and after the enhancement to the version number parsing implemented by @andy-ms, I am happy to report the following: Each module of the D3 standard bundle and a couple of add-ons (d3-selection-multi and d3-hsv) have now working TypeScript 2 definitions in the Thanks again in particular to @gustavderdrache @Ledragon and @arrayjam for their contributions to the new definitions!!! 🍻 For friends of Angular 2, I have published an initial version of a D3 Service, which also shows how the above definitions can be imported along-side the individual D3 modules: 🎉 Material Open Items (1) The individual **d3-***** module definitions still do not expose a (2) There is still no D3 version 4 definition file for the D3 standard bundle in d3 definitions folder. The folder still contains definitions for v3.5.17. This is due to the need to allow imports of the legacy definitions within DefinitelyTyped/types-2.0 by libraries still build on D3 v3.5.x. Structural support for both legacy and new version is critically required!!! See the discussion in Issue #10711. Suggestions to address these are welcome. Next Steps I will do a final release on the collaborative development repo which was used as the main source for migration. Update the README completely and migrate any remaining open issues over here. The above Material Open Items require resolution. There has also been an ask to fully support strictNullChecks, which would require some more validation work before switching it on. JSDoc comments enhancement should also be a key next step. I prefer these to happen here after winding down the other repo, to avoid the continued manual synchronization effort necessary to date. TypeScript 1.8.x definitions? I am aware that some people have been looking for TS 1.8.x definitions for D3 version 4. While the TS2 definitions can be "backcast" in principle and published in what is still There should probably also be a clean-up of *old * D3 v3.x related issues in this repo, which still ghost around. In order to take that on, additional collaborator support would be required. Suggestions in this matter are welcome. Cheers! |
|
Given that the heavy lifting of the development of the initial definitions for the separate D3 version 4 modules is essentially done, I would recommend following up on the known open items as separate targeted issues:
Furthermore,
As for definitions for D3 v4 which can be used with TypeScript 1.8.x, as I said, if someone wants to add their effort/support, I would recommend opening a separate issue. And that concludes today's status round-up... 😄 |
|
For those of us with a need for closure 😉 : I have created a final cut-over release on d3-v4-definitelytyped. The release completes the migration of all definitions developed there to DT for future use + maintenance. All open issues have been transferred to DT and cross-referenced to this issue. With the now final release of TS2, I do not have the intent to circle back to D3 version 4 definitions for TS 1.8.x. Thanks again to @Ledragon, @gustavderdrache and @arrayjam for their code contributions. Thanks as well to @RyanCavanaugh, @andy-ms, and @mhegazy for making TS and DT/@types possible. Thanks of course as well to @mbostock for D3 in the first place. Without you pushing the envelope, this would not have been necessary... eh, possible, I mean 😄 Let's keep this relevant and current with all your support and future contributions. Starting with the already cross-referenced items. No rest for the wicked 🎉 Cheers. |
|
Mad props, @tomwanzek, for your dedication getting this big task done! |
|
I'm curious what the plan is for NuGet since I have projects using that. Is the idea that everyone uses npm instead of NuGet? |
|
@zbjornson thanks for the props 😄 most appreciated! @jnm2 I have no plan for NuGet, which seems in line with D3 itself. See D3 issue 1335. So I am afraid, I am not aware of a solution. Regardless, there is still work to be done on the definitions here (see the JSDoc and strictNullChecking issues spun off from here for tracking). I started working through the JSDoc completion task, as always collaborators on a per module basis are welcome! We can coordinate in the respective tracking issue, who tackles which. Some were essentially done from the get go. Some I have recently completed and the PRs are in awaiting a merge. However, I have to mind the cycles I spend on this, now that the heaviest lifting is done. As always, bug fixes and keeping it in line with D3 changes have priority over usability enhancements. The pending validation for strictNullChecks, should be done after the JSDoc comments for a given module are in to avoid merge conflicts. However, while I would personally love to have the definitions validated and updated including the tests. There is effort involved to do it right, where the generics and interfaces come into play to determine the best way to do it. Tests also need to be updated. Cheers. |
|
FYI, in d3/d3#2982 @mbostock mentioned that he'd be willing to add JSDoc documentation to the D3 source:
I thought it might be relevant to note. |
|
@mootari Thanks for the FYI, I quickly read through the threat you referenced. For the TypeScript users, the matter is in the process of being addressed from a consumers' perspective. I have started pushing PRs to DefinitelyTyped. Once merged these will further enhance the already available definitions files available through If you are interested have a look at the tracking issue #11366 for the relevant PRs. While they are largely build based on the published API documents, I have kept them signature specific for overloaded methods. The benefit is simple, there is full IDE support when developing in TypeScript (hovers, argument help, peek at definition for a specific variable, method, or interface. That is on top of the type-safety aspect during development and the improved refactoring support gained from that. @mbostock you are totally right, that formatting (line breaks) is a bit iffy (will have to fine-tune that at some point for the hover-over in the IDE). And there is effort in adding them/maintaining them. But, by and large, it should be worthwhile. Personally, I do not consider it a replacement of the markdown API Docs in the repo. I think they serve two different use cases. Nothing in the JSDoc replaces the benefit of your examples and the single-view. |
|
@tomwanzek Oh, it was never my intention to invalidate any work done so far. All I wanted to point out was that there might be a chance for a joint effort to create precise and consistent descriptions, and that the ones already written by you and others could serve as an excellent basis for D3's adoption of JSDoc. As a side note, for some reason I wasn't even aware until now that DT definitions are tailored towards TypeScript (reading helps, I guess). Intellij's IDEs allow the import and use of DT definitions for vanilla JS, and that's the angle I was coming from. |
|
@mootari Ueberhaupt kein Problem, naechstes mal, wenn ich zu Hause bin, gehen wir einen trinken! 😉 Besides, what you proposed for the D3 repo in your referenced issue looks sweet. I am all for the source links from the API docs 👍 I am all for joining efforts where technically possible given the available tooling. Since I am running with VS Code as my IDE and work in TS, I was not aware that e.g. IntelliJ offers TS-d.ts file based intellisense when working in JS. (Maybe even VS Code for JS does it. I simply never tried?!) Would be great to know, once the PRs are merged and pushed to npm @types, whether they work for your environment... |
|
@mootari The first major batches with JSDoc comment enhanced definitions have just been merged and are now available as usual on npm from the @types organization. Would be curious to know, if your IDE support works with them in your described setup (i.e. JS in IntelliJ)? (Note: that I need to push a minor follow-up to duplicate the Selection interface comment in d3-transition, as the augmentation of the interface covers the comment from d3-selection) |
|
@tomwanzek I only did a superficial test, but: Oh boy, how amazing is that? 😃 🎉 IntelliJ (PhpStorm in my case) seems to only offer the master branch of https://github.com/DefinitelyTyped/DefinitelyTyped for direct downloads, so I had to manually add your definitions (picked the 2.0.0 release from https://github.com/tomwanzek/d3-v4-definitelytyped/releases and told PhpStorm to import the src folder). I only tested using the d3 global, so I can't say how well it will cope with module imports. Gonna try that later (might be a while though). |
|
@mootari sorry to hear that you have to manually bring in the type definitions into IntelliJ. Please be aware that the versions you find in DefinitelyTyped/types-2.0 are more current and contain the JSDoc comments. Since the cut-over release 2.0.0 in my old repo, I am no longer synchronizing the changes there. If you can install files into your project using npm install, you can readily download the definitions, e.g. If you need a bundle definition file which exports a All the definitions are written with TypeScript 2 in mind, as a module structure they are not backwards compatible to 1.8.x. So I'm not sure if IntelliJ will use them for language services in a JS project. Good luck, |
|
The D3 Standard Bundle definitions have just been merged and are now published. The first version which reflects in accordance with @types semver is v4.2.37 (Note that, the patch release corresponds to the sequential published definitions count, not the d3 patch release) By implication, using Anyone, requiring the legacy definitions will have to explicitly install definitions from @types with a version in the Definitions in |
|
As a brief follow-up, a similar In principle, the same would be advisable for each of D3 module definitions, which have dependencies on other D3 modules. My main concern in suggesting this is maintainability. There is potential for the PR process to exhibit a responsiveness more in line with getting such things done without disproportionate effort. That being said, and yes I am aware of the irony, I have just opened two issues for d3-geo and d3-voronoi definitions to be updated to the latest minor releases. Your chance for glory and taking one for the team 😄 Just always @ mention the authors of the affected definition file when submitting a PR for review! |
|
It seems to me, this issue can be closed now. The definitions for the individual modules and the standard bundle are published in version D3 v4.3 now. So, while there are open issues related to D3 v4, like the validation and enhancements related to |
ghost
closed this as 
d3/d3.d.ts /cc @gustavderdrache @borisyankov
d3.js got a major overhaul. Its API has improved considerably. See d3 v4 changes. I'm quite excited about it, but for the time being I have to stay with v3 or abandon TypeScript for a critical class.
Fascinating article by @mbostock discussing examples of poor d3.js API pre-v4 and the rationale behind v4's API: What Makes Software Good - well worth the read no matter what walk of programming you come from.
Edit: hang on- I just saw https://github.com/tomwanzek/d3-v4-definitelytyped so perhaps @tomwanzek is already taking care of this?
The text was updated successfully, but these errors were encountered: