deno task

Описание

deno task предоставляет кроссплатформенный способ определять и выполнять пользовательские команды, специфичные для кодовой базы.

Для начала определите команды в файле конфигурации Deno вашей кодовой базы под ключом "tasks".

Например:

{
  "tasks": {
    "data": "deno task collect && deno task analyze",
    "collect": "deno run --allow-read=. --allow-write=. scripts/collect.js",
    "analyze": {
      "description": "Run analysis script",
      "command": "deno run --allow-read=. scripts/analyze.js"
    }
  }
}

Запуск задачи, только если она существует

deno task <name> завершается с ненулевым кодом, если задача с указанным именем не определена. Чтобы сделать задачу необязательной, передайте --if-present. В этом случае Deno завершится с кодом 0 и ничего не выведет, если задача отсутствует. Это полезно для общих сценариев CI, которые вызывают задачу, определённую не во всех пакетах:

deno task --if-present build

Этот флаг подавляет только ошибку об отсутствии указанной задачи. Он не влияет на вывод списка задач при запуске deno task без аргументов, запуск существующей задачи и реальные ошибки, например отсутствие зависимости задачи.

Указание текущего рабочего каталога

По умолчанию deno task выполняет команды, используя каталог файла конфигурации Deno (например, deno.json) в качестве текущего рабочего каталога. Это позволяет задачам использовать относительные пути и работать независимо от того, из какой части дерева каталогов вы запускаете deno task. В некоторых случаях такое поведение может быть нежелательным; его можно переопределить с помощью переменной окружения INIT_CWD.

Если переменная INIT_CWD ещё не задана, ей будет присвоен полный путь к каталогу, из которого была запущена задача. Это соответствует поведению npm run.

Например, следующая задача изменит текущий рабочий каталог задачи на каталог, из которого пользователь запустил задачу, а затем выведет путь к этому текущему каталогу (помните, что это также работает в Windows, поскольку deno task является кроссплатформенным).

{
  "tasks": {
    "my_task": "cd $INIT_CWD && pwd"
  }
}

Получение каталога, из которого была запущена deno task

Поскольку задачи выполняются с использованием каталога файла конфигурации Deno в качестве текущего рабочего каталога, может быть полезно узнать каталог, из которого была запущена deno task. Это возможно с помощью переменной окружения INIT_CWD в задаче или скрипте, запущенном из deno task (работает так же, как в npm run, но кроссплатформенно).

Например, чтобы передать этот каталог скрипту в задаче, сделайте следующее (обратите внимание: каталог заключён в двойные кавычки, чтобы он считался одним аргументом, если в нём есть пробелы):

{
  "tasks": {
    "start": "deno run main.ts \"$INIT_CWD\""
  }
}

Сопоставление задач с подстановочными знаками

Команда deno task может запускать несколько задач параллельно, если передать ей шаблон с подстановочным знаком. Для задания такого шаблона используется символ *.

{
  "tasks": {
    "build:client": "deno run -RW client/build.ts",
    "build:server": "deno run -RW server/build.ts"
  }
}

Запуск deno task "build:*" выполнит задачи build:client и build:server.

Для составных имён задач рекомендуем использовать : в качестве разделителя (например, build:client, test:unit, lint:fix), следуя соглашению экосистемы npm и группируя связанные задачи для сопоставления с шаблонами.

Исключайте задачи из совпадений с шаблоном, добавляя в конец шаблона группу исключений (!a|b|c). Каждое указанное значение сопоставляется с тем, что захватил *. Например, если заданы задачи test:unit, test:integration, test:e2e и test:interactive:

deno task "test:*(!e2e|interactive)"

будут запущены test:unit и test:integration, а test:e2e и test:interactive будут пропущены. Шаблон с группой исключений, но без * отклоняется, поскольку исключать не из чего.

Загрузка переменных окружения из файла

Передайте --env-file, чтобы загрузить переменные из dotenv-файла в окружение оболочки задачи. Все команды в теле задачи унаследуют эти переменные:

# Load .env
deno task --env-file start

# Load a specific file
deno task --env-file=.env.production start

Флаг можно указать несколько раз, чтобы загрузить несколько файлов; значения из более поздних файлов имеют приоритет. Если значение не указано, по умолчанию используется .env.

Зависимости задач

Для задачи можно указать зависимости:

