### Install aywson

Source: https://github.com/threepointone/aywson/blob/main/README.md

Install the aywson library using npm.

```sh
npm install aywson
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/threepointone/aywson/blob/main/CONTRIBUTING.md

Install the necessary dependencies for the aywson project using npm.

```bash
npm install
```

--------------------------------

### CLI: Get a value from JSONC

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `get` command to retrieve a specific value from a JSONC file using dot-notation or bracket notation for paths.

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

--------------------------------

### CLI: Path validation example

Source: https://github.com/threepointone/aywson/blob/main/README.md

Demonstrates Aywson's default path validation which prevents path traversal attacks. Use `--allow-path-traversal` to override, though this is not recommended.

```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)
```

--------------------------------

### get(json, path)

Source: https://github.com/threepointone/aywson/blob/main/README.md

Retrieves a value from a JSON object at the specified path. Paths can be provided as dot-notation strings or arrays.

```APIDOC
## get(json, path)

### Description
Retrieves a value from a JSON object at the specified path. Paths can be provided as dot-notation strings or arrays.

### Parameters
- **json** (string | object) - The JSON data to query.
- **path** (string | array) - The path to the value. Can be a dot-notation string (e.g., "config.database.host") or an array (e.g., ["config", "database", "host"]).

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

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

--------------------------------

### Get Value with String Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Retrieves a value from a JSON object using a dot-notation string path. Ensure the JSON is valid.

```typescript
get('{ "config": { "enabled": true } }', "config.enabled");
// → true
```

--------------------------------

### CLI: Get a comment from JSONC

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `comment` command to retrieve a comment associated with a field. It prioritizes comments above the field, falling back to trailing comments.

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

--------------------------------

### Get Value with Array Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Retrieves a value from a JSON object using an array path. This method is equivalent to using string paths.

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

--------------------------------

### Get Comment Above Field

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `getComment` to retrieve the comment situated above a JSON field. It prioritizes comments above over trailing ones if both exist.

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

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

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

--------------------------------

### CLI: Get a trailing comment explicitly

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `--trailing` option with the `comment` command to specifically retrieve a comment positioned after the field on the same line.

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

--------------------------------

### Remove Field with String Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Removes a field and its associated comments from a JSON object using a string path. Comments starting with '**' are preserved.

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

--------------------------------

### Get Trailing Comment After Field

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `getTrailingComment` to specifically retrieve the comment located after a JSON field on the same line. Supports string and array paths.

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

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

--------------------------------

### Remove Field with Array Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Removes a field and its trailing comment from a JSON object using an array path. Comments are removed unless they start with '**'.

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

--------------------------------

