DEV Community: Fedar Haponenka

When to Switch to a Third-Party Localization Library

Fedar Haponenka — Mon, 26 Jan 2026 09:31:04 +0000

When starting a new project, my instinct is to keep things lean: minimal dependencies, maximum control, and code I fully understand. Localization often seems like the perfect candidate for a custom solution. After all, what's simpler than some JSON files and a locale switcher? But there comes a tipping point where simple becomes painful. Here's how to know when it's time to switch to a professional library.

The Simple Custom Solution

Let's start with what a basic custom implementation looks like:

// locales/en.json
{
  "welcome": "Welcome to our application",
  "login": {
    "title": "Sign In"
  },
  "user": {
    "greeting": "Hello, {name}!"
  }
}

// locales/ru.json
{
  "welcome": "Добро пожаловать в наше приложение",
  "login": {
    "title": "Войти"
  },
  "user": {
    "greeting": "Привет, {name}!"
  }
}

// localization.ts
interface Translations {
  [key: string]: string | Translations;
}

class Localization {
  private currentLocale: string = 'en';
  private translations: Map<string, Translations> = new Map();

  async loadLocale(locale: string): Promise<void> {
    const response = await fetch(`locales/${locale}.json`);
    const data = await response.json();
    this.translations.set(locale, data);
  }

  t(key: string, params?: Record<string, unknown>): string {
    const keys = key.split('.');
    let value: string | Translations | undefined = this.translations.get(this.currentLocale);

    for (const k of keys) {
      value = (value as Translations)?.[k];
      if (!value) {
        return key; // Fallback to key
      }
    }

    // Simple parameter replacement
    if (params && typeof value === 'string') {
      return Object.entries(params).reduce((str, [param, val]) => {
        return str.replace(new RegExp(`{${param}}`, 'g'), String(val));
      }, value);
    }

    return typeof value === 'string' ? value : key;
  }

  setLocale(locale: string): void {
    this.currentLocale = locale;
  }
}

This works perfectly at first. Then reality hits.

Pluralization Complexity

While English has only two forms, in Russian, nouns after numerals are declined (have different endings). This can be problematic, as it requires writing complex checks that aren't always obvious.

pluralize(count: number, forms: string[]): string {
    if (this.currentLocale === 'ru') {
        if (count <= 20 && count > 10) {
            return forms[2];
        }

        if (count % 10 === 1) {
            return forms[0];
        }

        if ([2, 3, 4].includes(count % 10)) {
            return forms[2];
        }

        return forms[2];
    }

    // English is easy
    return count === 1 ? forms[0] : forms[1];
}

Even these conditions don't cover all cases. What happens when you need to add another language?

Formatting Everything

Suddenly you need to format:

Dates (12/25/2023 vs 25.12.2023)
Times (2:30 PM vs 14:30)
Numbers (1,234.56 vs 1 234,56)
Currencies (€1,234.56 vs 1.234,56 € vs 1 234,56€)

Your simple utility grows to hundreds of lines of locale-specific formatting rules.

Now migration to a specialized localization library is becoming inevitable.

Security Considerations

This is where many developers hesitate. "But npm packages have vulnerabilities!". True, but consider:

Custom solution vulnerabilities:

XSS through unescaped interpolation
Path traversal in locale loading (../../../etc/passwd)
ReDoS in your regex-based replacement
Memory leaks from poor caching
No security team reviewing your code

Library vulnerabilities:

Dedicated security teams
Regular audits
CVEs with patches within days
Community scrutiny

The truth: Your custom code is likely more vulnerable than well-maintained, widely-used libraries. You're one regex mistake away from an XSS vulnerability that nobody will find until it's exploited.

When to Make the Switch

The decision to switch from a custom solution to a library isn't just about lines of code. It's about recognizing when you're solving problems that have already been solved better. That moment often arrives silently. One day you're adding a simple translation, the next you're debugging why your Russian pluralization doesn't work correctly. Or you discover that your custom middleware doesn't properly handle locale detection for search engine crawlers, hurting your international SEO.

