file-converter-nodejs/README.md

A powerful Node.js package for converting files between various formats, splitting and merging files, and automating complex file operations. Backed by LibreOffice and Python, this tool makes file processing seamless for developers.

# 📄 file-converter-nodejs

A powerful Node.js package for converting files between various formats, splitting and merging files, and automating complex file operations. Backed by LibreOffice and Python, this tool makes file processing seamless for developers.

Useful link:

- [Example Project](https://gitlab.com/bouhelalhamza/file-converter/-/tree/master/example?ref_type=heads)
- [NPM Package](https://www.npmjs.com/package/file-converter-nodejs)
- [Docker Image](https://hub.docker.com/r/azertyha77/nodejs-python-soffice)
- [GitLab Repository](https://gitlab.com/bouhelalhamza/file-converter)

---

## ✨ Features

- **Format Conversions**  
  Convert files between formats with ease:

  - **PDF** ➡️ PPTX, PNG, JPG, HTML, DOCX
  - **PPTX** ➡️ PDF, HTML, PNG, JPG
  - **PNG** ➡️ PDF, JPG, SVG
  - **JPG** ➡️ PDF, PNG, SVG
  - **SVG** ➡️ PDF, PNG, JPG
  - **XLSX** ➡️ PDF, CSV, HTML
  - **CSV** ➡️ XLSX, PDF, HTML

- **Advanced Pipelines**  
  Multi-step processing like splitting PDFs into pages, converting them, and merging results into a single file.

- **Splitting Files**  
  Split large PDFs and PPTX files into smaller components.

- **Merging Files**  
  Merge multiple PDFs, DOCX, or PPTX files into one.

- **🚀 Pre-built Docker Image**  
  Use the provided Docker image with all dependencies pre-installed.

---

## 📦 Installation

### 1. **Install Using Yarn or NPM**

```bash
# With Yarn
yarn add file-converter-nodejs

# With NPM
npm install file-converter-nodejs
```

### 2. **Install Dependencies**

This package requires LibreOffice and Python to be installed on your system. You can install them via your package manager or use the provided Docker image:

#### Using Docker (Recommended)

```bash
docker pull azertyha77/nodejs-python-soffice:latest
```

Your Dockerfile could look like this:

```Dockerfile
FROM azertyha77/nodejs-python-soffice:latest

WORKDIR /app

COPY . .

RUN npm install

CMD ["node", "index.js"]
```

Or check example [Dockerfile](https://gitlab.com/bouhelalhamza/file-converter/-/blob/master/Dockerfile.runner) for a more accurate example.

#### Without Docker

You will need to install the following dependencies manually:

- **LibreOffice**  
  Install LibreOffice on your system.  
  [Download LibreOffice](https://www.libreoffice.org/download/download/)

- **Python**
  Install Python on your system.

- **Python dependencies**  
  Install the required Python dependencies using pip (find them in [requirements.txt](https://gitlab.com/bouhelalhamza/file-converter/-/blob/master/requirements.txt)):
  ```bash
  pip install -r requirements.txt
  ```
  or if you already have the npm package installed:
  ```bash
  pip install -r node_modules/file-converter-nodejs/requirements.txt
  ```

You can have a look at an example of how to install each dependency in this [Dockerfile](https://gitlab.com/bouhelalhamza/file-converter/-/blob/master/Dockerfile).

---

## 🛠️ Usage

### Initialize the Processor

```typescript
import FileProcessor from "file-converter-nodejs";

const processor = new FileProcessor();
```

### 🔄 **File Conversion**

<details>
  <summary>Convert PDF 📄</summary>

#### 📄 **Convert PDF to DOCX**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.pdf",
  from: "pdf",
  to: "docx",
  outdir: "/path/to/output",
});
```

#### 📄 **Convert PDF to PPTX**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.pdf",
  from: "pdf",
  to: "pptx",
  outdir: "/path/to/output",
});
```

#### 📄 **Convert PDF to PNG**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.pdf",
  from: "pdf",
  to: "png",
  outdir: "/path/to/output",
});
```

#### 📄 **Convert PDF to JPG**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.pdf",
  from: "pdf",
  to: "jpg",
  outdir: "/path/to/output",
});
```

#### 📄 **Convert PDF to HTML**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.pdf",
  from: "pdf",
  to: "html",
  outdir: "/path/to/output",
});
```

#### 📄 **Convert PDF to DOCX**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.pdf",
  from: "pdf",
  to: "docx",
  outdir: "/path/to/output",
});
```

</details>

<details>
  <summary>Convert PPTX 📊</summary>

#### 📊 **Convert PPTX to PDF**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.pptx",
  from: "pptx",
  to: "pdf",
  outdir: "/path/to/output",
});
```

#### 📊 **Convert PPTX to HTML**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.pptx",
  from: "pptx",
  to: "html",
  outdir: "/path/to/output",
});
```

#### 📊 **Convert PPTX to PNG**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.pptx",
  from: "pptx",
  to: "png",
  outdir: "/path/to/output",
});
```

#### 📊 **Convert PPTX to JPG**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.pptx",
  from: "pptx",
  to: "jpg",
  outdir: "/path/to/output",
});
```

