feat: add File schema that returns a platform native File instance

Author: lubiah

index.ts

@@ -27,6 +27,7 @@ export { VineObject } from './src/schema/object/main.js'
 export { VineLiteral } from './src/schema/literal/main.js'
 export { VineBoolean } from './src/schema/boolean/main.js'
 export { VineAccepted } from './src/schema/accepted/main.js'
+export { VineFile } from './src/schema/file/main.js'
 export { BaseLiteralType } from './src/schema/base/literal.js'
 export { BaseType, BaseModifiersType } from './src/schema/base/main.js'
 export { SimpleErrorReporter } from './src/reporters/simple_error_reporter.js'

src/defaults.ts

@@ -97,6 +97,12 @@ export const messages = {
 
   'date.weekend': 'The {{ field }} field is not a weekend',
   'date.weekday': 'The {{ field }} field is not a weekday',
+
+  'file': 'The {{ field }} field must be a valid file',
+  'file.minSize': 'The {{ field }} field must be at least {{ min }} bytes in size',
+  'file.maxSize': 'The {{ field }} field must not exceed {{ max }} bytes in size',
+  'file.mimeTypes':
+    'The {{ field }} field must be one of the following mime types: {{ mimeTypes }}',
 }
 
 /**

src/schema/builder.ts

@@ -26,6 +26,7 @@ import { VineAccepted } from './accepted/main.js'
 import { group } from './object/group_builder.js'
 import { VineNativeEnum } from './enum/native_enum.js'
 import { VineUnionOfTypes } from './union_of_types/main.js'
+import { VineFile } from './file/main.js'
 import { ITYPE, OTYPE, COTYPE, IS_OF_TYPE, UNIQUE_NAME } from '../symbols.js'
 import type {
   UndefinedOptional,
@@ -185,4 +186,9 @@ export class SchemaBuilder extends Macroable {
     schemasInUse.clear()
     return new VineUnionOfTypes(schemas)
   }
+
+  /** Define a file field   */
+  file() {
+    return new VineFile()
+  }
 }

src/schema/file/main.ts

