TypeScript Guardian

Quick Start

This skill enforces TypeScript strict mode and type safety:

Strict mode compliance: Verify all strict flags enabled
Any type elimination: Replace any with specific types, unknown, or generics
Return type annotations: Add explicit return types to all functions
Type narrowing: Implement type guards and predicates

When to Use

TypeScript compiler errors need resolution
any types detected in production code
Missing return type annotations
Strict mode violations (unchecked index access, null/undefined)

Strict Mode Configuration

Current tsconfig.json requirements (already enforced):

json

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "strictNullChecks": true,
    "noImplicitAny": true,
    "strictFunctionTypes": true
  }
}

Verification commands:

bash

# Check for TypeScript errors
npx tsc --noEmit

# Run type-aware linting
npm run lint:ci

Common Violations & Fixes

1. Implicit Any

typescript

// ❌ Implicit any
function process(data) {
  return data.value;
}

// ✅ Explicit types
function process(data: { value: string }): string {
  return data.value;
}

2. Unchecked Index Access

typescript

// ❌ No check for undefined
const users = ['Alice', 'Bob'];
const firstUser = users[0]; // string | undefined
console.log(firstUser.toUpperCase()); // Runtime error if empty

// ✅ Check for undefined
const firstUser = users[0];
if (firstUser !== undefined) {
  console.log(firstUser.toUpperCase());
}

// ✅ Or use optional chaining
console.log(users[0]?.toUpperCase());

3. Null/Undefined Not Checked

typescript

// ❌ Assuming value exists
interface User {
  profile?: { name: string };
}

function greet(user: User): string {
  return `Hello, ${user.profile.name}`; // Error: profile might be undefined
}

// ✅ Check for existence
function greet(user: User): string {
  if (user.profile === undefined) {
    return 'Hello, stranger';
  }
  return `Hello, ${user.profile.name}`;
}

// ✅ Or use optional chaining
function greet(user: User): string {
  return `Hello, ${user.profile?.name ?? 'stranger'}`;
}

Any Type Elimination

Detection Strategy

bash

# Find any types in source code
grep -r ": any" src/ --include="*.ts" --include="*.tsx" --exclude="*.test.ts"

# Find any[] array types
grep -r ": any\\[\\]" src/

# Find type assertions with any
grep -r "as any" src/

ESLint enforces these rules (already configured):

@typescript-eslint/no-explicit-any: error
@typescript-eslint/no-unsafe-assignment: error
@typescript-eslint/no-unsafe-call: error

Replacement Patterns

Replace Any with Unknown:

typescript

// ❌ any (no type safety)
function processData(data: any): void {
  console.log(data.value);
}

// ✅ unknown (requires type narrowing)
function processData(data: unknown): void {
  if (typeof data === 'object' && data !== null && 'value' in data) {
    console.log((data as { value: string }).value);
  }
}

// ✅ Best: specific type
interface Data {
  value: string;
}
function processData(data: Data): void {
  console.log(data.value);
}

Replace Any with Generic:

typescript

// ❌ any loses type information
function identity(value: any): any {
  return value;
}

// ✅ Generic preserves type
function identity<T>(value: T): T {
  return value;
}

Replace Any with Union Type:

typescript

// ❌ any accepts anything
function format(value: any): string {
  return String(value);
}

// ✅ Union type is specific
function format(value: string | number | boolean): string {
  return String(value);
}

Replace Any with Type Predicate:

typescript

// ❌ any in type guard
function isString(value: any): boolean {
  return typeof value === 'string';
}

// ✅ Type predicate with unknown
function isString(value: unknown): value is string {
  return typeof value === 'string';
}

Return Type Annotations

ALWAYS add explicit return types (enforced by ESLint):

typescript

// ❌ Missing return type
function getUser(id: string) {
  return db.query('SELECT * FROM users WHERE id = ?', [id]);
}

// ✅ Explicit return type
function getUser(id: string): Promise<User | null> {
  return db.query('SELECT * FROM users WHERE id = ?', [id]);
}

// ✅ Void for no return
function logError(error: Error): void {
  console.error('Error:', error.message);
}

