Instruction file imported from michaeldrotar/tabby (.github/instructions/typescript-5-es2022.instructions.md). Copyright stays with the author.

TypeScript Development

These instructions assume projects are built with TypeScript 5.x (or newer) compiling to an ES2022 JavaScript baseline. Adjust guidance if your runtime requires older language targets or down-level transpilation.

Core Intent

• Respect the existing architecture and coding standards.
• Prefer readable, explicit solutions over clever shortcuts.
• Extend current abstractions before inventing new ones.
• Prioritize maintainability and clarity, short methods and classes, clean code.

General Guardrails

• Target TypeScript 5.x / ES2022 and prefer native features over polyfills.
• Use pure ES modules; never emit require, module.exports, or CommonJS helpers.
• Rely on the project's build, lint, and test scripts unless asked otherwise.
• Note design trade-offs when intent is not obvious.

Project Organization

• Follow the repository's folder and responsibility layout for new code.
• Use kebab-case filenames (e.g., user-session.ts, data-service.ts) unless told otherwise.
• Keep tests, types, and helpers near their implementation when it aids discovery.
• Reuse or extend shared utilities before adding new ones.

Naming & Style

• Use PascalCase for classes, interfaces, enums, and type aliases; camelCase for everything else.
• Skip interface prefixes like I; rely on descriptive names.
• Name things for their behavior or domain meaning, not implementation.

Formatting & Style

• Run the repository's lint/format scripts (e.g., npm run lint) before submitting.
• Match the project's indentation, quote style, and trailing comma rules.
• Keep functions focused; extract helpers when logic branches grow.
• Favor immutable data and pure functions when practical.

Type System Expectations

• Avoid any (implicit or explicit); prefer unknown plus narrowing.
• Use discriminated unions for realtime events and state machines.
• Centralize shared contracts instead of duplicating shapes.
• Express intent with TypeScript utility types (e.g., Readonly, Partial, Record).

Async, Events & Error Handling

• Use async/await; wrap awaits in try/catch with structured errors.
• Guard edge cases early to avoid deep nesting.
• Send errors through the project's logging/telemetry utilities.
• Surface user-facing errors via the repository's notification pattern.
• Debounce configuration-driven updates and dispose resources deterministically.

Architecture & Patterns

• Follow the repository's dependency injection or composition pattern; keep modules single-purpose.
• Observe existing initialization and disposal sequences when wiring into lifecycles.
• Keep transport, domain, and presentation layers decoupled with clear interfaces.
• Supply lifecycle hooks (e.g., initialize, dispose) and targeted tests when adding services.

External Integrations

• Instantiate clients outside hot paths and inject them for testability.
• Never hardcode secrets; load them from secure sources.
• Apply retries, backoff, and cancellation to network or IO calls.
• Normalize external responses and map errors to domain shapes.

Security Practices

• Validate and sanitize external input with schema validators or type guards.
• Avoid dynamic code execution and untrusted template rendering.
• Encode untrusted content before rendering HTML; use framework escaping or trusted types.
• Use parameterized queries or prepared statements to block injection.
• Keep secrets in secure storage, rotate them regularly, and request least-privilege scopes.
• Favor immutable flows and defensive copies for sensitive data.
• Use vetted crypto libraries only.
• Patch dependencies promptly and monitor advisories.

Configuration & Secrets

• Reach configuration through shared helpers and validate with schemas or dedicated validators.
• Handle secrets via the project's secure storage; guard undefined and error states.
• Document new configuration keys and update related tests.

UI & UX Components

• Sanitize user or external content before rendering.
• Keep UI layers thin; push heavy logic to services or state managers.
• Use messaging or events to decouple UI from business logic.

Testing Expectations

• Add or update unit tests with the project's framework and naming style.
• Expand integration or end-to-end suites when behavior crosses modules or platform APIs.
• Run targeted test scripts for quick feedback before submitting.
• Avoid brittle timing assertions; prefer fake timers or injected clocks.

Performance & Reliability

• Lazy-load heavy dependencies and dispose them when done.
• Defer expensive work until users need it.
• Batch or debounce high-frequency events to reduce thrash.
• Track resource lifetimes to prevent leaks.

Documentation & Comments

• Add JSDoc to public APIs; include @remarks or @example when helpful.
• Write comments that capture intent, and remove stale notes during refactors.
• Update architecture or design docs when introducing significant patterns.