file

Builds a parser for files. DServerDataParser.file() ensures the input is a file (with optional coercion support) and returns a typed Either containing either the validated value or a detailed DataParserError.

Example

import { SDP, type SF } from "@duplojs/server-utils";
import { E, type ExpectType, type DP } from "@duplojs/utils";

const schema = SDP.coerce.file({
	checkers: [SDP.checkerFileMimeType(/^application\/json$/)],
});

const result = schema.parse("/path/file.json");

if (E.isRight(result)) {
	type check = ExpectType<
		typeof result,
		E.Success<SF.FileInterface>,
		"strict"
	>;
} else {
	type check = ExpectType<
		typeof result,
		E.Error<DP.DataParserError>,
		"strict"
	>;
}

Parameters

• errorMessage: custom message used when the input is not a file and as the default for checkers that do not define their own message.
• checkers: array of checkers (checkerFileSize, checkerFileExist, checkerFileMimeType, checkerRefine, etc.) executed after the base validation.
• coerce: true to transform a path into FileInterface. Defaults to false.

Return value

A DataParserFile exposing parse, asyncParse, exec, asyncExec, addChecker, and clone.

The File parser is synchronous by default. checkerFileMimeType is also synchronous, while checkerFileExist and checkerFileSize are asynchronous because they read file information.

• schema.parse(data) runs synchronous validations and returns a DEither.Success<FileInterface> or a DEither.Error<DataParserError>. It returns an error when the parser contains an asynchronous checker.
• schema.asyncParse(data) awaits asynchronous checkers and returns a Promise<DEither.Success<FileInterface>> or a Promise<DEither.Error<DataParserError>>.

Other examples

Custom checkers

import { SDP, type SF } from "@duplojs/server-utils";
import { E, type ExpectType, type DP } from "@duplojs/utils";

const schema = SDP
	.coerce
	.file()
	.addChecker(
		SDP.checkerFileExist(),
		SDP.checkerFileSize(
			{
				min: 1,
				max: 5_000_000,
			},
			{ errorMessage: "file.invalid-size" },
		),
		SDP.checkerFileMimeType(/^image\/(?:png|jpeg)$/),
	);

const result = await schema.asyncParse("/path/image.png");

if (E.isRight(result)) {
	type check = ExpectType<
		typeof result,
		E.Success<SF.FileInterface>,
		"strict"
	>;
} else {
	type check = ExpectType<
		typeof result,
		E.Error<DP.DataParserError>,
		"strict"
	>;
}

Extended mode

import { SDPE, type SF } from "@duplojs/server-utils";
import { E, type ExpectType, type DP } from "@duplojs/utils";

const schema = SDPE
	.coerce
	.file()
	.exist()
	.mimeType(/^image\/(?:png|jpeg)$/)
	.size({ max: 5_000_000 });

const result = await schema.asyncParse("/path/image.png");

if (E.isRight(result)) {
	type check = ExpectType<
		typeof result,
		E.Success<SF.FileInterface>,
		"strict"
	>;
} else {
	type check = ExpectType<
		typeof result,
		E.Error<DP.DataParserError>,
		"strict"
	>;
}

Difference between parse and asyncParse

import { SDP, type SF } from "@duplojs/server-utils";
import { E, type DP, type ExpectType } from "@duplojs/utils";

const schema = SDP.coerce.file({
	checkers: [
		SDP.checkerFileExist(),
		SDP.checkerFileSize({ max: 2_000_000 }),
	],
});

const syncResult = schema.parse("/path/file.json");
Incorrect: parse cannot execute asynchronous checkers.

const asyncResult = await schema.asyncParse("/path/file.json");
Correct: asyncParse awaits asynchronous checkers.

if (E.isRight(asyncResult)) {
	type check = ExpectType<
		typeof asyncResult,
		E.Success<SF.FileInterface>,
		"strict"
	>;
} else {
	type check = ExpectType<
		typeof asyncResult,
		E.Error<DP.DataParserError>,
		"strict"
	>;
}

INFO

This example uses checkerFileExist and checkerFileSize, two asynchronous checkers that read file information. You must therefore use asyncParse to await their result. Using parse on this parser returns a DataParserError because it cannot execute these asynchronous checkers.

See also

• fileInterface - Creates a file interface.