How do I write a Typescript definition file for a JavaScript library written like the following?

Question

I have an old JavaScript library that I wrote to work with AMD and CommonJS. I forgot the original source which influenced me to write the library in this way, but my JavaScript library is written in the following pattern.

(function(window) {
 'use strict';

 function getLib() {
  var mylib = {};
  mylib.getSomething = function() {
   return 'x';
  }
  mylib.getCar = function(make, model, year) {
   return {
    make: make,
    model: model,
    year: year
   };
  }
  return mylib;
 }

 if(typeof module === 'object' && module && typeof module.exports === 'object') {
    module.exports = getLib();
  } else {
    if(typeof(mylib) === 'undefined') {
      window.mylib = getLib();
    }

    if(typeof define === 'function' && define.amd) {
      define('mylib', [], getLib());
    }
  }
})(this);

How do I write a type definition d.ts file for this JavaScript library?

I attempted to write a d.ts as follows, but it does not work. In my Angular app, I put the following file node_modules/@types/mylib/index.d.ts.

interface Car {
 make: string;
 model: string;
 year: number;
}

interface MyLib {
 getSomething(): string;
 getCar(make: string, model: string, year: number): Car;
}

declare module "mylib" {
 export let mylib: MyLib
}

In my controller, I simply try to import the library and debug it to the console, but get undefined.

import {mylib} from 'mylib'; //IDE doesn't complain, seems to find the type def

export class MyPage {
 constructor() {
  console.log(mylib); //undefined
  console.log(mylib.getCar('ford', 'f150', 2018)); //code won't reach here
 }
}

Note that the JavaScript package mylib is not on NPM but a private repository and I have already installed it (e.g. npm install mylib --save) to node_modules/mylib. I mention this because I am not sure where the type def file should go.

Any help is appreciated.

UPDATE:

Per the advice below, I've modified my d.ts file to look like the following and placed it in mylib/index.d.ts.

declare module "mylib" {
    let mylib: MyLib;
    export = mylib; 
}

Now, I can import the library in two ways. First way.

import mylib from 'mylib';

Second way.

import * as mylib from 'mylib';

In VS Code, the IDE, there are no complaints (no red lines hinting at problems). Furthermore, I've modified tsconfig.json to look like the following.

{
  "compileOnSave": false,
  "compilerOptions": {
    "baseUrl": "./",
    "outDir": "./dist/out-tsc",
    "sourceMap": true,
    "declaration": false,
    "module": "commonjs",
    "esModuleInterop": true,
    "moduleResolution": "node",
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "target": "es5",
    "typeRoots": [
      "node_modules/@types"
    ],
    "lib": [
      "es2015.promise",
      "es2017",
      "dom"
    ]
  }
}

When I run ng build, I see the message below.

ERROR in node_modules/typescript/lib/lib.dom.d.ts(3268,88): error TS2344: Type 'SVGElementTagNameMap[K]' does not satisfy the constraint 'Node'.
  Type 'SVGSVGElement | SVGCircleElement | SVGClipPathElement | SVGDefsElement | SVGDescElement | SVGElli...' is not assignable to type 'Node'.
    Type 'SVGFEColorMatrixElement' is not assignable to type 'Node'.
      Types of property 'values' are incompatible.
        Type 'SVGAnimatedNumberList' is not assignable to type 'string[]'.
          Property 'includes' is missing in type 'SVGAnimatedNumberList'.
node_modules/typescript/lib/lib.dom.d.ts(3626,85): error TS2344: Type 'SVGElementTagNameMap[K]' does not satisfy the constraint 'Node'.
  Type 'SVGSVGElement | SVGCircleElement | SVGClipPathElement | SVGDefsElement | SVGDescElement | SVGElli...' is not assignable to type 'Node'.
    Type 'SVGFEColorMatrixElement' is not assignable to type 'Node'.
node_modules/typescript/lib/lib.dom.d.ts(10405,11): error TS2430: Interface 'SVGFEColorMatrixElement' incorrectly extends interface 'SVGElement'.
  Types of property 'values' are incompatible.
    Type 'SVGAnimatedNumberList' is not assignable to type 'string[]'.
node_modules/typescript/lib/lib.dom.d.ts(14172,86): error TS2344: Type 'SVGElementTagNameMap[K]' does not satisfy the constraint 'Node'.
  Type 'SVGSVGElement | SVGCircleElement | SVGClipPathElement | SVGDefsElement | SVGDescElement | SVGElli...' is not assignable to type 'Node'.
    Type 'SVGFEColorMatrixElement' is not assignable to type 'Node'.

