TypeScript: Building a Simple File Downloader Application

Written by

learnmodernjavascript

in

In the digital age, the ability to download files from the web is a fundamental expectation. Whether it’s retrieving documents, images, or software updates, the process should be seamless and efficient. This tutorial will guide you through building a simple, yet functional, file downloader application using TypeScript. We’ll explore the core concepts, step-by-step implementation, and address common pitfalls to ensure you can confidently create your own file downloader.

Why Build a File Downloader?

While web browsers provide built-in download functionalities, there are scenarios where a custom solution is beneficial:

  • Automation: Automate file downloads as part of a larger workflow.
  • Customization: Tailor the download experience to specific needs, such as progress tracking or error handling.
  • Integration: Integrate downloads seamlessly into applications, like a desktop app or a command-line tool.

This tutorial offers a practical introduction to working with file downloads, demonstrating how to handle different file types and provide a user-friendly experience.

Prerequisites

Before we dive in, ensure you have the following:

  • Node.js and npm (or yarn): Required to manage dependencies and run the TypeScript code.
  • A code editor: VS Code, Sublime Text, or any editor of your choice.
  • Basic understanding of TypeScript and JavaScript: Familiarity with variables, functions, and classes.

Setting Up the Project

Let’s create a new project and initialize it with npm:

mkdir file-downloader
cd file-downloader
npm init -y

Next, install TypeScript and create a `tsconfig.json` file:

npm install typescript --save-dev
npx tsc --init

This will create a `tsconfig.json` file. You can customize this file, but for this tutorial, the default settings will suffice. Now, let’s create a directory for our source code, usually named `src`:

mkdir src

Core Concepts

Understanding the core concepts is crucial for building a successful file downloader. We’ll focus on these key elements:

1. The Fetch API

The `fetch` API is a modern interface for making network requests. It’s built into most modern browsers and Node.js. We’ll use it to retrieve the file data from a given URL. The `fetch` API returns a Promise that resolves to a `Response` object.

2. Streams

Streams are a way to handle data in chunks. This is particularly important for large files, as it allows us to process the file data as it arrives, rather than waiting for the entire file to download. We’ll access the stream through the `Response` object’s `body` property.

3. File System Access (for Node.js)

In a Node.js environment, we’ll use the `fs` module (file system) to write the downloaded data to a file on the local system. In a browser environment, you would use the `FileSaver.js` library or similar techniques to initiate a download.

4. Error Handling

Robust error handling is essential. We’ll need to handle network errors, file system errors (in Node.js), and other potential issues that might arise during the download process.

Step-by-Step Implementation (Node.js)

Let’s build the file downloader for a Node.js environment. Create a file named `src/downloader.ts`:

// src/downloader.ts
import * as fs from 'fs';
import * as https from 'https'; // Or 'http', depending on your URL
import * as http from 'http';
import { URL } from 'url';

interface DownloadOptions {
    url: string;
    filepath: string;
    onProgress?: (percent: number) => void;
}

async function downloadFile(options: DownloadOptions): Promise {
    const { url, filepath, onProgress } = options;

    try {
        const parsedUrl = new URL(url);
        const protocol = parsedUrl.protocol === 'https:' ? https : http;

        const request = protocol.get(url, (response) => {
            if (response.statusCode && (response.statusCode = 300)) {
                throw new Error(`Failed to download file, status code: ${response.statusCode}`);
            }

            const totalSize = response.headers['content-length'] ? parseInt(response.headers['content-length'], 10) : 0;
            let downloadedSize = 0;

            const fileStream = fs.createWriteStream(filepath);

            response.pipe(fileStream);

            response.on('data', (chunk) => {
                downloadedSize += chunk.length;
                if (totalSize > 0 && onProgress) {
                    const percent = Math.floor((downloadedSize / totalSize) * 100);
                    onProgress(percent);
                }
            });

            response.on('end', () => {
                fileStream.close();
                console.log('Download complete!');
            });

            response.on('error', (err) => {
                fileStream.close();
                console.error('Download failed:', err);
            });
        });

        request.on('error', (err) => {
            console.error('Request failed:', err);
        });

    } catch (error: any) {
        console.error('An error occurred:', error.message);
    }
}

export default downloadFile;

