TypeScript Authoring Skill

Write strictly-typed TypeScript extending javascript-author patterns.

Core Principles

Configuration

Strict tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",

    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "exactOptionalPropertyTypes": true,

    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,

    "outDir": "dist",
    "rootDir": "src",

    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Key Strict Options

Type Patterns

Interface vs Type

// Use interface for object shapes (extendable)
interface User {
  id: string;
  name: string;
  email: string;
}

// Use type for unions, primitives, computed types
type UserId = string;
type Status = 'pending' | 'active' | 'inactive';
type UserWithStatus = User & { status: Status };

Discriminated Unions

// Pattern: Use 'type' or 'kind' discriminator
type Result<T> =
  | { success: true; data: T }
  | { success: false; error: Error };

type ApiResponse =
  | { type: 'loading' }
  | { type: 'success'; data: unknown }
  | { type: 'error'; message: string };

function handleResponse(response: ApiResponse): void {
  switch (response.type) {
    case 'loading':
      showSpinner();
      break;
    case 'success':
      render(response.data); // TypeScript knows data exists
      break;
    case 'error':
      showError(response.message); // TypeScript knows message exists
      break;
  }
}

Type Guards

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

// Assertion function
function assertUser(value: unknown): asserts value is User {
  if (!isUser(value)) {
    throw new TypeError('Expected User object');
  }
}

// Usage
function processInput(input: unknown): User {
  assertUser(input);
  return input; // Type narrowed to User
}

Generics

// Basic generic function
function first<T>(array: T[]): T | undefined {
  return array[0];
}

// Constrained generic
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

// Generic with default
function createStore<T = Record<string, unknown>>(
  initial: T
): { get(): T; set(value: T): void } {
  let state = initial;
  return {
    get: () => state,
    set: (value) => { state = value; }
  };
}

Web Component Types

Typed Custom Element

// types.ts
interface MyComponentProps {
  value: string;
  disabled?: boolean;
}

interface MyComponentEvents {
  'value-change': CustomEvent<{ oldValue: string; newValue: string }>;
  'submit': CustomEvent<void>;
}

// my-component.ts
class MyComponent extends HTMLElement {
  static observedAttributes = ['value', 'disabled'] as const;

  // Private state
  #value = '';

  // Typed getter/setter
  get value(): string {
    return this.#value;
  }

  set value(newValue: string) {
    const oldValue = this.#value;
    this.#value = newValue;
    this.dispatchEvent(
      new CustomEvent('value-change', {
        detail: { oldValue, newValue },
        bubbles: true
      })
    );
  }

  get disabled(): boolean {
    return this.hasAttribute('disabled');
  }

  set disabled(value: boolean) {
    this.toggleAttribute('disabled', value);
  }

  // Typed attribute callback
  attributeChangedCallback(
    name: typeof MyComponent.observedAttributes[number],
    oldValue: string | null,
    newValue: string | null
  ): void {
    if (oldValue === newValue) return;

    switch (name) {
      case 'value':
        this.#value = newValue ?? '';
        break;
      case 'disabled':
        // Handle disabled state
        break;
    }
  }

  // Typed event emission
  #emit<K extends keyof MyComponentEvents>(
    type: K,
    detail: MyComponentEvents[K]['detail']
  ): void {
    this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true }));
  }
}

customElements.define('my-component', MyComponent);

export { MyComponent };
export type { MyComponentProps, MyComponentEvents };

Augmenting HTMLElementTagNameMap

// global.d.ts
declare global {
  interface HTMLElementTagNameMap {
    'my-component': MyComponent;
    'user-card': UserCard;
  }
}

export {};

// Usage - now type-safe
const element = document.querySelector('my-component');
// element is MyComponent | null, not Element | null

API Types

Request/Response Types

// api-types.ts
interface ApiError {
  code: string;
  message: string;
  details?: Record<string, string[]>;
}

type ApiResult<T> =
  | { ok: true; data: T }
  | { ok: false; error: ApiError };

interface PaginatedResponse<T> {
  items: T[];
  total: number;
  page: number;
  pageSize: number;
  hasMore: boolean;
}

