TypeScript Patterns Skill

Best practices for types, interfaces, assertions, and type safety.

Type Inference Over Explicit Returns

// ✅ Inferred return type
function calculateTotal(items: OrderItem[]) {
    return items.reduce((sum, item) => sum + item.price, 0);
}

// ❌ Explicit return type
function calculateTotal(items: OrderItem[]): number {
    return items.reduce((sum, item) => sum + item.price, 0);
}

Why: Inference catches implicit type coercion bugs.

Runtime Type Assertions

Never hard cast from JSON.parse. Validate at runtime.

// ❌ Hard cast
const value: MyType = JSON.parse(message);

// ✅ Runtime assertion
function isMyType(value: unknown): value is MyType {
    return typeof value === 'object' &&
        value !== null &&
        typeof (<MyType>value).prop === 'string';
}

const value = JSON.parse(message);
assert(isMyType(value), 'Invalid message format');

Type Assertion Functions

// Parameter: 'value' with 'unknown' type
// Always return boolean, never throw
function isStrategy(value: unknown): value is Strategy {
    return typeof value === 'object' &&
        value !== null &&
        typeof (<Strategy>value).name === 'string';
}

// Use with assert
assert(isStrategy(value), 'Value is not a valid Strategy');

Interfaces vs Types

// Interface for module-scope object types
export interface Product {
    id: string;
    name: string;
    price: number;
}

// Type for local function-scoped types
function validate(input: unknown) {
    type Result = { errors: string[]; valid: boolean };
    const output: Result = { errors: [], valid: true };
    // ...
}

// Type for unions
type Status = 'pending' | 'active' | 'inactive';

Casting Syntax

// ✅ Angle bracket syntax
const x = <number>y;
const config = <ConfigType>JSON.parse(json);

// ❌ 'as' syntax
const x = y as number;

Interface Conventions

• No I prefix or Data suffix
• Properties in alphabetical order
• Think of interfaces as nouns or adjectives (Shippable, Refundable)
• When extending, inherit ALL properties (no Omit)

// Adjective interfaces
interface Shippable {
    shipping_address: string;
    shipping_cost: number;
}

// Concrete interface
interface Order extends Shippable {
    id: string;
    total: number;
}

Enums

Use explicit values. Prefer union types for small sets.

// ✅ Explicit string enum (4+ values)
export enum TenantModel {
    USER = 'user',
    ORGANIZATION = 'organization',
    EMPLOYER = 'employer'
}

// ✅ Union type (2-3 values)
type Status = 'active' | 'inactive';

// Validate with Object.values
if (!Object.values(AttributionModel).includes(model)) {
    throw new Error('Invalid model');
}

Iteration

// ✅ for...of loop
for (const item of items) {
    processItem(item);
}

// ❌ forEach
items.forEach((item) => {
    processItem(item);
});

Why: for...of works with break, continue, return, await, and has better debugging/stack traces.

Use map/filter/reduce for transformations, not side effects.

Import Style

// ✅ Namespace imports
import * as mongodb from 'mongodb';
import * as Types from './types/index.js';

// ❌ Default imports
import MongoDB from 'mongodb';

Organization

• Keep types with related code (not in types/ directories)
• Only export types that are part of public API
• Use ReturnType and Parameters to access private types