typescript-rules
/typescript-rules
Applies type safety and error handling rules. Enforces no-any policy and type guards. Use when implementing TypeScript or reviewing types.
- Author
- shinpr ↗
- Repository
- ai-coding-project-boilerplate ↗
- Licence
- MIT
- Last repository change
- 23.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Applies type safety and error handling rules. Enforces no-any policy and type guards. Use when implementing TypeScript or reviewing types.
Original author description
Applies type safety and error handling rules. Enforces no-any policy and type guards. Use when implementing TypeScript or reviewing types.
How it works
- Prerequisite Detection
- Type Safety in Backend Implementation
- Coding Conventions
- Error Handling
- Performance Optimization
SKILL.md preview
---
name: typescript-rules
description: Applies type safety and error handling rules. Enforces no-any policy and type guards. Use when implementing TypeScript or reviewing types.
---
# TypeScript Development Rules
## Prerequisite Detection
Inspect `tsconfig`, runtime/framework configuration, lint/format configuration, path aliases, package scripts, and representative modules before applying project conventions. Treat a rule as project-specific only when configuration or an established pattern supports it. Label limited-pattern conclusions as inferred. When competing conventions change a public contract, runtime behavior, or error boundary, stop and name the source or user decision required.
## Type Safety in Backend Implementation
**Type Safety in Data Flow**
Input Layer (`unknown`) -> Type Guard -> Business Layer (Type Guaranteed) -> Output Layer (Serialization)
**Backend-Specific Type Scenarios**:
- **API Communication**: Receive responses as `unknown` and validate them with type guards
- **Form Input**: External input as `unknown`, type determined after validation
- **Legacy Integration**: Receive the legacy boundary as `unknown`; isolate any evidence-backed assertion in the adapter that owns the boundary
- **Test Code**: Define mock input/output types with the configured test harness; use `Partial<T>` for intentionally partial fixtures and typed `vi.fn<[Args], Return>()` only when Vitest is configured
## Coding Conventions
**Class Usage Criteria**
- **Recommended: Implementation with Functions and Interfaces**
- Rationale: Improves testability and flexibility of function composition
- **Classes Allowed**:
- Framework requirements (NestJS Controller/Service, TypeORM Entity, etc.)
- Custom error class definitions
- When state and business logic are tightly coupled (e.g., ShoppingCart, Session, StateMachine)
- **Decision Criterion**: If "Does this data have behavior?" is Yes, consider using a class
```typescript
// Functions and interfaces
interface UserService { create(data: UserData): User }
const userService: UserService = { create: (data) => {...} }
```
**Function Design**
- **0-2 parameters maximum**: Use object for 3+ parameters
```typescript
// Object parameter
function createUser({ name, email, role }: CreateUserParams) {}
```
**Dependency Injection**
- **Inject external dependencies as parameters**: Ensure testability and modularity
```typescript
// Receive dependency as parameter
function createService(repository: Repository) { return {...} }
```
**Asynchronous Processing**
- Promise Handling: Follow the established repository style; use `async/await` when it makes sequencing and error propagation explicit
- Error Handling: Add `try-catch` when the current layer can convert, enrich, recover, or record the failure. Otherwise allow the promise rejection to propagate to the owning boundary
- Type Definition: Explicitly define return value types (e.g., `Promise<Result>`)
**Format Rules**
- Follow the repository's configured formatter, including its semicolon policy
- Types in `PascalCase`, variables/functions in `camelCase`
- Use absolute imports only through aliases declared in `tsconfig` or the configured build tool; otherwise use relative imports
**Clean Code Principles**
- Remove unused code within the current change
- Delete debug `console.log()`
- Keep executable source free of commented-out code; version control retains removed implementations
- Comments explain "why" (not "what")
## Error Handling
**Error Outcome Rule**: Every failure has one owning outcome: return a typed expected error, recover according to a named requirement, or propagate it with diagnostic context. Log at the observability-owning boundary so one failure is not logged repeatedly.
**Fail-Fast Principle**: Fail quickly on errors to prevent continued processing in invalid states
```typescript
// Invalid: fallback hides a failure required by the caller
catch (error) {
return defaultValue // Hides error
}
// Explicit propagation with added context
catch (error) {
throw new Error('Processing failed', { cause: error })
}
```
**Result Type Pattern**: Express errors with types for explicit handling
```typescript
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
// Example: Express error possibility with types
function parseUser(data: unknown): Result<User, ValidationError> {
if (!isValid(data)) return { ok: false, error: new ValidationError() }
return { ok: true, value: data as User }
}
```
**Custom Error Classes**
```typescript
export class AppError extends Error {
constructor(message: string, public readonly code: string, public readonly statusCode = 500) {
super(message)
this.name = this.constructor.name
}
}
// Purpose-specific: ValidationError(400), BusinessRuleError(400), DatabaseError(500), ExternalServiceError(502)
```
**Layer-Specific Error Handling (Backend)**
- API Layer: Convert to HTTP response, log output excluding sensitive information
- Service Layer: Detect business rule violations, propagate AppError as-is
- Repository Layer: Convert technical errors to domain errors
**Structured Logging and Sensitive Information Protection**
Log only fields approved for the current trust boundary. Redact credentials, tokens, secrets, payment data, and personal data before logging.
**Asynchronous Error Handling**
- Configure runtime-level `unhandledRejection`/`uncaughtException` handling at the application entry point when the runtime exposes those events; libraries leave process-level policy to their host
- Catch an asynchronous failure at the layer that can add a typed outcome, recovery, or diagnostic context
- Propagate failures after enrichment unless a named requirement owns recovery at that layer
## Performance Optimization
- Streaming Processing: Use streaming or bounded batches when measured input size can exceed the available-memory budget or when requirements demand incremental output; record the triggering measurement or constraint
- Resource Lifetime: Release timers, subscriptions, handles, and retained references at the lifecycle boundary that owns them
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · shinpr/ai-coding-project-boilerplate | 100 | MIT |
| shinpr/ai-coding-project-boilerplate | 96 | MIT |
| shinpr/ai-coding-project-boilerplate | 96 | MIT |
| shinpr/claude-code-workflows | 90 | MIT |
Database snapshot: 13.11.2026 · package version 2af762d60524 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100frontend-typescript-rules
Applies React/TypeScript type safety, component design, and state management rules. Use when implementing React components. - 90typescript-type-system
Use when working with TypeScript's type system including strict mode, advanced types, generics, type guards, and compiler configuration. - 100typescript-type-safety
Use when encountering TypeScript any types, type errors, or lax type checking - eliminates type holes and enforces strict type safety through proper interfaces, type guards, and module augmentation - 100typescript-pro
Implements advanced TypeScript type systems, creates custom type guards, utility types, and branded types, and configures tRPC for end-to-end type safety. Use when building TypeScript applications requiring advanced generics, conditional or mapped types, discriminated unions,… - 90typescript-pro
Use when building TypeScript applications requiring advanced type systems, generics, or full-stack type safety. Invoke for type guards, utility types, tRPC integration, monorepo setup. - 96frontend-typescript-rules
React/TypeScriptの型安全性、コンポーネント設計、状態管理ルールを適用。Reactコンポーネント実装時に使用。