Discriminated unions in JSDoc

Two shapes, one name

API responses often have a tag field that decides the shape:

{ "kind": "ok",  "value": 42 }
{ "kind": "err", "message": "boom" }

This is a discriminated union: same union type, the kind field picks which branch you're in. In JSDoc you express it as two @typedefs plus a third that unions them:

/**
 * @typedef {Object} Ok
 * @property {"ok"} kind
 * @property {number} value
 */
/**
 * @typedef {Object} Err
 * @property {"err"} kind
 * @property {string} message
 */
/** @typedef {Ok | Err} Result */

How the editor narrows

When you check the discriminator, the editor narrows the type:

/** @param {Result} r */
function describe(r) {
  if (r.kind === "ok")  return "got " + r.value;     // r is Ok here
  if (r.kind === "err") return "fail: " + r.message; // r is Err here
}

Inside each branch, IntelliSense only suggests the fields valid for that shape — same as TypeScript discriminated unions.

The take-home

Tagged unions encode "API guarantees this OR that, never both" directly in the type. Cheap, robust, no compiler required.