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

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

References

Skill Reference Files

• [Anti-Patterns](references/anti-patterns.md) - Code examples of common anti-patterns with corrections
• [Type Safety Examples](references/type-safety-examples.md) - 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).