Forem: eustatos

React Forms Deep Dive: Part 2 — UX, Accessibility & Performance

eustatos — Tue, 17 Mar 2026 15:07:40 +0000

💡 Transparency Note

This series includes examples from @nexus-state/form, a library I maintain. I include it to demonstrate an atom-based architectural approach, but I recommend evaluating all tools based on your specific project needs. All patterns shown are framework-agnostic and applicable to any solution.

🎓 What you'll learn in this part:

Error handling patterns that improve UX without annoying users

Essential WAI-ARIA attributes for accessible forms

Keyboard navigation and focus management strategies

Performance optimization techniques for large forms

How to benchmark and measure form performance

🧪 Try it yourself:

Open StackBlitz Demo

🔗 Series Roadmap:

Part Topic Status

1 Foundations & Core Patterns ✅ Published

2 UX, Accessibility & Performance ✅ Published ← you are here

3 Multi-step, Dynamic & Array Patterns 📅 Planned

4 Async Validation & Persistence 📅 Planned

5 Building a Visual Form Builder 📅 Planned

6 Creating a Validation DSL (Finale) 📅 Planned

💡 New parts published weekly. Follow @eustatos to get notified!

Part	Topic	Status
1	Foundations & Core Patterns	✅ Published
2	UX, Accessibility & Performance	✅ Published ← you are here
3	Multi-step, Dynamic & Array Patterns	📅 Planned
4	Async Validation & Persistence	📅 Planned
5	Building a Visual Form Builder	📅 Planned
6	Creating a Validation DSL (Finale)	📅 Planned

Introduction

In Part 1, we established the foundational concepts: Controlled vs. Uncontrolled components, validation strategies, schema-based approaches, and how to choose the right architectural pattern for your form.

Now we turn to what often determines whether a form succeeds or fails in production: User Experience (UX), Accessibility (A11y), and Performance.

These three areas are deeply interconnected:

A form that's inaccessible excludes users and creates legal risk
Poor error handling frustrates users and reduces conversion
Slow performance impacts engagement and Core Web Vitals

Add to this the reality that 15% of users rely on assistive technologies, and poor form UX is a leading cause of cart abandonment, and the stakes become clear.

In this part, we'll cover:

Error Handling & UX Patterns — when and how to show errors
Accessibility (WAI-ARIA) — essential attributes and testing
Keyboard Navigation — focus management and tab order
Performance Optimization — reducing re-renders in large forms
Interactive Benchmarking — measuring performance in your environment

Let's build forms that work for everyone.

1. Error Handling & UX

Proper error handling is foundational to form UX. Users need to understand what went wrong and how to fix it — without frustration or confusion.

Types of Errors

Type	Description	Example	When to Show
Required	Field is mandatory	"Name is required"	onBlur / onSubmit
Format	Invalid format	"Invalid email format"	onBlur
Range	Value outside bounds	"Age must be 18-120"	onBlur
Length	Too short/long	"Password min 8 chars"	onBlur
Pattern	Doesn't match regex	"Only letters allowed"	onBlur
Unique	Value not unique	"Email already exists"	Async, on blur
Business Logic	Domain rule violation	"Insufficient funds"	After submit
Server	API/Network error	"Service unavailable"	After submit

💡 Key takeaway: Not all errors are created equal. Format errors can be shown early; business logic errors should wait for submit or async blur checks.

Inline Errors (Recommended)

Inline errors appear directly below the problematic field. This is the best approach for most forms.

Why inline errors work:

Clear which field has the error
Context is preserved
Accessibility-friendly with ARIA
No scrolling required

Implementation:

function FormField({ 
  label, 
  name, 
  value, 
  error, 
  hint,
  required,
  onChange,
  onBlur 
}: FormFieldProps) {
  const errorId = `${name}-error`;
  const hintId = `${name}-hint`;
  const hasError = !!error;

  return (
    <div className="form-field">
      <label htmlFor={name}>
        {label}
        {required && <span aria-label="required">*</span>}
      </label>

      <input
        id={name}
        name={name}
        value={value}
        onChange={onChange}
        onBlur={onBlur}
        aria-invalid={hasError}
        aria-describedby={hasError ? errorId : hint ? hintId : undefined}
      />

      {hint && <span id={hintId} className="hint">{hint}</span>}

      {hasError && (
        <span id={errorId} className="error" role="alert" aria-live="polite">
          {error}
        </span>
      )}
    </div>
  );
}

Key ARIA attributes:

Attribute	Purpose	Example
`aria-invalid`	Indicates invalid state	`aria-invalid={!!error}`
`aria-describedby`	Links to hint/error text	`aria-describedby="email-error"`
`role="alert"`	Immediate screen reader announcement	On error message
`aria-live="polite"`	Non-interrupting updates	For async validation status

Error Summary for Large Forms

For forms with 10+ fields, add an error summary at the top.

When to use:

Complex forms (checkout, profile setup)
Multiple errors after submit
Multi-step forms

function ErrorSummary({ errors, formTitle = "form" }) {
  if (errors.length === 0) return null;

  return (
    <div className="error-summary" role="alert" tabIndex={-1}>
      <h2>Please fix {errors.length} error{errors.length > 1 ? 's' : ''}</h2>
      <ul>
        {errors.map((error) => (
          <li key={error.field}>
            <a href={`#${error.field}`} onClick={(e) => {
              e.preventDefault();
              document.getElementById(error.field)?.focus();
            }}>
              {error.field}: {error.message}
            </a>
          </li>
        ))}
      </ul>
    </div>
  );
}

Timing: When to Show Errors

The moment you show errors dramatically impacts UX.

Strategy	Pros	Cons	Best For
onChange (instant)	Immediate feedback	Annoying during typing	Format masks (phone, card)
onBlur (after field)	Balanced UX	Slight delay	Most validations
onSubmit (final check)	No interruptions	Too late for good UX	Server-side only checks

Best Practice: Hybrid Approach

function useFormValidation() {
  const [touched, setTouched] = useState<Record<string, boolean>>({});
  const [isSubmitted, setIsSubmitted] = useState(false);

  // Show error only if:
  // 1. Field was touched (onBlur) OR
  // 2. Form was submitted
  const shouldShowError = (field: string) => {
    return (touched[field] || isSubmitted) && errors[field];
  };

  const handleBlur = (field: string) => {
    setTouched(prev => ({ ...prev, [field]: true }));
  };

  // ... rest of validation logic
}

Business Validation Errors: Special Handling

Business logic errors (e.g., "email already exists", "coupon expired") need special UX treatment:

// Async validation with debouncing
const debouncedCheckEmail = useDebouncedCallback(
  async (email: string) => {
    setIsChecking(true);
    try {
      const result = await api.checkEmailAvailability(email);
      if (!result.available) {
        setError("This email is already registered");
      }
    } finally {
      setIsChecking(false);
    }
  },
  300 // 300ms delay
);

// UI feedback during async check
{isChecking && (
  <span className="validation-status" aria-live="polite">
    Checking availability...
  </span>
)}

Business validation UX checklist:

Show loading state during async check
Debounce requests (300-500ms)
Preserve user input on error
Provide actionable next steps ("Try signing in instead")
Don't block form submission for non-critical checks

💡 Key takeaway: Error timing is a UX decision, not just a technical one. Show format errors early; defer business logic errors until they're relevant.

2. Accessibility (WAI-ARIA)

Accessibility isn't optional — it's essential. Let's make forms usable for everyone.

Required ARIA Attributes

Attribute	Value	Purpose
`htmlFor` / `id`	Match label to input	Click label → focus input
`aria-invalid`	`true`/`false`	Screen reader announces invalid state
`aria-describedby`	Element ID	Links to hint or error text
`aria-required`	`true`/`false`	Announces required fields
`aria-label`	Text	Alternative label when visual label absent
`role="alert"`	—	Immediate error announcement
`aria-live="polite"`	—	Non-interrupting status updates

Accessible Form Example

function AccessibleForm() {
  return (
    <form aria-labelledby="form-title" onSubmit={handleSubmit}>
      <h2 id="form-title">Contact Information</h2>

      {/* Required field */}
      <div className="form-field">
        <label htmlFor="name">
          Name <span aria-hidden="true">*</span>
        </label>
        <input
          id="name"
          name="name"
          required
          aria-required="true"
          aria-invalid={!!errors.name}
          aria-describedby={errors.name ? "name-error" : "name-hint"}
        />
        <span id="name-hint" className="hint">Enter your full name</span>
        {errors.name && (
          <span id="name-error" className="error" role="alert">
            {errors.name}
          </span>
        )}
      </div>

      {/* Async validation field */}
      <div className="form-field">
        <label htmlFor="email">Email</label>
        <input
          id="email"
          name="email"
          type="email"
          aria-invalid={!!errors.email}
          aria-describedby="email-status"
        />
        <span id="email-status" className="status" aria-live="polite">
          {isChecking ? "Checking..." : errors.email || "We'll never share your email"}
        </span>
      </div>

      <button type="submit">Submit</button>
    </form>
  );
}

What Screen Readers Announce

When a user focuses on a field with a screen reader enabled, they hear:

1. Label text: "Email"
2. Field type: "edit text" 
3. Required status: "required" (if applicable)
4. Current value: "user@example.com" (if filled)
5. Description: "We'll never share your email" (from aria-describedby)
6. Validation state: "invalid entry" (if aria-invalid=true)
7. Error message: "Invalid email format" (if role="alert")

Test with real screen readers:

NVDA (Windows, free)
VoiceOver (macOS, built-in)
JAWS (Windows, paid)

💡 Key takeaway: Test your form with a screen reader before shipping. It's the only way to truly understand the experience.

3. Keyboard Navigation

Many users rely on keyboards for navigation. Proper keyboard support is non-negotiable for accessibility.

Standard Keyboard Shortcuts

Key	Action
`Tab`	Next focusable element
`Shift+Tab`	Previous focusable element
`Enter`	Submit form / activate button
`Space`	Toggle checkbox/radio
`Arrow keys`	Navigate radio groups, selects
`Esc`	Close modal/dropdown

Focus Management

Proper focus handling is critical for keyboard users.

Auto-focus on first error after submit:

const handleSubmit = async (e: React.FormEvent) => {
  e.preventDefault();

  const errors = await validate(values);
  if (Object.keys(errors).length > 0) {
    // Find first field with error
    const firstErrorField = Object.keys(errors)[0];
    const element = document.getElementById(firstErrorField);

    if (element) {
      element.focus();
      element.scrollIntoView({ behavior: 'smooth', block: 'center' });
    }
  }
};

Focus trap for modal forms:

function useFocusTrap(isOpen: boolean, containerRef: RefObject<HTMLElement>) {
  useEffect(() => {
    if (!isOpen || !containerRef.current) return;

    const container = containerRef.current;
    const focusable = container.querySelectorAll(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );

    const first = focusable[0] as HTMLElement;
    const last = focusable[focusable.length - 1] as HTMLElement;

    first?.focus();

    const handleTab = (e: KeyboardEvent) => {
      if (e.key !== 'Tab') return;

      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault();
        last?.focus();
      } else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault();
        first?.focus();
      }
    };

    container.addEventListener('keydown', handleTab);
    return () => container.removeEventListener('keydown', handleTab);
  }, [isOpen, containerRef]);
}

Tab Order Best Practices

Logical order (top-to-bottom, left-to-right)
No skipped elements
No manual tabindex="1+" (breaks natural flow)

// Good: Natural tab order
<input type="text" />  {/* tabindex="0" by default */}
<input type="email" />
<button>Submit</button>

// Avoid: Manual tabindex breaks flow
<input tabIndex={3} />
<input tabIndex={1} /> {/* Confusing navigation */}

💡 Key takeaway: Keyboard navigation should feel invisible. If users notice it, something is wrong.

4. Performance Patterns

Form performance directly impacts UX, especially for large forms.

The Problem: Unnecessary Re-renders

Controlled forms re-render on every keystroke:

// Every keystroke = re-render ALL fields
function SlowForm() {
  const [values, setValues] = useState({
    field1: '', field2: '', /* ... field100: '' */
  });

  return (
    <form>
      {Object.keys(values).map(key => (
        <input 
          key={key}
          value={values[key]}
          onChange={(e) => setValues({ ...values, [key]: e.target.value })}
        />
      ))}
    </form>
  );
}

Solution 1: Debounced Async Validation

const debouncedValidate = useDebouncedCallback(
  async (value: string) => {
    setIsValidating(true);
    const result = await validateEmailOnServer(value);
    setError(result.error);
    setIsValidating(false);
  },
  300 // 300ms delay
);

Solution 2: Memoize Field Components

