JS with Types Start

Type expression

Arrays

  • Collections
  • Tested with TypeScript 5.9

An array type is the element type followed by [], as in {string[]}, or the generic form {Array<string>}; the two are the same type. TypeScript checks every element you add and types every element you read.

For an array of objects, put the object type before the brackets, {{ sku: string, quantity: number }[]}, or name the object with @typedef and write {LineItem[]}.

At a glance

Use JSDoc in a .js file TypeScript in a .ts file
Array of strings /** @type {string[]} */ : string[]
Generic spelling /** @type {Array<string>} */ : Array<string>
Array of objects /** @type {{ sku: string, quantity: number }[]} */ : { sku: string; quantity: number }[]
Closure spelling /** @type {Array.<string>} */ : Array<string>

Examples

cart.js cart.ts TypeScript 5.9.3 TypeScript 5.9.3, run 21 October 2026: No errors. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. No errors. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. No errors. checked 21 October 2026 
/** @type {string[]} */
const sizes = ["S", "M", "L"];

/** @type {Array<number>} */
const prices = [19.5, 12];

/** @type {{ sku: string, quantity: number }[]} */
const lines = [{ sku: "TEE-01", quantity: 2 }];

/** @type {Array<{ sku: string, quantity: number }>} */
const saved = [];

sizes.push("XL");
saved.push(...lines);
prices.map((p) => p.toFixed(2));

export { sizes, prices, lines, saved };
const sizes: string[] = ["S", "M", "L"];

const prices: Array<number> = [19.5, 12];

const lines: { sku: string; quantity: number }[] = [{ sku: "TEE-01", quantity: 2 }];

const saved: Array<{ sku: string; quantity: number }> = [];

sizes.push("XL");
saved.push(...lines);
prices.map((p) => p.toFixed(2));

export { sizes, prices, lines, saved };
Arrays in both spellings, and arrays of objects.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}
sizes.js Error confirmed 5.9.3 TypeScript 5.9.3, run 21 October 2026: sizes.js(5,12): error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. sizes.js(5,12): error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. sizes.js(5,12): error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'. checked 21 October 2026 
/** @type {string[]} */
const sizes = ["S", "M", "L"];

sizes.push(42);error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

export { sizes };
An element of the wrong type.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}
ids.js Error confirmed 5.9.3 TypeScript 5.9.3, run 21 October 2026: ids.js(10,19): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. ids.js(10,19): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. ids.js(10,19): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'. checked 21 October 2026 
// In a .js file an empty array literal starts as any[], so nothing below is checked.
const ids = [];
ids.push(100);
ids.push("A-101");

/** @type {number[]} */
const orderNumbers = [];
orderNumbers.push(100);
orderNumbers.push("A-101");error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

export { ids, orderNumbers };
An untyped empty array accepts anything; a typed one does not.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}

Empty arrays need a type

In a .js file, const ids = [] starts as any[], so anything can be pushed into it, and its element type becomes whatever was pushed, as the third example shows. Give empty arrays a type at the declaration: /** @type {number[]} */ const ids = [];.

An array literal with elements is typed from them: ["S", "M"] is string[].

Arrays of unions

Parentheses matter with unions. {(string | number)[]} is an array whose elements are strings or numbers; {string | number[]} is either one string or an array of numbers.

Gotchas

  • Reading items[5] is typed as the element type even when the array is shorter. The noUncheckedIndexedAccess option adds undefined to such reads.
  • For an array that should not change, use readonly string[]; for a fixed number of elements, use a tuple.

Questions

How do I write an array of objects in JSDoc?

@type {{ name: string, price: number }[]}, or define the object with @typedef and use @type {Product[]}. Array<Product> works too.

Is Array<string> the same as string[]?

Yes. They are two spellings of one type, and the older Array.<string> is a third.

  • Type expression

    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.

  • Type expression

    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.

  • Type expression

    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.

  • JSDoc tag

    @typedef

    The JSDoc @typedef tag names a reusable type: an object type built from @property lines, a union or anything else. Every @typedef in a module is exported.

Sources

Last reviewed 20 October 2026.