### Modify JSONC with aywson

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `modify` function to replace fields in a JSONC string. Fields not present in the changes object are deleted, and their comments are preserved 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
```

--------------------------------

### Build the aywson Project

Source: https://github.com/threepointone/aywson/blob/main/CONTRIBUTING.md

Build the aywson project for deployment or distribution.

```bash
npm run build
```

--------------------------------

### CLI: Preview setting a value

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `--dry-run` option with the `set` command to preview changes without writing them to the file.

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

--------------------------------

### Run Project Tests

Source: https://github.com/threepointone/aywson/blob/main/CONTRIBUTING.md

Execute the test suite for the aywson project.

```bash
npm test
```

--------------------------------

### Check Code Style and Types

Source: https://github.com/threepointone/aywson/blob/main/CONTRIBUTING.md

Run Biome and TypeScript checks to ensure code quality and correctness.

```bash
npm run check
```

--------------------------------

### Create a Changeset

Source: https://github.com/threepointone/aywson/blob/main/CONTRIBUTING.md

Generate a changeset file for versioning and changelog updates using the Changesets tool.

```bash
npx changeset
```

--------------------------------

### Clone aywson Repository

Source: https://github.com/threepointone/aywson/blob/main/CONTRIBUTING.md

Clone the aywson repository and navigate into the project directory.

```bash
git clone https://github.com/threepointone/aywson.git
cd aywson
```

--------------------------------

### CLI: Format/prettify JSONC

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `format` command to prettify the JSONC file with standard indentation.

```bash
# Format/prettify JSONC
aywson format config.json
```

--------------------------------

### CLI: File size limits

Source: https://github.com/threepointone/aywson/blob/main/README.md

Shows how to manage file size limits for Aywson operations. The default limit is 50MB, but this can be customized or disabled.

```bash
# 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)
```

--------------------------------

### CLI: JSON parsing limits via environment variables

Source: https://github.com/threepointone/aywson/blob/main/README.md

Illustrates setting JSON parsing limits like maximum size and depth using environment variables for Aywson operations.

```bash
# 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": {...}}}'
```

--------------------------------

### CLI: Format JSONC with tabs

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `--tabs` option with the `format` command to use tabs instead of spaces for indentation.

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

--------------------------------

### Import aywson functions

Source: https://github.com/threepointone/aywson/blob/main/README.md

Import various utility functions from the aywson library for JSONC manipulation.

```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";
```

--------------------------------

### CLI: Format JSONC with custom indentation

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `--tab-size` option with the `format` command to specify the number of spaces for indentation.

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

--------------------------------

### Build JSONC with set()

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `set()` function to incrementally build a JSONC structure, adding fields and comments.

```typescript
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);
```

--------------------------------

### format(json, options?)

Source: https://github.com/threepointone/aywson/blob/main/README.md

Formats a JSONC document with consistent indentation, preserving comments and normalizing whitespace.

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

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

### Method
`format`

### Parameters
- **json** (string | object) - The input JSONC string or object.
- **options** (object) - Optional. Formatting 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"`.

### Request Example
```json
import { format } from "aywson";

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

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

// 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" });
```

### Response
```json
// Example for minified JSON
'{ 
  "foo": "bar",
  "baz": 123
}'

// Example with preserved comment
'{ 
  /* important */
  "foo": "bar"
}'
```
```

--------------------------------

### Override Default File Size Limit

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `--max-file-size <bytes>` to set a custom file size limit or `--no-file-size-limit` to disable it. The default limit is 50MB.

```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
```

--------------------------------

### Demonstrate Comment Precedence and Preservation

Source: https://github.com/threepointone/aywson/blob/main/README.md

Illustrates how `getComment` prioritizes above-field comments and how `setComment` and `removeComment` preserve trailing comments.

```typescript
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
```

--------------------------------

### Increase JSON Parsing Limits via Environment Variables

Source: https://github.com/threepointone/aywson/blob/main/README.md

Set `AYWSON_MAX_JSON_SIZE` and `AYWSON_MAX_JSON_DEPTH` environment variables to customize JSON size (default 10MB) and nesting depth (default 100 levels) 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 '...'
```

--------------------------------

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

Source: https://github.com/threepointone/aywson/blob/main/README.md

Sets a value at a specified path in a JSON object. Supports optional comments and both string and array path formats.

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

### Description
Sets a value at a specified path in a JSON object. Supports optional comments and both string and array path formats.

### Parameters
- **json** (string | object) - The JSON data to modify.
- **path** (string | array) - The path where the value should be set. Can be a dot-notation string (e.g., "config.enabled") or an array (e.g., ["config", "enabled"]).
- **value** (any) - The value to set at the specified path.
- **comment** (string, optional) - An optional comment to associate with the set value.

### Example
```javascript
// 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);
```
```

--------------------------------

### Run Tests in Watch Mode

Source: https://github.com/threepointone/aywson/blob/main/CONTRIBUTING.md

Execute tests continuously and automatically re-run them when changes are detected.

```bash
npm test -- --watch
```

--------------------------------

### Merge JSONC with merge() and setComment()

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `merge()` to add multiple fields at once and `setComment()` to add comments to specific fields.

```typescript
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: Parse JSONC to JSON

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `parse` command to convert a JSONC file to a JSON file, stripping comments and handling trailing commas.

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

--------------------------------

