@boristype/types/lib/xmlmultielemobject/index.d.ts

<h1 align="center">WT Types</h1> <div align="center"> Typescript типы для WebSoft HCM.

type XmlMultiElemObject<T, F = never> = {
  /**
   * Возвращает документ, к которому относится данный объект.
   */
  Doc: XmlDocument;

  /**
   * Возвращает массив, указанный в атрибуте `FOREIGN-ARRAY` текущего элемента.
   */
  ForeignArray: F[];

  /**
   * Возвращает `true` если существует хоть один соответствующий множественный элемент.
   */
  HasValue: boolean;

  /**
   * Возвращает массив всех соответствующих множественных элементов.
   * Сам по себе данный метод не несет особого смысла, поскольку объект
   * {@link XmlMultiElem} сам является массивом, но, в сочетании с одноименным
   * методом объекта {@link XmlElem} позволяет создавать универсальный код для
   * работы как с обычными так и множественными элементами.
   * @example
   * ```
   * // Возвращает массив из всех элементов profession_id
   * const array = candidate.profession_id.Instances;
   * Возвращает массив из единственного элемента location_id
   * const array = candidate.location_id.Instances;
   * ```
   */
  Instances: F[];

  /**
   * Всегда возвращает `false`.
   * Аналогичный метод объекта {@link XmlElem} всегда возвращает `false`.
   * Это позволяет по конструкции вида `candidate.profession_id.IsMultiElem` определять
   * был ли элемент `profession_id` описан c атрибутом `MULTIPLE=1`.
   */
  IsMultiElem: true;

  /**
   * Возвращает имя соответствующего множественного элемента.
   */
  Name: string;

  /**
   * Возвращает родительский элемент текущего элемента.
   */
  Parent: XmlDocument;

  /**
   * Возвращает константу на языке {@link XQuery} в виде последовательности
   * из значений соответствующих множественных элементов.
   */
  XQueryLiteral: string;

  /**
   * Добавляет дочерний элемент и возвращает указатель на него.
   * Если текущий элемент создан по форме, то он должен быть простым массивом.
   * При этом аргументы для вызова функции не требуются.
   * Если текущий элемент является динамическим (то есть построенным без формы),
   * то добавляется дочерний динамический элемент с именем и типом, указанных в качестве аргументов.
   * @param {string} name - Имя дочернего элемента.
   * @param {string} type - Тип дочернего элемента.
   * @returns {XmlElem<T>}
   */
  Add(name?: string, type?: string): XmlElem<T>;

  /**
   * Проверяет существует ли соответствующий множественный элемент с заданным значением.
   * @param {K} value - Заданное значение.
   */
  ByValueExists<K>(value: K): boolean;

  /**
   * Удаляет все соответствующие множественные элементы.
   */
  Clear(): void;

  /**
   * @deprecated
   * Удаляет все соответствующие множественные элементы.
   */
  DeleteAll(): void;

  /**
   * Удаляет соответствующий множественный элемент с заданным значением.
   * Если таких элементов несколько, удаляет первый.
   * @throws {@link Error} В случае отсутствия таких элементов возвращает ошибку.
   */
  DeleteByValue<T>(value: T): void | never;

  /**
   * Находит соответствующий множественный элемент с заданным значением ключевого поля.
   * Если такой элемент не найден, возвращает ошибку.
   * @param {string} value - Значение ключа.
   * @param {string} name - Имя элемента, являющегося ключом. Если имя ключа не указано, используется первичный ключ.
   * @returns {XmlElem<T>} Объект {@link XmlElem}.
   */
  GetByKey<K>(value: K, name?: string): XmlElem<T>;

  /**
   * Ищет соответствующий множественный элемент с заданным ключевым элементом.
   * Если не находит, то добавляет новый дочерний элемент, и его ключевому полю присваивает заданное значение.
   * Возвращает ранее существовавший или вновь созданный дочерний элемент.
   * @param {K} value - Значение ключа.
   * @param {string} name - Имя элемента, являющегося ключом. Если имя ключа не указано, используется первичный ключ.
   * @returns {XmlElem<T>} Объект {@link XmlElem}.
   */
  ObtainByKey<K>(value: K, name?: string): XmlElem<T>;

  /**
   * Находит элемент, относящийся к данному объекту по ключу.
   * В случае его отсутствия, добавляет элемент в соответствующую позицию по возрастанию ключа.
   * @param {K} value - Значение ключа.
   * @param {string} name - Имя элемента, являющегося ключом. Если имя ключа не указано, используется первичный ключ.
   * @returns {XmlElem<T>} Объект {@link XmlElem}.
   */
  ObtainByKeySorted<K>(value: K, name: string): XmlElem<T>;

  /**
   * Ищет соответствующий множественный элемент с заданным значением.
   * Если не находит, добавляет новый элемент и присваивает ему заданное значение.
   * @param {K} value - Значение элемента.
   */
  ObtainByValue<K>(value: K): XmlElem<T>;
};