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.

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.

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.

TypeScript Development