npm package: @mackan_eu/json-toolbox
Description: Deterministic data transformation pipelines - CLI for JSON, CSV, XML, YAML
Author: mackan.eu
Latest version: 2.3.0-final

# JSON Toolbox CLI

**Deterministic data transformation pipelines for JSON, CSV, XML, and YAML.**

[![Version](https://img.shields.io/npm/v/@mackan/json-toolbox.svg)](https://www.npmjs.com/package/@mackan/json-toolbox)
[![License](https://img.shields.io/npm/l/@mackan/json-toolbox.svg)](https://opensource.org/licenses/MIT)
[![Node](https://img.shields.io/node/v/@mackan/json-toolbox.svg)](https://nodejs.org)

## Features

- **🔧 42 Operators** across 9 namespaces (json, csv, xml, yaml, transform, query, schema, diff, fix)
- **📊 Pipeline System** - Chain operators with manifest files
- **🎯 Deterministic** - Same input always produces same output
- **📦 Zero Dependencies** - Pure JavaScript, no external libraries
- **🔒 Zero Telemetry** - No data collection, offline-capable
- **🌐 Browser/CLI Parity** - Same behavior everywhere

## Installation

### npm (Recommended)

```bash
npm install -g @mackan/json-toolbox
```

### One-liner Installers

**macOS/Linux:**
```bash
curl -fsSL https://mackan.eu/tools/json/cli/install.sh | bash
```

**Windows (PowerShell):**
```powershell
irm https://mackan.eu/tools/json/cli/install.ps1 | iex
```

### Verify Installation

```bash
json-toolbox version
# json-toolbox v2.2.0
```

## Quick Start

### Execute Single Operators

```bash
# Format JSON
echo '{"a":1,"b":2}' | json-toolbox exec json.format

# Parse CSV to JSON
cat data.csv | json-toolbox exec csv.parse --header true

# Filter array
echo '[{"age":20},{"age":30}]' | json-toolbox exec transform.filter --key age --operator gt --value 25

# Convert XML to JSON
cat data.xml | json-toolbox exec xml.parse
```

### Run Pipelines

Create a pipeline manifest `csv-to-json.json`:

```json
{
  "name": "csv-to-json",
  "version": "1.0.0",
  "steps": [
    { "operator": "csv.parse", "params": { "header": true } },
    { "operator": "transform.sort", "params": { "key": "name" } },
    { "operator": "json.stringify", "params": { "indent": 2 } }
  ]
}
```

Execute:

```bash
json-toolbox run csv-to-json.json < input.csv > output.json
```

## Commands

| Command | Description |
|---------|-------------|
| `run <manifest>` | Run a pipeline manifest |
| `exec <operator>` | Execute a single operator |
| `validate <manifest>` | Validate a pipeline manifest |
| `describe <operator>` | Show detailed operator info |
| `list-operators` | List all available operators |
| `help` | Show help message |
| `version` | Show version |

## Operator Reference

### Core Namespaces

| Namespace | Operators | Description |
|-----------|-----------|-------------|
| `json` | 10 | Parse, stringify, format, validate, path, keys, values, entries |
| `csv` | 3 | Parse, stringify, transpose |
| `xml` | 2 | Parse, stringify |
| `yaml` | 2 | Parse, stringify |

### Transform Namespace

| Namespace | Operators | Description |
|-----------|-----------|-------------|
| `transform` | 10 | Sort, filter, map, flatten, unique, reverse, slice, group, count, merge |

### Query & Schema

| Namespace | Operators | Description |
|-----------|-----------|-------------|
| `query` | 2 | JSONPath, select |
| `schema` | 2 | Generate, validate |

### Utilities

| Namespace | Operators | Description |
|-----------|-----------|-------------|
| `diff` | 2 | Compare, patch |
| `fix` | 2 | Repair, escape |

### Get Operator Details

```bash
json-toolbox describe transform.filter
```

```
Operator: transform.filter
Description: Filter array by expression or key/value match
Input Type: array
Output Type: array

Parameters:
  --key [default: null]
      Object key to filter by
  --operator [default: eq]
      Filter operator: eq, ne, gt, lt, gte, lte, contains, startsWith, endsWith, exists, empty
  --value [default: null]
      Value to compare against
  --expression [default: null]
      Filter expression (e.g., "age > 18")

Examples:
  json-toolbox exec transform.filter --key age --operator gt --value 18 < users.json
```

## Options

### Global Options

| Option | Description |
|--------|-------------|
| `--strict` | Error on unknown parameters (default: warn) |
| `-v, --verbose` | Show execution metrics and warnings |

### Run Command Options

| Option | Description |
|--------|-------------|
| `-i, --input <file>` | Input file (default: stdin) |
| `-o, --output <file>` | Output file (default: stdout) |
| `--dry-run` | Show execution plan without running |
| `--minify` | Minify output |

## Examples

### Data Conversion

```bash
# CSV → JSON
cat data.csv | json-toolbox exec csv.parse --header true | json-toolbox exec json.format

# JSON → YAML
cat data.json | json-toolbox exec yaml.stringify

# XML → JSON
cat data.xml | json-toolbox exec xml.parse | json-toolbox exec json.format
```

### Data Transformation

```bash
# Sort and filter
echo '[{"n":"c"},{"n":"a"},{"n":"b"}]' | \
  json-toolbox exec transform.sort --key n | \
  json-toolbox exec transform.filter --key n --operator ne --value b

# Extract and dedupe
cat users.json | \
  json-toolbox exec transform.map --extract email | \
  json-toolbox exec transform.unique

# Group and count
cat orders.json | \
  json-toolbox exec transform.group --key status
```

### Schema Generation

```bash
# Generate JSON Schema from sample
cat sample.json | json-toolbox exec schema.generate

# Validate against schema
echo '{"data":"test","schema":{...}}' | json-toolbox exec schema.validate
```

### JSON Repair

```bash
# Fix malformed JSON
echo "{'key': 'value',}" | json-toolbox exec fix.repair
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Invalid manifest |
| 3 | Invalid input |
| 10 | Unknown operator |
| 11 | Unknown parameter (strict mode) |

## Presets

The CLI includes example pipeline presets in the `presets/` directory:

- `csv-to-json.json` - Parse CSV and format as JSON
- `json-to-yaml.json` - Convert JSON to YAML
- `data-cleanup.json` - Remove duplicates and sort
- `generate-schema.json` - Generate JSON Schema
- `xml-to-json.json` - Parse XML to JSON

## Comparison with Other Tools

| Feature | json-toolbox | jq | yq | miller |
|---------|-------------|-----|-----|--------|
| JSON support | ✅ | ✅ | ✅ | ✅ |
| CSV support | ✅ | ❌ | ❌ | ✅ |
| XML support | ✅ | ❌ | ✅ | ❌ |
| YAML support | ✅ | ❌ | ✅ | ❌ |
| Pipeline manifests | ✅ | ❌ | ❌ | ❌ |
| Schema generation | ✅ | ❌ | ❌ | ❌ |
| JSON repair | ✅ | ❌ | ❌ | ❌ |
| Browser parity | ✅ | ❌ | ❌ | ❌ |
| Zero dependencies | ✅ | ❌ | ❌ | ❌ |

## Development

```bash
# Run tests
npm test

# Run parity tests
npm run test:parity

# Run all tests
npm run test:all
```

## Links

- **Web App**: https://mackan.eu/tools/json/
- **Documentation**: https://mackan.eu/tools/json/docs/
- **GitHub**: https://github.com/mackan-eu/json-toolbox
- **npm**: https://www.npmjs.com/package/@mackan/json-toolbox

## License

MIT License - see [LICENSE](LICENSE) for details.

---

**Made with ❤️ by [mackan.eu](https://mackan.eu)**