@@ -0,0 +1,37 @@
+/*
+ * vinejs
+ *
+ * (c) VineJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { SUBTYPE } from '../../symbols.js'
+import { FieldOptions, Validation } from '../../types.js'
+import { BaseLiteralType } from '../base/literal.js'
+import { isFileRule, maxSizeRule, mimeTypesRule, minSizeRule } from './rules.js'
+
+export class VineFile extends BaseLiteralType<File, File, File> {
+  [SUBTYPE] = 'file'
+
+  constructor(options?: FieldOptions, validations?: Validation<any>[]) {
+    super(options, validations || [isFileRule()])
+  }
+
+  clone() {
+    return new VineFile(this.cloneOptions(), this.cloneValidations()) as this
+  }
+
+  minSize(size: number) {
+    return this.use(minSizeRule({ min: size }))
+  }
+
+  maxSize(size: number) {
+    return this.use(maxSizeRule({ max: size }))
+  }
+
+  mimeTypes(types: string[]) {
+    return this.use(mimeTypesRule({ mimeTypes: types }))
+  }
+}

src/schema/file/rules.ts

@@ -0,0 +1,25 @@
+import { messages } from '../../defaults.js'
+import { createRule } from '../../vine/create_rule.js'
+
+export const isFileRule = createRule((value, _, field) => {
+  if (!(value instanceof File)) field.report(messages.file, 'file', field)
+})
+
+export const minSizeRule = createRule<{ min: number }>((value, options, field) => {
+  if (!(value instanceof File) || !field.isValid) return
+  if (value.size < options.min)
+    field.report(messages['file.minSize'], 'file.minSize', field, options)
+})
+
+export const maxSizeRule = createRule<{ max: number }>((value, options, field) => {
+  if (!(value instanceof File) || !field.isValid) return
+  if (value.size > options.max)
+    field.report(messages['file.maxSize'], 'file.maxSize', field, options)
+})
+
+export const mimeTypesRule = createRule<{ mimeTypes: string[] }>((value, options, field) => {
+  if (!(value instanceof File) || !field.isValid) return
+  const mimeType = value.type
+  if (!options.mimeTypes.includes(mimeType))
+    field.report(messages['file.mimeTypes'], 'file.mimeTypes', field, options)
+})

tests/integration/schema/file.spec.ts

@@ -0,0 +1,104 @@
+/*
+ * @vinejs/vine
+ *
+ * (c) VineJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { test } from '@japa/runner'
+import vine from '../../../index.js'
+
+test.group('File', () => {
+  test('fail when value is not a file', async ({ assert }) => {
+    const schema = vine.object({
+      file: vine.file(),
+    })
+
+    const data = { file: 'not-a-file' }
+    await assert.validationErrors(vine.validate({ schema, data }), [
+      {
+        field: 'file',
+        message: 'The file field must be a valid file',
+        rule: 'file',
+      },
+    ])
+  })
+
+  test('fail when file size exceeds the limit', async ({ assert }) => {
+    const schema = vine.object({
+      file: vine.file().maxSize(2 * 1024 * 1024),
+    })
+
+    const data = { file: new File(['a'.repeat(3 * 1024 * 1024)], 'file.txt') } // Simulating a file of 3MB
+    await assert.validationErrors(vine.validate({ schema, data }), [
+      {
+        field: 'file',
+        meta: {
+          max: 2 * 1024 * 1024,
+        },
+        message: `The file field must not exceed ${2 * 1024 * 1024} bytes in size`,
+        rule: 'file.maxSize',
+      },
+    ])
+  })
+
+  test('pass when value is a valid file within size limit', async ({ assert }) => {
+    const schema = vine.object({
+      file: vine.file().maxSize(2 * 1024 * 1024),
+    })
+
+    const data = { file: new File(['a'.repeat(1 * 1024 * 1024)], 'file.text') } // Simulating a file of 1MB
+    await assert.validationOutput(vine.validate({ schema, data }), data)
+  })
+
+  test('fail when file size is below the minimum limit', async ({ assert }) => {
+    const schema = vine.object({
+      file: vine.file().minSize(1 * 1024 * 1024),
+    })
+
+    const data = { file: new File(['a'.repeat(512 * 1024)], 'file.txt') } // Simulating a file of 512KB
+    await assert.validationErrors(vine.validate({ schema, data }), [
+      {
+        field: 'file',
+        meta: {
+          min: 1 * 1024 * 1024,
+        },
+        message: `The file field must be at least ${1 * 1024 * 1024} bytes in size`,
+        rule: 'file.minSize',
+      },
+    ])
+  })
+
+  test('fail when value is not a valid MIME type', async ({ assert }) => {
+    const schema = vine.object({
+      file: vine.file().mimeTypes(['text/plain']),
+    })
+
+    const data = {
+      file: new File([''], 'file.txt', { type: 'image/png' }),
+    }
+    await assert.validationErrors(vine.validate({ schema, data }), [
+      {
+        field: 'file',
+        message: 'The file field must be one of the following mime types: text/plain',
+        meta: {
+          mimeTypes: ['text/plain'],
+        },
+        rule: 'file.mimeTypes',
+      },
+    ])
+  })
+
+  test('pass when value is a valid MIME type', async ({ assert }) => {
+    const schema = vine.object({
+      file: vine.file().mimeTypes(['text/plain']),
+    })
+
+    const data = {
+      file: new File([''], 'file.txt', { type: 'text/plain' }),
+    }
+    await assert.validationOutput(vine.validate({ schema, data }), data)
+  })
+})

tests/integration/validator.spec.ts

@@ -19,6 +19,7 @@ import vine, {
   VineString,
   VineLiteral,
   VineBoolean,
+  VineFile,
 } from '../../index.js'
 import { Infer } from '../../src/types.js'
 import { ValidationError } from '../../src/errors/validation_error.js'
@@ -190,6 +191,14 @@ test.group('Validator | extend schema classes', () => {
     assert.isTrue((vine.enum(['guest', 'moderator', 'admin']) as any).hasMultipleOptions())
   })
 
+  test('extend VineFile class', ({ assert }) => {
+    VineFile.macro('isImage' as any, function (this: VineFile) {
+      return true
+    })
+
+    assert.isTrue((vine.file() as any).isImage())
+  })
+
   test('extend Vine class', ({ assert }) => {
     Vine.macro('money' as any, function (this: Vine) {
       return true

tests/unit/rules/file.spec.ts

@@ -0,0 +1,123 @@
+/*
+ * @vinejs/vine
+ *
+ * (c) VineJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { test } from '@japa/runner'
+import { validator } from '../../../factories/main.js'
+import {
+  isFileRule,
+  maxSizeRule,
+  minSizeRule,
+  mimeTypesRule,
+} from '../../../src/schema/file/rules.js'
+
+test.group('File | isFileRule', () => {
+  test('should pass when value is a valid file', () => {
+    const rule = isFileRule()
+    const file = new File([''], 'file.txt')
+    const validated = validator.execute(rule, file)
+    validated.assertSucceeded()
+  })
+
+  test('should fail when value is not a file', () => {
+    const rule = isFileRule()
+    const validated = validator.execute(rule, 123)
+    validated.assertError('The dummy field must be a valid file')
+  })
+})
+
+test.group('File | minSizeRule', () => {
+  test('should pass when file size is greater than or equal to the minimum size', () => {
+    const rule = minSizeRule({ min: 1024 }) // 1 KB
+    const file = new File(['a'.repeat(1030)], 'file.txt') // 1 KB file
+    const validated = validator.execute(rule, file)
+    validated.assertSucceeded()
+  })
+
+  test('does not run when its not valid', () => {
+    const rule = minSizeRule({ min: 1024 }) // 1 KB
+    const file = new File(['a'.repeat(1030)], 'file.txt') // 1 KB file
+    const validated = validator.withContext({ isValid: false }).execute(rule, file)
+    validated.assertSucceeded()
+  })
+
+  test('does not run when its not a file', () => {
+    const rule = minSizeRule({ min: 1024 }) // 1 KB
+    const file = 'string'
+    const validated = validator.execute(rule, file)
+    validated.assertSucceeded()
+  })
+
+  test('should fail when file size is less than the minimum size', () => {
+    const rule = minSizeRule({ min: 1024 }) // 1 KB
+    const file = new File(['a'.repeat(512)], 'file.txt') // 512 bytes file
+    const validated = validator.execute(rule, file)
+    validated.assertError('The dummy field must be at least 1024 bytes in size')
+  })
+})
+
+test.group('File | maxSizeRule', () => {
+  test('should pass when file size is less than or equal to the maximum size', () => {
+    const rule = maxSizeRule({ max: 2048 }) // 2 KB
+    const file = new File(['a'.repeat(2030)], 'file.txt') // 2 KB file
+    const validated = validator.execute(rule, file)
+    validated.assertSucceeded()
+  })
+
+  test('should fail when file size is greater than the maximum size', () => {
+    const rule = maxSizeRule({ max: 2048 }) // 2 KB
+    const file = new File(['a'.repeat(3072)], 'file.txt') // 3 KB file
+    const validated = validator.execute(rule, file)
+    validated.assertError('The dummy field must not exceed 2048 bytes in size')
+  })
+
+  test('should not run when is not valid', () => {
+    const rule = maxSizeRule({ max: 2048 }) // 2 KB
+    const file = new File(['a'.repeat(1030)], 'file.txt') // 1 KB file
+    const validated = validator.withContext({ isValid: false }).execute(rule, file)
+    validated.assertSucceeded()
+  })
+
+  test('should not run when is not a file', () => {
+    const rule = maxSizeRule({ max: 2048 }) // 2 KB
+    const file = 'string'
+    const validated = validator.execute(rule, file)
+    validated.assertSucceeded()
+  })
+})
+
+test.group('File | mimeTypesRule', () => {
+  test('should pass when file has an allowed MIME type', () => {
+    const rule = mimeTypesRule({ mimeTypes: ['text/plain', 'application/json'] })
+    const file = new File([''], 'file.txt', { type: 'text/plain' })
+    const validated = validator.execute(rule, file)
+    validated.assertSucceeded()
+  })
+
+  test('does not run when is not a file', () => {
+    const rule = mimeTypesRule({ mimeTypes: ['text/plain', 'application/json'] })
+    const file = 'string'
+    const validated = validator.execute(rule, file)
+    validated.assertSucceeded()
+  })
+
+  test('does not run when is not valid', () => {
+    const rule = mimeTypesRule({ mimeTypes: ['text/plain', 'application/json'] })
+    const file = new File([''], 'file.txt', { type: 'text/plain' })
+    const validated = validator.withContext({ isValid: false }).execute(rule, file)
+    validated.assertSucceeded()
+  })
+
+  test('should fail when file has a disallowed MIME type', () => {
+    const rule = mimeTypesRule({ mimeTypes: ['text/plain', 'application/json'] })
+    const file = new File([''], 'file.txt', { type: 'image/png' })
+    const validated = validator.execute(rule, file)
+    validated.assertError(
+      'The dummy field must be one of the following mime types: text/plain,application/json'
+    )
+  })
+})