MyAiConfiguration/shared/rules/typescript.md

TypeScript Code Guidelines

• Write clear, readable, maintainable code first.
• Prefer modern TypeScript and current ECMAScript syntax.
• Keep code simple and explicit.
• Avoid clever or overly abstract solutions.
• Follow the existing project style and architecture.
• Enable strict TypeScript settings where possible.
• Prefer strict: true.
• Avoid any.
• Prefer precise types over broad types.
• Prefer unknown over any for untrusted or unknown values.
• Narrow types explicitly before use.
• Prefer strongly typed models over loose objects.
• Avoid excessive type assertions.
• Avoid non-null assertions unless safety is guaranteed.
• Prefer discriminated unions for state and variant modeling.
• Prefer literal unions over arbitrary strings.
• Prefer enums only when they provide a clear benefit.
• Prefer readonly where mutation is not required.
• Prefer immutable data where practical.
• Avoid unnecessary mutation.
• Avoid global mutable state.
• Keep functions small and focused.
• Keep modules focused on a clear responsibility.
• Prefer composition over inheritance.
• Avoid unnecessary classes when functions and plain objects are sufficient.
• Avoid unnecessary interfaces and abstractions.
• Prefer concrete object types when no abstraction is required.
• Use interfaces primarily when extension, implementation contracts, or declaration merging is actually useful.
• Prefer type aliases for unions, compositions, mapped types, and local data models.
• Avoid unnecessary wrapper types.
• Avoid excessive generic complexity.
• Keep generic constraints explicit and meaningful.
• Avoid deeply nested conditional or mapped types unless they provide clear value.
• Prefer readable types over type-system cleverness.
• Avoid duplicated type definitions.
• Derive types from existing sources when practical.
• Do not duplicate backend contracts manually when generated or shared types are available.
• Prefer explicit return types for public APIs and non-trivial functions.
• Prefer inference for simple local variables.
• Avoid unnecessary annotations when inference is obvious.
• Prefer const by default.
• Use let only when reassignment is required.
• Avoid var.
• Prefer optional chaining and nullish coalescing where appropriate.
• Do not use || when 0, false, or empty strings are valid values.
• Handle null and undefined intentionally.
• Avoid mixing null and undefined without a clear convention.
• Prefer early returns over excessive nesting.
• Avoid deeply nested control flow.
• Avoid overly large functions.
• Avoid hidden side effects.
• Keep pure logic pure where practical.
• Prefer deterministic behavior.
• Avoid implicit runtime coercion.
• Use strict equality.
• Avoid unnecessary object spreading in hot paths.
• Avoid unnecessary array copies.
• Avoid unnecessary intermediate arrays.
• Avoid repeated .map(), .filter(), or .reduce() chains in performance-critical paths.
• Use array methods when they improve readability and performance is not critical.
• Prefer appropriate data structures such as Map and Set when lookup behavior requires them.
• Avoid O(n²) patterns when a better structure is practical.
• Measure performance before micro-optimizing.
• Avoid unnecessary JSON serialization and parsing.
• Avoid unnecessary deep cloning.
• Avoid JSON.parse(JSON.stringify(...)) as a cloning strategy.
• Prefer platform APIs such as structuredClone when deep cloning is actually required.
• Avoid synchronous blocking operations in server-side hot paths.
• Prefer asynchronous APIs for I/O.
• Always handle rejected promises.
• Avoid floating promises.
• Use await when sequencing is required.
• Use Promise.all for independent operations when safe.
• Limit concurrency for large workloads.
• Avoid uncontrolled Promise.all over very large collections.
• Support cancellation with AbortSignal where applicable.
• Clean up event listeners, timers, subscriptions, streams, and resources.
• Avoid memory leaks caused by retained closures or listeners.
• Do not swallow exceptions.
• Preserve useful error context.
• Use typed domain errors where they improve handling.
• Avoid exceptions for normal control flow.
• Validate external input at system boundaries.
• Never trust API payloads, query parameters, environment variables, storage data, or user input based solely on TypeScript types.
• Use runtime validation for untrusted external data.
• Do not assume compile-time types provide runtime safety.
• Prefer schema validation when external contracts are complex.
• Never expose secrets, tokens, credentials, or sensitive data.
• Do not log sensitive information.
• Avoid unsafe dynamic property access.
• Avoid eval, Function, and dynamic code execution.
• Avoid unsafe HTML injection.
• Sanitize untrusted HTML when rendering HTML is required.
• Avoid weakening TLS, authentication, authorization, CSP, validation, or other security controls.
• Treat all external data as untrusted.
• Prefer secure defaults.
• Do not disable security checks for convenience.
• Avoid prototype pollution risks when merging untrusted objects.
• Prefer allowlists over denylists for security-sensitive validation.
• Keep dependencies minimal.
• Prefer built-in platform APIs over adding small utility dependencies.
• Do not add dependencies without a clear reason.
• Avoid abandoned or unnecessary packages.
• Keep dependencies current and supported.
• Respect lockfiles.
• Do not manually modify generated lockfile content.
• Avoid broad dependency upgrades unrelated to the task.
• Use ESM or the project's existing module system consistently.
• Avoid mixing module systems without necessity.
• Prefer named exports unless the project convention favors default exports.
• Keep import paths consistent.
• Remove unused imports and exports.
• Avoid circular dependencies.
• Keep frontend, domain, application, and infrastructure concerns separated where applicable.
• Keep API and transport models separate from domain logic when necessary.
• Do not leak implementation details through public APIs.
• Avoid unnecessary public exports.
• Keep module boundaries intentional.
• Write code that is easy to test.
• Prefer behavior-based tests.
• Avoid tests coupled to implementation details.
• Mock only external boundaries or expensive dependencies where practical.
• Keep tests deterministic.
• Avoid time-, network-, and environment-dependent tests without proper isolation.
• Remove dead code instead of keeping it as commented-out code.
• Do not add comments unless the user explicitly requests them.
• Use descriptive naming.
• Avoid vague names such as data, obj, item, temp, or value when more precise names are available.
• Avoid abbreviations unless they are established domain terminology.
• Keep naming conventions consistent.
• Treat lint and TypeScript errors seriously.
• Do not suppress ESLint or TypeScript diagnostics without a concrete reason.
• Avoid @ts-ignore.
• Prefer @ts-expect-error only when the error is intentional and documented.
• Do not disable lint rules globally for local problems.
• Prefer correctness, security, maintainability, and predictable behavior over micro-optimizations.

Performance Priority

Prioritize performance work in this order:

• Architecture
• Network and API usage
• Database access
• Algorithms and data structures
• Rendering and state updates
• Concurrency
• Memory allocations
• CPU micro-optimizations

Never optimize based purely on assumptions.

Safety Rule

• Compile-time type safety is not runtime validation.
• Validate all external and untrusted data.
• Do not use any, type assertions, non-null assertions, or disabled compiler checks to bypass real type problems.
• Prefer making invalid states unrepresentable where practical.