Cursor rule

1---
2description: 'TypeScript strict mode standards and naming conventions'
3globs: ['**/*.ts', '**/*.tsx']
4alwaysApply: false
5---
6 
7# TypeScript Standards
8 
9## Configuration
10 
11### Standard Configuration (All Packages)
12```json
13{
14  "compilerOptions": {
15    "declaration": true,
16    "importHelpers": true,
17    "module": "commonjs",
18    "outDir": "lib",
19    "rootDir": "src",
20    "strict": false,           // Relaxed for compatibility
21    "target": "es2017",
22    "sourceMap": false,
23    "allowJs": true,           // Mixed JS/TS support
24    "skipLibCheck": true,
25    "esModuleInterop": true
26  },
27  "include": ["src/**/*"]
28}
29```
30 
31### Root Configuration
32```json
33// tsconfig.json - Baseline configuration
34{
35  "compilerOptions": {
36    "strict": false,
37    "module": "commonjs",
38    "target": "es2017",
39    "declaration": true,
40    "outDir": "lib",
41    "rootDir": "src"
42  }
43}
44```
45 
46## Naming Conventions (Actual Usage)
47 
48### Files
49- **Primary pattern**: `kebab-case.ts` (e.g., `base-command.ts`, `config-handler.ts`)
50- **Single-word modules**: `index.ts`, `types.ts`
51- **Commands**: Follow OCLIF topic structure (`cm/auth/login.ts`, `cm/config/region.ts`)
52 
53### Classes
54```typescript
55// ✅ GOOD - PascalCase for classes
56export default class ConfigCommand extends Command { }
57export class AuthService { }
58export class ValidationError extends Error { }
59```
60 
61### Functions and Methods
62```typescript
63// ✅ GOOD - camelCase for functions
64export async function loadConfig(): Promise<Config> { }
65async validateInput(input: string): Promise<boolean> { }
66createCommandContext(): CommandContext { }
67```
68 
69### Constants
70```typescript
71// ✅ GOOD - SCREAMING_SNAKE_CASE for constants
72const DEFAULT_REGION = 'us';
73const MAX_RETRIES = 3;
74const API_BASE_URL = 'https://api.contentstack.io';
75```
76 
77### Interfaces and Types
78```typescript
79// ✅ GOOD - PascalCase for types
80export interface CommandConfig {
81  region: string;
82  alias?: string;
83}
84 
85export type CommandResult = {
86  success: boolean;
87  message?: string;
88};
89```
90 
91## Import/Export Patterns
92 
93### ES Modules (Preferred)
94```typescript
95// ✅ GOOD - ES import/export syntax
96import { Command } from '@oclif/core';
97import type { CommandConfig } from '../types';
98import { loadConfig } from '../utils';
99 
100export default class ConfigCommand extends Command { }
101export { CommandConfig };
102```
103 
104### Default Exports
105```typescript
106// ✅ GOOD - Default export for commands and main classes
107export default class ConfigCommand extends Command { }
108```
109 
110### Named Exports
111```typescript
112// ✅ GOOD - Named exports for utilities and types
113export async function delay(ms: number): Promise<void> { }
114export interface CommandOptions { }
115export type ActionResult = 'success' | 'failure';
116```
117 
118## Type Definitions
119 
120### Local Types
121```typescript
122// ✅ GOOD - Define types close to usage
123export interface AuthOptions {
124  email: string;
125  password: string;
126  token?: string;
127}
128 
129export type ConfigResult = {
130  success: boolean;
131  config?: Record<string, unknown>;
132};
133```
134 
135### Type Organization
136```typescript
137// ✅ GOOD - Organize types in dedicated files
138// src/types/index.ts
139export interface CommandConfig { }
140export interface AuthConfig { }
141export type ConfigValue = string | number | boolean;
142```
143 
144## Null Safety
145 
146### Function Return Types
147```typescript
148// ✅ GOOD - Explicit return types
149export async function getConfig(): Promise<CommandConfig> {
150  return await this.loadFromFile();
151}
152 
153export function createDefaults(): CommandConfig {
154  return {
155    region: 'us',
156    timeout: 30000,
157  };
158}
159```
160 
161### Null/Undefined Handling
162```typescript
163// ✅ GOOD - Handle null/undefined explicitly
164function processConfig(config: CommandConfig | null): void {
165  if (!config) {
166    throw new Error('Configuration is required');
167  }
168  // Process config safely
169}
170```
171 
172## Error Handling Types
173 
174### Custom Error Classes
175```typescript
176// ✅ GOOD - Typed error classes
177export class ValidationError extends Error {
178  constructor(
179    message: string,
180    public readonly code?: string
181  ) {
182    super(message);
183    this.name = 'ValidationError';
184  }
185}
186```
187 
188### Error Union Types
189```typescript
190// ✅ GOOD - Model expected errors
191type AuthResult<T> = {
192  success: true;
193  data: T;
194} | {
195  success: false;
196  error: string;
197};
198```
199 
200## Strict Mode Adoption
201 
202### Current Status
203- Most packages use `strict: false` for compatibility
204- Gradual migration path available
205- Team working toward stricter TypeScript
206 
207### Gradual Adoption
208```typescript
209// ✅ ACCEPTABLE - Comments for known issues
210// TODO: Fix type issues in legacy code
211const legacyData = unknownData as unknown;
212```
213 
214## Package-Specific Patterns
215 
216### Command Packages (auth, config)
217- Extend `@oclif/core` Command
218- Define command flags with `static flags`
219- Use @oclif/core flag utilities
220- Define command-specific types
221 
222### Library Packages (command, utilities)
223- No OCLIF dependencies
224- Pure TypeScript interfaces
225- Consumed by command packages
226- Focus on type safety for exports
227 
228### Main Package (contentstack)
229- Aggregates command plugins
230- May have common types
231- Shared interfaces for plugin integration
232 
233## Export Patterns
234 
235### Package Exports (lib/index.js)
236```typescript
237// ✅ GOOD - Barrel exports for libraries
238export { Command } from './command';
239export { loadConfig } from './config';
240export type { CommandConfig, AuthOptions } from './types';
241```
242 
243### Entry Points
244- Libraries export from `lib/index.js`
245- Commands export directly as default classes
246- Type definitions included via `types` field in package.json
247