### CLI: Set a value in JSONC

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `set` command to modify a value in a JSONC file. By default, it shows a diff and writes to the file.

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

--------------------------------

### CLI: Sort object keys alphabetically

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `sort` command to sort object keys alphabetically within a JSONC file.

```bash
# Sort object keys alphabetically
aywson sort config.json
```

--------------------------------

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

Source: https://github.com/threepointone/aywson/blob/main/README.md

Sorts object keys alphabetically while preserving comments. Can sort the root or a nested object.

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

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

### Method
`sort`

### Parameters
- **json** (string | object) - The input JSON string or object.
- **path** (string | string[] | undefined) - Optional. Specify a path to sort only a nested object. Defaults to `""` or `[]` for the root.
- **options** (object) - Optional. Configuration options for sorting.
  - **comparator?** (function) - Custom sort function. Defaults to alphabetical.
  - **deep?** (boolean) - Sort nested objects recursively. Defaults to `true`.

### Request Example
```json
// Sort root object
sort(`{
  // z comment
  "z": 1,
  // a comment
  "a": 2
}`);

// Sort only a nested object using string path
sort(json, "config.database");

// Sort only a nested object using array path
sort(json, ["config", "database"]);

// 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 });
```

### Response
```json
// Example for root sort
'{ "a": 2, "z": 1 }' // with comments preserved
```
```

--------------------------------

### CLI: Set a comment above a field

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `comment` command to add or update a comment positioned directly above a specified field.

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

--------------------------------

### Check Non-existent Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Demonstrates checking for a path that does not exist in the JSON object. This returns false.

```typescript
has('{ "foo": "bar" }', "baz"); // → false
```

--------------------------------

### Format JSON with Custom Options

Source: https://github.com/threepointone/aywson/blob/main/README.md

Customize JSON formatting using options like `tabSize`, `insertSpaces`, and `eol`. These control indentation, spacing, and line endings.

```typescript
// 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" });
```

--------------------------------

### move(json, fromPath, toPath)

Source: https://github.com/threepointone/aywson/blob/main/README.md

Moves a field from one location to another within the JSON object. Supports string or array paths for both source and destination.

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

### Description
Move a field to a different location.

### Method
`move`

### Parameters
- **json** (string | object) - The input JSON string or object.
- **fromPath** (string | string[]) - The path to the field to move. Can be a string like `"source.value"` or an array like `["source", "value"]`.
- **toPath** (string | string[]) - The destination path for the field. Can be a string like `"target.value"` or an array like `["target", "value"]`.

### Request Example
```json
// Using string paths
move(
  '{ "source": { "value": 123 }, "target": {} }',
  "source.value",
  "target.value"
);

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

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

### Response
```json
'{ "source": {}, "target": { "value": 123 } }'
```
```

--------------------------------

### Set Value with Comment

Source: https://github.com/threepointone/aywson/blob/main/README.md

Sets a value at a string path and includes a preceding comment. The comment is added above the field in the JSON output.

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

--------------------------------

### Set Value with String Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Sets a value at a specified string path in a JSON object. The original JSON is returned with the updated value.

```typescript
set('{ "foo": "bar" }', "foo", "baz");
// → '{ "foo": "baz" }'
```

--------------------------------

### Format Minified JSON

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `format` to apply consistent indentation to minified JSON. Comments are preserved, and whitespace is normalized.

```typescript
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"
// }'
```

--------------------------------

### Set Value with Array Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Sets a value at a specified array path in a JSON object. This provides an alternative syntax for setting values.

```typescript
set('{ "foo": "bar" }', ["foo"], "baz");
// → '{ "foo": "baz" }'
```

--------------------------------

### patch(json, changes)

Source: https://github.com/threepointone/aywson/blob/main/README.md

An alias for `merge`. Use `undefined` to explicitly delete fields.

```APIDOC
## patch(json, changes)

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

### Method
`patch`

### Parameters
- **json** (string | object) - The input JSON string or object.
- **changes** (object) - An object containing the fields to merge or delete (by setting values to `undefined`).

