JS with Types Start

Reference

Type expressions in JSDoc

Inside the braces of @type, @param or @returns, TypeScript reads ordinary TypeScript type syntax, plus a few older JSDoc forms. This reference covers those expressions one at a time, grouped from the basics through the utility types to the older Closure forms, each next to its TypeScript spelling.

Basics

The building blocks: primitives, literals, any and unknown, null and undefined, void and never, and the three object types.

  • Primitive types

    The primitive types in JSDoc are string, number, boolean, bigint and symbol, written in lowercase as in TypeScript. Examples, and the capital-letter trap.

    • {string}

  • Literal types

    A literal type is one exact value, such as "GET" or 5, used as a type. In JSDoc it goes inside the braces as in TypeScript, usually in a union of values.

    • {"GET" | "POST"}

  • any and unknown

    any turns checking off for a value; unknown accepts any value but makes you check it before use. Which one to write in JSDoc, and what {*} and {?} mean.

    • {unknown}

  • null, undefined and nullable types

    How to write a nullable type in JSDoc: {string | null}, the {?string} shorthand, and undefined. Why TypeScript makes you check before use, with strict on.

    • {string | null}

  • void and never

    void means a function's result is not used; never means a function never returns or a value cannot exist. How to write both in JSDoc and where each one helps.

    • {void}

  • object, Object and {}

    In JSDoc, {object} accepts any non-primitive, while {Object} and {} accept almost any value. None describes properties; for that, write the object's shape.

    • {object}

Collections

Arrays, tuples, object shapes, dictionaries, Map and Set, promises and read-only arrays.

  • Arrays

    Typing arrays in JSDoc: {string[]} or {Array<string>}, arrays of objects, union elements, and why an empty array literal needs a type in a .js file.

    • {string[]}

  • Tuples

    A tuple is an array with a fixed length and a type per position. Writing tuples in JSDoc, with named, optional and rest elements, and when you need one.

    • {[number, number]}

  • Object shapes

    Writing an object type inline in JSDoc: double braces, optional properties with ?, commas or semicolons, and the postfix = that does not mean optional.

    • {{ street: string, unit?: string }}

  • Record<K, V> and Object.<K, V>

    Record<K, V> types an object used as a dictionary. In JSDoc it is written as in TypeScript; Object.<K, V> and index signatures mean the same thing.

    • {Record<string, number>}

  • Map, Set and WeakMap

    Typing Map, Set, WeakMap and WeakSet in JSDoc: put the type arguments in @type, because new Map() alone is Map<any, any>. Examples of get, set and has.

    • {Map<string, number>}

  • Promise and async functions

    Typing promises and async functions in JSDoc: @returns {Promise<T>}, typing fetch().json() results, new Promise, and the missing-await error TypeScript catches.

    • {Promise<Product[]>}

  • Readonly arrays

    readonly string[] and ReadonlyArray<string> are arrays without push, sort or other changing methods. Use them to promise a function leaves its input alone.

    • {readonly string[]}

Functions

Function types in both spellings, optional and rest parameters, this, constructors, type predicates and assertion functions.

  • Function types

    Writing function types in JSDoc: TypeScript's arrow syntax (price: number) => string, the older function(number): string, and Function. Examples and errors.

    • {(price: number) => string}

  • Optional and default parameters

    How to mark a JSDoc parameter optional: [name], name= in the type, or a default value. Why typed parameters become required, and the undefined check inside.

    • {string} [label]

  • Rest parameters

    A rest parameter in JSDoc is written @param {...string} tags: the element type after three dots. Inside the function the parameter is a string[]. Examples.

    • {...string}

  • this parameters

    A this parameter types this inside a function. In JSDoc, write it first in a function type, (this: HTMLInputElement) => void, or use @this on a declaration.

    • {(this: HTMLInputElement, event: Event) => void}

  • Constructor types

    A constructor type describes a class passed as a value: new (sku: string) => T, or typeof Shirt for one class. Both in JSDoc, with a generic factory.

    • {new (sku: string) => T}

  • Type predicates

    A type predicate, @returns {item is Product}, turns a boolean function into a type guard that narrows in if statements and filter(). JSDoc syntax and examples.

    • {item is Product}

  • Assertion functions

    An assertion function throws unless a check holds, and TypeScript narrows the code after it. JSDoc: @returns {asserts value is string} or {asserts condition}.

    • {asserts value is string}

Generics

Type parameters with @template: the basics, constraints, defaults, generic classes and how inference fills them in.

  • Generics with @template

    Generics in JSDoc: declare type parameters with @template T, use T in @param and @returns, and let TypeScript infer it at each call. Generic function examples.

    • @template T

  • Generic constraints

    A constraint limits what a type parameter accepts: @template {string} K is TypeScript's K extends string, written in braces before the name. With examples.

    • @template {string} K

  • Default type arguments

    A default type argument, @template [T=string], fills in T when nothing else does. Supported in JSDoc since TypeScript 4.5, on typedefs, classes and functions.

    • @template [T=string]

  • Generic classes

    A generic class in JSDoc: @template T above the class, T in the members' tags, and the type argument on the variable, since new Queue<T>() is not JavaScript.

    • @template T

  • Type inference for generics

    How TypeScript infers @template type parameters in JavaScript, which has no explicit type arguments: from arguments, from the variable's type, and with const T.

    • @template const T

Combining types

