typescript

name	typescript
description	Use when changing TypeScript types, refactoring signatures, or reviewing typing style. Prefer inference for internal functions and locals; keep explicit return types only when they carry API intent or are required for correctness, such as overloads or unstable generic or recursive inference.

typescript

Apply these preferences when editing TypeScript in this repo:

• Omit explicit return types on internal functions unless they are necessary.
• Keep explicit return types when they define public API intent, support overloads, or prevent degraded inference in generic or recursive code.
• Treat broad result aliases as boundary contracts, not default internal implementation types.
• Prefer letting better-result infer concrete error unions for internal helpers instead of widening to a shared error alias.
• Use satisfies to check object shape without replacing inferred types.
• Add or update compile-time tests when changing public signatures or important inferred types.
• Treat casts as suspicious by default: if a cast exists only to force a helper or factory result into the desired shape, first ask whether the owning types should preserve that information directly.

When choosing between inference and annotation:

• Default to inference for local variables and non-exported helpers.
• Add an explicit annotation when it improves readability, pins a public contract, or avoids incorrect inference.
• Remove casts that only exist to force a broader type than the implementation actually produces.
• Remove casts that only compensate for lost generic information when the owning API can be fixed instead.
• Reintroduce an explicit annotation only if typechecking, declaration output, or call-site ergonomics become worse without it.