sort-package-json-rs

Node.js bindings and CLI for OXC(oxfmt)'s package.json sorter.

Introduction

oxc-project/sort-package-json is a high-performance Rust implementation for sorting package.json files, designed as a replacement for keithamus/sort-package-json. It powers the “Sort package.json fields” feature in oxfmt.

This package provides Node.js bindings for that implementation, along with a CLI that is similar to the original sort-package-json.

It can be used independently of oxfmt as a drop-in replacement for the original sort-package-json package, or integrated directly into your own tools and workflows in Node.js compatible environments.

Note on Compatibility: oxc-project/sort-package-json is not strictly compatible with the original sort-package-json npm package. It uses a different sorting algorithm and field order, so the output may differ from the original package.

Installation

# npm
npm install sort-package-json-rs

# yarn
yarn add sort-package-json-rs

# pnpm
pnpm add sort-package-json-rs

# bun
bun install sort-package-json-rs

# deno
deno install npm:sort-package-json-rs

CLI

Run it via npx, pnpm dlx, bunx, or deno run:

# npm
npx sort-package-json-rs@latest

# pnpm
pnpm dlx sort-package-json-rs@latest

# bun
bunx sort-package-json-rs@latest

# deno
deno run -A npm:sort-package-json-rs@latest

Usage Options

$ sort-package-json-rs --help
sort-package-json-rs/0.0.2

Usage:
  $ sort-package-json-rs [...files]

Commands:
  [...files]  Sort package.json files

For more info, run any command with the `--help` flag:
  $ sort-package-json-rs --help

Options:
  -c, --check          Check if files are sorted without modifying them 
  -q, --quiet          Don't output success messages 
  --stdin              Read package.json from stdin 
  -i, --ignore <glob>  Glob patterns to ignore (default: node_modules/**)
  -v, --version        Display version number 
  -h, --help           Display this message 

API

Basic Usage

import { sortPackageJson } from 'sort-package-json-rs';

const unsorted = {
  dependencies: {
    'react': '^18.0.0',
    'typescript': '^5.0.0',
    'lodash': '^4.17.0'
  },
  name: 'my-package',
  version: '1.0.0',
  scripts: {
    'build': 'tsc',
    'test': 'vitest'
  }
};

// Use default options (pretty-printed)
const sorted = sortPackageJson(JSON.stringify(unsorted));
console.log(sorted);

// Or with custom options
const compactSorted = sortPackageJson(JSON.stringify(unsorted), {
  pretty: false,
  sortScripts: true
});
console.log(compactSorted);

TypeScript Types

/** Options for controlling JSON formatting when sorting */
export interface SortOptions {
  /** Whether to pretty-print the output JSON */
  pretty: boolean
  /** Whether to sort the scripts field alphabetically */
  sortScripts: boolean
}

/**
 * Sorts a package.json string with optional custom options
 * If options is not provided, uses default options (pretty-printed)
 */
export declare function sortPackageJson(input: string, options?: SortOptions | undefined | null): string

Benchmarks

Using tests/index.bench.ts with vitest bench:

| Test Case | Original (hz) | RS Binding (hz) | Speedup | | --------------------------- | ------------- | --------------- | ------- | | Small package.json | 15,719.80 | 25,073.37 | 1.60x ⚡ | | Already sorted package.json | 17,005.20 | 26,249.62 | 1.54x ⚡ | | Minimal package.json | 139,344.74 | 907,643.81 | 6.51x ⚡ | | Large package.json | 42,820.94 | 72,237.26 | 1.69x ⚡ |

Executed on an MacBook Air (M1, 2020, 16GB RAM) with Node.js v23.7.0.

Credits

Some code and tests are adapted from keithamus/sort-package-json and oxc-project/sort-package-json.

License

MIT License © maxchang3

🤖 auto updated with automd