// Typed fetch wrapper
async function apiFetch<T>(
  url: string,
  options?: RequestInit
): Promise<ApiResult<T>> {
  try {
    const response = await fetch(url, options);

    if (!response.ok) {
      const error = await response.json() as ApiError;
      return { ok: false, error };
    }

    const data = await response.json() as T;
    return { ok: true, data };
  } catch (cause) {
    return {
      ok: false,
      error: {
        code: 'NETWORK_ERROR',
        message: cause instanceof Error ? cause.message : 'Unknown error'
      }
    };
  }
}

Zod for Runtime Validation

import { z } from 'zod';

// Define schema
const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1).max(100),
  email: z.string().email(),
  role: z.enum(['admin', 'user', 'guest']),
  createdAt: z.coerce.date()
});

// Infer type from schema
type User = z.infer<typeof UserSchema>;

// Parse with runtime validation
function parseUser(input: unknown): User {
  return UserSchema.parse(input);
}

// Safe parse (returns result object)
function safeParseUser(input: unknown): z.SafeParseReturnType<unknown, User> {
  return UserSchema.safeParse(input);
}

Utility Types

Common Built-in Types

// Partial - all properties optional
type PartialUser = Partial<User>;

// Required - all properties required
type RequiredUser = Required<User>;

// Pick - select properties
type UserName = Pick<User, 'id' | 'name'>;

// Omit - exclude properties
type UserWithoutEmail = Omit<User, 'email'>;

// Record - object type
type UserMap = Record<string, User>;

// ReturnType - function return type
type FetchResult = ReturnType<typeof fetch>;

// Parameters - function parameters
type FetchParams = Parameters<typeof fetch>;

// Awaited - unwrap Promise
type ResolvedData = Awaited<Promise<User>>;

Custom Utility Types

// Make specific properties optional
type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

// Make specific properties required
type RequiredBy<T, K extends keyof T> = T & Required<Pick<T, K>>;

// Deep partial
type DeepPartial<T> = T extends object
  ? { [P in keyof T]?: DeepPartial<T[P]> }
  : T;

// Non-nullable
type NonNullableProps<T> = {
  [P in keyof T]: NonNullable<T[P]>;
};

// Extract keys by value type
type KeysOfType<T, V> = {
  [K in keyof T]: T[K] extends V ? K : never;
}[keyof T];

File Organization

src/
├── types/
│   ├── index.ts          # Re-exports all types
│   ├── api.ts            # API request/response types
│   ├── domain.ts         # Business domain types
│   └── components.ts     # Component prop/event types
├── components/
│   └── my-component/
│       ├── my-component.ts
│       ├── my-component.types.ts  # Component-specific types
│       └── my-component.test.ts
├── utils/
│   ├── type-guards.ts    # isX and assertX functions
│   └── validators.ts     # Zod schemas
└── index.ts

Best Practices

Do

// Explicit return types on public functions
function calculateTotal(items: LineItem[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

// Use const assertions for literals
const STATUSES = ['pending', 'active', 'closed'] as const;
type Status = typeof STATUSES[number];

// Prefer unknown over any
function parseJSON(text: string): unknown {
  return JSON.parse(text);
}

// Use satisfies for type checking without widening
const config = {
  port: 3000,
  host: 'localhost'
} satisfies Record<string, string | number>;

Don't

// Don't use any
function bad(data: any) { } // Avoid

// Don't use non-null assertion without cause
const element = document.querySelector('#app')!; // Dangerous

// Don't use type assertions carelessly
const user = response as User; // Prefer type guards

// Don't ignore errors in catch
try {
  // ...
} catch (e) { } // Always handle or log

Checklist

When writing TypeScript:

• tsconfig.json has strict mode enabled
• All exports are named (no default exports)
• Public function boundaries have explicit types
• Unknown data is validated before use
• Type guards used instead of type assertions
• Discriminated unions for state management
• No any types (use unknown instead)

Related Skills

• javascript-author - Base patterns for functional core
• unit-testing - Testing typed code
• api-client - Typed API interactions
• custom-elements - Web Component patterns