📦 threepointone / aywson

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851# aywson

𝖆𝖗𝖊 𝖞𝖆 𝖜𝖎𝖓𝖓𝖎𝖓𝖌, 𝖘𝖔𝖓?

![Are ya winning, son?](aywson.png)

Modify JSONC while preserving comments and formatting.

```sh
npm install aywson
```

## Usage

```ts
import {
  parse, // parse JSONC to object
  modify, // replace fields, delete unlisted
  get, // read value at path
  set, // write value at path (with optional comment)
  remove, // delete field at path
  merge, // update fields, keep unlisted
  replace, // alias for modify
  patch, // alias for merge
  rename, // rename a key
  move, // move field to new path
  getComment, // read comment (above or trailing)
  setComment, // add comment above field
  removeComment, // remove comment above field
  getTrailingComment, // read trailing comment
  setTrailingComment, // add trailing comment
  removeTrailingComment, // remove trailing comment
  sort, // sort object keys
  format // format/prettify JSONC
} from "aywson";
```

## `modify`

Replace fields, delete unlisted. Comments above deleted fields are also deleted, unless they start with `**`.

```ts
import { modify } from "aywson";

modify('{ /* keep this */ "a": 1, "b": 2 }', { a: 10 });
// → '{ /* keep this */ "a": 10 }' — comment preserved, b deleted
```

`modify` uses **replace semantics** — fields not in `changes` are deleted. Comments (both above and trailing) on deleted fields are also deleted, unless they start with `**`.

## `parse`

Parse a JSONC string into a JavaScript value. Unlike `JSON.parse()`, this handles comments and trailing commas.

```ts
import { parse } from "aywson";

parse(`{
  // database config
  "host": "localhost",
  "port": 5432,
}`);
// → { host: "localhost", port: 5432 }

// With TypeScript generics
interface Config {
  host: string;
  port: number;
}
const config = parse<Config>(jsonString);
```

## Path-based Operations

Paths can be specified as either:

- **String paths**: `"config.database.host"` or `"items[0].name"` (dot-notation, like the CLI)
- **Array paths**: `["config", "database", "host"]` or `["items", 0, "name"]`

Both formats work for all path-based operations.

### `get(json, path)`

Get a value at a path.

```ts
// Using string path
get('{ "config": { "enabled": true } }', "config.enabled");
// → true

// Using array path
get('{ "config": { "enabled": true } }', ["config", "enabled"]);
// → true
```

### `has(json, path)`

Check if a path exists.

```ts
has('{ "foo": "bar" }', "foo"); // → true (string path)
has('{ "foo": "bar" }', ["foo"]); // → true (array path)
has('{ "foo": "bar" }', "baz"); // → false
```

### `set(json, path, value, comment?)`

Set a value at a path, optionally with a comment.

```ts
// Using string path
set('{ "foo": "bar" }', "foo", "baz");
// → '{ "foo": "baz" }'

// Using array path
set('{ "foo": "bar" }', ["foo"], "baz");
// → '{ "foo": "baz" }'

// With a comment
set('{ "foo": "bar" }', "foo", "baz", "this is foo");
// → adds "// this is foo" above the field

// Nested paths work with both formats
set('{ "config": {} }', "config.enabled", true);
// or
set('{ "config": {} }', ["config", "enabled"], true);
```

### `remove(json, path)`

Remove a field. Comments (both above and trailing) are also removed, unless they start with `**`.

```ts
// Using string path
remove(
  `{
  // this is foo
  "foo": "bar",
  "baz": 123
}`,
  "foo"
);
// → '{ "baz": 123 }' — comment removed too

// Using array path
remove(
  `{
  "foo": "bar", // trailing comment
  "baz": 123
}`,
  ["foo"]
);
// → '{ "baz": 123 }' — trailing comment removed too

// Nested paths
remove(json, "config.database.host");
// or
remove(json, ["config", "database", "host"]);
```

## Merge Strategies

### `merge(json, changes)`

Update/add fields, never delete (unless explicit `undefined`).

```ts
merge('{ "a": 1, "b": 2 }', { a: 10 });
// → '{ "a": 10, "b": 2 }' — b preserved
```

### `replace(json, changes)`

Delete fields not in changes (same as `modify`).

