DEV Community: Manas Joshi

Vitest Mocking: vi.mock vs vi.spyOn Explained

Manas Joshi — Sun, 12 Apr 2026 13:31:02 +0000

Vitest Mocking Deep Dive: `vi.mock` vs. `vi.spyOn`

Testing JavaScript applications often involves isolating the code under test from its dependencies. This isolation is achieved through mocking, a technique that replaces real dependencies with controlled substitutes. While essential, the distinction between Vitest's primary mocking utilities—vi.mock and vi.spyOn—can be a source of confusion. This article will clarify their specific use cases, complete with practical code examples.

Understanding `vi.mock`: Replacing Entire Modules

vi.mock is your go-to function when you need to replace an entire module or specific named exports within a module. This is particularly useful for external dependencies like API clients, database connectors, or utility libraries that perform side effects (e.g., network requests, file system operations) you want to control during a test.

When vi.mock is called, Vitest intercepts calls to the specified module throughout the test file. It effectively swaps out the real module for your mock implementation before the module under test is even imported.

Consider a dataService.js that fetches data:

// src/dataService.js
import axios from 'axios';

export const fetchData = async (id) => {
  const response = await axios.get(`https://api.example.com/data/${id}`);
  return response.data;
};

export const postData = async (payload) => {
  const response = await axios.post('https://api.example.com/data', payload);
  return response.data;
};

To test a component or function that uses fetchData without making actual network calls, you'd mock axios:

// test/dataService.test.js
import { describe, it, expect, vi } from 'vitest';
import { fetchData } from '../src/dataService';

// Mock the entire 'axios' module
vi.mock('axios', () => ({
  default: {
    get: vi.fn(() => Promise.resolve({ data: { id: 1, name: 'Mocked Data' } })),
    post: vi.fn(() => Promise.resolve({ data: { status: 'success' } }))
  }
}));

describe('fetchData', () => {
  it('should fetch data using mocked axios', async () => {
    const result = await fetchData(1);
    expect(result).toEqual({ id: 1, name: 'Mocked Data' });
    // Verify axios.get was called
    expect(vi.mocked(axios).get).toHaveBeenCalledWith('https://api.example.com/data/1');
  });
});

In this example, vi.mock('axios', ...) replaces the entire axios module. The factory function returns an object that becomes the mocked module. We mock axios.default because axios is often imported as a default export. vi.fn() creates a mock function, allowing us to control its return value (mockImplementation, mockResolvedValue, mockReturnValue) and inspect its calls (toHaveBeenCalledWith). vi.mocked(axios) is a type helper to ensure TypeScript knows axios is a mocked object.

Sometimes, you only need to mock a specific export from your own module, not the entire module. You can use a partial mock:

// test/partialMock.test.js
import { describe, it, expect, vi } from 'vitest';
import * as dataService from '../src/dataService'; // Import everything to access other exports

vi.mock('../src/dataService', async (importOriginal) => {
  const actual = await importOriginal(); // Get the actual module exports
  return {
    ...actual, // Spread all actual exports
    fetchData: vi.fn(() => Promise.resolve({ id: 99, name: 'Partially Mocked' })) // Override only fetchData
  };
});

describe('dataService partial mock', () => {
  it('should use the mocked fetchData but real postData', async () => {
    const fetched = await dataService.fetchData(123);
    expect(fetched).toEqual({ id: 99, name: 'Partially Mocked' });

    // If postData had a distinct side effect, we'd see it, or mock it separately if needed.
    // Here, for demonstration, imagine postData is still the original function.
    // expect(dataService.postData).toBeDefined(); // This would pass if not mocked
  });
});

Here, vi.mock uses an async factory function. importOriginal() resolves to the actual module's exports, allowing us to selectively override fetchData while keeping postData (and any other exports) as their original implementations. This is crucial when you only want to isolate a specific function without affecting others in the same module.

Understanding `vi.spyOn`: Inspecting and Modifying Existing Methods

vi.spyOn is used when you want to observe or temporarily modify the behavior of an existing method on an existing object. It does not replace an entire module; rather, it wraps around a specific method, allowing you to track its calls, arguments, and return values, and even change its implementation for the duration of a test.

vi.spyOn is ideal for:

Observing internal calls: Checking if a helper method was called by the public method being tested.
Temporarily altering behavior: Making a method return a specific value or throw an error for a test case without affecting other methods on the same object or other modules.

Let's consider a UserService class with a dependency on a logger:

// src/userService.js
export const logger = {
  log: (message) => console.log(`LOG: ${message}`),
  error: (message) => console.error(`ERROR: ${message}`)
};

export class UserService {
  constructor() {
    this.users = [];
  }

  addUser(user) {
    if (!user || !user.name) {
      logger.error('Invalid user data provided');
      return false;
    }
    this.users.push(user);
    logger.log(`User ${user.name} added.`);
    return true;
  }
}

We want to test addUser and ensure logger.error is called with the correct message when invalid data is provided, without actually logging to the console:

// test/userService.test.js
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { UserService, logger } from '../src/userService';

describe('UserService', () => {
  let userService;
  let errorSpy;

  beforeEach(() => {
    userService = new UserService();
    // Spy on the 'error' method of the 'logger' object
    errorSpy = vi.spyOn(logger, 'error');
    // Restore the original implementation after each test to prevent interference
    errorSpy.mockRestore(); // Important for clean tests
  });

  it('should add a user successfully', () => {
    const user = { name: 'Alice' };
    const result = userService.addUser(user);
    expect(result).toBe(true);
    expect(userService.users).toContainEqual(user);
    expect(logger.log).toHaveBeenCalledWith('User Alice added.');
  });

  it('should log an error and return false for invalid user data', () => {
    // Temporarily replace the implementation of logger.error for this test
    errorSpy.mockImplementation(() => {}); // Do nothing

    const result = userService.addUser(null);
    expect(result).toBe(false);
    expect(userService.users).toEqual([]); // No user should be added
    expect(errorSpy).toHaveBeenCalledWith('Invalid user data provided');
  });
});

Here, vi.spyOn(logger, 'error') creates a spy on the error method of the logger object. The beforeEach block ensures a fresh spy for each test and calls errorSpy.mockRestore(). This is crucial because vi.spyOn modifies the original method, and if not restored, subsequent tests might be affected. In the second test, errorSpy.mockImplementation(() => {}) overrides the error method's behavior, making it do nothing instead of logging to console.error. This allows us to test the logic without console pollution and verify the spy was called correctly.

When to Use Which?