</details>

<details>
  <summary>Convert PNG 🖼️</summary>

#### 🖼️ **Convert PNG to PDF**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.png",
  from: "png",
  to: "pdf",
  outdir: "/path/to/output",
});
```

#### 🖼️ **Convert PNG to JPG**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.png",
  from: "png",
  to: "jpg",
  outdir: "/path/to/output",
});
```

#### 🖼️ **Convert PNG to SVG**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.png",
  from: "png",
  to: "svg",
  outdir: "/path/to/output",
});
```

</details>

<details>
  <summary>Convert JPG 🖼️</summary>

#### 🖼️ **Convert JPG to PDF**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.jpg",
  from: "jpg",
  to: "pdf",
  outdir: "/path/to/output",
});
```

#### 🖼️ **Convert JPG to PNG**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.jpg",
  from: "jpg",
  to: "png",
  outdir: "/path/to/output",
});
```

#### 🖼️ **Convert JPG to SVG**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.jpg",
  from: "jpg",
  to: "svg",
  outdir: "/path/to/output",
});
```

</details>

<details>
  <summary>Convert SVG 🖼️</summary>

#### 🖼️ **Convert SVG to PDF**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.svg",
  from: "svg",
  to: "pdf",
  outdir: "/path/to/output",
});
```

#### 🖼️ **Convert SVG to PNG**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.svg",
  from: "svg",
  to: "png",
  outdir: "/path/to/output",
});
```

#### 🖼️ **Convert SVG to JPG**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.svg",
  from: "svg",
  to: "jpg",
  outdir: "/path/to/output",
});
```

</details>

<details>
  <summary>Convert XLSX 📊</summary>
  
#### 📊 **Convert XLSX to PDF**:
```typescript
await processor.convertFile({
  filePath: '/path/to/input.xlsx',
  from: 'xlsx',
  to: 'pdf',
  outdir: '/path/to/output',
});
```

#### 📊 **Convert XLSX to CSV**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.xlsx",
  from: "xlsx",
  to: "csv",
  outdir: "/path/to/output",
});
```

#### 📊 **Convert XLSX to HTML**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.xlsx",
  from: "xlsx",
  to: "html",
  outdir: "/path/to/output",
});
```

</details>

<details>
  <summary>Convert CSV 📊</summary>

#### 📝 **Convert CSV to XLSX**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.csv",
  from: "csv",
  to: "xlsx",
  outdir: "/path/to/output",
});
```

#### 📝 **Convert CSV to PDF**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.csv",
  from: "csv",
  to: "pdf",
  outdir: "/path/to/output",
});
```

#### 📝 **Convert CSV to HTML**:

```typescript
await processor.convertFile({
  filePath: "/path/to/input.csv",
  from: "csv",
  to: "html",
  outdir: "/path/to/output",
});
```

</details>

### 🔄 **Splitting and Merging Files**

<details>
    <summary>Splitting File 📄 &rarr; 📄📄📄 </summary>

#### 📄 **Split PDF into Pages**:

```typescript
const splitFiles = processor.splitFile({
  filePath: "/path/to/input.pdf",
  fileType: "pdf",
  outputDir: "/path/to/output",
});

console.log("Generated Files:", splitFiles);
```

#### 📄 **Split PPTX into Pages**:

```typescript
const splitSlides = processor.splitFile({
  filePath: "/path/to/input.pptx",
  fileType: "pptx",
  outputDir: "/path/to/output",
});

console.log("Generated Files:", splitSlides);
```

</details>

<details>
    <summary>Merging Files 📄📄📄 &rarr; 📄</summary>

#### 📄 **Merge PDF Files**:

```typescript
processor.mergeFiles({
  filePaths: ["/path/to/file1.pdf", "/path/to/file2.pdf"],
  fileType: "pdf",
  outputFilePath: "/path/to/merged.pdf",
});
```

#### 📄 **Merge PPTX Files**:

```typescript
processor.mergeFiles({
  filePaths: ["/path/to/file1.pptx", "/path/to/file2.pptx"],
  fileType: "pptx",
  outputFilePath: "/path/to/merged.pptx",
});
```

#### 📄 **Merge DOCX Files**:

```typescript
processor.mergeFiles({
  filePaths: ["/path/to/file1.docx", "/path/to/file2.docx"],
  fileType: "docx",
  outputFilePath: "/path/to/merged.docx",
});
```

</details>

---

## ⚙️ Configuration

### Default Settings

- **LibreOffice Path** `soffice`
- **Python Path** `python3`

You can customize the configuration by passing options to the `FileProcessor` constructor:

```typescript
const processor = new FileProcessor({
  libreOfficePath: "/custom/path/to/soffice",
  pythonPath: "/custom/path/to/python",
});
```

Note that if you're using the provided docker image, you don't need to pass these options.

---

## 🤝 Contribution

Contributions are welcome! Please open an issue or submit a pull request for any improvements or feature requests.

---

## 📝 License

This project is licensed under the MIT License. See the [LICENSE](https://gitlab.com/bouhelalhamza/file-converter/-/blob/master/LICENSE) file for more information.