Import declarations from other files by side effects and triple-slash as an external node module

[falsandtru]

This code works correctly as an external node module. Is this correct usage?

1. This external node module import some declarations from other files by side effects.
2. This external node module has triple-slash references indirectly but it might be the violation of rules.

https://github.com/Microsoft/TypeScript/wiki/Typings-for-npm-packages

// foo.d.ts
declare namespace foo { }

// bar.d.ts
/// <reference path="./foo.d.ts" />
declare namespace bar { }

// index.d.ts
import './bar.d';
export {
  foo,
  bar
};

[mhegazy]

In this sample, if your package user imports your package, they will also get two global names "foo" and "bar" from your global namespace declarations. if this is what you intend, then you are set. if not, then i would suggest moving these declarations into index.d.ts, and not adding /// <references>.

The issue is that external modules have their own scoping rules, and do not pollute the global namespace, but when including a file using ///<reference> tags, any global declarations will be visible by any package consumer.

This issue has not been completely resolved. see #4665 for more details on the discussion. we have a couple of ideas on how to solve this but we have not landed one yet.

in the mean time, what the compiler will check is that the first imported file does not have a /// <reference>. as you mentioned this is easy to beak, and this is why we have added the wiki page: https://github.com/Microsoft/TypeScript/wiki/Typings-for-npm-packages

does this answer your question?

[falsandtru]

Thanks for your answer. I have some external module resolutions for native javascript packages.

power-assert-js/power-assert#29

This is my external module resolution. We need global scope declarations by external modules.

Important global declarations by side effects.

• assert

// ./index.d.ts
import "empower";
import "power-assert-formatter";
import "./typings/power-assert";
export * from "power-assert";
export {default} from "power-assert";

// ./typings/power-assert.d.ts
declare function assert(value:any, message?:string):void;
declare namespace assert {
  ...
}
declare module "power-assert" {
  export default assert;
}

// ./node_modules/empower/index.d.ts
// ./node_modules/empower/typings/empower.d.ts
// ./node_modules/power-assert-formatter/index.d.ts
// ./node_modules/power-assert-formatter/typings/power-assert-formatter.d.ts

import "power-assert"; // declare global variables by side effects of this external module
assert(1 === 1);

mochajs/mocha#1933

This is my external module resolution using DefinitelyTyped. This is a maintenance-free management model. You can update to latest typings of DefinitelyTyped by $ dtsm update --save.

Important global declarations by side effects.

• describe
• it
• etc...

// ./index.d.ts
import "./typings/mocha/mocha.d.ts";
export * from "mocha";
export {default} from "mocha";

// ./typings/mocha/mocha.d.ts
...
declare var mocha: Mocha;
declare var describe: Mocha.IContextDefinition;
...
declare module "mocha" {
    export default Mocha;
}

import "mocha"; // declare global variables by side effects of this external module
describe("describe", function () {
  it("it");
});

I want to use these resolutions as stable resolutions. Where should I go, #4665, or #2839?

[mhegazy]

#4665 would be the correct issue.

[falsandtru]

Thanks! I move to #4665.