The true cost of custom i18n becomes apparent when you consider opportunity cost. Every hour spent maintaining your own solution is an hour not spent building features that differentiate your product. When localization becomes a recurring headache rather than a solved foundation, when new team members struggle to understand your bespoke system, or when adding a new language feels like a multi-day engineering task rather than a simple translation update.
Here's your decision framework:

Switch NOW if:

You support 3+ languages with different plural rules
You need date/number/currency formatting
You're expanding to right-to-left languages (Arabic, Hebrew)
You need SSR/SSG support

Stay Custom if:

You only support English (maybe +1 similar language like Spanish)
No complex formatting needed
Bundle size is absolutely critical (<1KB budget)
You're building a prototype (will rebuild later)

Making AI Code Consistent with Linters

Fedar Haponenka — Tue, 23 Dec 2025 07:06:34 +0000

As AI coding assistants like GitHub Copilot, Cursor, and Claude Code become popular, a surprising pattern has emerged: teams that enforce strict linting and code style rules are getting better results from AI agents. The reason? Consistent, predictable code patterns create a perfect environment for AI to contribute safely and effectively.

The Problem: AI's Creative Inconsistency

Ask an AI to implement a new feature, and you'll often get code that's functionally correct but stylistically chaotic:

// ❌ AI without guidance produces inconsistent patterns
async function getUserData(id: string) {
  const response = await fetch(`/api/users/${id}`);
  return await response.json();
}

function getUserData(id: string) {
  return fetch(`/api/users/${id}`).then(res => res.json());
}

const getUserData = async (id: string) => {
  return fetch(`/api/users/${id}`).then(res => res.json());
}

Three similar operations, three different patterns. This inconsistency creates technical debt from day one.

The Limitations of Documentation Alone

Many teams try to guide AI with documentation files like instructions.md, agents.md, or coding-standards.md. While these are valuable for human developers, they're fundamentally suggestions, not guarantees. AI agents might read them, but there's no enforcement mechanism:

# instructions.md - AI might or might not follow these

- Use async/await instead of .then()
- Always add explicit return types
- Use interfaces over type aliases
- Prefer arrow functions for callbacks

# Result: AI sometimes follows, sometimes doesn't

Documentation provides hints, but linters provide rules. The difference is critical: AI can choose to ignore documentation, but it cannot ignore linting errors in your CI pipeline.

The Solution: Teaching AI Your Code Standards

When you configure strict linting rules, you're essentially creating a style guide that AI can follow perfectly. Consider this TypeScript setup:

// .eslintrc.json
{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking"
  ],
  "rules": {
    "@typescript-eslint/explicit-function-return-type": "error",
    "@typescript-eslint/no-explicit-any": "error",
    "@typescript-eslint/consistent-type-definitions": ["error", "interface"],
    "@typescript-eslint/consistent-type-imports": "error",
    "@typescript-eslint/array-type": ["error", { "default": "generic" }],
    "arrow-body-style": ["error", "always"],
    "prefer-arrow-callback": "error"
  }
}

With these rules, AI-generated code becomes predictably consistent:

// ✅ AI with linting rules produces consistent code
interface User {
  id: string;
  name: string;
  email: string;
}

const getUserData = async (userId: string): Promise<User> => {
  const response = await fetch(`/api/users/${userId}`);
  const data: unknown = await response.json();

  // Type guard enforced by linting rules
  if (isValidUser(data)) {
    return data;
  }
  throw new Error('Invalid user data');
};

const isValidUser = (data: unknown): data is User => {
  return (
    typeof data === 'object' &&
    data !== null &&
    'id' in data &&
    'name' in data &&
    'email' in data
  );
};

TypeScript Strictness as a guardrail

TypeScript's strict mode combined with ESLint rules prevents AI from taking shortcuts:

// ❌ AI might try this without constraints
const processData = (data: any) => {
  return data.map(item => item.value * 2);
};

// ✅ With strict linting, AI produces safe code
interface DataPoint {
  value: number;
  timestamp: Date;
}

const processData = (dataPoints: DataPoint[]): number[] => {
  return dataPoints.map((dataPoint: DataPoint): number => {
    return dataPoint.value * 2;
  });
};

Import/Export Consistency

AI tends to mix import styles, but linters enforce uniformity:

// ❌ Inconsistent imports AI might generate
import React from 'react';
import { useState, useEffect, useCallback } from "react";
import { type User, getUsers } from '../../services/userService';
import { formatDate, isValidEmail } from '@/utils/helpers';

// ✅ Linter-enforced consistency
import React, { useState, useEffect, useCallback } from 'react';
import { type User, getUsers } from '@/services/userService';
import { formatDate, isValidEmail } from '@/utils/helpers';

Naming Convention Enforcement

Linters make AI use consistent naming across the codebase:

// With naming-convention rules, AI learns your patterns
interface UserPreferences {
  theme: 'light' | 'dark';
  notificationsEnabled: boolean;
  language: string;
}

class UserService {
  private apiClient: ApiClient;

  async getUserPreferences(userId: string): Promise<UserPreferences> {
    return this.apiClient.fetch<UserPreferences>(
      `/users/${userId}/preferences`
    );
  }

  async updateUserPreferences(
    userId: string,
    preferences: Partial<UserPreferences>
  ): Promise<void> {
    await this.apiClient.update(
      `/users/${userId}/preferences`,
      preferences
    );
  }
}

The Magic of Prettier + ESLint Integration

When you combine Prettier for formatting with ESLint for rules, AI produces code that looks like it was written by your team:

// .prettierrc.json
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2,
  "arrowParens": "always"
}

// AI-generated code with Prettier + ESLint
interface ApiResponse<T> {
  data: T;
  status: number;
  message?: string;
}

