TypeScript Cheat Sheet

// RECOMMENDED: Strong typing with validation - ALWAYS use in production
interface User {
  readonly id: number;
  name: string;
  email: string;
  role: "admin" | "user" | "guest";
  createdAt: Date;
}

// RECOMMENDED: Type guards for runtime validation
function isValidUser(obj: unknown): obj is User {
  return typeof obj === "object" && 
         obj !== null &&
         typeof (obj as User).id === "number" &&
         typeof (obj as User).name === "string" &&
         typeof (obj as User).email === "string" &&
         ["admin", "user", "guest"].includes((obj as User).role);
}

// SECURITY: SECURITY: Always validate external data
function processUserData(userData: unknown): User | null {
  if (!isValidUser(userData)) {
    console.error("Invalid user data received");
    return null;
  }
  
  // Additional validation
  if (!userData.email.includes("@") || userData.email.length < 5) {
    console.error("Invalid email format");
    return null;
  }
  
  return userData;
}

// RECOMMENDED: Branded types for additional safety
type UserId = number & { readonly brand: unique symbol };
type Email = string & { readonly brand: unique symbol };

function createUserId(id: number): UserId | null {
  return id > 0 ? id as UserId : null;
}

function createEmail(email: string): Email | null {
  return email.includes("@") && email.length >= 5 ? email as Email : null;
}

// TIP: WHEN TO USE: Type guards are essential for API data, user input, and any external sources
// TIP: WHY: Prevents runtime errors and security vulnerabilities
// TIP: COMMON MISTAKE: Trusting external data without validation
// TIP: PRODUCTION TIPS: Always log validation failures for monitoring

