Two mechanisms combine, and either alone is harmless.
**1. JSDoc is a type declaration, not a comment.** Under checkJs, an undocumented function has implicitly-`any` parameters and accepts anything. The moment any `@param` is added, TypeScript uses the annotation, and every call site is re-checked against it. A "docs-only" diff is therefore a typing diff.
**2. `Object.freeze` produces `readonly T[]`, which is not assignable to `T[]`.** The assignability is one-way: `T[]` is assignable to `readonly T[]`, never the reverse, because a mutable parameter type advertises the right to push or sort. So the natural-looking `@param {object[]}` rejects exactly the frozen value the codebase was built to pass.
The result was five errors across four files, including one knock-on `ts(2322)` where a *return* type narrowed too — the object literal's inferred `route: object` property no longer matched a consuming interface that had previously received `any`.
**Why it is easy to miss.** The unit test runner imports library modules directly and never type-checks. Only the full project check compiles the entry/page files that hold the call sites, and that check may run only inside a long build lane. The failing commit's own tests were green.
Problem details
- Observed symptom
- A documentation-only commit — adding a JSDoc block to an exported JavaScript function that previously had none — introduces type errors in caller files the commit never touched. The errors do not appear in the unit test suite; they surface only under a full type-check pass that compiles the caller files.
- Context
- A JS codebase type-checked with checkJs. One exported function was undocumented, so TypeScript inferred `any` for its positional parameters and every call site type-checked freely. A comment was added to explain a newly added options flag; while writing it, the two existing positional parameters were annotated for completeness — `@param {object[]} candidates`. The project passes a deeply frozen (Object.freeze) array to that parameter everywhere, which infers as `readonly any[]`.
- Environment
- State
- partial
- Text
- Any JavaScript project type-checked with checkJs/allowJs where JSDoc is the type source, and where some values are Object.freeze'd. Observed with a framework-provided `check` command that compiles page/entry files the unit test runner never imports.
- Symptom signature
- Literal error text
- error ts(2345): Argument of type 'readonly any[]' is not assignable to parameter of type 'object[]'. The type 'readonly any[]' is 'readonly' and cannot be assigned to the mutable type 'object[]'.
- Error code
- ts(2345)
- Component
- JSDoc @param type inference under checkJs
- Operation
- type-check of a JS project after adding a JSDoc block
- Literal source
- contributor_supplied
- Expected behavior
- Adding a comment to a function is expected to be type-neutral. It is not: it converts inferred `any` into a declared type, and that declaration is then enforced against every existing call site.
Known approaches
solution · Revision 1
Annotate the parameter as readonly, or leave positional parameters untyped and document only the new option
Two fixes, chosen by intent.
**If the goal is documentation, keep it type-neutral.** Document the new option in the `@param` for the options object only, and annotate the pre-existing positional parameters as `any` (or omit them, though a partial `@param` list is its own hazard). A comment can then carry the explanation without changing what compiles. Recording *why* they are untyped in the comment itself stops the next person re-introducing it.
**If the goal is real typing, make it readonly.** `@param {readonly any[]}` or `@param {ReadonlyArray<T>}` accepts both frozen and mutable arrays, and is the honest type for a parameter the function does not mutate. Expect a second round: narrowing a parameter often narrows the inferred return type too, which can break a consumer that was receiving `any`.
Either way the load-bearing habit is to run the project's full type-check after a JSDoc change, because a unit suite that imports modules directly will not compile the call sites.
- Problem id
- 5babcf77-bade-4bb8-b3f4-8c6ead571b76
- Proposed action
- Use `@param {readonly any[]}` (or `ReadonlyArray<T>`) for any parameter that receives a frozen array, and widen a parameter to `any` rather than a structural type when the surrounding code has never been type-checked against a narrower one. Then re-run the FULL project type-check — not the unit suite — before considering a documentation commit finished.
- Applicability
- State
- known
- Text
- JavaScript projects using checkJs/allowJs with JSDoc as the type source, where values are frozen with Object.freeze. Applies to any JSDoc annotation added to a function that previously had none.
- Limitations
- State
- known
- Text
- Verified on one codebase, for the array case and one knock-on return-type error. `readonly` is not a fix when the function genuinely mutates the argument — there the frozen value is the real defect and would throw at runtime in strict mode. Not verified for generics or for TS 5.x `const` type parameters.
- Success criteria
- State
- known
- Text
- The full project type-check reports 0 errors, and the call sites the JSDoc commit never touched are unchanged.
- Risk notes
- Not supplied
- Lifecycle
- active
Page 1 · 1 children total
Sources and related records
No source relations recorded.