Add ignore option (#21)

Co-authored-by: Sindre Sorhus <[email protected]>

Author: btea

index.d.ts

@@ -1,3 +1,15 @@
+
+export type IgnoreContext = {
+	/** Key of the current object or array item. */
+	key: string | number | undefined;
+	/** Value of the current object or array item. */
+	value: unknown;
+	/** Path to the current object or array item. */
+	path: Array<string | number>;
+	/** Current depth in the object or array. */
+	depth: number;
+};
+
 export type Options = {
 	/**
 	Recursively sort keys, including keys of objects inside arrays.
@@ -10,6 +22,11 @@ export type Options = {
 	[Compare function.](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort)
 	*/
 	readonly compare?: (left: string, right: string) => number;
+
+	/**
+	Decide whether to skip sorting of certain options based on the result returned by ignore function. This only applies when `deep` is set to `true`.
+	*/
+	readonly ignore?: (context: IgnoreContext) => boolean;
 };
 
 /**

index.js

@@ -5,10 +5,10 @@ export default function sortKeys(object, options = {}) {
 		throw new TypeError('Expected a plain object or array');
 	}
 
-	const {deep, compare} = options;
+	const {deep, compare, ignore} = options;
 	const cache = new WeakMap();
 
-	const deepSortArray = array => {
+	const deepSortArray = (array, path = []) => {
 		const resultFromCache = cache.get(array);
 		if (resultFromCache !== undefined) {
 			return resultFromCache;
@@ -17,44 +17,94 @@ export default function sortKeys(object, options = {}) {
 		const result = [];
 		cache.set(array, result);
 
-		result.push(...array.map(item => {
-			if (Array.isArray(item)) {
-				return deepSortArray(item);
+		result.push(...array.map((item, index) => {
+			path.push(index);
+			try {
+				if (deep && ignore && ignore(
+					{
+						key: index,
+						value: item,
+						path: [...path],
+						depth: path.length,
+					})) {
+					return item;
+				}
+
+				if (Array.isArray(item)) {
+					return deepSortArray(item, path);
+				}
+
+				if (isPlainObject(item)) {
+					return _sortKeys(item, path);
+				}
+
+				return item;
+			} finally {
+				path.pop();
 			}
-
-			if (isPlainObject(item)) {
-				return _sortKeys(item);
-			}
-
-			return item;
 		}));
 
 		return result;
 	};
 
-	const _sortKeys = object => {
+	const _sortKeys = (object, path = []) => {
 		const resultFromCache = cache.get(object);
 		if (resultFromCache !== undefined) {
 			return resultFromCache;
 		}
 
 		const result = {};
-		const keys = Object.keys(object).sort(compare);
+		const originalKeys = Object.keys(object);
+		const keys = deep && ignore && ignore({
+			key: undefined,
+			value: object,
+			path: [...path],
+			depth: path.length + 1,
+		}) ? originalKeys : originalKeys.sort(compare);
 
 		cache.set(object, result);
 
 		for (const key of keys) {
 			const value = object[key];
 			let newValue;
+			path.push(key);
+
+			if (deep && ignore && ignore(
+				{
+					key,
+					value,
+					path: [...path],
+					depth: path.length,
+				})) {
+				const descriptor = Object.getOwnPropertyDescriptor(object, key);
+				if (descriptor && ('get' in descriptor || 'set' in descriptor)) {
+					Object.defineProperty(result, key, descriptor);
+				} else {
+					Object.defineProperty(result, key, {
+						...descriptor,
+						value,
+					});
+				}
+
+				path.pop();
+				continue;
+			}
 
 			if (deep && Array.isArray(value)) {
-				newValue = deepSortArray(value);
+				newValue = deepSortArray(value, path);
 			} else {
-				newValue = deep && isPlainObject(value) ? _sortKeys(value) : value;
+				newValue = deep && isPlainObject(value) ? _sortKeys(value, path) : value;
+			}
+
+			path.pop();
+			const descriptor = Object.getOwnPropertyDescriptor(object, key);
+			if (descriptor && ('get' in descriptor || 'set' in descriptor)) {
+				Object.defineProperty(result, key, descriptor);
+				continue;
 			}
 
 			Object.defineProperty(result, key, {
-				...Object.getOwnPropertyDescriptor(object, key),
+				...descriptor,
 				value: newValue,
 			});
 		}

readme.md

@@ -59,3 +59,54 @@ Recursively sort keys, including keys of objects inside arrays.
 Type: `Function`
 
 [Compare function.](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort)
+
+##### ignore(context)
+
+Type: `Function`
+
+Decide whether to skip sorting of certain keys or branches based on the result returned by ignore function. This only applies when `deep` is set to `true`.
+
+###### context
+
+Type: `object`
+
+_key_
+
+Type: `string | number | undefined`
+
+Key of the current object or array item.  When `undefined`, the callback decides whether to sort the current object’s own keys (object-level decision).
+
+Examples:
+```ts
+// Preserve top-level object key order, but still deep-sort children
+sortKeys(input, {
+  deep: true,
+  ignore: ({key, path}) => key === undefined && path.length === 0
+});
+
+// Skip sorting at depth 3 only (object-level)
+sortKeys(input, {
+  deep: true,
+  ignore: ({key, depth}) => key === undefined && depth === 3
+});
+```
+
+_value_
+
+Type: `unknown`
+
+Value of the current object or array item.
+
+_path_
+
+Type: `Array<string | number>`
+
+Path to the current object or array item.
+
+_depth_
+
+Type: `number`
+
+Current depth in the object or array. For per-key callbacks, `depth === path.length` (after pushing the key/index). For object-level decisions (when `key` is `undefined`), `depth === path.length + 1`.
+
+**Note:** If the object-level callback returns `true`, the current object's own key order is preserved, but children are still deep-sorted unless those are also ignored.