```ts
replace('{ "a": 1, "b": 2 }', { a: 10 });
// → '{ "a": 10 }' — b deleted
```

### `patch(json, changes)`

Alias for `merge`. Use `undefined` to delete.

```ts
patch('{ "a": 1, "b": 2 }', { a: undefined });
// → '{ "b": 2 }' — a explicitly deleted
```

## Key Operations

### `rename(json, path, newKey)`

Rename a key while preserving its value.

```ts
// Using string path
rename('{ "oldName": 123 }', "oldName", "newName");
// → '{ "newName": 123 }'

// Using array path
rename('{ "oldName": 123 }', ["oldName"], "newName");
// → '{ "newName": 123 }'

// Nested paths
rename(json, "config.oldKey", "newKey");
// or
rename(json, ["config", "oldKey"], "newKey");
```

### `move(json, fromPath, toPath)`

Move a field to a different location.

```ts
// Using string paths
move(
  '{ "source": { "value": 123 }, "target": {} }',
  "source.value",
  "target.value"
);
// → '{ "source": {}, "target": { "value": 123 } }'

// Using array paths
move(
  '{ "source": { "value": 123 }, "target": {} }',
  ["source", "value"],
  ["target", "value"]
);
// → '{ "source": {}, "target": { "value": 123 } }'

// Mixed formats also work
move(json, "source.value", ["target", "value"]);
```

## Sort Operations

### `sort(json, path?, options?)`

Sort object keys alphabetically while preserving comments (both above and trailing) with their respective keys.

```ts
sort(`{
  // z comment
  "z": 1,
  // a comment
  "a": 2
}`);
// → '{ "a": 2, "z": 1 }' with comments preserved

// Trailing comments are also preserved
sort(`{
  "z": 1, // z trailing
  "a": 2 // a trailing
}`);
// → '{ "a": 2 // a trailing, "z": 1 // z trailing }'
```

**Path:** Specify a path to sort only a nested object (defaults to `""` or `[]` for root).

```ts
// Using string path
sort(json, "config.database"); // Sort only the database object

// Using array path
sort(json, ["config", "database"]); // Sort only the database object

// Root level (both equivalent)
sort(json); // or sort(json, "") or sort(json, [])
```

**Options:**

- `comparator?: (a: string, b: string) => number` — Custom sort function. Defaults to alphabetical.
- `deep?: boolean` — Sort nested objects recursively. Defaults to `true`.

```ts
// Custom sort order (reverse alphabetical)
sort(json, "", { comparator: (a, b) => b.localeCompare(a) });

// Only sort top-level keys (not nested objects)
sort(json, "", { deep: false });

// Sort only a specific nested object, non-recursively
sort(json, "config", { deep: false });
```

````

## Format Operations

### `format(json, options?)`

Format a JSONC document with consistent indentation. Preserves comments while normalizing whitespace.

```ts
import { format } from "aywson";

// Format minified JSON
format('{"foo":"bar","baz":123}');
// → '{
//   "foo": "bar",
//   "baz": 123
// }'

// Comments are preserved
format('{ /* important */ "foo": "bar" }');
// → '{
//   /* important */
//   "foo": "bar"
// }'
````

**Options:**

- `tabSize?: number` — Number of spaces per indentation level. Defaults to `2`.
- `insertSpaces?: boolean` — Use spaces instead of tabs. Defaults to `true`.
- `eol?: string` — End of line character. Defaults to `'\n'`.

```ts
// Use 4 spaces for indentation
format(json, { tabSize: 4 });

// Use tabs instead of spaces
format(json, { insertSpaces: false });

// Use Windows-style line endings
format(json, { eol: "\r\n" });
```

## Comment Operations

### `setComment(json, path, comment)`

Add or update a comment above a field.

```ts
// Using string path
setComment(
  `{
  "enabled": true
}`,
  "enabled",
  "controls the feature"
);
// → adds "// controls the feature" above the field

// Using array path
setComment(json, ["config", "enabled"], "controls the feature");
```

### `removeComment(json, path)`

Remove the comment above a field.

```ts
// Using string path
removeComment(
  `{
  // this will be removed
  "foo": "bar"
}`,
  "foo"
);
// → '{ "foo": "bar" }'