// ✅ Never for functions that don't return
function throwError(message: string): never {
  throw new Error(message);
}

Type Narrowing Patterns

Type Guards

typescript

// User-defined type guard
function isUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'name' in value &&
    typeof (value as User).id === 'string' &&
    typeof (value as User).name === 'string'
  );
}

// Usage
function processData(data: unknown): void {
  if (isUser(data)) {
    console.log(data.name); // data is User here
  }
}

Discriminated Unions

typescript

// Result type with discriminated union
type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

function handleResult<T>(result: Result<T>): T {
  if (result.success) {
    return result.data; // TypeScript knows this is success branch
  } else {
    throw result.error; // TypeScript knows this is error branch
  }
}

Assertion Functions

typescript

// Assert function (throws if condition fails)
function assertDefined<T>(
  value: T | null | undefined,
  message = 'Value is null or undefined',
): asserts value is T {
  if (value === null || value === undefined) {
    throw new Error(message);
  }
}

// Usage
function process(user: User | null): void {
  assertDefined(user, 'User not found');
  console.log(user.name); // user is User here
}

Generic Constraints

typescript

// ❌ Unconstrained generic
function merge<T>(obj1: T, obj2: T): T {
  return { ...obj1, ...obj2 }; // Error: Spread requires object
}

// ✅ Constrained to objects
function merge<T extends object>(obj1: T, obj2: T): T {
  return { ...obj1, ...obj2 };
}

// ✅ More specific constraint
function merge<T extends Record<string, unknown>>(
  obj1: T,
  obj2: Partial<T>,
): T {
  return { ...obj1, ...obj2 };
}

Workflow

Phase 1: Analysis

Run tsc --noEmit to find errors
Scan for any types: grep -r ": any" src/
Identify missing return types
Prioritize by severity (compiler errors first)

Phase 2: Remediation

Replace any with unknown or specific types
Add explicit return type annotations
Fix null/undefined handling with guards
Add type narrowing where needed

Phase 3: Validation

Run tsc --noEmit (must pass)
Run npm run lint:ci (must pass)
Verify zero any types remain
Check all functions have return types

Common Issues

Array index flagged as potentially undefined

Solution: Check for undefined or use optional chaining

Object property access on potentially null/undefined

Solution: Use optional chaining and nullish coalescing: user?.profile?.name ?? 'Unknown'

Function parameters inferred as any

Solution: Add explicit type annotations: function process(data: { value: string })

Type assertion needed for external library

Solution: Create type definition file in types/ directory

Best Practices

Prefer Unknown Over Any:

typescript

// ✅ unknown requires type narrowing
function parse(json: string): unknown {
  return JSON.parse(json);
}

Use Type Assertions Sparingly:

typescript

// ⚠️ Type assertion (use only when certain)
const user = data as User;

// ✅ Type guard with runtime check
if (isUser(data)) {
  const user = data; // Type narrowed safely
}

Document Complex Types:

typescript

/**
 * Result type for async operations
 * @typeParam T - Success value type
 * @typeParam E - Error type (defaults to Error)
 */
type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

Success Criteria

Zero TypeScript compiler errors
Zero ESLint type errors
No any types in production code
All functions have explicit return types
Strict mode compliance: 100%

References

TypeScript Strict Mode: https://www.typescriptlang.org/tsconfig#strict
ESLint TypeScript Plugin: https://typescript-eslint.io/
TypeScript Handbook: https://www.typescriptlang.org/docs/handbook/intro.html

Search AI Tools

typescript-guardian

Install this agent skill to your Project

SKILL.md

TypeScript Guardian

Quick Start

When to Use

Strict Mode Configuration

Common Violations & Fixes

1. Implicit Any

2. Unchecked Index Access

3. Null/Undefined Not Checked

Any Type Elimination

Detection Strategy

Replacement Patterns

Return Type Annotations

Type Narrowing Patterns

Type Guards

Discriminated Unions

Assertion Functions

Generic Constraints

Workflow

Phase 1: Analysis

Phase 2: Remediation

Phase 3: Validation

Common Issues

Best Practices

Success Criteria

References