// SECURITY: SECURITY: Input sanitization functions
function sanitizeHtmlInput(input: string): string {
  return input
    .replace(/&/g, "&")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&#x27;")
    .replace(///g, "&#x2F;");
}

function sanitizeUsername(username: string): string | null {
  // Only allow alphanumeric and underscore
  const cleaned = username.trim().toLowerCase();
  const isValid = /^[a-zA-Z0-9_]{3,20}$/.test(cleaned);
  return isValid ? cleaned : null;
}

// RECOMMENDED: Safe string operations with validation
class SafeString {
  private constructor(private readonly value: string) {}
  
  static create(input: string): SafeString | null {
    if (typeof input !== "string" || input.length === 0) {
      return null;
    }
    return new SafeString(sanitizeHtmlInput(input));
  }
  
  toString(): string {
    return this.value;
  }
  
  concat(other: SafeString): SafeString {
    return new SafeString(this.value + other.value);
  }
}

// RECOMMENDED: Template literal type safety
type AllowedDomains = "example.com" | "test.com" | "myapp.com";
type EmailAddress<T extends AllowedDomains> = `${string}@${T}`;

function sendEmail<T extends AllowedDomains>(
  to: EmailAddress<T>, 
  subject: string, 
  body: string
): boolean {
  // Email sending logic with domain validation
  const [, domain] = to.split("@");
  const allowedDomains: AllowedDomains[] = ["example.com", "test.com", "myapp.com"];
  
  if (!allowedDomains.includes(domain as AllowedDomains)) {
    console.error(`Unauthorized domain: ${domain}`);
    return false;
  }
  
  // Safe to send email
  console.log(`Sending email to ${to}`);
  return true;
}

// SECURITY: Path traversal prevention
function validateFilePath(userPath: string): string | null {
  // Prevent directory traversal
  if (userPath.includes("..") || userPath.includes("~") || userPath.startsWith("/")) {
    console.warn(`Potential path traversal attempt: ${userPath}`);
    return null;
  }
  
  // Only allow alphanumeric, dash, underscore, and dot
  const sanitized = userPath.replace(/[^a-zA-Z0-9._-]/g, "");
  return sanitized.length > 0 ? sanitized : null;
}

// TIP: SECURITY BEST PRACTICES:
// - Always sanitize user input before processing or storing
// - Use branded types for sensitive data that needs validation
// - Validate domains and file paths to prevent traversal attacks
// - Never trust external data without proper validation
// - Log all security violations for monitoring and incident response

// PERFORMANCE: Type-safe numeric operations
type SafeInteger = number & { readonly __brand: "SafeInteger" };
type PositiveNumber = number & { readonly __brand: "PositiveNumber" };
type Percentage = number & { readonly __brand: "Percentage" };

function createSafeInteger(value: number): SafeInteger | null {
  if (!Number.isInteger(value) || !Number.isSafeInteger(value)) {
    return null;
  }
  return value as SafeInteger;
}

function createPositiveNumber(value: number): PositiveNumber | null {
  if (typeof value !== "number" || value <= 0 || !Number.isFinite(value)) {
    return null;
  }
  return value as PositiveNumber;
}

function createPercentage(value: number): Percentage | null {
  if (typeof value !== "number" || value < 0 || value > 100) {
    return null;
  }
  return value as Percentage;
}

// RECOMMENDED: Safe arithmetic operations
class SafeMath {
  static divide(a: number, b: number): number | null {
    if (b === 0 || !Number.isFinite(a) || !Number.isFinite(b)) {
      return null;
    }
    const result = a / b;
    return Number.isFinite(result) ? result : null;
  }
  
  static add(a: number, b: number): number | null {
    const result = a + b;
    if (!Number.isFinite(result)) {
      console.error("Addition resulted in non-finite number");
      return null;
    }
    return result;
  }
  
  static multiply(a: number, b: number): number | null {
    const result = a * b;
    if (!Number.isFinite(result)) {
      console.error("Multiplication resulted in non-finite number");
      return null;
    }
    return result;
  }
}

// SECURITY: Financial calculations with precision
class Money {
  private readonly cents: SafeInteger;
  
  constructor(dollars: number) {
    const cents = Math.round(dollars * 100);
    const safeCents = createSafeInteger(cents);
    if (!safeCents) {
      throw new Error(`Invalid monetary amount: ${dollars}`);
    }
    this.cents = safeCents;
  }
  
  add(other: Money): Money {
    const newCents = createSafeInteger(this.cents + other.cents);
    if (!newCents) {
      throw new Error("Monetary addition overflow");
    }
    return new Money(newCents / 100);
  }
  
  multiply(factor: PositiveNumber): Money {
    const result = SafeMath.multiply(this.cents, factor);
    if (!result) {
      throw new Error("Monetary multiplication error");
    }
    return new Money(result / 100);
  }
  
  toDollars(): number {
    return this.cents / 100;
  }
}

// RECOMMENDED: Range validation
function validateRange(value: number, min: number, max: number): boolean {
  return typeof value === "number" && 
         Number.isFinite(value) && 
         value >= min && 
         value <= max;
}

// TIP: WHEN TO USE:
// - Branded types: Financial calculations, IDs, measurements, sensitive data
// - SafeMath: Any user-input arithmetic operations to prevent overflow
// - Range validation: Age, scores, percentages, quantities, user inputs
// - Money class: All financial calculations to prevent precision errors

// PERFORMANCE: PERFORMANCE: Choose the right data structure

// RECOMMENDED: Arrays: Use for ordered data and frequent access by index
const users: readonly User[] = [
  { id: 1, name: "Alice", email: "alice@example.com", role: "admin", createdAt: new Date() },
  { id: 2, name: "Bob", email: "bob@example.com", role: "user", createdAt: new Date() }
];

// O(1) access by index
const firstUser = users[0];

// RECOMMENDED: Sets: Use for membership testing and unique values
const validRoles = new Set<User["role"]>(["admin", "user", "guest"]);

function isValidRole(role: string): role is User["role"] {
  return validRoles.has(role as User["role"]); // O(1) lookup vs O(n) for arrays
}

// RECOMMENDED: Maps: Use for key-value associations with object keys
const userCache = new Map<number, User>();

function getUserById(id: number): User | null {
  return userCache.get(id) || null; // O(1) lookup
}

function cacheUser(user: User): void {
  userCache.set(user.id, user); // O(1) insertion
}

// PERFORMANCE: MEMORY: ReadonlyArray for immutable collections
type ImmutableUsers = readonly User[];

function processUsers(users: ImmutableUsers): ImmutableUsers {
  // Functional approach - creates new array, doesn't mutate
  return users.filter(user => user.role !== "guest")
              .sort((a, b) => a.name.localeCompare(b.name));
}

// RECOMMENDED: Typed collections with constraints
class TypedSet<T> {
  private readonly items = new Set<T>();
  
  constructor(
    private readonly validator: (item: T) => boolean,
    private readonly maxSize: number = 1000
  ) {}
  
  add(item: T): boolean {
    if (!this.validator(item)) {
      console.warn("Invalid item rejected");
      return false;
    }
    
    if (this.items.size >= this.maxSize) {
      console.warn("Set size limit reached");
      return false;
    }
    
    this.items.add(item);
    return true;
  }
  
  has(item: T): boolean {
    return this.items.has(item);
  }
  
  size(): number {
    return this.items.size;
  }
  
  toArray(): T[] {
    return Array.from(this.items);
  }
}

// Usage with validation
const emailSet = new TypedSet<string>(
  (email) => email.includes("@") && email.length >= 5,
  100
);

// TIP: PERFORMANCE COMPARISON:
// Array.includes(): O(n) - linear search, slow for large datasets
// Set.has(): O(1) - hash lookup, fast even for large datasets  
// Map.get(): O(1) - hash lookup, efficient key-value operations
// Object property access: O(1) - but limited to string/symbol keys

// TIP: WHEN TO USE:
// - Array: Need indexing, ordered data, frequent iteration, small datasets
// - Set: Membership testing, removing duplicates, unique collections, fast lookups
// - Map: Key-value pairs with non-string keys, frequent lookups, complex keys
// - WeakMap/WeakSet: When you need garbage collection of keys for memory management

// SECURITY: Safe object operations with type guards
interface ApiResponse<T = unknown> {
  data?: T;
  error?: string;
  status: number;
}

function isSuccessResponse<T>(response: ApiResponse): response is ApiResponse<T> & { data: T } {
  return response.status >= 200 && response.status < 300 && response.data !== undefined;
}

function isErrorResponse(response: ApiResponse): response is ApiResponse & { error: string } {
  return response.status >= 400 && response.error !== undefined;
}

// RECOMMENDED: Safe property access with default values
function getProperty<T, K extends keyof T>(obj: T, key: K, defaultValue: T[K]): T[K] {
  const value = obj[key];
  return value !== undefined ? value : defaultValue;
}

// RECOMMENDED: Safe object updates - immutable approach
function updateUser<K extends keyof User>(
  user: User, 
  updates: Pick<User, K>
): User {
  // Validate updates before applying
  const validatedUpdates: Partial<User> = {};
  
  for (const [key, value] of Object.entries(updates)) {
    if (key === "email" && typeof value === "string") {
      if (value.includes("@")) {
        validatedUpdates.email = value;
      }
    } else if (key === "name" && typeof value === "string") {
      if (value.trim().length > 0) {
        validatedUpdates.name = value.trim();
      }
    } else if (key === "role" && typeof value === "string") {
      if (validRoles.has(value as User["role"])) {
        validatedUpdates.role = value as User["role"];
      }
    }
  }
  
  return { ...user, ...validatedUpdates };
}

// RECOMMENDED: Type-safe object transformation
function transformObject<T, U>(
  obj: T,
  transformer: (value: T[keyof T], key: keyof T) => U
): Record<keyof T, U> {
  const result = {} as Record<keyof T, U>;
  
  for (const key in obj) {
    if (Object.prototype.hasOwnProperty.call(obj, key)) {
      result[key] = transformer(obj[key], key);
    }
  }
  
  return result;
}

// RECOMMENDED: Deep readonly types for immutable objects
type DeepReadonly<T> = {
  readonly [P in keyof T]: T[P] extends object 
    ? T[P] extends Function 
      ? T[P] 
      : DeepReadonly<T[P]>
    : T[P];
};

// RECOMMENDED: Safe object merging
function mergeObjects<T extends Record<string, unknown>, U extends Record<string, unknown>>(
  target: T,
  source: U
): T & U {
  // Validate that source doesn't override critical target properties
  const protectedKeys = new Set(["id", "createdAt"]);
  
  for (const key of Object.keys(source)) {
    if (protectedKeys.has(key)) {
      console.warn(`Attempted to override protected property: ${key}`);
      delete (source as any)[key];
    }
  }
  
  return { ...target, ...source };
}

// SECURITY: SECURITY: Prevent prototype pollution
function safeAssign<T extends Record<string, unknown>>(
  target: T,
  source: Record<string, unknown>
): T {
  const result = { ...target };
  
  for (const [key, value] of Object.entries(source)) {
    // Skip dangerous keys
    if (key === "__proto__" || key === "constructor" || key === "prototype") {
      console.warn(`Dangerous key ignored: ${key}`);
      continue;
    }
    
    (result as any)[key] = value;
  }
  
  return result;
}

// TIP: BEST PRACTICES:
// - Always validate object properties from external sources
// - Use readonly types for immutable data structures and shared state
// - Prefer immutable updates over mutations for predictable state changes
// - Protect against prototype pollution attacks in user-facing applications
// - Use type guards for runtime safety when dealing with unknown objects

// RECOMMENDED: Strategic type guards - validate at system boundaries
type APIResponse<T> = 
  | { success: true; data: T }
  | { success: false; error: string; code: number };

function isSuccessResponse<T>(response: APIResponse<T>): response is { success: true; data: T } {
  return response.success === true;
}

function isErrorResponse<T>(response: APIResponse<T>): response is { success: false; error: string; code: number } {
  return response.success === false;
}

// RECOMMENDED: Process API responses safely
async function fetchUserSafely(id: number): Promise<User | null> {
  // Guard clause - validate input early
  if (!Number.isInteger(id) || id <= 0) {
    console.error(`Invalid user ID: ${id}`);
    return null;
  }

  try {
    const response: APIResponse<User> = await fetch(`/api/users/${id}`).then(r => r.json());
    
    // Type narrowing with discriminated unions
    if (isSuccessResponse(response)) {
      // TypeScript knows response.data is User
      if (!isValidUser(response.data)) {
        console.error("Invalid user data from API");
        return null;
      }
      return response.data;
    }
    
    if (isErrorResponse(response)) {
      // TypeScript knows response.error and response.code exist
      console.error(`API Error ${response.code}: ${response.error}`);
      return null;
    }
    
    console.error("Unexpected API response format");
    return null;
    
  } catch (error) {
    console.error("Network error:", error);
    return null;
  }
}

// RECOMMENDED: Exhaustive type checking with never
type Theme = "light" | "dark" | "auto";

function applyTheme(theme: Theme): void {
  switch (theme) {
    case "light":
      document.body.className = "light-theme";
      break;
    case "dark":
      document.body.className = "dark-theme";
      break;
    case "auto":
      const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
      document.body.className = prefersDark ? "dark-theme" : "light-theme";
      break;
    default:
      // This ensures all cases are handled
      const exhaustive: never = theme;
      throw new Error(`Unhandled theme: ${exhaustive}`);
  }
}

// RECOMMENDED: Optional chaining and nullish coalescing for safety
interface NestedData {
  user?: {
    profile?: {
      settings?: {
        theme: Theme;
        notifications: boolean;
      };
    };
  };
}

function getThemePreference(data: NestedData): Theme {
  // Safe navigation with fallback
  return data.user?.profile?.settings?.theme ?? "auto";
}

function isNotificationsEnabled(data: NestedData): boolean {
  return data.user?.profile?.settings?.notifications ?? true;
}

// TIP: DEFENSIVE PROGRAMMING:
// - Validate inputs at function boundaries to catch errors early
// - Use discriminated unions for complex state management
// - Handle all possible cases with never type for exhaustive checking
// - Use optional chaining for nested properties to prevent runtime errors
// - Always provide sensible defaults to ensure graceful degradation

// RECOMMENDED: Type-safe async operations with proper error handling
type AsyncResult<T, E = Error> = Promise<
  | { success: true; data: T }
  | { success: false; error: E }
>;

async function safeAsyncOperation<T>(
  operation: () => Promise<T>
): AsyncResult<T> {
  try {
    const data = await operation();
    return { success: true, data };
  } catch (error) {
    const errorObj = error instanceof Error ? error : new Error(String(error));
    return { success: false, error: errorObj };
  }
}

// RECOMMENDED: Async operation with timeout
function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
  const timeoutPromise = new Promise<never>((_, reject) => {
    setTimeout(() => reject(new Error(`Operation timed out after ${timeoutMs}ms`)), timeoutMs);
  });
  
  return Promise.race([promise, timeoutPromise]);
}