{
  "tasks": {
    "build": "deno run -RW build.ts",
    "generate": "deno run -RW generate.ts",
    "serve": {
      "command": "deno run -RN server.ts",
      "dependencies": ["build", "generate"]
    }
  }
}

В приведённом выше примере запуск deno task serve сначала выполнит задачи build и generate параллельно, а после успешного завершения обеих задач выполнит задачу serve:

deno task serve
Task build deno run -RW build.ts
Task generate deno run -RW generate.ts
Generating data...
Starting the build...
Build finished
Data generated
Task serve deno run -RN server.ts
Listening on http://localhost:8000/

Задачи-зависимости выполняются параллельно; по умолчанию максимальное число параллельно выполняемых задач равно числу ядер вашего компьютера. Чтобы изменить это ограничение для одного запуска, передайте --jobs (краткая форма — -j, также допускается написание --concurrency); чтобы задать его для окружения, используйте переменную окружения DENO_JOBS. Флаг имеет приоритет:

# Run workspace tasks fully sequentially
deno task --recursive --jobs 1 build

Зависимости отслеживаются: если от одной задачи зависят несколько других задач, эта задача будет запущена только один раз:

{
  //   a
  //  / \
  // b   c
  //  \ /
  //   d
  "tasks": {
    "a": {
      "command": "deno run a.js",
      "dependencies": ["b", "c"]
    },
    "b": {
      "command": "deno run b.js",
      "dependencies": ["d"]
    },
    "c": {
      "command": "deno run c.js",
      "dependencies": ["d"]
    },
    "d": "deno run d.js"
  }
}

deno task a
Task d deno run d.js
Running d
Task c deno run c.js
Running c
Task b deno run b.js
Running b
Task a deno run a.js
Running a

Если обнаружен цикл в зависимостях, будет возвращена ошибка:

{
  "tasks": {
    "a": {
      "command": "deno run a.js",
      "dependencies": ["b"]
    },
    "b": {
      "command": "deno run b.js",
      "dependencies": ["a"]
    }
  }
}

deno task a
Task cycle detected: a -> b -> a

Также можно указать задачу, у которой есть dependencies, но нет command. Это полезно для логической группировки нескольких задач:

{
  "tasks": {
    "dev:client": "deno run --watch client/mod.ts",
    "dev:server": "deno run --watch server/mod.ts",
    "dev": {
      "dependencies": ["dev:client", "dev:server"]
    }
  }
}

Запуск deno task dev запустит параллельно dev:client и dev:server.

Кэширование результатов задач

Задача может пропускать работу, если ни один из её входных данных не изменился. Добавьте поле files со списком шаблонов входных файлов, которые использует задача. Deno создаст отпечаток команды, добавленных к ней аргументов, содержимого соответствующих файлов и значений перечисленных переменных окружения, а при следующем запуске пропустит задачу, если ничего из этого не изменилось. Кэширование включается явно: задача без поля files выполняется всегда.

{
  "tasks": {
    "build": {
      "command": "deno run -RW build.ts",
      "files": ["src/**/*.ts", "deno.json"],
      "output": ["dist/"],
      "env": ["NODE_ENV"]
    }
  }
}

• files содержит шаблоны входных файлов, составляющие ключ кэша. Их объявление включает кэширование для задачи.
• output содержит шаблоны файлов, создаваемых задачей. При попадании в кэш они восстанавливаются из него, поэтому удаление dist/ и повторный запуск приведёт к повторному созданию этого файла.
• env содержит имена переменных окружения, значения которых входят в ключ кэша. Поэтому при изменении одной из них задача запускается повторно.

Отпечатки зависимостей задачи включаются в её собственный ключ кэша, поэтому задача запускается повторно всякий раз, когда запускалась какая-либо вышестоящая задача.

Поддержка исполняемых файлов Node и npx

По умолчанию deno task выполняет команды с помощью исполняемого файла deno. Если нужно гарантировать, что команда будет выполнена с помощью исполняемого файла npm или npx, вызовите соответственно команду npm или npx run. Например:

{
  "tasks": {
    "test:node": "npm run test"
  }
}

Поддержка рабочей области

deno task можно использовать в рабочих областях для параллельного запуска задач из нескольких каталогов участников. Чтобы выполнить задачи dev всех участников рабочей области, используйте флаг --recursive:

{
  "workspace": [
    "client",
    "server"
  ]
}