Use vi.mock when:
- You need to replace an entire external module (e.g., axios, a database client).
- You need to replace specific named exports of a module before it's imported by the code under test.
- The dependency is imported directly via import X from 'module' or import { Y } from 'module' and you want to control its behavior globally for a test file.
Use vi.spyOn when:
- You want to observe if a method on an already instantiated object (or a module's direct export) was called, with what arguments, and how many times.
- You need to temporarily change the implementation of an existing method on an object for a specific test scenario, without affecting other methods on that object or requiring a full module replacement.
- You're working with classes or objects where methods are called directly on instances.

Common Mistakes and Gotchas

vi.mock Hoisting: vi.mock calls are hoisted to the top of the file. This means they execute before any import statements. If you try to define a mock after your imports, it won't work as expected. Always place vi.mock at the top level of your test file.
Forgetting mockRestore() with vi.spyOn: Spies modify the actual object method. If you use mockImplementation or mockReturnValue on a spy and don't call spy.mockRestore() (often in a afterEach or beforeEach block), the modified behavior will leak into subsequent tests, leading to flaky results.
Mocking too much: Over-mocking can lead to tests that don't reflect real-world behavior and become brittle. Mock only what's necessary to isolate the unit under test and control side effects.
Misunderstanding Default Exports: When mocking modules with default exports (like axios), remember to mock the default property within your factory function (e.g., default: vi.fn()).
Not using vi.mocked for TypeScript: When mocking modules with TypeScript, cast the mocked module using vi.mocked(myModule) to get proper type inference for your mock functions, preventing TypeScript errors when accessing mock-specific methods like toHaveBeenCalled.

Conclusion

Mastering vi.mock and vi.spyOn is fundamental for writing robust and reliable unit tests with Vitest. vi.mock allows you to control entire module dependencies, providing a clean slate for isolating your code. vi.spyOn, on the other hand, offers granular control over individual methods, enabling inspection and temporary behavior modification without broad module replacement. By understanding their distinct purposes and avoiding common pitfalls, you can write more effective and maintainable tests, ensuring the quality of your JavaScript applications.

Dive into your Vitest tests and apply these techniques to gain finer control over your testing environment!

Master TypeScript Discriminated Unions for Safer Type Narrowing

Manas Joshi — Tue, 07 Apr 2026 08:11:49 +0000

When building applications with TypeScript, you often encounter situations where a variable can hold data of several distinct but related shapes. Handling these variations safely and efficiently is crucial for robust code. TypeScript's powerful combination of discriminated unions and type narrowing provides an elegant solution, allowing you to write code that is both type-safe and easy to understand. This guide will walk you through applying these concepts with practical examples, moving beyond high-level theory to concrete implementation.

Understanding Discriminated Unions

A discriminated union is a specific pattern in TypeScript where a union type is composed of several types that all share a common, literal-valued property—the "discriminant." This discriminant property acts as a tag, allowing TypeScript's control flow analysis to determine which specific type within the union you are currently working with.

Consider an application that processes various user events. These events share some common properties but also have unique ones.

interface UserLoggedInEvent {
  type: "LOGGED_IN";
  userId: string;
  timestamp: number;
}

interface UserLoggedOutEvent {
  type: "LOGGED_OUT";
  userId: string;
  timestamp: number;
  reason?: string;
}

interface UserPurchasedItemEvent {
  type: "ITEM_PURCHASED";
  userId: string;
  timestamp: number;
  itemId: string;
  price: number;
}

type UserEvent = UserLoggedInEvent | UserLoggedOutEvent | UserPurchasedItemEvent;

Here, we define three interfaces for different user events: UserLoggedInEvent, UserLoggedOutEvent, and UserPurchasedItemEvent. Each interface includes a type property, which is a string literal (e.g., "LOGGED_IN"). This type property is our chosen discriminant. The UserEvent type is then a union of these three interfaces, explicitly defining type as the common literal property across all members of the union.

Type Narrowing in Action

The real power of discriminated unions emerges when combined with type narrowing. TypeScript's control flow analysis intelligently infers the specific type of a variable based on runtime checks. When you check the value of the discriminant property, TypeScript knows which specific member of the union you are referring to, allowing you to safely access properties unique to that type.

Let's write a function to process these UserEvent types:

function processUserEvent(event: UserEvent): void {
  switch (event.type) {
    case "LOGGED_IN":
      console.log(`User ${event.userId} logged in at ${new Date(event.timestamp).toLocaleString()}`);
      // Inside this block, 'event' is narrowed to UserLoggedInEvent
      break;
    case "LOGGED_OUT":
      console.log(`User ${event.userId} logged out at ${new Date(event.timestamp).toLocaleString()}. Reason: ${event.reason || 'N/A'}`);
      // Inside this block, 'event' is narrowed to UserLoggedOutEvent
      break;
    case "ITEM_PURCHASED":
      console.log(`User ${event.userId} purchased item ${event.itemId} for $${event.price} at ${new Date(event.timestamp).toLocaleString()}`);
      // Inside this block, 'event' is narrowed to UserPurchasedItemEvent
      break;
    default:
      // This default case handles any unhandled types if the union expands without corresponding cases.
      console.warn("Unknown event type received:", (event as any).type);
  }
}

In this processUserEvent function, we utilize a switch statement on event.type. Within each case block, TypeScript automatically narrows the event parameter to the corresponding specific type (e.g., UserLoggedInEvent). This enables safe access to properties like event.reason (exclusive to UserLoggedOutEvent) or event.itemId (exclusive to UserPurchasedItemEvent) without requiring explicit type assertions or any casts, significantly enhancing code safety and clarity.

Ensuring Exhaustive Checks with `never`

A common concern when working with union types is ensuring that you've handled all possible cases. If you introduce a new type to a discriminated union but neglect to update all associated processing functions, you risk introducing a bug. TypeScript's never type, when combined with type narrowing, offers an elegant solution for enforcing comprehensive, compile-time exhaustive checks.

interface UserDeletedEvent {
  type: "USER_DELETED";
  userId: string;
  timestamp: number;
  adminId: string;
}

type NewUserEvent = UserEvent | UserDeletedEvent; // Extend the union with a new event

function processNewUserEvent(event: NewUserEvent): void {
  switch (event.type) {
    case "LOGGED_IN":
      console.log(`User ${event.userId} logged in.`);
      break;
    case "LOGGED_OUT":
      console.log(`User ${event.userId} logged out.`);
      break;
    case "ITEM_PURCHASED":
      console.log(`User ${event.userId} purchased ${event.itemId}.`);
      break;
    case "USER_DELETED":
      console.log(`User ${event.userId} deleted by ${event.adminId}.`);
      break;
    default:
      // This line will cause a compile-time TypeScript error if any case is missing from the switch!
      const _exhaustiveCheck: never = event;
      throw new Error(`Unhandled event type: ${(_exhaustiveCheck as any).type}`);
  }
}

When a new type like UserDeletedEvent is added to NewUserEvent, if you forget to add a corresponding case "USER_DELETED": to processNewUserEvent, the default block will be reached. In this default context, event would still be of the unhandled type. By attempting to assign event to a variable explicitly typed never, TypeScript will emit a compile-time error. This effectively forces you to add a case for UserDeletedEvent (or any other future unhandled type), ensuring that all members of the union are explicitly managed and significantly improving the robustness of your codebase against future modifications.

Common Mistakes & Gotchas

Mismatched Discriminant Values: A frequent pitfall is a simple typo in the string literal used for the discriminant. For example, if your case statement incorrectly uses "LOGED_IN" instead of "LOGGED_IN", TypeScript will fail to correctly narrow the type within that block, leading to potential errors when attempting to access specific properties. Always carefully verify your string literal values.
Forgetting the Discriminant Property: If you define a union of types but neglect to include the common literal property (the discriminant) on all members of that union, TypeScript cannot effectively narrow the type. For instance, if UserLoggedInEvent lacked type: "LOGGED_IN", then checking event.type would not sufficiently narrow event to UserLoggedInEvent.
Incomplete Exhaustive Checks: While the const _exhaustiveCheck: never = event; pattern is incredibly powerful, its effectiveness relies on the default branch being genuinely reachable only by unhandled types. If you handle some cases and then return early from the function, leaving the default unreachable for other unhandled types, the never check won't trigger. Ensure your control flow guarantees that any unhandled union members will reach the default block.
Implicit any without never: If you choose not to employ the never trick and your default branch merely logs a warning, TypeScript might implicitly infer the event type as any within that default context, thereby undermining type safety. The never check is crucial for maintaining strict compile-time safety across all possible code paths.

Key Takeaways

Discriminated unions, when expertly paired with TypeScript's control flow-based type narrowing, represent an indispensable pattern for managing varying data shapes within your applications. They empower you to write highly expressive, type-safe, and inherently maintainable code by explicitly defining expected data structures and providing compiler-guided mechanisms for handling each variant correctly. Embracing this pattern significantly reduces the incidence of runtime errors and enhances your codebase's resilience to future modifications and expansions.

Conclusion

By now, you should possess a robust understanding of how to effectively implement and leverage discriminated unions and type narrowing within your TypeScript projects. From precisely defining distinct interfaces with a shared literal property to utilizing switch statements for accurate type inference and employing the never type for exhaustive checks, these techniques collectively empower you to build more robust and reliable applications. Start integrating discriminated unions into your TypeScript code today to unlock a new level of type safety, clarity, and maintainability.

Optimize React Re-renders: DevTools & Memoization Guide

Manas Joshi — Sun, 05 Apr 2026 03:28:17 +0000

Optimizing React Re-renders: A Deep Dive with DevTools and Memoization

React's declarative nature simplifies UI development, but it can also obscure performance bottlenecks. One of the most common culprits for sluggish React applications is unnecessary component re-renders. While React is highly optimized, understanding when and why components re-render, and how to control it, is crucial for building performant user interfaces.

This article will guide you through a practical workflow: first, identifying re-render hotspots using the React DevTools Profiler, and then, resolving them with powerful memoization techniques like React.memo, useCallback, and useMemo. We'll skip the high-level theory and dive straight into actionable code and tooling.

Understanding React Component Re-renders

At its core, React components re-render when React detects that something might have changed, prompting it to re-evaluate the component's output and update the DOM if necessary. This happens primarily for two reasons:

State Changes: When a component's internal state (managed by useState or useReducer) is updated, React schedules a re-render for that component and its children.
Prop Changes or Parent Re-renders: If a parent component re-renders, by default, all of its child components will also re-render, regardless of whether their props have actually changed. This is a crucial point where unnecessary work can pile up.

While React is fast, frequent, unnecessary re-renders—especially in complex component trees—can consume significant CPU cycles, lead to memory overhead, drain battery life, and ultimately degrade the user experience. Our goal is to minimize renders that don't result in a visible UI change.

Tooling Up: React DevTools Profiler

Before optimizing, we need to know where to optimize. The React DevTools browser extension (available for Chrome, Firefox, and Edge) is indispensable for this. Specifically, its Profiler tab allows you to record rendering cycles and visualize component performance.

How to Use the Profiler:

Install React DevTools: If you haven't already, add the extension to your browser.
Open DevTools: Navigate to your React application in the browser and open your browser's developer tools.
Go to the Profiler Tab: You'll see a 'Components' tab and a 'Profiler' tab (or '⚛️ Components'/'⚛️ Profiler'). Click on 'Profiler'.
Start Recording: Click the 'Record' button (a circle icon). Interact with your application as a user would, triggering various state updates and component interactions.
Stop Recording: Click the 'Stop' button. The Profiler will then display a flame graph or ranked chart showing your component renders.

In the flame graph, components are stacked, and their width indicates the time spent rendering. Look for components that frequently appear in different render cycles or have disproportionately long render times, especially if their props seem unchanged. Yellow or green highlights often indicate a component that rendered.

The Re-rendering Problem: A Basic Example

Let's set up a common scenario where a child component re-renders unnecessarily just because its parent does.

// ChildComponent.jsx
import React from 'react';

const ChildComponent = ({ data, onClick }) => {
  console.log('ChildComponent re-rendered');
  return (
    <div style={{ padding: '10px', border: '1px solid #ddd', margin: '10px 0', borderRadius: '4px' }}>
      <h3>Child Component</h3>
      <p>Data: {data}</p>
      <button onClick={onClick} style={{ padding: '8px 12px', background: '#007bff', color: 'white', border: 'none', borderRadius: '4px', cursor: 'pointer' }}>
        Click Me (Child)
      </button>
    </div>
  );
};

export default ChildComponent;

// ParentComponent.jsx
import React, { useState } from 'react';
import ChildComponent from './ChildComponent';

function ParentComponent() {
  const [count, setCount] = useState(0);
  const [text, setText] = useState('Hello');

  const handleChildClick = () => {
    console.log('Child button clicked!');
  };

  return (
    <div style={{ padding: '20px', border: '2px solid #61DAFB', borderRadius: '8px', background: '#f6f6f6' }}>
      <h1>Parent Component</h1>
      <p>Parent Count: {count}</p>
      <button onClick={() => setCount(prev => prev + 1)} style={{ padding: '10px 15px', background: '#282C34', color: 'white', border: 'none', borderRadius: '4px', cursor: 'pointer', marginRight: '10px' }}>
        Increment Parent Count
      </button>
      <input
        type="text"
        value={text}
        onChange={(e) => setText(e.target.value)}
        placeholder="Type here"
        style={{ padding: '8px', border: '1px solid #ccc', borderRadius: '4px' }}
      />
      <ChildComponent data={text} onClick={handleChildClick} />
    </div>
  );
}

export default ParentComponent;

In this setup, ParentComponent manages a count state and a text state. It renders a ChildComponent, passing text as data and handleChildClick as an onClick prop. If you run this code and click the "Increment Parent Count" button, you'll observe ChildComponent re-rendered in the console, even though the data prop (text) has not changed. This happens because ParentComponent re-renders when count updates, and by default, React re-renders all its children. Furthermore, handleChildClick is re-declared on every ParentComponent render, meaning a new function reference is passed to ChildComponent each time, which React perceives as a prop change.

The Memoization Solution: `React.memo` and `useCallback`

To prevent unnecessary re-renders, React provides memoization utilities. Memoization is an optimization technique where you cache the result of an expensive function call and return the cached result when the same inputs occur again.

`React.memo` for Components

React.memo is a Higher-Order Component (HOC) that memoizes a functional component. It prevents the component from re-rendering if its props have not changed (via a shallow comparison). If a prop is a primitive (number, string, boolean), comparison is straightforward. If it's an object or function, React.memo performs a shallow comparison of references.

`useCallback` for Functions

As we saw, functions are re-created on every render. useCallback is a React Hook that returns a memoized version of a callback function that only changes if one of the dependencies has changed. This is essential when passing callbacks to memoized child components, as it ensures the function reference remains stable.

Let's apply these to our example:

// ChildComponent.jsx (Memoized)
import React from 'react';

const ChildComponent = React.memo(({ data, onClick }) => {
  console.log('Memoized ChildComponent re-rendered');
  return (
    <div style={{ padding: '10px', border: '1px solid #ddd', margin: '10px 0', borderRadius: '4px' }}>
      <h3>Child Component (Memoized)</h3>
      <p>Data: {data}</p>
      <button onClick={onClick} style={{ padding: '8px 12px', background: '#007bff', color: 'white', border: 'none', borderRadius: '4px', cursor: 'pointer' }}>
        Click Me (Child)
      </button>
    </div>
  );
});

export default ChildComponent;

// ParentComponent.jsx (with useCallback)
import React, { useState, useCallback } from 'react';
import ChildComponent from './ChildComponent';

function ParentComponent() {
  const [count, setCount] = useState(0);
  const [text, setText] = useState('Hello');

  // Memoize the callback function with useCallback
  const handleChildClick = useCallback(() => {
    console.log('Child button clicked!');
  }, []); // Empty dependency array means it's created once

  return (
    <div style={{ padding: '20px', border: '2px solid #61DAFB', borderRadius: '8px', background: '#f6f6f6' }}>
      <h1>Parent Component</h1>
      <p>Parent Count: {count}</p>
      <button onClick={() => setCount(prev => prev + 1)} style={{ padding: '10px 15px', background: '#282C34', color: 'white', border: 'none', borderRadius: '4px', cursor: 'pointer', marginRight: '10px' }}>
        Increment Parent Count
      </button>
      <input
        type="text"
        value={text}
        onChange={(e) => setText(e.target.value)}
        placeholder="Type here"
        style={{ padding: '8px', border: '1px solid #ccc', borderRadius: '4px' }}
      />
      <ChildComponent data={text} onClick={handleChildClick} />
    </div>
  );
}

export default ParentComponent;

Here, we've wrapped ChildComponent with React.memo. This tells React to skip re-rendering ChildComponent unless its data or onClick props have shallowly changed. We've also wrapped handleChildClick with useCallback and an empty dependency array ([]). This ensures that handleChildClick maintains the same function reference across ParentComponent re-renders. Now, if you click "Increment Parent Count," you'll see ParentComponent re-renders, but Memoized ChildComponent re-rendered will not log to the console, confirming that the child's re-render was successfully prevented. If you type in the input field, text changes, thus data prop changes, triggering ChildComponent to re-render.

`useMemo` for Expensive Values

Sometimes, you pass an object or array as a prop, or perform an expensive calculation within a component. Even with React.memo, if a new object/array is created on every render, the shallow comparison will fail, causing re-renders. useMemo helps here by memoizing the result of a function and only re-calculating it when its dependencies change.

// ParentComponent.jsx (with useMemo for a computed value)
import React, { useState, useMemo, useCallback } from 'react';
import ChildComponent from './ChildComponent'; // Assume the Memoized ChildComponent from above

function ParentComponent() {
  const [count, setCount] = useState(0);
  const [filter, setFilter] = useState('');

  const items = ['apple', 'banana', 'orange', 'grape', 'kiwi'];

  // Memoize an expensive calculation or object creation
  const filteredItems = useMemo(() => {
    console.log('Running expensive item filter...');
    return items.filter(item => item.includes(filter));
  }, [filter, items]); // Re-run this function only when filter or items change

  const handleChildClick = useCallback(() => {
    console.log('Child button clicked!');
  }, []);

  return (
    <div style={{ padding: '20px', border: '2px solid #61DAFB', borderRadius: '8px', background: '#f6f6f6' }}>
      <h1>Parent Component</h1>
      <p>Parent Count: {count}</p>
      <button onClick={() => setCount(prev => prev + 1)} style={{ padding: '10px 15px', background: '#282C34', color: 'white', border: 'none', borderRadius: '4px', cursor: 'pointer', marginRight: '10px' }}>
        Increment Parent Count
      </button>
      <input
        type="text"
        value={filter}
        onChange={(e) => setFilter(e.target.value)}
        placeholder="Filter items" // This input changes the 'filter' state
        style={{ padding: '8px', border: '1px solid #ccc', borderRadius: '4px' }}
      />
      {/* Pass the memoized array (converted to string for simplicity) to ChildComponent */}
      <ChildComponent data={filteredItems.join(', ')} onClick={handleChildClick} />
    </div>
  );
}

export default ParentComponent;

In this example, filteredItems is an array whose creation involves a filtering operation. Without useMemo, a new filteredItems array would be created on every ParentComponent render, even if the filter state hadn't changed. By wrapping the filtering logic with useMemo, we ensure that filteredItems is only re-calculated and a new array reference is generated when its dependencies (filter or items) actually change. If you increment the count state, you'll see neither Running expensive item filter... nor Memoized ChildComponent re-rendered in the console, indicating that both the calculation and the child component's render were skipped.

Common Mistakes and Gotchas

While powerful, memoization tools can be misused. Be aware of these pitfalls:

Over-memoization: Not every component or value needs to be memoized. Memoization itself has a small overhead (memory and comparison cost). Apply it judiciously, primarily when profiling indicates a performance bottleneck, or when passing props down to many children that do not need to re-render.
Incorrect Dependency Arrays:
- Missing Dependencies: Forgetting to include all values from the component's scope that are used inside useCallback or useMemo can lead to stale closures. Your memoized function/value might use an outdated version of a state or prop, causing bugs.
- Unnecessary Dependencies: Including dependencies that change frequently (e.g., an object always re-created inline {} or []) defeats the purpose of memoization, as the memoized value/function will still be re-created on almost every render.
- Object/Array Dependencies: If a dependency in useCallback or useMemo is a non-primitive (object or array) that is created inline within the render function (e.g., someProp={ { id: 1 } }), its reference will change on every render. This causes the memoized hook to re-run. Instead, memoize the object/array itself upstream with useMemo if its contents are stable.
Shallow Comparison Limitations: React.memo performs a shallow comparison of props. If a prop is a complex object or array and only its internal properties change (but not its reference), React.memo will not detect a change and will skip re-rendering. In such rare cases, you might need a custom comparison function for React.memo's second argument, but it's often a sign that you should normalize your state or avoid mutating objects directly.

Key Takeaways

Unnecessary React component re-renders are a common cause of performance issues.
The React DevTools Profiler is your primary tool for identifying these re-render hotspots.
React.memo prevents functional components from re-rendering if their props haven't changed (shallowly).
useCallback memoizes function references, essential for stable props passed to React.memo children.
useMemo memoizes expensive values or objects, preventing their re-creation on every render.
Use memoization strategically, targeting identified bottlenecks, rather than universally applying it.

Conclusion

Mastering re-render optimization is a critical skill for any React developer aiming to build high-performance, responsive applications. By integrating the React DevTools Profiler into your development workflow and judiciously applying React.memo, useCallback, and useMemo, you gain precise control over your application's rendering behavior. Start profiling your components today and deliver smoother, more efficient user experiences.

Reliable LLM JSON Output: Few-Shot Prompting & Robust Parsing

Manas Joshi — Thu, 02 Apr 2026 10:10:27 +0000

Achieving Reliable Structured JSON Output from LLMs

As developers integrate Large Language Models (LLMs) into their applications, a common challenge emerges: consistently obtaining structured data (like JSON) rather than freeform text. While LLMs excel at generating natural language, coercing them into a precise, parsable format requires specific techniques. This post dives into how to reliably extract structured JSON from LLMs using few-shot prompting and robust programmatic parsing.

The Challenge with Unstructured LLM Responses

By default, LLMs are designed to generate human-like text. When asked to produce JSON, they might include conversational filler, return malformed JSON, or deviate from the specified schema. Relying solely on a textual instruction often leads to brittle integrations that break with minor model variations or unexpected outputs.

Consider a simple request to extract product details into a JSON object. A basic prompt might look like this:

from openai import OpenAI
import json

client = OpenAI()

def get_basic_summary(text_content: str) -> str:
    response = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "system", "content": "You are a helpful assistant designed to extract information into JSON."},
            {"role": "user", "content": f"""
            Extract the product name, price, and category from the following text into a JSON object.
            Text: "{text_content}"
            Expected JSON format: {{"product_name": "string", "price": float, "category": "string"}}
            """}
        ]
    )
    return response.choices[0].message.content

