# sort-jsonc

> Sort JSONC without mangling comments!

Latest version **1.0.2** (published 2024-10-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install sort-jsonc
pnpm add sort-jsonc
yarn add sort-jsonc
bun add sort-jsonc
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2024-10-01 |
| First published | 2023-03-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >= 6 |
| Dependencies | 1 |
| Unpacked size | 24.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Author | Daniel Grefberg |
| Maintainers | duniul |
| Keywords | sort, json, jsonc, json-comments, comments |

## Links

- npm: https://www.npmjs.com/package/sort-jsonc
- Repository: https://github.com/duniul/sort-jsonc
- Homepage: https://github.com/duniul/sort-jsonc/issues
- Issues: https://github.com/duniul/sort-jsonc/issues
- npm.io page: https://npm.io/package/sort-jsonc

## Dependencies (1)

- [comment-json](https://npm.io/package/comment-json.md) ^4.2.3

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 1.0.2 (latest) — 2024-10-01
- 1.0.1 — 2024-03-13
- 1.0.0 — 2023-03-28

## README

# sort-jsonc

[![npm](https://img.shields.io/npm/v/sort-jsonc.svg)](https://www.npmjs.com/package/sort-jsonc)

✅ Sort JSONC (JSON with comments) without mangling comments!

<sup><i>Works with regular JSON too, of course!</i></sup>

See [sort-jsonc-cli](../sort-jsonc-cli) for the CLI version.

## Usage

See the [API reference](#api-reference) for info on all options.

```ts
import { sortJsonc } from 'sort-jsonc';

// JSON with comments
const jsonc = `{
  "charlie": 0,
  /*
   * Big block comment explaining "nested"
   */
  "nested": {
    "caesar": 0, // Comment left of "nested.c"
    "adam": 0,
    "bertil": 0
  },
  "array": [
    { "amsterdam": 0, "baltimore": 0 },
    { "yankee": 0, "zulu": 0 }
  ],
  "bravo": 0,
  // Comment above "a"
  "alfa": 1
}`;

// Sort it alphabetically...
const sortedAlphabetically = sortJsonc(jsonc);

// ... or sort it by preferred key order...
const sortedPreferred = sortJsonc(jsonc, { sort: ['nested', 'array'] });

// ... or sort it however you want!
const sortedByKeyLength = sortJsonc(jsonc, { sort: (a, b) => a.length - b.length });
```

<details>
  <summary>See example results</summary>
  
##### `sortedAlphabetically`

```jsonc
{
  // Comment above "a"
  "alfa": 1,
  "array": [
    {
      "amsterdam": 0,
      "baltimore": 0
    },
    {
      "yankee": 0,
      "zulu": 0
    }
  ],
  "bravo": 0,
  "charlie": 0,
  /*
   * Big block comment explaining "nested"
   */
  "nested": {
    "adam": 0,
    "bertil": 0,
    "caesar": 0 // Comment left of "nested.c"
  }
}
```

##### `sortedPreferred`

```jsonc
{
  /*
   * Big block comment explaining "nested"
   */
  "nested": {
    "adam": 0,
    "bertil": 0,
    "caesar": 0 // Comment left of "nested.c"
  },
  "array": [
    {
      "amsterdam": 0,
      "baltimore": 0
    },
    {
      "yankee": 0,
      "zulu": 0
    }
  ],
  // Comment above "a"
  "alfa": 1,
  "bravo": 0,
  "charlie": 0
}
```

##### `sortedAlphabetically`

```jsonc
{
  // Comment above "a"
  "alfa": 1,
  "array": [
    {
      "amsterdam": 0,
      "baltimore": 0
    },
    {
      "zulu": 0,
      "yankee": 0
    }
  ],
  "bravo": 0,
  /*
   * Big block comment explaining "nested"
   */
  "nested": {
    "adam": 0,
    "caesar": 0, // Comment left of "nested.c"
    "bertil": 0
  },
  "charlie": 0
}
```

</details>

## Installation

| npm                      | yarn                  | pnpm                  |
| ------------------------ | --------------------- | --------------------- |
| `npm install sort-jsonc` | `yarn add sort-jsonc` | `pnpm add sort-jsonc` |

## API reference

### `sortJsonc(jsonc, options)`

```ts
  sortJsonc(jsonc: string, options?: SortJsoncOptions): string
```

Sorts a JSON/JSONC string without mangling comments (can also remove them if wanted).

Sorts alphabetically by default, but can also sort by preferred key order or by a custom sort function.

#### Parameters

| Name      | Type               | Description                                                        |
| --------- | ------------------ | ------------------------------------------------------------------ |
| `jsonc`   | `string`           | The JSONC string to sort.                                          |
| `options` | `SortJsoncOptions` | Options for sorting. See [below](#sortjsoncoptions) for more info. |

##### Options

| Name               | Type                      | Default     | Description                                                                                                  |
| ------------------ | ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
| `sort`             | `CompareFn` or `string[]` | `undefined` | Can be a compare function (like `Array.sort`) or a list of ordered keys. Sorts alphabetically if left blank. |
| `spaces`           | `number`                  | `2`         | Number of spaces to indent the JSON. Same as the third parameter of `JSON.stringify()`.                      |
| `removeComments`   | `boolean`                 | `false`     | Whether to remove comments or not.                                                                           |
| `parseReviver`     | `Reviver`                 | `undefined` | Reviver function, like the second parameter of `JSON.parse()`.                                               |
| `stringifyReviver` | `Reviver`                 | `undefined` | Reviver function, like the second parameter of `JSON.stringify()`.                                           |

---
_Source: https://npm.io/package/sort-jsonc · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._