const FormField = React.memo(({ name, value, onChange, error }: FormFieldProps) => {
  // Only re-renders when its own props change
  return (
    <div className="form-field">
      <input value={value} onChange={onChange} />
      {error && <span className="error">{error}</span>}
    </div>
  );
});

Solution 3: Uncontrolled Approach for Large Forms

import { useForm } from 'react-hook-form';

function FastForm() {
  const { register, handleSubmit } = useForm();

  // Minimal re-renders - only on submit
  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      {Array.from({ length: 100 }).map((_, i) => (
        <input key={i} {...register(`field${i}`)} />
      ))}
    </form>
  );
}

Interactive Benchmarking

🧪 Try it live: Open Demo on StackBlitz

Our interactive demo includes a built-in benchmark tool to measure form performance in your environment.

How to use:

Open the StackBlitz demo
Click the Benchmark tab
Click Run Benchmark to simulate user input
Review render times for each field component
Click Export JSON to save results for analysis

Expected Results (Local Environment):

Component	Renders	Avg Time (ms)	Rating
FormField-0	6	0.07	Excellent
FormField-1	6	0.04	Excellent
FormField-2	5	0.05	Excellent

⚠️ StackBlitz Note: Results in StackBlitz Preview may include WebContainers overhead. For production-accurate measurements, clone and run locally.

Performance Guidelines:

Avg Render Time	Rating	Recommendation
< 16ms	Excellent	60 FPS, no optimization needed
16-100ms	Acceptable	Good for most forms
> 100ms	Slow	Consider memoization or uncontrolled inputs

💡 Key takeaway: Profile before optimizing. Measure in your target environment, not just in development.

Production Checklist

Use this checklist before shipping your form to production.

Validation & Error Handling

[ ] Client-side validation for format/length
[ ] Server-side validation for uniqueness/business rules
[ ] Schema-based validation (Zod/Yup)
[ ] Async validation with debouncing (300-500ms)
[ ] Clear, actionable error messages
[ ] Inline errors for each field
[ ] Error summary for forms with 10+ fields
[ ] Show errors after onBlur (not onChange)
[ ] Focus first error field on submit
[ ] Preserve user input on validation errors

Accessibility

[ ] All inputs have associated <label> elements
[ ] aria-invalid on invalid fields
[ ] aria-describedby linking to hints/errors
[ ] aria-required for mandatory fields
[ ] role="alert" on error messages
[ ] Keyboard navigation works end-to-end
[ ] Logical tab order
[ ] Focus trap for modal forms
[ ] Tested with at least one screen reader

Performance

[ ] Minimal re-renders (use React.memo where needed)
[ ] Debounced async validation
[ ] Uncontrolled inputs for large forms (>20 fields)
[ ] Profiled with React DevTools Profiler
[ ] Lazy validation (only touched fields)

UX Polish

[ ] Loading states for async operations
[ ] Disabled submit button during submission
[ ] Success feedback after submit
[ ] Auto-save for long forms (optional)
[ ] Confirm before losing unsaved changes
[ ] Clear placeholder text and hints
[ ] Visual indicator for required fields

Security

[ ] HTTPS for all form submissions
[ ] CSRF protection
[ ] Rate limiting on submit endpoint
[ ] Input sanitization
[ ] Never log sensitive data (passwords, tokens)
[ ] Content Security Policy headers

Conclusion & What's Next

Key Takeaways from Part 2

Error handling is a UX decision. Show format errors on blur; defer business logic errors until they're relevant. Use role="alert" for screen reader announcements.
Accessibility attributes aren't optional. aria-invalid, aria-describedby, and proper label associations are essential for inclusive forms.
Keyboard navigation should be invisible. Focus management, logical tab order, and focus traps for modals are non-negotiable.
Performance matters most for large forms. Use memoization, debouncing, or uncontrolled inputs to minimize re-renders.
Measure in your environment. StackBlitz benchmarks are useful for relative comparison; run locally for production-accurate numbers.

Coming Up in the Series

We've covered foundations and UX. Next, we'll tackle advanced patterns:

Part 3: Multi-step, Dynamic & Array Patterns

→ Wizard forms, conditional fields, repeatable field groups, and state management strategies

Part 4: Async Validation & Persistence

→ Cross-field validation, debouncing strategies, auto-save, and TanStack Query integration

Part 5: Building a Visual Form Builder

→ Schema-driven architecture, drag-and-drop UI, component registry, and code export

Part 6: Creating a Validation DSL (Series Finale)

→ Designing a domain-specific language for validation rules, parser implementation, and real-world examples

Resources & Further Reading

Documentation

Tools

StackBlitz Demo — Interactive playground with benchmarking
axe-core — Accessibility testing engine
React DevTools Profiler — Performance debugging
jest-axe — Accessibility testing in Jest

💬 Feedback welcome!

Found an error? Have a suggestion? Open an issue on GitHub or leave a comment below. Let's build better forms together.

React Forms Deep Dive: Part 1 — Foundations & Core Patterns

eustatos — Mon, 16 Mar 2026 15:20:44 +0000

💡 Transparency Note

This series includes examples from @nexus-state/form, a library I maintain. I include it to demonstrate an atom-based architectural approach, but I recommend evaluating all tools based on your specific project needs. All patterns shown are framework-agnostic and applicable to any solution.

🎓 What you'll learn in this part:

The fundamental tradeoffs between Controlled and Uncontrolled components

When to use client-side vs. server-side validation (and how to combine them)

Why schema-based validation beats imperative code

How to choose a form library based on architectural needs, not trends

🧪 Try it yourself:

Open StackBlitz Demo

🔗 Series Roadmap:

Part Topic Status

1 Foundations & Core Patterns ✅ Published ← you are here

2 UX, Accessibility & Performance ✅ Published

3 Multi-step, Dynamic & Array Patterns 📅 Planned

4 Async Validation & Persistence 📅 Planned

5 Building a Visual Form Builder 📅 Planned

6 Creating a Validation DSL (Finale) 📅 Planned

💡 New parts published weekly. Follow @eustatos to get notified!

Part	Topic	Status
1	Foundations & Core Patterns	✅ Published ← you are here
2	UX, Accessibility & Performance	✅ Published
3	Multi-step, Dynamic & Array Patterns	📅 Planned
4	Async Validation & Persistence	📅 Planned
5	Building a Visual Form Builder	📅 Planned
6	Creating a Validation DSL (Finale)	📅 Planned

Introduction

If you've ever worked with forms in React, you know they can be surprisingly complex. Forms sit at the intersection of three types of state:

UI state — what the user sees and interacts with
Server state — data to send/receive from the backend
Validation state — rules, errors, and async checks

Add edge cases (async validation, cross-field dependencies, multi-step flows), UX requirements (accessibility, performance, error feedback), and you have one of the most challenging aspects of frontend development.

In this 6-part series, we'll go from foundational concepts to production-ready patterns for building forms in React:

Foundations & Core Patterns ← you are here
UX, Accessibility & Performance
Advanced Patterns: Multi-step, Dynamic, Arrays
Validation Deep Dive: Async, Cross-field, Persistence
Building a Visual Form Builder
Creating a Validation DSL (Series Finale)

In this first part, we'll establish the mental models you need: Controlled vs. Uncontrolled components, validation strategies, schema-based approaches, and how to think about library selection.

1. Controlled vs. Uncontrolled: The First Decision

The first fundamental choice when building forms in React: should your component be Controlled or Uncontrolled?

Controlled Components

In the Controlled approach, React state is the single source of truth for form values:

import { useState } from 'react';

function ControlledEmailInput() {
  const [email, setEmail] = useState('');

  return (
    <input
      value={email}
      onChange={(e) => setEmail(e.target.value)}
      aria-label="Email address"
    />
  );
}

How it works:

User types a character
onChange fires
State updates via setEmail
React re-renders the component
Input receives the new value from state

✅ Advantages:

Full control over the value at all times
Instant validation and formatting
Easy to implement dependent fields (e.g., password confirmation)
Ideal for Time Travel debugging and state inspection
Predictable data flow

❌ Tradeoffs:

Re-renders on every keystroke
More boilerplate for simple cases
Can impact performance in large forms (50+ fields)

Uncontrolled Components

In the Uncontrolled approach, the DOM is the source of truth:

import { useRef } from 'react';

function UncontrolledEmailInput() {
  const emailRef = useRef<HTMLInputElement>(null);

  const handleSubmit = () => {
    const value = emailRef.current?.value;
    console.log('Submitted:', value);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input ref={emailRef} defaultValue="" aria-label="Email address" />
      <button type="submit">Submit</button>
    </form>
  );
}

How it works:

User types a character
Value is stored in the DOM
React does not re-render
Access the value via ref when needed (e.g., on submit)

✅ Advantages:

Minimal re-renders → better performance for large forms
Less boilerplate for simple use cases
Easier integration with non-React libraries
Native browser features (autocomplete, spellcheck) work seamlessly

❌ Tradeoffs:

No instant validation or formatting
Harder to implement dependent field logic
More complex for Time Travel debugging
Values must be read imperatively

📊 Comparison at a Glance

Criterion	Controlled	Uncontrolled
Source of truth	React state	DOM
Re-renders	On every change	Minimal
Validation timing	Instant (onChange)	Typically on submit
Time Travel debugging	✅ Easy	❌ Complex
Boilerplate	Higher	Lower
Performance (large forms)	Lower	Higher
Input formatting	✅ Easy	❌ Manual

When to Use Which

Choose Controlled when:

You need instant validation or formatting (masks, uppercase, etc.)
Fields depend on each other (e.g., "Confirm Password")
You want Time Travel debugging or state inspection
The form is small to medium (< 20 fields)
You're building a highly interactive UI

Choose Uncontrolled when:

Performance is critical and the form is large (50+ fields)
You're integrating with non-React code or third-party widgets
Validation happens only on submit
You're working with file inputs (always uncontrolled)
You prefer minimal re-renders and simpler code

💡 Key takeaway: There's no universally "correct" choice. Controlled components give you power and predictability; Uncontrolled components give you performance and simplicity. Many production forms use a hybrid approach.

2. Validation Strategies: Client, Server, and Hybrid

Validation is one of the most critical aspects of form development. There are three primary approaches:

Client-Side Validation

Validation that runs in the browser before data is sent to the server.

function validateEmail(email: string): string | null {
  if (!email) return 'Email is required';

  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(email)) {
    return 'Please enter a valid email address';
  }

  return null;
}

function EmailField() {
  const [email, setEmail] = useState('');
  const [error, setError] = useState<string | null>(null);

  const handleChange = (value: string) => {
    setEmail(value);
    if (value && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
      setError('Invalid email format');
    } else {
      setError(null);
    }
  };

  return (
    <div>
      <label htmlFor="email">Email</label>
      <input
        id="email"
        type="email"
        value={email}
        onChange={(e) => handleChange(e.target.value)}
        aria-invalid={!!error}
        aria-describedby={error ? 'email-error' : undefined}
      />
      {error && (
        <span id="email-error" className="error" role="alert">
          {error}
        </span>
      )}
    </div>
  );
}

✅ Pros:

Instant feedback → better UX
Reduces unnecessary server requests
Works offline
Lowers server load

❌ Cons:

Can be bypassed via DevTools → never trust client validation alone
Logic duplication between client and server
Increases bundle size if validation rules are complex

Server-Side Validation

Validation that runs on the backend after form submission.

async function submitForm(data: FormData) {
  try {
    const response = await fetch('/api/submit', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });

    if (!response.ok) {
      const errors = await response.json();
      return { success: false, errors };
    }

    return { success: true };
  } catch (err) {
    return { success: false, errors: { form: 'Network error' } };
  }
}

✅ Pros:

Single source of truth → cannot be bypassed
Access to database (e.g., check email uniqueness)
Enforces business rules and security policies
Centralized logic → easier to maintain

❌ Cons:

Network latency → slower feedback
Server load increases with validation complexity
Doesn't work offline
Poor UX if errors are only shown after submit

Hybrid Validation: The Best Practice

Combine client and server validation for optimal UX and security.

Strategy:

Client: Format, length, required fields → instant feedback
Server: Uniqueness, business rules, security → authoritative check