### Request Example
```json
patch('{ "a": 1, "b": 2 }', { a: undefined });
```

### Response
```json
'{ "b": 2 }'
```
```

--------------------------------

### Move Field in JSON (String Paths)

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `move` with string paths to relocate a field from a source to a target location within the JSON structure.

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

--------------------------------

### CLI: Merge JSONC without deleting fields

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `merge` command to combine JSONC objects without removing existing fields.

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

--------------------------------

### Bypass Path Traversal Protection

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `--allow-path-traversal` flag to bypass default path validation. This is 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
```

--------------------------------

### Rename Key in JSON (String Path)

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `rename` with a string path to change a key's name while keeping its value.

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

--------------------------------

### CLI: Sort without deep recursion

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `--no-deep` option with the `sort` command to sort only the top-level keys and not recurse into nested objects.

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

--------------------------------

### replace(json, changes)

Source: https://github.com/threepointone/aywson/blob/main/README.md

Replaces fields in a JSON object. Fields not present in the `changes` object are deleted.

```APIDOC
## replace(json, changes)

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

### Method
`replace`

### Parameters
- **json** (string | object) - The input JSON string or object.
- **changes** (object) - An object containing the fields to replace. Fields not in this object will be deleted from the original JSON.

### Request Example
```json
replace('{ "a": 1, "b": 2 }', { a: 10 });
```

### Response
```json
'{ "a": 10 }'
```
```

--------------------------------

### Move Field in JSON (Array Paths)

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `move` with array paths to relocate a field. This provides precise control over nested structures. Mixed path formats are also supported.

```typescript
// 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"]);
```

--------------------------------

### merge(json, changes)

Source: https://github.com/threepointone/aywson/blob/main/README.md

Updates or adds fields in a JSON object. Fields are preserved unless explicitly set to undefined.

```APIDOC
## merge(json, changes)

### Description
Updates/add fields, never delete (unless explicit `undefined`).

### Method
`merge`

### Parameters
- **json** (string | object) - The input JSON string or object.
- **changes** (object) - An object containing the fields to merge.

### Request Example
```json
merge('{ "a": 1, "b": 2 }', { a: 10 });
```

### Response
```json
'{ "a": 10, "b": 2 }'
```
```

--------------------------------

### Iterate and Transform JSON Objects Using aywson

Source: https://github.com/threepointone/aywson/blob/main/README.md

Parse a JSON string into an object to iterate and transform its properties. Use `set()`, `remove()`, or `merge()` to apply changes back to the JSON string, preserving formatting and comments.

```typescript
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 });
```

--------------------------------

### CLI: Sort a specific nested object

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `sort` command with a path to sort keys only within a specific nested object.

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

--------------------------------

### has(json, path)

Source: https://github.com/threepointone/aywson/blob/main/README.md

Checks if a value exists at the specified path within a JSON object. Supports both string and array path formats.

```APIDOC
## has(json, path)

### Description
Checks if a value exists at the specified path within a JSON object. Supports both string and array path formats.

### Parameters
- **json** (string | object) - The JSON data to query.
- **path** (string | array) - The path to check. Can be a dot-notation string (e.g., "foo") or an array (e.g., ["foo"]).

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

--------------------------------

### Check Path Existence with String Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Verifies if a path exists within a JSON object using a string path. Returns true if the path is found, false otherwise.

```typescript
has('{ "foo": "bar" }', "foo"); // → true (string path)
```

--------------------------------

### Check Path Existence with Array Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Verifies if a path exists within a JSON object using an array path. This is an alternative to string paths for checking existence.

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

--------------------------------

### rename(json, path, newKey)

Source: https://github.com/threepointone/aywson/blob/main/README.md

Renames a key in the JSON object while preserving its value. Supports string or array paths.

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

### Description
Rename a key while preserving its value.

### Method
`rename`

### Parameters
- **json** (string | object) - The input JSON string or object.
- **path** (string | string[]) - The path to the key to rename. Can be a string like `"oldName"` or `"config.oldKey"`, or an array like `["config", "oldKey"]`.
- **newKey** (string) - The new name for the key.

### Request Example
```json
// Using string path
rename('{ "oldName": 123 }', "oldName", "newName");

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

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

