1 line
5.5 KiB
Text
1 line
5.5 KiB
Text
|
{"version":3,"file":"firstBy.cjs","names":["purryOrderRules","hasAtLeast"],"sources":["../src/firstBy.ts"],"sourcesContent":["import { hasAtLeast } from \"./hasAtLeast\";\nimport { purryOrderRules, type OrderRule } from \"./internal/purryOrderRules\";\nimport type { CompareFunction } from \"./internal/types/CompareFunction\";\nimport type { IterableContainer } from \"./internal/types/IterableContainer\";\nimport type { NonEmptyArray } from \"./internal/types/NonEmptyArray\";\n\ntype FirstBy<T extends IterableContainer> =\n | T[number]\n | (T extends readonly [unknown, ...(readonly unknown[])]\n ? never\n : T extends readonly [...(readonly unknown[]), unknown]\n ? never\n : undefined);\n\n/**\n * Find the first element in the array that adheres to the order rules provided. This is a superset of what a typical `maxBy` or `minBy` function would do as it allows defining \"tie-breaker\" rules when values are equal, and allows comparing items using any logic. This function is equivalent to calling `R.first(R.sortBy(...))` but runs at *O(n)* instead of *O(nlogn)*.\n *\n * Use `nthBy` if you need an element other that the first, or `takeFirstBy` if you more than just the first element.\n *\n * @param rules - A variadic array of order rules defining the sorting criteria. Each order rule is a projection function that extracts a comparable value from the data. Sorting is based on these extracted values using the native `<` and `>` operators. Earlier rules take precedence over later ones. Use the syntax `[projection, \"desc\"]` for descending order.\n * @returns The first element by the order criteria, or `undefined` if the array\n * is empty. (The function provides strong typing if the input type assures the\n * array isn't empty).\n * @signature\n * R.firstBy(...rules)(data);\n * @example\n * const max = R.pipe([1,2,3], R.firstBy([R.identity(), \"desc\"])); // => 3;\n * const min = R.pipe([1,2,3], R.firstBy(R.identity())); // => 1;\n *\n * const data = [{ a: \"a\" }, { a: \"aa\" }, { a: \"aaa\" }] as const;\n * const maxBy = R.pipe(data, R.firstBy([(item) => item.a.length, \"desc\"])); // => { a: \"aaa\" };\n * const minBy = R.pipe(data, R.firstBy((item) => item.a.length)); // => { a: \"a\" };\n *\n * const data = [{type: \"cat\", size: 1}, {type: \"cat\", size: 2}, {type: \"dog\", size: 3}] as const;\n * const multi = R.pipe(data, R.firstBy(R.prop('type'), [R.prop('size'), 'desc'])); // => {type: \"cat\", size: 2}\n * @dataLast\n * @category Array\n */\nexport function firstBy<T extends IterableContainer>(\n ...rules: Readonly<NonEmptyArray<OrderRule<T[number]>>>\n): (data: T) => FirstBy<T>;\n\n/**\n * Find the first element in the array that adheres to the order rules provided. This is a superset of what a typical `maxBy` or `minBy` function would do as it allows defining \"tie-breaker\" rules when values are equal, and allows comparing items using any logic. This function is equivalent to calling `R.first(R.sortBy(...))` but runs at *O(n)* instead of *O(nlogn)*.\n *\n * Use `nthBy` if you need an element other that the first, or `takeFirstBy` if you more than just the first element.\n *\n * @param data - An array of items.\n * @param rules - A variadic array of order rules defining the sorting criteria. Each order rule is a projection function that extracts a comparable value from the data. Sorting is based on these extracted values using the native `<` and `>` operators. Earlier rules take precedence over later ones. Use the syntax `[projection, \"desc\"]` for descending order.\n * @returns The first element by the order criteria, or `undefined` if the array\n * is empty. (The function provides strong typing if the input type assures the\n * array isn't empty).\n * @signature\n * R.firstBy(data, ...rules);\n * @example\n * const max = R.firstBy([1,2,3], [R.identity(), \"desc\"]); // => 3;\n * const min = R.firstBy([1,2,3], R.identity()); // => 1;\n *\n * const data = [{ a: \"a\" }, { a: \"aa\" }, { a: \"aaa\" }] as const;\n * const maxBy = R.firstBy(data, [(item) => item.a.
|