{"id":30363818,"url":"https://github.com/deans-bradley/file-to-json","last_synced_at":"2026-05-09T06:02:45.605Z","repository":{"id":307598724,"uuid":"1029632939","full_name":"deans-bradley/file-to-json","owner":"deans-bradley","description":"A powerful and flexible Node.js CLI tool that converts various file formats to JSON with clean, well-structured output.","archived":false,"fork":false,"pushed_at":"2025-08-01T04:06:46.000Z","size":12,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-19T20:05:04.206Z","etag":null,"topics":["cli","converter","csv","csv-parser","excel","json","nodejs","xlsx"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deans-bradley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-31T10:36:16.000Z","updated_at":"2025-08-01T04:06:49.000Z","dependencies_parsed_at":"2025-08-01T05:34:17.933Z","dependency_job_id":"b21944fe-7b23-4126-8a7c-1b1617de55f0","html_url":"https://github.com/deans-bradley/file-to-json","commit_stats":null,"previous_names":["deans-bradley/file-to-json"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/deans-bradley/file-to-json","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deans-bradley%2Ffile-to-json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deans-bradley%2Ffile-to-json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deans-bradley%2Ffile-to-json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deans-bradley%2Ffile-to-json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deans-bradley","download_url":"https://codeload.github.com/deans-bradley/file-to-json/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deans-bradley%2Ffile-to-json/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32809147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","converter","csv","csv-parser","excel","json","nodejs","xlsx"],"created_at":"2025-08-19T19:50:50.664Z","updated_at":"2026-05-09T06:02:45.599Z","avatar_url":"https://github.com/deans-bradley.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# File to JSON Converter\n\nA powerful and flexible Node.js CLI tool that converts various file formats to JSON with clean, well-structured output.\n\n## Features\n\n- **Multiple formats** - Convert CSV and Excel files (.xlsx, .xls) to JSON\n- **Smart detection** - Auto-detect file types or use specific commands\n- **Data cleaning** - Automatically trims whitespace and handles empty cells\n- **Flexible output** - Custom filenames, pretty formatting, and sheet selection\n- **Fast processing** - Efficient streaming for large files\n- **Professional CLI** - Built with Commander.js for excellent UX\n- **Clear feedback** - Detailed progress and conversion statistics\n\n## Installation\n\n1. **Clone or download** the project files\n2. **Install dependencies:**\n   ```bash\n   npm install\n   ```\n3. **Make executable (optional):**\n   ```bash\n   chmod +x bin/ftj.js\n   ```\n\n## Usage\n\n### CSV Conversion\n\nConvert comma or semicolon-delimited CSV files to JSON:\n\n```bash\n# Basic CSV conversion\nftj csv data.csv\n\n# Custom output with pretty formatting\nftj csv employees.csv -o staff.json --pretty\n\n# Semicolon-delimited CSV\nftj csv european-data.csv --delimiter comma --pretty\n```\n\n### Excel Conversion\n\nConvert Excel workbooks (.xlsx, .xls) to JSON:\n\n```bash\n# Convert all sheets\nftj excel workbook.xlsx --pretty\n\n# Convert specific sheet\nftj excel sales-data.xlsx --sheet \"Q4 Results\" -o q4.json\n\n# Custom output file\nftj excel report.xlsx -o converted-report.json --pretty\n```\n\n### Auto-Detection\n\nLet the tool detect the file type automatically:\n\n```bash\n# Auto-detect and convert\nftj convert data.csv --pretty\nftj convert spreadsheet.xlsx --sheet \"Summary\"\n```\n\n### File Information\n\nGet detailed information about your files:\n\n```bash\n# Check file details and get usage suggestions\nftj info myfile.xlsx\nftj info data.csv\n```\n\n## Command Reference\n\n### `csv` - Convert CSV files\n\n| Option               | Short | Description                                 |\n|----------------------|-------|---------------------------------------------|\n| `--output \u003cfile\u003e`    | `-o`  | Specify output JSON file                    |\n| `--delimiter \u003ctype\u003e` | `-d`  | Delimiter: `semicolon` (default) or `comma` |\n| `--pretty`           | `-p`  | Format JSON with indentation                |\n\n### `excel` - Convert Excel files\n\n| Option            | Short | Description                                            |\n|-------------------|-------|--------------------------------------------------------|\n| `--output \u003cfile\u003e` | `-o`  | Specify output JSON file                               |\n| `--sheet \u003cname\u003e`  | `-s`  | Convert specific sheet (converts all if not specified) |\n| `--pretty`        | `-p`  | Format JSON with indentation                           |\n\n### `convert` - Auto-detect and convert\n\n| Option               | Short | Description                      |\n|----------------------|-------|----------------------------------|\n| `--output \u003cfile\u003e`    | `-o`  | Specify output JSON file         |\n| `--delimiter \u003ctype\u003e` | `-d`  | CSV delimiter (if CSV file)      |\n| `--sheet \u003cname\u003e`     | `-s`  | Excel sheet name (if Excel file) |\n| `--pretty`           | `-p`  | Format JSON with indentation     |\n\n### `info` - File information\n\nDisplays file details, supported status, and usage suggestions.\n\n## Examples\n\n### CSV Example\n\n**Input (employees.csv):**\n```csv\nname;age;department;salary\nJohn Doe;30;Engineering;75000\nJane Smith;28;Marketing;65000\nBob Johnson;35;Engineering;80000\n```\n\n**Command:**\n```bash\nftj csv employees.csv --pretty\n```\n\n**Output (employees.json):**\n```json\n[\n  {\n    \"name\": \"John Doe\",\n    \"age\": \"30\",\n    \"department\": \"Engineering\",\n    \"salary\": \"75000\"\n  },\n  {\n    \"name\": \"Jane Smith\",\n    \"age\": \"28\",\n    \"department\": \"Marketing\",\n    \"salary\": \"65000\"\n  },\n  {\n    \"name\": \"Bob Johnson\",\n    \"age\": \"35\",\n    \"department\": \"Engineering\",\n    \"salary\": \"80000\"\n  }\n]\n```\n\n### Excel Example\n\n**Input:** Excel file with multiple sheets (Sales, Inventory, Staff)\n\n**Command:**\n```bash\nftj excel company-data.xlsx --sheet \"Sales\" --pretty\n```\n\n**Output:** JSON object with data from the \"Sales\" sheet\n\n**Convert all sheets:**\n```bash\nftj excel company-data.xlsx --pretty\n```\n\n**Output:** JSON object with all sheets as separate properties:\n```json\n{\n  \"Sales\": [\n    { \"product\": \"Widget A\", \"revenue\": 5000 }\n  ],\n  \"Inventory\": [\n    { \"item\": \"Widget A\", \"stock\": 150 }\n  ],\n  \"Staff\": [\n    { \"name\": \"John Doe\", \"role\": \"Manager\" }\n  ]\n}\n```\n\n## Supported File Types\n\n| Format    | Extensions      | Features                                                       |\n|-----------|-----------------|----------------------------------------------------------------|\n| **CSV**   | `.csv`          | Comma/semicolon delimiters, header detection, data cleaning    |\n| **Excel** | `.xlsx`, `.xls` | Multiple sheets, sheet selection, cell formatting preservation |\n\n## File Structure\n\n```\nfile-to-json/\n├── bin/\n│   └── ftj.js                 # Main CLI application\n├── converters/\n│   ├── csv-converter.js       # CSV conversion logic\n│   └── excel-converter.js     # Excel conversion logic\n├── package.json               # Project configuration\n└── README.md                  # Documentation\n```\n\n## Global Installation (Optional)\n\nInstall globally to use from anywhere on your system:\n\n```bash\n# Install globally\nnpm install -g .\n\n# Use from any directory\nftj csv ~/Documents/data.csv --pretty\nftj excel ~/Downloads/report.xlsx --sheet \"Summary\"\n```\n\n## Path Handling\n\nThe tool works with both relative and absolute paths:\n\n```bash\n# Same directory\nftj csv data.csv\n\n# Relative path\nftj csv ../documents/data.csv\n\n# Absolute path (Windows)\nftj csv \"C:\\Users\\brad\\Documents\\data.csv\"\n\n# Absolute path (Unix/Mac)\nftj csv /home/user/documents/data.csv\n```\n\n**Tip:** If your file path contains spaces, wrap it in quotes!\n\n## Data Processing\n\n### CSV Processing\n- Automatically detects and cleans headers\n- Trims whitespace from all values\n- Skips empty rows\n- Supports both comma (`,`) and semicolon (`;`) delimiters\n- Each row becomes a JSON object in an array\n\n### Excel Processing\n- Processes all sheets or specific sheets\n- Cleans column headers and cell values\n- Handles empty cells gracefully\n- Maintains data types where possible\n- Multiple sheets become separate JSON properties\n\n## Troubleshooting\n\n**File not found:**\n- Check the file path and ensure the file exists\n- Use quotes around paths with spaces\n\n**Permission denied:**\n- Make the script executable: `chmod +x bin/ftj.js`\n- Check file permissions for input/output directories\n\n**Excel sheet not found:**\n- Use `ftj info file.xlsx` to see available sheet names\n- Sheet names are case-sensitive\n\n**Wrong CSV output:**\n- Try `--delimiter comma`\n- Check if your CSV uses a different delimiter\n\n**Memory issues with large files:**\n- The tool streams data efficiently, but very large Excel files may need more memory\n- Consider converting one sheet at a time for huge workbooks\n\n## Requirements\n\n- **Node.js** 14.0 or higher\n- **npm** for package management\n\n## Dependencies\n\n- `commander` (^14.0.0) - Professional CLI framework\n- `csv-parser` (^3.2.0) - Robust CSV parsing\n- `xlsx` (^0.18.5) - Excel file processing\n\n## Contributing\n\nThis tool is designed to be extensible! Ideas for future enhancements:\n\n- **Additional formats**: JSON to other formats, TSV files, XML conversion\n- **Data transformation**: Type conversion, field mapping, filtering\n- **Advanced Excel features**: Formula evaluation, cell styling preservation\n- **Performance**: Progress bars, parallel processing for multiple files\n- **Validation**: Schema validation, data quality checks\n\n## License\n\nMIT License - Feel free to use and modify as needed.\n\n## Getting Help\n\n```bash\n# General help\nftj --help\n\n# Command-specific help\nftj csv --help\nftj excel --help\n\n# File information and suggestions\nftj info your-file.csv\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeans-bradley%2Ffile-to-json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeans-bradley%2Ffile-to-json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeans-bradley%2Ffile-to-json/lists"}