The quirks of JSDoc in TypeScript

/* @param {string} title */
export function slugify(title) {error TS7006: Parameter 'title' implicitly has an 'any' type.
  return title.toLowerCase().replace(/\s+/g, "-");
}

/** @param {number[]} prices */
/** Adds up a list of prices. */
export function total(prices) {error TS7006: Parameter 'prices' implicitly has an 'any' type.
  let sum = 0;
  for (const price of prices) sum += price;
  return sum;
}

export class Cart { /** @param {number} cents */
  add(cents) {error TS7006: Parameter 'cents' implicitly has an 'any' type.
    return cents;
  }
}

export class Wishlist {
  /** @param {string} sku */
  add(sku) {
    return sku;
  }
}

/** @param {number} cents */
const CURRENCY = "USD";

export function formatCents(cents) {error TS7006: Parameter 'cents' implicitly has an 'any' type.
  return `${(cents / 100).toFixed(2)} ${CURRENCY}`;
}

// Hover normalizeCode: TypeScript shows an author tag reading "Jane Doe jane"
// and an example tag reading ".com", because the email is not in angle brackets.
/**
 * Lowercases a product code.
 *
 * @author Jane Doe jane@example.com
 * @param {string} code
 */
export function normalizeCode(code) {
  return code.toLowerCase();
}

/**
 * @typedef {object} Order
 * @property {string} id
 * @readonly
 * @property {number} total
 */

/** @type {Order} */
const order = { id: "A-100", total: 42 };error TS2353: Object literal may only specify known properties, and 'total' does not exist in type 'Order'.

export { order };

/**
 * @property {string} sku
 */
export class Product {}

new Product().sku;error TS2339: Property 'sku' does not exist on type 'Product'.

class Counter {
  count = 0;
}

/** @extends {Counter} */
export class Tally {
  bump() {
    this.count += 1;error TS2339: Property 'count' does not exist on type 'Tally'.
  }
}

export class Tally extends Map {
  /** @param {string} key */
  bump(key) {
    this.set(key, (this.get(key) ?? 0) + 1);
    return this;
  }
}

// No error: the base class is Map<any, any>, so a number key and a string value pass.
new Tally().set(1, "one");

/** @constructor */
export function Account() {
  /** @private */
  this.balance = 0;error TS2341: Property 'balance' is private and only accessible within class 'Account'.
}

/** @enum {string} */
export const Status = {
  Draft: "draft",
  Live: "live",
};

/** @param {Status} status */
export function setStatus(status) {
  return status;
}

// Status means string here, so a value that is not in the enum still passes.
setStatus("deleted");

/**
 * @callback Compare
 * @param {string} a
 * @param {string} b
 */

/** @type {Compare} */
const byLength = (a, b) => a.length - b.length;

const result = byLength("tea", "coffee");
result.toUpperCase();

export { byLength };

/** @import { Ordr } from "./types.js" */

/** @param {number} total */
export function report(total) {
  return `Total: ${total}`;
}

/** @this {HTMLButtonElement} */error TS2730: An arrow function cannot have a 'this' parameter.
export const onClick = () => {
  console.log("clicked");
};

import express from "express";

const app = express();

/** @type {import("express").RequestHandler<{ id: string }>} */
const getUser = (req, res) => {error TS2355: A function whose declared type is neither 'undefined', 'void', nor 'any' must return a value.
  res.json({ id: req.params.id });
};

app.get("/users/:id", getUser);

export function createCart() {
  return { lines: /** @type {string[]} */ ([]) };
}

// TypeScript resolves a value name in JSDoc to the value's type, so this passes in a .js file.
/** @type {ReturnType<createCart>} */
const cart = createCart();

export { cart };

/**
 * @template T
 * @returns {{ items: T[] }}
 */
export function createStore() {
  return { items: [] };
}

// T has no inference source here, so in a .js file it becomes any: nothing is checked.
const loose = createStore();
loose.items.push(1, "two");

/** @type {{ items: number[] }} */
const counts = createStore();
counts.items.push(1);
counts.items.push("two");error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

export { loose, counts };

