Explain Method

The explain() method provides a step-by-step breakdown of all operations applied to a collection in their execution order. This is particularly useful for debugging complex collection pipelines and understanding query optimization.

Basic Syntax

explain(): string

Examples

Basic Usage

import { collect } from 'ts-collect'

const result = collect([1, 2, 3, 4, 5])
  .filter(n => n > 2)
  .map(n => n * 2)
  .sort()
  .explain()

console.log(result)
// 1. filter(n => n > 2)
// 2. map(n => n * 2)
// 3. sort()

Working with Objects

interface User {
  id: number
  name: string
  role: string
}

const users = collect<User>([
  { id: 1, name: 'Chris', role: 'admin' },
  { id: 2, name: 'Avery', role: 'user' },
  { id: 3, name: 'Buddy', role: 'user' }
])

const explanation = users
  .where('role', 'user')
  .sortBy('name')
  .map(user => ({ ...user, role: user.role.toUpperCase() }))
  .explain()

console.log(explanation)
// 1. where(role, user)
// 2. sortBy(name)
// 3. map(user => ({ ...user, role: user.role.toUpperCase() }))

Real-world Example: E-commerce Query Debugging

interface Product {
  id: string
  name: string
  price: number
  category: string
  stock: number
}

class ProductQueryAnalyzer {
  private products: Collection<Product>

  constructor(products: Product[]) {
    this.products = collect(products)
  }

  debugCategoryQuery(category: string, minPrice: number): string {
    const query = this.products
      .where('category', category)
      .where('stock', '>', 0)
      .filter(product => product.price >= minPrice)
      .sortBy('price', 'asc')
      .map(product => ({
        id: product.id,
        name: product.name,
        price: product.price
      }))

    console.log('Query Execution Plan:')
    console.log(query.explain())

    return query.explain()
  }

  explainComplexQuery(): string {
    return this.products
      .groupBy('category')
      .map(group => ({
        category: group.first()?.category,
        count: group.count(),
        averagePrice: group.avg('price')
      }))
      .sortBy('count', 'desc')
      .explain()
  }
}

Type Safety

interface QueryMetrics {
  operation: string
  timestamp: Date
  count: number
}

const metrics = collect<QueryMetrics>([
  { operation: 'insert', timestamp: new Date(), count: 10 },
  { operation: 'update', timestamp: new Date(), count: 5 }
])

// Type-safe operation chaining with explanation
const debugInfo = metrics
  .sortBy('count')
  .where('operation', 'insert')
  .map(m => ({ ...m, analyzed: true }))
  .explain()

// Each operation in the explanation maintains type safety

Return Value

• Returns a string containing numbered steps of operations
• Each step shows the operation name and parameters when applicable
• Operations are listed in execution order
• Preserves method chaining information
• Includes all transformations and filters
• Useful for query optimization and debugging

Common Use Cases

1. Query Optimization

• Analyzing query performance
• Identifying bottlenecks
• Optimizing operation order
• Understanding data flow
• Debugging complex queries

2. Development Debugging

• Tracing operation chains
• Validating query logic
• Testing data transformations
• Debugging filter conditions
• Verifying sort operations

3. Performance Analysis

• Identifying redundant operations
• Analyzing query complexity
• Understanding data transformations
• Optimizing collection pipelines
• Debugging performance issues

4. Documentation

• Generating query documentation
• Explaining complex operations
• Creating audit trails
• Documenting data flows
• Recording transformation steps

5. Maintenance

• Troubleshooting issues
• Maintaining complex queries
• Understanding legacy code
• Refactoring operations
• Validating changes