Functional Weave
Code in TypeScript

form.file-check@1.0.0

README.md

3,599 bytes · view raw

# 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.