mds-file-upload/README.md

A simple and efficient file upload utility for Node.js applications, supporting temporary and permanent storage.

# mds-file-upload

**mds-file-upload** is a simple and efficient file upload utility built for Node.js applications. It supports uploading files to a specified folder and managing temporary and permanent storage paths with ease.

---

## Features

- Upload files to a specified folder.
- Temporary file storage option.
- Move files from temporary to permanent storage.
- Delete uploaded files.
- Check for the existence of files or folders.

---

## Installation

To install the package, run:

```bash
npm install mds-file-upload
```

---

## Usage

### Importing and Initialization

Import the `MdsFileUpload` class and initialize it with your project's base directory:

```typescript
import { MdsFileUpload } from "mds-file-upload";

const uploader = new MdsFileUpload(process.cwd());
```

---

### Methods

#### 1. `handleFileUpload`

Uploads a file to the `uploads` folder by default or to the `temp` folder if specified.

**Parameters:**
- `infile` (File): The file to upload.
- `toTemp` (boolean, optional): Whether to upload to the temporary folder. Defaults to `false`.

**Example:**

```typescript
const file = new File(["content"], "example.txt");

uploader.handleFileUpload(file)
  .then(result => console.log("File uploaded:", result))
  .catch(err => console.error("Upload failed:", err));
```

#### 2. `deleteUploadedFile`

Deletes a file from the `uploads` folder.

**Parameters:**
- `filename` (string): The name of the file to delete.

**Example:**

```typescript
uploader.deleteUploadedFile("example.txt")
  .then(() => console.log("File deleted."))
  .catch(err => console.error("Deletion failed:", err));
```

#### 3. `moveFileToUpload`

Moves a file from the `temp` folder to the `uploads` folder.

**Parameters:**
- `filename` (string): The name of the file to move.

**Example:**

```typescript
uploader.moveFileToUpload("temp-example.txt")
  .then(success => console.log("File moved successfully:", success))
  .catch(err => console.error("Move failed:", err));
```

#### 4. `checkFileOrFolderExists`

Checks if a file or folder exists at a specified path.

**Parameters:**
- `targetPath` (string): The path to check.

**Example:**

```typescript
uploader.checkFileOrFolderExists("/path/to/file.txt")
  .then(exists => console.log("Exists:", exists))
  .catch(err => console.error("Error checking existence:", err));
```

---

## File Structure

```
mds-file-upload/
├── src/
│   ├── index.ts       # Main source file
├── dist/              # Compiled output
├── package.json       # NPM configuration
├── README.md          # Project documentation
└── tsconfig.json      # TypeScript configuration
```

---

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch (`git checkout -b feature-branch`).
3. Commit your changes (`git commit -m 'Add new feature'`).
4. Push to the branch (`git push origin feature-branch`).
5. Open a Pull Request.

---

## License

This project is licensed under the MIT License.

---

## Author

Developed and maintained by **Mwero Abdalla**.

- GitHub: [mwenaro](https://github.com/mwenaro)

---

## Repository

The source code for this project is available on GitHub:

[https://github.com/mwenaro/mds-file-upload](https://github.com/mwenaro/mds-file-upload)

---

## Versioning

This package follows semantic versioning. Refer to the [CHANGELOG](https://github.com/mwenaro/mds-file-upload/blob/main/CHANGELOG.md) for details on updates.