const handleUserUpdate = async (
  userId: string,
  updates: Partial<User>
): Promise<ApiResponse<User>> => {
  try {
    const response = await fetch(`/api/users/${userId}`, {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(updates),
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const result = await response.json();
    return {
      data: result,
      status: response.status,
    };
  } catch (error) {
    console.error('Failed to update user:', error);
    throw error;
  }
};

Different Rules for Humans vs AI

An emerging best practice is to apply stricter rules to AI-generated code than to human-written code. Rules that feel burdensome for developers are trivial for AI to follow perfectly:

Human-friendly linting rules (.eslintrc.json):

{
  "overrides": [
    {
      "files": ["*.ts", "*.tsx"],
      "rules": {
        "require-jsdoc": "off",
        "max-lines-per-function": "off",
        "complexity": ["warn", 10],
        "no-nested-ternary": "warn",
        "@typescript-eslint/explicit-function-return-type": "warn"
      }
    }
  ]
}

AI-optimized strict rules (.eslintrc.ai.json):

{
  "extends": ["./.eslintrc.json"],
  "overrides": [
    {
      "files": ["*.ai.ts", "*.ai.tsx", "*-generated.ts", "src/ai/**/*.ts"],
      "rules": {
        "require-jsdoc": "error",
        "max-lines-per-function": ["error", { "max": 20 }],
        "complexity": ["error", 5],
        "no-nested-ternary": "error",
        "no-magic-numbers": "error",
        "@typescript-eslint/explicit-function-return-type": "error",
        "@typescript-eslint/explicit-member-accessibility": "error"
      }
    }
  ]
}

This dual-rule approach recognizes the fundamental difference between human and AI coding:

Humans need flexibility for creative problem-solving and rapid iteration
AI excels at following rigid patterns consistently without cognitive overhead

Practical Implementation

{
  "scripts": {
    "lint:human": "eslint . --ext .ts,.tsx --config .eslintrc.json",
    "lint:ai": "eslint . --ext .ts,.tsx --config .eslintrc.ai.json",
    "lint:all": "npm run lint:human && npm run lint:ai"
  }
}

Create an AI-specific linting workflow:

bash
# Check AI-generated code with strict rules
npm run lint:ai --config .eslintrc.ai.json

# Check human code with developer-friendly rules  
npm run lint:human --config .eslintrc.json

# In CI/CD pipeline
if [ "$AUTHOR" = "AI_ASSISTANT" ]; then
  npm run lint:ai
else
  npm run lint:human
fi

Smart Constraints for Smart Tools

The most successful teams aren't just using AI to write code. They're creating targeted constraints that maximize AI's strengths while minimizing developer friction. By applying stricter linting rules selectively to AI-generated code, you get the benefits of perfect consistency without burdening your human developers.
Your linting configuration is becoming more than just a style guide. It's becoming a collaboration framework that optimizes how humans and AI work together.

When JavaScript Proxies Actually Save the Day

Fedar Haponenka — Tue, 16 Dec 2025 08:36:29 +0000

JavaScript Proxies often feel like an advanced feature you rarely need in day-to-day development. Most tutorials show trivial examples like logging property access or validation. That don't justify the complexity. But I recently faced a situation where Proxies were the only solution that worked.

I was working on a project using a third-party calendar library that was no longer supported. Users complained about losing scroll position when modifying events. Upgrading wasn't an option because we had no budget, and the vendor had abandoned the code. We were stuck with minified, obfuscated JavaScript we couldn't modify.

The Problem: Black Box Code

When you can't see the source code, traditional fixes don't work:

Can't modify the code: It's minified and obfuscated
Can't wait for a fix: Vendor support ended

This is exactly when Proxies shine: they let you intercept behavior at runtime without touching the original code.

Understanding the Calendar Architecture

Before attempting any fix, I needed to understand what I was working with. Through debugging, I discovered the calendar's structure.

Core Components:

Resources List: People, Tools
Events List: Calendar items assigned to resources
Scroll Manager: Internal component tracking position

Whenever an event updated, the calendar would:

Update the event in the Events List
Update the associated resource
Re-render both lists (changing the container height)

The prolonged re-render led to the scroll position reset.

The Discovery: Accidental Global Access

While debugging, I found the vendor had accidentally exposed internal state:

// Vendor's internal structure

window.__calendarInternals = {
  scrollManager: {
    updateScrollPosition: function() {
      // This was resetting our scroll!
    }
  }
};

This wasn't a public API. It was an implementation detail that leaked to the global scope. But it gave me an entry point.

The Proxy Solution

Here's where Proxies became essential. I couldn't modify the original function, but I could wrap it:

const originalManager = window.__calendarInternals.scrollManager;

// Create a proxy that intercepts updateScrollPosition
const proxiedManager = new Proxy(originalManager, {
  get(target, prop, receiver) {
    if (prop === 'updateScrollPosition') {
      return function() {
        // Only allow scroll updates when NOT in a calendar refresh
        if (!window.__blockScrollUpdates) {
          return target.updateScrollPosition.apply(this, arguments);
        }
      };
    }
    return Reflect.get(...arguments);
  }
});

// Replace the internal reference
window.__calendarInternals.scrollManager = proxiedManager;

Now, during calendar updates:

// Block scroll updates while updating
window.__blockScrollUpdates = true;
calendar.updateEvent(eventId, changes);
window.__blockScrollUpdates = false;

Why This Only Works with Proxies

Let's compare alternatives that wouldn't work:

// ❌ Direct assignment - breaks other functionality
scrollManager.updateScrollPosition = function() {
  // Now we lose all original behavior!
};

// ❌ Wrapper function - calendar may ignore it
const original = scrollManager.updateScrollPosition;
scrollManager.updateScrollPosition = function() {
  if (!window.__blockScrollUpdates) {
    return original.apply(this, arguments);
  }
};
Object.getPrototypeOf(scrollManager).updateScrollPosition.call(context);

// ❌ Event listeners - can't prevent the call
// No event is emitted before the scroll reset

// ✅ Proxy - intercepts ALL access
// Calendar thinks it's calling the original, but gets our version

The proxy creates a complete illusion. The calendar code thinks it's interacting with the original scroll manager, but every property access goes through our handler first.

The Result

The fix was remarkably small but completely solved the issue. Most importantly:

No vendor code modified: We didn't touch the minified library
No side effects: Other calendar functionality remained intact
Easy to remove: Just stop using the proxy wrapper

Should You Use Proxies More Often?

Probably not. For 95% of day-to-day work, simpler patterns work fine. But for that remaining 5%, when you're dealing with code you can't control, Proxies move from "interesting feature" to "essential tool".

Case Study: How I Reduced React Bundle Size by 68%

Fedar Haponenka — Sat, 13 Dec 2025 08:31:29 +0000

I worked on a B2B application where I faced a common misconception: businesses are more tolerant of poor Google Core Web Vitals and bloated bundle sizes because "users access from office PCs with fast internet." Unfortunately, reality was different. Primary users accessed the application from mobile phones with mobile internet connections. When I discovered this, optimization became critical.

Starting Point: The production bundle size was 1,542 KB (gzipped).
Target: 500 KB (following industry best practices)

Step 1: Compression - Already Optimized

The obvious first step was enabling Brotli compression, which typically saves 15-25% compared to gzip. However, the infrastructure already had Brotli enabled. No gains here.

Step 2: Route-Based Code Splitting

React Router supports lazy loading out of the box. I eagerly implemented dynamic imports for all routes:

// Before
import Dashboard from './Dashboard';

// After
const Dashboard = React.lazy(() => import('./Dashboard'));

Result: Bundle reduced by 37% to 971 KB. A great start!

Step 3: Dependency Analysis & Vendor Splitting

Using Webpack Bundle Analyzer, I discovered heavy third-party libraries dominating the bundle:

Date picker/calendar libraries
Feature flag management
Analytics SDKs
PDF editor
WYSIWYG editor
File upload widget

These were imported directly across multiple modules. I created wrapper modules with dynamic imports:

// Before - Direct imports everywhere
import { DatePicker } from 'heavy-date-library';

// After - Wrapper with lazy loading
export const loadDatePicker = () => 
  import('heavy-date-library').then(module => module.DatePicker);

Result: Bundle reduced to 57% of original size (879 KB).

Step 4: Module Decoupling & Dependency Chains

The bundle analyzer revealed tightly coupled dependency chains. For example:

// ❌ Tightly coupled
// Module A imported Module B, which imported Module C, 
// which imported a heavy utility library
// All loaded together even if only one piece was needed

// ✅ Solution: Extract shared code to independent modules
// Created small, focused modules with only necessary shared code
// Broke circular dependencies

I identified and separated these chains, creating smaller, focused modules with only necessary shared code.

Result: Bundle at 63% reduction (571 KB).

Step 5: Localization Optimization

The application supported several languages, but all translations loaded synchronously regardless of user preference.

Before: All language files bundled together (≈ 120 KB of JSON).
After: Only the user's selected language loads initially:

// Dynamic locale loading
const loadLocale = (locale) => 
  import(`./locales/${locale}.json`);

// Initial load: only user's language or default

Final Result: 493 KB - a 68% reduction that beat our 500 KB target!

Key Takeaways

Assumptions are dangerous: I learned never to assume user context without data
Analyze before optimizing: Webpack Bundle Analyzer was invaluable for my process
Third-party libraries are expensive: I became strategic about heavy dependencies
Dependency chains matter: I discovered tight coupling creates bundle bloat
Localization can be heavy: Dynamic loading per language is essential

Boost React TypeScript Test Coverage Without Slowing Down

Fedar Haponenka — Fri, 05 Dec 2025 15:23:46 +0000

In fast-moving React TypeScript projects, testing often becomes the casualty of tight deadlines. Teams face a dilemma: slow down to write tests or ship faster with technical debt. But this is a false choice. With the right strategy, you can systematically increase test coverage while maintaining or even accelerating development speed.

Shift Left: Test as You Build, Not After

The most significant speed boost comes from changing when you test. Waiting until a feature is "done" to write tests creates massive overhead. Instead, adopt a Test-First mindset.

Component Contracts with TypeScript

Before writing a component, define its props with TypeScript. This simple constraint acts as a living specification and catches entire categories of errors before runtime.

interface Props {
  variant: 'primary' | 'secondary';
  onClick: () => void;
  children: React.ReactNode;
}

// The component automatically validates against this interface
const Button: React.FC<Props> = ({ variant, onClick, children }) => {
  return (
    <button 
      className={`btn btn-${variant}`} 
      onClick={onClick}
    >
      {children}
    </button>
  );
};

Now, your test suite validates this contract automatically. TypeScript becomes your first line of defense, reducing the need for extensive runtime validation tests.

Prioritize Smartly: The Testing Pyramid

Don't aim for 100% coverage everywhere. Apply the 80/20 rule to testing.

1. Unit Test What Matters Most
Focus your unit tests on:

Custom Hooks (with React Testing Library's renderHook)
Utility/Helper functions
Complex business logic
Critical UI components (Forms, Buttons, Inputs)

2. Integration Over Isolation
Instead of testing every component in isolation, write fewer but more valuable integration tests that verify how components work together. A well-written integration test can replace 5-10 unit tests.

3. Mock Strategically, Not Excessively
Over-mocking creates brittle tests that slow you down. Follow these rules:

Mock external dependencies (APIs, third-party libraries)
Don't mock your own components unless absolutely necessary
Use MSW (Mock Service Worker) for API mocking. It works at the network level and is far more realistic.

Automate the Boring Parts

1. Type-Safe Test Utilities
Create a comprehensive test utilities file with custom render functions, data factories, and helper methods.

// test-utils.tsx
import { ReactElement } from 'react';
import { render, RenderOptions } from '@testing-library/react';
import { Provider } from 'react-redux';
import { configureStore, Store } from '@reduxjs/toolkit';
import { RootState } from '../store';
import { userReducer } from '../store/slices/userSlice';

interface ExtendedRenderOptions extends Omit<RenderOptions, 'wrapper'> {
  preloadedState?: Partial<RootState>;
  store?: Store;
}

export function renderWithProviders(
  ui: ReactElement,
  {
    preloadedState = {},
    store = configureStore({
      reducer: { user: userReducer },
      preloadedState,
    }),
    ...renderOptions
  }: ExtendedRenderOptions = {}
) {
  const Wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
    <Provider store={store}>{children}</Provider>
  );

  return {
    store,
    ...render(ui, { wrapper: Wrapper, ...renderOptions }),
  };
}

// Type-safe test data factory
export function createMockUser(overrides?: Partial<User>): User {
  return {
    id: '1',
    name: 'Test User',
    email: 'test@example.com',
    ...overrides,
  };
}

2. Coverage Gates
Set up test coverage gates in your test runner.

// jest.config.ts

import type { Config } from 'jest';

const config: Config = {
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: -10,
    },
  },
};

