tomwanzek / d3-v4-definitelytyped Goto Github PK

The ticks(...) method of an axis with a Date based domain should ideally be typed as:

ticks(interval: TimeInterval, specifier?: string)

Here TimeInterval is an interface imported from the d3-time module. However, since the d3-axis module has no dependency on d3-time, this would create a definitions level dependency, which is unnecessary when time scales are not used for the axis.

Currently, there is a separate line with an interval argument, but this argument is typed as any to workaround. Commented out code with TODO: and HACK: comments indicate the alternatives in the d3-axis definitions file and the related test file.

The best choice may depend on the ultimate solution to issue #1.

A lot of methods from Selection support an object as a param. Example:

d3.selectAll('div')
  .attr({
    position: 'absolute',
    top: 0
  });

The definitions of these functions (attr, style, classed, ...) should allow this object parameter (type any ?).

d3-selection and d3-transition both export Selection, the one from d3-transition extends the one from d3-selection with the addition of interrupt & transition, but it doesn't work in all use cases.
Let's say that I have a selection:

let element: Selection = d3.select('div');

now if this is a Selection from d3-selection, I cannot call .transition() on it, so I change this to a Selection from d3-transition, but then if I call style() before transition() then it won't work because the method style() returns a Selection from d3-selection, not a Selection from d3-transition, and it doesn't have transition() ...

To make it work I have to declare my element as a Transition, but it isn't one until I call transition(), right ? I find this really weird.

Add Definitions for d3-queue module.

Important: Under this milestone Data Acquisition (Enhanced). The definitions should be structured as proper modules/UMD-style module definitions. I.e., they should be comparable to the modules tracked under milestone Core Modules (Enhanced) and contained in the master branch of this repo.

Combined with their tests, they should compile successfully using Typescript 2.0.0 (beta).

They should make use of function-context this typing, where appropriate, comparable to its use in under the Core Modules (Enhanced) milestone.

For future consideration, null and undefined types should be used, where the API indicates the explicit types to be, e.g. for a function return type, string | null vs string | undefined vs. string only for non-nullable defined types.

Note, however, that, currently and in correspondence to the approach taken by DefinitelyTyped/types-2.0 the compiler is using the "strictNullChecks": false option.

Add Definitions for d3-geo module.

Important: Under this milestone Additional Layout (Enhanced). The definitions should be structured as proper modules/UMD-style module definitions. I.e., they should be comparable to the modules tracked under milestone Core Modules (Enhanced) and contained in the master branch of this repo.

Combined with their tests, they should compile successfully using Typescript 2.0.0 (beta).

They should make use of function-context this typing, where appropriate, comparable to its use in under the Core Modules (Enhanced) milestone.

For future consideration, null and undefined types should be used, where the API indicates the explicit types to be, e.g. for a function return type, string | null vs string | undefined vs. string only for non-nullable defined types.

Note, however, that, currently and in correspondence to the approach taken by DefinitelyTyped/types-2.0 the compiler is using the "strictNullChecks": false option.

Using export as namespace d3; to export each separate D3 module to a merged d3 global creates a compiler error: Duplicate Identifier 'd3'

When the individual D3 modules are used in a vanilla context (i.e. separately included scripts), they all expose their methods/properties under a d3 global. See release notes for D3 version 4 regarding different use scenarios supported.

In the specific case of D3, this behavior should ideally be supportable from a definitions perspective. There are no conflicts between identifiers exported from the individual modules (definitions).

Closed TypeScript 2.0 issue 'Built-In Support for UMD module definitions' contains the following statement in the Solution summary section:

These declarations may engage in module merging, though this should probably be discouraged somehow.

In general, the elements of a selection will be DOM elements (HTML or SVG.) These could be captured with the current constraint the type BaseType = Element for d3-selection, d3-transition and DOM event related packages like d3-drag and d3-zoom.

