This repo is intended as a staging area for typescript definitions supporting the latest major release of D3js (i.e. version 4.1.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.0.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 intended complete 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. Specifically, this optional scope may include d3-selection-multi and d3-scale-chromatic.

The content is work in progress as detailed in the section Module-Level Status below.

The migration of completed definitions and their supporting shape tests to DefinitelyTyped has started. See the section Roadmap below, which also lines out the considered strategy to addressing TypeScript 1.8.x compatible definitions.

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 @types, typings, or tsd. The plan is to retire this repo after successful migration to DefinitelyTyped and keep it only for historic reference.

• Roadmap
• Module-Level Status
• Contributing
• Related Contributions

This section provides a high-level view of the road ahead to completed definitons for D3 4.1.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

While most modules comprising the standard D3 bundle now have a complete working TypeScript 2 definition with accompanying tests, there is some remaining work to be done.

(a) Open Modules

The Module-Level Status section provides a quick glance at the modules, which do not yet have a complete initial definition with tests.

For each of these modules there is one 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.

The Standard Bundle Module (TypeScript 2) milestone takes priority over the Optional Scope Modules milestone.

Beyond that, please refer to the Contributing section.

(a) Open Issues

The issues in this repo, broadly fall into three categories:

1. Overarching issues related to how TypeScript definitions are written and/or deployed for easy use/maintenance by developers,
2. Module-specific 'functional' issues, and
3. 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 started.

A key rationale for using DefinitelyTyped going forward is that, it serves as the primary feeder source for the @types organization. Aspirationally, this means the resulting definitions should be 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.

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.

This way the impact of upgrading a D3-consuming code base from TS 1.8.x to TS 2.x should be minimal.

These definitions could then be contributed to what is currently the DefinitelyTyped/master branch.

See specifically this issue comment for DefinitelyTyped related questions.

• D3 Standard Bundle Modules
• Optional Scope Modules

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 Selection interface of d3-selection).

• The availability of the d3 global for vanilla use, is somewhat related to the potential use of export as namespace d3 in 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 a d3 global which can be used, where the module is not imported, but definitions are included by reference. The global is exposed using export as namespace d3.

• The individual D3 modules, currently do not merge into the d3 global when used as unbundled vanilla scripts. This is a known issue with a duplicate identifier compile error created by using export as namespace d3 at 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 in progress. 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.

• Definition File
• Test File

(individual modules in alphabetical order)

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

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.

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Note: Utilizes this-typing (criticality: medium)

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Note: Utilizes this-typing (criticality: high)

this-typing is used for context-binding to DOM element.

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Note: Utilizes this-typing (criticality: medium)

this-typing is used for context-binding of event handler to Simulation (using Simulation.on(...)).

Migration in progress. Check here for detailed status.

• Definition File
• Test File

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

See issue 2 BaseType definition for selection/transition elements.

Note: Utilizes this-typing (criticality: high)

this-typing is used for context-binding to DOM element.

Migration in progress. Check here for detailed status.

• Definition File
• Test File

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.

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Note: Utilizes this-typing (criticality: high)

this-typing is used for context-binding to DOM element.

Migration in progress. Check here for detailed status.

• Definition File
• Test File

Migration in progress. Check here for detailed status.

• Definition File
• Test File

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

• Definition File
• Test File

• Definition File
• Test File

• Definition File
• Test File

• Definition File
• Test File

• 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.