export default config;

Type-Safe Testing as an Accelerator

When done right, TypeScript-enhanced tests don't slow you down, they speed you up. The type system catches errors at compile time, reducing runtime surprises. By focusing on valuable tests and automating the tedious parts, you can achieve both comprehensive coverage and high velocity.

How Intentional Constraints Lead to Superior Code

Fedar Haponenka — Mon, 01 Dec 2025 15:39:43 +0000

In software development, the word "constraint" often carries a negative connotation, suggesting limitation and a lack of freedom. However, experienced engineers know that the opposite is true: well-chosen constraints are not limitations; they are liberating. They channel creativity into productive paths, reduce cognitive load, and systematically eliminate entire classes of errors.

The Paradox of Choice and the Tyranny of Freedom

When a codebase has no constraints, every developer is a law unto themselves. This leads to an environment where everything is possible, but nothing of value is easy to accomplish. You see:

Inconsistent patterns: Should this be a function or a class? No one knows.
Bike-shedding: Endless debates over trivial decisions like code formatting.
Architectural drift: Every new feature is built in a slightly different way. Constraints solve this by removing the paradox of choice.

How Constraints Act as a Force Multiplier

Type Systems: The Compiler as a Guardian

A type system like TypeScript's is a powerful constraint. It removes the possibility of entire categories of runtime errors by making them compile-time errors.

