TypeScript Tutorial: Building a Simple Command-Line File Organizer

Written by

learnmodernjavascript

in

Are you tired of messy directories filled with files scattered all over the place? Do you spend valuable time manually organizing your files, only to find yourself in a disorganized mess again? In today’s tutorial, we’ll dive into the world of TypeScript and build a simple, yet powerful, command-line file organizer that will automate this tedious task. This tool will not only save you time but also help you maintain a clean and efficient file system.

Why Build a File Organizer?

As developers, we often deal with numerous files: code, documentation, images, and more. Without a proper organization system, your directories can quickly become chaotic. A file organizer can:

  • Save Time: Automate the process of sorting files.
  • Improve Efficiency: Make it easier to find what you need.
  • Reduce Errors: Minimize the risk of accidental file deletion or modification.

Prerequisites

Before we begin, ensure you have the following installed:

  • Node.js and npm: You’ll need Node.js (version 12 or higher) and npm (Node Package Manager) installed on your system. You can download them from the official Node.js website.
  • TypeScript: We’ll use TypeScript for this project. If you don’t have it installed globally, you can install it using npm: npm install -g typescript
  • A Code Editor: A code editor like Visual Studio Code, Sublime Text, or Atom will be helpful.
  • Basic Understanding: Familiarity with JavaScript and the command line is beneficial.

Setting Up Your Project

Let’s start by setting up our project:

  1. Create a Project Directory: Create a new directory for your project (e.g., file-organizer) and navigate into it using your terminal.
  2. Initialize npm: Run npm init -y to create a package.json file. This file will manage your project dependencies and metadata.
  3. Install TypeScript: Install TypeScript as a development dependency: npm install --save-dev typescript
  4. Create a TypeScript Configuration File: Create a tsconfig.json file in your project root. This file configures the TypeScript compiler. You can generate a basic one using the command: npx tsc --init.
  5. Project Structure: Create a directory named src where we’ll put our TypeScript files.

Your project structure should look like this:

file-organizer/
├── node_modules/
├── src/
├── package.json
├── tsconfig.json
└──

Coding the File Organizer

Now, let’s write the code for our file organizer. We’ll start with the core functionality.

1. Creating the Entry Point

Create a file named index.ts inside the src directory. This will be the entry point of our application.

// src/index.ts
import * as fs from 'fs';
import * as path from 'path';

// Function to organize files
function organizeFiles(directoryPath: string) {
  // Implementation will go here
}

// Get directory path from command line arguments
const directoryPath = process.argv[2];

// Check if a directory path is provided
if (!directoryPath) {
  console.error('Please provide a directory path.');
  process.exit(1);
}

// Call the organizeFiles function
organizeFiles(directoryPath);

In this code:

  • We import the fs (file system) and path modules from Node.js. These are essential for interacting with the file system.
  • We define a function organizeFiles that will contain the core logic.
  • We retrieve the directory path from the command-line arguments using process.argv[2] (the first two arguments are typically the Node.js executable and the script file).
  • We check if a directory path is provided and exit with an error message if it’s missing.

2. Reading the Directory

Inside the organizeFiles function, we’ll read the contents of the specified directory.

// src/index.ts
import * as fs from 'fs';
import * as path from 'path';

function organizeFiles(directoryPath: string) {
  fs.readdir(directoryPath, (err, files) => {
    if (err) {
      console.error('Error reading directory:', err);
      return;
    }

    // Process each file
    files.forEach(file => {
      const filePath = path.join(directoryPath, file);
      // Implement file processing logic here
    });
  });
}

const directoryPath = process.argv[2];

if (!directoryPath) {
  console.error('Please provide a directory path.');
  process.exit(1);
}

organizeFiles(directoryPath);

Here’s what’s happening:

  • We use fs.readdir to read the contents of the directory. This function takes the directory path and a callback function.
  • The callback function handles any errors and iterates through each file or subdirectory within the specified directory.
  • For each file, we construct the full file path using path.join.

3. Determining File Types

Next, we need to determine the type of each file (e.g., image, document, code). We’ll use the file extension for this.

// src/index.ts
import * as fs from 'fs';
import * as path from 'path';

function organizeFiles(directoryPath: string) {
  fs.readdir(directoryPath, (err, files) => {
    if (err) {
      console.error('Error reading directory:', err);
      return;
    }

    files.forEach(file => {
      const filePath = path.join(directoryPath, file);
      const fileExtension = path.extname(file).toLowerCase();
      let destinationDirectory = '';

      switch (fileExtension) {
        case '.jpg':
        case '.jpeg':
        case '.png':
        case '.gif':
          destinationDirectory = 'images';
          break;
        case '.pdf':
        case '.doc':
        case '.docx':
        case '.txt':
          destinationDirectory = 'documents';
          break;
        case '.js':
        case '.ts':
        case '.html':
        case '.css':
          destinationDirectory = 'code';
          break;
        default:
          destinationDirectory = 'other';
      }

      // Implement moving files logic here
    });
  });
}

