JSON Patterns

1// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
2// for details. All rights reserved. Use of this source code is governed by a
3// BSD-style license that can be found in the LICENSE file.
4
5/// Examples of Dart pattern matching for JSON handling:
6/// - Polymorphic JSON deserialization (discriminated unions)
7/// - Nested JSON validation with optional and omitted keys
8library;
9
10/// Represents an API response in a sealed hierarchy.
11sealed class ApiResponse {}
12
13/// Successful API response carrying data.
14class SuccessResponse implements ApiResponse {
15  final Map<String, dynamic> data;
16  SuccessResponse(this.data);
17}
18
19/// Error API response carrying an error message and code.
20class ErrorResponse implements ApiResponse {
21  final String message;
22  final int code;
23  ErrorResponse(this.message, this.code);
24}
25
26/// Parses a raw JSON map into an [ApiResponse] subtype.
27ApiResponse parseApiResponse(Map<String, dynamic> json) => switch (json) {
28  {'status': 'ok', 'data': Map<String, dynamic> data} => SuccessResponse(data),
29  {'status': 'error', 'message': String msg, 'code': int code} => ErrorResponse(
30    msg,
31    code,
32  ),
33  _ => throw FormatException('Invalid or unrecognized API response: $json'),
34};
35
36/// Validates a nested user payload with both required schema and optional keys.
37void processUserPayload(Map<String, dynamic> json) {
38  if (json case {
39    'id': String id,
40    'profile':
41        {'name': String name, 'email': String email} &&
42        final Map<String, dynamic> profile,
43    'tags': [
44      String primaryTag,
45      ...,
46    ], // Matches at least 1 element, ignores rest
47  }) {
48    // Read optional/omitted fields directly from the validated submap.
49    // Map patterns check for key existence (containsKey), so an omitted key
50    // fails matching even if typed as String?.
51    final avatarUrl = profile['avatarUrl'] as String?;
52    print(
53      'User $name ($id, $email, avatar: $avatarUrl) - Primary tag: $primaryTag',
54    );
55  } else {
56    throw FormatException('Malformed user payload structure: $json');
57  }
58}
59
60void main() {
61  // Test polymorphic deserialization
62  final success = parseApiResponse({
63    'status': 'ok',
64    'data': {'userId': '123'},
65  });
66  print('Parsed success: $success');
67
68  final error = parseApiResponse({
69    'status': 'error',
70    'message': 'Not found',
71    'code': 404,
72  });
73  print('Parsed error: $error');
74
75  // Test nested validation
76  processUserPayload({
77    'id': 'u100',
78    'profile': {
79      'name': 'Alice',
80      'email': 'alice@example.com',
81      'avatarUrl': 'https://example.com/avatar.png',
82    },
83    'tags': ['admin', 'staff'],
84  });
85}