feat: Add file validation with l.file() and @IsFile code generation support

Author: exaby73

docs/astro.config.mjs

@@ -73,6 +73,10 @@ export default defineConfig({
               label: 'String',
               link: '/single-values/string',
             },
+            {
+              label: 'File',
+              link: '/single-values/file',
+            },
             {
               label: 'Null',
               link: '/single-values/null',

docs/src/content/docs/schemas/code-generation.mdx

@@ -503,6 +503,33 @@ The generator automatically:
 - Omits `.required()` from element validators when elements are nullable (`List<T?>`)
 - Makes the list itself optional when the field is nullable (`List<T>?`)
 
+## File Validation with Code Generation
+
+Use `@IsFile()` (or `@isFile`) when a field should be validated with `l.file()`.
+
+```dart
+@luthor
+@freezed
+abstract class FileUpload with _$FileUpload {
+  const factory FileUpload({
+    @IsFile() required Object profileImage,
+    String? description,
+  }) = _FileUpload;
+
+  factory FileUpload.fromJson(Map<String, dynamic> json) =>
+      _$FileUploadFromJson(json);
+}
+```
+
+### Generated File Validation
+
+```dart
+Validator $FileUploadSchema = l.withName('FileUpload').schema({
+  FileUploadSchemaKeys.profileImage: l.file().required(),
+  FileUploadSchemaKeys.description: l.string(),
+});
+```
+
 ## Auto-Generation for Classes Without @luthor
 
 The code generator can automatically generate schemas for classes that don't have the `@luthor` annotation, as long as they meet certain compatibility requirements:
@@ -640,4 +667,4 @@ Validator $SignupFormSchema = l.withName('SignupForm').schema({
 4. **Automatic Detection** - Let the generator handle self-references automatically; only use `@luthorForwardRef` for cross-class circular references
 5. **Run Generation** - Run `dart run build_runner build` after making changes to annotated classes
 
-The code generation features make Luthor validation both more powerful and safer to use, providing compile-time guarantees and excellent IDE support for your validation logic.
+The code generation features make Luthor validation both more powerful and safer to use, providing compile-time guarantees and excellent IDE support for your validation logic.

docs/src/content/docs/single-values/file.mdx

@@ -0,0 +1,63 @@
+---
+title: Validating a File value
+---
+
+import CodeGenContentSwitcher from '../../../components/CodeGenContentSwitcher.astro'
+
+<CodeGenContentSwitcher>
+  <div slot="false">
+```dart
+import 'dart:typed_data';
+
+import 'package:luthor/luthor.dart';
+
+void main() {
+  final validator = l.file();
+  print(validator.validateValue(Uint8List.fromList([1, 2, 3]))); // Success
+  print(validator.validateValue('not-a-file')); // Error
+}
+```
+  </div>
+
+  <div slot="true">
+```dart
+import 'dart:typed_data';
+
+import 'package:freezed_annotation/freezed_annotation.dart';
+import 'package:luthor/luthor.dart';
+
+part 'file_schema.freezed.dart';
+part 'file_schema.g.dart';
+
+@luthor
+@freezed
+abstract class FileSchema with _$FileSchema {
+  const factory FileSchema({
+    @isFile /* OR @IsFile() */ required Object profileImage,
+    String? description,
+  }) = _FileSchema;
+
+  factory FileSchema.fromJson(Map<String, dynamic> json) =>
+      _$FileSchemaFromJson(json);
+}
+
+void main() {
+  final result = $FileSchemaValidate({
+    'profileImage': Uint8List.fromList([1, 2, 3]),
+    'description': 'Avatar upload',
+  });
+
+  switch (result) {
+    case SchemaValidationSuccess(data: final data):
+      print('✅ Valid: ${data.description}');
+    case SchemaValidationError(errors: final errors):
+      print('❌ Errors: $errors');
+  }
+}
+```
+  </div>
+</CodeGenContentSwitcher>
+
+`l.file()` validates common file-like values such as `File`, `MultipartFile`, `XFile`, `Uint8List`, and `ByteData`.
+
+When using code generation, apply `@IsFile()` (or `@isFile`) to fields that should use file validation.

packages/luthor/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 0.17.0
+
+- **FEAT**: Add support for validating files with `l.file()` validator.
+
 # 0.16.0
 
 - **FEAT**: Update version to match luthor_generator.

packages/luthor/lib/luthor.dart

@@ -8,6 +8,7 @@ export 'src/annotations/validators/date_time.dart';
 export 'src/annotations/validators/email.dart';
 export 'src/annotations/validators/emoji.dart';
 export 'src/annotations/validators/ends_with.dart';
+export 'src/annotations/validators/file.dart';
 export 'src/annotations/validators/forward_ref.dart';
 export 'src/annotations/validators/ip.dart';
 export 'src/annotations/validators/length.dart';
@@ -27,6 +28,7 @@ export 'src/validations/any_validation.dart';
 export 'src/validations/bool_validation.dart';
 export 'src/validations/custom_validation.dart';
 export 'src/validations/double_validation.dart';
+export 'src/validations/file_validation.dart';
 export 'src/validations/int_validation.dart';
 export 'src/validations/list_validation.dart';
 export 'src/validations/map_validation.dart';

packages/luthor/lib/src/annotations/validators/file.dart

@@ -0,0 +1,8 @@
+class IsFile {
+  final String? message;
+  final String? Function()? messageFn;
+
+  const IsFile({this.message, this.messageFn});
+}
+
+const isFile = IsFile();

packages/luthor/lib/src/validations/file_validation.dart

@@ -0,0 +1,34 @@
+import 'package:luthor/src/validation.dart';
+
+class FileValidation extends Validation {
+  String? customMessage;
+  String? Function()? customMessageFn;
+
+  FileValidation({String? message, String? Function()? messageFn})
+    : customMessage = message,
+      customMessageFn = messageFn;
+
+  @override
+  bool call(String? fieldName, Object? value) {
+    super.call(fieldName, value);
+    if (value == null) return false;
+
+    final typeName = value.runtimeType.toString().toLowerCase();
+    return typeName.contains('file') ||
+        typeName.contains('multipart') ||
+        typeName.contains('xfile') ||
+        typeName.contains('stream') ||
+        typeName.contains('bytes') ||
+        typeName.contains('uint8list') ||
+        typeName.contains('bytedata');
+  }
+
+  @override
+  String get message =>
+      customMessage ??
+      customMessageFn?.call() ??
+      '${fieldName ?? 'value'} must be a file';
+
+  @override
+  Map<String, List<String>>? get errors => null;
+}

packages/luthor/lib/src/validator.dart

@@ -4,6 +4,7 @@ import 'package:luthor/src/validations/any_validation.dart';
 import 'package:luthor/src/validations/bool_validation.dart';
 import 'package:luthor/src/validations/custom_validation.dart';
 import 'package:luthor/src/validations/double_validation.dart';
+import 'package:luthor/src/validations/file_validation.dart';
 import 'package:luthor/src/validations/int_validation.dart';
 import 'package:luthor/src/validations/list_validation.dart';
 import 'package:luthor/src/validations/map_validation.dart';
@@ -181,6 +182,17 @@ class Validator implements ValidatorReference {
     return newValidator;
   }
 
+  /// Validates that the value is a file.
+  Validator file({String? message, String? Function()? messageFn}) {
+    final newValidations = List<Validation>.from(validations)
+      ..add(FileValidation(message: message, messageFn: messageFn));
+    final newValidator = Validator(initialValidations: newValidations);
+    if (_name != null) {
+      newValidator._name = _name;
+    }
+    return newValidator;
+  }
+
   /// Validates that the value is a list.
   Validator list({
     List<ValidatorReference>? validators,

packages/luthor/pubspec.yaml

@@ -2,7 +2,7 @@ name: luthor
 description: |
   A Dart validation library inspired by https://zod.dev 
   with support for code generation.
-version: 0.16.0
+version: 0.17.0
 repository: https://github.com/exaby73/luthor/tree/main/packages/luthor
 homepage: https://luthor.ex3.dev
 resolution: workspace

packages/luthor/test/validations/file_validation_test.dart

@@ -0,0 +1,77 @@
+import 'dart:io';
+import 'dart:typed_data';
+
+import 'package:luthor/luthor.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('should validate File instances', () {
+    final result = l.file().validateValue(File('avatar.png'));
+
+    switch (result) {
+      case SingleValidationSuccess(data: final data):
+        expect(data, isA<File>());
+      case SingleValidationError(data: _, errors: final errors):
+        fail('expected success but got errors: $errors');
+    }
+  });
+
+  test('should validate byte arrays as file-like values', () {
+    final result = l.file().validateValue(Uint8List.fromList([1, 2, 3]));
+
+    switch (result) {
+      case SingleValidationSuccess(data: final data):
+        expect(data, isA<Uint8List>());
+      case SingleValidationError(data: _, errors: final errors):
+        fail('expected success but got errors: $errors');
+    }
+  });
+
+  test('should fail for null values', () {
+    final result = l.file().validateValue(null);
+
+    switch (result) {
+      case SingleValidationSuccess(data: _):
+        fail('should not be a success');
+      case SingleValidationError(data: _, errors: final errors):
+        expect(errors, ['value must be a file']);
+    }
+  });
+
+  test('should fail for non file-like values', () {
+    final result = l.file().validateValue('not-a-file');
+
+    switch (result) {
+      case SingleValidationSuccess(data: _):
+        fail('should not be a success');
+      case SingleValidationError(data: _, errors: final errors):
+        expect(errors, ['value must be a file']);
+    }
+  });
+
+  test('should use custom message when message is provided', () {
+    final result = l
+        .file(message: 'profileImage must be a file')
+        .validateValue('not-a-file');
+
+    switch (result) {
+      case SingleValidationSuccess(data: _):
+        fail('should not be a success');
+      case SingleValidationError(data: _, errors: final errors):
+        expect(errors, ['profileImage must be a file']);
+    }
+  });
+
+  test('should use messageFn when provided', () {
+    final result = l
+        .file(messageFn: () => 'dynamic file error')
+        .validateValue('not-a-file');
+
+    switch (result) {
+      case SingleValidationSuccess(data: _):
+        fail('should not be a success');
+      case SingleValidationError(data: _, errors: final errors):
+        expect(errors, ['dynamic file error']);
+    }
+  });
+}