How Files Differ from Text Data

Everything we’ve sent so far — JSON, URL-encoded forms, multipart text fields — has been text data. Text is human-readable, relatively small, and easy to work with. Files are different in several important ways, and understanding those differences will help you choose the right API.

Binary Data

A file on disk is a sequence of bytes — binary data. An image, a PDF, a zip archive, or a video are all binary. They aren’t structured as key-value pairs or JSON objects. They’re just raw bytes that only make sense to software that knows how to interpret them.

Some files (like .txt or .csv) contain text, but even those are binary at the transport level. The HTTP client sends the raw bytes, and the server decides how to interpret them.

Content-Type (MIME Type)

When you send a file over HTTP, the server needs to know what kind of file it is. This is communicated through the Content-Type header, using a format called a MIME type (Multipurpose Internet Mail Extensions).

Some common MIME types:

• image/png: PNG image
• image/jpeg: JPEG image
• application/pdf: PDF document
• application/octet-stream: generic binary (used when the specific type is unknown)
• text/plain: plain text file
• text/csv: CSV file

When using HttpClientRequest’s file APIs, the content type is either auto-detected or specified by you.

Streams

Small files (a few KB) can be loaded entirely into memory and sent in one go. But large files — a 500MB video, a multi-gigabyte database dump — can’t reasonably fit in memory all at once.

Streaming solves this by reading and sending the file in small chunks. Instead of loading the whole file into a Uint8Array, you create a Stream<Uint8Array> that reads chunks on demand. The HTTP client sends each chunk as it arrives, keeping memory usage low regardless of file size.

How Files Are Sent in HTTP

There are several ways to include a file in an HTTP request:

• As the raw request body: The file’s bytes are the entire body. This is the simplest approach for single-file uploads. The Content-Type header indicates the file type.
• Inside multipart form data: The file is one part of a multipart body, alongside other fields. This is the standard approach for HTML file upload forms, and it’s what most API endpoints for file upload expect.
• As a Base64-encoded string in JSON: Some APIs accept files encoded as text within a JSON payload. This increases size by ~33% but avoids multipart complexity.

The HttpClientRequest module provides APIs for all of these approaches.