Library Replacement Skill

This skill provides guidelines for finding redundant custom implementations and replacing them with well-known libraries.

Purpose

Identify custom implementations that:

• •Duplicate functionality available in well-known libraries
• •Are harder to maintain than library equivalents
• •May have bugs that libraries have already solved
• •Lack the testing/documentation of established libraries

When to Apply

Apply this skill when:

• •Auditing codebase for technical debt
• •Refactoring for maintainability
• •Reducing custom code footprint
• •Standardizing on ecosystem best practices

Common Replacement Patterns

Pattern Categories

Bun-Specific Considerations

Bun provides built-in alternatives for some patterns:

Audit Checklist

When auditing code, look for:

1. Utility Functions (High Priority)

// RED FLAG: Custom implementations of common utilities
function deepClone(obj) { ... }
function debounce(fn, delay) { ... }
function retry(fn, maxAttempts) { ... }
function generateId() { return Math.random()... }

2. Error Handling Patterns (High Priority)

// RED FLAG: Custom Result type
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

// BETTER: Use neverthrow
import { Result, ok, err } from 'neverthrow';

3. Validation Logic (Medium Priority)

// RED FLAG: Manual validation
function validateEmail(email: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

// BETTER: Use zod
const emailSchema = z.string().email();

4. Date/Time Operations (Medium Priority)

// RED FLAG: Custom date formatting
function formatDate(date: Date): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  ...
}

// BETTER: Use date-fns
import { format } from 'date-fns';
format(date, 'yyyy-MM-dd');

5. Async Patterns (Medium Priority)

// RED FLAG: Custom promise utilities
async function promisePool(tasks, concurrency) { ... }
async function withTimeout(promise, ms) { ... }

// BETTER: Use p-* packages
import pLimit from 'p-limit';
import pTimeout from 'p-timeout';

Replacement Strategy

Phase 1: Audit

1. •Scan for custom utility functions
2. •Identify patterns matching library functionality
3. •Assess replacement difficulty
4. •Prioritize by impact and risk

Phase 2: Plan

For each replacement:

1. •Identify all usages of custom implementation
2. •Select appropriate library
3. •Plan migration approach (big bang vs incremental)
4. •Identify test coverage requirements

Phase 3: Replace (Concurrent Execution)

Parallelizable replacements (no shared dependencies):

• •Different utility functions in separate files
• •Independent module replacements

Sequential replacements (shared dependencies):

• •Core types used across modules
• •Shared validation schemas

Phase 4: Verify

1. •Run type checking
2. •Run all tests
3. •Review changes
4. •Verify no regressions

Difficulty Assessment

Easy Replacements

• •Drop-in function replacement
• •Same or compatible API
• •No type changes needed
• •Example: generateId() -> nanoid()

Medium Replacements

• •API differences require minor refactoring
• •Some type adjustments needed
• •Limited scope of changes
• •Example: Custom validation -> Zod schemas

Hard Replacements

• •Significant API differences
• •Type system changes
• •Wide usage across codebase
• •Example: Custom Result type -> neverthrow

Testing Considerations

Before Replacement

• •Ensure existing tests pass
• •Identify test coverage gaps
• •Document expected behavior

During Replacement

• •Keep tests passing incrementally
• •Add tests for edge cases
• •Verify library handles all cases

After Replacement

• •Full test suite must pass
• •Add integration tests if needed
• •Performance comparison if relevant

References

• •neverthrow - Type-Safe Errors
• •zod - TypeScript-first schema validation
• •date-fns - Modern date utility library
• •Sindre Sorhus's p-* packages
• •unjs packages - High-quality JS utilities