getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne

Возвращает элемент массива, удовлетворяющий указанному предикату (функции, возвращающей булевское значение) тогда и только тогда, когда такой элемент ровно 1. Если же такого элемента нет, либо их 2 и больше то:

• Будет брошена ошибка, если указано значение { mustThrowErrorIfElementNotFoundOrMoreThan1: true } 3-им параметром. TypeScript при этом будет верить, что функция отработала успешно, то возвращаемое значение имеет непустое значение (не null), а того типа, который указан (в данном случае обычно неявно) через параметр обобщения.
• Если 3-ий параметр не указан, то будет возвращён null. При этом TypeScript будет требовать проверки на null,　прежде чем можно будет полноценно пользоваться возвращённым значением.

Пример

const sample: Array<string> = [ "Saint Paul", "Santa Barbara", "St. Louis", "Santa Monica" ];

const targetCityName: string | null = getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne(
  sample, (arrayElement: string): boolean => arrayElement.startsWith("St.")
);

console.log(targetCityName.length);

console.log(
  getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne(
    sample, (arrayElement: string): boolean => arrayElement.startsWith("Santa")
  )
);

const matching: string = getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne(
  sample,
  (arrayElement: string): boolean => arrayElement.startsWith("Santa"),
  { mustThrowErrorIfElementNotFoundOrMoreThan1: true }
);

Сравнение с нативными методами

Приведённые ниже нативные методы не лучше и не хуже функции getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne; что именно использовать — зависит от того, какое поведение требуется с случаях, когда:

• Нет ни одного элемента массива, удовлетворяющего предикату.
• Имеется 2 и более элементов массива, удовлетворяющих предикату.

Array.prototype.find

• Общего с getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne у этого метода то, что оба ищут первый элемент, удовлетворяющий предикату.
• Если удовлетворяющих предикату элементов нет, Array.prototype.find вернёт undefined, в во время как getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne либо возвращает null, либо бросает ошибку — в зависимости от наличия или отсутствия 3-его параметра. Если выбран вариант с бросанием ошибки, то TypeScript не будет требовать проверки на null — именно эта особенность может побудить использовать getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne, так как в случае с Array.prototype.find потребуется проверка на undefined.
• Если удовлетворяющих предикату элементов 2 или больше, то Array.prototype.find возвращает первый, а остальные — игнорирует. getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne　же, найдя удовлетворяющий предикату элемент, дополнительно проверит, не удовлетворяют ли предикату ещё какие-либо элементы, и если да, то никакой элемент не вернёт. Эта особенность полезна в тех случаях, когда надо не просто получить элемент массива по предикату, но и убедиться, что он в чём-то отличен от других, например имеет уникальный идентификатор.

Array.prototype.filter

Данный метод предназначен не для доступа к конкретному элементу массива, а для получения выборки из исходного массива. Таким образом, этот метод массива возвращает тоже массив — элементов, удовлетворяющих предикату, а не конкретный элемент.

Если же элементов, удовлетворяющих предикату нет, то будет возвращён пустой массив. При обращении к любому элементу этого массива (в томи числе к первому, то есть с индексом 0) будет возвращено значение undefined, чего TypeScript (да и вообще-то многие другие статически типизированные языки программирования) об этом не предупредит. Например, Array<string> или string[] фактически означает «массив бесконечного количества строчных элементов», когда в реальности любой массив конечен, а иногда может быть пустым.

Быстрый ввод в интегрированных средах разработки семейства IntelliJ IDEA

Использование Live template-ов в семействе интегрированных сред разработки IntelliJ IDEA позволяет вводить код такой так выражения вызова функции быстрее. Для получения доступа к Live Template-ам библиотеки YDEE потребуется установить официальный плагин этой библиотеки.

Пошаговое описание процесса использования шаблона

Если Вы ранее не пользовались Live template-ами, то пусть Вас не пугает приведённая ниже объёмная инструкция: при сформированной привычке использования Live template-ов (эта привычка сходна с повседневным применением сочетаний клавиш) скорость выполнения описанных ниже операций займёт считанные секунды.

1. Скопируйте в буфер обмен имя переменной, содержащей массив, либо само выражение массива. Чтобы среда разработки смогла автоматически заполнить позицию 1-ого параметра нужным значением, сформируйте привычку делать это копирование перед тем, как начинать вводить Live template функции getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne.
2. Начните набирать имя функции — getArrayElementSatisfiesThePredicateIfSuchElementIsExactlyOne. Подсветится 2 варианта автодополнения:
   1. Круглая иконка с буквой — это просто автодополнение имени функции, стандартная функциональность среды разработки. Нажатие на Enter введёт полное имя функции, а также при необходимости объявления импорта этой функции. Неплохо, однако это не предел, до которого можно частично автоматизировать процесс.
   2. Иконка с клише — это как раз нужный шаблон. Нажмите Enter. Произойдёт вставка шаблона кода, при этом значение 1-ого параметра будет автоматически выделено и заполнено содержимым буфера обмена. Поскольку при следовании данному руководству менять подставленное значение targetArray на другое не требуется, выйдете из режима редактирования 1-ого параметра, нажав Enter ещё раз.
3. Введите имя параметра предиката — стрелочной функции. Данным параметром является элемент массива, однако рекомендуется дать ему более конкретное имя, чем «element». Когда закончите вводить, нажмите Tab. Если этому будет препятствовать на этот раз ненужное Вам автодополнение, то сначала нажмите Esc.
4. Введите тип параметра предиката, затем нажмите Enter.
5. Удалите лишний код.

Внешние ссылки

• Исходный код
• Код тестов