# Example usage
text_input_good = "The new 'Quantum Leap SSD' is available for $199.99 in the Storage category."
text_input_bad = "I saw a 'Smart Coffee Maker' today at $120.00. It's in the Kitchen Appliances."

print("Good example output:")
print(get_basic_summary(text_input_good))

print("\nBad example output (might vary):")
print(get_basic_summary(text_input_bad))

This code defines get_basic_summary to send a user message to an LLM, requesting information extraction into JSON. The prompt includes a template for the desired JSON structure. However, without explicit examples, the LLM might prepend conversational text like "Here's the JSON:" or sometimes return malformed JSON, making programmatic parsing difficult and unreliable.

Guiding LLMs with Few-Shot Prompting

Few-shot prompting is a technique where you provide the LLM with a few input-output examples before giving it the actual task. This teaches the model the desired format and behavior more effectively than just describing it. For structured output, this means demonstrating the exact JSON structure you expect.

When using the OpenAI API's chat.completions.create endpoint, few-shot examples are provided by adding pairs of {"role": "user", "content": ...} and {"role": "assistant", "content": ...} messages to the messages array, prior to the final user prompt. This implicitly trains the model on the desired interaction pattern.

from openai import OpenAI
import json

client = OpenAI()

def get_few_shot_summary(text_content: str) -> str:
    response = client.chat.completions.create(
        model="gpt-3.5-turbo", # Or gpt-4, gpt-4o for better results
        messages=[
            {"role": "system", "content": "You are a helpful assistant designed to extract information into JSON. Always respond with only the JSON object."},
            # Few-shot example 1
            {"role": "user", "content": "Extract the product name, price, and category from the following text into a JSON object. Text: 'New 'Zenith X Headphones' are priced at $249.00 under Audio.'"},
            {"role": "assistant", "content": '{"product_name": "Zenith X Headphones", "price": 249.00, "category": "Audio"}'},
            # Few-shot example 2
            {"role": "user", "content": "Extract the product name, price, and category from the following text into a JSON object. Text: 'Grab the 'Ergo Mouse Pro' for $45.50 in Computer Accessories.'"},
            {"role": "assistant", "content": '{"product_name": "Ergo Mouse Pro", "price": 45.50, "category": "Computer Accessories"}'},
            # Actual request for which we want the output
            {"role": "user", "content": f"""
            Extract the product name, price, and category from the following text into a JSON object.
            Text: "{text_content}"
            """}
        ]
    )
    return response.choices[0].message.content

# Example usage
text_input_valid = "The 'Ultra HD Monitor' is now $399.99, found in Electronics."
print("Few-shot output (much cleaner):")
print(get_few_shot_summary(text_input_valid))

This updated function get_few_shot_summary incorporates few-shot examples within the messages array. Each pair of user and assistant messages explicitly demonstrates the desired input-output format, specifically the clean JSON structure. The system message also reinforces the instruction to only respond with JSON, leading to much more consistent and parseable output from the LLM.

Robust Output Parsing and Validation

Even with effective few-shot prompting, LLMs can occasionally make mistakes. Therefore, it's crucial to implement robust parsing and validation on the application side. This involves using a JSON parser and then validating the parsed data against an expected schema. For Python, the built-in json module is essential, and you can define a simple class for schema validation.

from openai import OpenAI
import json

client = OpenAI()

# Assuming get_few_shot_summary is defined as above
# (omitted here for brevity, but it would be included in a full script)

class ProductData:
    def __init__(self, product_name: str, price: float, category: str):
        if not isinstance(product_name, str) or not product_name:
            raise ValueError("Product name must be a non-empty string.")
        if not isinstance(price, (int, float)) or price < 0:
            raise ValueError("Price must be a non-negative number.")
        if not isinstance(category, str) or not category:
            raise ValueError("Category must be a non-empty string.")

        self.product_name = product_name
        self.price = price
        self.category = category

    @classmethod
    def from_dict(cls, data: dict):
        # Basic validation on presence of keys before passing to __init__
        required_keys = ["product_name", "price", "category"]
        if not all(key in data for key in required_keys):
            missing_keys = [key for key in required_keys if key not in data]
            raise ValueError(f"Missing required fields: {', '.join(missing_keys)}")
        return cls(
            product_name=data["product_name"],
            price=data["price"],
            category=data["category"]
        )

    def __repr__(self):
        return f"ProductData(name='{self.product_name}', price={self.price}, category='{self.category}')"

def get_and_parse_product_data(text_content: str) -> ProductData | None:
    llm_output = get_few_shot_summary(text_content) # Call the LLM with few-shot prompting

    try:
        # Step 1: Parse the JSON string into a Python dictionary
        parsed_json = json.loads(llm_output)

        # Step 2: Validate against our custom schema/class
        product_instance = ProductData.from_dict(parsed_json)
        return product_instance
    except json.JSONDecodeError as e:
        print(f"Error parsing JSON from LLM: {e}")
        print(f"LLM Output was: {llm_output}")
        return None
    except ValueError as e:
        print(f"Validation error for product data: {e}")
        print(f"LLM Output was: {llm_output}")
        print(f"Parsed JSON (before validation error) was: {parsed_json if 'parsed_json' in locals() else 'N/A'}")
        return None
    except Exception as e:
        print(f"An unexpected error occurred: {e}")
        return None

# Example usage:
text_input = "The 'Gaming Headset Pro' is listed at $89.99 in the Peripherals section."
result = get_and_parse_product_data(text_input)
print(result)

text_input_malformed = "'Wireless Earbuds' for $59.99, category Audio. oops, this isn't json"
result_malformed = get_and_parse_product_data(text_input_malformed) # This will likely trigger JSONDecodeError
print(result_malformed)

This code block demonstrates robust parsing and validation of LLM output. It first defines a ProductData class with type hints and validation logic to ensure the extracted data adheres to expected rules (e.g., price is a non-negative number, product_name is a non-empty string). The get_and_parse_product_data function calls the get_few_shot_summary function (which leverages few-shot prompting) to get the LLM's raw string output. Crucially, it wraps the json.loads call and ProductData.from_dict instantiation in a try-except block to catch json.JSONDecodeError for malformed JSON and ValueError for data that fails ProductData's validation, making the application resilient to imperfect LLM responses.

Common Mistakes and Gotchas

When working with structured LLM output, be aware of these pitfalls:

Ignoring parsing errors: Never assume the LLM will always return perfectly valid, schema-compliant JSON. Always wrap your parsing logic in try-except blocks to handle malformed outputs gracefully.
Too few or too many examples: While one or two few-shot examples often suffice for simple structures, providing too few can lead to ambiguity. Conversely, too many examples consume more tokens, increasing latency and cost, and can sometimes overconstrain the model or hit token limits.
Inconsistent example formats: Your few-shot examples must strictly adhere to the exact desired output format. Any deviation in spacing, key names, or data types within the examples can confuse the model.
Schema drift: If your application's data schema changes, remember to update both your few-shot examples and your parsing/validation logic (e.g., your ProductData class). Outdated schemas lead to validation failures.
Prompt Injection within Examples: Be cautious if user-supplied input is directly incorporated into the few-shot examples without sanitization. Malicious input could potentially alter the model's behavior in unexpected ways.

Conclusion

Achieving reliable structured JSON output from LLMs is not about magic, but about meticulous prompt engineering and robust application-side parsing. By consistently employing few-shot prompting to demonstrate your desired format and implementing strong validation, you can build much more stable and predictable LLM integrations. Embrace these techniques to transform your LLM from a free-text generator into a dependable data extraction engine.

Start experimenting with few-shot examples and see how much more control you gain over your LLM's output today!

TypeScript Discriminated Unions: Safe API Response Handling

Manas Joshi — Wed, 01 Apr 2026 03:11:49 +0000

TypeScript Discriminated Unions: Safely Handling Dynamic API Responses

In the real world, API responses aren't always uniform. Sometimes, a single endpoint might return data in wildly different shapes depending on a status field, or an error might contain different details than a successful payload. This heterogeneity can quickly lead to runtime errors if not handled carefully. TypeScript's discriminated unions, combined with type guards, provide an elegant and robust solution to this common challenge, ensuring type safety even when dealing with dynamic data.

This article dives into how to define and use discriminated unions to confidently process API responses that vary in structure. We'll move beyond high-level concepts and explore practical code examples, demonstrating how to leverage TypeScript's type narrowing capabilities for more reliable applications.

Understanding Discriminated Unions

At its core, a discriminated union is a type that consists of several other types (a union), where each member of the union shares a common, literal property (the 'discriminant'). This property acts as a tag, allowing TypeScript to narrow down the specific type within the union at runtime based on its value.

Consider an API that returns either a success payload with user data or an error payload with a message. Both responses might share a status field, but its value ('success' or 'error') dictates the presence of other fields.

Defining Our API Response Types

Let's start by defining the possible shapes of our API responses using interfaces and then combining them into a discriminated union type. We'll use a status property as our discriminant.

interface UserData {
  id: string;
  name: string;
  email: string;
}

interface SuccessApiResponse {
  status: 'success';
  data: UserData;
}

interface ErrorApiResponse {
  status: 'error';
  message: string;
  errorCode?: number; // Optional error code
}

// Our discriminated union type
type ApiResponse = SuccessApiResponse | ErrorApiResponse;

Here, UserData defines the structure of a successful payload. SuccessApiResponse and ErrorApiResponse each declare a status property with a literal string type ('success' or 'error'). This literal type is crucial for the discriminant. Finally, ApiResponse is a union of these two interfaces. Notice how SuccessApiResponse has a data property, while ErrorApiResponse has message and an optional errorCode.

Implementing Type Guards for Narrowing

Once we have our discriminated union, the next step is to write code that can intelligently determine which specific type it's currently dealing with. This is where type guards come in. A type guard is a runtime check that guarantees a type within a certain scope. For discriminated unions, checking the discriminant property acts as a powerful type guard.

Let's create a function that processes an ApiResponse:

function processApiResponse(response: ApiResponse): void {
  if (response.status === 'success') {
    // TypeScript now knows 'response' is a SuccessApiResponse
    console.log(`User ID: ${response.data.id}, Name: ${response.data.name}`);
    // console.log(response.message); // This would cause a compile-time error
  } else {
    // TypeScript now knows 'response' is an ErrorApiResponse
    console.error(`Error (${response.errorCode || 'unknown'}): ${response.message}`);
    // console.log(response.data); // This would also cause a compile-time error
  }
}

// Example usage:
const successRes: ApiResponse = {
  status: 'success',
  data: { id: '123', name: 'Alice', email: 'alice@example.com' }
};

const errorRes: ApiResponse = {
  status: 'error',
  message: 'User not found', 
  errorCode: 404
};

processApiResponse(successRes);
processApiResponse(errorRes);

