From 19f9a5527f2ca191a6cb8c85220a0570bc21b083 Mon Sep 17 00:00:00 2001 From: Johann Schopplich Date: Sun, 7 Dec 2025 13:10:09 +0100 Subject: [PATCH] docs: fix CLI options naming (fixes #241) --- docs/cli/index.md | 24 ++++++++++++------------ packages/cli/README.md | 20 ++++++++++---------- packages/cli/test/index.test.ts | 8 ++++---- 3 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/cli/index.md b/docs/cli/index.md index 9d1dcee..03a617c 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -120,7 +120,7 @@ Both encoding and decoding operations use streaming output, writing incrementall - Uses the same event-based streaming decoder as the `decodeStream` API in `@toon-format/toon`. - Streams JSON tokens to output. - No full JSON string in memory. -- When `--expand-paths safe` is enabled, falls back to non-streaming decode internally to apply deep-merge expansion before writing JSON. +- When `--expandPaths safe` is enabled, falls back to non-streaming decode internally to apply deep-merge expansion before writing JSON. Process large files with minimal memory usage: @@ -153,9 +153,9 @@ When using the `--stats` flag with encode, the CLI builds the full TOON string o | `--indent ` | Indentation size (default: `2`) | | `--stats` | Show token count estimates and savings (encode only) | | `--no-strict` | Disable strict validation when decoding | -| `--key-folding ` | Key folding mode: `off`, `safe` (default: `off`) | -| `--flatten-depth ` | Maximum segments to fold (default: `Infinity`) – requires `--key-folding safe` | -| `--expand-paths ` | Path expansion mode: `off`, `safe` (default: `off`) | +| `--keyFolding ` | Key folding mode: `off`, `safe` (default: `off`) | +| `--flattenDepth ` | Maximum segments to fold (default: `Infinity`) – requires `--keyFolding safe` | +| `--expandPaths ` | Path expansion mode: `off`, `safe` (default: `off`) | ## Advanced Examples @@ -247,11 +247,11 @@ Collapse nested wrapper chains to reduce tokens (since spec v1.5): ::: code-group ```bash [Basic key folding] -toon input.json --key-folding safe -o output.toon +toon input.json --keyFolding safe -o output.toon ``` ```bash [Limit folding depth] -toon input.json --key-folding safe --flatten-depth 2 -o output.toon +toon input.json --keyFolding safe --flattenDepth 2 -o output.toon ``` ::: @@ -270,7 +270,7 @@ For data like: } ``` -With `--key-folding safe`, output becomes: +With `--keyFolding safe`, output becomes: ```yaml data.metadata.items[2]: a,b @@ -289,19 +289,19 @@ data: Reconstruct nested structure from folded keys when decoding: ```bash -toon data.toon --expand-paths safe -o output.json +toon data.toon --expandPaths safe -o output.json ``` -This pairs with `--key-folding safe` for lossless round-trips. +This pairs with `--keyFolding safe` for lossless round-trips. ### Round-Trip Workflow ```bash # Encode with folding -toon input.json --key-folding safe -o compressed.toon +toon input.json --keyFolding safe -o compressed.toon # Decode with expansion (restores original structure) -toon compressed.toon --expand-paths safe -o output.json +toon compressed.toon --expandPaths safe -o output.json # Verify round-trip diff input.json output.json @@ -313,5 +313,5 @@ Combine multiple options for maximum efficiency: ```bash # Key folding + tab delimiter + stats -toon data.json --key-folding safe --delimiter "\t" --stats -o output.toon +toon data.json --keyFolding safe --delimiter "\t" --stats -o output.toon ``` diff --git a/packages/cli/README.md b/packages/cli/README.md index a895829..cb4706b 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -64,9 +64,9 @@ cat data.toon | toon --decode | `--indent ` | Indentation size (default: `2`) | | `--stats` | Show token count estimates and savings (encode only) | | `--no-strict` | Disable strict validation when decoding | -| `--key-folding ` | Enable key folding: `off`, `safe` (default: `off`) | -| `--flatten-depth ` | Maximum folded segment count when key folding is enabled (default: `Infinity`) | -| `--expand-paths ` | Enable path expansion: `off`, `safe` (default: `off`) | +| `--keyFolding ` | Enable key folding: `off`, `safe` (default: `off`) | +| `--flattenDepth ` | Maximum folded segment count when key folding is enabled (default: `Infinity`) | +| `--expandPaths ` | Enable path expansion: `off`, `safe` (default: `off`) | ## Advanced Examples @@ -136,7 +136,7 @@ cat million-records.toon | toon --decode > output.json - **Encode (JSON → TOON)**: Streams TOON lines to output without full string in memory - **Decode (TOON → JSON)**: Uses the same event-based streaming decoder as the `decodeStream` API in `@toon-format/toon`, streaming JSON tokens to output without full string in memory - Peak memory usage scales with data depth, not total size -- When `--expand-paths safe` is enabled, decode falls back to non-streaming mode internally to apply deep-merge expansion before writing JSON +- When `--expandPaths safe` is enabled, decode falls back to non-streaming mode internally to apply deep-merge expansion before writing JSON > [!NOTE] > When using `--stats` with encode, the full output string is kept in memory for token counting. Omit `--stats` for maximum memory efficiency with very large datasets. @@ -149,7 +149,7 @@ Collapse nested wrapper chains to reduce tokens: ```bash # Encode with key folding -toon input.json --key-folding safe -o output.toon +toon input.json --keyFolding safe -o output.toon ``` For data like: @@ -179,24 +179,24 @@ data: ```bash # Fold maximum 2 levels deep -toon input.json --key-folding safe --flatten-depth 2 -o output.toon +toon input.json --keyFolding safe --flattenDepth 2 -o output.toon ``` #### Path expansion on decode ```bash # Reconstruct nested structure from folded keys -toon data.toon --expand-paths safe -o output.json +toon data.toon --expandPaths safe -o output.json ``` #### Round-trip workflow ```bash # Encode with folding -toon input.json --key-folding safe -o compressed.toon +toon input.json --keyFolding safe -o compressed.toon # Decode with expansion (restores original structure) -toon compressed.toon --expand-paths safe -o output.json +toon compressed.toon --expandPaths safe -o output.json # Verify round-trip diff input.json output.json @@ -206,7 +206,7 @@ diff input.json output.json ```bash # Key folding + tab delimiter + stats -toon data.json --key-folding safe --delimiter "\t" --stats -o output.toon +toon data.json --keyFolding safe --delimiter "\t" --stats -o output.toon ``` ## Why Use the CLI? diff --git a/packages/cli/test/index.test.ts b/packages/cli/test/index.test.ts index 5c34645..d4753e1 100644 --- a/packages/cli/test/index.test.ts +++ b/packages/cli/test/index.test.ts @@ -306,7 +306,7 @@ describe('toon CLI', () => { }) describe('encode options', () => { - it('encodes with --key-folding safe', async () => { + it('encodes with --keyFolding safe', async () => { const data = { data: { metadata: { @@ -332,7 +332,7 @@ describe('toon CLI', () => { } }) - it('encodes with --flatten-depth', async () => { + it('encodes with --flattenDepth', async () => { const data = { level1: { level2: { @@ -362,7 +362,7 @@ describe('toon CLI', () => { }) describe('decode options', () => { - it('decodes with --expand-paths safe', async () => { + it('decodes with --expandPaths safe', async () => { const data = { data: { metadata: { @@ -715,7 +715,7 @@ describe('toon CLI', () => { } }) - it('rejects invalid --key-folding value', async () => { + it('rejects invalid --keyFolding value', async () => { const context = await createCliTestContext({ 'input.json': JSON.stringify({ value: 1 }), })