JSDoc

Annotates a variable, class field, or type-alias position. The value string runs through the real type parser, so the whole type-expression grammar below is available inside it — including this compiler's integer width keywords.

/** @type {uint8} */
let r = 255
r = r + 1
console.log(r)                    // 0  (wrapped at 8 bits)

Types a parameter from the doc comment — the core of the typed-JavaScript workflow. It fills in only where the parameter has no inline annotation, so an existing `: T` always wins. The type body uses the full grammar below, and a `{number=}` or `[name]` optional decoration is recognized and stripped.

/**
 * @param {int32} a
 * @param {int32} b
 * @returns {int32}
 */
function idiv(a, b) {
  return a / b
}

Supplies a function's return type from the doc comment, filling in only when there is no inline `: RetType`.

/**
 * @param {string} s
 * @returns {number} the code unit count
 */
function width(s) {
  return s.length
}

Declares a named type. Both spellings work — the `@typedef {Object} Name` + `@property {T} field` form and the inline `@typedef {{x: number}} Name` object literal — and the result is synthesized into a `type Name = …` declaration, so it resolves anywhere a type name does.

/**
 * @typedef {Object} Point
 * @property {number} x
 * @property {number} y
 */

/** @param {Point} p */
function manhattan(p) {
  return p.x + p.y
}

Declares a named function type from its `@param`/`@returns` tags, synthesized into a function-type alias that is usable wherever a type name is.

/**
 * @callback Combine
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */

/** @param {Combine} fn */
function run(fn) {
  return fn(10, 5)
}

The JSDoc form of a `<T>` generic — it sets the function's type-parameter list and drives the exact same monomorphization a TS `<T>` does. `@erased` is the compile-once variant.

/**
 * @template T
 * @param {T[]} arr
 * @returns {T}
 */
function firstOf(arr) {
  return arr[0]
}

Accepted and erased, parity with the erased TS `satisfies` operator — the value keeps its own type and gets no conformance check.

Tags a `const` object for value access (`Dir.Up`). It stays a plain object, not a nominal enum type.

Accepted and erased. A `this` parameter type is not separately modeled — `this` is bound by the class method it lives in.

Accepted and erased — the class's own `extends` clause does the work; the tag does not add type arguments to a generic base.

Accepted and erased — like a TS `implements` clause here, it does not strictly enforce structural conformance.

Accepted and erased, not enforced — the same stance as the TS `public` field modifier here.

Accepted and erased, not enforced — no access checking (the TS `private` modifier is likewise erased, not enforced, here).

Accepted and erased, not enforced.

Accepted and erased, not enforced — no mutation checking, parity with the erased TS `readonly` modifier.

Accepted and erased — no override-consistency check.

Documentation-only; accepted with no compile effect, parity with TS's runtime behavior.

Documentation-only, no type effect — accepted, parity with TS.

Documentation-only, no type effect — accepted, parity with TS.

Documentation-only, no type effect — accepted, parity with TS.

The comment-form import statement is not synthesized. Use a normal `import` plus an `import("./m").T` type reference, which does resolve — see the type-expression table.

Marks a plain function as a constructor (legacy pre-`class` JS). Unsupported by design — this compiler uses real `class` declarations, not function-as-constructor.

Resolved by the same type resolver a TS annotation uses.

The `[]` suffix is handled by the resolver.

The optional decoration is recognized at the `@param` name/type level and stripped.

Stripped to the base `T`; the varargs value flows into a declared `...rest` parameter.

/**
 * @param {...number} nums
 */
function total(nums: number[]) {
  let t = 0
  for (const n of nums) t += n
  return t
}

The JSDoc string is parsed by the real type parser, so a union resolves like an inline one.

/** @param {number | string} v */
function kind(v) {
  return typeof v
}

A leading `?` marker becomes a union with null (`?number` → `number | null`).

The marker is stripped (`!number` → `number`) — TS treats non-null as no semantic change.

Inline object shapes resolve, and nested braces are supported (`@param {{x: number}}`) via balanced-brace scanning.

/** @param {{name: string, age: number}} u */
function greet(u) {
  return u.name
}

The Closure dot form (`Array.<T>`) is normalized to `Array<T>`.

Normalized to `Record<K, V>`, backed by real index-signature support — per-key read/write (`d[key]`) works, e.g. `@type {Object.<string, number>}` on a dictionary object.

Rewritten to the arrow form `(arg0: A) => B`.

/** @param {function(number): number} f */
function twice(f) {
  return f(f(3))
}

Both are normalized to `any`.

The `import("./m").Name` qualifier is dropped to the bare `Name`, which resolves under whole-program compilation when that module is part of the build.

Names introduced by `@typedef`/`@callback` resolve wherever a type name does; inline `{{…}}` typedefs work too.

The capitalized Closure-era synonyms remap to their lowercase primitives.

A compiler extension with no TypeScript equivalent: the real-integer escape hatch — exact semantics and bit-width storage, also usable in `@param`/`@returns`.

/** @type {int64} */
let bigExact = 9007199254740993
console.log(bigExact)             // 9007199254740993  (exact, via int64)

A compiler extension with no TypeScript equivalent: `float64` is the default `number`; `float32` is a narrower slot.

/** @type {float32} */
let ratio = 1 / 3
console.log(ratio)                // 0.3333333432674408  (float32 rounding)

A compiler extension with no TypeScript equivalent: opts a generic function out of monomorphization — the JSDoc analogue of a `<T>` the compiler compiles once.

A compiler extension: asserts a function is side-effect-free and referentially transparent, and ENFORCES it with a front-end pass — zero runtime/codegen cost, output byte-identical to the untagged function. Inside a @pure function (declaration, arrow binding, or function-expression binding, including capturing closures) the compiler rejects the five impurity classes: mutating a parameter (or anything reachable from it), mutating a captured/global binding, I/O (console/fs/fetch/…), nondeterminism (Math.random/Date.now/new Date()), and calling a function that is not itself @pure (purity is contagious). Local mutation is allowed — only observable effects are constrained.

/** @pure */
function sq(n: number): number { return n * n }