// RECOMMENDED: Parallel operations with error aggregation
async function fetchMultipleUsers(ids: number[]): Promise<{
  users: User[];
  errors: Array<{ id: number; error: string }>;
}> {
  const results = await Promise.allSettled(
    ids.map(async (id) => {
      const result = await safeAsyncOperation(() => fetchUserSafely(id));
      return { id, result };
    })
  );
  
  const users: User[] = [];
  const errors: Array<{ id: number; error: string }> = [];
  
  results.forEach((result) => {
    if (result.status === "fulfilled") {
      const { id, result: userResult } = result.value;
      if (userResult && userResult.success) {
        users.push(userResult.data);
      } else if (userResult && !userResult.success) {
        errors.push({ id, error: userResult.error.message });
      }
    } else {
      errors.push({ id: -1, error: result.reason });
    }
  });
  
  return { users, errors };
}

// RECOMMENDED: Async iterators for streaming data
async function* fetchUsersStream(): AsyncIterableIterator<User> {
  let page = 1;
  const pageSize = 10;
  
  while (true) {
    const result = await safeAsyncOperation(() => 
      fetch(`/api/users?page=${page}&size=${pageSize}`).then(r => r.json())
    );
    
    if (!result.success) {
      console.error("Failed to fetch users:", result.error);
      break;
    }
    
    const users = result.data;
    if (users.length === 0) break;
    
    for (const user of users) {
      if (isValidUser(user)) {
        yield user;
      }
    }
    
    page++;
  }
}