In processApiResponse, the if (response.status === 'success') statement acts as a type guard. Inside the if block, TypeScript automatically narrows the type of response to SuccessApiResponse. This means you can safely access response.data without any type assertions. Conversely, in the else block, TypeScript narrows response to ErrorApiResponse, allowing access to response.message and response.errorCode.

Processing Collections of Mixed Responses

Discriminated unions truly shine when you need to process an array or collection of items that could be any of the union members. Imagine a scenario where you've made multiple API calls, and you want to log both successful results and errors.

const apiResponses: ApiResponse[] = [
  { status: 'success', data: { id: 'u1', name: 'Bob', email: 'bob@example.com' } },
  { status: 'error', message: 'Unauthorized', errorCode: 401 },
  { status: 'success', data: { id: 'u2', name: 'Charlie', email: 'charlie@example.com' } }
];

apiResponses.forEach(response => {
  switch (response.status) {
    case 'success':
      console.log(`Fetched user: ${response.data.name} (ID: ${response.data.id})`);
      break;
    case 'error':
      console.error(`API Error: ${response.message} (Code: ${response.errorCode || 'N/A'})`);
      break;
    default:
      // This branch should theoretically be unreachable if all cases are handled.
      // 'never' type helps ensure exhaustiveness.
      const _exhaustiveCheck: never = response;
      return _exhaustiveCheck;
  }
});

Here, we iterate through an array of ApiResponse objects. The switch (response.status) statement provides clear branching logic. For each case, TypeScript intelligently narrows the response type, allowing direct and safe access to the specific properties of SuccessApiResponse or ErrorApiResponse. The default case with const _exhaustiveCheck: never = response; is a powerful TypeScript pattern. If you were to add a new variant to ApiResponse (e.g., LoadingApiResponse) but forgot to add a corresponding case in the switch, TypeScript would issue a compile-time error, reminding you to handle all possibilities. This ensures exhaustiveness and prevents unexpected runtime behavior.

Common Mistakes and Gotchas

While powerful, discriminated unions have a few pitfalls to be aware of:

Missing or Optional Discriminant Property: The common property must be present in all members of the union and have a literal type (e.g., 'success', not string). If it's optional (status?: 'success') or a broad string type, TypeScript cannot reliably use it for narrowing.
Incorrect Type Guards: Relying on typeof for object differentiation often doesn't work as expected, as typeof someObject will always return 'object'. Always use the literal discriminant property for narrowing discriminated unions.
Non-Exhaustive Checks: Forgetting to handle all possible cases in if/else if/else chains or switch statements can lead to runtime errors if new union members are introduced. The never type check in a default case is a strong guard against this.
Accidental Overlap: Ensure your discriminant values are truly unique across the union members. If SuccessApiResponse and ErrorApiResponse could both have status: 'pending', TypeScript wouldn't be able to narrow them effectively based on that property.

Key Takeaways

Discriminated unions are a cornerstone of advanced TypeScript usage, providing a robust mechanism to handle data with varying structures. By explicitly defining the possible shapes and using a common literal property as a discriminant, you enable TypeScript's static analysis to perform precise type narrowing. This leads to code that is:

Safer: Runtime errors due to incorrect property access are drastically reduced.
Clearer: The code explicitly documents the possible data shapes and how they are handled.
More Maintainable: Refactoring is easier, as TypeScript will flag unhandled cases when union members change.

Conclusion

Mastering discriminated unions and type guards is an essential skill for any intermediate TypeScript developer. They empower you to write more resilient and maintainable applications, especially when interacting with external systems like APIs that may return dynamic data. Experiment with these patterns in your own projects to experience the full benefits of TypeScript's type system in action. Your future self (and your teammates) will thank you for the clarity and safety they provide.

Cancel JavaScript Async Ops with AbortController

Manas Joshi — Tue, 31 Mar 2026 01:06:55 +0000

Cleanly Cancel Asynchronous Operations with JavaScript's AbortController

Modern web applications heavily rely on asynchronous operations like fetching data from APIs, handling user input with delays, or executing long-running computations. Without proper management, these operations can lead to undesirable behaviors: stale data, race conditions where an older request's response overwrites a newer one, or even memory leaks if resources aren't properly cleaned up.

JavaScript's AbortController provides a standardized way to signal cancellation to cancellable asynchronous operations. It's a powerful tool for maintaining application stability and responsiveness, offering a native, elegant solution to problems often previously tackled with complex custom logic.

Understanding AbortController

The AbortController is a simple Web API object with two main components: a signal property and an abort() method.

new AbortController(): Creates a new controller instance.
controller.signal: This is an AbortSignal object. It's an event target that you pass to cancellable asynchronous APIs. When the abort() method is called, the signal fires an abort event.
controller.abort(): Triggers the cancellation. This sets the signal.aborted property to true and dispatches an abort event on the associated signal.

Many built-in Web APIs, notably fetch, and some DOM APIs like addEventListener, natively support AbortSignal for cancellation. Custom asynchronous operations can also integrate with it.

Example 1: Basic Fetch Cancellation

The most common use case for AbortController is cancelling fetch requests. Imagine a scenario where a user navigates away from a page before a large data fetch completes. Continuing that fetch is wasteful and its eventual response could trigger unwanted state updates.

const controller = new AbortController();
const signal = controller.signal;

async function fetchData() {
  try {
    const response = await fetch('https://api.example.com/data', { signal });
    const data = await response.json();
    console.log('Data fetched:', data);
  } catch (error) {
    if (error.name === 'AbortError') {
      console.log('Fetch aborted.');
    } else {
      console.error('Fetch error:', error);
    }
  }
}

fetchData();

// Simulate user navigating away or a timeout after 1 second
setTimeout(() => {
  controller.abort();
  console.log('Request cancelled via AbortController.');
}, 1000);

In this example:

We create an AbortController and extract its signal.
The signal is passed to the fetch options object. This tells fetch to listen for cancellation.
If controller.abort() is called before fetch completes, the fetch Promise will reject with an AbortError.
The catch block specifically checks for error.name === 'AbortError' to differentiate a user-initiated cancellation from other network or API errors, allowing for appropriate handling.

Example 2: Managing Component-Scoped Requests

In single-page applications, it's common for components to initiate data fetches. If a component unmounts while a request is pending, you should cancel that request. Otherwise, it might try to update state on an unmounted component, leading to errors or memory leaks.

class DataFetcherComponent {
  constructor() {
    this.abortController = null;
  }

  async loadData(query) {
    // If a previous request is still pending, cancel it first.
    if (this.abortController) {
      this.abortController.abort();
      console.log('Previous request cancelled.');
    }
    this.abortController = new AbortController();
    const signal = this.abortController.signal;

    try {
      const response = await fetch(`https://api.example.com/search?q=${query}`, { signal });
      const data = await response.json();
      console.log(`Results for '${query}':`, data);
    } catch (error) {
      if (error.name === 'AbortError') {
        console.log(`Fetch for '${query}' was aborted.`);
      } else {
        console.error(`Error fetching '${query}':`, error);
      }
    }
  }

  // Method to be called when the component is unmounted or destroyed
  cleanup() {
    if (this.abortController) {
      this.abortController.abort();
      this.abortController = null;
      console.log('Component cleanup: pending request cancelled.');
    }
  }
}

const component = new DataFetcherComponent();
component.loadData('initial search');

// Simulate a new search request after a short delay
setTimeout(() => component.loadData('another search'), 500);

// Simulate component unmount after some time
setTimeout(() => component.cleanup(), 2000);

Here:

The DataFetcherComponent maintains an abortController instance as part of its state.
Before initiating a new loadData request, it checks if an existing abortController is present. If so, it calls abort() on the old controller to cancel any pending request from a previous call.
A new AbortController is then created for the current request, ensuring each new operation gets its own cancellation mechanism.
The cleanup() method ensures that any outstanding requests are cancelled when the component is no longer needed, preventing potential issues.

Example 3: AbortSignal with Other Asynchronous Tasks

AbortSignal isn't limited to fetch. You can integrate it with setTimeout, addEventListener, or even custom Promise-based operations.

function delayWithCancellation(ms, signal) {
  return new Promise((resolve, reject) => {
    if (signal && signal.aborted) {
      reject(new DOMException('Aborted', 'AbortError'));
      return;
    }

    const timeoutId = setTimeout(() => {
      console.log(`Delayed for ${ms}ms.`);
      resolve(`Operation completed after ${ms}ms.`);
    }, ms);

    signal.addEventListener('abort', () => {
      clearTimeout(timeoutId);
      reject(new DOMException('Aborted by signal', 'AbortError'));
    }, { once: true });
  });
}

async function runCancellableDelay() {
  const controller = new AbortController();
  const signal = controller.signal;

  try {
    // Start a long delay
    const promise1 = delayWithCancellation(3000, signal);
    // Immediately try to cancel it after a short moment
    setTimeout(() => controller.abort(), 1000);

    const result = await promise1;
    console.log(result);
  } catch (error) {
    if (error.name === 'AbortError') {
      console.log('Delay was successfully cancelled:', error.message);
    } else {
      console.error('An unexpected error occurred:', error);
    }
  }
}

runCancellableDelay();

This example demonstrates:

A delayWithCancellation function that wraps setTimeout in a Promise, accepting an AbortSignal.
Inside the function, it first checks signal.aborted. If already aborted, it immediately rejects with an AbortError to prevent starting the operation.
An event listener is attached to the signal for the abort event. When abort() is called, this listener fires, clearing the setTimeout and rejecting the Promise with an AbortError.
The { once: true } option ensures the event listener is removed after it fires, preventing memory leaks.
The runCancellableDelay function showcases how to use this custom cancellable operation, demonstrating that AbortController can orchestrate complex async flows beyond just network requests.

Common Mistakes & Gotchas

Not checking signal.aborted early: For long-running synchronous or potentially synchronous tasks within an async function, check signal.aborted at strategic points. Simply passing the signal to fetch is not enough for custom logic; you need to actively listen or check the signal's state.
Handling AbortError improperly: Always check error.name === 'AbortError' in your catch blocks. An AbortError is usually an expected outcome of a cancellation, not a failure that needs to be retried or reported as an error to the user.
Over-reusing AbortController: An AbortController can only abort its signal once. If you need to perform multiple cancellable operations over time (e.g., sequential fetches), create a new AbortController for each logical group or operation you wish to independently control.
Forgetting to remove addEventListener: If you manually attach an abort event listener to a signal (as in Example 3), remember to remove it, especially if the signal is long-lived. Using { once: true } or removeEventListener is crucial to prevent memory leaks.

Conclusion

AbortController is an indispensable API for building robust, performant, and user-friendly JavaScript applications. By providing a clean, standard mechanism for cancelling asynchronous operations, it helps developers manage complex async flows, prevent race conditions, and ensure efficient resource utilization. Integrating AbortController into your async patterns will lead to more predictable and maintainable code.

Start experimenting with AbortController in your projects today. Your users (and your future self) will thank you for the improved stability and responsiveness.

Optimize Performance with Intersection Observer API

Manas Joshi — Mon, 30 Mar 2026 02:53:44 +0000

Traditional methods for detecting element visibility (like scroll event listeners combined with getBoundingClientRect()) are notoriously inefficient. They force the browser to re-layout the page repeatedly, leading to jank and poor user experience, especially on mobile devices. The Intersection Observer API offers a modern, performant solution to determine when an element enters or exits the viewport, or even intersects with another element. It allows developers to defer loading resources or trigger actions only when necessary, significantly improving web performance. This guide dives into how to effectively leverage Intersection Observer for common use cases like lazy loading and infinite scrolling.

Understanding the Core Concept

At its heart, the Intersection Observer API asynchronously observes changes in the intersection of a target element with an ancestor element or with the document's viewport (referred to as the "root"). Instead of constantly polling for changes, it only triggers a callback function when the intersection threshold is crossed.

Key concepts:

Target: The element you want to observe.
Root: The element that is the ancestor of the target, defining the viewport for intersection checking. If null or undefined, the document's viewport is used.
Root Margin: A margin around the root. This value defines how much larger or smaller the root's bounding box is before calculations. Similar to CSS margin properties (e.g., "10px 20px 30px 40px").
Thresholds: A single number or an array of numbers between 0.0 and 1.0, indicating at what percentage of the target's visibility the observer's callback should be executed. A value of 0.0 means the callback will fire as soon as a single pixel of the target element is visible. A value of 1.0 means the callback will fire when all of the target element is visible.

Basic Setup and Observation

Setting up an IntersectionObserver involves instantiating a new observer object and defining its callback function. This callback receives a list of IntersectionObserverEntry objects and the observer instance itself.

// 1. Define the callback function
const handleIntersection = (entries, observer) => {
  entries.forEach(entry => {
    // Each 'entry' describes an intersection change for one observed target
    if (entry.isIntersecting) {
      console.log('Element is now visible:', entry.target);
      // Optional: Stop observing once it's visible if it's a one-time action
      // observer.unobserve(entry.target);
    } else {
      console.log('Element is no longer visible:', entry.target);
    }
    console.log('Intersection ratio:', entry.intersectionRatio);
  });
};

// 2. Create an observer instance
// Options object is optional; defaults to viewport root, no root margin, threshold 0.0
const options = {
  root: null, // Use the document viewport as the root
  rootMargin: '0px', // No margin around the root
  threshold: 0.5 // Trigger when 50% of the target is visible
};

const observer = new IntersectionObserver(handleIntersection, options);