{
  "name": "@scope/client",
  "tasks": {
    "dev": "deno run -RN build.ts"
  }
}

{
  "name": "@scope/server",
  "tasks": {
    "dev": "deno run -RN server.ts"
  }
}

deno task --recursive dev
Task dev deno run -RN build.ts
Task dev deno run -RN server.ts
Bundling project...
Listening on http://localhost:8000/
Project bundled

Список запускаемых задач можно отфильтровать по участникам рабочей области:

deno task --filter "client" dev
Task dev deno run -RN build.ts
Bundling project...
Project bundled

Обратите внимание: фильтр сопоставляется с именами участников рабочей области, указанными в поле name файла deno.json каждого участника.

Синтаксис

deno task использует кроссплатформенную оболочку, представляющую собой подмножество sh/bash, для выполнения определённых задач.

Булевы списки

Булевы списки позволяют выполнять дополнительные команды в зависимости от кода завершения исходной команды. Команды разделяются операторами && и ||.

Оператор && позволяет выполнить команду, а затем, если она завершилась успешно (код завершения равен 0), выполнить следующую команду:

deno run --allow-read=. --allow-write=. collect.ts && deno run --allow-read=. analyze.ts

Оператор || работает противоположным образом. Он позволяет выполнить команду, а затем выполнить следующую только в том случае, если первая завершилась с ошибкой (код завершения ненулевой):

deno run --allow-read=. --allow-write=. collect.ts || deno run play_sad_music.ts

Последовательные списки

Последовательные списки похожи на булевы, но выполняют команды независимо от того, завершилась ли предыдущая команда успешно или с ошибкой. Команды разделяются точкой с запятой (;).

deno run output_data.ts ; deno run --allow-net server.ts

Асинхронные команды

Асинхронные команды позволяют выполнять команду асинхронно. Это может быть полезно при запуске нескольких процессов. Чтобы сделать команду асинхронной, добавьте в её конец &. Например, следующая команда выполнит sleep 1 && deno run --allow-net server.ts и deno run --allow-net client.ts одновременно:

sleep 1 && deno run --allow-net server.ts & deno run --allow-net client.ts

В отличие от большинства оболочек, при сбое первой асинхронной команды остальные команды немедленно завершаются с ошибкой. В приведённом выше примере, если команда сервера завершится с ошибкой, команда клиента также завершится с ошибкой и остановится. Это поведение можно отключить, добавив в конец команды || true, что приведёт к принудительному коду завершения 0. Например:

deno run --allow-net server.ts || true & deno run --allow-net client.ts || true

Переменные окружения

Переменные окружения задаются следующим образом:

export VAR_NAME=value

Вот пример использования переменной в подстановке переменной оболочки, а затем её экспорта в окружение запускаемого процесса Deno (обратите внимание: в файле конфигурации JSON двойные кавычки нужно экранировать обратной косой чертой):

export VAR=hello && echo $VAR && deno eval "console.log('Deno: ' + Deno.env.get('VAR'))"

Вывод будет следующим:

hello
Deno: hello

Установка переменных окружения для команды

Чтобы задать переменные окружения перед командой, перечислите их следующим образом:

VAR=hello VAR2=bye deno run main.ts

Эти переменные окружения будут использоваться только для следующей команды.

Переменные оболочки

Переменные оболочки похожи на переменные окружения, но не экспортируются в запускаемые команды. Они задаются следующим синтаксисом:

VAR_NAME=value

Если в примере, аналогичном приведённому в предыдущем разделе «Переменные окружения», использовать переменную оболочки вместо переменной окружения:

VAR=hello && echo $VAR && deno eval "console.log('Deno: ' + Deno.env.get('VAR'))"

мы получим следующий вывод:

hello
Deno: undefined

Переменные оболочки полезны, когда нужно повторно использовать значение, не делая его доступным запущенным процессам.

Переменная кода завершения

Код завершения ранее выполненной команды доступен в переменной $?.

# outputs 10
deno eval 'Deno.exit(10)' || echo $?

Конвейеры

Конвейеры позволяют передать вывод одной команды другой команде.

Следующая команда передаёт стандартный вывод «Hello» на стандартный ввод запущенного процесса Deno:

echo Hello | deno run main.ts

Чтобы передать стандартный вывод и стандартный поток ошибок, используйте вместо этого |&:

deno eval 'console.log(1); console.error(2);' |& deno run main.ts

