npm package: @raphaellcs/json-converter
Description: Convert between JSON, YAML, XML, and other formats
Author: Dream Heart
Latest version: 1.0.0

# @raphaellcs/json-converter

A simple and powerful tool to convert between JSON, YAML, XML, and CSV formats.

## Features

- 🔄 **Convert** JSON ↔ YAML
- 📄 **Convert** JSON ↔ XML
- 📊 **Convert** JSON ↔ CSV
- 🎯 **Support** for complex nested structures
- ⚡ **Fast** and lightweight
- 🎨 **Pretty print** option for readability

## Installation

```bash
# Use with npx (no installation needed)
npx @raphaellcs/json-converter --help

# Or install globally
npm install -g @raphaellcs/json-converter
```

## Usage

### JSON to YAML

```bash
# Convert JSON to YAML
npx @raphaellcs/json-converter json2yaml -i data.json

# Specify output file
npx @raphaellcs/json-converter json2yaml -i data.json -o data.yaml

# Compact output (no pretty print)
npx @raphaellcs/json-converter json2yaml -i data.json --no-pretty
```

### YAML to JSON

```bash
# Convert YAML to JSON
npx @raphaellcs/json-converter yaml2json -i config.yaml

# Specify output file
npx @raphaellcs/json-converter yaml2json -i config.yaml -o config.json

# Compact output
npx @raphaellcs/json-converter yaml2json -i config.yaml --no-pretty
```

### JSON to XML

```bash
# Convert JSON to XML
npx @raphaellcs/json-converter json2xml -i data.json

# Specify root element name
npx @raphaellcs/json-converter json2xml -i data.json -r document

# Specify output file
npx @raphaellcs/json-converter json2xml -i data.json -o data.xml
```

### XML to JSON

```bash
# Convert XML to JSON
npx @raphaellcs/json-converter xml2json -i data.xml

# Specify output file
npx @raphaellcs/json-converter xml2json -i data.xml -o data.json

# Compact output
npx @raphaellcs/json-converter xml2json -i data.xml --no-pretty
```

### JSON to CSV

```bash
# Convert JSON array to CSV
npx @raphaellcs/json-converter json2csv -i data.json

# Specify output file
npx @raphaellcs/json-converter json2csv -i data.json -o data.csv
```

### CSV to JSON

```bash
# Convert CSV to JSON
npx @raphaellcs/json-converter csv2json -i data.csv

# Specify output file
npx @raphaellcs/json-converter csv2json -i data.csv -o data.json

# Compact output
npx @raphaellcs/json-converter csv2json -i data.csv --no-pretty
```

## Examples

### Example 1: JSON to YAML

**Input file (data.json):**
```json
{
  "name": "John",
  "age": 30,
  "city": "New York",
  "skills": ["JavaScript", "Python"]
}
```

**Command:**
```bash
$ npx @raphaellcs/json-converter json2yaml -i data.json
✓ Converted successfully!
Output: data.yaml
```

**Output file (data.yaml):**
```yaml
name: John
age: 30
city: New York
skills:
  - JavaScript
  - Python
```

### Example 2: YAML to JSON

**Input file (config.yaml):**
```yaml
server:
  host: localhost
  port: 3000
database:
  name: myapp
  user: postgres
```

**Command:**
```bash
$ npx @raphaellcs/json-converter yaml2json -i config.yaml -o config.json
✓ Converted successfully!
Output: config.json
```

**Output file (config.json):**
```json
{
  "server": {
    "host": "localhost",
    "port": 3000
  },
  "database": {
    "name": "myapp",
    "user": "postgres"
  }
}
```

### Example 3: JSON to XML

**Input file (data.json):**
```json
{
  "user": {
    "name": "Alice",
    "email": "alice@example.com"
  }
}
```

**Command:**
```bash
$ npx @raphaellcs/json-converter json2xml -i data.json -r document -o data.xml
✓ Converted successfully!
Output: data.xml
```

**Output file (data.xml):**
```xml
<document>
  <user>
    <name>Alice</name>
    <email>alice@example.com</email>
  </user>
</document>
```

### Example 4: JSON Array to CSV

**Input file (users.json):**
```json
[
  {
    "name": "John",
    "age": 30,
    "city": "New York"
  },
  {
    "name": "Jane",
    "age": 25,
    "city": "London"
  }
]
```

**Command:**
```bash
$ npx @raphaellcs/json-converter json2csv -i users.json
✓ Converted successfully!
Output: users.csv
```

**Output file (users.csv):**
```csv
name,age,city
John,30,New York
Jane,25,London
```

### Example 5: CSV to JSON

**Input file (products.csv):**
```csv
name,price,stock
Laptop,999.99,50
Phone,699.99,100
Tablet,349.99,75
```

**Command:**
```bash
$ npx @raphaellcs/json-converter csv2json -i products.json -o products.json
✓ Converted successfully!
Output: products.json
```

**Output file (products.json):**
```json
[
  {
    "name": "Laptop",
    "price": "999.99",
    "stock": "50"
  },
  {
    "name": "Phone",
    "price": "699.99",
    "stock": "100"
  },
  {
    "name": "Tablet",
    "price": "349.99",
    "stock": "75"
  }
]
```

## Options

### Common Options

- `-i, --input <path>` - Input file path (required)
- `-o, --output <path>` - Output file path (optional, auto-generates if not specified)
- `-p, --pretty` - Pretty print output (default: true)
- `--no-pretty` - Compact output (no pretty print)

### JSON to XML Options

- `-r, --root <name>` - Root element name (default: 'root')

## Use Cases

- 📄 **Configuration**: Convert between JSON and YAML for config files
- 📊 **Data Export**: Convert database results to CSV
- 🔄 **API Integration**: Convert between API response formats
- 📦 **Data Migration**: Transform data between different systems
- 📝 **Documentation**: Convert JSON configs to human-readable YAML
- 🎯 **Testing**: Generate test data in different formats

## Format Support

| From / To | JSON | YAML | XML | CSV |
|-----------|------|------|-----|-----|
| JSON      | -    | ✅   | ✅  | ✅  |
| YAML      | ✅    | -    | ❌  | ❌  |
| XML       | ✅    | ❌    | -   | ❌  |
| CSV       | ✅    | ❌    | ❌  | -   |

## Tips

### 1. Working with Nested Structures

```json
{
  "users": [
    { "name": "John", "age": 30 },
    { "name": "Jane", "age": 25 }
  ]
}
```

When converting to CSV, the tool automatically extracts the array:
```csv
name,age
John,30
Jane,25
```

### 2. Custom Root Element for XML

```bash
npx @raphaellcs/json-converter json2xml -i data.json -r document
```

This wraps your JSON in a `<document>` root element.

### 3. Pretty vs Compact Output

```bash
# Pretty (default, readable)
npx @raphaellcs/json-converter json2yaml -i data.json

# Compact (minified)
npx @raphaellcs/json-converter json2yaml -i data.json --no-pretty
```

### 4. Auto-naming Output Files

If you don't specify output, the tool automatically names it:
- `data.json` → `data.yaml` (json2yaml)
- `config.yaml` → `config.json` (yaml2json)
- `data.json` → `data.xml` (json2xml)
- `data.csv` → `data.json` (csv2json)

## Limitations

- CSV conversion works best with flat data structures
- XML attributes are preserved but may appear as nested properties
- Very large files may use significant memory

## Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

## License

MIT

## Author

Dream Heart 🌙

## Links

- [npm](https://www.npmjs.com/package/@raphaellcs/json-converter)
- [GitHub](https://github.com/RaphaelLcs-financial/json-converter)