Facade Pattern: Simplifying Complex Subsystems

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// WITHOUT jQuery (subsystem): Browser-specific, verbose
const element = document.getElementById('myElement');
if (element.addEventListener) {
    element.addEventListener('click', handler, false);
} else if (element.attachEvent) {
    element.attachEvent('onclick', handler);  // IE8
}
element.style.display = 'none';
element.style.opacity = '0';
 
// Cross-browser AJAX was extremely complex
const xhr = new XMLHttpRequest();
xhr.open('GET', '/api/data', true);
xhr.onreadystatechange = function() {
    if (xhr.readyState === 4 && xhr.status === 200) {
        // handle response
    }
};
xhr.send();
 
// WITH jQuery (Facade): Simple, consistent, cross-browser
$('#myElement')
    .click(handler)
    .hide()
    .fadeOut();
 
// AJAX simplified
$.get('/api/data', function(response) {
    // handle response
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// SLF4J Facade usage - works with ANY logging backend
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
 
public class UserService {
    // Get logger through Facade
    private static final Logger logger = LoggerFactory.getLogger(UserService.class);
    
    public User createUser(UserRequest request) {
        logger.info("Creating user with email: {}", request.getEmail());
        
        try {
            User user = userRepository.save(request.toUser());
            logger.debug("User created successfully: {}", user.getId());
            return user;
        } catch (Exception e) {
            logger.error("Failed to create user", e);
            throw e;
        }
    }
}
 
// The SAME code works with:
// - Log4j 1.x (via slf4j-log4j12)
// - Log4j 2.x (via log4j-slf4j-impl)
// - Logback (via logback-classic)
// - java.util.logging (via slf4j-jdk14)
// - Simple console output (via slf4j-simple)
 
// Just change the dependency - zero code changes!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

// WITHOUT Express (Node.js http module)
const http = require('http');
const url = require('url');
 
const server = http.createServer((req, res) => {
    const parsedUrl = url.parse(req.url, true);
    const pathname = parsedUrl.pathname;
    const method = req.method;
    
    if (method === 'GET' && pathname === '/users') {
        // Manually handle routing
        let body = '';
        req.on('data', chunk => { body += chunk; });
        req.on('end', () => {
            // Parse JSON manually
            // Handle headers manually
            res.writeHead(200, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify({ users: [] }));
        });
    } else if (method === 'POST' && pathname === '/users') {
        // Repeat similar code...
    } else {
        res.writeHead(404);
        res.end('Not Found');
    }
});
server.listen(3000);
 
// WITH Express (Facade)
const express = require('express');
const app = express();
 
app.use(express.json());  // Middleware handles parsing
 
app.get('/users', (req, res) => {
    res.json({ users: [] });  // Automatic serialization
});
 
app.post('/users', (req, res) => {
    const user = req.body;  // Already parsed
    res.status(201).json(user);
});
 
app.listen(3000);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170

// SUBSYSTEM: Complex compiler components
 
class Lexer {
    tokenize(source: string): Token[] {
        // Convert source code to tokens
        // Handle string literals, numbers, identifiers, operators
        // Track line/column for error reporting
        return tokens;
    }
}
 
class Parser {
    parse(tokens: Token[]): AST {
        // Build Abstract Syntax Tree from tokens
        // Handle precedence, associativity
        // Generate syntax errors
        return ast;
    }
}
 
class SemanticAnalyzer {
    analyze(ast: AST): AnnotatedAST {
        // Type checking
        // Symbol resolution
        // Scope analysis
        // Generate semantic errors
        return annotatedAst;
    }
}
 
class Optimizer {
    optimize(ast: AnnotatedAST): OptimizedAST {
        // Constant folding
        // Dead code elimination
        // Inlining
        return optimizedAst;
    }
}
 
class CodeGenerator {
    generate(ast: OptimizedAST, target: Target): GeneratedCode {
        // Instruction selection
        // Register allocation
        // Machine code generation
        return generatedCode;
    }
}
 
class ErrorReporter {
    report(errors: CompilerError[]): string {
        // Format errors with context
        // Suggest fixes
        // Color output
        return formattedErrors;
    }
}
 
// FACADE: Simple interface for clients
 
class CompilerFacade {
    private lexer: Lexer;
    private parser: Parser;
    private semanticAnalyzer: SemanticAnalyzer;
    private optimizer: Optimizer;
    private codeGenerator: CodeGenerator;
    private errorReporter: ErrorReporter;
 
    constructor(options: CompilerOptions = {}) {
        this.lexer = new Lexer();
        this.parser = new Parser();
        this.semanticAnalyzer = new SemanticAnalyzer();
        this.optimizer = new Optimizer(options.optimizationLevel ?? OptLevel.O1);
        this.codeGenerator = new CodeGenerator();
        this.errorReporter = new ErrorReporter(options.errorFormat ?? 'pretty');
    }
 
    /**
     * Compile source code to target format.
     * Handles all phases internally.
     */
    compile(source: string, target: Target = Target.JAVASCRIPT): CompilationResult {
        const errors: CompilerError[] = [];
 
        try {
            // Phase 1: Lexical analysis
            const tokens = this.lexer.tokenize(source);
            
            // Phase 2: Parsing
            const ast = this.parser.parse(tokens);
            
            // Phase 3: Semantic analysis
            const annotatedAst = this.semanticAnalyzer.analyze(ast);
            
            // Phase 4: Optimization
            const optimizedAst = this.optimizer.optimize(annotatedAst);
            
            // Phase 5: Code generation
            const generatedCode = this.codeGenerator.generate(optimizedAst, target);
 
            return {
                success: true,
                output: generatedCode,
                warnings: errors.filter(e => e.severity === 'warning'),
            };
 
        } catch (error) {
            if (error instanceof CompilerError) {
                errors.push(error);
            }
            
            return {
                success: false,
                errors: errors,
                errorOutput: this.errorReporter.report(errors),
            };
        }
    }
 
    /**
     * Type-check without full compilation (for IDE integration)
     */
    typeCheck(source: string): TypeCheckResult {
        try {
            const tokens = this.lexer.tokenize(source);
            const ast = this.parser.parse(tokens);
            const annotatedAst = this.semanticAnalyzer.analyze(ast);
            
            return {
                valid: true,
                types: annotatedAst.typeInfo,
            };
        } catch (error) {
            return {
                valid: false,
                errors: [error as CompilerError],
            };
        }
    }
 
    /**
     * Just parse for syntax validation
     */
    checkSyntax(source: string): SyntaxCheckResult {
        try {
            const tokens = this.lexer.tokenize(source);
            this.parser.parse(tokens);
            return { valid: true };
        } catch (error) {
            return {
                valid: false,
                error: error as CompilerError,
            };
        }
    }
}
 
// CLIENT USAGE: Dramatically simplified
 
const compiler = new CompilerFacade({ optimizationLevel: OptLevel.O2 });
 
// Full compilation
const result = compiler.compile(sourceCode, Target.WASM);
if (result.success) {
    fs.writeFileSync('output.wasm', result.output.binary);
} else {
    console.error(result.errorOutput);
}
 
// Quick syntax check for editor
const syntaxOk = compiler.checkSyntax(editorContent);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218

// SUBSYSTEM: Complex media processing components
 
class VideoDecoder {
    decode(input: Buffer, codec: VideoCodec): DecodedFrames { /* ... */ }
    getSupportedCodecs(): VideoCodec[] { /* ... */ }
    setHardwareAcceleration(enabled: boolean): void { /* ... */ }
}
 
class VideoEncoder {
    encode(frames: DecodedFrames, codec: VideoCodec, settings: EncoderSettings): Buffer { /* ... */ }
    estimateBitrate(width: number, height: number, fps: number, quality: Quality): number { /* ... */ }
}
 
class AudioProcessor {
    extract(input: Buffer): AudioStream { /* ... */ }
    transcode(audio: AudioStream, codec: AudioCodec, bitrate: number): Buffer { /* ... */ }
    normalize(audio: AudioStream): AudioStream { /* ... */ }
}
 
class ContainerMuxer {
    mux(video: Buffer, audio: Buffer, format: ContainerFormat): Buffer { /* ... */ }
    addSubtitles(container: Buffer, subtitles: SubtitleTrack[]): Buffer { /* ... */ }
    setMetadata(container: Buffer, metadata: MediaMetadata): Buffer { /* ... */ }
}
 
class ThumbnailGenerator {
    generate(frames: DecodedFrames, timestamps: number[]): Image[] { /* ... */ }
    generateAnimated(frames: DecodedFrames, options: GifOptions): Buffer { /* ... */ }
}
 
// FACADE: Simple interface for common operations
 
interface VideoConversionOptions {
    quality?: 'low' | 'medium' | 'high' | 'maximum';
    maxWidth?: number;
    maxHeight?: number;
    preserveAudioQuality?: boolean;
    generateThumbnail?: boolean;
    thumbnailTimestamp?: number;
}
 
interface ConversionResult {
    video: Buffer;
    thumbnail?: Image;
    metadata: {
        duration: number;
        resolution: { width: number; height: number };
        fileSize: number;
    };
}
 
class MediaConversionFacade {
    private videoDecoder: VideoDecoder;
    private videoEncoder: VideoEncoder;
    private audioProcessor: AudioProcessor;
    private containerMuxer: ContainerMuxer;
    private thumbnailGenerator: ThumbnailGenerator;
 
    constructor(useHardwareAcceleration: boolean = true) {
        this.videoDecoder = new VideoDecoder();
        this.videoEncoder = new VideoEncoder();
        this.audioProcessor = new AudioProcessor();
        this.containerMuxer = new ContainerMuxer();
        this.thumbnailGenerator = new ThumbnailGenerator();
 
        if (useHardwareAcceleration) {
            this.videoDecoder.setHardwareAcceleration(true);
        }
    }
 
    /**
     * Convert any video to web-optimized MP4 (H.264/AAC)
     * Suitable for web playback, progressive download, and streaming
     */
    async toWebMP4(
        input: Buffer, 
        options: VideoConversionOptions = {}
    ): Promise<ConversionResult> {
        const quality = options.quality ?? 'medium';
        
        // Decode original video
        const frames = this.videoDecoder.decode(input, this.detectCodec(input));
        
        // Calculate optimal encoding settings
        const targetResolution = this.calculateResolution(
            frames.width, 
            frames.height, 
            options.maxWidth, 
            options.maxHeight
        );
        
        const settings = this.getEncodingPreset(quality, targetResolution);
        
        // Encode video
        const encodedVideo = this.videoEncoder.encode(frames, VideoCodec.H264, settings);
        
        // Process audio
        const audioStream = this.audioProcessor.extract(input);
        const normalizedAudio = this.audioProcessor.normalize(audioStream);
        const encodedAudio = this.audioProcessor.transcode(
            normalizedAudio, 
            AudioCodec.AAC,
            options.preserveAudioQuality ? 320 : 128
        );
        
        // Mux into MP4 container
        const output = this.containerMuxer.mux(encodedVideo, encodedAudio, ContainerFormat.MP4);
        
        // Generate thumbnail if requested
        let thumbnail: Image | undefined;
        if (options.generateThumbnail) {
            const timestamp = options.thumbnailTimestamp ?? frames.duration * 0.1;
            [thumbnail] = this.thumbnailGenerator.generate(frames, [timestamp]);
        }
        
        return {
            video: output,
            thumbnail,
            metadata: {
                duration: frames.duration,
                resolution: targetResolution,
                fileSize: output.length,
            },
        };
    }
 
    /**
     * Convert to HLS format for adaptive streaming
     */
    async toHLS(
        input: Buffer, 
        qualities: Quality[] = ['360p', '720p', '1080p']
    ): Promise<HLSPackage> {
        const frames = this.videoDecoder.decode(input, this.detectCodec(input));
        const audioStream = this.audioProcessor.extract(input);
        
        const variants: HLSVariant[] = [];
        
        for (const quality of qualities) {
            const settings = this.getHLSPreset(quality);
            const encodedVideo = this.videoEncoder.encode(frames, VideoCodec.H264, settings);
            const encodedAudio = this.audioProcessor.transcode(audioStream, AudioCodec.AAC, 128);
            
            variants.push({
                quality,
                segments: this.segmentForHLS(encodedVideo, encodedAudio),
            });
        }
        
        return {
            masterPlaylist: this.generateMasterPlaylist(variants),
            variants,
        };
    }
 
    /**
     * Extract audio as MP3
     */
    async extractAudioMP3(input: Buffer, bitrate: number = 192): Promise<Buffer> {
        const audioStream = this.audioProcessor.extract(input);
        const normalized = this.audioProcessor.normalize(audioStream);
        return this.audioProcessor.transcode(normalized, AudioCodec.MP3, bitrate);
    }
 
    /**
     * Generate thumbnail at specific time
     */
    async generateThumbnail(
        input: Buffer, 
        timestampSeconds: number
    ): Promise<Image> {
        const frames = this.videoDecoder.decode(input, this.detectCodec(input));
        const [thumbnail] = this.thumbnailGenerator.generate(frames, [timestampSeconds]);
        return thumbnail;
    }
 
    /**
     * Generate animated GIF preview
     */
    async generatePreviewGif(
        input: Buffer, 
        startSeconds: number = 0,
        durationSeconds: number = 5
    ): Promise<Buffer> {
        const frames = this.videoDecoder.decode(input, this.detectCodec(input));
        return this.thumbnailGenerator.generateAnimated(frames, {
            start: startSeconds,
            duration: durationSeconds,
            width: 480,
            fps: 10,
        });
    }
 
    // Private helper methods
    private detectCodec(input: Buffer): VideoCodec { /* ... */ }
    private calculateResolution(/* ... */): Resolution { /* ... */ }
    private getEncodingPreset(quality: string, resolution: Resolution): EncoderSettings { /* ... */ }
    private getHLSPreset(quality: Quality): EncoderSettings { /* ... */ }
    private segmentForHLS(video: Buffer, audio: Buffer): HLSSegment[] { /* ... */ }
    private generateMasterPlaylist(variants: HLSVariant[]): string { /* ... */ }
}
 
// CLIENT USAGE
 
const converter = new MediaConversionFacade();
 
// Common case: Convert uploaded video to web-friendly format
const webVideo = await converter.toWebMP4(uploadedFile, {
    quality: 'high',
    maxWidth: 1920,
    generateThumbnail: true,
});
 
// Prepare for streaming
const hlsPackage = await converter.toHLS(uploadedFile, ['480p', '720p', '1080p']);
 
// Extract podcast audio
const audio = await converter.extractAudioMP3(videoFile, 128);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268

// SUBSYSTEM: Many services involved in checkout
 
interface InventoryService {
    checkAvailability(items: CartItem[]): Promise<AvailabilityResult>;
    reserveItems(items: CartItem[], reservationId: string): Promise<ReservationResult>;
    releaseReservation(reservationId: string): Promise<void>;
    commitReservation(reservationId: string): Promise<void>;
}
 
interface PricingService {
    calculateItemPrices(items: CartItem[], customerId?: string): Promise<PricedItems>;
    applyPromotions(priced: PricedItems, promotionCodes: string[]): Promise<PricedItems>;
    calculateShipping(items: PricedItems, address: Address): Promise<ShippingOptions>;
}
 
interface TaxService {
    calculateTax(items: PricedItems, shippingAddress: Address): Promise<TaxBreakdown>;
    validateTaxExemption(customerId: string): Promise<TaxExemption | null>;
}
 
interface PaymentService {
    authorize(amount: Money, paymentMethod: PaymentMethod): Promise<AuthorizationResult>;
    capture(authorizationId: string): Promise<CaptureResult>;
    refund(captureId: string, amount: Money): Promise<RefundResult>;
}
 
interface FraudService {
    assessRisk(order: OrderDetails, customer: Customer): Promise<RiskAssessment>;
}
 
interface FulfillmentService {
    createShipment(order: Order, shippingMethod: ShippingMethod): Promise<Shipment>;
    selectWarehouse(items: CartItem[], destination: Address): Promise<Warehouse>;
}
 
interface NotificationService {
    sendOrderConfirmation(order: Order, customer: Customer): Promise<void>;
    sendShippingNotification(shipment: Shipment): Promise<void>;
}
 
interface AnalyticsService {
    trackCheckoutStarted(cart: Cart): void;
    trackCheckoutCompleted(order: Order): void;
    trackCheckoutAbandoned(cart: Cart, step: string): void;
}
 
// FACADE: Unified checkout experience
 
interface CheckoutOptions {
    promotionCodes?: string[];
    shippingMethod?: ShippingMethod;
    savePaymentMethod?: boolean;
    giftMessage?: string;
    bypassFraudCheck?: boolean; // For trusted customers
}
 
interface CheckoutResult {
    success: boolean;
    order?: Order;
    confirmationNumber?: string;
    estimatedDelivery?: Date;
    error?: CheckoutError;
}
 
class CheckoutFacade {
    constructor(
        private inventory: InventoryService,
        private pricing: PricingService,
        private tax: TaxService,
        private payment: PaymentService,
        private fraud: FraudService,
        private fulfillment: FulfillmentService,
        private notifications: NotificationService,
        private analytics: AnalyticsService
    ) {}
 
    /**
     * Complete checkout in a single call.
     * Coordinates all services to convert a cart into an order.
     */
    async checkout(
        cart: Cart,
        customer: Customer,
        paymentMethod: PaymentMethod,
        shippingAddress: Address,
        options: CheckoutOptions = {}
    ): Promise<CheckoutResult> {
        
        this.analytics.trackCheckoutStarted(cart);
        let reservationId: string | null = null;
        let authorizationId: string | null = null;
 
        try {
            // Step 1: Check inventory availability
            const availability = await this.inventory.checkAvailability(cart.items);
            if (!availability.allAvailable) {
                return this.failure('INVENTORY_UNAVAILABLE', availability.unavailableItems);
            }
 
            // Step 2: Reserve inventory
            reservationId = generateReservationId();
            const reservation = await this.inventory.reserveItems(cart.items, reservationId);
            if (!reservation.success) {
                return this.failure('RESERVATION_FAILED');
            }
 
            // Step 3: Calculate final pricing
            let pricedItems = await this.pricing.calculateItemPrices(cart.items, customer.id);
            if (options.promotionCodes?.length) {
                pricedItems = await this.pricing.applyPromotions(pricedItems, options.promotionCodes);
            }
 
            // Step 4: Calculate shipping
            const shippingOptions = await this.pricing.calculateShipping(pricedItems, shippingAddress);
            const selectedShipping = options.shippingMethod 
                ?? this.selectDefaultShipping(shippingOptions);
 
            // Step 5: Calculate tax
            const taxExempt = await this.tax.validateTaxExemption(customer.id);
            const taxBreakdown = taxExempt 
                ? { total: Money.zero(), exempt: true }
                : await this.tax.calculateTax(pricedItems, shippingAddress);
 
            // Step 6: Calculate total
            const total = this.calculateTotal(pricedItems, selectedShipping, taxBreakdown);
 
            // Step 7: Fraud assessment
            if (!options.bypassFraudCheck) {
                const riskAssessment = await this.fraud.assessRisk(
                    { items: pricedItems, total, customer, shippingAddress },
                    customer
                );
                if (riskAssessment.risk === 'high') {
                    await this.inventory.releaseReservation(reservationId);
                    return this.failure('FRAUD_SUSPECTED', { riskScore: riskAssessment.score });
                }
            }
 
            // Step 8: Authorize payment
            const authorization = await this.payment.authorize(total, paymentMethod);
            if (!authorization.success) {
                await this.inventory.releaseReservation(reservationId);
                return this.failure('PAYMENT_DECLINED', authorization.declineReason);
            }
            authorizationId = authorization.id;
 
            // Step 9: Capture payment
            const capture = await this.payment.capture(authorizationId);
            if (!capture.success) {
                await this.inventory.releaseReservation(reservationId);
                return this.failure('PAYMENT_CAPTURE_FAILED');
            }
 
            // Step 10: Commit inventory and create order
            await this.inventory.commitReservation(reservationId);
            
            const order = await this.createOrder({
                customer,
                items: pricedItems,
                shipping: selectedShipping,
                tax: taxBreakdown,
                total,
                paymentId: capture.id,
                giftMessage: options.giftMessage,
            });
 
            // Step 11: Initiate fulfillment
            const warehouse = await this.fulfillment.selectWarehouse(cart.items, shippingAddress);
            const shipment = await this.fulfillment.createShipment(order, selectedShipping);
 
            // Step 12: Send notifications
            await this.notifications.sendOrderConfirmation(order, customer);
 
            // Step 13: Track analytics
            this.analytics.trackCheckoutCompleted(order);
 
            return {
                success: true,
                order,
                confirmationNumber: order.confirmationNumber,
                estimatedDelivery: shipment.estimatedDelivery,
            };
 
        } catch (error) {
            // Compensating actions for failure
            if (authorizationId) {
                await this.payment.refund(authorizationId, await this.getAuthorizedAmount(authorizationId));
            }
            if (reservationId) {
                await this.inventory.releaseReservation(reservationId);
            }
            
            this.analytics.trackCheckoutAbandoned(cart, 'error');
            
            return this.failure('SYSTEM_ERROR', { message: (error as Error).message });
        }
    }
 
    /**
     * Get a price preview without committing (for checkout UI)
     */
    async preview(
        cart: Cart,
        customer: Customer,
        shippingAddress: Address,
        options: { promotionCodes?: string[]; shippingMethod?: ShippingMethod } = {}
    ): Promise<CheckoutPreview> {
        let pricedItems = await this.pricing.calculateItemPrices(cart.items, customer.id);
        
        if (options.promotionCodes?.length) {
            pricedItems = await this.pricing.applyPromotions(pricedItems, options.promotionCodes);
        }
 
        const shippingOptions = await this.pricing.calculateShipping(pricedItems, shippingAddress);
        const selectedShipping = options.shippingMethod ?? this.selectDefaultShipping(shippingOptions);
        
        const taxBreakdown = await this.tax.calculateTax(pricedItems, shippingAddress);
        const total = this.calculateTotal(pricedItems, selectedShipping, taxBreakdown);
 
        return {
            items: pricedItems,
            shippingOptions,
            selectedShipping,
            tax: taxBreakdown,
            total,
            savings: this.calculateSavings(pricedItems),
        };
    }
 
    // Helper methods
    private failure(code: string, details?: unknown): CheckoutResult {
        return { success: false, error: { code, details } };
    }
    
    private selectDefaultShipping(options: ShippingOptions): ShippingMethod { /* ... */ }
    private calculateTotal(/* ... */): Money { /* ... */ }
    private calculateSavings(/* ... */): Money { /* ... */ }
    private createOrder(/* ... */): Promise<Order> { /* ... */ }
    private getAuthorizedAmount(id: string): Promise<Money> { /* ... */ }
}
 
// CLIENT USAGE
 
const checkout = new CheckoutFacade(
    inventoryService,
    pricingService,
    taxService,
    paymentService,
    fraudService,
    fulfillmentService,
    notificationService,
    analyticsService
);
 
// Complete checkout in one call
const result = await checkout.checkout(
    userCart,
    currentUser,
    creditCard,
    shippingAddress,
    { promotionCodes: ['SAVE10'], shippingMethod: 'express' }
);
 
if (result.success) {
    showConfirmation(result.confirmationNumber, result.estimatedDelivery);
} else {
    handleError(result.error);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

// WITHOUT SDK Facade: Raw REST API
async function uploadToS3(file: Buffer, key: string): Promise<void> {
    const timestamp = new Date().toISOString();
    const region = 'us-east-1';
    const service = 's3';
    
    // Build canonical request
    const canonicalRequest = buildCanonicalRequest(/* complex signature process */);
    
    // Calculate AWS Signature V4
    const stringToSign = buildStringToSign(timestamp, region, service, canonicalRequest);
    const signingKey = getSignatureKey(secretKey, dateStamp, region, service);
    const signature = hmacSha256(signingKey, stringToSign);
    
    // Build authorization header
    const authHeader = `AWS4-HMAC-SHA256 Credential=${accessKey}/${dateStamp}/${region}/${service}/aws4_request, SignedHeaders=${signedHeaders}, Signature=${signature}`;
    
    // Make request with retry logic
    await fetchWithRetry(`https://${bucket}.s3.${region}.amazonaws.com/${key}`, {
        method: 'PUT',
        headers: {
            'Authorization': authHeader,
            'x-amz-date': timestamp,
            'x-amz-content-sha256': sha256(file),
            'Content-Type': 'application/octet-stream',
        },
        body: file,
    });
}
 
// WITH SDK Facade: Simple, safe, correct
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
 
const s3 = new S3Client({ region: 'us-east-1' });
 
await s3.send(new PutObjectCommand({
    Bucket: bucket,
    Key: key,
    Body: file,
}));