// RECOMMENDED: Cancellable async operations
class CancellableOperation<T> {
  private controller = new AbortController();
  private promise: Promise<T>;
  
  constructor(
    operation: (signal: AbortSignal) => Promise<T>
  ) {
    this.promise = operation(this.controller.signal);
  }
  
  cancel(): void {
    this.controller.abort();
  }
  
  async execute(): Promise<T> {
    try {
      return await this.promise;
    } catch (error) {
      if (error instanceof Error && error.name === "AbortError") {
        throw new Error("Operation was cancelled");
      }
      throw error;
    }
  }
}

// Usage
const operation = new CancellableOperation(async (signal) => {
  const response = await fetch("/api/data", { signal });
  return response.json();
});

// Cancel if needed
setTimeout(() => operation.cancel(), 5000);

// TIP: ASYNC BEST PRACTICES:
// - Always handle both success and error cases explicitly
// - Use timeouts for external operations to prevent hanging
// - Aggregate errors in parallel operations for better debugging
// - Use async iterators for streaming data to manage memory efficiently
// - Implement cancellation for long-running operations to improve UX

// RECOMMENDED: Pure function - predictable, testable, no side effects
function calculateTax(amount: number, rate: number): number | null {
  // Input validation
  if (typeof amount !== "number" || typeof rate !== "number") {
    return null;
  }
  
  if (amount < 0 || rate < 0 || rate > 1) {
    return null;
  }
  
  if (!Number.isFinite(amount) || !Number.isFinite(rate)) {
    return null;
  }
  
  return Math.round(amount * rate * 100) / 100; // Round to 2 decimal places
}