// Unconstrained JavaScript
function calculateTotal(price, quantity) {
    return price * quantity; // What if `quantity` is a string?
}

// Constrained TypeScript
function calculateTotal(price: number, quantity: number): number {
    return price * quantity; // The compiler guarantees the types.
}

This constraint forces developers to think more clearly about data shapes and function contracts, leading to more robust code.

Linting and Formatting: Enforcing Consistency

Tools like ESLint and Prettier impose constraints on code style and structure. While debates over semicolons and tabs are trivial, the consistency they provide is invaluable. It eliminates mental overhead when reading code, makes diffs easier to review, and prevents stylistic debates from clogging up pull requests. This allows teams to focus on what truly matters: logic and architecture.

Immutability: Constraining State Mutations

One of the most powerful constraints in modern software is immutability. By forbidding the mutation of existing data structures and requiring that every change creates a new object, we eliminate hidden side effects and temporal coupling.

// Constrained, functional approach
const addUser = (users: User[], newUser: User) => [...users, newUser];

// vs. the unconstrained, mutable approach
const addUser = (users: User[], newUser: User) => {
  users.push(newUser);
  return users;
}

The first function is predictable and easy to test. The second mutates state in a way that can be difficult to trace. Frameworks like React have popularized this constraint for a reason: it makes state changes predictable and debuggable.

