_code-rules-TypeScript-summary

This file is an always-applied concise summary of ./.cursor/rules/_code-rules-TypeScript.mdc. Every rule below is binding; when a point is ambiguous or an edge case arises, read the original ./.cursor/rules/_code-rules-TypeScript.mdc for the full rationale, canonical code examples, and boundary clarifications.

PRINCIPLES

• DRY - one authoritative location for every piece of knowledge.
• SoC - each module and function owns exactly one concern.
• Modularity - small, named, independently testable units connected by stable typed interfaces.
• Readability - names and structure carry meaning; comments fill only gaps code cannot convey.
• Iterability - changes to one concern must not cascade into unrelated code.

FORMATTING

• Indent with 1 tab (\t) per level; never spaces.
• Double quotes ("…") for all string literals; template literals only for interpolation or multiline strings; never single quotes.
• Terminate every statement with a semicolon (;).
• Use only a plain hyphen-minus (-); never an en dash or em dash.
• Maximum 100 physical lines per named function/method (blank lines count; JSDoc above does not). Split responsibilities into smaller named functions when the limit would be exceeded.

TRAILING COMMAS & SEPARATORS

• Multiline array literals, object literals, and call-site argument lists: trailing comma after the last item.
• Formal parameter lists (non-empty): always a trailing comma after the last parameter, even on a single physical line (e.g. function foo(bar: Baz,)).
• Empty parameter lists: no comma inside ().
• Use commas to separate runtime lists (parameters, arguments, destructuring bindings, array/object elements, tuple element types). Generic lists <T, U> and import type { Foo, Bar } keep commas wherever TS/ECMAScript syntax requires them.
• Use semicolons to separate members inside interface bodies and inline object-type shapes. Do not use ; between tuple element types.

NAMING CONVENTIONS

• camelCase: variables, functions, parameters (leading _ allowed for unused; no trailing _).
• UPPER_CASE: every hardcoded configuration literal assigned to a const (timeouts, limits, HTTP methods, status codes, path segments, feature flags, multipliers). Shared styling classes also use UPPER_CASE. Runtime-varying data (request fields, parsed JSON, loop indices, intermediates) stays camelCase unless it is a true compile-time-style constant.
• PascalCase: classes, interfaces, type aliases.
• No I prefix on interfaces (UserAccount, not IUserAccount).
• snake_case bindings only when mirroring an external schema (REST/JSON, DB rows, vendor SDKs). Keep snake_case local and aligned with upstream field names only where renaming would obscure protocol or storage reality.

NO MAGIC NUMBERS

• Never use a bare numeric literal directly in an expression. Assign it to a named UPPER_CASE const first, then reference the binding.
• Exception: obvious pure-bookkeeping indices such as index + 1.
• Domain-specific bare numbers (timeouts, HTTP codes, limits, geodetic bounds) must always be named first.

MULTILINE FORMATTING

• Arrays / objects: one element or property per physical line.
• Compound boolean predicates (&&, ||): one operand/sub-condition per physical line everywhere they appear - if, while, do…while, for-condition, ternary condition, const/let boolean bindings, return, throw.
• for-loop headers: one clause per physical line (initializer / condition / update).
• Non-empty function signatures: async (if any), function, and name on one line followed by (; one parameter per physical line (each ends with a trailing comma); close with ): ReturnType { on its own line. Empty parameter lists stay compact: function f().
• Inline object type annotations ({ … }): expand across multiple lines - { alone, each member: Type; on its own line, } alone before =, ), :, as, or the following token. Prefer a type/interface under ./src/types/** when the shape repeats.

VARIABLES

• Never var.
• const by default; let only when a binding must be reassigned.
• Destructuring: const when no binding in the pattern is reassigned; let when any binding needs reassignment. You cannot mark one binding const and another let in the same pattern - split into multiple declarations when only some fields must stay mutable.
• let/const are block-scoped with a temporal dead zone; prefer them over var to avoid accidental reads before initialization and leakage across branches.