DeepSource MCP Server

/** * @fileoverview MetricValue value object * * This module defines the MetricValue value object which represents * a measured metric value with its unit and display formatting. */ import { ValueObject } from '../shared/value-object.js'; /** * Properties for the MetricValue value object */ interface MetricValueProps { value: number; unit: string; displayValue: string; measuredAt: Date; } /** * Value object representing a metric measurement * * Encapsulates a metric value with its unit, display formatting, * and the timestamp when it was measured. * * @example * ```typescript * const coverage = MetricValue.create(85.5, '%'); * console.log(coverage.value); // 85.5 * console.log(coverage.displayValue); // "85.5%" * * const complexity = MetricValue.create(12, 'points', '12/20'); * console.log(complexity.displayValue); // "12/20" * ``` */ export class MetricValue extends ValueObject<MetricValueProps> { // Private constructor enforces factory pattern - instances must be created via static methods // skipcq: JS-0358 - This constructor is necessary to prevent direct instantiation private constructor(props: MetricValueProps) { super(props); } /** * Creates a new MetricValue instance * * @param value - The numeric value of the metric * @param unit - The unit of measurement * @param displayValue - Optional custom display value (defaults to value + unit) * @param measuredAt - Optional measurement timestamp (defaults to now) * @returns A new MetricValue instance * @throws Error if the value is not a valid number */ static create( value: number, unit: string, displayValue?: string, measuredAt?: Date ): MetricValue { if (!Number.isFinite(value)) { throw new Error('Metric value must be a finite number'); } if (unit.length === 0) { throw new Error('Unit cannot be empty'); } const display = displayValue || `${value}${unit}`; const timestamp = measuredAt || new Date(); return new MetricValue({ value, unit, displayValue: display, measuredAt: timestamp, }); } /** * Creates a percentage metric value * * @param value - The percentage value * @param decimalPlaces - Number of decimal places to display (default: 1) * @returns A new MetricValue instance for percentages */ static createPercentage(value: number, decimalPlaces = 1): MetricValue { const displayValue = `${value.toFixed(decimalPlaces)}%`; return MetricValue.create(value, '%', displayValue); } /** * Creates a null/unknown metric value * * @param unit - The unit of measurement * @returns A new MetricValue instance representing an unknown value */ static createUnknown(unit: string): MetricValue { return MetricValue.create(0, unit, 'N/A'); } /** * Gets the numeric value */ get value(): number { return this.props.value; } /** * Gets the unit of measurement */ get unit(): string { return this.props.unit; } /** * Gets the display-formatted value */ get displayValue(): string { return this.props.displayValue; } /** * Gets the measurement timestamp */ get measuredAt(): Date { return this.props.measuredAt; } /** * Checks if this is a percentage value */ get isPercentage(): boolean { return this.props.unit === '%'; } /** * Checks if this represents an unknown/null value */ get isUnknown(): boolean { return this.props.displayValue === 'N/A'; } /** * Calculates the difference between this value and another * * @param other - The other metric value to compare * @returns The numeric difference * @throws Error if the units don't match */ difference(other: MetricValue): number { if (this.props.unit !== other.props.unit) { throw new Error('Cannot calculate difference between metrics with different units'); } return this.props.value - other.props.value; } /** * Calculates the percentage change from another value * * @param previous - The previous metric value * @returns The percentage change * @throws Error if the units don't match */ percentageChange(previous: MetricValue): number { if (this.props.unit !== previous.props.unit) { throw new Error('Cannot calculate percentage change between metrics with different units'); } if (previous.props.value === 0) { return this.props.value > 0 ? 100 : 0; } return ((this.props.value - previous.props.value) / previous.props.value) * 100; } /** * Returns a string representation of the metric value */ override toString(): string { return this.props.displayValue; } }