Agent Skills: TypeScript Code Quality Patterns

TypeScript Code Quality Patterns

Overview

Project-specific code quality checklist for the Saleor Configurator codebase. Covers type safety conventions, error handling patterns, and architectural standards unique to this project.

When to Use

• Adding entity types, services, repositories, comparators, formatters
• Implementing deployment stages or bootstrap methods
• Creating Zod schemas or error classes
• Reviewing code before commit or PR merge

Quick Reference

| Convention | Rule | |-----------|------| | No any | Production code only; allowed in test mocks | | Branded types | Use EntitySlug, EntityName for domain values | | Error classes | Extend BaseError with error code | | GraphQL errors | Wrap with GraphQLError.fromCombinedError() | | Zod errors | Wrap with ZodValidationError.fromZodError() | | Functions | 10-50 lines ideal, ~100 max | | Style | Functional (map/filter/flatMap) over loops |

Quality Checklist

Type Safety

• [ ] No any types in production code
• [ ] No unsafe assertions (as unknown as T)
• [ ] No non-null assertions (!) without justification
• [ ] Branded types for domain values (EntitySlug, EntityName)
• [ ] Discriminated unions over inheritance
• [ ] satisfies for type validation with literal preservation
• [ ] readonly for immutable data

Clean Code

• [ ] Single responsibility per function
• [ ] Functions under 50 lines (ideally)
• [ ] Meaningful, declarative names
• [ ] Boolean names use is/has/should/can prefix
• [ ] Named constants instead of magic numbers
• [ ] Registry/strategy pattern for long conditional chains
• [ ] Arrow functions for consistency

Functional Patterns

• [ ] No direct mutation of arrays/objects
• [ ] map/filter/flatMap over for/forEach loops
• [ ] No accumulating spreads in reduce (use Map)

Error Handling

• [ ] Custom errors extend BaseError with error code
• [ ] GraphQL errors: GraphQLError.fromCombinedError()
• [ ] Zod errors: ZodValidationError.fromZodError()
• [ ] Error messages are actionable with recovery suggestions
• [ ] Error includes relevant context

Review Output Format

Structure findings as:

Critical Issues

Items that must be fixed before merge.

Important Improvements

Items that should be addressed but are not blocking.

Suggestions

Nice-to-have improvements for future consideration.

Positive Observations

Well-implemented patterns worth highlighting.

Project-Specific Conventions

• Entity identification: Slug-based (categories, products) vs Name-based (productTypes, pageTypes)
• Service pattern: Constructor DI with validator, repository, logger
• Repository pattern: GraphQL operations encapsulated, responses mapped to domain models
• Test pattern: vi.fn() mocks with schema-generated test data
• Zod-first: Define schemas before implementing logic; use z.infer<> for types

Common Mistakes

| Mistake | Fix | |---------|-----| | Using any in production code | Use unknown + type guards | | Exposing GraphQL types to services | Map to domain types in repository | | Missing error context in GraphQL calls | Include operation name in error | | Long if-else chains | Refactor to registry/strategy pattern | | Accumulating spreads in reduce | Use Map or Object.fromEntries | | Mutation in loops (push) | Use map/filter/flatMap |

References

Skill Reference Files

• Anti-Patterns - Code examples of common anti-patterns with corrections
• Type Safety Examples - Branded types, type guards, discriminated unions

Project Resources

• docs/CODE_QUALITY.md - Complete coding standards
• docs/ARCHITECTURE.md - Service patterns
• biome.json - Linting rules

Related Skills

• Complete entity workflow: See adding-entity-types for architectural patterns
• Zod standards: See designing-zod-schemas for schema review criteria
• Pre-commit checks: See validating-pre-commit for quality gate commands

Quick Reference Rule

For a condensed quick reference, see .claude/rules/code-quality.md (automatically loaded when editing src/**/*.ts files).