typescript-esm-utils-developer-maintainer

name

typescript-esm-utils-developer-maintainer

description

skill for developing and maintaining TypeScript utility libraries transpiled to esm. Use this skill when working on TypeScript projects that involve creating reusable utility functions, managing library structure, testing, documentation, and build processes. This includes creating new utilities, refactoring existing code, setting up testing frameworks, configuring build tools, and ensuring type safety.

TypeScript ESM Utils Developer & Maintainer

Overview

This skill provides comprehensive guidance for developing TypeScript utility libraries transpiled to ESM, including best practices for code organization, testing, documentation, and build configuration.

Workflow Decision Tree

Use this skill when:

• Creating new TypeScript utility functions or modules
• Maintaining a TypeScript library project
• Maintaining pure cjs source files
• Writing and maintaining tests for utility functions
• Configuring and maintaining build tools (tsc)
• Managing type definitions and exports
• Refactoring utility code for better performance or maintainability

Core Capabilities

1. Project Structure & Setup

• Maintain TypeScript library projects with proper folder structure
  • ./ts is the main source folder
  • ./esm is the main transpilation target folder
• Maintain package.json with appropriate scripts and dependencies
• Set up tsconfig.json for optimal settings between the lib to deliver as esm modules and the tests
• Create proper .gitignore and other config files
• Follow conventional commit messages for git commits
• Maintain a strict linting configuration with ESLint

2. Utility Function Development

• Write type-safe utility functions following TypeScript best practices
• Implement proper error handling and edge case management
• Use advanced TypeScript features (generics, conditional types, mapped types)
• Ensure functions are pure and side-effect free when appropriate

3. Testing & Quality Assurance

• Make sure no deprecated packages are used
• Set up Bun for unit testing and running scripts
• Write comprehensive test suites with edge cases
• Implement property-based testing where applicable
• Configure test coverage reporting
• Après toute modification de fichiers par l'agent : Toujours lancer le linting (bun run lint), exécuter les tests (bun test), et vérifier qu'il n'y a pas d'erreurs ou d'avertissements TypeScript (bun run build). Résoudre immédiatement toute erreur ou avertissement détecté.

4. Build & Distribution

• Support continuous ESM transpilation without warning or error
• Generate type definition files (.d.ts)

5. Documentation & Maintenance

• Audit the dependencies and make sure no vulnerable package version is used
• Write JSDoc comments for all public APIs
• Maintain changelog and version management
• Implement proper semantic versioning

Best Practices

Code Organization

• eslint.config.js is sacred: follow its rules strictly and do not modify it unless explicitly instructed
• Search for existing utilities before creating new ones
• Avoid code duplication by reusing existing utilities
• Look for linting rules and apply them consistently
  • analyse eslint.config.js for coding style rules to follow during development
• Follow strictly the linting rules
  • when coding, avoid eslint-disable comments as much as possible
    • exceptions are:
      • max-params when:
        • a callback or a sorting function with fixed signature
        • a provided or a type definition function with fixed signature
        • mocked and testing functions where parameters are fixed by the implementation or the API that is being mocked
    • @ts-ignore when:
      • unavoidable limitations due to the code being run on different environments (e.g., browser vs node) or node versions
      • unavoidable limitations due to third-party library type definitions
  • use the eslint --fix command to check and automatically fix as many code style issues automatically before analysing the possible remaining errors or warnings
• Group related utilities in feature-based modules
• Use barrel exports (index.ts files) for clean imports
• Implement proper tree-shaking support
• Follow consistent naming conventions
• Keep util functions small and focused, optimize for reusability and tree-shaking
• functions MUST have 0 or 1 parameter only
  • Follow the max-params limit of 1: Avoid functions with multiple parameters unless absolutely necessary
  • If the function requires multiple parameters, use an object as the single parameter to encapsulate them
  • The single parameter can be an optional object to allow multiple named parameters if needed that are all optional only
  • The single parameter is mandatory if at least 1 of its parameters is required for the function to operate correctly
• Do not use ; at the end of statements
  • rewrite the code to avoid needing them when a missing ; would cause a syntax error
• Use single quotes for basic strings
• Use template literals instead of string concatenation
• Prefer using named functions for better stack traces
  • else use arrow functions for anonymous functions
• Use async/await for asynchronous code instead of using callbacks or .then()/.catch()
• Prefer const over let, and never use var
• Use destructuring for objects and arrays except when the value is used only once

Type Safety

• Use strict TypeScript settings
• Leverage utility types from TypeScript standard library
• Create custom utility types for complex scenarios
• Ensure 100% type coverage

Performance

• Write efficient algorithms with O(n) complexity analysis
• Use lazy evaluation where beneficial
• Implement memoization for expensive operations
• Optimize bundle size through tree-shaking when available

Testing

• Test both happy path and error scenarios driven by edge cases
• Use table-driven tests for multiple inputs
  • All cases MUST have a descriptive test name to display in the test results
• Combine with property-based testing
• Mock external dependencies appropriately
• Maintain high test coverage (>90%)

Common Patterns

Utility Function Template

/**
 * Description of what the function does
 * @param _ - Description of the provided parameter(s)
 * @returns Description of the return value
 * @example
 * ```typescript
 * const result = utilityFunction(input);
 * ```
 */
export function utilityFunction<T, U, V, W>(_?: { t: T, u?: U, v?: V }): W {
  // Implementation
  return _
}