sort-keys

sortKeys: {
    <T extends Record<string, any>>(object: T, options?: Options): T;
    <T>(object: T[], options?: Options): T[];
};

type Options = {
    /**
	Compare function for sorting keys.

	@see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort

	If omitted, remaining keys are sorted using the platform's default string sort.
	*/
    readonly compare?: (left: string, right: string) => number;

    /**
	Recursively sort keys, including keys of objects inside arrays.

	@default false

	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.
	The context is `SortContext` with `{ key, value, path, depth }`.

	@example
	```
	// Fine-grained deep control with context
	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 as any[]).length > 100) {
				return false;
			}

			// Skip config objects entirely
			if (path.includes('config')) {
				return false;
			}

			return true;
		}
	});
	```
	*/
    readonly deep?: boolean | ((context: SortContext) => boolean);

    /**
	Keys to ignore during sorting. Ignored keys 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.

	@default []

	Only affects the ordering of object keys; it does not control deep processing, and array indices are not sorted or filtered.

	Can be an array of key names, or a function that receives context and returns true to ignore the key.

	@example
	```
	// Ignore by name; ignored keys keep original order and appear first
	sortKeys({c: 0, _private: 1, a: 0, b: 0}, {ignoreKeys: ['_private']});
	//=> {_private: 1, a: 0, b: 0, c: 0}

	// Ignore by function with multiple conditions
	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 as any).length === 0) {
				return true;
			}

			return false;
		}
	});
	```
	*/
    readonly ignoreKeys?: readonly string[] | ((context: SortContext) => boolean);
};

type SortContext = {
    /**
	The current key being processed.
	*/
    readonly key: string;

    /**
	The value associated with the current key
	*/
    readonly value: unknown;

    /**
	The full path to this key as an array of path elements (for example, `['user', 'profile', 'name']`).

	Array indices are stringified (for example, `['items', '0', 'title']`).

	Examples of generated paths (with depths):
	- ['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)
	*/
    readonly path: readonly string[];

    /**
	The current nesting depth (0 for root level).
	*/
    readonly depth: number;
};