// RECOMMENDED: Function composition for complex operations
type Validator<T> = (value: T) => boolean;
type Transformer<T, U> = (value: T) => U;

function compose<T, U, V>(
  validator: Validator<T>,
  transformer: Transformer<T, U>,
  finalValidator: Validator<U>
) {
  return function(input: T): U | null {
    if (!validator(input)) {
      return null;
    }
    
    const transformed = transformer(input);
    
    if (!finalValidator(transformed)) {
      return null;
    }
    
    return transformed;
  };
}

// RECOMMENDED: Higher-order function for retry logic
function withRetry<T extends unknown[], R>(
  fn: (...args: T) => Promise<R>,
  maxRetries: number = 3,
  delayMs: number = 1000
) {
  return async function(...args: T): Promise<R> {
    let lastError: Error | null = null;
    
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        return await fn(...args);
      } catch (error) {
        lastError = error instanceof Error ? error : new Error(String(error));
        
        if (attempt === maxRetries) {
          throw lastError;
        }
        
        // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delayMs * attempt));
      }
    }
    
    throw lastError;
  };
}

// RECOMMENDED: Function overloading for flexible APIs
function processData(input: string): string;
function processData(input: number): number;
function processData(input: User): User;
function processData(input: string | number | User): string | number | User {
  if (typeof input === "string") {
    return input.trim().toLowerCase();
  }
  
  if (typeof input === "number") {
    return Math.max(0, input);
  }
  
  // User object - return validated copy
  if (isValidUser(input)) {
    return { ...input, name: input.name.trim() };
  }
  
  throw new Error("Invalid input type");
}

// RECOMMENDED: Currying for configuration
function createValidator<T>(
  validationRules: Array<(value: T) => boolean>,
  errorMessages: string[]
) {
  return function(value: T): { isValid: boolean; errors: string[] } {
    const errors: string[] = [];
    
    validationRules.forEach((rule, index) => {
      if (!rule(value)) {
        errors.push(errorMessages[index]);
      }
    });
    
    return {
      isValid: errors.length === 0,
      errors
    };
  };
}

