TypeScript Basics - Code Standards

TypeScript Code Standards

Style Guide Compliance

// ✅ Good: Clear, documented, well-structured code
interface EmailDeliveryScore {
  overallScore: number;
  confidence: number;
  componentScores: {
    engagement: number;
    quality: number;
    technical: number;
  };
}

interface HistoricalPerformance {
  campaigns?: CampaignMetrics[];
  averagePerformance?: number;
  trendDirection?: 'improving' | 'declining' | 'stable';
}

interface CampaignMetrics {
  id: string;
  performance: number;
  date: string;
}

/**

 * Calculate comprehensive email delivery score using multiple metrics.

 *

 * This function analyzes recipient engagement patterns, content quality,

 * technical deliverability factors, and historical performance to provide

 * a weighted delivery score.

 *

 * @param recipientEngagement - Historical engagement rate (0.0-1.0)

 * @param contentQuality - AI-evaluated content score (0.0-1.0)

 * @param technicalScore - Technical deliverability score (0.0-1.0)

 * @param historicalPerformance - Optional historical metrics for trend analysis

 * @returns Comprehensive delivery score with confidence interval

 * @throws {Error} If any score is outside valid range (0.0-1.0)

 *

 * @example

 * ```typescript

 * const score = calculateEmailDeliveryScore(0.85, 0.92, 0.88);

 * console.log(score.overallScore); // 0.88

 * ```
 */
function calculateEmailDeliveryScore(
  recipientEngagement: number,
  contentQuality: number,
  technicalScore: number,
  historicalPerformance?: HistoricalPerformance
): EmailDeliveryScore {
  // Validate input parameters
  const scoreParams = [
    { name: 'recipientEngagement', value: recipientEngagement },
    { name: 'contentQuality', value: contentQuality },
    { name: 'technicalScore', value: technicalScore }
  ];

  for (const param of scoreParams) {
    if (typeof param.value !== 'number' || param.value < 0.0 || param.value > 1.0) {
      throw new Error(`${param.name} must be a number between 0.0 and 1.0`);
    }
  }

  // Calculate weighted score with confidence based on data quality
  const weights = {
    engagement: 0.4,
    quality: 0.35,
    technical: 0.25
  };

  const baseScore =
    recipientEngagement * weights.engagement +
    contentQuality * weights.quality +
    technicalScore * weights.technical;

  // Adjust confidence based on historical data availability
  let confidence = 0.7; // Base confidence

  if (historicalPerformance) {
    confidence += 0.2; // Increase confidence with historical data

    const campaignCount = historicalPerformance.campaigns?.length || 0;
    if (campaignCount > 10) {
      confidence += 0.1; // More confidence with more data
    }
  }

  return {
    overallScore: Math.round(baseScore * 1000) / 1000,
    confidence: Math.min(confidence, 1.0),
    componentScores: {
      engagement: recipientEngagement,
      quality: contentQuality,
      technical: technicalScore
    }
  };
}

// ❌ Bad: Poor documentation, unclear variable names, magic numbers
function calc(x: number, y: number, z: number): EmailDeliveryScore {
  const s = x * 0.4 + y * 0.35 + z * 0.25;
  return {
    overallScore: s,
    confidence: 0.7,
    componentScores: { engagement: x, quality: y, technical: z }
  };
}

Documentation Standards

interface EmailCampaignAnalytics {
  campaignId: string;
  sentCount: number;
  deliveredCount: number;
  openedCount: number;
  clickedCount: number;
  bouncedCount: number;
  complainedCount: number;
  createdAt: Date;
  deliveryRate?: number;
  openRate?: number;
  clickRate?: number;
}

/**

 * Analytics data for email campaign performance.
 */
class EmailCampaignAnalyticsService {
  constructor(private readonly analytics: EmailCampaignAnalytics) {}

  /**

   * Calculate delivery rate as percentage.
   */
  getDeliveryRate(): number {
    if (this.analytics.sentCount === 0) {
      return 0.0;
    }
    return (this.analytics.deliveredCount / this.analytics.sentCount) * 100;
  }

  /**

   * Calculate open rate as percentage of delivered emails.
   */
  getOpenRate(): number {
    if (this.analytics.deliveredCount === 0) {
      return 0.0;
    }
    return (this.analytics.openedCount / this.analytics.deliveredCount) * 100;
  }

  /**

   * Calculate click rate as percentage of delivered emails.
   */
  getClickRate(): number {
    if (this.analytics.deliveredCount === 0) {
      return 0.0;
    }
    return (this.analytics.clickedCount / this.analytics.deliveredCount) * 100;
  }

  /**

   * Convert analytics to dictionary format.

   *

   * @param includeCalculated - Whether to include calculated rates

   * @returns Dictionary representation of analytics data
   */
  toDictionary(includeCalculated: boolean = true): Record<string, number | string> {
    const data: Record<string, number | string> = {
      campaignId: this.analytics.campaignId,
      sentCount: this.analytics.sentCount,
      deliveredCount: this.analytics.deliveredCount,
      openedCount: this.analytics.openedCount,
      clickedCount: this.analytics.clickedCount,
      bouncedCount: this.analytics.bouncedCount,
      complainedCount: this.analytics.complainedCount,
      createdAt: this.analytics.createdAt.toISOString()
    };

    if (includeCalculated) {
      data.deliveryRate = this.getDeliveryRate();
      data.openRate = this.getOpenRate();
      data.clickRate = this.getClickRate();
    }

    return data;
  }
}