function HybridEmailValidation() {
  const [email, setEmail] = useState('');
  const [error, setError] = useState<string | null>(null);
  const [isValidating, setIsValidating] = useState(false);

  const validateFormat = (value: string): string | null => {
    if (!value) return 'Email is required';
    const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return regex.test(value) ? null : 'Invalid email format';
  };

  const checkUniqueness = async (value: string): Promise<string | null> => {
    try {
      const response = await fetch('/api/check-email', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email: value }),
      });
      const data = await response.json();
      return data.available ? null : 'Email already registered';
    } catch {
      return 'Unable to verify email';
    }
  };

  const handleBlur = async () => {
    const formatError = validateFormat(email);
    if (formatError) {
      setError(formatError);
      return;
    }

    setIsValidating(true);
    const serverError = await checkUniqueness(email);
    setError(serverError);
    setIsValidating(false);
  };

  return (
    <div>
      <label htmlFor="email">Email</label>
      <input
        id="email"
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        onBlur={handleBlur}
        aria-invalid={!!error}
        aria-describedby={error ? 'email-error' : undefined}
      />
      {isValidating && <span aria-live="polite">Checking...</span>}
      {error && (
        <span id="email-error" className="error" role="alert">
          {error}
        </span>
      )}
    </div>
  );
}

Timing Strategy:

Trigger	Client Validation	Server Validation
`onChange`	✅ Format hints (optional)	❌ Too frequent
`onBlur`	✅ Final format check	✅ Uniqueness / business rules
`onSubmit`	✅ Full client check	✅ Final authoritative check

💡 Key takeaway: Hybrid validation = best of both worlds. Use client-side for instant UX feedback, server-side for security and data integrity. Always validate on the server—client validation is a convenience, not a guarantee.

3. Schema-Based Validation: Declarative Over Imperative

Imperative validation (writing if statements for each field) quickly becomes unmaintainable. Schema-based validation solves this by describing rules declaratively.

The Problem with Imperative Validation

// ❌ Hard to maintain, no type safety, repetitive
function validateUser(user: User): Record<string, string> {
  const errors: Record<string, string> = {};

  if (!user.name || user.name.length < 2) {
    errors.name = 'Name must be at least 2 characters';
  }

  if (!user.email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(user.email)) {
    errors.email = 'Invalid email format';
  }

  if (!user.age || user.age < 18) {
    errors.age = 'Must be 18 or older';
  }

  return errors;
}

Problems:

Repetitive boilerplate
No type safety between validation and data structures
Hard to reuse rules across forms
Difficult to test in isolation

The Solution: Declarative Schemas

Describe validation rules once, infer TypeScript types automatically, and reuse across client/server.

Zod Example

import { z } from 'zod';

const userSchema = z.object({
  name: z
    .string()
    .min(2, 'Name must be at least 2 characters')
    .max(50, 'Name is too long'),

  email: z.string().email('Please enter a valid email address'),

  age: z
    .number()
    .min(18, 'Must be 18 or older')
    .max(120, 'Please enter a valid age'),

  password: z
    .string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/[A-Z]/, 'Include at least one uppercase letter')
    .regex(/[0-9]/, 'Include at least one number'),
});

// Automatically infer TypeScript type
type UserInput = z.infer<typeof userSchema>;

// Use the schema
const result = userSchema.safeParse(formData);
if (!result.success) {
  console.log(result.error.errors);
}

Yup Example

import * as yup from 'yup';

const userSchema = yup.object({
  name: yup
    .string()
    .min(2, 'Name must be at least 2 characters')
    .required('Name is required'),

  email: yup
    .string()
    .email('Invalid email format')
    .required('Email is required'),

  age: yup.number().min(18, 'Must be 18 or older').required('Age is required'),
});

// Usage
try {
  await userSchema.validate(formData, { abortEarly: false });
} catch (error) {
  console.log(error.errors);
}

Why Schema-Based Validation Wins

Benefit	Description
Type Safety	TypeScript types inferred automatically from schema
Reusability	One schema for client + server validation
Composition	Combine and extend schemas easily
Maintainability	Rules are declarative, easy to read and update
Testing	Validate schema logic in isolation from UI
Error Messages	Centralized, customizable, localizable

💡 Key takeaway: Schema-based validation is the modern standard for production forms. It reduces bugs, improves DX, and scales with your application.

4. Implementation Strategies: Choosing the Right Tool

There's no single "best" form library. The right choice depends on your project's requirements, team experience, and architectural priorities.

Rather than ranking libraries, let's compare architectural approaches they represent:

Approach 1: Controlled State (Formik-style)

Philosophy: "Keep it simple, use React patterns you already know."

// Conceptual example
function SimpleForm() {
  const [values, setValues] = useState({ email: '', password: '' });

  const handleChange = (field: string, value: string) => {
    setValues((prev) => ({ ...prev, [field]: value }));
  };

  return (
    <form>
      <input
        value={values.email}
        onChange={(e) => handleChange('email', e.target.value)}
      />
    </form>
  );
}

✅ Best for:

Simple forms with straightforward logic
Teams new to React or form libraries
Projects where bundle size isn't critical

❌ Considerations:

Re-renders on every field change
More boilerplate for complex validation

Approach 2: Uncontrolled + Refs (React Hook Form-style)

Philosophy: "Minimize re-renders, maximize performance."

// Conceptual example
import { useForm } from 'react-hook-form';

function PerformantForm() {
  const { register, handleSubmit } = useForm();

  const onSubmit = (data) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email', { required: true })} />
    </form>
  );
}

✅ Best for:

Large forms (20+ fields) where performance matters
Projects prioritizing minimal bundle size
Teams comfortable with refs and uncontrolled patterns

❌ Considerations:

Slightly steeper learning curve
Less intuitive for Time Travel debugging

Approach 3: Atom-Based State (Experimental / Advanced)

Philosophy: "Fine-grained reactivity + built-in debugging."

// Conceptual example (atom-based architecture)
import { createFormAtom } from '@nexus-state/form';

const formAtom = createFormAtom(schema, { email: '', password: '' });

function AtomForm() {
  const [emailValue] = useAtom(formAtom.fields.email);

  return (
    <input
      value={emailValue}
      onChange={(e) => formAtom.setField('email', e.target.value)}
    />
  );
}

✅ Best for:

Complex forms needing deep state inspection
Projects already using atom-based state management
Teams building tooling (Form Builders, DevTools, etc.)

❌ Considerations:

Smaller ecosystem, evolving API (pre-v1.0)
Requires understanding of atomic state concepts

Quick Comparison

Aspect	Controlled	Uncontrolled	Atom-Based
Re-renders	On every change	Minimal	Per-field only
Learning curve	Low	Medium	Medium-High
Bundle size	~15KB	~7KB	~8KB (core)
Debugging	Standard React DevTools	Standard	Time Travel + DevTools
Ecosystem	Mature	Large	Emerging
Framework support	React	React	React/Vue/Svelte

💡 Key takeaway: Don't choose a library because it's popular. Choose an architectural approach that matches your needs:

Need simplicity? → Controlled

Need performance? → Uncontrolled

Need deep state inspection? → Atom-based

5. Decision Guide: How to Choose

Use this framework to evaluate form solutions for your project.

By Project Requirements

Requirement	Recommended Approach
Simple login/contact form	Controlled (minimal setup)
Large data-entry form (50+ fields)	Uncontrolled (performance)
Complex multi-step wizard	Either + state management
Need Time Travel debugging	Atom-based or custom solution
Framework-agnostic code	Uncontrolled or atom-based
Maximum bundle size constraints	Uncontrolled (~7KB)

By Team Experience

Team Profile	Recommendation
React beginners	Controlled approach (familiar patterns)
Intermediate React devs	React Hook Form (balance of power + DX)
Advanced / tooling teams	Evaluate atom-based or build custom
Large team (10+ devs)	Mature library with strong docs + community

By Validation Complexity

Validation Need	Strategy
Format + required only	Client-side schema (Zod/Yup)
Uniqueness checks	Hybrid: client format + server async
Cross-field rules	Schema `refine()` + `watch()`
Business rules + DB access	Server-side authoritative validation

Production Checklist for Part 1

Before moving to advanced patterns, ensure your foundation includes:

[ ] Controlled vs. Uncontrolled decision documented
[ ] Hybrid validation strategy (client + server)
[ ] Schema-based validation (Zod or Yup)
[ ] Accessibility attributes (aria-invalid, aria-describedby)
[ ] Error timing: validate on blur, not every keystroke
[ ] TypeScript types inferred from validation schema
[ ] Library choice justified by project needs, not trends

Conclusion & What's Next

Key Takeaways from Part 1

Controlled vs. Uncontrolled isn't about "right vs. wrong"—it's about tradeoffs. Controlled gives you power; Uncontrolled gives you performance.
Hybrid validation is the production standard: client-side for instant UX, server-side for security and data integrity.
Schema-based validation (Zod, Yup) reduces bugs, improves type safety, and scales better than imperative if statements.
Library selection should be driven by architectural needs, not popularity. Evaluate approaches, not just brands.
Accessibility and UX start at the foundation—aria-invalid, proper error timing, and keyboard navigation aren't "nice-to-haves."

Coming Up in the Series

We've laid the groundwork. Next, we'll build on these foundations:

Part 2: UX, Accessibility & Performance

→ Error handling patterns, WAI-ARIA deep dive, keyboard navigation, performance optimization checklist

Part 3: Advanced Patterns I

→ Multi-step forms (wizards), dynamic/conditional fields, form arrays (repeatable groups)

Part 4: Validation Deep Dive

→ Cross-field validation, async validation with debouncing, form persistence, TanStack Query integration

Part 5: Building a Form Builder

→ Schema-driven architecture, drag-and-drop UI, component registry, export to code

Part 6: Creating a Validation DSL

→ Designing a domain-specific language for validation rules, parser implementation, real-world examples

Resources & Further Reading

Documentation

Tools

StackBlitz Demo — Interactive playground
axe-core — Accessibility testing
React DevTools Profiler — Performance debugging

💬 Feedback welcome!

Found an error? Have a suggestion? Open an issue on GitHub or leave a comment below. Let's build better forms together.

Time-Travel Debugging in State Management: Part 2 — Performance & Advanced Topics

eustatos — Sat, 14 Mar 2026 09:44:14 +0000

Introduction

Imagine: your application uses time-travel — for debugging or as a user feature. After 50 changes, problems start: 500MB memory, 200ms undo/redo delay.

Sound familiar? This article covers advanced optimization techniques used in production applications:

Delta compression (up to 90% memory savings)
Batching (change grouping)
Smart navigation algorithms
Transactional restoration
Turning time-travel from debugging tool into a UX feature

📖 From Part 1: We covered architectural patterns (Command, Snapshot, Delta, Hybrid). In this part, we dive into optimization and performance.

💡 Note: Examples use SimpleTimeTravel from Nexus State for demonstration. For other libraries (Zustand, Redux, Jotai), use similar patterns — change tracking + snapshot array + navigation. API may differ, but concepts are universal.

💡 Note: Optimizations in this article apply to both scenarios — debugging AND user-facing undo/redo.

Memory Optimization: Delta Snapshots

The Memory Problem

With full snapshots, memory grows linearly:

State: 100KB
History: 50 snapshots
Memory: 100KB × 50 = 5MB

Solution: Delta Compression

interface DeltaSnapshot {
  id: string;
  type: 'delta';
  baseSnapshotId: string;
  changes: Record<string, {
    oldValue: any;
    newValue: any;
  }>;
  timestamp: number;
  metadata: {
    changedAtoms: string[];
    deltaSize: number;
  };
}

Delta Calculation Algorithm

class DeltaCalculator {
  computeDelta(base: Snapshot, target: Snapshot): DeltaSnapshot | null {
    const changes: Record<string, any> = {};
    let hasChanges = false;

    for (const [key, entry] of Object.entries(target.state)) {
      const baseEntry = base.state[key];

      if (!deepEqual(baseEntry?.value, entry.value)) {
        changes[key] = {
          oldValue: baseEntry?.value,
          newValue: entry.value,
        };
        hasChanges = true;
      }
    }

    if (!hasChanges) return null;

    return {
      id: generateId(),
      type: 'delta',
      baseSnapshotId: base.id,
      changes,
      timestamp: target.metadata.timestamp,
      metadata: {
        changedAtoms: Object.keys(changes),
        deltaSize: Object.keys(changes).length,
      },
    };
  }
}

Efficiency

Scenario: Form with 50 fields, 1-2 fields change at a time

Full Snapshots: 50 × 50KB = 2.5MB
Delta Snapshots: 50KB + (49 × 2KB) = 148KB
Savings: ~94%

Batching: Grouping Changes

The Problem

User fills a 5-field form. Each change creates a snapshot:

// Without batching: 5 snapshots
store.set(form.name, 'John');      // Snapshot 1
store.set(form.email, 'john@');    // Snapshot 2
store.set(form.email, 'john@ex');  // Snapshot 3
// ... and so on

Result: 5 snapshots instead of 1, history fills 5x faster.

Solution

