# form.file-check
The checks behind a file upload field, so the browser and the server refuse
the same files with the same words. `react.form.file-upload` calls it as files
are chosen; the API that receives the upload (or that signs the upload URL with
`storage.signed-url`) calls it again, in TypeScript, Python or Rust, on the
names, sizes and types it is told about.
```ts
validateFiles(
[{ name: "setup.exe", size: 100, mimeType: "application/x-msdownload" }],
{ required: true, accept: ".pdf", maxBytes: 2 * 1024 * 1024, multiple: false, maxFiles: null },
);
// { valid: false, message: "The selected file must be a PDF",
// errors: [{ index: 0, name: "setup.exe", code: "type", message: "The selected file must be a PDF" }] }
```
## The rules, in order
1. **The field.** Nothing chosen and `required`: "Select a file" ("Select at
least one file" when `multiple`). More than one file when not `multiple`:
"Select only one file". More than `maxFiles`: "You can only select up to 5
files". At most one field error, `index` -1, first in `errors`.
2. **Each file**, at most one error each, in this order: not accepted ("must
be a PDF"), empty ("is empty"), larger than `maxBytes` ("must be 2MB or
smaller"). A lone file is "The selected file"; when several are chosen each
message starts with the file's name, so the person can tell which.
`message` is the first error's, for an error summary; `valid` is `errors` being
empty. The wording follows the GOV.UK Design System's file upload component.
## accept
`acceptsFile` reads an accept attribute the way a browser's file chooser does:
comma-separated tokens, trimmed, compared ignoring ASCII case; `.pdf` matches a
name ending in `.pdf`; `application/pdf` matches the browser's MIME type
exactly; `image/*` matches any `image/` type. An empty accept (or null in the
rules) takes anything. A token that is none of these (`pdf`, `image/`) throws,
because a typo would let every file through on the server while the browser
hid them.
The browser's MIME type is a guess from the extension and may be empty, so a
wildcard alone refuses a file the browser could not type; list the extensions
too (`image/*,.heic`).
The message names the accepted types: an extension or a MIME subtype upper-cased
(`.pdf` and `application/pdf` are both "PDF", once), a wildcard as its word
("image"), joined "a PDF, JPG or PNG". The article follows how it is said:
"an image", "an SVG", "an MP4", "a PDF".
**This checks what the browser says about a file, not the file.** The name,
size and type come from the person's computer. Check the stored object's real
size and content (the upload-scanning gap in the saas-starter suite) before
trusting it.
## formatFileSize
Units of 1024 (KB, MB, GB, TB), as file choosers show sizes, with one decimal
place rounded half up only when the size is not whole: 1536 is "1.5KB", 2097152
is "2MB", 1 is "1 byte". A size that rounds to 1024 of a unit is written as one
of the next (1048575 bytes is "1MB", not "1024KB"). Integer arithmetic only, so
every language prints the same. The size limit in the too-large message is
written with it.
## Errors
Thrown, since they are the caller's mistakes: a negative `maxBytes`, a
`maxFiles` below 1 or without `multiple`, a malformed accept token, a negative
or fractional file size.
## Notices
Error message wording follows the GOV.UK Design System. Portions derived from GOV.UK Frontend (https://github.com/alphagov/govuk-frontend), Copyright (c) 2017 Crown Copyright (Government Digital Service), under the MIT License; the full notice is in NOTICE.