const directoryPath = process.argv[2];

if (!directoryPath) {
  console.error('Please provide a directory path.');
  process.exit(1);
}

organizeFiles(directoryPath);

In this code:

  • We use path.extname to get the file extension.
  • We convert the extension to lowercase for consistency.
  • We use a switch statement to determine the destination directory based on the file extension.
  • We create destination directories for images, documents, code, and other files.

4. Moving the Files

Now, let’s move the files to their respective directories.

// src/index.ts
import * as fs from 'fs';
import * as path from 'path';

function organizeFiles(directoryPath: string) {
  fs.readdir(directoryPath, (err, files) => {
    if (err) {
      console.error('Error reading directory:', err);
      return;
    }

    files.forEach(file => {
      const filePath = path.join(directoryPath, file);
      const fileExtension = path.extname(file).toLowerCase();
      let destinationDirectory = '';

      switch (fileExtension) {
        case '.jpg':
        case '.jpeg':
        case '.png':
        case '.gif':
          destinationDirectory = 'images';
          break;
        case '.pdf':
        case '.doc':
        case '.docx':
        case '.txt':
          destinationDirectory = 'documents';
          break;
        case '.js':
        case '.ts':
        case '.html':
        case '.css':
          destinationDirectory = 'code';
          break;
        default:
          destinationDirectory = 'other';
      }

      // Create destination directory if it doesn't exist
      const destinationPath = path.join(directoryPath, destinationDirectory);
      if (!fs.existsSync(destinationPath)) {
        fs.mkdirSync(destinationPath);
      }

      // Move the file
      const newFilePath = path.join(destinationPath, file);
      fs.rename(filePath, newFilePath, (err) => {
        if (err) {
          console.error('Error moving file:', err);
        }
      });
    });
  });
}

const directoryPath = process.argv[2];

if (!directoryPath) {
  console.error('Please provide a directory path.');
  process.exit(1);
}

organizeFiles(directoryPath);

Here’s the breakdown:

  • We create the destination directory if it doesn’t exist using fs.mkdirSync.
  • We construct the new file path using path.join.
  • We use fs.rename to move the file to the new location.
  • We include error handling for the file moving process.

5. Compiling and Running

Now, let’s compile our TypeScript code and run the file organizer:

  1. Compile: Open your terminal and run npx tsc. This will compile your TypeScript code into JavaScript and create an index.js file in the same directory.
  2. Run: Execute the file organizer using node dist/index.js <directory_path>. Replace <directory_path> with the path to the directory you want to organize.

Example:

node dist/index.js ./my-files

This command will organize the files in the my-files directory.

Handling Errors and Edge Cases

In real-world scenarios, you’ll encounter various edge cases and potential errors. Here are some common ones and how to handle them:

  • Invalid Directory Path: The user might provide an invalid directory path.
  • File Access Permissions: The script might not have permission to read or write to the directory.
  • Duplicate File Names: If files with the same name exist in the destination directory, they could be overwritten.
  • Large Number of Files: Organizing a large number of files can take a long time and might cause performance issues.

Error Handling

Let’s improve our error handling. We’ll check if the directory exists and handle file access errors.

// src/index.ts
import * as fs from 'fs';
import * as path from 'path';

function organizeFiles(directoryPath: string) {
  // Check if directory exists
  if (!fs.existsSync(directoryPath)) {
    console.error('Error: Directory does not exist.');
    return;
  }

  fs.readdir(directoryPath, (err, files) => {
    if (err) {
      console.error('Error reading directory:', err);
      return;
    }

    files.forEach(file => {
      const filePath = path.join(directoryPath, file);
      const fileExtension = path.extname(file).toLowerCase();
      let destinationDirectory = '';

      switch (fileExtension) {
        case '.jpg':
        case '.jpeg':
        case '.png':
        case '.gif':
          destinationDirectory = 'images';
          break;
        case '.pdf':
        case '.doc':
        case '.docx':
        case '.txt':
          destinationDirectory = 'documents';
          break;
        case '.js':
        case '.ts':
        case '.html':
        case '.css':
          destinationDirectory = 'code';
          break;
        default:
          destinationDirectory = 'other';
      }

      // Create destination directory if it doesn't exist
      const destinationPath = path.join(directoryPath, destinationDirectory);
      if (!fs.existsSync(destinationPath)) {
        try {
          fs.mkdirSync(destinationPath);
        } catch (mkdirErr) {
          console.error('Error creating directory:', mkdirErr);
          return;
        }
      }

      // Move the file
      const newFilePath = path.join(destinationPath, file);
      fs.rename(filePath, newFilePath, (err) => {
        if (err) {
          console.error('Error moving file:', err);
        }
      });
    });
  });
}

const directoryPath = process.argv[2];