class BatchManager {
  private isBatching = false;
  private debounceTimer: ReturnType<typeof setTimeout> | null = null;

  batch<T>(updateFn: () => T, actionName: string, debounceMs = 0): T {
    if (this.isBatching) return updateFn();

    this.isBatching = true;

    try {
      const result = updateFn();

      if (debounceMs > 0) {
        if (this.debounceTimer) clearTimeout(this.debounceTimer);
        this.debounceTimer = setTimeout(() => {
          timeTravel.capture(actionName);
          this.isBatching = false;
        }, debounceMs);
      } else {
        timeTravel.capture(actionName);
        this.isBatching = false;
      }

      return result;
    } catch (error) {
      this.isBatching = false;
      throw error;
    }
  }
}

// Usage
batchManager.batch(() => {
  store.set(form.name, 'John');
  store.set(form.email, 'john@example.com');
  store.set(form.age, 25);
}, 'form-update');
// → One snapshot for all three changes

When to Use

Approach	Use when	Example
Batch	Known number of changes	Form, profile update
Debounce	Frequent changes	Text input, scroll
Batch + Debounce	Combined	Code editor, validated forms

Snapshot Comparison

Why Compare?

Visualization — Diff View for users
Optimization — Compute only changed parts
Analysis — Understand what changed between versions

Comparison Algorithm

interface ComparisonResult {
  added: string[];
  removed: string[];
  changed: { key: string; oldValue: any; newValue: any }[];
  unchanged: string[];
  similarity: number; // 0-1
}

class SnapshotComparator {
  compare(a: Snapshot, b: Snapshot): ComparisonResult {
    const result: ComparisonResult = {
      added: [], removed: [], changed: [], unchanged: [],
      similarity: 0,
    };

    const allKeys = new Set([...Object.keys(a.state), ...Object.keys(b.state)]);

    for (const key of allKeys) {
      const aHas = key in a.state;
      const bHas = key in b.state;

      if (!aHas && bHas) {
        result.added.push(key);
      } else if (aHas && !bHas) {
        result.removed.push(key);
      } else if (!deepEqual(a.state[key], b.state[key])) {
        result.changed.push({ key, oldValue: a.state[key], newValue: b.state[key] });
      } else {
        result.unchanged.push(key);
      }
    }

    result.similarity = 1 - (result.changed.length / allKeys.size);
    return result;
  }
}

Optimization Use Case

// Restore only changes
function restoreChangesOnly(comparison: ComparisonResult) {
  for (const { key, newValue } of comparison.changed) {
    if (newValue !== undefined) store.set(key, newValue);
  }
  for (const key of comparison.added) {
    store.set(key, /* newValue */);
  }
  for (const key of comparison.removed) {
    store.delete(key);
  }
}

// Savings: 67% (25.1ms → 8.3ms for 100 atoms)

Serialization & Persistence

JSON.stringify Problems

Standard serialization doesn't work with complex types:

const state = {
  date: new Date(),         // → ISO string (loses type)
  map: new Map([['a', 1]]), // → {} (loses data)
  set: new Set([1, 2]),     // → {} (loses data)
  sparse: [1, , 3],         // → [1, null, 3] (loses "hole")
  typed: new Uint8Array([1, 2, 3]), // → {} (loses data)
  circular: null,
};
state.circular = state; // ❌ TypeError: Circular structure

Custom Revivers

const customStringifier = (key: string, value: any): any => {
  if (value instanceof Date) return { __type: 'date', value: value.toISOString() };
  if (value instanceof Map) return { __type: 'map', value: Array.from(value.entries()) };
  if (value instanceof Set) return { __type: 'set', value: Array.from(value) };
  if (value === undefined) return { __type: 'undefined' };
  return value;
};

const customReviver = (key: string, value: any): any => {
  if (value?.__type) {
    switch (value.__type) {
      case 'date': return new Date(value.value);
      case 'map': return new Map(value.value);
      case 'set': return new Set(value.value);
      case 'undefined': return undefined;
    }
  }
  return value;
};

Advanced Types

const advancedStringifier = (key, value) => {
  // BigInt
  if (typeof value === 'bigint') {
    return { __type: 'bigint', value: value.toString() };
  }
  // RegExp
  if (value instanceof RegExp) {
    return { __type: 'regexp', source: value.source, flags: value.flags };
  }
  // URL
  if (value instanceof URL) {
    return { __type: 'url', href: value.href };
  }
  // ArrayBuffer
  if (value instanceof ArrayBuffer) {
    return { __type: 'array-buffer', data: Array.from(new Uint8Array(value)) };
  }
  return value;
};

Deep Equality for Map/Set

function deepEqual(a, b): boolean {
  if (a === b) return true;

  if (a instanceof Map && b instanceof Map) {
    if (a.size !== b.size) return false;
    for (const [key, value] of a) {
      if (!b.has(key) || !deepEqual(value, b.get(key))) return false;
    }
    return true;
  }

  if (a instanceof Set && b instanceof Set) {
    if (a.size !== b.size) return false;
    for (const value of a) {
      if (!b.has(value)) return false;
    }
    return true;
  }

  if (Array.isArray(a) && Array.isArray(b)) {
    if (a.length !== b.length) return false;
    for (let i = 0; i < a.length; i++) {
      if (!deepEqual(a[i], b[i])) return false;
    }
    return true;
  }

  if (typeof a === 'object' && typeof b === 'object') {
    const keysA = Object.keys(a);
    const keysB = Object.keys(b);
    if (keysA.length !== keysB.length) return false;
    for (const key of keysA) {
      if (!keysB.includes(key) || !deepEqual(a[key], b[key])) return false;
    }
    return true;
  }

  return a === b;
}

Circular References

function safeStringify(obj, indent = 2) {
  const seen = new WeakSet();
  return JSON.stringify(obj, (key, value) => {
    if (typeof value === 'object' && value !== null) {
      if (seen.has(value)) return '[Circular]';
      seen.add(value);
    }
    return value;
  }, indent);
}

Type Support Table

Type	Serialization	Comparison	Notes
string/number/boolean	✅	✅	NaN, Infinity, -0
undefined	⚠️ `{ __type }`	✅	Lost in JSON
Object/Array	✅	✅	Key order, sparse arrays
Date	✅ `{ __type }`	✅ timestamp
Map/Set	✅ entries	✅ recursion	Object keys
WeakMap/WeakSet	❌	❌	Replace with Map/Set
RegExp	✅ `{ source, flags }`	✅
BigInt	✅ `{ __type }`	✅
URL	✅ `{ href }`	✅
TypedArray	✅ `{ constructor, data }`	✅	8 types
ArrayBuffer	✅ data array	✅
Promise	❌	❌	Async
Blob/File	⚠️ base64	✅ size+type	Large
Function	❌	❌	Not serializable
Circular ref	✅ WeakSet	✅ WeakMap

Performance: stringify vs deepClone

For creating snapshots, you need to clone objects. Let's compare approaches:

Benchmark (real data)

Methodology: Node 20.19.4, macOS x64. Testing on real data with nested objects, Map, Set, Date, TypedArray (~765KB). Benchmark source code (GitHub Gist).

┌──────────────────────┬────────────┬────────────┬──────────────┬─────────┐
│ Method               │ Time (ms)  │ Avg (ms)   │ Memory       │ Tests   │
├──────────────────────┼────────────┼────────────┼──────────────┼─────────┤
│ JSON.stringify       │ 16491.61   │ 16.492     │ 192%         │ 3/7 ✅  │
│ structuredClone      │ 19956.35   │ 19.956     │ 58%          │ 7/7 ✅  │
│ deepClone (custom)   │ 7369.91    │ 7.370      │ 125%         │ 7/7 ✅  │
│ lodash cloneDeep     │ 20419.67   │ 20.420     │ 101%         │ 7/7 ✅  │
└──────────────────────┴────────────┴────────────┴──────────────┴─────────┘

🏆 Fastest: deepClone (custom) — 2-3x faster for large data

Note: Results vary by data size, structure, and environment. For small objects (<100KB), structuredClone is usually faster. For large data (>500KB), custom deepClone shows better performance.

Recommendations

Scenario	Method	Why
Large data (>500KB)	`deepClone (custom)`	2-3x faster
Small data (<100KB)	`structuredClone()`	Fast, built-in
Memory efficiency	`structuredClone()`	58% memory
Prototyping	`JSON.stringify`	Simple, but loses types
Avoid	`lodash cloneDeep`	Slow + 24KB bundle

Navigation Algorithms

Undo/Redo with Two Stacks

class HistoryNavigator {
  private past: Snapshot[] = [];
  private future: Snapshot[] = [];
  private current: Snapshot | null = null;

  undo(): Snapshot | null {
    if (this.past.length === 0) return null;
    if (this.current) this.future.unshift(this.current);
    this.current = this.past.pop()!;
    return this.current;
  }

  redo(): Snapshot | null {
    if (this.future.length === 0) return null;
    if (this.current) this.past.push(this.current);
    this.current = this.future.shift()!;
    return this.current;
  }

  jumpTo(index: number): Snapshot | null {
    const all = [...this.past, this.current, ...this.future].filter(Boolean) as Snapshot[];
    if (index < 0 || index >= all.length) return null;
    this.past = all.slice(0, index);
    this.future = all.slice(index + 1);
    this.current = all[index];
    return this.current;
  }
}

Operation Complexity

Operation	Complexity
`undo()`	O(1)
`redo()`	O(1)
`jumpTo(n)`	O(n)

Transactionality

The Problem

During restoration, errors can occur: atom doesn't exist, type changed, side effects.

Solution

class TransactionalRestorer {
  async restoreWithTransaction(snapshot: Snapshot): Promise<{
    success: boolean;
    restored: string[];
    failed: string[];
    rolledBack: boolean;
  }> {
    const checkpoint = this.saveCurrentState();
    const restored: string[] = [];
    const failed: string[] = [];

    try {
      for (const [key, entry] of Object.entries(snapshot.state)) {
        try {
          await this.restoreAtom(key, entry);
          restored.push(key);
        } catch {
          failed.push(key);
          await this.rollback(checkpoint);
          return { success: false, restored, failed, rolledBack: true };
        }
      }
      return { success: failed.length === 0, restored, failed, rolledBack: false };
    } catch (error) {
      await this.rollback(checkpoint);
      return { success: false, restored: [], failed: [], rolledBack: true };
    }
  }

  private saveCurrentState() { /* ... */ }
  private async rollback(checkpoint: any) { /* ... */ }
}

Performance Issues

1. Memory Consumption

// LRU cleanup
class LRUHistoryCleaner {
  cleanup(history: Snapshot[], maxHistory = 50): Snapshot[] {
    if (history.length <= maxHistory) return history;
    return history.slice(history.length - maxHistory);
  }
}

// TTL cleanup
class TTLHistoryCleaner {
  cleanup(history: Snapshot[], ttl = 300000): Snapshot[] {
    const now = Date.now();
    return history.filter(s => now - s.timestamp < ttl);
  }
}

2. Comparison Performance

// Structural equality for immutable
function structuralEqual(a: any, b: any): boolean {
  return a === b; // For immutable, reference check is enough
}

// Lazy comparison with cache
class LazyComparator {
  private cache = new Map<string, boolean>();

  isEqual(a: any, b: any, path: string): boolean {
    const key = `${path}:${hashCode(a)}:${hashCode(b)}`;
    if (this.cache.has(key)) return this.cache.get(key)!;
    const result = deepEqual(a, b);
    this.cache.set(key, result);
    return result;
  }
}

3. UI Blocking

// Chunked restoration
async function chunkedRestore(snapshot: Snapshot, chunkSize = 10) {
  const entries = Object.entries(snapshot.state);
  for (let i = 0; i < entries.length; i += chunkSize) {
    const chunk = entries.slice(i, i + chunkSize);
    for (const [key, value] of chunk) {
      await restoreAtom(key, value);
    }
    await new Promise(resolve => setTimeout(resolve, 0)); // Let UI update
  }
}

// RequestIdleCallback
function idleCallbackRestore(snapshot: Snapshot) {
  const restoreChunk = (deadline?: IdleDeadline) => {
    if (!deadline || deadline.timeRemaining() > 0) {
      restoreNextChunk();
      if (hasMoreChunks()) requestIdleCallback(restoreChunk);
    } else {
      requestIdleCallback(restoreChunk);
    }
  };
  requestIdleCallback(restoreChunk);
}

Time-Travel as User-Facing Feature

Evolution

2015-2020: "Developer Tool"
    └─ Redux DevTools, debugging only

2020+: "UX Competitive Advantage"
    └─ Undo/Redo, version history, visible value

Production Examples