Architectural Constraints: Drawing the Lines

Architectural patterns like MVC, Clean Architecture, and microservices are, at their core, sets of constraints. They dictate:

Direction of dependencies: Domain logic must not depend on the UI or database.
Data flow: In a unidirectional data flow architecture (like Redux), data moves in one predictable direction.
Boundaries: Microservices enforce separation of concerns at a system level.

These constraints prevent the "big ball of mud" architecture. They make the system easier to reason about, test, and modify in parts without breaking the whole.

The Psychology of Constraints

Constraints work because they align with how our brains function best. They reduce decision fatigue, allowing developers to focus their mental energy on solving complex business problems rather than on trivial choices. They create a "pit of success" where the easiest way to write code is also the correct, maintainable way.

Implementing Effective Constraints

The goal is not to create a straitjacket, but a scaffold. Good constraints are:

Automated: Enforced by tools, not by memory or peer pressure.
Consensual: Agreed upon by the team to serve a clear purpose.
Revisable: Able to be changed when they no longer serve their purpose.

Freedom Through Discipline

The path to high-quality, maintainable code is not paved with unlimited freedom. It is built with a foundation of thoughtful, intentional constraints. By embracing a strong type system, consistent styling, immutable data, and a clear architecture, we don't limit our potential, we amplify it. We trade the chaos of infinite possibility for the clarity of a well-defined path, and in doing so, we build software that is not just functional, but truly robust.

Donald Knuth’s insight captures our mission perfectly:

Science is what we understand well enough to explain to a computer. Art is everything else.

Constraints are the tools we use to turn the art of programming into a disciplined science.

The Disservice of Optional Properties in TypeScript Interfaces

Fedar Haponenka — Fri, 28 Nov 2025 09:18:54 +0000

TypeScript's optional properties, marked with a ?, seem like a convenient way to design flexible interfaces. They promise backward compatibility and the ability to create objects incrementally. However, overusing them is an anti-pattern that often leads to fragile, bug-prone code. What appears to be flexibility is frequently a lack of design clarity.

The Illusion of Flexibility

Consider a typical user interface:

interface User {
  id: string;
  name: string;
  email?: string;
  phoneNumber?: string;
  avatarUrl?: string;
}

This seems harmless, but it creates a fundamental problem: we no longer know what a valid User is. Does a valid user require an email? The type system can't tell us. This ambiguity spreads through the entire application.

The Cascading Complexity

Optional properties push the burden of validation from the type system to runtime checks and developer vigilance. Every function that consumes this interface must handle the possibility of missing data.

function sendWelcomeNotification(user: User) {
  // This code is now littered with guards
  if (user.email) {
    sendEmail(user.email, template);
    return;
  }

  if (user.phoneNumber) {
    sendSms(user.phoneNumber, template);
    return;
  } 

  // What now? Log an error? Throw an exception?
  // The type system gave us no guidance.
}

This violates the core purpose of TypeScript: to use types to eliminate entire categories of runtime errors.

The Null Object Pattern and Explicit Design

Often, the need for an optional property reveals an unstated requirement for a default value or a state machine. Instead of a single, partially-defined interface, use separate, fully-defined interfaces that represent different states.

// A user that has completed core registration
interface RegisteredUser {
  id: string;
  name: string;
}

// A user that has a confirmed contact method
interface ContactableUser extends RegisteredUser {
  email: string; // This is now required
}

// A user with a full profile
interface CompleteUser extends ContactableUser {
  phoneNumber: string;
  avatarUrl: string;
}

This approach forces you to answer critical design questions up front. What is the minimum data required for a user to be considered "registered"? When is an email truly mandatory?

