Ambient Namespaces typescript example

Question

The Namespaces chapter give an example related to D3.d.ts which I don't understand.
This is the full example:

declare namespace D3 {
    export interface Selectors {
        select: {
            (selector: string): Selection;
            (element: EventTarget): Selection;
        };
    }

    export interface Event {
        x: number;
        y: number;
    }

    export interface Base extends Selectors {
        event: Event;
    }
}

declare var d3: D3.Base;

What I really don't understand is how would I use D3.d.ts in my modules or my typescript scripts? Please give me some short examples.

EDIT
Please ignore the fact that here it is used D3; could be B3 or G3 or X7 ... whatever; I'm not interested on a specifically library. I'm only interested in how would I use the example given both in my typescript modules and my typescript scripts.

EDIT2 What mostly confuse me is the fact that the above example uses declare namespace ... instead of namespace D3 (as used e.g. for namespace Validation). Also what's the use (and how to use?) of declare var d3: D3.Base;?

Answer 1

Such declarations define global variables that do not come from imports but might be defined on the window by some <script>. To be able to simply use these variables directly (without imports!) you could always use a reference, e.g.:

/// <reference path="../types/D3.d.ts" />
d3.select("div"); // No import!

If the declaration file is placed in an @types directory it should be included without explicit reference.

---

The namespace uses declare because this is a declaration file: It has to either export the namespace (which only is valid for modules) or declare it, to make these types available.

Answer 2

As I understand typescript the "code" in the example does not generate nor change any output javascript. It is all declarations that will help intellisense and the typescript compiler find errors, but does nothing to alter the code. The declarations that the example gives are intended for an "ambient" declaration file, i.e. a declaration file that provides typescript definitions for ordinary javascript library so that typescript and intellisense can work with them as if they were typescript files instead of plain javascript. I believe that at a first approximation typescript treats anything it finds of which it has no declaration knowledges as an "any" type.

For the library mentioned you would be better off to use the existing type library (npm install --save-dev @types/d3). I have found that after installing the library (npm install --save d3) and the @types/d3, using import * as d3 from 'd3' in a .ts file (in angular 5; other situations may other steps) will bring the object and type information in, and everything works satisfactorily. If you open up the types file you will see a completely different set of declarations from the ones given in the typescript documentation example, but I believe they are still all declarations, i.e. no code.

In reply to edits

The file in the example is not a primary typescript file. It is a declarations file describing the "typescript shape" of an ordinary javascript library, i.e. how the typescript compiler and intellisense should pretend the ordinary javascript would look like if it were written in typescript. While you may think the choice of the name D3 was arbitrary, it was not exactly. The .d.ts file is trying to provide typescript meta information for a library (the d3 library: https://www.npmjs.com/package/d3) which does not itself provide that information (although, as mentioned, the typescript meta information for that particular library is available as an @types package).

If you were writing your own library code and wanted to work inside a namespace as per the validation example, you would use namespace D3 rather than declare namespace D3, but you would also be writing a .ts file, not a .d.ts file. As the section title of the documentation says, that example is working on ambient namespaces, i.e. namespaces for ordinary javascript code the writer of the file does not (typically) provide.

In summary, the goals of the two halves of the documentation are different. In the first half the "validation" code is showing you how to use namespaces within your own typescript code. In the second half, the "d3" code is showing you how you can provide typescript metadata for code that is plain javascript, not typescript.