Application	Feature	Value
Google Docs	30-day history	Version restoration
Figma	Version history	Design comparison
Notion	Page history	Change rollback
VS Code	Timeline view	Local history

Technical Requirements

Requirement	Debugging	UX
Depth	20-50	100-1000+
Persistence	Memory	localStorage/DB
Performance	Background	Non-blocking
Hotkeys	No	Ctrl+Z / Ctrl+Y

Implementation Patterns

Undo/Redo

// Universal pattern (works for any library)
function useUndoRedo(timeTravel: TimeTravel) {
  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.ctrlKey && e.key === 'z') {
        e.preventDefault();
        if (e.shiftKey) {
          timeTravel.redo();
        } else {
          timeTravel.undo();
        }
      }
    };
    window.addEventListener('keydown', handleKeyDown);
    return () => window.removeEventListener('keydown', handleKeyDown);
  }, [timeTravel]);
}

// Nexus State: new SimpleTimeTravel(store)
// Zustand: createZustandTimeTravel(store) — pseudo-code
// Redux: enhanceStoreWithTimeTravel(store) — pseudo-code
// Jotai: createTimeTravelProvider(store) — pseudo-code

Version History

interface UserVersion {
  id: string;
  name: string; // "Draft 1"
  timestamp: number;
  snapshotId: string;
}

function saveVersion(name: string) {
  const snapshot = timeTravel.capture(name);
  saveToDatabase({ id: uuid(), name, timestamp: Date.now(), snapshotId: snapshot.id });
}

// For different libraries:
// - Nexus State: timeTravel.capture(name)
// - Zustand: timeTravel.saveSnapshot(name) — pseudo-code
// - Redux: dispatch(saveSnapshot(name)) — pseudo-code

Implementation Checklist

[ ] Hotkeys (Ctrl+Z / Ctrl+Y)
[ ] Visible UI (undo/redo buttons)
[ ] Availability indicators (disabled when unavailable)
[ ] Version history (with names)
[ ] Fast restoration (<100ms)
[ ] Auto-save (localStorage / DB)
[ ] Version export
[ ] Version comparison (diff view)

Adapting for Your Library

Time-travel is a universal pattern. Here's how to implement it with different libraries:

Library	Solution	Example
Nexus State	`SimpleTimeTravel`	`new SimpleTimeTravel(store)`
Zustand	Middleware	`createTimeTravelMiddleware(store)`*
Redux	Store enhancer	`enhanceStoreWithTimeTravel(store)`*
Jotai	Provider	`createTimeTravelProvider(store)`*
MobX	Reaction	`autorun(() => saveSnapshot())`
Vue/Pinia	Plugin	`app.use(timeTravelPlugin)`

*Examples marked as pseudo-code — implement for your library by analogy.

Universal pattern for all:

// 1. Create snapshot storage
const history: Snapshot[] = [];
let currentIndex = -1;

// 2. Track changes
store.subscribe((newState) => {
  history.push({ state: newState, timestamp: Date.now() });
  currentIndex++;
});

// 3. Implement navigation
function undo() {
  if (currentIndex > 0) {
    currentIndex--;
    store.setState(history[currentIndex].state);
  }
}

function redo() {
  if (currentIndex < history.length - 1) {
    currentIndex++;
    store.setState(history[currentIndex].state);
  }
}

Conclusion

Key Takeaways

Memory optimization is critical: Delta compression saves up to 90%
Batching solves frequent snapshot problem: 5 changes → 1 snapshot
Serialization needed for production: localStorage for small, IndexedDB for large
Transactionality ensures reliability: Rollback on errors
Dual nature: Debugging → UX feature

🤔 Food for Thought

What competitive advantage would time-travel give YOUR product?

Think about:

Which scenarios would benefit from undo/redo?

How would version history improve UX?

What's Next?

💡 Note: Part 3 ("Practical Implementation") is in development. Subscribe to get notified when it's published.

In Part 3 (in development):

Step-by-step implementation from scratch
Integration with React/Zustand/Redux
DevTools integration
Examples: forms, text and graphic editors

Resources

Time-Travel Debugging in State Management: Part 1 — Foundations & Patterns

eustatos — Sat, 14 Mar 2026 08:53:46 +0000

Introduction

Imagine: you're testing a checkout form. The user fills in all fields, clicks "Pay"... and gets an error.

You start debugging. But instead of reproducing the scenario again and again, you simply rewind the state back — to the moment before the error. Like in a video game where you respawn from the last checkpoint.

This is Time-Travel Debugging — the ability to move between application states over time.

💡 Key Insight: In modern applications, time-travel has evolved from exclusively a developer tool to a standalone user-facing feature that becomes a competitive product advantage.

💡 Note: The techniques and patterns in this series work for both scenarios — debugging AND user-facing undo/redo.

Use Cases

Domain	Examples	History Depth	Value
📝 Text Editors	Google Docs, Notion	500-1000 steps	Version history, undo/redo
📋 Forms & Builders	Typeform, Tilda	50-100 steps	Real-time change reversal
🎨 Graphic Editors	Figma, Canva	50-100 steps	Design experimentation
💻 Code Editors	VS Code, CodeSandbox	500+ steps	Local change history
🏗️ Low-code Platforms	Webflow, Bubble	100-200 steps	Visual version control
🎬 Video Editors	Premiere Pro, CapCut	10-20 steps	Edit operation rollback

In this article, we'll explore architectural patterns that work across all these domains — from simple forms to complex multimedia systems.

Terminology

This article uses the following terms:

Term	Description	Library Equivalents
State Unit	Minimal indivisible part of state	Universal concept
Atom	State unit in atom-based libraries	Jotai: `atom`, Recoil: `atom`, Nexus State: `atom`
Slice	Logically isolated part of state	Redux Toolkit: `createSlice`, Zustand: `state key`
Observable	Reactive object with auto-tracking	MobX: `observable`, Valtio: `proxy`, Solid.js: `signal`
Store	Container for state units (global state)	Zustand: `store`, Redux: `store`
Snapshot	State copy at a point in time	Universal term
Delta	Difference between two snapshots	Universal term

💡 Note: "State unit" is used as a universal abstraction. Depending on your library, this might be called:

Atom (Jotai, Recoil, Nexus State)

Slice / state key (Redux, Zustand)

Observable property (MobX, Valtio)

Signal (Solid.js, Preact)

Code Examples Across Libraries

// Nexus State / Jotai / Recoil
const countAtom = atom(0);

// Zustand (state unit equivalent)
const useStore = create((set) => ({
  count: 0, // ← this is a "state unit"
}));

// Redux Toolkit (state unit equivalent)
const counterSlice = createSlice({
  name: 'counter',
  initialState: { value: 0 },
  //              ^^^^^^^^^^^ this is a "state unit"
});

// MobX (state unit equivalent)
const store = makeObservable({
  count: 0, // ← this is a "state unit"
});

Why "state unit"?

Universality — works for any library (not just atom-based)
Precision — emphasizes minimality and indivisibility
Neutrality — not tied to specific library terminology

What is Time-Travel Debugging?

Definition

Time-Travel Debugging is a debugging method where the system preserves state history and allows developers to:

View previous application states
Navigate between states (forward and backward)
Analyze differences between states
Replay action sequences

Key Capabilities

interface TimeTravelAPI {
  // Navigation
  undo(): boolean;
  redo(): boolean;
  jumpTo(index: number): boolean;

  // Availability checks
  canUndo(): boolean;
  canRedo(): boolean;

  // History
  getHistory(): Snapshot[];
  getCurrentSnapshot(): Snapshot | undefined;

  // Management
  capture(action?: string): Snapshot;
  clearHistory(): void;
}

Use Cases

Debugging complex states — when bugs reproduce only after specific action sequences
Regression analysis — understanding which change caused an issue
Training & demos — step-by-step user scenario replay
Automated testing — sequence reproduction for tests

Historical Context

Early Implementations

Time-travel debugging isn't new. First significant implementations appeared in mid-2000s:

Year	System	Description
2004	Smalltalk Squeak	One of first environments with state "rollback"
2010	OmniGraffle	Undo/redo for graphic operations
2015	Redux DevTools	Popularized time-travel for web apps
2016	Elm Time Travel	Built-in support via immutable architecture
2019	Akita (Angular)	Built-in time-travel for Angular
2021	Elf (Shopify)	Reactive state management on RxJS with DevTools
2020+	Modern Libraries	Jotai, Zustand, MobX with plugins

Evolution of Approaches

Generation 1 (2010-2015): Simple undo/redo stacks

Full state copy storage
Limited history depth
No async support

Generation 2 (2015-2020): DevTools integration

Change visualization
Redux-like architecture support
Action-based tracking

Generation 3 (2020+): Optimized systems

Delta compression
Smart memory cleanup
Atomic state support
State visualizer tools

Architectural Patterns

1. Command Pattern

Classic approach where each state change is encapsulated in a command object:

interface Command<T> {
  execute(): T;
  undo(): void;
  redo(): void;
}

// For atom-based libraries (Jotai, Recoil, Nexus State)
class SetAtomCommand<T> implements Command<T> {
  constructor(
    private atom: Atom<T>,
    private newValue: T,
    private oldValue?: T
  ) {}

  execute(): T {
    this.oldValue = this.atom.get();
    this.atom.set(this.newValue);
    return this.newValue;
  }

  undo(): void {
    this.atom.set(this.oldValue!);
  }

  redo(): void {
    this.execute();
  }
}

// For Redux / Zustand (equivalent)
class SetStateCommand<T extends Record<string, any>> implements Command<T> {
  constructor(
    private store: Store<T>,
    private slice: keyof T,
    private newValue: any
  ) {}

  execute(): void {
    this.oldValue = this.store.getState()[this.slice];
    this.store.setState({ [this.slice]: this.newValue });
  }

  undo(): void {
    this.store.setState({ [this.slice]: this.oldValue });
  }

  redo(): void {
    this.execute();
  }
}

Pros:

Explicit operation representation
Easy to extend with new commands
Macro support (command grouping)

Cons:

Object creation overhead
Complexity with async operations

2. Snapshot Pattern

Preserving full state copies at key moments:

interface Snapshot {
  id: string;
  timestamp: number;
  action?: string;
  state: Record<string, AtomState>;
  metadata: {
    label?: string;
    source?: 'auto' | 'manual';
  };
}

class SnapshotManager {
  private history: Snapshot[] = [];

  capture(action?: string): Snapshot {
    const snapshot: Snapshot = {
      id: generateId(),
      timestamp: Date.now(),
      action,
      state: deepClone(this.store.getState()),
      metadata: { label: action },
    };

    this.history.push(snapshot);
    return snapshot;
  }
}

Pros:

Simple implementation
Fast restoration (direct state replacement)
Easy to serialize for export

Cons:

High memory consumption
Data duplication

3. Delta Pattern

Storing only changes between states:

interface DeltaSnapshot {
  id: string;
  type: 'delta';
  baseSnapshotId: string;
  changes: {
    [atomId: string]: {
      oldValue: any;
      newValue: any;
    };
  };
  timestamp: number;
}

class DeltaCalculator {
  computeDelta(before: Snapshot, after: Snapshot): DeltaSnapshot {
    const changes: Record<string, any> = {};

    for (const [key, value] of Object.entries(after.state)) {
      const oldValue = before.state[key]?.value;
      if (!deepEqual(oldValue, value)) {
        changes[key] = { oldValue, newValue: value };
      }
    }

    return {
      id: generateId(),
      type: 'delta',
      baseSnapshotId: before.id,
      changes,
      timestamp: Date.now(),
    };
  }
}

Pros:

Significant memory savings (up to 90% for small changes)
Precise change tracking
Ability to "apply" deltas

Cons:

Complex restoration (requires delta chain application)
Risk of "chain break" (if base snapshot is deleted)

4. Hybrid Approach

Modern approach combining snapshots and deltas:

class HybridHistoryManager {
  private fullSnapshots: Snapshot[] = [];
  private deltaChain: Map<string, DeltaSnapshot> = new Map();

  // Every N changes, create a full snapshot
  private fullSnapshotInterval = 10;
  private changesSinceFull = 0;

  add(state: State): void {
    if (this.changesSinceFull >= this.fullSnapshotInterval) {
      // Create full snapshot
      const full = this.createFullSnapshot(state);
      this.fullSnapshots.push(full);
      this.changesSinceFull = 0;
    } else {
      // Create delta
      const base = this.getLastFullSnapshot();
      const delta = this.computeDelta(base, state);
      this.deltaChain.set(delta.id, delta);
      this.changesSinceFull++;
    }
  }