### Response
```json
'{ "newName": 123 }'
```
```

--------------------------------

### CLI: Modify JSONC with replace semantics

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `modify` command to replace a section of the JSONC file with new content.

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

--------------------------------

### Modify JSON with comment-json

Source: https://github.com/threepointone/aywson/blob/main/README.md

Demonstrates how to parse a JSON string, modify properties, and stringify it back using comment-json. This approach involves working with a JavaScript object and re-serializing the entire structure.

```javascript
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);
```

--------------------------------

### CLI: Set a trailing comment

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `--trailing` option with the `comment` command to set or update a comment positioned after the field on the same line.

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

--------------------------------

### setComment

Source: https://github.com/threepointone/aywson/blob/main/README.md

Adds or updates a comment directly above a specified field in the JSON structure. It can handle both string and array paths for identifying the field.

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

### Description
Add or update a comment above a field.

### Parameters
- **json**: The JSON object or string to modify.
- **path**: The path to the field (string or array of strings).
- **comment**: The comment string to add or update.

### Example
```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");
```
```

--------------------------------

### Replace JSON Fields

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `replace` to update or add fields, deleting any fields not present in the changes object. This is equivalent to `modify`.

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

--------------------------------

### CLI: Remove a field from JSONC

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `remove` command to delete a field from a JSONC file.

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

--------------------------------

### getComment

Source: https://github.com/threepointone/aywson/blob/main/README.md

Retrieves the comment associated with a field. It prioritizes comments above the field and falls back to trailing comments if no comment is found above.

```APIDOC
## getComment(json, path)

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

### Parameters
- **json**: The JSON object or string to inspect.
- **path**: The path to the field (string or array of strings).

### Example
```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)
```
```

--------------------------------

### Parse JSONC with aywson

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `parse` function to convert a JSONC string into a JavaScript value, handling comments and trailing commas. TypeScript generics can be used for type safety.

```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);
```

--------------------------------

### Sort JSON with Custom Comparator or Deep Option

Source: https://github.com/threepointone/aywson/blob/main/README.md

Customize `sort` behavior with a `comparator` function for custom order or set `deep: false` to avoid recursive sorting. Defaults are alphabetical and deep sorting.

```typescript
// 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 });
```

--------------------------------

### Set Nested Value with Array Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Sets a value in a nested structure using an array path. This is an alternative to string paths for nested modifications.

```typescript
set('{ "config": {} }', ["config", "enabled"], true);
```

--------------------------------

### Rename Key in JSON (Array Path)

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `rename` with an array path to change a key's name while keeping its value. This is useful for nested structures.

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

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

--------------------------------

### Set Nested Value with String Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Sets a value in a nested structure using a string path. This operation supports deep paths within the JSON.

```typescript
set('{ "config": {} }', "config.enabled", true);
```

--------------------------------

### setTrailingComment

Source: https://github.com/threepointone/aywson/blob/main/README.md

Adds or updates a trailing comment immediately following a specified field. It supports both string and array paths for field identification.

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

### Description
Add or update a trailing comment after a field.

### Parameters
- **json**: The JSON object or string to modify.
- **path**: The path to the field (string or array of strings).
- **comment**: The comment string to add or update.