// 3. Select target elements and observe them
const targetElements = document.querySelectorAll('.observe-me');
targetElements.forEach(element => {
  observer.observe(element);
});

This code snippet first defines handleIntersection, a function that will be called whenever a target element's intersection status changes. It iterates through the entries array, checking entry.isIntersecting to determine if the element has entered or exited the root. Next, options are defined; here, root: null means the browser's viewport is the reference, and threshold: 0.5 means the callback fires when 50% of the target element becomes visible or invisible. Finally, an IntersectionObserver instance is created, and it starts observing all elements matching the .observe-me selector.

Real-world Use Case: Lazy Loading Images

A common and impactful use case is lazy loading images. Instead of loading all images on page load, which consumes bandwidth and impacts Initial Load time, we can load them only when they are about to enter the viewport.

<!-- Example HTML for lazy loading images -->
<img data-src="image1.jpg" alt="Image 1" class="lazy-image">
<img data-src="image2.jpg" alt="Image 2" class="lazy-image">
<img data-src="image3.jpg" alt="Image 3" class="lazy-image">
<!-- ... many more images ... -->

const lazyLoadImages = (entries, observer) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      const img = entry.target;
      const src = img.getAttribute('data-src');

      if (src) {
        img.setAttribute('src', src); // Set the actual src attribute
        img.removeAttribute('data-src'); // Remove data-src to prevent re-loading
        observer.unobserve(img); // Stop observing once loaded
      }
    }
  });
};

const imgOptions = {
  root: null, // Viewport
  rootMargin: '0px 0px 100px 0px', // Load images 100px before they enter the viewport
  threshold: 0 // As soon as any part is visible
};

const imageObserver = new IntersectionObserver(lazyLoadImages, imgOptions);

const imagesToLoad = document.querySelectorAll('.lazy-image');
imagesToLoad.forEach(image => {
  imageObserver.observe(image);
});

This JavaScript code targets all img elements with the class lazy-image and a data-src attribute. The lazyLoadImages callback checks if an image (entry.target) is isIntersecting. If it is, the data-src value is moved to the src attribute, effectively loading the image. Importantly, observer.unobserve(img) is called immediately after loading to prevent unnecessary future observations. The rootMargin: '0px 0px 100px 0px' in imgOptions pre-loads images when they are 100 pixels below the viewport, ensuring a smoother user experience as they scroll.

Real-world Use Case: Infinite Scrolling

Another powerful application is implementing infinite scrolling, where new content loads automatically as the user approaches the end of a page. This typically involves observing a "sentinel" element placed at the bottom of your content list.

// Assume 'contentContainer' is the parent of your dynamically loaded items
// and 'loadingIndicator' is an element at the bottom, initially hidden, acting as the sentinel.
const contentContainer = document.getElementById('content-list');
const loadingIndicator = document.getElementById('loading-spinner'); // Our sentinel

let page = 1; // Track current page for API requests
let isLoading = false; // Prevent multiple simultaneous loads

const loadMoreContent = async () => {
  if (isLoading) return;
  isLoading = true;
  console.log(`Loading page ${page}...`);

  // Simulate an API call
  try {
    const response = await fetch(`/api/items?page=${page}&limit=10`);
    const newItems = await response.json();

    newItems.forEach(item => {
      const div = document.createElement('div');
      div.textContent = `Item ${item.id} - from page ${item.page}`;
      contentContainer.appendChild(div);
    });

    page++;
  } catch (error) {
    console.error('Failed to load more content:', error);
  } finally {
    isLoading = false;
  }
};

const infiniteScrollObserver = new IntersectionObserver((entries, observer) => {
  entries.forEach(entry => {
    if (entry.isIntersecting && !isLoading) {
      // Sentinel is visible, load more content
      loadMoreContent();
    }
  });
}, {
  root: null, // Viewport
  rootMargin: '0px',
  threshold: 0.1 // Trigger when 10% of the sentinel is visible
});

// Start observing the loading indicator
infiniteScrollObserver.observe(loadingIndicator);

// Initial load (optional, or done via server-side rendering)
// loadMoreContent();

This example shows how to set up infinite scrolling. A loadingIndicator (often a spinner or simple div) acts as a sentinel. When this loadingIndicator enters the viewport (determined by entry.isIntersecting), the loadMoreContent function is triggered. This function simulates fetching new data, appends it to contentContainer, and increments the page counter. A isLoading flag is crucial to prevent multiple loadMoreContent calls while an API request is already in flight. The threshold: 0.1 means the observer fires as soon as 10% of the loadingIndicator is visible, giving enough time for new content to load before the user reaches the very bottom.

Common Mistakes and Gotchas

While powerful, Intersection Observer has its nuances:

Not Unobserving: For one-time actions like lazy loading an image, remember to call observer.unobserve(entry.target) after the action is complete. Failing to do so keeps the observer active, potentially triggering the callback multiple times unnecessarily.
Misunderstanding intersectionRatio vs. isIntersecting: isIntersecting is a boolean indicating if any part of the target is currently intersecting the root. intersectionRatio gives the percentage (0.0 to 1.0) of the target that is intersecting. For simple visibility checks, isIntersecting is often sufficient and clearer. Use intersectionRatio when you need finer control, e.g., triggering an event only when an element is fully visible (intersectionRatio === 1).
Over-optimizing threshold: Providing a large array of threshold values (e.g., [0, 0.1, 0.2, ..., 1.0]) will cause the callback to fire frequently. For many use cases, a single threshold value like 0 (any visibility) or 0.1 (10% visible) is sufficient and more performant.
Root Margin vs. Threshold: rootMargin expands or shrinks the root's bounding box before intersection calculations. This is useful for "pre-loading" or "pre-triggering" actions (like loading images 200px before they reach the viewport). threshold specifies what percentage of the target must be visible within the (potentially adjusted) root. Don't confuse their roles.
Observing Dynamically Added Elements: If you're adding elements to the DOM after the initial setup (e.g., for infinite scroll), remember to call observer.observe() on these new elements if they also need to be observed. For infinite scroll, typically you only observe the single sentinel element, not all the new items.

Key Takeaways

The Intersection Observer API is a fundamental tool for modern web development, offering a highly performant and efficient way to detect element visibility without blocking the main thread. By offloading intersection checks to the browser's optimized asynchronous mechanisms, it significantly reduces layout thrashing and improves responsiveness. Its declarative nature simplifies code for common patterns like lazy loading and infinite scrolling, making your applications faster and more user-friendly.

Conclusion

Mastering Intersection Observer is crucial for building high-performance web applications that provide a smooth and engaging user experience. By implementing the techniques discussed, you can dramatically improve your site's Core Web Vitals, particularly Largest Contentful Paint (LCP) and Cumulative Layout Shift (CLS), by loading resources intelligently. Start integrating Intersection Observer into your projects today and unlock a new level of web performance.

Mocking Fetch API Calls in Vitest for Reliable Tests

Manas Joshi — Sat, 28 Mar 2026 15:48:27 +0000

Master Mocking Fetch API Calls in Vitest

Testing asynchronous code, especially functions that interact with external services via network requests, is a critical part of building robust applications. However, allowing unit tests to make real network calls introduces several problems: they are slow, unreliable due to network flakiness, and introduce external dependencies, making your tests non-deterministic. This is where mocking comes in, allowing us to simulate network responses and keep our unit tests fast, isolated, and reliable.

In this guide, we'll dive deep into effectively mocking the native fetch API using Vitest, focusing on practical examples and common pitfalls. We'll ensure your data-fetching logic is thoroughly tested without ever hitting a real server.

The Challenge of `fetch` in Unit Tests

The fetch API is a global function available in browsers and Node.js (with an experimental flag or polyfill) that initiates network requests. When you write a unit test for a function that uses fetch, you want to test your function's logic—how it handles different responses, errors, and data transformations—not the fetch API itself or the remote server's uptime. Directly calling fetch in a unit test would attempt to contact a real URL, which is counterproductive for isolation and speed.

Vitest, a modern test runner, provides powerful mocking capabilities that allow us to intercept and control the behavior of functions and modules, including global objects like fetch.

Building a Data Service

Let's start with a simple JavaScript module that uses fetch to retrieve user data. This is the code we want to test.

// src/dataService.js
export async function fetchUserData(userId) {
  try {
    const response = await fetch(`https://api.example.com/users/${userId}`);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return await response.json();
  } catch (error) {
    console.error("Failed to fetch user data:", error);
    throw error;
  }
}

This fetchUserData function asynchronously retrieves data from a hypothetical API endpoint. It constructs the URL using the provided userId and uses the native fetch API to make the request. The function checks response.ok to determine if the HTTP status code is in the 200-299 range, throwing an error for non-successful responses. Finally, it parses the response body as JSON and handles any network or parsing errors.

Setting Up `fetch` Mocking with Vitest

To mock fetch, we'll replace the global fetch object with a Vitest mock function (vi.fn()). This gives us complete control over what fetch returns when called in our tests.

// __tests__/dataService.test.js
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { fetchUserData } from '../src/dataService';

// Create a Vitest mock function for fetch
const mockFetch = vi.fn();

// Assign the mock to the global fetch object
global.fetch = mockFetch;

describe('fetchUserData', () => {
  beforeEach(() => {
    // Clear any previous mock calls and implementations before each test
    mockFetch.mockClear();
  });

  // ... tests will be added here ...

  // Optionally, restore the original fetch after all tests if needed
  // afterAll(() => {
  //   vi.restoreAllMocks();
  // });
});

This block initializes the testing environment with Vitest, importing necessary utilities like describe, it, expect, and vi. A mock function, mockFetch, is created using vi.fn() and then directly assigned to global.fetch, effectively replacing the browser's native fetch API for all tests in this file. The beforeEach hook is crucial, as it calls mockFetch.mockClear() before every test, ensuring that call counts and mock implementations are reset, preventing state leakage between tests.

Writing Tests for Different Scenarios

Now, let's write tests that cover successful data fetching, HTTP errors, and network failures. We'll use mockResolvedValueOnce and mockRejectedValueOnce to control the mock fetch behavior for individual test cases.

// __tests__/dataService.test.js (continued)
// ... (previous setup)

describe('fetchUserData', () => {
  beforeEach(() => {
    mockFetch.mockClear();
  });

  it('should fetch user data successfully', async () => {
    const mockUser = { id: 1, name: 'John Doe' };
    // Simulate a successful fetch response
    mockFetch.mockResolvedValueOnce({
      ok: true,
      status: 200,
      json: () => Promise.resolve(mockUser),
    });

    const userData = await fetchUserData(1);

    expect(mockFetch).toHaveBeenCalledTimes(1);
    expect(mockFetch).toHaveBeenCalledWith('https://api.example.com/users/1');
    expect(userData).toEqual(mockUser);
  });

  it('should handle API errors gracefully', async () => {
    // Simulate an HTTP 404 Not Found error
    mockFetch.mockResolvedValueOnce({
      ok: false,
      status: 404,
      json: () => Promise.resolve({ message: 'Not Found' }),
    });

    await expect(fetchUserData(2)).rejects.toThrow('HTTP error! status: 404');
    expect(mockFetch).toHaveBeenCalledTimes(1);
    expect(mockFetch).toHaveBeenCalledWith('https://api.example.com/users/2');
  });

  it('should handle network failures', async () => {
    const networkError = new TypeError('Failed to fetch');
    // Simulate a network-level error (e.g., no internet connection)
    mockFetch.mockRejectedValueOnce(networkError);

    await expect(fetchUserData(3)).rejects.toThrow(networkError);
    expect(mockFetch).toHaveBeenCalledTimes(1);
    expect(mockFetch).toHaveBeenCalledWith('https://api.example.com/users/3');
  });
});

These tests meticulously cover different fetch scenarios. The first it block demonstrates a successful data retrieval by configuring mockFetch.mockResolvedValueOnce to return a mock Response object, complete with ok: true and a json method. The subsequent assertions verify that fetch was called exactly once with the correct URL and that the fetchUserData function returned the expected mock data. The second and third it blocks handle error conditions: one simulates an HTTP 404 error by setting ok: false and the other a network failure using mockRejectedValueOnce, both asserting that fetchUserData rejects with the appropriate error.

Common Mistakes and Gotchas

When mocking fetch (or any global object), there are several common pitfalls to avoid:

Not Resetting Mocks: Forgetting to call mockClear() (or mockReset()/mockRestore()) between tests is a frequent source of test flakiness. If a mock's call count or implementation from a previous test persists, it can lead to unexpected behavior in subsequent tests. Always ensure your beforeEach hooks handle proper mock isolation.
Incorrect Response Object Structure: The fetch API returns a Promise that resolves to a Response object. A common mistake is to mock fetch to directly return data (e.g., mockFetch.mockResolvedValueOnce(mockUser)). This is incorrect because the consuming code expects a Response object with properties like ok, status, and methods like json() or text(). Your mock must simulate this structure accurately, as shown in the examples, by having json: () => Promise.resolve(mockData).
Mocking Too Late: Ensure that global.fetch = mockFetch; is executed before any code that calls fetch within your test files. If the original fetch is accessed before your mock replaces it, your tests will still make real network requests.
Confusing mockResolvedValue with mockResolvedValueOnce: Use mockResolvedValueOnce when you want the mock to return a specific value for a single subsequent call and then revert to its default behavior (or the next Once value). If you use mockResolvedValue, the mock will always return that value for all subsequent calls until explicitly cleared or overridden, which might not be what you intend for different test cases.

Key Takeaways