Building new types from old ones: unions, intersections, keyof, typeof, indexed access, conditional, mapped and template literal types.

  • Union types

    A union type says a value is one of several types: {string | number} in JSDoc, written as in TypeScript. How to write one, and how to narrow it before use.

    • {string | number}

  • Intersection types

    An intersection type, A & B, is a value that is both: every property of A and of B. Written the same in JSDoc; the usual way to extend a @typedef.

    • {Product & Stored}

  • Discriminated unions

    A discriminated union is a union of object types sharing a literal property such as kind; checking it narrows the value. JSDoc syntax and examples.

    • {{ kind: "circle", radius: number } | { kind: "square", side: number }}

  • keyof

    keyof Product is the union of Product's property names. Use it in JSDoc for parameters that take a field name, and keyof typeof for the keys of an object value.

    • {keyof Product}

  • typeof in types

    typeof in a JSDoc type gives you the type of a value, such as a config object or a function, without writing it twice. How it differs from JavaScript's typeof.

    • {typeof defaults}

  • Indexed access types

    An indexed access type, Order["status"], is the type of one property of another type. In JSDoc it looks the same; [number] gives an array's element type.

    • {Order["status"]}

  • Conditional types

    A conditional type chooses between two types by testing a third: T extends string ? A : B. In JSDoc it lives in a generic @typedef. infer and unions explained.

    • {T extends string ? "text" : "other"}

  • Mapped types

    A mapped type builds an object type with one property per key of another: { [K in keyof T]?: string }. Writing mapped types in JSDoc, with key renaming.

    • {{ [K in keyof T]?: string }}

  • Template literal types

    Template literal types describe string patterns, such as ${number}px or on${Capitalize<Interaction>}. They work inside JSDoc braces, backticks included.

    • {`${number}px`}

Utility types

TypeScript's built-in type helpers, written inside JSDoc braces exactly as in a .ts file.

  • Partial<T>

    Partial<T> makes every property of T optional. Use it in JSDoc for update payloads, options and fixtures; the types of the properties present stay checked.

    • {Partial<Product>}

  • Required<T>

    Required<T> makes every property of T mandatory, the reverse of Partial. Useful in JSDoc for options after their defaults are filled in. Examples and errors.

    • {Required<PriceOptions>}

  • Readonly<T>

    Readonly<T> makes every property of T read-only, so assignments are errors. Use it in JSDoc to promise a function will not modify an object. It is shallow.

    • {Readonly<Product>}

  • Pick<T, K>

    Pick<T, K> builds a type with only the properties K of T. In JSDoc it names smaller views of a type, such as a card, and checks that the keys exist.

    • {Pick<Product, "sku" | "name">}

  • Omit<T, K>

    Omit<T, K> is T without the properties K, such as a product before it has an id. How to use it in JSDoc, and why a misspelled key is not caught.

    • {Omit<Product, "id">}

  • Exclude<T, U> and Extract<T, U>

    Exclude<T, U> removes union members assignable to U; Extract<T, U> keeps them. Use them in JSDoc to filter literal unions and discriminated unions. Examples.

    • {Exclude<Status, "deleted">}

  • NonNullable<T>

    NonNullable<T> removes null and undefined from a type. Use it in JSDoc for the value after a check or a default, and in helpers that filter out empty values.

    • {NonNullable<Product["discount"]>}

  • ReturnType<T>

    ReturnType<typeof fn> is the type a function returns. In JSDoc it names a factory's result without writing it twice; .js files also accept it without typeof.

    • {ReturnType<typeof createCart>}

  • Parameters<T>

    Parameters<typeof fn> is a tuple of a function's parameter types. Use it in JSDoc for wrappers that pass arguments through, or to name one parameter type.

    • {Parameters<typeof addToCart>}

  • Awaited<T>

    Awaited<T> is the value a promise resolves to, unwrapped as await does. In JSDoc, Awaited<ReturnType<typeof fn>> names an async function's result.

    • {Awaited<ReturnType<typeof loadAccount>>}

  • Other utility types

    InstanceType, ConstructorParameters, NoInfer, ThisParameterType, OmitThisParameter and the string case types, written in JSDoc as in TypeScript, with examples.

    • {InstanceType<typeof Cart>}

Importing and casting

Types from other modules, casts, const assertions, @satisfies, and what to write instead of the ! operator.

  • import() types

    An import type, import("./models.js").Product, uses a type from another module inside JSDoc braces without importing anything at run time. Since TypeScript 2.9.

    • {import("./models.js").Product}

  • Type casts

    A JSDoc cast is /** @type {T} */ (expression), parentheses included: the JavaScript spelling of expression as T. When casts fail, and what they never check.

    • /** @type {HTMLInputElement} */ (value)

  • const assertions

    /** @type {const} */ (value) is the JSDoc form of as const, since TypeScript 4.5: literal types kept, properties read-only, arrays turned into read-only tuples.

    • /** @type {const} */ ({ … })

  • Annotate, cast or satisfy

    Three ways to attach a type to a value in JSDoc: @type annotates, a cast claims, @satisfies checks and keeps the value's own type. When to use each one.

    • /** @satisfies {Settings} */

  • Non-null assertions in JavaScript

    TypeScript's ! operator is an error in a .js file. Four alternatives that work there: a check that throws, optional chaining, an assertion function, or a cast.

    • if (!total) throw …

Legacy syntax

The older Closure-style JSDoc forms, and which of them TypeScript still accepts.

  • Closure-style JSDoc types

    Which Closure Compiler JSDoc types TypeScript still accepts: ?string, !string, *, Array.<T>, Object.<K, V>, function(…) types, string= and ...T.

    • {?string}

The entries on this page are also published as data: type-expressions.json (about the data files).