ts-r
  • Sound mode S-13, pre-alpha
  • Design record 0007, Accepted

TSR1302

Exported '{0}' can throw '{1}' but has no '@throws' tag. Document it with a '@throws' tag.

Opt-in: an exported function or public method can throw but has no '@throws' tag. Document what it throws with a '@throws' tag.

Rule S-13: Checked exceptions (level: sound). Reported by ts-r-check and ts-r-lsp in files that opt in to sound mode. See Sound mode.

What it means

This check is off by default. With exports-declare-throws = true in the [sound] configuration, an exported function, or a public method of an exported class, whose throws set isn't empty must declare it with @throws tags, so callers in other files and packages know what to handle. It's reported at the declaration name. Without the switch, only functions that already have @throws tags are held to them (TSR1301).

Example

With exports-declare-throws = true:

Spec case from design record 0007 (checked by the record's case harness, not by this site's build)
// An exported function that throws without a @throws tag.
export function port(text: string): number { // @expect TSR1302
  const n = Number(text);
  if (!Number.isInteger(n)) throw new RangeError("not a port");
  return n;
}

How to fix

  • Add the tag: /** @throws {RangeError} */.
  • Or catch inside and return a value instead (Row | null).
  • In the editor, the quick fix inserts the missing tags from the computed throws set.

Sound mode is defined in design record 0007 (accepted 2026-10-15).