Let’s break down the code:

  • Imports: We import the necessary modules: `fs` (file system), `https` and `http` (for making requests), and `URL` to parse the URL.
  • `DownloadOptions` Interface: Defines the structure of the options object, including the URL, the desired file path, and an optional `onProgress` callback for tracking the download progress.
  • `downloadFile` Function: This is the main function that handles the download process. It takes a `DownloadOptions` object as input.
  • URL Parsing and Protocol Selection: Determines the protocol (http or https) based on the URL.
  • Making the Request: Uses `https.get` (or `http.get`) to initiate the download.
  • Error Handling: Checks for HTTP status codes indicating errors.
  • Progress Tracking: Determines the `content-length` header. If available, it calculates and reports the download progress using the `onProgress` callback.
  • Streaming the Data: Pipes the response stream to a file stream using `response.pipe(fileStream)`.
  • Events: Handles the `data`, `end`, and `error` events to manage the download process and provide feedback.

Now, create an `index.ts` file to test our downloader:

// index.ts
import downloadFile from './src/downloader';

async function main() {
    const fileUrl = 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'; // Replace with a valid file URL
    const filePath = './downloaded.pdf';

    try {
        await downloadFile({
            url: fileUrl,
            filepath: filePath,
            onProgress: (percent) => {
                console.log(`Download progress: ${percent}%`);
            },
        });
    } catch (error) {
        console.error('Download failed:', error);
    }
}

main();

This `index.ts` file imports the `downloadFile` function and calls it with a sample URL and file path. It also includes an `onProgress` callback to display the download progress in the console.

To run the code, first compile the TypeScript code using the command:

tsc

This will generate JavaScript files in your `dist` directory (or wherever you configured the output directory in `tsconfig.json`). Then, execute the compiled JavaScript using Node.js:

node index.js

This will download the file from the specified URL and save it to the specified file path. You should see progress updates in your console.

Step-by-Step Implementation (Browser)

For a browser-based file downloader, the approach differs slightly. We’ll use the `fetch` API directly and the `FileSaver.js` library to handle the download. First, install the `file-saver` library:

npm install file-saver --save

Create a file named `src/browserDownloader.ts`:

// src/browserDownloader.ts
import { saveAs } from 'file-saver';

interface DownloadOptions {
    url: string;
    filename: string; // The desired filename, including extension
    onProgress?: (percent: number) => void;
}

async function downloadFileBrowser(options: DownloadOptions): Promise {
    const { url, filename, onProgress } = options;

    try {
        const response = await fetch(url);

        if (!response.ok) {
            throw new Error(`Failed to download file, status code: ${response.status}`);
        }

        const totalSize = parseInt(response.headers.get('content-length') || '0', 10);
        let downloadedSize = 0;

        const reader = response.body?.getReader();
        const chunks: Uint8Array[] = [];

        if (!reader) {
            throw new Error('Could not get a reader for the response body.');
        }

        while (true) {
            const { done, value } = await reader.read();
            if (done) {
                break;
            }
            if (value) {
                chunks.push(value);
                downloadedSize += value.length;
                if (totalSize > 0 && onProgress) {
                    const percent = Math.floor((downloadedSize / totalSize) * 100);
                    onProgress(percent);
                }
            }
        }

        const blob = new Blob(chunks);
        saveAs(blob, filename);

    } catch (error: any) {
        console.error('An error occurred:', error.message);
    }
}

export default downloadFileBrowser;

Let’s break down the browser code:

  • Imports: Imports `saveAs` from `file-saver`.
  • `DownloadOptions` Interface: Similar to the Node.js version, but includes `filename` instead of `filepath`.
  • `downloadFileBrowser` Function: This is the main function for the browser.
  • `fetch` API: Uses the `fetch` API to make the request.
  • Response Handling: Checks for errors based on the HTTP status code.
  • Progress Tracking: Gets the total size from the `content-length` header and calculates progress.
  • Reading the Body: Uses the `reader` to read the response body in chunks.
  • Blob Creation: Creates a `Blob` from the downloaded chunks.
  • File Saving: Uses `saveAs` from `file-saver` to initiate the download in the browser.

Create an `index.ts` file to test our browser downloader:


// index.ts
import downloadFileBrowser from './src/browserDownloader';

