1---
2title: Honor Liskov Substitution Principle
3impact: HIGH
4impactDescription: Ensures implementations are truly interchangeable without breaking callers
5tags: dependency-injection, inheritance, solid, lsp
6---
7 
8## Honor Liskov Substitution Principle
9 
10Subtypes must be substitutable for their base types without altering program correctness. In NestJS with dependency injection, this means any implementation of an interface or abstract class must honor the contract completely. A mock payment service used in tests must behave like a real payment service (return similar shapes, handle errors the same way). Violating LSP causes subtle bugs when swapping implementations.
11 
12**Incorrect (implementation violates the contract):**
13 
14```typescript
15// Base interface with clear contract
16interface PaymentGateway {
17  /**
18   * Charges the specified amount.
19   * @returns PaymentResult on success
20   * @throws PaymentFailedException on payment failure
21   */
22  charge(amount: number, currency: string): Promise<PaymentResult>;
23}
24 
25// Production implementation - follows the contract
26@Injectable()
27export class StripeService implements PaymentGateway {
28  async charge(amount: number, currency: string): Promise<PaymentResult> {
29    const response = await this.stripe.charges.create({ amount, currency });
30    return { success: true, transactionId: response.id, amount };
31  }
32}
33 
34// Mock that violates LSP - different behavior!
35@Injectable()
36export class MockPaymentService implements PaymentGateway {
37  async charge(amount: number, currency: string): Promise<PaymentResult> {
38    // VIOLATION 1: Throws for valid input (contract says return PaymentResult)
39    if (amount > 1000) {
40      throw new Error('Mock does not support large amounts');
41    }
42 
43    // VIOLATION 2: Returns null instead of PaymentResult
44    if (currency !== 'USD') {
45      return null as any; // Real service would convert or reject properly
46    }
47 
48    // VIOLATION 3: Missing required field
49    return { success: true } as PaymentResult; // Missing transactionId!
50  }
51}
52 
53// Consumer trusts the contract
54@Injectable()
55export class OrdersService {
56  constructor(@Inject(PAYMENT_GATEWAY) private payment: PaymentGateway) {}
57 
58  async checkout(order: Order): Promise<void> {
59    const result = await this.payment.charge(order.total, order.currency);
60    // These fail with MockPaymentService:
61    await this.saveTransaction(result.transactionId); // undefined!
62    await this.sendReceipt(result); // might be null!
63  }
64}
65```
66 
67**Correct (implementations honor the contract):**
68 
69```typescript
70// Well-defined interface with documented behavior
71interface PaymentGateway {
72  /**
73   * Charges the specified amount.
74   * @param amount - Amount in smallest currency unit (cents)
75   * @param currency - ISO 4217 currency code
76   * @returns PaymentResult with transactionId, success status, and amount
77   * @throws PaymentFailedException if charge is declined
78   * @throws InvalidCurrencyException if currency is not supported
79   */
80  charge(amount: number, currency: string): Promise<PaymentResult>;
81 
82  /**
83   * Refunds a previous charge.
84   * @throws TransactionNotFoundException if transactionId is invalid
85   */
86  refund(transactionId: string, amount?: number): Promise<RefundResult>;
87}
88 
89// Production implementation
90@Injectable()
91export class StripeService implements PaymentGateway {
92  async charge(amount: number, currency: string): Promise<PaymentResult> {
93    try {
94      const response = await this.stripe.charges.create({ amount, currency });
95      return {
96        success: true,
97        transactionId: response.id,
98        amount: response.amount,
99      };
100    } catch (error) {
101      if (error.type === 'card_error') {
102        throw new PaymentFailedException(error.message);
103      }
104      throw error;
105    }
106  }
107 
108  async refund(transactionId: string, amount?: number): Promise<RefundResult> {
109    // Implementation...
110  }
111}
112 
113// Mock that honors LSP - same contract, same behavior shape
114@Injectable()
115export class MockPaymentService implements PaymentGateway {
116  private transactions = new Map<string, PaymentResult>();
117 
118  async charge(amount: number, currency: string): Promise<PaymentResult> {
119    // Honor the contract: validate currency like real service would
120    if (!['USD', 'EUR', 'GBP'].includes(currency)) {
121      throw new InvalidCurrencyException(`Unsupported currency: ${currency}`);
122    }
123 
124    // Simulate decline for specific test scenarios
125    if (amount === 99999) {
126      throw new PaymentFailedException('Card declined (test scenario)');
127    }
128 
129    // Return same shape as production
130    const result: PaymentResult = {
131      success: true,
132      transactionId: `mock_${Date.now()}_${Math.random().toString(36)}`,
133      amount,
134    };
135 
136    this.transactions.set(result.transactionId, result);
137    return result;
138  }
139 
140  async refund(transactionId: string, amount?: number): Promise<RefundResult> {
141    // Honor the contract: throw if transaction not found
142    if (!this.transactions.has(transactionId)) {
143      throw new TransactionNotFoundException(transactionId);
144    }
145 
146    return {
147      success: true,
148      refundId: `refund_${transactionId}`,
149      amount: amount ?? this.transactions.get(transactionId)!.amount,
150    };
151  }
152}
153 
154// Consumer can swap implementations safely
155@Injectable()
156export class OrdersService {
157  constructor(@Inject(PAYMENT_GATEWAY) private payment: PaymentGateway) {}
158 
159  async checkout(order: Order): Promise<Order> {
160    try {
161      const result = await this.payment.charge(order.total, order.currency);
162      // Works with both StripeService and MockPaymentService
163      order.transactionId = result.transactionId;
164      order.status = 'paid';
165      return order;
166    } catch (error) {
167      if (error instanceof PaymentFailedException) {
168        order.status = 'payment_failed';
169        return order;
170      }
171      throw error;
172    }
173  }
174}
175```
176 
177**Testing LSP compliance:**
178 
179```typescript
180// Shared test suite that any implementation must pass
181function testPaymentGatewayContract(
182  createGateway: () => PaymentGateway,
183) {
184  describe('PaymentGateway contract', () => {
185    let gateway: PaymentGateway;
186 
187    beforeEach(() => {
188      gateway = createGateway();
189    });
190 
191    it('returns PaymentResult with all required fields', async () => {
192      const result = await gateway.charge(1000, 'USD');
193      expect(result).toHaveProperty('success');
194      expect(result).toHaveProperty('transactionId');
195      expect(result).toHaveProperty('amount');
196      expect(typeof result.transactionId).toBe('string');
197    });
198 
199    it('throws InvalidCurrencyException for unsupported currency', async () => {
200      await expect(gateway.charge(1000, 'INVALID'))
201        .rejects.toThrow(InvalidCurrencyException);
202    });
203 
204    it('throws TransactionNotFoundException for invalid refund', async () => {
205      await expect(gateway.refund('nonexistent'))
206        .rejects.toThrow(TransactionNotFoundException);
207    });
208  });
209}
210 
211// Run against all implementations
212describe('StripeService', () => {
213  testPaymentGatewayContract(() => new StripeService(mockStripeClient));
214});
215 
216describe('MockPaymentService', () => {
217  testPaymentGatewayContract(() => new MockPaymentService());
218});
219```
220 
221Reference: [Liskov Substitution Principle](https://en.wikipedia.org/wiki/Liskov_substitution_principle)
222