Skip to content
Skills Library
Programming · Building & coding

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.

Licence
MIT
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

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

  1. Prerequisite Detection
  2. Type Safety in Backend Implementation
  3. Coding Conventions
  4. Error Handling
  5. Performance Optimization
Original SKILL.md headings · 121 lines, 791 words
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

RepositoryScoreLicence
This page · shinpr/ai-coding-project-boilerplate100MIT
shinpr/ai-coding-project-boilerplate96MIT
shinpr/ai-coding-project-boilerplate96MIT
shinpr/claude-code-workflows90MIT

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コンポーネント実装時に使用。

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.