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).