Generate consistent, hashable JSON output for use in command-line interfaces, Node.js modules, and web browsers. Sorts arrays based on configurable priority, optionally sorts object keys, and supports in-place file modification. Ideal for hashing, deterministic comparisons, and version control of JSON data.
Published as an ES module and compatible with both Node.js and browser environments.
- Sorts arrays by predefined keys.
- Optionally sorts object keys (
--sort-objectorsortObjectoption). - Works as a command-line tool, a module, and in the browser.
- Supports in-place modification of JSON files (
--in-placeoption). - Great for storing JSON in Git (deterministic output).
- Uses modern ES modules for easy integration into contemporary JavaScript projects.
Try it in the browser (Live Demo)
The entire project now uses ES modules. This affects both how the library is imported/required and how the CLI is executed.
Impact: Users in older environments without ES module support will need to update their Node.js versions or use a build process that handles ES modules.
The default priority is now handled internally in hashable.js.
Impact: Users who relied on customizing the default priority by modifying config/priority.json will need to use getDefaultPriority() to retrieve the default and create a modified copy.
The CLI now returns a single JSON object (not wrapped in an array) for single file input without --in-place. This makes the output consistent with stdin handling.
Impact: User scripts or tools that relied on the previous array output (even for single files) will need to be updated to handle a single JSON object.
# Install globally (for use as a CLI command anywhere):
npm install -g hashable-cli
# Install locally (for use within a specific project):
npm install --save hashable-clicat file.json | npx hashable-cli > sorted.jsonnpx hashable-cli file.json > sorted.json
npx hashable-cli --in-place file.json # In-place modification
npx hashable-cli --priority=id,label file.json # Custom priority for sorting arrays
npx hashable-cli --sort-object file.json # Sort object keysnpm install --save hashable-cliimport hashable from 'hashable-cli'
import md5 from "md5"
const sorted1 = hashable({ a: 'b', c: ['e', 'd']}, { sortObject: true })
const sorted2 = hashable({ c: ['d', 'e'], a: 'b'}, { sortObject: true })
const hash1 = md5(JSON.stringify(sorted1))
const hash2 = md5(JSON.stringify(sorted2))
return hash1 === hash2const appendPriority = getDefaultPriority().concat(['field1', 'field2']) // append to default priority
const sorted3 = hashable(input, {priority: appendPriority })
const overridePriority = ['field1', 'field2'] // override default priority
const sorted4 = hashable(input, {priority: overridePriority})| CLI Flag | Module Option | Default | Description |
|---|---|---|---|
--in-place |
N/A | false |
Overwrite the original JSON file (CLI only) |
--sort-object |
sortObject |
false |
Sort object keys alphabetically. |
--priority |
priority |
id, _id, name, key, category, value, label, page, language, store_id, category_id |
Specify the priority for sorting arrays. Provide an array of strings (field names) in module usage. In CLI mode, provide a comma-separated string of field names. e.g. --priority=id,label |
see LICENSE
Consider these alternatives if hashable-cli doesn't fully meet your needs. Please check the latest status of these projects:
- safe-stable-stringify - Safe, deterministic and fast serialization alternative to
JSON.stringify. Zero dependencies. ESM and CJS. Gracefully handles circular structures and bigint instead of throwing.
- json-stable-stringify - deterministic version of
JSON.stringify()so you can get a consistent hash from stringified results. You can also pass in a custom comparison function.
- sort-keys - Sort the keys of an object, does not rearrange objects in a list. Supports custom comparison function.