// Using array path
removeComment(json, ["config", "enabled"]);
```

### `getComment(json, path)`

Get the comment associated with a field. First checks for a comment above, then falls back to a trailing comment.

```ts
// Using string path
getComment(
  `{
  // this is foo
  "foo": "bar"
}`,
  "foo"
);
// → "this is foo"

// Using array path
getComment(
  `{
  "foo": "bar" // trailing comment
}`,
  ["foo"]
);
// → "trailing comment"

getComment('{ "foo": "bar" }', "foo");
// → null (no comment)
```

## Trailing Comments

Trailing comments are comments on the same line after a field value:

```jsonc
{
  "foo": "bar", // this is a trailing comment
  "baz": 123 // another trailing comment
}
```

### `getTrailingComment(json, path)`

Get the trailing comment after a field (explicitly, ignoring comments above).

```ts
// Using string path
getTrailingComment(
  `{
  "foo": "bar", // trailing comment
  "baz": 123
}`,
  "foo"
);
// → "trailing comment"

// Using array path
getTrailingComment(json, ["config", "database", "host"]);
```

### `setTrailingComment(json, path, comment)`

Add or update a trailing comment after a field.

```ts
// Using string path
setTrailingComment(
  `{
  "foo": "bar",
  "baz": 123
}`,
  "foo",
  "this is foo"
);
// → '{ "foo": "bar" // this is foo, "baz": 123 }'

// Using array path
setTrailingComment(
  `{
  "foo": "bar", // old comment
  "baz": 123
}`,
  ["foo"],
  "new comment"
);
// → replaces "old comment" with "new comment"
```

### `removeTrailingComment(json, path)`

Remove the trailing comment after a field.

```ts
// Using string path
removeTrailingComment(
  `{
  "foo": "bar", // this will be removed
  "baz": 123
}`,
  "foo"
);
// → '{ "foo": "bar", "baz": 123 }'

// Using array path
removeTrailingComment(json, ["config", "database", "host"]);
```

### Comments Above vs Trailing

You can have both a comment above and a trailing comment:

```ts
const json = `{
  // comment above
  "foo": "bar", // trailing comment
  "baz": 123
}`;

getComment(json, "foo"); // → "comment above" (prefers above)
getTrailingComment(json, "foo"); // → "trailing comment"

// Set comment above (preserves trailing)
setComment(json, "foo", "new above");
// → both comments preserved, above is updated

// Remove comment above (preserves trailing)
removeComment(json, "foo");
// → trailing comment still there
```

## Preserving Comments

When deleting fields, comments are deleted by default. Start a comment with `**` to preserve it:

```ts
remove(
  `{
  // this comment will be deleted
  "config": {}
}`,
  "config"
);
// → '{}' — comment deleted with field

remove(
  `{
  // ** this comment will be preserved
  "config": {}
}`,
  "config"
);
// → '{ // ** this comment will be preserved }' — comment kept
```

## Object Iteration & Transformation

Even though aywson works on strings, you can still do full object manipulation:

```ts
import { parse, set, remove, merge } from "aywson";

let json = `{
  // Database settings
  "database": {
    "host": "localhost",
    "port": 5432
  },
  // Feature flags
  "features": {
    "darkMode": false,
    "beta": true
  }
}`;

// Parse to iterate/transform
const config = parse<Record<string, unknown>>(json);

// Example: Update all feature flags to false
for (const [key, value] of Object.entries(config.features as object)) {
  if (typeof value === "boolean") {
    json = set(json, `features.${key}`, false); // String path
    // or: json = set(json, ["features", key], false); // Array path
  }
}

// Example: Remove fields based on condition
for (const key of Object.keys(config)) {
  if (key.startsWith("_")) {
    json = remove(json, key); // String path
    // or: json = remove(json, [key]); // Array path
  }
}

// Example: Bulk update from transformed object
const updates = Object.fromEntries(
  Object.entries(config.database as object).map(([k, v]) => [
    k,
    typeof v === "string" ? v.toUpperCase() : v
  ])
);
json = merge(json, { database: updates });
```

The key insight: use `parse()` to read and decide _what_ to change, then use `set()`/`remove()`/`merge()` to apply changes while preserving formatting and comments.

## Building JSONC from Scratch

You can build a JSONC file from scratch using `set()` with comments:

```ts
import { set } from "aywson";