### Example
```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"
```
```

--------------------------------

### Merge JSON with Changes

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `merge` to update or add fields in a JSON object. Fields not present in the changes object are preserved. Deletion is not supported unless `undefined` is explicitly used.

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

--------------------------------

### Sort JSON Object Keys Alphabetically

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `sort` to sort object keys alphabetically while preserving comments. By default, it sorts the root object recursively.

```typescript
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 }'
```

--------------------------------

### Modify JSON with aywson

Source: https://github.com/threepointone/aywson/blob/main/README.md

Shows how to perform surgical edits on a JSON string using aywson's immutable functions. This method preserves original formatting and returns a new string with the applied changes.

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

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

--------------------------------

### Sort Nested JSON Object by Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Specify a path to `sort` to only sort a nested object. An empty string or array sorts the root.

```typescript
// 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, [])
```

--------------------------------

### Add or Update Comment Above Field

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `setComment` to add or update a comment positioned directly above a JSON field. Supports both string and array paths.

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

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

--------------------------------

### Preserve Comments When Deleting Fields in JSON

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `**` to prefix comments that should be preserved when a field is deleted from a JSON string. Otherwise, comments are deleted by default.

```typescript
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
```

--------------------------------

### remove(json, path)

Source: https://github.com/threepointone/aywson/blob/main/README.md

Removes a field from a JSON object at the specified path. Associated comments are also removed. Supports string and array path formats.

```APIDOC
## remove(json, path)

### Description
Removes a field from a JSON object at the specified path. Associated comments are also removed. Supports string and array path formats.

### Parameters
- **json** (string | object) - The JSON data to modify.
- **path** (string | array) - The path to the field to remove. Can be a dot-notation string (e.g., "config.database.host") or an array (e.g., ["config", "database", "host"]).

### Example
```javascript
// 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"]);
```
```

--------------------------------

### Patch JSON by Deleting Fields

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `patch` as an alias for `merge`. To delete a field, set its value to `undefined` in the changes object.

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

--------------------------------

### CLI: Remove a comment above a field

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `uncomment` command to remove a comment that is positioned directly above a specified field.

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

--------------------------------

### getTrailingComment

Source: https://github.com/threepointone/aywson/blob/main/README.md

Retrieves the trailing comment specifically located after a field on the same line. This function ignores comments positioned above the field.

```APIDOC
## getTrailingComment(json, path)

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

### Parameters
- **json**: The JSON object or string to inspect.
- **path**: The path to the field (string or array of strings).

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

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

--------------------------------

### Add or Update Trailing Comment After Field

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `setTrailingComment` to add or modify a comment that appears after a JSON field on the same line. Works with string and array paths.

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

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

--------------------------------

### CLI: Remove a trailing comment

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use the `--trailing` option with the `uncomment` command to remove a comment positioned after the field on the same line.

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

--------------------------------

### removeComment

Source: https://github.com/threepointone/aywson/blob/main/README.md

Removes the comment located directly above a specified field in the JSON structure. Supports both string and array paths.

```APIDOC
## removeComment(json, path)

### Description
Remove the comment above a field.

### Parameters
- **json**: The JSON object or string to modify.
- **path**: The path to the field (string or array of strings).

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

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

--------------------------------

### removeTrailingComment

Source: https://github.com/threepointone/aywson/blob/main/README.md

Removes the trailing comment associated with a specified field. This operation works with both string and array paths.

```APIDOC
## removeTrailingComment(json, path)

### Description
Remove the trailing comment after a field.

### Parameters
- **json**: The JSON object or string to modify.
- **path**: The path to the field (string or array of strings).

### Example
```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"]);
```
```

--------------------------------

### Remove Comment Above Field

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `removeComment` to delete the comment located above a specified JSON field. Accepts string or array paths.

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

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

--------------------------------

### Remove Nested Field with Array Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Removes a nested field from a JSON object using an array path. This provides an alternative syntax for removing nested fields.

```typescript
remove(json, ["config", "database", "host"]);
```

--------------------------------

### Remove Trailing Comment After Field

Source: https://github.com/threepointone/aywson/blob/main/README.md

Use `removeTrailingComment` to delete the comment that follows a JSON field on the same line. Supports both string and array paths.

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

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

--------------------------------

### Remove Nested Field with String Path

Source: https://github.com/threepointone/aywson/blob/main/README.md

Removes a nested field from a JSON object using a string path. This operation works for any level of nesting.

```typescript
remove(json, "config.database.host");
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.