Project Extend Plugin

Плагин для расширения конфигурации проекта другими файлами.

Установка

npm

npm install @runium/plugin-project-extend

yarn

yarn add @runium/plugin-project-extend

pnpm

pnpm add @runium/plugin-project-extend

Возможности

Плагин позволяет минимизировать дублирование элементов конфигурации проектов, используя файлы-шаблоны.

Повторяющиеся элементы могут быть вынесены в отдельные файлы и подключены к основной конфигурации проекта.

TIP

Файл-шаблон - это JSON-файл, содержащий полное или частичное описание конфигурации проекта.

Принцип работы

Плагин объединяет содержимое файла-шаблона с текущим файлом конфигурации проекта.

Содержимое файла-шаблона является основой конфигурации.

Содержимое текущего файла конфигурации объединяется с содержимым файла-шаблона по принципу "deep merge":

• элементы с одинаковыми наименованиями свойств будут объединены
• элементы текущей конфигурации имеют приоритет перед элементами файла-шаблона (т.е. переопределяют соответствующие элементы файла-шаблона)
• элементы, отсутствующие в файле-шаблоне, будут добавлены

TIP

Конфигурация проекта предполагает наличие элементов, представляющих собой массивы других элементов (задачи, триггеры, обработчики и зависимости в задачах и т.п.).

В случае с массивами объединение возможно только для элементов с одинаковыми значениями свойства id (задачи, триггеры).

Если в элементе конфигурации отсутствует свойство id (обработчики, зависимости), в массив будет добавлен новый элемент.

Это может привести к дублированию элементов массива.

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

Свойства конфигурации

Плагин добавляет новое свойство к основной конфигурации проекта:

• $extends - путь к файлу-шаблону

TIP

Подробнее о свойствах конфигурации см. в разделе Свойства конфигурации.

Пример

Представим, что у нас есть две конфигурации проектов.

some-project1.json:

{
  "id": "some-project1",
  "tasks": [
    {
      "id": "some-task1",
      "options": {
        "command": "some-command",
        "arguments": ["arg1", "arg2"]
      }
    },
    {
      "id": "some-task2",
      "options": {
        "command": "some-command2",
        "env": {
          "VAR1": "value1",
          "VAR2": "value2",
          "VAR3": "value3"
        }
      }
    }
  ]
}

some-project2.json:

{
  "id": "some-project2",
  "tasks": [
    {
      "id": "some-task1",
      "options": {
        "command": "some-command",
        "arguments": ["arg1", "arg2", "arg3"]
      }
    },
    {
      "id": "some-task2",
      "options": {
        "command": "some-command2",
        "env": {
          "VAR1": "value1",
          "VAR2": "value2",
          "VAR3": "value3_1",
          "VAR4": "value4"
        }
      }
    },
    {
      "id": "some-task3",
      "options": {
        "command": "some-command3"
      }
    }
  ]
}

Конфигурации имеют дублирующиеся элементы. Отличия some-project2.json от some-project1.json:

• some-task1 - отличает значение arguments
• some-task2 - разные значения VAR3, добавлено значение VAR4 в env
• some-task3 - новая задача

В данном случае можно использовать конфигурацию some-project1.json в качестве файла-шаблона для some-project2.json, переопределив только отличающиеся элементы.

Конфигурация some-project2.json с использованием файла-шаблона some-project1.json:

{
  "id": "some-project2",
  "$extends": "./some-project1.json",
  "tasks": [
    {
      "id": "some-task1",
      "options": {
        "arguments": ["arg3"]
      }
    },
    {
      "id": "some-task2",
      "options": {
        "env": {
          "VAR3": "value3_1",
          "VAR4": "value4"
        }
      }
    },
    {
      "id": "some-task3",
      "options": {
        "command": "some-command3"
      }
    }
  ]
}

TIP

Важно: т.к массив arguments в some-task1 содержит примитивные значения без id, arg3 будет добавлен в конец массива.