Unable to add property to interface after external import

[eschwartz]

Consider this code:

// myPlugin.ts
<reference path="typings/jquery/jquery.d.ts" />

// Add a plugin to the JQuery type
interface JQuery {
  myPlugin():JQuery;
}

var $myEl = $('foo').myPlugin();
var $bar = $('foo').find('bar');

This works fine. The problem comes when I mix this with an external import:

// myPlugin.ts
<reference path="typings/jquery/jquery.d.ts" />

import _ = require('underscore');

// Add a plugin to the JQuery type
interface JQuery {
  myPlugin():JQuery;
}

var $myEl = $('foo').myPlugin();
var $bar = $('foo').find('bar');
/// error TS2339: Property 'find' does not exist on type 'JQuery'.

This does not seem to be specific to JQuery/underscore, but happens whenever I add to an interface in the same file as an import.

I can work around this by moving the interface additions to another file:

// jquery.ext.d.ts
<reference path="typings/jquery/jquery.d.ts" />

interface JQuery {
  myPlugin();
}

// myPlugin.ts
<reference path="typings/jquery/jquery.d.ts" />
<reference path="jquery.ext.d.ts" />

import _ = require('underscore');

var $myEl = $('foo').myPlugin();
var $bar = $('foo').find('bar');

Is this a bug in the compiler, or expected behavior? If it is expected, is there any documentation I can look at?

Thanks!

[RyanCavanaugh]

This is the expected behavior.

When a file has a top-level export or import, that file becomes a new 'namespace' that is the external module the file represents. The net effect is similar to this:

module My_File { // <- Internal name created by the compiler
  interface JQuery { ... } // A new type, not an extension of JQuery
}

We need to document this in an easier to find place as it's a very frequently-encountered thing (I've seen many questions on StackOverflow and here).

[eschwartz]

Thanks. Yes, some documentation on this would be helpful. I looked through a number of StackOverflow posts specifically about adding properties to interfaces, but I can't find anything about it in the docs. The only reference I found to this functionality is in a blog post from Jan 2013:

Extending Existing Types

Moreover, interfaces in TypeScript are open, meaning you can add your own members to an interface by simply writing another interface block. If you have an external script that adds members to Date, for example, you simply need to write interface Date { /.../ } and declare the additional members.