Sort the keys of an object
npm install sort-keys> Sort the keys of an object
Useful to get a deterministically ordered object, as the order of keys can vary between engines.
``sh`
npm install sort-keys
`js
import sortKeys from 'sort-keys';
sortKeys({c: 0, a: 0, b: 0});
//=> {a: 0, b: 0, c: 0}
sortKeys({b: {b: 0, a: 0}, a: 0}, {deep: true});
//=> {a: 0, b: {a: 0, b: 0}}
sortKeys({b: [{b: 0, a: 0}], a: 0}, {deep: true});
//=> {a: 0, b: [{a: 0, b: 0}]}
sortKeys({c: 0, a: 0, b: 0}, {
compare: (a, b) => -a.localeCompare(b)
});
//=> {c: 0, b: 0, a: 0}
sortKeys([{b: 0, a: 2}], {deep: true});
//=> [{a: 2, b: 0}]
`
The deep and ignoreKeys options can receive a context object with detailed information about the current key being processed:
`js
// Ignore private keys only at root level
sortKeys(data, {
ignoreKeys: ({key, depth}) => key.startsWith('_') && depth === 0
});
// Deep process only up to 3 levels, skip config paths
sortKeys(data, {
deep: ({path, depth}) => depth < 3 && !path.includes('config')
});
// Complex path-based logic
sortKeys(data, {
deep: ({path}) => !(path[0] === 'user' && path[1] === 'cache'),
ignoreKeys: ({path, key}) => (path.length === 1 && path[0] === 'metadata') || key.startsWith('_')
});
`
Returns a new object with sorted keys.
Property descriptors are preserved, including accessors (get/set), and getters are not invoked or deep-processed. Circular references are supported and preserved.
#### object
Type: object | Array
When it's an object:
- Only plain objects are deeply processed.
- Only enumerable own string keys are considered; symbol and non-enumerable properties are ignored.
When it's an array:
- Array order is unchanged; holes in sparse arrays are preserved.
- Elements may be deep-processed if deep enables it.
- Extra enumerable properties on arrays are ignored.
#### options
Type: object
##### compare
Type: Function
Compare function for sorting keys.
If omitted, remaining keys are sorted using the platform's default string sort.
`js`
sortKeys(object, {
compare: (a, b) => b.localeCompare(a) // Reverse alphabetical
});
##### deep
Type: boolean | Function\false
Default:
Recursively sort keys, including keys of objects inside arrays.
Only plain objects are sorted; other object types are left as-is. For arrays, deep processing applies to their elements.
When a boolean:
- true: Deep process all nested objects and arrays.false
- : Only sort keys at the current level.
When a function, it receives a context object and should return true to enable deep processing for that specific key-value pair:
`js
sortKeys(data, {
deep: ({key, value, path, depth}) => {
// Only deep process up to 2 levels
if (depth >= 2) {
return false;
}
// Skip deep processing of large arrays for performance
if (Array.isArray(value) && value.length > 100) {
return false;
}
// Skip config objects entirely
if (path.includes('config')) {
return false;
}
return true;
}
});
`
##### ignoreKeys
Type: string[] | Function\[]
Default:
Keys to ignore when sorting. Ignored keys will appear first in their original order, followed by the sorted keys. Remaining keys are sorted by compare, or by default string sort if compare is not provided.
Can be an array of key names:
`js`
sortKeys({c: 0, _private: 1, a: 0, b: 0}, {ignoreKeys: ['_private']});
//=> {_private: 1, a: 0, b: 0, c: 0}
Or a function that receives a context object:
`js
sortKeys(data, {
ignoreKeys: ({key, value, path, depth}) => {
// Ignore private keys at root level
if (key.startsWith('_') && depth === 0) {
return true;
}
// Ignore metadata keys in user objects
if (path[0] === 'user' && key === 'metadata') {
return true;
}
// Ignore empty objects
if (typeof value === 'object' && Object.keys(value).length === 0) {
return true;
}
return false;
}
});
`
Note: ignoreKeys only affects the ordering of object keys; it does not control deep processing, and array indices are not sorted or filtered. To prevent deep processing of specific values, use the deep function option.
#### Context object
When using functions for deep or ignoreKeys, they receive a context object with:
- key (string): The current key being processed.value
- (any): The value associated with the current key.path
- (string[]): The full path to this key as an array of elements (for example, ['user', 'profile', 'name']). Array indices are stringified (for example, ['items', '0', 'title']).depth
- (number): The current nesting depth (0 for root level).
#### Path examples
`js
const data = {
user: {
profile: {
name: 'John'
}
},
items: [
{title: 'Item 1'},
{title: 'Item 2'}
]
};
// Paths generated during processing (as arrays):
// ['user'] (depth: 0)
// ['user', 'profile'] (depth: 1)
// ['user', 'profile', 'name'] (depth: 2)
// ['items'] (depth: 0)
// ['items', '0'] (depth: 1)
// ['items', '0', 'title'] (depth: 2)
// ['items', '1'] (depth: 1)
// ['items', '1', 'title'] (depth: 2)
`
Note: path is an array of elements with stringified array indices (for example, ['items', '0', 'title']`). If your key names include dots or special characters, this representation remains unambiguous.