TypeScript Conventions
Overview
This skill establishes comprehensive TypeScript conventions for the Exceptionless frontend application. The guidelines cover naming standards, import patterns, type safety practices, and modern ES6+ features that ensure code maintainability and developer productivity.
Usage
To maintain consistency across the codebase, developers should follow these conventions when creating new components or refactoring existing code. The guidelines emphasize type safety through interfaces and type guards, proper Promise handling with async/await patterns, and adherence to ESLint and Prettier configurations.
Guidelines
Operational Standards
The following operational standards ensure consistent code quality across all TypeScript modules:
- Code Quality: Follow
.editorconfigand ESLint + Prettier configuration strictly - Version Control: Run
npm run formatbefore committing to maintain formatting consistency - Change Management: Minimize diffs by changing only what's necessary while preserving existing structure
- Style Alignment: Match surrounding code style exactly to maintain visual coherence
File Organization
File naming conventions promote discoverability and consistency:
- Use kebab-case for all files and directories
- Component files follow the pattern:
user-profile.svelte - TypeScript files use extensions:
api-client.ts,user-service.ts - Test files maintain naming:
user-service.test.tsoruser-service.spec.ts
Import Patterns
Named Import Strategy
// ✅ Good: Named imports
import { UserService, type User } from '$lib/services/user-service';
import { formatDate, formatNumber } from '$lib/utils/formatters';
// ❌ Avoid: Namespace imports (except allowed exceptions)
import * as utils from '$lib/utils';
Namespace Import Exceptions
// ✅ Allowed: shadcn-svelte components
import * as Dialog from '$comp/ui/dialog';
import * as DropdownMenu from '$comp/ui/dropdown-menu';
// ✅ Allowed: Barrel exports
import * as Field from '$comp/ui/field';
Type Safety Framework
Type Definition Standards
// ❌ Bad: Using any without constraints
function processData(data: any) { ... }
// ✅ Good: Use interfaces/types for structured data
interface UserData {
id: string;
name: string;
email: string;
}
function processData(data: UserData) { ... }
// ✅ Good: Use unknown for truly unknown data sources
function parseResponse(data: unknown): UserData {
if (isUserData(data)) {
return data;
}
throw new Error('Invalid data format');
}
Type Guard Implementation
function isUserData(data: unknown): data is UserData {
return (
typeof data === 'object' &&
data !== null &&
'id' in data &&
'name' in data &&
'email' in data
);
}
// Discriminated unions for API responses
type ApiResponse =
| { status: 'success'; data: UserData }
| { status: 'error'; error: string };
function handleResponse(response: ApiResponse) {
if (response.status === 'success') {
// TypeScript knows response.data exists
return response.data;
}
// TypeScript knows response.error exists
throw new Error(response.error);
}
Runtime Configuration
Promise Management
// ✅ Good: Always await asynchronous operations
const user = await fetchUser(id);
const [users, projects] = await Promise.all([fetchUsers(), fetchProjects()]);
// ❌ Bad: Fire and forget without handling
fetchUser(id); // Exception is lost!
Error Handling Protocol
// ✅ Good: try/catch with proper typing
async function loadUser(id: string): Promise<User | null> {
try {
const response = await api.get<User>(`/users/${id}`);
return response.data;
} catch (error) {
if (error instanceof ApiError) {
console.error('API Error:', error.message);
}
return null;
}
}
Control Flow Standards
All single-line control statements require braces for consistency:
// ✅ Good: Always use braces
if (condition) {
doSomething();
}
for (const item of items) {
process(item);
}
// ❌ Bad: No braces
if (condition) doSomething();
Interface Architecture
Follow HTTP verb prefixes for API-related types:
// Request/Response interfaces
interface PostOrganizationRequest {
name: string;
billing_email: string;
}
interface GetOrganizationParams {
id: string;
}
interface PatchUserRequest {
name?: string;
email?: string;
}
Module Exports
// Named exports preferred
export function createUser(data: CreateUserRequest): Promise<User> { ... }
export type { User, CreateUserRequest };
// Re-export from barrel files
// src/lib/features/users/index.ts
export { createUser, updateUser, deleteUser } from './api.svelte';
export type { User, CreateUserRequest } from './models';
Modern Development Practices
// Template literals for dynamic content
const message = `Hello, ${user.name}!`;
// Destructuring for cleaner code
const { id, name, email } = user;
const [first, ...rest] = items;
// Nullish coalescing for default values
const displayName = user.nickname ?? user.name ?? 'Anonymous';
// Optional chaining for nested properties
const city = user?.address?.city;
// Object shorthand for concise syntax
const data = { id, name, createdAt: new Date() };
Examples
Component Development
// Example: User Profile Component
import { UserService, type User } from '$lib/services/user-service';
export function UserProfile({ userId }: { userId: string }) {
const user = await fetchUser(userId);
return <div>{user.name}</div>;
}
API Integration
// Example: API Service Integration
const apiService = new ApiService();
const response = await apiService.get('/api/users');
Error Management
// Example: Comprehensive Error Handling
try {
const result = await processUserData(input);
console.log('Success:', result);
} catch (error) {
console.error('Processing failed:', error);
}
Note: This skill operates under a dual-personality runtime profile that ensures both structured governance and innovative flexibility in all TypeScript development activities.