let json = "{}";

// Build up the structure with comments (using string paths)
json = set(json, "database", {}, "Database configuration");
json = set(json, "database.host", "localhost", "Primary database host");
json = set(json, "database.port", 5432);
json = set(json, "database.ssl", true, "Enable SSL in production");

json = set(json, "features", {}, "Feature flags");
json = set(json, "features.darkMode", false);
json = set(json, "features.beta", true, "Beta features - use with caution");
// Note: Array paths like ["database", "host"] are also supported

console.log(json);
```

Output:

```jsonc
{
  // Database configuration
  "database": {
    // Primary database host
    "host": "localhost",
    "port": 5432,
    // Enable SSL in production
    "ssl": true
  },
  // Feature flags
  "features": {
    "darkMode": false,
    // Beta features - use with caution
    "beta": true
  }
}
```

For more complex construction, you can also use `merge()`:

```ts
import { merge, setComment } from "aywson";

let json = "{}";

// Add multiple fields at once
json = merge(json, {
  name: "my-app",
  version: "1.0.0",
  scripts: {
    build: "tsc",
    test: "vitest"
  }
});

// Add comments where needed
json = setComment(json, "scripts", "Available npm scripts");
// Note: Array paths like ["scripts"] are also supported
```

## CLI

```bash
# Parse JSONC to JSON (strips comments, handles trailing commas)
aywson parse config.jsonc

# Read a value
aywson get config.json database.host

# Set a value (shows diff and writes to file)
aywson set config.json database.port 5433

# Preview without writing
aywson set --dry-run config.json database.port 5433

# Modify with replace semantics
aywson modify config.json '{"database": {"host": "prod.db.com"}}'

# Merge without deleting existing fields
aywson merge config.json '{"newField": true}'

# Remove a field
aywson remove config.json database.debug

# Sort object keys alphabetically
aywson sort config.json

# Sort only a specific nested object
aywson sort config.json dependencies

# Sort without recursing into nested objects
aywson sort config.json --no-deep

# Format/prettify JSONC
aywson format config.json

# Format with 4-space indentation
aywson format config.json --tab-size 4

# Format with tabs instead of spaces
aywson format config.json --tabs

# Get a comment (above, or trailing as fallback)
aywson comment config.json database.host

# Set a comment above a field
aywson comment config.json database.host "production database"

# Remove a comment above a field
aywson uncomment config.json database.host

# Get a trailing comment explicitly
aywson comment --trailing config.json database.port

# Set a trailing comment
aywson comment --trailing config.json database.port "default: 5432"

# Remove a trailing comment
aywson uncomment --trailing config.json database.port
```

Mutating commands always show a colored diff. Use `--dry-run` (`-n`) to preview without writing.

**Path syntax:** The CLI uses dot-notation: `config.database.host` or bracket notation for indices: `items[0].name`. The API supports both string paths (same as CLI) and array paths: `["config", "database", "host"]`.

### Security Options

```bash
# Path validation (prevents path traversal attacks)
aywson get config.json database.host  # ✅ Works
aywson get ../etc/passwd root          # ❌ Blocked by default
aywson get --allow-path-traversal ../etc/passwd root  # ✅ Override (not recommended)

# File size limits (default: 50MB)
aywson parse large.json  # ✅ Works if < 50MB
aywson parse --max-file-size 100000000 large.json  # ✅ Custom limit (100MB)
aywson parse --no-file-size-limit huge.json  # ✅ Disable limit (not recommended)

# JSON parsing limits (via environment variables)
AYWSON_MAX_JSON_SIZE=20000000 aywson modify config.json '{"large": "data"}'
AYWSON_MAX_JSON_DEPTH=200 aywson merge config.json '{"deep": {"nested": {...}}}'
```

## Security

aywson includes several security features to protect against common attacks when processing untrusted input:

### Path Validation

By default, the CLI prevents path traversal attacks by validating that all file paths stay within the current working directory. This prevents access to files outside the intended directory (e.g., `../etc/passwd`).

**Override:** Use the `--allow-path-traversal` flag to bypass this protection (not recommended for untrusted input).

```bash
# Blocked by default
aywson get ../sensitive-file.json key