if (!directoryPath) {
  console.error('Please provide a directory path.');
  process.exit(1);
}

organizeFiles(directoryPath);

Here, we’ve added a check using fs.existsSync to ensure the directory exists before proceeding. We also wrap the fs.mkdirSync call in a try...catch block to handle potential errors during directory creation.

Duplicate File Names

To handle duplicate file names, you can append a number to the file name before moving it. Here’s how you can modify the fs.rename part:

// src/index.ts
import * as fs from 'fs';
import * as path from 'path';

function organizeFiles(directoryPath: string) {
  // Check if directory exists
  if (!fs.existsSync(directoryPath)) {
    console.error('Error: Directory does not exist.');
    return;
  }

  fs.readdir(directoryPath, (err, files) => {
    if (err) {
      console.error('Error reading directory:', err);
      return;
    }

    files.forEach(file => {
      const filePath = path.join(directoryPath, file);
      const fileExtension = path.extname(file).toLowerCase();
      let destinationDirectory = '';

      switch (fileExtension) {
        case '.jpg':
        case '.jpeg':
        case '.png':
        case '.gif':
          destinationDirectory = 'images';
          break;
        case '.pdf':
        case '.doc':
        case '.docx':
        case '.txt':
          destinationDirectory = 'documents';
          break;
        case '.js':
        case '.ts':
        case '.html':
        case '.css':
          destinationDirectory = 'code';
          break;
        default:
          destinationDirectory = 'other';
      }

      // Create destination directory if it doesn't exist
      const destinationPath = path.join(directoryPath, destinationDirectory);
      if (!fs.existsSync(destinationPath)) {
        try {
          fs.mkdirSync(destinationPath);
        } catch (mkdirErr) {
          console.error('Error creating directory:', mkdirErr);
          return;
        }
      }

      // Handle duplicate file names
      let newFilePath = path.join(destinationPath, file);
      let baseName = path.basename(file, fileExtension);
      let counter = 1;

      while (fs.existsSync(newFilePath)) {
        newFilePath = path.join(destinationPath, `${baseName}(${counter})${fileExtension}`);
        counter++;
      }

      fs.rename(filePath, newFilePath, (err) => {
        if (err) {
          console.error('Error moving file:', err);
        }
      });
    });
  });
}

const directoryPath = process.argv[2];

if (!directoryPath) {
  console.error('Please provide a directory path.');
  process.exit(1);
}

organizeFiles(directoryPath);

In this code, we check if the new file path already exists. If it does, we append a number in parentheses to the file name until a unique name is found.

Performance Considerations

For a large number of files, consider these performance improvements:

  • Asynchronous Operations: Use asynchronous functions (e.g., fs.promises.readdir) to avoid blocking the main thread.
  • Batch Operations: Instead of moving files one by one, batch them into groups to reduce the number of file system calls.
  • Buffering: For very large files, consider using streams to read and write data in chunks.

Advanced Features

You can extend your file organizer with more advanced features:

  • Configuration Files: Allow users to configure the file types and destination directories using a configuration file (e.g., JSON).
  • Command-Line Options: Add command-line options using a library like commander to customize the behavior of the organizer (e.g., recursive organization, dry-run mode).
  • File Size Filtering: Filter files based on their size.
  • Date-Based Organization: Organize files based on their creation or modification dates.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to avoid them:

  • Incorrect File Paths: Ensure you are providing the correct directory path. Use absolute paths to avoid confusion.
  • Missing Dependencies: Double-check that you have installed all necessary dependencies (e.g., TypeScript).
  • Case Sensitivity: File extensions are case-sensitive on some operating systems. Handle this by converting extensions to lowercase.
  • Permissions Issues: Make sure the script has the necessary permissions to read and write files in the target directory.
  • Incorrect Compilation: Always compile your TypeScript code using npx tsc before running the script.

Key Takeaways

  • You’ve built a command-line file organizer using TypeScript.
  • You’ve learned how to read directories, identify file types, and move files.
  • You’ve implemented error handling for various scenarios.
  • You understand the importance of considering edge cases and performance.

FAQ

  1. Can I use this organizer on any operating system?

    Yes, this script should work on any operating system that supports Node.js and npm, such as Windows, macOS, and Linux.

  2. How do I add support for more file types?

    Simply add more cases to the switch statement in the code, specifying the file extensions and their corresponding destination directories.

  3. What if I want to organize subdirectories?

    You’ll need to implement a recursive function that iterates through subdirectories as well.

  4. How can I undo the file organization?

    There isn’t a built-in undo feature. However, you could implement a logging system to track file movements and potentially revert them.

By following this tutorial, you’ve taken your first steps toward automating file organization with TypeScript. The ability to create command-line tools is a valuable skill for any developer, and this project serves as a solid foundation. As you continue to build and refine this tool, you’ll discover new ways to improve your workflow and streamline your development process. This file organizer is just the beginning; the possibilities for automating your tasks are endless.

More posts