async function main() {
    const fileUrl = 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'; // Replace with a valid file URL
    const filename = 'downloaded.pdf';

    try {
        await downloadFileBrowser({
            url: fileUrl,
            filename: filename,
            onProgress: (percent) => {
                console.log(`Download progress: ${percent}%`);
            },
        });
    } catch (error) {
        console.error('Download failed:', error);
    }
}

main();

To run this in a browser, you’ll need to set up a basic HTML page and bundle the JavaScript using a bundler like Webpack or Parcel. Here’s a basic `index.html` file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>File Downloader</title>
</head>
<body>
    <script src="bundle.js"></script>  <!-- Assuming your bundled file is named bundle.js -->
</body>
</html>

You’ll need to configure your bundler to bundle the `index.ts` and its dependencies (including `file-saver`). Refer to the documentation for your chosen bundler for specific instructions.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to avoid them:

  • Incorrect File Paths/URLs: Double-check the file paths and URLs to ensure they are correct and accessible. Typos are a common source of errors.
  • CORS Issues (Browser): If you’re downloading from a different domain in a browser, you may encounter Cross-Origin Resource Sharing (CORS) errors. The server hosting the file must configure the appropriate CORS headers.
  • Missing Dependencies: Ensure that all necessary dependencies are installed using `npm install` or `yarn install`.
  • Incorrect MIME Types: Sometimes the server might serve files with an incorrect MIME type. This can cause issues with how the browser handles the download.
  • Network Errors: Handle network errors gracefully. Use `try…catch` blocks to catch potential errors during the `fetch` or `https.get` calls.
  • File System Permissions (Node.js): Ensure the application has the necessary permissions to write to the specified file path.
  • Blocking the UI (Browser): If your download process takes a long time, consider using Web Workers to prevent blocking the main thread in a browser. This keeps the user interface responsive.

Advanced Features and Considerations

Here are some ways to enhance your file downloader:

  • Progress Bar UI (Browser): Instead of just console logging, display a visual progress bar in the browser to provide a better user experience.
  • Resume Downloads: Implement the ability to resume interrupted downloads. This involves storing the downloaded portion and sending a `Range` header in the request to the server.
  • File Type Detection: Automatically detect the file type based on the content or file extension.
  • Rate Limiting: Implement rate limiting to prevent overwhelming the server with download requests.
  • User Authentication: Add authentication to protect the download functionality.
  • Support for Different Protocols: Extend the downloader to support other protocols like FTP.
  • Error Retries: Implement retry logic to handle temporary network issues.

Summary / Key Takeaways

This tutorial provided a comprehensive guide to building a file downloader application using TypeScript, covering both Node.js and browser environments. We explored the core concepts, including the `fetch` API, streams, and file system access (Node.js), and provided step-by-step instructions for implementation. We also discussed common mistakes and how to address them, along with advanced features and considerations for enhancing your downloader. The ability to download files programmatically is a valuable skill in modern software development, opening up possibilities for automation, customization, and seamless integration within various applications. By understanding these techniques, you’re well-equipped to create your own file downloaders tailored to specific needs.

FAQ

  1. What is the difference between Node.js and browser implementations?
    • The primary difference lies in the environment and available APIs. In Node.js, we use the `fs` module to write to the file system. In browsers, we utilize the `FileSaver.js` library (or similar) to trigger the download.
  2. How do I handle large file downloads?
    • Use streams to process the file in chunks. This prevents the entire file from being loaded into memory at once, improving performance and reducing memory usage.
  3. How can I improve the user experience in the browser?
    • Display a progress bar, provide clear error messages, and consider using Web Workers to avoid blocking the user interface.
  4. How do I handle CORS issues?
    • Ensure the server providing the file includes the appropriate CORS headers in its response. This allows the browser to access the resource from a different origin.
  5. Can I use this code for production?
    • The provided code serves as a solid foundation. For production use, consider adding more robust error handling, security measures, and thorough testing.

Building a file downloader is a practical exercise that reinforces understanding of asynchronous operations, network requests, and file handling. The principles demonstrated here can be adapted and extended to address various file download scenarios, making it a valuable addition to your software development skillset. Whether you’re working on a desktop application, a web-based tool, or automating a workflow, the ability to download files programmatically will prove invaluable. By combining the techniques presented with your creativity, you can create efficient and user-friendly file downloader applications that meet a wide range of needs.

More posts