Error Handling

final class ZemaIssue {
  final String code;              // stable identifier for the failure type
  final String message;           // human-readable description
  final List<Object> path;        // location: String keys and int array indices
  final Object? receivedValue;    // the value that failed (may be null)
  final String? expected;         // the expected type/value (e.g. 'int', 'email')
  final Map<String, dynamic>? meta; // interpolation data used by i18n
  final ZemaSeverity severity;    // ZemaSeverity.error (default) or .warning
}

final schema = z.object({
  'user': z.object({
    'email': z.string().email(),
  }),
});

final result = schema.safeParse({
  'user': {'email': 'not-an-email'},
});

final issue = result.errors.first;

issue.code           // 'invalid_email'
issue.message        // 'Invalid email format'
issue.path           // ['user', 'email']
issue.pathString     // 'user.email'
issue.receivedValue  // 'not-an-email'
issue.severity       // ZemaSeverity.error

// Fragile — typo is invisible:
ZemaIssue(code: 'too_short', message: '...', meta: {'minn': 2}) // 'minn' → null in translation

// Safe — typo caught at compile time:
ZemaIssue(code: 'too_short', message: '...', meta: {ZemaMetaKeys.min: 2})

final result = passwordSchema.safeParse('hello123');

print(result.isSuccess);     // true
print(result.hasWarnings);   // true
for (final w in result.warnings) {
  print('${w.code}: ${w.message}'); // advisory message
}

switch (issue.code) {
  case 'invalid_email':
    showError('Please enter a valid email.');
  case 'too_short':
    showError('Input is too short.');
  case 'custom_error':
    showError(issue.message);
  default:
    showError('Validation failed.');
}

final schema = z.object({
  'user': z.object({
    'profile': z.object({
      'email': z.string().email(),
    }),
  }),
});

final result = schema.safeParse({
  'user': {'profile': {'email': 'invalid'}},
});

result.errors.first.path        // ['user', 'profile', 'email']
result.errors.first.pathString  // 'user.profile.email'

final schema = z.array(z.integer());

final result = schema.safeParse([1, 'two', 3]);

result.errors.first.path        // [1]  (int index)
result.errors.first.pathString  // '[1]'

final schema = z.object({
  'users': z.array(z.object({'email': z.string().email()})),
});

final result = schema.safeParse({
  'users': [
    {'email': 'valid@example.com'},
    {'email': 'invalid'},
  ],
});

result.errors.first.path        // ['users', 1, 'email']
result.errors.first.pathString  // 'users.[1].email'

try {
  final user = userSchema.parse(data);
  saveToDatabase(user);
} on ZemaException catch (e) {
  for (final issue in e.issues) {
    print('${issue.pathString}: ${issue.message}');
  }
}

result.errors.flatten();
// ['Invalid email format', 'Must be >= 18']

result.errors.groupByPath();
// {
//   'email': ['Invalid email format'],
//   'age':   ['Must be >= 18'],
// }

result.errors.format();
// {
//   'user': {
//     'email': {'_errors': ['Invalid email format']},
//     'age':   {'_errors': ['Must be >= 18']},
//   }
// }

result.errors.errorsAt(['email']);       // ['Invalid email format'] or null
result.errors.firstErrorAt(['email']);   // 'Invalid email format' or null
result.errors.hasErrorsAt(['email']);    // true / false

final result = schema.safeParse(formData);

if (result.isFailure) {
  final byPath = result.errors.groupByPath();

  emailField.error    = byPath['email']?.first;
  passwordField.error = byPath['password']?.first;
  ageField.error      = byPath['age']?.first;
}

final messages = result.errors.flatten().join('\n');
showDialog(content: Text(messages));

if (result.isFailure) {
  final first = result.errors.first;
  showSnackBar('${first.pathString}: ${first.message}');
}

z.string()
    .min(5, message: 'Username must be at least 5 characters.')
    .max(20, message: 'Username cannot exceed 20 characters.')
    .regex(
      RegExp(r'^[a-zA-Z0-9_]+$'),
      message: 'Only letters, numbers, and underscores.',
    );

z.object({
  'startDate': z.dateTime(),
  'endDate':   z.dateTime(),
}).refine(
  (data) => (data['endDate'] as DateTime).isAfter(data['startDate'] as DateTime),
  message: 'End date must be after start date.',
  code: 'invalid_range',
);

ZemaErrorMap.setErrorMap((issue, ctx) {
  // ctx.code, ctx.defaultMessage, ctx.meta are available
  switch (issue.code) {
    case 'invalid_email':
      return 'Please enter a valid email address.';
    case 'too_short':
      final min = issue.meta?['min'];
      return min != null ? 'Must be at least $min characters.' : null;
    default:
      return null;  // keep default
  }
});

ZemaErrorMap.clearErrorMap();

ZemaErrorMap.setLocale('fr');  // all subsequent messages use French

final translated = result.errors.translate();
// same List<ZemaIssue> with messages in the current locale

ZemaI18n.registerTranslations('de', {
  'invalid_email': (_) => 'Ungültige E-Mail-Adresse.',
  'too_short': (p) => 'Mindestens ${p?['min']} Zeichen erforderlich.',
  'too_big': (p) => 'Darf maximal ${p?['max']} betragen.',
  // add entries for any code you need to translate
});

ZemaErrorMap.setLocale('de');