Mocking the fetch API in Vitest is essential for writing isolated, fast, and reliable unit tests for your data-fetching logic. By replacing the global fetch with a controlled mock, you can:

Prevent real network requests: Isolate your code from external dependencies.
Control API responses: Easily simulate success, various HTTP errors, and network failures.
Speed up tests: Eliminate the latency of actual network calls.
Increase test determinism: Ensure tests always behave the same way, regardless of network conditions or server state.

Conclusion

Integrating fetch mocking into your Vitest workflow is a fundamental skill for any developer working with modern JavaScript applications. By mastering vi.fn(), global.fetch assignments, and the careful construction of mock Response objects, you empower yourself to write comprehensive tests that give you confidence in your application's data-handling capabilities. Start applying these techniques today to elevate the quality and reliability of your codebase.

Vite Environment Variables: Master .env & import.meta.env

Manas Joshi — Fri, 27 Mar 2026 11:13:39 +0000

Managing environment-specific configurations like API endpoints, feature flags, or secret keys is a fundamental challenge in frontend development. Hardcoding these values directly into your codebase is unsustainable, insecure, and error-prone when deploying to different environments. Vite, a modern and fast build tool, provides a streamlined and explicit way to handle environment variables, offering clarity and security for different deployment targets.

This guide dives into Vite's specific mechanisms for managing environment variables, moving beyond a simple overview to practical application with code examples, focusing on how and why these approaches work. We'll explore import.meta.env, .env files, and the concept of 'modes'.

Core Concept: Vite's Approach to Environment Variables

Vite's approach to environment variables differs significantly from traditional Node.js-based setups. While Node.js applications often rely on process.env, Vite applications primarily use import.meta.env within client-side code. This distinction is crucial because Vite performs a static replacement during the build process for variables prefixed with VITE_, making them available in your bundled frontend code.

Variables without the VITE_ prefix are not exposed to the client bundle. They are only accessible within the Vite config file (vite.config.js) or during Node.js server-side operations (e.g., custom Vite plugins or SSR setups). This mechanism helps prevent accidental exposure of sensitive information.

Defining Environment Variables with `.env` Files

To manage variables, Vite leverages .env files, similar to the popular dotenv library. These files are loaded based on the mode your application is running in. The mode is a string that indicates the environment, typically 'development' (for vite or vite dev) or 'production' (for vite build).

Vite provides a hierarchy for .env files:

.env: General defaults.
.env.local: Local overrides, ignored by Git.
.env.[mode]: Mode-specific overrides (e.g., .env.development, .env.production).
.env.[mode].local: Local, mode-specific overrides, ignored by Git.

Let's set up a common scenario with three files:

.env             # General defaults
.env.development # Overrides for development mode
.env.production  # Overrides for production mode

Here's an example of their content:

./.env

VITE_APP_NAME="My Awesome App"
VITE_API_BASE_URL="https://api.example.com/v1"
SECRET_API_KEY="this-should-not-be-exposed" # Not prefixed, thus not exposed to client

./.env.development

VITE_API_BASE_URL="http://localhost:3001/api/v1"

./.env.production

VITE_API_BASE_URL="https://prod-api.example.com/v1"

Explanation: In these files, we define key-value pairs. Variables prefixed with VITE_ (e.g., VITE_APP_NAME, VITE_API_BASE_URL) will be exposed to your client-side code via import.meta.env. Variables without this prefix (like SECRET_API_KEY) are not exposed to the client, making them suitable for server-side configurations or within vite.config.js. Vite automatically loads .env files based on the current mode, with .env.[mode] taking precedence over the generic .env.

Accessing Variables in Your Application

Within your frontend JavaScript or TypeScript code, you access these environment variables through the special import.meta.env object. This object is populated by Vite during the build or development server startup.

// src/main.js or src/App.vue

// Accessing custom environment variables
console.log("App Name:", import.meta.env.VITE_APP_NAME);
console.log("API Base URL:", import.meta.env.VITE_API_BASE_URL);

// Vite also exposes built-in environment flags
if (import.meta.env.DEV) {
  console.log("Running in development mode");
} else if (import.meta.env.PROD) {
  console.log("Running in production mode");
}

// Accessing the current mode string
console.log("Current Mode:", import.meta.env.MODE);

// Attempting to access an unprefixed variable will result in 'undefined'
console.log("Secret API Key (should be undefined):", import.meta.env.SECRET_API_KEY);

const element = document.getElementById('app-info');
if (element) {
  element.textContent = `App: ${import.meta.env.VITE_APP_NAME}, API: ${import.meta.env.VITE_API_BASE_URL}`;
}

Explanation: import.meta.env is a special object that Vite populates with your environment variables. VITE_APP_NAME and VITE_API_BASE_URL are successfully logged, reflecting the values from the appropriate .env file for the active mode. Vite also provides useful boolean flags like DEV and PROD to conditionally execute code based on the current environment, eliminating the need to manually parse NODE_ENV. Note that import.meta.env.SECRET_API_KEY correctly returns undefined, preventing accidental exposure of sensitive data to the client, reinforcing the importance of the VITE_ prefix.

Running with Different Modes and Customizing Build Behavior

Vite commands inherently use a mode. When you run vite (or vite dev), it defaults to development mode. When you run vite build, it defaults to production mode. You can explicitly specify a mode using the --mode CLI flag.

This is particularly useful for environments like staging or test, which require their own distinct configurations without being 'development' or 'production'.

Let's add a build:staging script to package.json and a corresponding .env.staging file:

package.json

{
  "name": "vite-env-example",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "build:staging": "vite build --mode staging",
    "dev:staging": "vite --mode staging"
  }
}

Now, create the ./.env.staging file:

./.env.staging

VITE_API_BASE_URL="https://staging-api.example.com/v1"
VITE_APP_ENVIRONMENT="staging"

Explanation: The scripts section in package.json demonstrates how to use the --mode flag. npm run dev:staging will start the development server using staging mode, causing Vite to load variables from .env.staging (and then .env). Similarly, npm run build:staging will create a production build configured specifically for the staging environment. This explicit mode control allows for distinct configurations tailored to various deployment pipelines without altering your core application code.

Common Mistakes / Gotchas

Forgetting VITE_ prefix: This is the most common mistake. Only variables prefixed with VITE_ are exposed to your client-side code via import.meta.env. Variables like API_KEY=123 will not be accessible in your components. If you need to access non-prefixed variables, they are typically for vite.config.js or server-side scripts.
Using process.env: This is a common habit from Node.js development. In a Vite frontend application, process.env is not available at runtime in the browser. Always use import.meta.env for client-side variables.
Exposing Sensitive Information: Even with the VITE_ prefix, remember that any variable exposed via import.meta.env is eventually bundled into your client-side JavaScript. This means it's publicly visible if someone inspects your deployed code. Never put truly sensitive information (like private API keys, database credentials) directly into .env files that will be used for client-side builds. Instead, use a backend proxy or server-side logic to handle such secrets securely.
Understanding mode vs. NODE_ENV: While import.meta.env.MODE reflects the current mode (e.g., 'development', 'production', 'staging'), import.meta.env.DEV and import.meta.env.PROD are specific boolean flags Vite provides. NODE_ENV is not directly used by Vite for mode resolution but might be present as a fallback from other tools. Always rely on import.meta.env.MODE, import.meta.env.DEV, import.meta.env.PROD for consistency within Vite.

Key Takeaways

Vite uses import.meta.env for client-side environment variables, not process.env.
Variables must be prefixed with VITE_ to be exposed to the client bundle.
.env files (e.g., .env, .env.development, .env.production, .env.[mode]) allow for environment-specific configuration.
The --mode CLI flag explicitly controls which .env files Vite loads for development or build processes.
Never expose truly sensitive secrets directly to the client bundle; use a backend or server-side rendering for true privacy.

Conclusion

Effectively managing environment variables is crucial for building robust and adaptable frontend applications. Vite's clear and explicit mechanism, leveraging import.meta.env and mode-specific .env files, simplifies this process significantly. By understanding these conventions and avoiding common pitfalls, you can ensure your application behaves predictably across development, staging, and production environments, enhancing both security and developer experience. Implement these practices today to streamline your configuration workflow and enhance your application's deployment reliability.

Integrate Custom Tools with OpenAI Function Calling

Manas Joshi — Thu, 26 Mar 2026 14:11:26 +0000

Large Language Models (LLMs) are incredibly powerful for generating text, summarizing information, and answering questions. However, their knowledge is typically limited to their training data. To perform real-world actions like checking the weather, sending emails, or querying a database, LLMs need to interact with external tools. This is where "function calling" or "tool use" becomes essential. It’s the mechanism that allows an LLM to not just generate text, but to intelligently decide when and how to invoke external functions, transforming it from a text generator into a capable agent.

In this guide, we'll dive into OpenAI's Function Calling feature, a robust way to connect your LLM applications with custom tools and APIs. We'll explore the core concepts, walk through practical Python code examples, and discuss common pitfalls to help you build more dynamic and powerful AI-driven applications.

Understanding OpenAI Function Calling

OpenAI Function Calling empowers models like gpt-4o to detect when a user's prompt might require an external function call, generate the necessary arguments for that call, and present this structured information back to your application. Your application then executes the function and feeds the result back to the LLM, allowing it to complete the user's request with up-to-date, real-world data or perform specific actions.

This isn't the LLM executing code directly. Instead, it acts as a smart orchestrator:

You describe your tools: You provide the LLM with a JSON Schema definition of functions it can "call" (their names, descriptions, and expected parameters).
User prompt: A user asks a question or makes a request.
LLM decides: The LLM analyzes the prompt, compares it against the available tool descriptions, and decides if a tool is needed.
LLM generates tool call: If a tool is needed, the LLM generates a structured JSON object containing the tool's name and the arguments it inferred from the user's prompt.
Your application executes: Your code receives this JSON, calls your actual Python function (or external API) with the provided arguments.
Tool output is returned: The result of your function call is then sent back to the LLM.
LLM synthesizes response: The LLM uses this real-world data to formulate a natural language response to the user.

Let's illustrate this with a common example: fetching current weather information.

Step 1: Describing Your Tools to the LLM

The first crucial step is to define the capabilities of your external tools in a way the LLM can understand. OpenAI uses a JSON Schema-like structure for this. Each tool needs a descriptive name, a clear description (this is key for the LLM's understanding), and a parameters object detailing the inputs it expects.

Consider a simple get_current_weather function that takes a location and an optional unit.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
        },
    }
]

This Python list defines a single tool. The type is specified as "function", indicating it's a callable operation. Within the function object, we provide a name (get_current_weather) that your actual code will use, and a description that the LLM reads to understand the tool's purpose. The parameters field, written in JSON Schema format, details the expected inputs: location as a required string and unit as an optional string that must be either "celsius" or "fahrenheit".

Step 2: Triggering a Function Call from the LLM

Now that our tool is defined, we can pass it to the OpenAI API when making a chat completion request. The tool_choice parameter gives you control over whether the model should use a tool, always use a specific tool, or never use one. Setting it to "auto" (the default) lets the LLM decide.

from openai import OpenAI
import json # Used for parsing arguments later

client = OpenAI()

messages = [{"role": "user", "content": "What's the weather like in Boston?"}]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools, # Our defined tools
    tool_choice="auto", # Let the model decide if a tool is needed
)
response_message = response.choices[0].message

# Check if the model decided to call a tool
if response_message.tool_calls:
    tool_call = response_message.tool_calls[0] # Assuming one tool call for simplicity
    print(f"LLM wants to call a tool: {tool_call.function.name}")
    print(f"Arguments: {tool_call.function.arguments}")
else:
    print("LLM responded directly:", response_message.content)

In this snippet, we initialize the OpenAI client and prepare a list of messages containing the user's query. The core of this step is the call to client.chat.completions.create. We pass our messages, specify a model (gpt-4o is good for function calling), and crucially, include our tools definition. tool_choice="auto" instructs the model to automatically determine if a function call is appropriate. The response_message then holds the model's decision; if response_message.tool_calls is populated, it means the LLM has generated a call to one of our defined tools, providing the function name and its parsed arguments as a JSON string.

Step 3: Executing the Tool and Sending Results Back

Receiving a tool_calls object means your application now needs to execute the identified function. This involves parsing the arguments provided by the LLM, calling your actual local function, and then sending the result back to the LLM to complete the conversation.

# Mock tool function (in a real application, this would query a weather API, database, etc.)
def get_current_weather(location, unit="fahrenheit"):
    # Simplified logic for demonstration
    if "boston" in location.lower():
        return json.dumps({"location": location, "temperature": "65", "unit": unit, "forecast": "partly cloudy"})
    elif "new york" in location.lower():
        return json.dumps({"location": location, "temperature": "72", "unit": unit, "forecast": "sunny"})
    return json.dumps({"location": location, "temperature": "unknown", "unit": unit, "forecast": "unavailable"})

# --- Continuation from Step 2, assuming response_message.tool_calls exists ---
if response_message.tool_calls:
    tool_call = response_message.tool_calls[0]
    function_name = tool_call.function.name
    function_args = json.loads(tool_call.function.arguments) # Parse the JSON string into a Python dict

    # Execute the function based on its name
    if function_name == "get_current_weather":
        function_response = get_current_weather(**function_args) # Unpack arguments with **

        # Append both the LLM's tool call and the tool's output to the messages history
        messages.append(response_message) # The model's request to call the tool
        messages.append(
            {
                "tool_call_id": tool_call.id,
                "role": "tool",
                "name": function_name,
                "content": function_response, # The actual result from our function
            }
        )

        # Send the updated messages back to the LLM to get a final, human-readable response
        second_response = client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
        )
        print("Final LLM response:", second_response.choices[0].message.content)
    else:
        print(f"Error: Unknown function requested: {function_name}")