  restore(index: number): State {
    const full = this.getNearestFullSnapshot(index);
    const deltas = this.getDeltasBetween(full.index, index);

    // Apply deltas to full snapshot
    return deltas.reduce(
      (state, delta) => this.applyDelta(state, delta),
      full.state
    );
  }
}

When to use:

Pattern	Use when...	Avoid when...
Command	Complex operations, macros	Simple changes, async
Snapshot	Small states, need simplicity	Large states, frequent changes
Delta	Frequent small changes	Rare large changes
Hybrid	Universal case	Very simple apps

State Storage Strategies

1. Full Snapshots

// Universal example for any library
function createFullSnapshot(store: Store): Snapshot {
  return {
    id: uuid(),
    state: JSON.parse(JSON.stringify(store.getState())),
    timestamp: Date.now(),
  };
}

// For Redux / Zustand
const snapshot = {
  state: {
    counter: { value: 5 }, // Redux slice
    user: { name: 'John' }, // Redux slice
  },
  timestamp: Date.now(),
};

// For Jotai / Nexus State
const snapshot = {
  state: {
    'count-atom-1': { value: 5, type: 'atom' },
    'user-atom-2': { value: { name: 'John' }, type: 'atom' },
  },
  timestamp: Date.now(),
};

Characteristics:

Memory: O(n × m), where n = snapshots, m = state size
Restoration: O(1) — direct replacement
Serialization: Simple

2. Deltas

// Universal example
function computeDelta(before: State, after: State): Delta {
  const changes: Record<string, Change> = {};

  for (const key of Object.keys(after)) {
    if (!deepEqual(before[key], after[key])) {
      changes[key] = {
        from: before[key],
        to: after[key],
      };
    }
  }

  return { changes, timestamp: Date.now() };
}

// Example: Redux slice
const delta = {
  changes: {
    'counter.value': { from: 5, to: 6 },
    'user.lastUpdated': { from: 1000, to: 2000 },
  },
};

// Example: Jotai atoms
const delta = {
  changes: {
    'count-atom-1': { from: 5, to: 6 },
  },
};

Characteristics:

Memory: O(n × k), where k = average change size (k << m)
Restoration: O(d) — applying d deltas
Serialization: Requires context (base snapshot)

3. Structural Sharing (Immer example)

Using immutable structures with shared references:

// Example with Immutable.js
import { Map } from 'immutable';

const state1 = Map({ count: 1, user: { name: 'John' } });
const state2 = state1.set('count', 2);

// state1 and state2 share the user object
// Only count changed

// For React + Immer (more popular approach)
import { produce } from 'immer';

const state1 = { count: 1, user: { name: 'John' } };
const state2 = produce(state1, (draft) => {
  draft.count = 2;
  // user remains the same reference
});

Characteristics:

Aspect	Immer (Proxy)	Immutable.js
Memory	O(n + m) best case	O(log n) for Persistent Data Structures
Restoration	O(1) with references	O(log n) for access
Requirements	Proxy API (ES2015+)	Specialized library
Compatibility	High (transparent objects)	Medium (special types)

Note: Characteristics may differ by implementation. For ClojureScript, Mori, and other persistent data structure libraries, complexity will vary.

4. Strategy Comparison

Strategy	Memory	Restoration	Complexity	Use Case
Full Snapshots	High	Fast	Low	Small states
Deltas	Low	Medium	Medium	Frequent small changes
Structural Sharing	Medium	Fast	High	Immutable states
Hybrid	Medium	Medium	High	Universal

What's Next?

In Part 2 ("Performance & Advanced Topics"), we'll cover:

Memory Optimization: Delta Snapshots, compression, smart cleanup
Navigation Algorithms: Undo/Redo, jumpTo, large history optimization
Transactionality: Rollback restoration, checkpoints
Performance Issues: Benchmarks, optimizations
Time-Travel as User-Facing Feature: From debugging to UX

🤔 Food for Thought

Which pattern would you choose for your project?

Think about your current project:

How often does state change?

What's the state size (small/medium/large)?

Do you need deep history (100+ steps)?

Share your choice in the comments!

Resources

Libraries with Time-Travel Support

Immutable Data Structures

GridKit Enhanced: Enterprise Features for TanStack Table Without the Pain

eustatos — Sun, 08 Mar 2026 14:28:46 +0000

TL;DR: GridKit Enhanced adds enterprise features (audit logs, analytics, validation, plugins) to TanStack Table in 2-3 days instead of 3-4 weeks of custom development. Overhead: ~5-15ms. Try the live demo →

You love TanStack Table. It's flexible, headless, gives you full control.

Then business requirements arrive:

"We need audit logging for compliance"
"Can we track how often users change sorting?"
"Users want Excel export"
"Why does the table lag with 10K rows?"
"We need analytics on user interactions"

You realize: TanStack is great, but enterprise features mean 3-4 weeks of custom development:

Event system (instead of endless useEffect chains)
Performance monitoring (metrics, alerts)
Validation (schema, checking, auto-fix)
Plugin management (audit, analytics, export)

The Solution

GridKit Enhanced is an adapter for TanStack Table that adds enterprise features without changing your existing code.

// 1. Create your TanStack table (as usual)
const tanstackTable = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
});

// 2. Wrap with GridKit (add enterprise features)
const table = createEnhancedTable(tanstackTable, {
  events: true,
  performance: true,
  plugins: [auditLogPlugin()],
});

// 3. All TanStack APIs still work + new features
table.getRowModel(); // ✅ TanStack
table.on('row:select', handler); // ✅ GridKit

Result: Enterprise features in 2-3 days instead of 3-4 weeks.

Honest warning: ~5-15ms overhead. For enterprise apps, this is an acceptable trade-off.

Why TanStack + GridKit?

TanStack Table gives you:

✅ Full control over rendering
✅ No hidden abstractions
✅ Works with any UI library
✅ TypeScript out of the box

But you build everything yourself:

Feature	TanStack	GridKit Enhanced
Basic table	✅	✅
Event system	❌	✅
Performance monitoring	❌	✅
Validation	❌	✅
Plugin ecosystem	❌	✅
Audit logging	❌	✅

GridKit provides "backend for your table":

📊 Events — instead of useEffect for tracking
📈 Metrics — instead of custom monitoring
🔌 Plugins — instead of building audit/analytics/export from scratch

Architecture

GridKit Enhanced works as an adapter layer between your code and TanStack Table.

Key principles:

Zero Migration — your TanStack code continues working
Opt-in Features — enable only what you need
Transparent Overhead — ~5-15ms for enterprise features
Type Safe — full TypeScript support

Live Demo

🎯 Try GridKit Enhanced on CodeSandbox

The demo includes 6 interactive examples:

1. Quick Start

Basic table with sorting and event tracking. Click a row → event logged.

2. Event System

See events in action: row:select, sorting:change, filtering:change, pagination:change.

3. Performance

Performance monitoring with metrics (render, sort, filter). Budget violation alerts, memory leak detection.

4. Validation

Schema validation with Zod. Auto-fix errors, validation reports.

5. Plugins

Toggle plugins on/off:

Audit Log — logs all changes
Analytics — Mixpanel integration (simulated)
Export — CSV/Excel/PDF export

6. Benchmarks

TanStack vs GridKit Enhanced comparison.

Try this (30 seconds):

Open Quick Start demo
Click a table row
Check Live Event Log — see the row:click event
Go to Plugins, enable Audit Log
Click another row
Compare the log format

Open demo in new tab →

Use Cases

Scenario 1: New Table (Greenfield)

Situation: Starting a new project, choosing table stack.

Why GridKit:

✅ Enterprise features from day one
✅ No rewriting later
✅ Best practices built-in

Setup (5 minutes):

npm install @gridkit/tanstack-adapter @tanstack/react-table

const table = createEnhancedTable(tanstackTable, {
  events: true,
  plugins: [auditLogPlugin()],
});

You get: Event tracking, audit logs, performance monitoring, ready to scale.

Scenario 2: Existing Table (Brownfield)

Situation: You have a working TanStack Table in production.

Why GridKit:

✅ Zero breaking changes — your code continues working
✅ Add features gradually
✅ Can rollback anytime

Setup (30 minutes):

npm install @gridkit/tanstack-adapter

// Before
const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
});

// After (added 1 line)
const tanstackTable = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
});
const table = createEnhancedTable(tanstackTable, {}); // Empty options = no changes

Gradual rollout:

// Week 1: Add event tracking
const table = createEnhancedTable(tanstackTable, { events: true });
table.on('row:select', (e) => analytics.track('row_selected', e.payload));

// Week 2: Add audit log
const table = createEnhancedTable(tanstackTable, {
  events: true,
  plugins: [auditLogPlugin()],
});

// Week 3: Add performance monitoring
const table = createEnhancedTable(tanstackTable, {
  events: true,
  performance: { budgets: { rowModelBuild: 16 } },
  plugins: [auditLogPlugin()],
});

You get: Zero breaking changes, gradual migration, can stop anytime.

Comparison

Criteria	New Table	Existing Table
Setup time	5 minutes	30 minutes + gradual rollout
Risks	None	Minimal (zero breaking changes)
Complexity	Low	Medium
ROI	Long-term	Immediate (if you need features)
Recommendation	✅ Start with GridKit	✅ Add gradually

Quick Start (5 Minutes)

Step 1: Install (30 seconds)

npm install @gridkit/tanstack-adapter

Step 2: Import (30 seconds)

// Before
import { useReactTable } from '@tanstack/react-table';

// After (or keep as is — it works!)
import { createEnhancedTable } from '@gridkit/tanstack-adapter';

Step 3: Create Table (2 minutes)

import { createEnhancedTable } from '@gridkit/tanstack-adapter';
import {
  createColumnHelper,
  useReactTable,
  getCoreRowModel,
} from '@tanstack/react-table';

type User = {
  id: string;
  name: string;
  email: string;
  age: number;
};

const columnHelper = createColumnHelper<User>();

const columns = [
  columnHelper.accessor('name', { header: 'Name' }),
  columnHelper.accessor('email', { header: 'Email' }),
  columnHelper.accessor('age', { header: 'Age' }),
];

const data: User[] = [
  { id: '1', name: 'John', email: 'john@example.com', age: 30 },
  { id: '2', name: 'Jane', email: 'jane@example.com', age: 25 },
];

// 1. Create TanStack table
const tanstackTable = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(),
});

// 2. Add GridKit enterprise features
const table = createEnhancedTable(tanstackTable, {
  events: true,
  performance: true,
  validation: true,
});

Step 4: First Event (2 minutes)

// Subscribe to events
table.on('row:select', (event) => {
  console.log('Row selected:', event.payload.rowId);
  analytics.track('row_selected', {
    rowId: event.payload.rowId,
    timestamp: event.timestamp,
  });
});

// Or listen to sorting changes
table.on('sorting:change', (event) => {
  api.saveUserPreferences({
    sorting: event.payload.sorting,
  });
});

Done! Enterprise table in 5 minutes.

Event System

Why Events Beat useEffect

Before (TanStack Table):

// 30+ lines for one event
useEffect(() => {
  const subscription = table.options.onStateChange?.(state);

  if (subscription?.sorting) {
    const sortingChanged = !isEqual(prevSorting, subscription.sorting);

    if (sortingChanged) {
      analytics.track('sorting_changed', {
        sorting: subscription.sorting,
        timestamp: Date.now(),
      });

      api.saveUserPreferences({
        sorting: subscription.sorting,
      });
    }

    prevSorting = subscription.sorting;
  }
}, [table]);

After (GridKit Enhanced):

// 1 line
table.on('sorting:change', (e) => analytics.track('sorting', e.payload));

Available Events

Event	Payload	Use Case
`row:select`	`{ rowId, row }`	Analytics, audit
`row:create`	`{ row, index }`	Audit, sync
`row:update`	`{ rowId, changes }`	Audit, sync
`row:delete`	`{ rowId }`	Audit, sync
`sorting:change`	`{ sorting }`	Save preferences
`filtering:change`	`{ filtering }`	Save preferences
`pagination:change`	`{ page, pageSize }`	Save preferences
`performance:budgetViolation`	`{ operation, actual, budget }`	Alerting
`validation:error`	`{ rowId, field, message }`	UI notifications

Middleware

import {
  createDebounceMiddleware,
  createLoggingMiddleware,
} from '@gridkit/tanstack-adapter';

// Debounce frequent events
table.use(
  createDebounceMiddleware({
    events: ['sorting:change', 'filtering:change'],
    wait: 300,
  })
);

// Log all events
table.use(
  createLoggingMiddleware({
    logger: customLogger,
    level: 'info',
  })
);

Performance: Honest Truth

TL;DR

GridKit Enhanced adds ~5-15ms overhead for enterprise features.

