This repo has been deprecated.
Current defintions for D3 modules are actively maintained on DefinitelyTyped.
Questions on how to use the published definitions should be filed on StackOverflow.
Feature requests and suspected definition bugs should be filed on DefinitelyTyped.
MIGRATION COMPLETE
It is with a great sense of pleasure that I announce the completed migration of the D3 version 4 definitions in this repo to a production setting.
On a go forward basis the definitions will be maintained on DefinitelyTyped (DT). The definitions utilize TypeScript 2 features and are currenly contained in the types-2.0 branch.
As DefinitelyTyped/types-2.0 feeds the npm @types organization, acquiring the definitions for a project is as easy as:
npm install @types/d3-selection --save
All individual D3 modules comprising the D3 Standard Bundle as published on d3/d3 have completed definition files. There are some additional D3 module definitions for what was called "optional scope modules" in this repo.
Important: Please refer to issue Parallel Version Structure to Support D3 v4 Standard Bundle Definition and D3 v3. As a result of this issue, the published definitions under d3 still refer to the legacy version 3.5.17.
The definitions on npm @types have version numbers following a variation of semver: major.minor.patch, where major and minor correspond to the major and minor version of the corresponding D3 module. The "patch" version number corresponds to updates of the definitions file itself.
To request enhancements, open issues or PRs with changes, please, use DefinitelyTyped Issues from now on. Kindly ensure you @ mention the author(s) listed in the header of the definitions file for their awareness, when submitting issues/PRs.
As part of the transition to DT, any open issues in this repo have been migrated to DT as well. These issues have been cross-referenced to the main Defintions Request Issue 9936, which tracked the migration to DT/@types.
Thanks go to Alex Ford, Hugues Stefanski, and Yuri Feldman for their contributions to this repo. Their hard work will forever live on in the now published definitions...subject to git version control. 🎉
Thanks as well to everyone, who participated in discussions/issues resolution.
And last but not least, thanks to Ryan Cavanaugh, Andy and Mohamed Hegazy for making TypeScript and @types possible, and of course Mike Bostock for D3. đź‘Ť đź‘Ť đź‘Ť
The following sections are kept for historic reference only
This repo is intended as a staging area for typescript definitions supporting the latest major release of D3js (i.e. version 4.x) by Mike Bostock.
The definitions are written on a per module basis in reference to the now separated D3 modules. Definitions in the master branch are written on the basis of TypeScript 2.x.
In particular, they make use of a new feature which allows the typing of the this context of functions. This ability is particulary beneficial for D3, as D3 frequently binds the this context of
functions to the DOM Element being manipulated. The definition files are written as external modules/UMD modules.
The scope of this project covers the modules which are part of the standard D3 bundle as defined by Mike Bostock. On a best efforts basis, consideration may be given to a small number of D3 modules which are not part of the standard bundle, but are maintained by Mike Bostock.
Starting with Release Candidate 2.0.0-rc.2 work on the D3 standard bundle modules is considered functionally complete. For a module-by-module status see section Module-Level Status below.
The migration of completed definitions and their supporting shape tests to DefinitelyTyped has progressed well for the majority of the modules. This means that modules which have been successfully migrated, now have a supporting definition in the npm @types organization. These definitions can be used in conjunction with e.g. npm install @types/d3-selection --save. For the remaining modules and the definition for the D3 standard bundle itself, migration is still in progress. See the section Roadmap below for a further discussion.
For added clarity, this repo is not intended as a permanent source for definition files to be used in the regular course of working with D3 in TypeScript. As a result, this repo currently does not contain instructions for definitions acquisition using typings, or tsd (legacy). The plan is to retire this repo after successful migration to DefinitelyTyped and keep it only for historic reference.
This section provides a high-level view of the road ahead to completed definitons for D3 4.x, which can be accessed by developers using standard definition acquisition methods:
- Completion of Module Definitions
- Migration to DefinitelyTyped
- TypeScript 1.8.x Compatible Definitions
The modules comprising the D3 Standard Bundle now have a complete working TypeScript 2 definition with accompanying tests.
A TypeScript related issue is open and tracked which pertains to the generation of a d3 global for plain-vanilla script use of individual D3 modules.
Adding complete JSDoc comments is a pending task for most modules. Given the effort involved in keeping this repo and DefinitelyTyped in sync during the migration process, completing this task might be better solved after a successfully completed migration.
(a) Open Modules (Optional Scope)
The Module-Level Status section provides a quick glance at the modules, which do not yet have a complete initial definition with tests. Currently, this affects only a limited number of optional scope modules, which do not form part of the D3 standard bundle.
For each of these modules there is one open issue for the definition and one for the related tests. Should you wish to contribute by writing a definition that is flagged as not yet started, please check the related issue for a current status. The issue is also mapped to a milestone to give a sense of prioritization.
Beyond that, please refer to the Contributing section.
(b) Open Issues
The issues in this repo, broadly fall into three categories:
- Overarching issues related to how TypeScript definitions are written and/or deployed for easy use/maintenance by developers,
- Module-specific 'functional' issues, and
- Project management issues (progress tracking etc).
Please review and contribute to these open issues as you see fit.
Important: As described in the next sub-sections, this repo is in the process of being migrated to DefinitelyTyped. If an open module-specific issue for an otherwise complete module is critical/severe, I may hold off on migrating the affected module. Otherwise, preference will be given to migrating the module and carrying the related open issue over to DefinitelyTyped.
The process of moving essentially complete TypeScript 2 definitions and tests over to DefinitelyTyped/types-2.0 branch has, in general, progressed well.
A key rationale for using DefinitelyTyped going forward is that, it serves as the primary feeder source for the @types organization. Depending on the migration status of the individual module definitions, this means the resulting definitions are easily deployable using, e.g:
npm install @types/d3-selection --save
The main DefinitelyTyped issue thread for the migration-related questions is Request for d3.js API update from v3 to v4.1.0. This thread contains a more in depth, live disscussion of the mechanics related to the migration.
The section Module-Level Status gives a quick migration status indication by module. A slightly more granular breakout can be found here for D3 standard bundle modules and here for the optional scope modules.
Under the milestone Standard Bundle Modules (TypeScript 1.8.x) consideration is given to the preparation of definitions/tests which do not require the latest features of TypeScript 2.
The intent is to strip the unsupported features (e.g. this typing of function contexts) out, with the aim of keeping the definitions structurally as comparable as possible. A suitable wrapping of the module definitions may be required.
IMPORTANT: Activities related to this milestone are currently on hold, until the remaining migration related questions have been sufficiently resolved.
See specifically this issue comment for DefinitelyTyped related questions.
First of:
-
As long as a D3 module does not have a definition and test file flagged as complete, the definition is available for review and comment, but not considered stable. Self-evidently, changes may also result from changes to D3 itself.
-
Starting with the D3 version 4 release, D3 provides substantial flexibility with regard to (un)bundling as well as the choice between vanilla and module import use. The definitions in this repo are written as external modules/UMD module definitions. Ambient declarations are only used, when required for module augmentation (e.g. d3-transition extending the
Selectioninterface of d3-selection). -
The availability of the
d3global for vanilla use, is somewhat related to the potential use ofexport as namespace d3in UMD module definitions. The D3 standard bundle definitions file contained in this repo re-exports the modules listed in the next section. It also exposes ad3global which can be used, where the module is not imported, but definitions are included by reference. The global is exposed usingexport as namespace d3. -
The individual D3 modules, currently do not merge into the
d3global when used as unbundled vanilla scripts. This is a known issue with a duplicate identifier compile error created by usingexport as namespace d3at the constituent module level. -
The definition and test files in this repo are currently using relative paths. This was done as an interim step to focus on the D3-related aspects of this effort.
Important: All references to "Test File" below should be read as follows. The typescript files should compile without errors to indicate the internal consistency of the typescript definitions. I.e. they are only shape tests as is the DefinitelyTyped tradition. They are expressly not meant to be used with a test runner as functional tests.
Migration on hold. Check here for detailed status.
This is a definitions file for the bundle which re-exports the constituent modules and exposes a d3 global for vanilla script use.
(individual modules in alphabetical order)
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Note: Utilizes this-typing (criticality: medium)
this-typing is used accessor functions in RibbonGenerator. The this context depends on the context bound when invoking the
RibbonGenerator with data. I.e. it can be global object, undefined, a custom object or anything explicitly bound using .call(...) et al.
The latter is the case e.g. when using RibbonGenerator to create the path string in conjunction with a Selection or Transition for SVGPathElements' attr(...) callbacks.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Note: Utilizes this-typing (criticality: medium)
Available through @types. Migration complete.
Note: Utilizes this-typing (criticality: high)
this-typing is used for context-binding to DOM element.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Note: Utilizes this-typing (criticality: medium)
this-typing is used for context-binding of event handler to Simulation (using Simulation.on(...)).
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Note: Utilizes this-typing (criticality: high)
this-typing is used for context-binding to DOM element.
Available through @types. Migration complete.
Note: Utilizes this-typing (criticality: medium)
this-typing is used for accessor functions in Arc, Pie, Symbol, Stack. The this context depends on the context bound when invoking the
respective generator with data. I.e. it can be global object, undefined, a custom object or anything explicitly bound using .call(...) et al.
The latter is the case e.g. when using symbol or arc to create the path string in conjunction with a Selection or Transition for SVGPathElements' attr(...) callbacks.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Migration complete.
Available through @types. Check here for detailed status.
Note: Utilizes this-typing (criticality: high)
this-typing is used for context-binding to DOM element.
Available through @types. Migration complete.
Available through @types. Migration complete.
Note: Utilizes this-typing (criticality: high)
this-typing is used for context-binding to DOM element.
(in alphabetical order)
- Definition File
- Test File
- Definition File
- Test File
Available through @types. Migration complete.
- Definition File
- Test File
Migration in progress. Click here for details.
Available through @types. Migration complete.
- Definition File
- Test File
You can contribute to this repository in several ways:
- help to identify or resolve specific issues with the existing definitions,
- review the definitions and point out areas of improvement, or
- provide pull requests for as yet missing definitions.
For details of how to contribute, please see here.
Important: Contributing to this repo, means your contribution is intended to be merged into DefinitelyTyped. Once a module indicates completed migration from here to DefinitelyTyped, all new issues should be opened on DefinitelyTyped. Any related outstanding issues will be migrated over to DefinitelyTyped alond-side the module.
This repo benefits from the original work on D3js 3.x typings on DefinitelyTyped for the file d3.d.ts and its tests d3-test.ts. By implication the debt is to all its contributors with primary listed responsibility of Alex Ford and Boris Yankov.