Refactor extend.ts: Break into smaller files and improve type system

[adrianbrowning]

Overview

The main extend.ts file has grown to 2120 lines with 82 type declarations and 11 classes. This makes it difficult to maintain, navigate, and understand. We should refactor it into a more modular structure.

Goals

1. Break extend.ts into smaller, focused files

Suggested structure:

• src/runtime/classes/ - Query builder classes

  • DbSelect.ts - Base DbSelect class
  • Run.ts - _fRun class (query execution)
  • Pagination.ts - _fOffset and _fLimit classes
  • OrderBy.ts - _fOrderBy class
  • Select.ts - _fSelect and _fSelectDistinct classes
  • Aggregation.ts - _fHaving and _fGroupBy classes
  • Where.ts - _fWhere class
  • Join.ts - _fJoin class

• src/types/ - Type definitions

  • database.ts - DATABASE, TTables, TTableSources, TArrSources types
  • query.ts - Query-related types (ClauseType, Values, etc.)
  • select.ts - Selection types (ValidSelect, GetOtherColumns, GetTableStar, etc.)
  • where.ts - Where clause types (WhereCriteria, COND_NUMERIC, COND_STRING, etc.)
  • join.ts - Join-related types (SafeJoins, MapJoinsToKnownTables, etc.)
  • transforms.ts - Type transformation utilities (MergeItems, IterateTables, etc.)

• src/utils/ - Utility functions and types

  • type-helpers.ts - Generic utility types (DeepWriteable, Filter, IsString, Trim, etc.)
  • type-conversions.ts - Prisma to TS type conversion (StrTypeToTSType, GetTSType, IsNullable, RemoveNullChar)
  • column-helpers.ts - Column extraction helpers (GetFieldsFromTable, GetColsBaseTable, GetJoinCols, IterateFields, etc.)

• src/extend.ts - Main entry point that re-exports and provides the Prisma extension

2. Create/enhance utils for common helpers

Move shared utility types and functions into dedicated utility files:

• Type transformation utilities (DeepWriteable, Filter, IsString, Trim, Prettify)
• Column/field extraction helpers (GetFieldsFromTable, GetColsBaseTable, GetJoinCols)
• Type conversion helpers (StrTypeToTSType, GetTSType, IsNullable, RemoveNullChar)

3. Clean up and reduce duplication

Areas to investigate:

• Review commented-out code (lines with /*..*/ and //) - decide whether to keep or remove
• Look for duplicate type patterns that could be consolidated
• Simplify complex type transformations where possible
• Check for redundant type guards or conditions
• Consider if any runtime functions could be extracted and shared
• Review JSDoc comments - ensure they're accurate and helpful
• Look for opportunities to use type composition instead of duplication

Specific items found:

• Commented-out helper functions around line 1245-1268 (processCriteria, processCondition)
• Commented-out join methods around lines 2070-2087 (innerJoin, leftJoin, etc.)
• Multiple similar type patterns for handling table sources vs aliases
• Potential duplication in how different classes handle the same generic parameters

Benefits

1. Improved maintainability - Easier to find and modify specific functionality
2. Better code organization - Related types and classes grouped together
3. Reduced cognitive load - Smaller files are easier to understand
4. Better IDE performance - Smaller files perform better in editors
5. Easier testing - Isolated modules can be tested independently
6. Clearer dependencies - Explicit imports show relationships between modules

Implementation Notes

• Maintain backward compatibility - the public API should remain unchanged
• Ensure all existing tests pass after refactoring
• Consider adding internal documentation about the architecture
• Review and update type exports to ensure nothing breaks
• Use explicit imports (no barrel files)

Related

This refactor will make it easier to:

• Add new features
• Fix bugs
• Onboard new contributors
• Understand the codebase architecture

---

Current stats:

• File size: 2120 lines
• Type declarations: 82
• Classes: 11
• Functions: Minimal (mostly class methods)