Global-modifying Modules
A global-modifying module alters existing values in the global scope when they are imported.
For example, there might exist a library which adds new members to String.prototype
when imported.
This pattern is somewhat dangerous due to the possibility of runtime conflicts,
but we can still write a declaration file for it.
Identifying global-modifying modules
Global-modifying modules are generally easy to identify from their documentation.
In general, they’re similar to global plugins, but need a require
call to activate their effects.
You might see documentation like this:
js
// 'require' call that doesn't use its return valuevar unused = require("magic-string-time");/* or */require("magic-string-time");var x = "hello, world";// Creates new methods on built-in typesconsole.log(x.startsWithHello());var y = [1, 2, 3];// Creates new methods on built-in typesconsole.log(y.reverseAndSort());
Here is an example
ts
// Type definitions for [~THE LIBRARY NAME~] [~OPTIONAL VERSION NUMBER~]// Project: [~THE PROJECT NAME~]// Definitions by: [~YOUR NAME~] <[~A URL FOR YOU~]>/*~ This is the global-modifying module template file. You should rename it to index.d.ts*~ and place it in a folder with the same name as the module.*~ For example, if you were writing a file for "super-greeter", this*~ file should be 'super-greeter/index.d.ts'*//*~ Note: If your global-modifying module is callable or constructable, you'll*~ need to combine the patterns here with those in the module-class or module-function*~ template files*/declare global {/*~ Here, declare things that go in the global namespace, or augment*~ existing declarations in the global namespace*/interface String {fancyFormat(opts: StringFormatOptions): string;}}/*~ If your module exports types or values, write them as usual */export interface StringFormatOptions {fancinessLevel: number;}/*~ For example, declaring a method on the module (in addition to its global side effects) */export function doSomething(): void;/*~ If your module exports nothing, you'll need this line. Otherwise, delete it */export {};