A way to specify class properties using JSDoc

[arendjr]

Search Terms

JSDoc class properties any key @property

Suggestion

I would like to be able to extend the type of an ES6 class using JSDoc comments, such that TypeScript understands there are other properties that might be added to the object later.

Alternatively, I would like a way to indicate that a given class acts as a container that can contain any possible key.

Use Cases

I have a class that is used like a DTO. It has some properties that are guaranteed to be there, but is also used for a lot of optional properties. Take, for example:

class DTO {
    constructor(id) {
         /**
          * @type {string}
          */
         this.id = id;
    }
}

TypeScript now recognizes the object type, but whenever I try to use other properties, it complains. Currently, I'm resorting to something like this as a work-around:

class DTO {
    constructor(id) {
         /**
          * @type {string}
          */
         this.id = id;

         /**
          * @type {Object?}
          */
         this.otherProperty;
    }
}

But it's ugly and verbose, and worse, it includes actual JavaScript code, that serves no purpose other than to provide type information.

Examples

Rather, what I would like to do is something like this (that I would like to be equivalent to the snippet above):

/**
 * @property {Object} [otherProperty]
 */
class DTO {
    constructor(id) {
         /**
          * @type {string}
          */
         this.id = id;
    }
}

Another equivalent alternative could be (but currently doesn't compile because of a "Duplicate identifier" error):

/**
 * @typedef {Object} DTO
 * @property {string} id
 * @property {Object} [otherProperty]
 */
class DTO {
    constructor(id) {
         this.id = id;
    }
}

Or, otherwise, some way to indicate this class can be extended with anything. Which means I would like a way to specify the following TypeScript using JSDoc and I want it to apply to an existing ES6 class (because I do use the class to be able to do instanceof checks):

interface DTO {
    id: string,
    [key: string]: any,
}

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript / JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. new expression-level syntax)

[RyanCavanaugh]

@sandersn can this be accomplished with declaration merging today?

[sandersn]

Is the ideal solution a list of possible properties, or can the DTO truly hold any property that will come along?

There are a couple of workarounds you can use:

1. As @RyanCavanaugh suggested, you can create a d.ts that merges with DTO:

interface DTO {
  [key: string]: any
}

Merging happens automatically in scripts (since they're all global), or you will have to wrap the interface in declare module "mymodule" { ... } if you're using ES6 modules.

As you point out, @typedef does NOT merge with classes, because it creates a type alias, not an interface.

2. If you can use ES Next features, property declarations would solve the individual property list problem:

class C {
  /** @type {Object?} */
  otherProperty;
  constructor(id) {
    this.id = id;
  }
}

This feature isn't done yet either, but is tracked by #27023.

[arendjr]

I'm sorry, I'm probably missing something. If I create a .d.ts file with the same basename as the .js file, it seems to shadow it, so I don't think that's what I should be doing. But adding it with a different basename it seems to have no effect at all, I don't see any "automatic merging" happening (I am using CommonJS indeed) and I don't know how I would need to import the interface otherwise.

I'm not that well-versed in TypeScript, so I'm feeling a little lost here...

[sandersn]

Yes, you are correct, X.d.ts and X.js causes X.d.ts to shadow the JS file. If you are using a tsconfig.json (or jsconfig) then you need to make sure both the js and d.ts are included in the files list or glob. Otherwise, you'll need an explicit <reference path="Y.d.ts" /> inside of X.js.

I'm not actually sure whether CommonJS needs to use module augmentation syntax in order to merge with .d.ts interfaces. Let me check...

[sandersn]

Bad news. CommonJS modules do indeed require matching module augmentation syntax, but it does not work right now. Here's what I got to work in Typescript:

// @Filename: ex.d.ts
export var dummy: number;
declare module "./welove" {
  interface DTO {
    // (number is more obvious when it works)
    [s: string]: number 
  }
}
// @Filename welove.ts
export class DTO {
  constructor(public n: number) { }
}
var c = new DTO(1)
c.n // ok
c.w // ok

Unfortunately, the same thing doesn't work with commonjs:

// @Filename: ex.d.ts
export var dummy: number;
declare module "./test" {
  interface DTO {
    // (number is more obvious when it works)
    [s: string]: number 
  }
}
// @Filename test.js
class DTO {
  /** @param {number} n */
  constructor(n) { 
    this.n = n
  }
}
var c = new DTO(1)
c.n // ok
c.w // error
module.exports = { DTO }

I'll file a bug to make sure this works.

At this point, I think we have 3 proposals to solve this problem. Unfortunately, none of them work right now!

[sandersn]

Never mind. Thanks to @Andy-MS for pointing out that the distinction is not TS vs JS, but ES exports vs CommonJS value exports. That is, this works:

// @Filename: ex.d.ts
export var dummy: number;
declare module "./test" {
  interface DTO {
    [s: string]: any
  }
}
// @Filename test.js
module.exports.DTO = class {
    /** @param {number} id */
    constructor(id) {
        this.id = id
    }
}
var c = new module.exports.DTO(1);
c.id  // ok
c.w // ok

But my previous example, with module.exports = { DTO }, does not. But it also doesn't work in TS, where you use the syntax export = DTO. That's because it creates an object literal and the compiler only knows how to augment modules, not object literals.