However, EnterElement (or EnterNode) elements constituting the group elements of the enter() selection after a data join do not meet this minimal requirement (see EnterElement interface in d3-selection.

Also, there may be use cases, albeit exceptional, where the constituent element of a selection (transition), is of a general nature, i.e. could be any. In which case, some methods of the Selection or Transition will not work, as the element misses properties/methods which are internally used by the respective D3 modules.

See the d3- selection issue and the DOM-to-Canvas Example.

As the Selection and Transition interfaces and related selection methods are generisized, not explicitly stating the type, may use type inference, based on typed arguments or return values to determine the type of this where it is tied to the element type. If inference is not possible, the BaseType would be the default value.

So, while strictly a type BaseType = Element or something likeinterface BaseType extends Node, QuerySelector {} would be too restrictive, it may be preferable in 99% (?) of use cases due to the default behavior.

Hi,
First of all, thanks for this repo, it's great to be able to find all new d3 types in a single place rather that the huge DefinitelyTyped repo.
I have a few questions:

• I started working on the d3-request API, How do I make sure nobody else is doing it at the same time? I.e. how to avoid concurrent work?
• How do you sync with DefinitelyTyped to make types available via Typings?
• Do you have nomenclature/style rules that should be followed by contributors? Would it make sense to write a contributing.md file?

Add Definitions for d3-request module.

Important: Under this milestone Data Acquisition (Enhanced). The definitions should be structured as proper modules/UMD-style module definitions. I.e., they should be comparable to the modules tracked under milestone Core Modules (Enhanced) and contained in the master branch of this repo.

Combined with their tests, they should compile successfully using Typescript 2.0.0 (beta).

They should make use of function-context this typing, where appropriate, comparable to its use in under the Core Modules (Enhanced) milestone.

For future consideration, null and undefined types should be used, where the API indicates the explicit types to be, e.g. for a function return type, string | null vs string | undefined vs. string only for non-nullable defined types.

Note, however, that, currently and in correspondence to the approach taken by DefinitelyTyped/types-2.0 the compiler is using the "strictNullChecks": false option.

The primary use case for the .merge(other) method on Selection and Transition is to merge selections or transitions, respectively, that are type-compatible in the following sense:

// s: Selection<GElement, Datum, PElement, PDatum>
// other: Selection<GElement, Datum, PElement, PDatum>
s.merge(other)

Mutatis mutandis for Transition. The standard application is merging the enter and update selection after enter elements have been appended to materialize them.

The open question is, whether there are meaningful use cases, where s and other have different types for the generics referring to element or data types. In that case the interfaces for
Selection and Transition should be amended to include a .merge(...) signature like the following:

merge(other: Selection<OElement, ODatum, OPElement, OPDatum>): Selection<GElement | OElement, Datum | ODatum, PElement | OPElement, PDatum | OPDatum>;

This seems rather on the fringe. Would also have to review source code to see, how the merge affects parents, if at all.

The Selection interface defined in d3-selection is augmented in relation to transitions in d3-transition.

In the definitions this is handled using the standard module augmentation pattern in the d3-transition definition file:

declare module "d3-selection" {
    export interface Selection<GElement extends BaseType, Datum, PElement extends BaseType, PDatum>{
        // augmentation here
    }
}

The issue is that the interface augmentation is not localized in the following sense.

A module with the following imports works as intended:

// Module 'A'
import * as d3Selection from 'd3-selection';
import * as d3Transition from 'd3-transition';

The d3-transition module import extends the Selection object from the d3-selection module as per D3 and the relevant Selection interface is augmented correspondingly.

However, the following module, may exhibit interface bleed.

// Module 'B'
import * as d3Selection from 'd3-selection';

In module 'B', the Selection interface should not show properties related to transitions. This is true and a non-issue, if the d3-transition definitions file is not part of the project.
However, if the d3-transition module is part of the project, even when it is not locally imported into the module 'B' file, the Selection interface has been augmented with transition properties.

This issue seems to be related to the type script issue: Proposal: Localized typings for definition files.

Need to file issue/investigate on Typescript.

Hi,

I get the following issue with d3-time-format/index.d.ts :
=> (53,63): error TS1110: Type expected.

Shouldn't it return "Date" instead of "(Date | null)" ?

Note : I use ts-loader

Decide whether to add a specific call signature of:

export function voronoi(): VoronoiLayout<[number, number]>;

as the default without user specifying T in voronoi?<T>(), or it defaulting to any.

Check permissiveness of Histogram related types. number may be to restrictive, for some signatures. See d3-array issue.

Currently there are two primary channels for publishing typescript definitions for third party libraries, where the definitions are not included with the library: DefinitelyTyped and typings registry. A separate tool, typings (or formerly tsd), is used for acquisition of definition files and integration into the code base.

The typescript 2.0 milestone adds a further dimension for typescript definitions acquisition with the @types/npm mechanism. @types is intended to draw on DefinitelyTyped (including conversion tooling). typescript@next also already allows the authoring of definitions in UMD format.

With respect to support for D3 v4 related typings, this raises the question of the best deployment mechanism/migration path, i. p. since D3 v4

• is now modularized,
• can be deployed 'vanilla' using a d3 global (both as standard bundle or with a subset of the modules which extend the same global), and
• can be used through module imports.

Given the implications of @types for module resolution of definitions (additional meta data files npm etc.) and in order not to cloud the focus of on D3 v4 this typing related exploration, definitions and tests are currently integrated using relative imports.

This is a preliminary matter, to focus on definition content rather than tool chain implications.

Add Definitions for d3-dsv module.

Important: Under this milestone Data Acquisition (Enhanced). The definitions should be structured as proper modules/UMD-style module definitions. I.e., they should be comparable to the modules tracked under milestone Core Modules (Enhanced) and contained in the master branch of this repo.

Combined with their tests, they should compile successfully using Typescript 2.0.0 (beta).

They should make use of function-context this typing, where appropriate, comparable to its use in under the Core Modules (Enhanced) milestone.

For future consideration, null and undefined types should be used, where the API indicates the explicit types to be, e.g. for a function return type, string | null vs string | undefined vs. string only for non-nullable defined types.

Note, however, that, currently and in correspondence to the approach taken by DefinitelyTyped/types-2.0 the compiler is using the "strictNullChecks": false option.

Review whether recently made generalization of element type and datum type for Selection or Transition which can be passed into to ZoomBehavior methods translate(...), scaleBy(...), and scaleTo(...) is really sensible.

Should probably revert the change and restrict again to element and datum type of ZoomBehavior. Datum type must not break accessor functions that have previously been set on the ZoomBehavior and are invoked when calling translate(...), scaleBy(...), orscaleTo(...).

d3-selection defines the event variable and customEvent. The modules d3-drag, d3-zoom and d3-brush define specific implementations of events.

As the event variable is routinely accessed in callbacks to access properties specific to the handling of the event in the context it is invoked in, the typing should be flexible enough to support/allow appropriate contextualization.

Given the modularization of D3, there is an interaction with the deployment issue #1 . Depending, on which module the relevant definitions are kept in, there may be a trade-off between:

• how the best possible event-type context is used when compiling or in editor support, and
• not introducing module coupling at the level of definitions, which does not exist when loading the underlying D3 modules.

zoomTransforms allow the rescaling of scales passed into rescaleX(...) and rescaleY(...).

The current draft of d3-zoom definitions imports relevant scale type interfaces from d3-scale. This coupling is too tight. An minimally necessary interface for a 'ZoomScale' (or similar name), should be added directly to d3-zoom to de-couple and provide a less restrictive contract for typing.

I tried the current type definitions with the enhanced "this", but I get a lot of errors in my code from tslint because of "argument type function is not assignable to parameter type this"

Ex with:

d3.selectAll('div').each(function() {
  // ...
})

How am I supposed to define the "this" here to avoid this error? Is it just a problem of tslint not being updated to 1.9 (or 2.0) yet?

Validate the return type of the callback function passed into visitAfter(...). There seems to be some ambiguous wording in the original API documentation.

Review the appropriateness of this contexts and use of ...args: any[] in callback functions were flagged in the definition file as TODO.

Decide, if in (some) cases, a signature should be added with the typical (d, i?, group?) pattern and GElement this context. The more general version should be retained nevertheless.

Once the Core Module (Enhanced) definitions are stable enough (or definition related issues are essentially only related to this typing), create a separate branch with 'stripped down' definitions that can readily be used with typescript 1.8.10.

In particular, stripping down refers to removing features which use this typing. It may also involve wrapping the definitions into ambient module declarations.

Convert relevant tests and run them with typescript 1.8.10.

Contribute to DefinitelyTyped (or similar) Depends on issue #1 to a lesser extent than the enhanced definitions.