Подстановка команды

Синтаксис $(command) позволяет использовать вывод команды в других выполняемых командах.

Например, чтобы передать другой команде результат получения последней ревизии git, можно сделать следующее:

deno run main.ts $(git rev-parse HEAD)

Ещё один пример с использованием переменной оболочки:

REV=$(git rev-parse HEAD) && deno run main.ts $REV && echo $REV

Инверсия кода завершения

Чтобы инвертировать код завершения, добавьте перед командой восклицательный знак и пробел:

# change the exit code from 1 to 0
! deno eval 'Deno.exit(1);'

Перенаправления

Перенаправления позволяют направить стандартный вывод и/или стандартный поток ошибок в файл.

Например, следующая команда перенаправляет стандартный вывод deno run main.ts в файл file.txt в файловой системе:

deno run main.ts > file.txt

Чтобы перенаправить вместо этого стандартный поток ошибок, используйте 2>:

deno run main.ts 2> file.txt

Чтобы перенаправить и стандартный вывод, и стандартный поток ошибок, используйте &>:

deno run main.ts &> file.txt

Чтобы дописать данные в файл, а не перезаписать существующие, используйте две правые угловые скобки вместо одной:

deno run main.ts >> file.txt

Подавить стандартный вывод, стандартный поток ошибок или оба потока можно, перенаправив их в /dev/null. Это работает кроссплатформенно, в том числе в Windows.

# suppress stdout
deno run main.ts > /dev/null
# suppress stderr
deno run main.ts 2> /dev/null
# suppress both stdout and stderr
deno run main.ts &> /dev/null

Также можно перенаправить стандартный вывод в стандартный поток ошибок и наоборот:

# redirect stdout to stderr
deno run main.ts >&2
# redirect stderr to stdout
deno run main.ts 2>&1

Поддерживается и перенаправление ввода:

# redirect file.txt to the stdin of gzip
gzip < file.txt

Обратите внимание: одновременное использование нескольких перенаправлений пока не поддерживается.

Кроссплатформенный shebang

Начиная с Deno 1.42, deno task одинаково на всех платформах выполняет скрипты, начинающиеся с #!/usr/bin/env -S.

Например:

#!/usr/bin/env -S deno run
console.log("Hello there!");

{
  "tasks": {
    "hi": "./script.ts"
  }
}

Затем на компьютере с Windows:

> pwd
C:\Users\david\dev\my_project
> deno task hi
Hello there!

Раскрытие glob-шаблонов

Раскрытие glob-шаблонов поддерживается в Deno 1.34 и более поздних версиях. Это позволяет кроссплатформенно задавать шаблоны для поиска файлов.

# match .ts files in the current and descendant directories
echo **/*.ts
# match .ts files in the current directory
echo *.ts
# match files that start with "data", have a single number, then end with .csv
echo data[0-9].csv

Поддерживаются символы шаблонов *, ? и [/].

Параметры оболочки

В Deno 2.6.6 и более поздних версиях deno task поддерживает параметры оболочки для управления раскрытием glob-шаблонов и поведением конвейеров. По умолчанию включены failglob и globstar.

• failglob — если параметр включён, шаблоны, не совпавшие ни с одним файлом, вызовут ошибку. Отключается с помощью shopt -u failglob.
• globstar — если параметр включён, ** соответствует нулю или более каталогам. Отключается с помощью shopt -u globstar.
• nullglob — если параметр включён, шаблоны, не совпавшие ни с одним файлом, раскрываются в пустую строку, а не остаются буквальным шаблоном. Включается с помощью shopt -s nullglob.
• pipefail — если параметр включён, код завершения конвейера совпадает с кодом последней завершившейся команды с ненулевым статусом либо равен нулю, если все команды завершились успешно. Включается с помощью set -o pipefail.
• errexit (Deno 2.8+) — если параметр включён, последовательный список прерывается при первой команде, завершившейся с ненулевым кодом. Включается с помощью set -e или set -o errexit; отключается с помощью set +e или set +o errexit. Полезно при переносе shell-скрипта, опирающегося на семантику set -e, в блок tasks.

Примеры:

{
  "tasks": {
    // disable failglob
    "task1": "shopt -u failglob && rm -rf *.ts",
    // disable failglob and enable nullglob
    "task2": "shopt -u failglob && shopt -s nullglob && rm -rf *.ts",
    // disable globstar
    "task3": "shopt -u globstar && echo **/*.ts",
    // enable pipefail
    "task4": "set -o pipefail && cat missing.txt | echo 'hello'",
    // abort the sequential list on the first failing command
    "task5": "set -e; build_step_one; build_step_two; build_step_three"
  }
}