For most enterprise apps, this is negligible:

Operation	Time
Network latency (API)	50-500ms
Database query	10-100ms
User perception threshold	100ms
GridKit overhead	~5-15ms

Verdict: GridKit overhead is 10-50x smaller than network latency.

Why GridKit Doesn't "Speed Up" TanStack

GridKit Enhanced is not about speed optimization.

TanStack Table already works great. GridKit adds features that would otherwise take weeks:

Feature	What It Adds	"Cost"
Event system	Pub/sub, middleware	~2-5ms
Performance monitoring	Metrics, budgets	~1-3ms
Validation	Schema validation	~3-7ms
Plugin manager	Registration, isolation	~2-5ms
Total	All enterprise features	~5-15ms

This has a cost. But for enterprise apps, it's negligible compared to development time saved.

Detailed Benchmarks

Environment: M1 MacBook Pro, Chrome 122

Your results may vary based on hardware, browser, data.

Rows	Operation	TanStack (ms)	GridKit (ms)	Difference
100	Render	0.12	0.19	+0.07ms
	Sort	0.48	0.17	-0.31ms (faster)
	Filter	0.11	0.19	+0.08ms
1,000	Render	2.19	1.97	-0.22ms (faster)
	Sort	1.10	1.16	+0.06ms
	Filter	1.18	2.72	+1.54ms
5,000	Render	10.15	6.01	-4.14ms (faster)
	Sort	5.85	14.32	+8.47ms
	Filter	5.85	9.41	+3.56ms
10,000	Render	9.30	11.91	+2.61ms
	Sort	9.37	9.23	-0.14ms (faster)
	Filter	12.45	9.21	-3.24ms (faster)

Analysis:

Data Size	Avg Overhead	Verdict
100 rows	~0-1ms	Negligible
1,000 rows	~0-2ms	Negligible
5,000 rows	~2-9ms	Noticeable but acceptable
10,000 rows	~0-3ms	Negligible

Important:

Benchmarks are synthetic — real-world difference is usually smaller
For tables < 50,000 rows, overhead is almost always < 15ms
Some operations are faster due to GridKit caching
Some are slower due to event processing and validation
Positive difference = GridKit slower, Negative = GridKit faster

Run benchmarks yourself →

When GridKit Is the Right Choice

✅ Good fit:

Enterprise apps with audit/compliance needs
Teams valuing developer productivity
Tables with < 50,000 rows
Apps where event tracking, plugins, validation matter
Projects with deadlines (weeks vs months)

❌ Consider alternatives when:

Trading platforms (need every millisecond)
100,000+ rows with frequent updates
Maximum raw performance is critical
No enterprise feature requirements
Have time for custom implementation

The Right Question

Don't ask: "Is GridKit faster than TanStack?"

Ask:

"Is 5-15ms overhead worth saving 10+ hours of development
and getting enterprise features out of the box?"

For most enterprise teams: Yes.

ROI Math

Scenario: Team of 3 developers

Approach	Time to Implement	Time Saved
TanStack + custom features	3-4 weeks	—
GridKit Enhanced	2-3 days	~3 weeks

Savings: ~15 working days (3 weeks)

5-15ms overhead is worth 3 weeks of saved development time.

Validation

Schema-Based Validation

Use Zod, Yup, or Joi for data validation:

import { z } from 'zod';
import { createEnhancedTable } from '@gridkit/tanstack-adapter';

const userSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  age: z.number().min(0).max(150),
});

const tanstackTable = useReactTable({
  columns: [
    {
      accessorKey: 'email',
      meta: {
        validation: {
          schema: userSchema.shape.email,
          mode: 'onChange',
        },
      },
    },
  ],
  data,
  getCoreRowModel: getCoreRowModel(),
});

const table = createEnhancedTable(tanstackTable, {
  validation: {
    mode: 'strict',
    throwOnError: false,
    autoFix: true,
  },
});

Validate Rows

// Validate single row
const result = await table.validateRow(rowData, rowIndex);

if (!result.valid) {
  console.log(result.errors);
  // [{ field: 'email', message: 'Invalid email format' }]
}

// Bulk validation
const report = table.validateAll();

console.log(report.summary);
// { total: 1000, valid: 987, invalid: 13, warnings: 5 }

Compliance Reports

Generate reports for auditors:

const complianceReport = table.generateValidationReport({
  includeAllErrors: true,
  format: 'pdf',
  timestamp: new Date(),
  signedBy: currentUser.id,
});

await complianceApi.submitReport(complianceReport);

Compliance tools:

📝 Audit Log — audit trail for GDPR, HIPAA, SOX
🔒 PII Masking — protect personal data
📊 Validation Reports — auditor-ready reports

⚠️ Important: GridKit provides tools for compliance (audit logging, PII masking, validation reports), but is not certified for GDPR/HIPAA/SOX/ISO 27001.

Your team is responsible for:

Full compliance implementation

Legal review

Certification from accredited bodies

Plugin Ecosystem

Why Plugins Are Powerful

GridKit Enhanced is the only table with a full plugin architecture.*

Unlike AG Grid "modules" or Handsontable "extensions", GridKit plugins:

✅ Run in isolated sandbox
✅ Can't break table or other plugins
✅ Auto-load dependencies
✅ Have lifecycle (init/destroy)
✅ Access event bus, table instance, config

* Only table with isolated plugin system. Plugins in sandbox, don't break each other.

Analogy: GridKit plugins are like Chrome Extensions for tables.

Ready-to-Use Plugins

import {
  auditLogPlugin,
  analyticsPlugin,
  exportPlugin,
} from '@gridkit/plugins';

const table = createEnhancedTable(tanstackTable, {
  plugins: [
    // Audit logging for compliance
    auditLogPlugin({
      destination: 'api/logs',
      events: ['row:create', 'row:update', 'row:delete'],
      pii: { mask: ['email', 'ssn'] },
    }),

    // Analytics
    analyticsPlugin({
      provider: 'mixpanel',
      autoTrack: true,
    }),

    // Export
    exportPlugin({
      formats: ['csv', 'xlsx', 'pdf'],
    }),
  ],
});

Plugin Use Cases

1. Compliance Prep (GDPR/HIPAA/SOX-ready)

Situation: Need to log all changes for compliance.

Without plugins:

// 200+ lines of code
useEffect(() => {
  // Subscribe to all events
  // Log every change
  // PII masking
  // Send to server
  // Error handling
  // Retry logic
}, []);

With plugin:

auditLogPlugin({
  destination: '/api/audit',
  events: ['row:create', 'row:update', 'row:delete'],
  pii: { mask: ['email', 'ssn'] },
});
// 1 line. Done.

Saves: 2-3 weeks of development.

What Audit Log provides:

✅ Audit trail for GDPR (Art. 30), HIPAA (§164.312), SOX (§404)
✅ PII masking for data protection
✅ Validation reports for auditors

But you still need (not in GridKit):

❌ Data encryption
❌ Access Control
❌ Breach Notification
❌ Risk Assessment
❌ Certification (your responsibility)

2. Product Analytics

Situation: Need to understand how users interact with table.

Without plugins:

// Manual Mixpanel/Amplitude integration
// Track every event
// Testing
// Maintenance

With plugin:

analyticsPlugin({
  provider: 'mixpanel',
  autoTrack: true,
});
// 2 lines. All events tracked automatically.

Saves: 1-2 weeks of development.

3. User Export

Situation: Users want CSV/Excel export.

Without plugins:

// Generate CSV
// Format Excel
// Handle large data
// Download file

With plugin:

exportPlugin({
  formats: ['csv', 'xlsx', 'pdf'],
});
// Done.

Saves: 3-5 days of development.

4. Custom Plugin for Your Team

Situation: Unique business logic (e.g., sync with external system).

const syncPlugin = {
  metadata: {
    id: 'sync-external',
    name: 'External Sync',
    version: '1.0.0',
  },
  initialize: async (config, context) => {
    context.eventBus.on('row:update', async (e) => {
      await api.syncToExternal(e.payload);
    });
  },
  destroy: async () => {
    // Cleanup
  },
};

table.registerPlugin(syncPlugin);

Benefits:

Plugin is isolated — won't break table
Auto-subscribes to events
Has lifecycle (cleanup on unmount)

Available Plugins

Plugin	Description	Use Case
Audit Log	Logs all changes	Compliance-ready (GDPR, HIPAA, SOX)
Analytics	Mixpanel/Amplitude integration	Product analytics
Export	CSV/Excel/PDF export	User reports

When Plugins Are Valuable

Industry	Plugins	Why
FinTech	Audit Log, Access Control	Compliance-ready (SOX, PCI-DSS)
Healthcare	Audit Log, PII Masking	HIPAA-ready tools
E-commerce	Analytics, Export	Product insights
Enterprise SaaS	All plugins	All enterprise features
Internal Tools	Export, Validation	Team productivity
Admin Panels	Access Control, Audit	Security + audit

Comparison with Alternatives

Feature	TanStack Table	GridKit Enhanced	AG Grid Enterprise
Basic table	✅	✅	✅
Event system	❌	✅	✅
Performance Monitoring	❌	✅	⚠️ Partial
Validation	❌	✅	✅
Audit Logging	❌	✅	✅
Plugin Ecosystem	❌	✅	⚠️ Limited
Export (CSV/Excel)	❌	✅	✅
Real-time Collaboration	❌	✅	✅
Offline Support	❌	✅	❌
Cost	Free	$	$2,000+/year
Migration	N/A	5 minutes	Weeks
Bundle Size	6KB	17KB	450KB

When to Choose What

TanStack Table:

✅ Simple tables without enterprise needs
✅ $0 budget
✅ Team already knows TanStack

GridKit Enhanced:

✅ Need enterprise features
✅ Team knows TanStack
✅ Limited budget
✅ Fast migration matters

AG Grid Enterprise:

✅ Maximum features out of box
✅ Budget not a concern
✅ Ready for long migration
✅ Need vendor support

Conclusion

GridKit Enhanced is not about speeding up TanStack Table.

It's about saving development time.

Key Takeaways

Enterprise features in 2-3 days, not 3-4 weeks

Audit logs, event tracking, performance monitoring, validation, plugins — all take weeks to build. GridKit adds them in a few lines of code.

~5-15ms overhead is an acceptable trade-off

For enterprise apps, this is negligible compared to:

Network latency (50-500ms)
Database queries (10-100ms)
User perception threshold (100ms)

Zero breaking changes

Your TanStack code continues working. GridKit is an adapter wrapper, not a replacement.

Plugin Ecosystem is a unique advantage

Only table with full plugin architecture. Isolated plugins, auto dependencies, lifecycle management.

When to Choose GridKit

✅ Yes:

Enterprise apps needing compliance-ready tools
Teams valuing developer productivity
Tables with < 50,000 rows
Projects with deadlines

❌ No:

Trading platforms (need every millisecond)
100,000+ rows with frequent updates
Maximum raw performance is critical
Need ready-made certification (GDPR/HIPAA/SOX)

Try It Yourself

🎯 Live Demo on CodeSandbox

6 interactive examples. 30 seconds to try. No installation needed.

What's Next

For developers:

Install: npm install @gridkit/tanstack-adapter
Try: Quick Start
Learn: Event System or Plugins

For teams:

Evaluate: Use Cases
Calculate: ROI (3 weeks saved)

Questions? GitHub Issues — we respond within 24 hours.

GridKit Enhanced — TanStack Table with enterprise features.

Faster than building yourself. Cheaper than AG Grid. Honest about trade-offs.

Originally published at gridkit.dev

Found a bug or inaccuracy? Open an issue

Stop Using Heavy MD5 Libraries in 2026: pure-md5 Review

eustatos — Tue, 17 Feb 2026 12:06:43 +0000

In 2026, writing a new MD5 library might seem odd. The algorithm is considered outdated, browsers are gradually removing it from Web Crypto API, and Node.js documentation includes warnings about its use.

But reality is more nuanced. MD5 is still very much alive in:

File checksums (many repositories still publish MD5 hashes)
Content-based caching (cache keys derived from content)
Legacy protocols (some APIs still require MD5 signatures)
Internal identifiers (where security isn't critical)

The problem? Existing implementations are either outdated, lack TypeScript support, or don't work universally (Node.js + browser). I decided to fix this and created pure-md5 — a modern, typed, and adaptive library.

In this article, I'll share the technical decisions, architecture, and show why it might be useful in your projects.

⚠️ Important Security Warning: MD5 is cryptographically insecure. Do not use for passwords, tokens, or digital signatures. Only use for checksums, caching, and compatibility purposes.

⚠️ v0.2.2 Update: Tree-shaking support added!
• Use import { md5 } from 'pure-md5/md5' for ~1.4KB gzipped
• Full bundle: ~6KB (was <1KB)
• WHATWG streams & improved exports

Why Not Built-in `crypto`?

The first question that comes to mind: "Why a new library when Node.js has crypto and browsers have SubtleCrypto?"

Problem	Node.js `crypto`	Browser `SubtleCrypto`	pure-md5
Works in browser	❌	✅	✅
Works in Node.js	✅	❌	✅
TypeScript out of box	❌ (needs @types)	⚠️ Limited	✅
MD5 support	✅	⚠️ (being removed)	✅
Bundle size	Native	Native	~1.4KB gz¹
Dependencies	0	0	0

¹ ~1.4KB gzipped with tree-shaking (md5 only). Full bundle: ~6KB gzipped.

Key advantage of pure-md5: universality. You write code once, and it works everywhere. The library automatically selects the optimal adapter:

// Same code works in both Node.js and browser
import { md5, hashFile } from 'pure-md5';

const hash = md5('hello');
// "5d41402abc4b2a76b9719d911017c592"

const fileHash = await hashFile('large-file.bin');
// { digest: '...', bytesProcessed: 1048576 }

Tree-Shaking Support (New in v0.2.1+)

Important: pure-md5 now supports modern tree-shaking for smaller bundle sizes. Here's how to use it:

Import Strategies

For minimal bundle (recommended):

import { md5 } from 'pure-md5/md5'; // Only md5() function
// Result: ~1.4KB gzipped

For full API:

import { md5, hashFile, createMD5Stream } from 'pure-md5';
// Result: ~6KB gzipped

Why Tree-Shaking Matters

md5() alone: ~500 bytes raw, ~1.4KB gzipped
Full library: ~17KB raw, ~6KB gzipped
Tree-shaking benefits: Only included code that you actually use

Build Tool Configuration

Most modern bundlers enable tree-shaking by default:

Vite:

// vite.config.js
export default {
  optimizeDeps: {
    include: ['pure-md5/md5'] // Pre-bundle specific entry
  }
};

Webpack:

// webpack.config.js
module.exports = {
  optimization: {
    usedExports: true
  }
};

Rollup:

// rollup.config.js
export default {
  treeshake: true
};

Architecture: Adapter System

The heart of the library is an adaptive system that tries to use native APIs, falling back to pure JavaScript implementation when needed.

How Detection Works

// Simplified adapter selection logic
function detectAdapter() {
  if (typeof process !== 'undefined' && process.versions?.node) {
    return nodeAdapter; // Priority 1
  }
  if (typeof crypto !== 'undefined' && crypto.subtle) {
    return webCryptoAdapter; // Priority 2
  }
  return pureJSAdapter; // Fallback
}

This gives several advantages:

Performance: Uses native C++ code in Node.js (~1.15M ops/sec)
Compatibility: Works in older browsers with JS implementation
Future-proof: Continues working even if WebCrypto removes MD5

Working with Large Files: Streaming & Progress

For files larger than memory, use the streaming API:

import { hashFile } from 'pure-md5';

// Simple file hashing
const result = await hashFile('large-file.bin');
console.log('MD5:', result.digest);
// "5d41402abc4b2a76b9719d911017c592"

console.log('Bytes processed:', result.bytesProcessed);
// 104857600

// With progress tracking
const progress = (percent) => {
  console.log(`Progress: ${percent.toFixed(1)}%`);
};

const result = await hashFile('large-file.bin', { onProgress: progress });

Node.js Streams (Recommended for Node.js)

import { createMD5Stream } from 'pure-md5';
import fs from 'fs';

const stream = createMD5Stream();

stream.on('md5', (result) => {
  console.log('MD5:', result.digest);
  console.log('Bytes:', result.bytesProcessed);
});

fs.createReadStream('large-file.bin').pipe(stream);

WHATWG Streams (Recommended for Browsers)

import { createMD5Stream } from 'pure-md5/stream/whatwg-stream';

const stream = createMD5Stream();
const readable = new ReadableStream({
  start(controller) {
    // Your data source
    controller.enqueue('data');
    controller.close();
  }
});

const result = await readable.pipeThrough(stream).getReader().read();
console.log('MD5:', result.value.digest);

Under the Hood

The library uses streaming data processing:

class MD5Stream extends Transform {
  constructor() {
    super();
    this.hash = createMD5Context();
    this.bytesProcessed = 0;
  }

  _transform(chunk, encoding, callback) {
    this.hash.update(chunk);
    this.bytesProcessed += chunk.length;
    this.emit('progress', { bytesProcessed: this.bytesProcessed });
    callback();
  }

  _flush(callback) {
    this.emit('md5', {
      digest: this.hash.digest('hex'),
      bytesProcessed: this.bytesProcessed
    });
    callback();
  }
}

This allows hashing files of any size without memory overflow risk.

TypeScript First

In 2026, a library without types is second-class. pure-md5 is written in TypeScript 5.6+ with full type definitions.

// Full type coverage for all APIs
import { md5, hashFile, MD5Result } from 'pure-md5';

const hash: string = md5('hello');

const result: MD5Result = await hashFile('file.txt');
// result.digest: string
// result.bytesProcessed: number

No @types/md5, no any. Everything works out of the box.

Export Paths

The library provides multiple entry points for different use cases:

// Main entry (all exports)
import { md5, hashFile, createMD5Stream } from 'pure-md5';

// Tree-shakeable md5 only
import { md5 } from 'pure-md5/md5';

// Adapters
import { NodeCryptoBackend } from 'pure-md5/adapters/node';
import { WebCryptoBackend } from 'pure-md5/adapters/webcrypto';
import { PureJSBackend } from 'pure-md5/adapters/ie11';

// Detection
import { detectAdapter } from 'pure-md5/detect';

// Streaming
import { createMD5Stream } from 'pure-md5/stream';
import { createMD5Stream } from 'pure-md5/stream/whatwg-stream';

Benchmarks

Size and speed are critical metrics for frontend libraries.

Bundle Size (gzipped)

Library	Size	Dependencies
pure-md5 (md5 only)	~1.4KB	0
pure-md5 (full)	~6KB	0
md5 (pvorb/node-md5)	~3KB	3 (charenc, crypt, is-buffer)
js-md4	~2KB	0
blueimp-md5	~2KB	0
crypto-js	~4KB+	0
spark-md5	~3KB	0

Note: pure-md5 achieves smaller final sizes through tree-shaking, allowing you to import only what you use.

Speed (Operations/Second, Node.js)

Library	ops/sec
Node.js crypto	~1,200,000
pure-md5 (node adapter)	~1,150,000
pure-md5 (pure JS)	~450,000
md5 (pvorb)	~350,000
crypto-js	~380,000
spark-md5	~420,000

In Node.js, pure-md5 nearly matches native crypto performance thanks to its adapter. In browsers, the pure JS implementation is still faster than competitors due to optimizations.

Comparison with `md5` (pvorb/node-md5)

The md5 package (from pvorb/node-md5) is one of the most popular MD5 implementations (~2.5M weekly downloads). However, it has several limitations:

Key Differences

Feature	pure-md5	md5 (pvorb)
Compatibility	Node.js + Browser	Node.js only
TypeScript	✅ Out of box	❌ No types
Bundle Size	~1.4KB¹	~3KB
Dependencies	0	3 (charenc, crypt, is-buffer)
Tree-shaking	✅ Supported	❌ CommonJS only
Stream API	✅ Built-in	❌ None
Adapters	Auto-detection	One-size-fits-all
Performance	~1.15M ops/sec	~350K ops/sec
Browser streams	✅ WHATWG streams	❌ None

¹ ~1.4KB with tree-shaking (md5 only). Full bundle: ~6KB.

Usage Examples

// md5 (pvorb) - Node.js only
import md5 from 'md5';

// ❌ Won't work in browser (uses require())
const hash = md5('hello');

// pure-md5 - universal solution
import { md5 } from 'pure-md5/md5'; // Tree-shakeable

// ✅ Works everywhere (Node.js + Browser)
const hash = md5('hello');

Why is `md5` Slower?

The md5 package uses byte-by-byte string processing and auxiliary libraries for encoding:

// From md5 (pvorb) - inefficient approach
const str = new String(string);
const bytes = [];
for (let i = 0; i < str.length; i++) {
  bytes.push(str.charCodeAt(i));
}
// ... then process byte array

pure-md5 uses a more efficient approach — working with 32-bit words and optimized loops.

Practical Usage Examples

1. Verify Downloaded File Integrity

import { verifyFile } from 'pure-md5';

const isVerified = await verifyFile(
  'downloaded-file.zip',
  '5d41402abc4b2a76b9719d911017c592' // Expected hash from server
);

if (!isVerified) {
  throw new Error('File corrupted during download');
}
// Returns true or false

2. Content-Based Cache Key

import { md5 } from 'pure-md5/md5'; // Tree-shakeable import

function getCacheKey(content) {
  return `cache:${md5(content)}`;
}

const key = getCacheKey(JSON.stringify(userData));
// "cache:5d41402abc4b2a76b9719d911017c592"

3. Universal Hashing (Node + Browser)

// Single file works everywhere
import { md5 } from 'pure-md5/md5';

export function generateId(data) {
  if (typeof data === 'string') {
    return md5(data);
  }
  // For binary data (ArrayBuffer/Uint8Array)
  if (data instanceof Uint8Array || data instanceof ArrayBuffer) {
    // Convert to string for md5
    return md5(new TextDecoder().decode(data));
  }
  // For Buffer (Node.js)
  return md5(data);
}

4. Streaming API for Large Files (Node.js)

import { createMD5Stream } from 'pure-md5';
import fs from 'fs';

const stream = createMD5Stream();

stream.on('md5', (result) => {
  console.log('MD5:', result.digest);
  console.log('Bytes:', result.bytesProcessed);
});

fs.createReadStream('large-file.bin').pipe(stream);

5. Streaming API for Large Files (Browser)

import { createMD5Stream } from 'pure-md5/stream/whatwg-stream';

document.querySelector('#fileInput').addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (!file) return;

  console.log(`Hashing: ${file.name} (${file.size} bytes)`);

  const stream = createMD5Stream();
  const readable = file.stream();

  const reader = readable.pipeThrough(stream).getReader();
  const result = await reader.read();

  console.log('✅ MD5:', result.value.digest);
  console.log('📦 Size:', result.value.bytesProcessed, 'bytes');
});

6. Manual Adapter Selection

When you need explicit control over the backend:

import { NodeCryptoBackend, WebCryptoBackend, PureJSBackend } from 'pure-md5';

// Create backend instances
const nodeBackend = new NodeCryptoBackend();
const hash = await nodeBackend.hash('hello');
console.log(hash);

// Force pure JS (for testing or special environments)
const pureBackend = new PureJSBackend();
const hash2 = await pureBackend.hash('hello');

Security: Where to Use and Where Not To

Scenario	Use MD5?	Alternative
File checksums	✅	—
Cache keys	✅	—
Internal object IDs	✅	—
User passwords	❌	bcrypt, argon2
JWT tokens	❌	HS256, RS256
Digital signatures	❌	SHA-256, EdDSA

Rule: If an attacker could benefit from hash manipulation — don't use MD5.

Installation & Quick Start

npm install pure-md5
# or
yarn add pure-md5
# or
pnpm add pure-md5

Basic Usage (Tree-Shakeable)

import { md5 } from 'pure-md5/md5';

// String input
const hash = md5('hello');
// "5d41402abc4b2a76b9719d911017c592"

Full API Usage

import { md5, hashFile, createMD5Stream } from 'pure-md5';

// String input
const hash = md5('hello');
// "5d41402abc4b2a76b9719d911017c592"

// File hashing
const result = await hashFile('path/to/file.txt');

// Streaming
const stream = createMD5Stream();
fs.createReadStream('file.bin').pipe(stream);

CDN Usage

<!-- Minimal (md5 only) -->
<script src="https://unpkg.com/pure-md5@latest/md5.js"></script>
<script>
  console.log(md5('hello')); // "5d41402abc4b2a76b9719d911017c592"
</script>

<!-- Full bundle -->
<script src="https://unpkg.com/pure-md5@latest/dist/index.js"></script>
<script>
  console.log(md5('hello')); // "5d41402abc4b2a76b9719d911017c592"
</script>

Conclusion

pure-md5 doesn't try to revive MD5 for security purposes. It's a tool for specific tasks where MD5 is still used, but the implementation should be modern, typed, and universal.

If you need file checksums, cache keys, or legacy API compatibility — pure-md5 gives you the best developer experience without extra dependencies.

Links:

npm
GitHub