const orders = [{ id: "A-100", totalCents: 4250 }];

export function totalOf(id) {
  const order = orders.find((o) => o.id === id);
  return order.totalCent;
}

totalOf(100);

// 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 };

function greet(name, greeting) {
  return (greeting || "Hello") + ", " + (name || "you");
}

/**
 * @param {string} name
 * @param {string} greeting
 */
function greetTyped(name, greeting) {
  return greeting + ", " + name;
}

greet();
greet("Ada");
greetTyped("Ada");error TS2554: Expected 2 arguments, but got 1.

/** @typedef {{ theme: "light" | "dark", pageSize: number }} Settings */

/** @type {Settings} */
const annotated = { theme: "dark", pageSize: 24 };

// The cast is accepted although pageSize is missing: a cast claims, it does not check.
const cast = /** @type {Settings} */ ({ theme: "dark" });

/** @satisfies {Settings} */
const checked = { theme: "dark", pageSize: 24 };

/** @type {"dark"} */
const fromChecked = checked.theme;

/** @type {"dark"} */
const fromAnnotated = annotated.theme;error TS2322: Type '"light" | "dark"' is not assignable to type '"dark"'.
  Type '"light"' is not assignable to type '"dark"'.

export { cast, fromChecked, fromAnnotated };

/** @typedef {{ id: string, sku: string, price: number }} Product */

// No error: Omit accepts any key, so the typo removes nothing.
/** @typedef {Omit<Product, "iid">} Draft */

/** @type {Draft} */
const draft = { id: "p_1", sku: "TEE-01", price: 19.5 };

export { draft };

/**
 * @param {unknown} value
 * @returns {item is { sku: string }}
 */
export function isProduct(value) {
  return typeof value === "object" && value !== null && "sku" in value;
}

/** @param {unknown} row */
export function label(row) {
  return isProduct(row) ? row.sku : "unknown row";error TS18046: 'row' is of type 'unknown'.
}

/**
 * @param {number} cents
 * @returns {string}
 */
export function formatPrice(cents) {
  return `${formatPrice.symbol.trim()}${(cents / 100).toFixed(2)}`;error TS2339: Property 'trim' does not exist on type 'string | number'.
  Property 'trim' does not exist on type 'number'.
}
formatPrice.symbol = "$";

formatPrice.symbol = 36;
console.log(formatPrice.currency);error TS2339: Property 'currency' does not exist on type 'typeof formatPrice'.

/**
 * @template T
 * @param {T[]} items
 * @returns {T | undefined}
 */
export function first(items) {
  return items[0];
}

/** @type {unknown[]} */
const rows = ["TEE-01"];
const sku = first<string>(rows);error TS2365: Operator '>' cannot be applied to types 'boolean' and 'unknown[]'.error TS2693: 'string' only refers to a type, but is being used as a value here.

export { sku };

/** @param {...[string, number]} entries */
export function addStock(...entries) {
  return entries.length;
}

addStock(["TEA-01", 3], ["CUP-02", 1]);
addStock("TEA-01", 3);error TS2345: Argument of type 'string' is not assignable to parameter of type '[string, number]'.

/** @param {[string, ...number[]]} args */
export function receive(...args) {
  return args.length;
}

receive("TEA-01", 3, 4);

/** @type {{ street: string, unit: string= }} */error TS1247: A type literal property cannot have an initializer.error TS1109: Expression expected.
const address = { street: "12 Market St" };error TS2741: Property 'unit' is missing in type '{ street: string; }' but required in type '{ street: string; unit: string; }'.

export { address };

/** @type {!HTMLElement} */
const link = document.querySelector("a");error TS2322: Type 'HTMLAnchorElement | null' is not assignable to type 'HTMLElement'.
  Type 'null' is not assignable to type 'HTMLElement'.

export { link };

/** @type {Array<string>} */
const tags = [];

/** @type {array} */error TS2552: Cannot find name 'array'. Did you mean 'Array'?
const legacyTags = [];

/** @param {promise} pending */error TS2552: Cannot find name 'promise'. Did you mean 'Promise'?
export function settle(pending) {
  return pending;
}

export { tags, legacyTags };