TypeScript Development Guide

This skill provides mandatory specifications for writing TypeScript in this project to ensure consistency, type safety, and code cleanliness.

1. Naming Conventions

1.1 Variables and Functions

• Variables: Use snake_case (e.g., theme_value, is_dev).
• Functions: Use camelCase (e.g., getAntdTheme, setGlobalAnimation).
• Internal Props Objects: Use props_* prefix (e.g., props_side_bar).

1.2 Classes and Types

• Classes: Use PascalCase (e.g., GlobalModel, Settings).
• Interfaces/Types: Use PascalCase. Interfaces preferably start with I (e.g., IProps, IPropsSidebar).
• Enum-like Types: Use literal union types instead of enum where possible (e.g., type Theme = 'light' | 'dark' | 'system').

2. Type Definitions

2.1 File Organization

• Global Types: Place in packages/app/types/ or packages/app/typings/.
• Local Types: Use types.ts file in the component or module directory.
• Props: Define an IProps interface for each component, typically in the component file or adjacent types.ts.

2.2 Best Practices

• Explicit Types: Prefer providing explicit type annotations for function parameters and complex return value types.
• Utility Types: Leverage TypeScript's utility types (Pick, Omit, Partial, Exclude) to reuse existing definitions.
• Strict Types: Avoid any. If the type is truly unknown, use unknown and perform type casting (cast) when necessary.
• Type Alias vs. Interface: Use interface for object structures (especially props), use type for unions, intersections, or base types.

3. Code Style

3.1 Imports and Exports

• Named Exports: Utility functions and models prefer named exports.
• Default Exports: For the main component or main class in a file, use default export.
• Pure Type Imports: Use import type for importing types to maintain clear process boundaries and reduce bundle size.
• Path Aliases: Use @/ to reference the src directory (e.g., import { Settings } from '@/models').

3.2 Statements and Logic

• Arrow Functions: Component definitions and small utility functions prefer arrow functions.
• Destructuring: Use destructuring for props and objects to improve readability.
• Conditional Logic: Use optional chaining (?.) and nullish coalescing (??) for safer property access.

3.3 Code Spacing and Blank Lines

Use blank lines to separate code with different execution styles or visual appearances. If two adjacent lines of code look stylistically different, a blank line must be added between them.

When to Add Blank Lines:

• Between data fetching and return statements
• Between variable calculation and usage
• Between multiple consecutive operations (different independent steps)
• Before early returns
• Between different operation types (sync vs async, query vs mutation)
• Before and after state changes

Recommended:

async getSnapshot(weight_threshold = 0.2) {
	const nodes = await this.query(sql.sql_get_snapshot_nodes(weight_threshold))
	const edges = await this.query(sql.sql_get_snapshot_edges(weight_threshold))

	return { nodes, edges }
}

async tick(threshold_override?: number) {
	const threshold = threshold_override ?? 0.5

	await this.exec(sql.sql_tick(threshold))
}

Avoid:

async getSnapshot(weight_threshold = 0.2) {
	const nodes = await this.query(sql.sql_get_snapshot_nodes(weight_threshold))
	const edges = await this.query(sql.sql_get_snapshot_edges(weight_threshold))
	return { nodes, edges }
}

4. Summary Checklist

• Are variable names snake_case?
• Are function names camelCase?
• Are component props using IProps or IProps*?
• Are pure type imports using import type?
• Are local types placed in types.ts files?
• Has any been avoided in favor of strict types or unknown?
• Are blank lines used to separate different execution style code blocks?