For properties that genuinely might not exist, be explicit with union types or use the null object pattern.

// Instead of `avatarUrl?: string;`
interface User {
  id: string;
  name: string;
  avatarUrl: string | null; // Explicitly marked as potentially absent
}

When Optional Properties Are Acceptable

There are legitimate use cases for optional properties, primarily at the boundaries of your system, such as:

Configuration Objects: Where many settings have sensible defaults.
Data Transfer Objects (DTOs) for PATCH operations: Where you only want to update provided fields.
Third-Party API Responses: Where you cannot control the data shape.

Even in these cases, validate and convert these optional inputs into required properties in your core domain models as soon as possible.

Embrace Intentional Design

Optional properties are a code smell that often indicates unresolved business logic. By favoring required properties and explicit state modeling, you create a type system that works for you, not against you. You'll write code that is self-documenting, less prone to runtime errors, and easier to refactor.
Make your interfaces assertions about what data must be present, and let the compiler guarantee it for you. Your future self, and your teammates, will thank you for the clarity.

The Hidden Cost of Utility Types and Inheritance in TypeScript

Fedar Haponenka — Wed, 26 Nov 2025 09:28:17 +0000

TypeScript's type system is a powerful tool for building robust applications. Features like utility types and interface inheritance feel like natural ways to reduce repetition and structure code. However, when overused, they can silently introduce complexity and fragility that undermine the very maintainability we seek.

When Utility Types Create Complexity

Utility types like Pick, Omit, and Partial are incredibly convenient. They allow us to create new types on the fly, often saving us from writing verbose type definitions.

The Problem: Overusing them, especially nested within other utilities, creates "type opaqueness." The origin and contract of a type become obscured, making the code harder to understand and reason about.

Consider this example:

type User = {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
  preferences: { /* ... */ };
};

// A function that updates a user... but what does it actually need?
function updateUser(id: string, updates: Partial<Pick<User, 'name' | 'email'>> & { lastModified: Date }) {
  // ...
}

What is the shape of updates? You have to mentally unravel the Partial<Pick<...>> & ... chain. This violates a core principle of clean code: clarity is king.

As Robert C. Martin states in Clean Code

The ratio of time spent reading versus writing is well over 10 to 1. Making it easy to read makes it easier to write.

A simple, explicit interface would be far clearer:

interface UserUpdateRequest {
  name?: string;
  email?: string;
  lastModified: Date;
}

This is self-documenting. The cognitive load for the next developer (or future you) is drastically reduced.

The Inheritance Trap

The real danger in overusing extends with Omit or Pick is that it creates a hidden, fragile coupling between types. While it seems like you're avoiding duplication, you're actually creating a silent dependency that is easy to break.

Consider this common pattern:

interface User {
    birthDate: number; // UTC
    email: string;
    id: string;
    name: string;
    role: 'admin' | 'user' | 'guest';
}

interface UserFormValues extends Omit<User, 'birthDate' | 'id' | 'role'> {
    birthDate: BirthDate | null; // Different type
}

The Problem: This code creates an implicit contract that says, "UserFormValues should mirror most fields from User, except for a few." But this contract is not enforced by the architecture—it exists only in the developer's mind.

When you add a new field to the User interface, like phoneNumber: string, it automatically propagates to UserFormValues through the Omit clause. This might be exactly what you want, or it might be a silent bug.

The solution is to make the relationship explicit and intentional:

interface UserFormValues {
    email: string;
    name: string;
    birthDate: BirthDate | null;
}

Now, when the User interface changes, UserFormValues remains stable until you consciously decide to update it. Your form logic is now robust against changes in the entity model.

The Path to Maintainable TypeScript:

Prefer Explicit Interfaces: Use simple, named interfaces to define clear, independent contracts.
Use Utility Types for Derivation, Not Coupling: They are excellent for creating one-off derivatives, but avoid using them to create permanent, coupled type hierarchies.
Favor Conscious Coupling: Before using extends with Omit, ask: "Do I want this type to automatically inherit all future changes from the parent?" If the answer is no, use an explicit type.

By valuing clarity and loose coupling over cleverness and convenience, we can leverage TypeScript's power to create codebases that are not just type-safe, but also human-friendly and built to last.