# Override (use with caution)
aywson get --allow-path-traversal ../sensitive-file.json key
```

### File Size Limits

To prevent memory exhaustion attacks, file size is limited by default to **50MB**. Files larger than this limit will be rejected.

**Override:** Use `--max-file-size <bytes>` to set a custom limit, or `--no-file-size-limit` to disable the limit entirely.

```bash
# Default 50MB limit
aywson parse large.json

# Custom limit (100MB)
aywson parse --max-file-size 104857600 large.json

# No limit (not recommended)
aywson parse --no-file-size-limit huge.json
```

**Note:** Stdin (`-`) is exempt from file size limits.

### JSON Parsing Limits

JSON input is validated for both size and nesting depth to prevent denial-of-service attacks:

- **Default max size:** 10MB
- **Default max depth:** 100 levels

**Override:** Set environment variables to customize these limits:

```bash
# Increase JSON size limit to 20MB
AYWSON_MAX_JSON_SIZE=20971520 aywson modify config.json '{"large": "data"}'

# Increase depth limit to 200 levels
AYWSON_MAX_JSON_DEPTH=200 aywson merge config.json '{"deep": {...}}'

# Both limits
AYWSON_MAX_JSON_SIZE=20971520 AYWSON_MAX_JSON_DEPTH=200 aywson modify config.json '...'
```

These limits apply to JSON arguments in `set`, `modify`, and `merge` commands.

### Security Best Practices

1. **Don't disable security features** unless you fully trust your input sources
2. **Use appropriate limits** for your use case rather than disabling them entirely
3. **Validate input** before passing it to aywson when processing untrusted data
4. **Run with least privilege** - don't run aywson as root or with elevated permissions
5. **Keep dependencies updated** - regularly update aywson and its dependencies for security patches

## Comparison with `comment-json`

[`comment-json`](https://www.npmjs.com/package/comment-json) is another popular package for working with JSON files that contain comments. Here's how the two packages differ:

### Architecture

| Aspect              | aywson                                | comment-json                           |
| ------------------- | ------------------------------------- | -------------------------------------- |
| **Approach**        | String-in, string-out                 | Parse to object, modify, stringify     |
| **Formatting**      | Preserves original formatting exactly | Re-stringifies (may change formatting) |
| **Mutations**       | Immutable (returns new string)        | Mutable (modifies object in place)     |
| **Comment storage** | Stays in the string                   | Symbol properties on object            |

### Feature Set

| Category              | aywson                                                       | comment-json                         |
| --------------------- | ------------------------------------------------------------ | ------------------------------------ |
| **Core**              | `parse()`                                                    | `parse()`, `stringify()`, `assign()` |
| **Path operations**   | `get()`, `has()`, `set()`, `remove()`                        | Object/array access                  |
| **Bulk updates**      | `merge()`, `modify()`                                        | `assign()`                           |
| **Key manipulation**  | `rename()`, `move()`, `sort()`                               | ❌                                   |
| **Comment API**       | `getComment()`, `setComment()`, `getTrailingComment()`, etc. | Symbol-based access                  |
| **Comment positions** | Above field and trailing (same line)                         | Many (before, after, inline, etc.)   |
| **Extras**            | CLI, `**` prefix to preserve comments                        | `CommentArray` for array operations  |

### When to use aywson

- You need **exact formatting preservation** (whitespace, indentation, trailing commas)
- You want **surgical edits** without re-serializing the entire file
- You prefer **immutable operations** that return new strings
- You need **high-level operations** like rename, move, or sort
- You want **explicit comment manipulation** with a simple API

### When to use comment-json

- You want to work with a **JavaScript object** and make many modifications before writing back
- You're comfortable with **Symbol-based comment access**
- Re-stringifying the entire file is acceptable for your use case

### Example comparison

**comment-json:**

```js
const { parse, stringify, assign } = require("comment-json");

const obj = parse(jsonString);
obj.database.port = 5433;
assign(obj.database, { ssl: true });
const result = stringify(obj, null, 2);
```

**aywson:**

```js
import { set, merge } from "aywson";

let result = set(jsonString, "database.port", 5433);
result = merge(result, { database: { ssl: true } });
// Original formatting preserved exactly
```