else:
    # This case would be handled by the direct response logic in Step 2
    pass

This expanded block handles the actual execution. We define a placeholder get_current_weather function that simulates an API call. After receiving the LLM's tool_call, we parse its arguments (which are a JSON string) into a Python dictionary using json.loads(). We then dynamically call our get_current_weather function, unpacking the arguments using **function_args. Crucially, we append two new messages to our messages history: first, the response_message from the LLM (which contained the tool_calls), and second, a new message with role="tool". This tool message includes the tool_call_id (linking it back to the original call), the function name, and the content which is the actual output from our get_current_weather function. Finally, we make a second API call to client.chat.completions.create with this updated message history, allowing the LLM to synthesize a natural language response based on the tool's output.

Common Mistakes and Gotchas

Working with Function Calling, while powerful, can introduce specific challenges:

Incorrect Schema Definition: The description of your tool and its parameters are vital. If they are vague or misleading, the LLM might struggle to correctly identify when to call your tool or how to map user input to its arguments. Ensure required parameters are correctly marked.
Forgetting to Send Tool Output: A common oversight is to call the tool but not feed its results back into the LLM's messages history. Without the role="tool" message, the LLM won't know the outcome of its requested action and cannot complete the user's request contextually.
Infinite Loops: In more complex scenarios, an LLM might continuously request the same tool if the tool's output doesn't provide enough information or resolve the initial query. Ensure your tool outputs are comprehensive, and consider adding retry limits or human intervention points.
Security Implications: Since your application executes the functions, be extremely cautious about what functions you expose and how you handle their arguments. Malicious prompts could potentially lead to unexpected function calls or data exposure if not properly validated. Always sanitize and validate inputs before executing actions.
Over-reliance on tool_choice="auto": While convenient, auto might not always pick the desired tool or might pick one when a direct response is better. For critical flows, consider explicit tool_choice values, e.g., {"type": "function", "function": {"name": "my_specific_tool"}}, or none to force a direct textual response.

Key Takeaways

OpenAI Function Calling fundamentally shifts how we interact with LLMs, moving beyond simple text generation to building truly intelligent, agentic systems. By providing a clear contract for your external tools through JSON Schema, you enable LLMs to:

Perform real-world actions: Interact with APIs, databases, or local services.
Access up-to-date information: Overcome knowledge cutoffs by fetching current data.
Improve user experience: Provide more accurate and actionable responses.

This pattern is a cornerstone for building sophisticated AI assistants, task automation agents, and advanced chatbots that can understand user intent and execute complex workflows.

Conclusion: Build Smarter, Not Harder

Integrating custom tools with LLMs via function calling unlocks a new dimension of possibilities for developers. It's a critical pattern for extending the capabilities of models beyond their inherent knowledge, turning them into versatile problem-solvers. The ability to dynamically connect LLMs to your existing backend services means you can create applications that are not just conversational, but genuinely functional and integrated.

Start experimenting with OpenAI Function Calling in your projects today. Define a simple tool, feed it to the model, and observe how your LLM begins to intelligently orchestrate actions. The future of AI applications lies in these powerful integrations.

Optimizing React State Updates with useDeferredValue

Manas Joshi — Wed, 25 Mar 2026 11:50:56 +0000

Optimizing React State Updates with useDeferredValue

Modern web applications demand snappy, responsive user interfaces. However, even in React, frequent state updates, especially those leading to expensive re-renders or complex calculations, can quickly degrade the user experience. Imagine a search bar for a large dataset: if every keystroke triggers a full re-render of the list, the UI can become sluggish, feel "sticky," or even freeze momentarily. This is a common performance bottleneck where the main thread is busy processing updates, preventing it from handling user interactions smoothly.

The useDeferredValue hook is React's answer to this challenge. It provides a way to "defer" updates to a value, allowing the UI to remain responsive by prioritizing urgent updates while non-urgent updates are rendered in the background. It's a powerful tool for intermediate React developers looking to fine-tune their application's perceived performance and responsiveness.

Understanding Concurrent React and Transitions

To fully appreciate useDeferredValue, it's crucial to understand Concurrent React. Traditional React renders updates synchronously: once an update begins, it cannot be interrupted. This "all or nothing" approach means if an update is computationally intensive, the UI will be blocked until it completes.

Concurrent React introduces the ability for React to work on multiple updates concurrently. This doesn't mean parallel execution on different CPU cores, but rather that React can pause, resume, or even abandon rendering work. This non-blocking behavior is key to maintaining UI responsiveness.

Within this concurrent model, React introduces the concept of transitions. A transition marks a set of state updates as non-urgent. When you update state within a transition, React understands that these updates can be interrupted if a more urgent user interaction (like typing in an input field or clicking a button) occurs. This allows React to prioritize user feedback, ensuring the UI remains interactive.

useDeferredValue is a special kind of hook that leverages this transition mechanism internally. It signals to React that the value it produces can be deferred, essentially turning its updates into a low-priority transition, allowing urgent updates to take precedence.

How useDeferredValue Works

The useDeferredValue hook's API is simple:

const deferredValue = useDeferredValue(value);

It takes a value and returns a "deferred" version of that value. The magic happens when the value changes. When the input value updates, useDeferredValue doesn't immediately return the new value. Instead, it holds onto the previous value for a short period, allowing React to first render any urgent updates (like updating an input field). Only after urgent updates have been processed and the main thread is free, React will then update deferredValue to reflect the latest input value, triggering a non-urgent re-render with the deferred state.

Let's contrast this with useState:

useState: When setMyState(newValue) is called, myState immediately becomes newValue in the next render cycle, triggering a potentially expensive update that blocks the UI.
useDeferredValue: When value changes, deferredValue initially retains its old value. React prioritizes rendering the immediate changes (e.g., the input field update). In the background, React will schedule a separate, lower-priority render to update deferredValue to the new value, ensuring the UI remains interactive.

This subtle difference is crucial. useDeferredValue essentially provides a "stale" version of your data for a brief period, enabling a smoother user experience during computationally intensive operations.

Practical Example: Filtering a Large List

Let's illustrate the benefits with a common scenario: filtering a large list of items based on a user's search input.

Before `useDeferredValue`

Without useDeferredValue, every keystroke immediately triggers a re-render of the potentially large filtered list, leading to jank.

import React, { useState, useMemo } from 'react';

const generateLargeList = (size) => {
  return Array.from({ length: size }, (_, i) => ({
    id: i,
    name: `Item ${i}`,
    description: `This is item number ${i} with some descriptive text.`,
  }));
};

const ALL_ITEMS = generateLargeList(10000); // 10,000 items

function FilteredListStandard() {
  const [searchTerm, setSearchTerm] = useState('');

  const filteredItems = useMemo(() => {
    console.log('Calculating filtered items (standard)');
    if (!searchTerm) {
      return ALL_ITEMS;
    }
    return ALL_ITEMS.filter(item =>
      item.name.toLowerCase().includes(searchTerm.toLowerCase()) ||
      item.description.toLowerCase().includes(searchTerm.toLowerCase())
    );
  }, [searchTerm]);

  const handleChange = (e) => {
    setSearchTerm(e.target.value);
  };

  return (
    <div>
      <h1>Standard Search Filter</h1>
      <input
        type="text"
        placeholder="Search items..."
        value={searchTerm}
        onChange={handleChange}
        style={{ width: '100%', padding: '8px', marginBottom: '16px' }}
      />
      <div style={{ maxHeight: '400px', overflowY: 'auto', border: '1px solid #ccc', padding: '8px' }}>
        {filteredItems.map(item => (
          <div key={item.id} style={{ padding: '4px 0', borderBottom: '1px dotted #eee' }}>
            <strong>{item.name}</strong> - {item.description.substring(0, 50)}...
          </div>
        ))}
        {filteredItems.length === 0 && <p>No items found.</p>}
      </div>
    </div>
  );
}

export default FilteredListStandard;

Try typing quickly into the search box with this component. You'll likely notice a noticeable lag between your keystrokes and the characters appearing in the input, especially on less powerful machines, because the expensive useMemo calculation blocks the UI.

After `useDeferredValue`

Now, let's introduce useDeferredValue to defer the filtering logic.

import React, { useState, useMemo, useDeferredValue } from 'react';

const generateLargeList = (size) => {
  return Array.from({ length: size }, (_, i) => ({
    id: i,
    name: `Item ${i}`,
    description: `This is item number ${i} with some descriptive text.`,
  }));
};

const ALL_ITEMS = generateLargeList(10000); // 10,000 items

function FilteredListDeferred() {
  const [searchTerm, setSearchTerm] = useState('');
  const deferredSearchTerm = useDeferredValue(searchTerm); // Defer this value!

  const filteredItems = useMemo(() => {
    // This expensive calculation now depends on the DEFERRED search term
    console.log('Calculating filtered items (deferred)');
    if (!deferredSearchTerm) {
      return ALL_ITEMS;
    }
    return ALL_ITEMS.filter(item =>
      item.name.toLowerCase().includes(deferredSearchTerm.toLowerCase()) ||
      item.description.toLowerCase().includes(deferredSearchTerm.toLowerCase())
    );
  }, [deferredSearchTerm]); // Only re-run when deferredSearchTerm updates

  const handleChange = (e) => {
    setSearchTerm(e.target.value);
  };

  return (
    <div>
      <h1>Deferred Search Filter</h1>
      <input
        type="text"
        placeholder="Search items..."
        value={searchTerm} // Input always reflects the immediate searchTerm
        onChange={handleChange}
        style={{ width: '100%', padding: '8px', marginBottom: '16px' }}
      />
      {searchTerm !== deferredSearchTerm && (
        <p style={{ color: 'gray' }}>Updating results...</p>
      )}
      <div style={{ maxHeight: '400px', overflowY: 'auto', border: '1px solid #ccc', padding: '8px' }}>
        {filteredItems.map(item => (
          <div key={item.id} style={{ padding: '4px 0', borderBottom: '1px dotted #eee' }}>
            <strong>{item.name}</strong> - {item.description.substring(0, 50)}...
          </div>
        ))}
        {filteredItems.length === 0 && <p>No items found.</p>}
      </div>
    </div>
  );
}

export default FilteredListDeferred;

In this deferred version, the input field (<input value={searchTerm} />) updates immediately because searchTerm is the urgent value. The expensive useMemo calculation, however, depends on deferredSearchTerm. This means that while you're typing quickly, the input updates responsively, and the list of filtered items (which uses deferredSearchTerm) updates slightly later in a non-blocking fashion. The UI feels much smoother. The Updating results... message is a neat way to show that the list is "catching up" to the input.

When to Use (and Not Use) useDeferredValue

Ideal Use Cases:

Search/Filter Inputs with Large Datasets: As shown in the example, this is a prime candidate. It ensures the input remains responsive while the heavy filtering happens in the background.
Complex Charting Libraries: If changing a chart's data prop triggers a re-render of many SVG elements or canvas operations, deferring the data update can keep the rest of the UI interactive.
Expensive Calculations/Transformations: Any time an input value leads to a computationally intensive operation (e.g., image processing, data aggregation, complex animations), useDeferredValue can improve responsiveness.
Real-time Previews: For content editors or design tools where a change in an input triggers an expensive preview render, deferring the preview update allows immediate feedback on the input field itself.

When Not to Use or Exercise Caution:

Values critical for immediate user feedback: If a value must be up-to-date instantly for correct UI behavior (e.g., a "save" button's disabled state that must reflect the latest form validity), do not defer it.
Data fetching (mostly): While you could defer a query parameter, often you want immediate feedback for data fetching (e.g., showing a loading spinner immediately). useTransition might be more appropriate here for explicitly marking the network request as a transition, providing more control.
Simple, inexpensive updates: For trivial updates that don't cause any performance issues, useDeferredValue adds unnecessary complexity and overhead.
When dealing with external systems that expect immediate values: If the deferred value is passed to a non-React library or API that expects the latest state, using a deferred value might lead to unexpected behavior or out-of-sync states.

Best Practices and Potential Pitfalls

Best Practices:

Pair with useMemo or useCallback: As seen in the example, useDeferredValue is most effective when the deferred value is then used as a dependency for useMemo or useCallback to memoize the expensive computation. This ensures the expensive work only re-runs when the deferred value changes.
Provide Visual Cues: When a value is deferred, there's a temporary discrepancy between the "immediate" state (e.g., the input value) and the "deferred" state (e.g., the filtered list). Consider adding visual indicators like a subtle loading spinner, a "Updating results..." message, or dimming the deferred content to inform the user that an update is in progress.
Understand "Stale" Data: Remember that useDeferredValue intentionally provides a stale value for a short period. Ensure your UI can gracefully handle this temporary inconsistency.
Test on Various Devices: What feels smooth on a high-end development machine might still be janky on an older mobile device. Always test your deferred components across different hardware to ensure the desired performance improvement.

Gotchas / Common Mistakes:

Overuse: Don't defer every state update. Only use it for values that genuinely trigger expensive, non-urgent operations. Overusing it can lead to a consistently "stale" feeling UI without a tangible performance benefit.
Forgetting Memoization: If you defer a value but then use it in an expensive calculation without useMemo, that calculation might still run on every keystroke if other props change, negating some of the benefits. Ensure your expensive logic is properly memoized against the deferred value.
Not understanding the "double render": useDeferredValue can lead to two renders: one with the immediate value and one with the deferred value. While React optimizes this, it's important to be aware that your components might render twice in quick succession for a single input change. Avoid side effects in render that are not idempotent.
Confusing with Debouncing/Throttling: While useDeferredValue shares some goals with debouncing/throttling (reducing the frequency of expensive operations), it operates at a fundamentally different level. Debouncing/throttling delay when the event handler fires; useDeferredValue allows the event handler to fire immediately but defers the rendering consequence. They can even be used together if desired, but useDeferredValue often provides a more integrated and "React-native" feel.

Conclusion

useDeferredValue is a powerful addition to React's Concurrent Mode capabilities, empowering developers to build significantly more responsive and user-friendly applications, especially when dealing with frequent, expensive UI updates. By intelligently deferring non-urgent rendering, it keeps the main thread free to handle critical user interactions, leading to a smoother perceived performance. Employ it thoughtfully for computationally intensive scenarios, always keeping user experience and potential "staleness" in mind, to unlock the full potential of Concurrent React.

TypeScript Discriminated Unions: Advanced Type Narrowing

Manas Joshi — Tue, 24 Mar 2026 08:50:29 +0000

TypeScript Discriminated Unions: Advanced Type Narrowing

Handling data that can take multiple distinct shapes is a common challenge in application development. Whether it's different event types, varied API responses, or distinct UI states, ensuring type safety when working with these variations can become complex. TypeScript's discriminated unions provide a powerful and elegant solution, allowing you to narrow down types based on a shared literal property.

This technique combines union types with a special kind of type guard: a property common to all members of the union, but with a different literal type in each member. This shared literal property is known as the "discriminant," and TypeScript uses it to infer the specific type within the union, enabling precise type narrowing.

Understanding the Core Concept

At its heart, a discriminated union is a union of types (usually interfaces or type aliases) that share a common field, and that common field has a string literal type (or sometimes a number or boolean literal type). When you check the value of this common field, TypeScript becomes smart enough to know which specific type from the union you're dealing with.

Consider an application that processes various user actions. Each action might have different associated data, but they all share an actionType property.

interface CreateUserAction {
  actionType: "CREATE_USER";
  payload: { name: string; email: string; };
}

interface DeleteUserAction {
  actionType: "DELETE_USER";
  payload: { userId: string; };
}

interface UpdateUserAction {
  actionType: "UPDATE_USER";
  payload: { userId: string; newEmail?: string; newName?: string; };
}

type UserAction = CreateUserAction | DeleteUserAction | UpdateUserAction;

function handleUserAction(action: UserAction) {
  switch (action.actionType) {
    case "CREATE_USER":
      console.log(`Creating user: ${action.payload.name} (${action.payload.email})`);
      // TypeScript knows 'action' is CreateUserAction here
      break;
    case "DELETE_USER":
      console.log(`Deleting user with ID: ${action.payload.userId}`);
      // TypeScript knows 'action' is DeleteUserAction here
      break;
    case "UPDATE_USER":
      console.log(`Updating user with ID: ${action.payload.userId}`);
      // TypeScript knows 'action' is UpdateUserAction here
      if (action.payload.newName) {
        console.log(`New name: ${action.payload.newName}`);
      }
      if (action.payload.newEmail) {
        console.log(`New email: ${action.payload.newEmail}`);
      }
      break;
    default:
      // We'll explore exhaustiveness checking next
      break;
  }
}

In this example:

We define three interfaces: CreateUserAction, DeleteUserAction, and UpdateUserAction. Each represents a distinct user action.
Crucially, each interface has an actionType property with a unique string literal type (e.g., "CREATE_USER"). This is our discriminant.
UserAction is a union type combining these three interfaces.
Inside the handleUserAction function, when we use a switch statement on action.actionType, TypeScript automatically narrows the type of action within each case block. For instance, in the "CREATE_USER" case, action is guaranteed to be a CreateUserAction, giving us access to action.payload.name and action.payload.email without type assertions.

Leveraging Generics with Discriminated Unions

Discriminated unions become even more powerful when combined with generics, especially in scenarios like handling generic API responses where the data payload can vary significantly based on the response status.

interface SuccessResponse<T> {
  status: "success";
  data: T;
}

interface ErrorResponse {
  status: "error";
  message: string;
  code?: number;
}

type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;

async function fetchData<T>(url: string): Promise<ApiResponse<T>> {
  const response = await fetch(url);
  if (!response.ok) {
    const errorData = await response.json();
    return { status: "error", message: errorData.message || "Unknown error" };
  }
  const data: T = await response.json();
  return { status: "success", data };
}

interface UserProfile {
  id: string;
  username: string;
  lastLogin: string;
}

async function getUserProfile(userId: string) {
  const result = await fetchData<UserProfile>(`/api/users/${userId}`);

  if (result.status === "success") {
    // TypeScript knows 'result' is SuccessResponse<UserProfile>
    console.log(`User ${result.data.username} last logged in: ${result.data.lastLogin}`);
    return result.data;
  } else {
    // TypeScript knows 'result' is ErrorResponse
    console.error(`Failed to fetch user profile: ${result.message}`);
    return null;
  }
}

Here's how this works:

SuccessResponse<T> is a generic interface. It has a status property with the literal type "success" and a generic data property of type T.
ErrorResponse is a non-generic interface for error cases, with status: "error".
ApiResponse<T> is a discriminated union of these two, using status as the discriminant.
The fetchData<T> function fetches data and returns an ApiResponse<T>, inferring T based on the usage.
In getUserProfile, after awaiting fetchData, we check result.status. If it's "success", TypeScript automatically knows that result is of type SuccessResponse<UserProfile>, giving us safe access to result.data.username and result.data.lastLogin. If result.status is "error", TypeScript correctly infers result as ErrorResponse, allowing access to result.message.

Exhaustiveness Checking with `never`

A critical benefit of discriminated unions is the ability to enforce exhaustiveness. This means ensuring that you've handled every possible variant in the union. If you forget a case, TypeScript can alert you. This is typically done by assigning the unhandled value to a variable of type never.

interface NotificationEvent {
  type: "email" | "sms" | "push";
  timestamp: number;
  payload: any;
}

function processNotification(event: NotificationEvent) {
  switch (event.type) {
    case "email":
      console.log("Processing email notification");
      // ... specific email logic
      break;
    case "sms":
      console.log("Processing SMS notification");
      // ... specific SMS logic
      break;
    // What if a new type 'push' is added later and we forget to update this?
    default:
      // TypeScript will error if 'event' is not 'never' here,
      // meaning there's an unhandled case in the switch statement.
      const _exhaustiveCheck: never = event;
      throw new Error(`Unhandled notification type: ${_exhaustiveCheck}`);
  }
}

// Example: Adding 'push' to NotificationEvent type without updating processNotification
// type NotificationEvent = { type: "email" | "sms" | "push"; timestamp: number; payload: any; }
// If you remove the 'push' case from the switch, the '_exhaustiveCheck' line will error,
// because 'event' (which could be { type: "push", ... }) cannot be assigned to 'never'.
// This forces you to add the 'push' case to your switch statement.

In this snippet:

The processNotification function uses a switch statement over event.type.
The default case includes const _exhaustiveCheck: never = event;. This is a powerful pattern.
If we were to add a new type to NotificationEvent (e.g., "push") but forget to add a corresponding case in the switch statement, TypeScript would then see event in the default block as potentially being of type { type: "push", ... }. Since event is no longer of type never (it could be "push"), TypeScript will throw a compilation error, reminding us to handle the new case. This ensures our logic is always complete for all defined types.

Common Mistakes and Gotchas

Missing or Mismatched Discriminant Property: All members of the union must have the same discriminant property name. Forgetting to include it, or spelling it differently in one of the interfaces, will prevent TypeScript from recognizing the union as discriminated.
```
// Incorrect: 'kind' vs 'type'
interface Foo { kind: "foo"; } 
interface Bar { type: "bar"; } 
type MyUnion = Foo | Bar; // Not a discriminated union
```

Non-Literal Discriminant Types: The discriminant property must be a string literal, number literal, or boolean literal type (e.g., "success", 1, true), not a general string or number. If it's a general type, TypeScript cannot use it for narrowing.

// Incorrect: 'status' is a general string
interface Success { status: string; data: any; }
interface Failure { status: string; error: string; }
type Result = Success | Failure; // Not a discriminated union for narrowing

Forgetting Exhaustiveness Checks: While optional, not using the never type for exhaustiveness checking can lead to runtime errors when new union members are added but not handled in switch statements. Always consider adding this pattern for robustness in critical functions.

Key Takeaways

Discriminated unions are an indispensable tool in TypeScript for managing complex data structures with varying shapes. They enable:

Enhanced Type Safety: Guarantees that you're accessing properties only when they are known to exist on the specific type.
Improved Code Readability: Makes intent clear by explicitly differentiating between data variations.
Robustness: With exhaustiveness checking, you're prompted to update your logic whenever new types are introduced into a union.
Better Developer Experience: Reduces the need for tedious type assertions and provides intelligent autocomplete within narrowed blocks.

By consistently applying discriminated unions, you can write more resilient, maintainable, and understandable TypeScript code, especially when dealing with the dynamic nature of real-world data.

Conclusion

Mastering discriminated unions is a significant step towards writing advanced, type-safe TypeScript. They provide a structural and reliable way to handle conditional types, moving beyond simple instanceof or typeof checks to deep, semantic type narrowing. Integrate this pattern into your projects to build more robust and error-resistant applications. Dive into your codebase and identify areas where discriminated unions could bring clarity and safety today!

DEV Community: Manas Joshi

Vitest Mocking: vi.mock vs vi.spyOn Explained

Vitest Mocking Deep Dive: vi.mock vs. vi.spyOn

Understanding vi.mock: Replacing Entire Modules

Understanding vi.spyOn: Inspecting and Modifying Existing Methods

When to Use Which?

Common Mistakes and Gotchas

Conclusion

Master TypeScript Discriminated Unions for Safer Type Narrowing

Understanding Discriminated Unions

Type Narrowing in Action

Ensuring Exhaustive Checks with never

Common Mistakes & Gotchas

Key Takeaways

Conclusion

Optimize React Re-renders: DevTools & Memoization Guide

Optimizing React Re-renders: A Deep Dive with DevTools and Memoization

Understanding React Component Re-renders

Tooling Up: React DevTools Profiler

How to Use the Profiler:

The Re-rendering Problem: A Basic Example

The Memoization Solution: React.memo and useCallback

React.memo for Components

useCallback for Functions

useMemo for Expensive Values

Common Mistakes and Gotchas

Key Takeaways

Conclusion

Reliable LLM JSON Output: Few-Shot Prompting & Robust Parsing

Achieving Reliable Structured JSON Output from LLMs

The Challenge with Unstructured LLM Responses

Guiding LLMs with Few-Shot Prompting

Robust Output Parsing and Validation

Common Mistakes and Gotchas

Conclusion

TypeScript Discriminated Unions: Safe API Response Handling

TypeScript Discriminated Unions: Safely Handling Dynamic API Responses

Understanding Discriminated Unions

Defining Our API Response Types

Implementing Type Guards for Narrowing

Processing Collections of Mixed Responses

Common Mistakes and Gotchas

Key Takeaways

Conclusion

Cancel JavaScript Async Ops with AbortController

Cleanly Cancel Asynchronous Operations with JavaScript's AbortController

Understanding AbortController

Example 1: Basic Fetch Cancellation

Example 2: Managing Component-Scoped Requests

Example 3: AbortSignal with Other Asynchronous Tasks

Common Mistakes & Gotchas

Conclusion

Optimize Performance with Intersection Observer API

Understanding the Core Concept

Basic Setup and Observation

Real-world Use Case: Lazy Loading Images

Real-world Use Case: Infinite Scrolling

Common Mistakes and Gotchas

Key Takeaways

Conclusion

Mocking Fetch API Calls in Vitest for Reliable Tests

Master Mocking Fetch API Calls in Vitest

The Challenge of fetch in Unit Tests

Building a Data Service

Setting Up fetch Mocking with Vitest

Writing Tests for Different Scenarios

Common Mistakes and Gotchas

Key Takeaways

Conclusion

Vite Environment Variables: Master .env & import.meta.env

Core Concept: Vite's Approach to Environment Variables

Defining Environment Variables with .env Files

Accessing Variables in Your Application

Running with Different Modes and Customizing Build Behavior

Common Mistakes / Gotchas

Key Takeaways

Conclusion

Integrate Custom Tools with OpenAI Function Calling

Understanding OpenAI Function Calling

Step 1: Describing Your Tools to the LLM

Vitest Mocking Deep Dive: `vi.mock` vs. `vi.spyOn`

Understanding `vi.mock`: Replacing Entire Modules

Understanding `vi.spyOn`: Inspecting and Modifying Existing Methods

Ensuring Exhaustive Checks with `never`

The Memoization Solution: `React.memo` and `useCallback`

`React.memo` for Components

`useCallback` for Functions

`useMemo` for Expensive Values

The Challenge of `fetch` in Unit Tests

Setting Up `fetch` Mocking with Vitest

Defining Environment Variables with `.env` Files

Before `useDeferredValue`

After `useDeferredValue`

Exhaustiveness Checking with `never`