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({
	mimeType: "application/json",
});

const result = await schema.asyncParse("/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 injected into each issue when the input is not a file or does not meet constraints.
• coerce: true to transform a path into FileInterface. Defaults to false.
• mimeType?: string, [string, ...string[]], or RegExp applied to the file mime type.
• minSize?: number or BytesInString (${number}${"b" | "kb" | "mb"...}) to enforce a minimum file size. This check is only executed through asyncParse.
• maxSize?: number or BytesInString (${number}${"b" | "kb" | "mb"...}) to enforce a maximum file size. This check is only executed through asyncParse.
• checkExist?: true to check whether the file really exists. This check is only executed through asyncParse.

Return value

A DataParserFile exposing parse, asyncParse, isAsynchronous, and clone.

• schema.parse(data) returns a DEither.Success<FileInterface> when synchronous checks pass, or a DEither.Error<DataParserError>. If checkExist, minSize, or maxSize are enabled, this synchronous mode immediately returns an error because these checks require async I/O.
• schema.asyncParse(data) runs full validation (including real file existence and size constraints) and returns a Promise<DEither.Success<FileInterface>> when all validations pass, or a Promise<DEither.Error<DataParserError>> with paths (path), messages, and rejected values.

Other examples

Extended mode

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

const schema = SDPE
	.coerce
	.file()
	.mustExist()
	.mimeType(["image/png", "image/jpeg"])
	.maxSize("5mb");

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({
	checkExist: true,
	maxSize: "2mb",
});

// parse returns an Either immediately and cannot execute async I/O checks.
const syncResult = schema.parse("/path/file.json");

if (E.isLeft(syncResult)) {
	type check = ExpectType<
		typeof syncResult,
		E.Error<DP.DataParserError>,
		"strict"
	>;
}

// asyncParse runs full checks (existence and size) and returns Promise<Either>.
const asyncResult = await schema.asyncParse("/path/file.json");

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"
	>;
}

See also

• fileInterface - Creates a file interface.