JSDoc generic typedef for TypeScript

Question

I am using JSDoc in a JavaScript project which is checked using the TypeScript compiler.

In TypeScript, I can create a generic type like so:

type Optional<TType extends string> = { type: TType; optional?: boolean; } | { type: `${TType}?` };
type OptionalThing = Optional<'thing'>;

The resolved and flattened value of OptionalThing is now this:

type OptionalThing = 
  | { type: 'thing'; optional?: boolean; }
  | { type: 'thing?'; }

This type creates a type union where one member type has the literal and const thing value for the type field and it has an additional optional boolean field and the other member type has literal and const thing? for the type field and doesn't have the optional field.

The ? suffix on type is a short-hand syntax for marking a thing as optional in the problem I am solving so specifying optional in addition needs to be forbidden otherwise it would be possible to represent an invalid value: { type: 'thing?', optional: false }.

In other words:

/* These are allowed - they conform to the type */
const optionalThing1: OptionalThing = { type: 'thing?' };
const optionalThing2: OptionalThing = { type: 'thing', optional: true };
const optionalThing3: OptionalThing = { type: 'thing', optional: false };

// This is disallowed, `optional` cannot be specified while `type` has `?` suffix
const optionalThing4: OptionalThing = { type: 'thing?', optional: false };

// This is disallowed, `type` must be either `thing` or `thing?` const string
const optionalThing5: OptionalThing = { type: 'not literally "thing"' };

Playground (configured to TypeScript)

I am having trouble translating this to JSDoc that would have the same behavior in TypeScript. I tried this:

/** @typedef {{ type: T; optional?: boolean; } | { type: `${T}?`; }} Type<T> */
/** @template {string} T */

/** @typedef {Type<'thing'>} ThingType */
// Error: Type 'Type' is not generic.

Playground (configured to JavaScript)

How can I made a generic typedef in JSDoc such that the above TypeScript logic works the same way when TypeScript checks the JavaScript and JSDoc version?

I would define complex types in d.ts files and just use them in JS — Titian Cernicova-Dragomir
– Titian Cernicova-Dragomir, Commented Aug 4, 2022 at 14:27
How do you do that? Can I do that using /** @type {import('types.d.ts')} */? — Tomáš Hübelbauer
– Tomáš Hübelbauer, Commented Aug 4, 2022 at 14:30
no need for the d.ts If you export it should work with import('./types').Generic<{ o: string }> — Titian Cernicova-Dragomir
– Titian Cernicova-Dragomir, Commented Aug 4, 2022 at 14:45

Carlo Cannas · Accepted Answer · 2022-08-04 15:56:59Z

14

Your code is almost right, you just have to place in the same JSDoc comment both the @template and @typedef tags, like this:

/** 
 * @typedef {{ type: T; optional?: boolean; } | { type: `${T}?`; }} Type<T>
 * @template {string} T
 */

/**
 * @typedef {Type<'thing'>} ThingType
 */

Playground Link

In general, when you need to define a generic type you'll need to have alongside that @typedef tag also a @template tag in the same JSDoc comment.

You can't however place the ThingType typedef in the same JSDoc, otherwise it will become a generic type as well.

edited Aug 4, 2022 at 15:56

answered Aug 4, 2022 at 15:50

Carlo Cannas

3,28222 silver badges23 bronze badges

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

Collectives™ on Stack Overflow

JSDoc generic typedef for TypeScript

1 Answer 1

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related