The "interesting" thing is that if I comment out the import then run ng build or ng serve, the compile error goes away. While the app is in live reload mode, I can simply uncomment the import, and though the compile error shows up, I can still use all the features of the library in the application.

Matt McCutchen · Accepted Answer · 2018-11-13 23:27:50Z

3

In your type declaration file, the getSomething and getCar functions are members of a named export named mylib, but in the implementation, getSomething and getCar are themselves exports of the module. The cleanest way to write the declaration file would be like this:

declare module "mylib" {
 export function getSomething(): string;
 export function getCar(make: string, model: string, year: number): Car;
}

(Using an export assignment as artem said is another option.)

Side note: It's inadvisable to create a file at node_modules/@types/mylib/index.d.ts manually because package management tools such as npm and yarn expect to be in control of the entire node_modules directory. Instead, you can add the declaration file to the original mylib package or publish an actual @types/mylib package to your private repository. Or if you want to use the type declarations only in this Angular app, you can put the index.d.ts file in its own directory in the Angular app and either (1) set the baseUrl and paths options so that module resolution of mylib finds your file or (2) create a package.json file for your type declaration and register it as a dependency in your main package.json using a relative path.

answered Nov 13, 2018 at 23:27

Matt McCutchen

31.4k3 gold badges76 silver badges82 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

Jane Wayne Over a year ago

Please let me clarify; are you saying one approach could be to simply add the type definition file to the root of mylib? So upon npm install mylib --save it will end up in node_modules/mylib/index.d.ts? And then from there I may import as import mylib from 'mylib'?

Matt McCutchen Over a year ago

Yes, that should work in terms of finding the declaration file. A separate issue is that the default import will only work if you enable esModuleInterop according to artem's answer. If you want to import the entire module, I would suggest instead using import * as mylib from 'mylib';. That works regardless of esModuleInterop.

artem · Accepted Answer · 2018-11-14 15:31:02Z

1

Since you mentioned NPM, I'm assuming that the code which uses mylib is using CommonJS module resolution, and you are running it in node (or you are using something like webpack).

Then, this export variant is in effect:

module.exports = getLib();

This exports mylib object as a whole, and does not introduce anything named mylib, so the named import

import {mylib} from 'mylib'.

is undefined at runtime.

How to consume this kind of export in TypeScript is complicated, but starting from TypeScript 2.7, the way that usually works is

write type declaration using export assignment

declare module "mylib" {
    let mylib: MyLib;
    export = mylib; 
}

compile with --module=commonjs and --esModuleInterop=true
import it as if it was default export
```
import mylib from 'mylib';
```

UPDATE

To avoid name conflicts in global scope, it would be better to have all the types from mylib declared within mylib module scope, like this

declare module "mylib" {

    export interface Car {
        make: string;
        model: string;
        year: number;
    }

    export interface MyLib {
        getSomething(): string;
        getCar(make: string, model: string, year: number): Car;
    }

    export let mylib: MyLib
}

But then, you will have to import these types explicitly in every module that needs them:

import mylib from 'mylib';

import {Car, MyLib} from 'mylib';

edited Nov 14, 2018 at 15:31

answered Nov 13, 2018 at 23:25

artem

52.2k10 gold badges86 silver badges85 bronze badges

5 Comments

Jane Wayne Over a year ago

I followed your advice and modified tsconfig.json to set the module and esModuleInterop to the values you specified above. However, when I type in ng build, I get a compile error:

ERROR in node_modules/typescript/lib/lib.dom.d.ts(3268,88): error TS2344: Type 'SVGElementTagNameMap[K]' does not satisfy the constraint 'Node'.

Note that I have placed index.d.ts at the root of the project, and import mylib from 'mylib' does not show any errors in the IDE (VS Code). Any ideas?

Jane Wayne Over a year ago

Something interest to observe. If I comment out the import statement and run ng serve the compile error goes away. While the server is running from ng serve, if I uncomment the import statements, the compile error shows up in the console, however, I can still use my library's code completely! This observation leads me to believe that the problem is with the compile configuration. Not sure how to fix that.

artem Over a year ago

Is there by any chance some interface or type named Node in mylib?

Jane Wayne Over a year ago

You are right! There is an interface named Node (this is a graph library with Node, Edge, Graph). Let me see if I can tinker with that.

artem Over a year ago

Then it would be better to have all the interfaces from mylib declared within the declare module { .. } scope, not as globals, to avoid interfering with other global types. I updated the answer.

Collectives™ on Stack Overflow

How do I write a Typescript definition file for a JavaScript library written like the following?

2 Answers 2

2 Comments

5 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

2 Comments

5 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related