import type {MatchingKey} from './matching-key.d.ts'; import type {DeduplicatedKeys, WithKeyAliases} from './internal/keys.d.ts'; import type {IfNotAnyOrNever} from './internal/type.d.ts'; import type {IsLiteral} from './is-literal.d.ts'; import type {IsUnion} from './is-union.d.ts'; /** Group an array of objects by a property, preserving the order within each group. Use-cases: - Group static route or command definitions by their kind. - Keep the contents and length of each group as a tuple. The input must be a fixed tuple of required elements. Arrays and rest tuples give `never`; optional tuple elements are not accepted. Tuples intersected with brands or extra properties are unsupported. The selected property must be a key of every element, so a misspelled or missing key is a compile error. It must hold one literal property key. Optional, union-valued, and non-literal group properties give `never`. Branded group values are unsupported. Groups are required and preserve the input's readonly modifier. The resulting record is mutable. Numeric and string forms of the selected property and group values are resolved with TypeScript's key rules, so `0` and `'0'` belong to the same group. Distributes over unions of arrays and keys. The selected property must be a key of the elements of every array in the union. Returns `any` for `any` and `never` for `never`. @example ``` import type {ArrayGroupBy} from 'type-fest'; type Routes = [ {method: 'GET'; path: '/users'}, {method: 'POST'; path: '/users'}, {method: 'GET'; path: '/health'}, ]; type GetRoutes = ArrayGroupBy['GET']; //=> [{method: 'GET'; path: '/users'}, {method: 'GET'; path: '/health'}] ``` The group keys are mapped once, and each group collects its items in input order. `MatchingKey` resolves group membership, so numeric and string forms of the same key share one tuple without building nested mapped accumulators. @category Array */ export type ArrayGroupBy> = IfNotAnyOrNever extends true ? GroupItems extends infer Groups ? {[Group in keyof Groups]: Items extends unknown[] ? Groups[Group] : Readonly} : never : never : never : never; }>; /** Checks that each item has one definite group key. */ type HasGroupKey = [Item] extends [Record] ? [IsLiteral, IsUnion] extends [true, false] ? true : false : false; /** Consumes required tuple positions, rejecting uncertain group keys and unknown-length inputs. */ type HasGroupKeys = Items extends readonly [infer First extends object, ...infer Rest extends object[]] ? MatchingKey extends infer ItemKey extends keyof First ? HasGroupKey extends true ? HasGroupKeys : false : false : Items extends readonly [] ? true : false; /** Maps group keys once, keeping each group's tuple independent of the other groups. Deduplicate numeric and string aliases first, because TypeScript can drop a remapped property when both spellings are present. */ type GroupItems = { [Group in DeduplicatedKeys>]: CollectGroup }; /** Reads the selected property on each item before combining the group values. */ type GroupKeyValues = Item extends unknown ? Item[MatchingKey] & PropertyKey : never; /** Appends matching items to one group, using the native key resolver for numeric and string aliases. */ type CollectGroup< Items extends readonly object[], Key extends PropertyKey, Group extends PropertyKey, Result extends object[] = [], > = Items extends readonly [infer Item extends object, ...infer Rest extends object[]] ? MatchingKey, Item[MatchingKey] & PropertyKey> extends never ? CollectGroup : CollectGroup : Result; export {};