Встроенные команды

deno task включает несколько встроенных команд, которые одинаково работают в Windows, Mac и Linux без дополнительной настройки.

• cp — копирует файлы.
• mv — перемещает файлы.
• rm — удаляет файлы или каталоги.
  • Например: rm -rf [FILE]... — обычно используется для рекурсивного удаления файлов или каталогов.
• mkdir — создаёт каталоги.
  • Например: mkdir -p DIRECTORY... — обычно используется для создания каталога и всех его родительских каталогов без ошибки, если он уже существует.
• pwd — выводит имя текущего/рабочего каталога.
• sleep — приостанавливает выполнение на указанное время.
  • Например, sleep 1 — приостановить выполнение на 1 секунду, sleep 0.5 — на полсекунды, а sleep 1m — на минуту.
• echo — выводит строку текста.
• cat — объединяет файлы и выводит их в стандартный поток вывода. Если аргументы не указаны, считывает и выводит данные из стандартного потока ввода.
• exit — завершает работу оболочки.
• head — выводит начало файла.
• export — задаёт переменные окружения и экспортирует их в запускаемые команды.
• unset — удаляет переменные окружения.
• xargs — формирует аргументы из стандартного потока ввода и выполняет команду.
• : — пустая команда POSIX. Ничего не делает и всегда завершается со статусом 0 (Deno 2.8+). Удобна в качестве пустой операции в условных выражениях или для побочных эффектов при раскрытии параметров.

Если вам не хватает какого-либо полезного флага команды или у вас есть предложения по поводу дополнительных встроенных команд, пожалуйста, создайте issue в репозитории deno_task_shell.

Обратите внимание: если вы хотите выполнить любую из этих команд на Mac или Linux без обеспечения кроссплатформенной совместимости, запустите её через sh: sh -c <command> (например, sh -c cp source destination).

Поддержка package.json

Если обнаружен файл package.json, deno task использует его записи "scripts". Обратите внимание: Deno не соблюдает и не поддерживает события жизненного цикла npm, такие как preinstall или postinstall — необходимо явно запускать нужные вам скрипты (например, deno install --entrypoint main.ts && deno task postinstall).

При запуске скрипта package.json командой deno task задаются переменные окружения npm_*, которые предоставляет npm, поэтому скрипты, читающие их, продолжают работать. К ним относятся npm_package_name, npm_package_version, npm_lifecycle_event (имя скрипта), npm_lifecycle_script (строка его команды) и npm_config_user_agent, а также npm_execpath и npm_node_execpath (обеим задаётся путь к исполняемому файлу deno) и npm_command (ей задаётся значение run-script). Эти переменные задаются только для скриптов package.json. Задачи, определённые в deno.json, их не получают.

Разрешение команд

Когда в команде задачи указывается исполняемый файл (например, ohm, tsc, eslint), Deno ищет его в следующем порядке:

1. node_modules/.bin/ — если в каталоге задачи или одном из его родительских каталогов есть папка node_modules/.bin/, Deno сначала ищет исполняемый файл там. Обратите внимание: deno add npm:<pkg> обновляет импорты deno.json и deno.lock, но не создаёт каталог node_modules. Каталог node_modules создаётся только при использовании deno install или других инструментов, совместимых с npm.

2. Поле package.json bin — если зависимость определяет поле bin в своём package.json, Deno автоматически делает эти команды доступными в скриптах задач через свой уровень совместимости с npm.

3. Системный PATH — если команда не найдена указанными выше способами, Deno ищет её в системном PATH.

Пример

Предположим, что в package.json указано:

{
  "dependencies": {
    "@ohm-js/cli": "^2.0.0"
  }
}

А в deno.json указано:

{
  "tasks": {
    "generate": "ohm src/grammar.ohm -o src/grammar.js"
  }
}

Запуск deno task generate выполнит следующие действия:

1. Поиск ohm в node_modules/.bin/ohm
2. Если файл найден, его выполнение с использованием уровня совместимости Deno с Node.js
3. Команда выполняется в среде выполнения Deno, а не Node.js.