// Usage
const userValidator = createValidator<User>(
  [
    (user) => user.name.length >= 2,
    (user) => user.email.includes("@"),
    (user) => ["admin", "user", "guest"].includes(user.role)
  ],
  [
    "Name must be at least 2 characters",
    "Email must contain @",
    "Role must be valid"
  ]
);

// TIP: WHEN TO USE:
// - Pure functions: Calculations, transformations, business logic that doesn't depend on external state
// - Function composition: Complex data processing pipelines that need to be maintainable
// - Higher-order functions: Cross-cutting concerns like retry, caching, logging, validation
// - Currying: Configuration, specialized validators, and creating reusable function factories

// RECOMMENDED: Result type for better error handling
type Result<T, E = Error> = 
  | { success: true; data: T }
  | { success: false; error: E };

function createResult<T>(data: T): Result<T, never> {
  return { success: true, data };
}

function createError<E>(error: E): Result<never, E> {
  return { success: false, error };
}

// RECOMMENDED: Safe operation wrapper
async function safeOperation<T>(
  operation: () => Promise<T>,
  context?: string
): Promise<Result<T, string>> {
  try {
    const data = await operation();
    return createResult(data);
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    const contextMessage = context ? `${context}: ${message}` : message;
    
    console.error("Operation failed:", {
      context,
      error: message,
      timestamp: new Date().toISOString()
    });
    
    return createError(contextMessage);
  }
}

// RECOMMENDED: Custom error classes for specific domains
class ValidationError extends Error {
  constructor(
    message: string,
    public readonly field: string,
    public readonly value: unknown
  ) {
    super(message);
    this.name = "ValidationError";
  }
}

class NetworkError extends Error {
  constructor(
    message: string,
    public readonly status: number,
    public readonly url: string
  ) {
    super(message);
    this.name = "NetworkError";
  }
}

class BusinessError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly details?: Record<string, unknown>
  ) {
    super(message);
    this.name = "BusinessError";
  }
}

// RECOMMENDED: Error boundary function for async operations
async function withErrorBoundary<T>(
  operation: () => Promise<T>,
  errorHandler: (error: Error) => T | null = () => null
): Promise<T | null> {
  try {
    return await operation();
  } catch (error) {
    if (error instanceof ValidationError) {
      console.error("Validation failed:", {
        field: error.field,
        value: error.value,
        message: error.message
      });
    } else if (error instanceof NetworkError) {
      console.error("Network error:", {
        status: error.status,
        url: error.url,
        message: error.message
      });
    } else if (error instanceof BusinessError) {
      console.error("Business logic error:", {
        code: error.code,
        details: error.details,
        message: error.message
      });
    } else {
      console.error("Unexpected error:", error);
    }
    
    return errorHandler(error instanceof Error ? error : new Error(String(error)));
  }
}

// RECOMMENDED: Assertion functions for development
function assert(condition: boolean, message: string): asserts condition {
  if (!condition) {
    throw new Error(`Assertion failed: ${message}`);
  }
}

function assertNever(value: never): never {
  throw new Error(`Unexpected value: ${value}`);
}

function assertIsNumber(value: unknown): asserts value is number {
  if (typeof value !== "number") {
    throw new ValidationError(
      `Expected number, got ${typeof value}`,
      "value",
      value
    );
  }
}

// RECOMMENDED: Safe resource management
class ResourceManager<T> {
  constructor(
    private resource: T,
    private cleanup: (resource: T) => void | Promise<void>
  ) {}
  
  async use<R>(operation: (resource: T) => Promise<R>): Promise<Result<R, string>> {
    try {
      const result = await operation(this.resource);
      return createResult(result);
    } catch (error) {
      return createError(error instanceof Error ? error.message : String(error));
    } finally {
      try {
        await this.cleanup(this.resource);
      } catch (cleanupError) {
        console.error("Cleanup failed:", cleanupError);
      }
    }
  }
}

// TIP: ERROR HANDLING STRATEGY:
// - Use Result types for operations that can fail gracefully
// - Create domain-specific error classes for better debugging and handling
// - Never fail silently - always log errors with context for monitoring
// - Implement proper cleanup in finally blocks to prevent resource leaks
// - Use assertions for development-time checks to catch bugs early