Lib Replacement

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.