concurrently 8.2.2 → 9.0.1

package/docs/cli/input-handling.md

@@ -0,0 +1,40 @@
+# Input Handling
+
+By default, concurrently doesn't send input to any commands it spawns.<br/>
+In the below example, typing `rs` to manually restart [nodemon](https://nodemon.io/) does nothing:
+
+```bash
+$ concurrently "nodemon" "npm run watch-js"
+rs
+```
+
+To turn on input handling, it's necessary to set the `--handle-input`/`-i` flag.<br/>
+This will send `rs` to the first command:
+
+```bash
+$ concurrently --handle-input "nodemon" "npm run watch-js"
+rs
+```
+
+To send input to a different command instead, it's possible to prefix the input with the command index, followed by a `:`.<br/>
+For example, the below sends `rs` to the second command:
+
+```bash
+$ concurrently --handle-input "npm run watch-js" "nodemon"
+1:rs
+```
+
+If the command has a name, it's also possible to target it using that command's name:
+
+```bash
+$ concurrently --handle-input --names js,server "npm run watch-js" "nodemon"
+server:rs
+```
+
+It's also possible to change the default command that receives input.<br/>
+To do this, set the `--default-input-target` flag to a command's index or name.
+
+```bash
+$ concurrently --handle-input --default-input-target 1 "npm run watch-js" "nodemon"
+rs
+```

package/docs/cli/output-control.md

@@ -0,0 +1,35 @@
+# Output Control
+
+concurrently offers a few ways to control a command's output.
+
+## Hiding
+
+A command's outputs (and all its events) can be hidden by using the `--hide` flag.
+
+```bash
+$ concurrently --hide 0 "echo Hello there" "echo 'General Kenobi!'"
+[1] General Kenobi!
+[1] echo 'General Kenobi!' exited with code 0
+```
+
+## Grouping
+
+It might be useful at times to make sure that the commands outputs are grouped together, while running them in parallel.<br/>
+This can be done with the `--group` flag.
+
+```bash
+$ concurrently --group "echo Hello there && sleep 2 && echo 'General Kenobi!'" "echo hi Star Wars fans"
+[0] Hello there
+[0] General Kenobi!
+[0] echo Hello there && sleep 2 && echo 'General Kenobi!' exited with code 0
+[1] hi Star Wars fans
+[1] echo hi Star Wars fans exited with code 0
+```
+
+## No Colors
+
+When piping concurrently's outputs to another command or file, you might want to force it to not use colors, as these can break the other command's parsing, or reduce the legibility of the output in non-terminal environments.
+
+```bash
+$ concurrently -c red,blue --no-color "echo Hello there" "echo 'General Kenobi!'"
+```

package/docs/cli/passthrough-arguments.md

@@ -0,0 +1,80 @@
+# Passthrough Arguments
+
+If you have a shortcut for running a specific combination of commands through concurrently,
+you might need at some point to pass additional arguments/flags to some of these.
+
+For example, imagine you have in your `package.json` file scripts like this:
+
+```jsonc
+{
+  // ...
+  "scripts": {
+    "build:client": "tsc -p client",
+    "build:server": "tsc -p server",
+    "build": "concurrently npm:build:client npm:build:server"
+  }
+}
+```
+
+If you wanted to run only either `build:server` or `build:client` with an additional `--noEmit` flag,
+you can do so with `npm run build:server -- --watch`, for example.<br/>
+However, if you want to do that while using concurrently, as `npm run dev -- --noEmit` for example,
+you might find that concurrently actually parses `--watch` as its own flag, which does nothing,
+because it doesn't exist.
+
+To solve this, you can set the `--passthrough-arguments`/`-P` flag, which instructs concurrently to
+take everything after a `--` as additional arguments that are passed through to the input commands
+via a few placeholder styles:
+
+## Single argument
+
+We can modify the original `build` script to pass a single additional argument/flag to a script by using
+a 1-indexed `{number}` placeholder to the command you want it to apply to:
+
+```jsonc
+{
+  // ...
+  "scripts": {
+    // ...
+    "build": "concurrently -P 'npm:build:client -- {1}' npm:build:server --",
+    "typecheck": "npm run build -- --noEmit"
+  }
+}
+```
+
+With this, running `npm run typecheck` will pass `--noEmit` only to `npm run build:client`.
+
+## All arguments
+
+In the original `build` example script, you're more likely to want to pass every additional argument/flag
+to your commands. This can be done with the `{@}` placeholder.
+
+```jsonc
+{
+  // ...
+  "scripts": {
+    // ...
+    "build": "concurrently -P 'npm:build:client -- {@}' 'npm:build:server -- {@}' --",
+    "typecheck": "npm run build -- --watch --noEmit"
+  }
+}
+```
+
+In the above example, both `--watch` and `--noEmit` are passed to each command.
+
+## All arguments, combined
+
+If for some reason you wish to combine all additional arguments into a single one, you can do that with the `{*}` placeholder,
+which wraps the arguments in quotes.
+
+```jsonc
+{
+  // ...
+  "scripts": {
+    // ...
+    "build": "concurrently -P 'npm:build:client -- --outDir {*}/client' 'npm:build:server -- --outDir {*}/server' -- $(date)"
+  }
+}
+```
+
+In the above example, the output of the `date` command, which looks like `Sun  1 Sep 2024 23:50:00 AEST` will be passed as a single string to the `--outDir` parameter of both commands.

package/docs/cli/prefixing.md

@@ -0,0 +1,147 @@
+# Prefixing
+
+## Prefix Styles
+
+concurrently will by default prefix each command's outputs with a zero-based index, wrapped in square brackets:
+
+```bash
+$ concurrently "echo Hello there" "echo 'General Kenobi!'"
+[0] Hello there
+[1] General Kenobi!
+[0] echo Hello there exited with code 0
+[1] echo 'General Kenobi!' exited with code 0
+```
+
+If you've given the commands names, they are used instead:
+
+```bash
+$ concurrently --names one,two "echo Hello there" "echo 'General Kenobi!'"
+[one] Hello there
+[two] General Kenobi!
+[one] echo Hello there exited with code 0
+[two] echo 'General Kenobi!' exited with code 0
+```
+
+There are other prefix styles available too:
+
+| Style     | Description                       |
+| --------- | --------------------------------- |
+| `index`   | Zero-based command's index        |
+| `name`    | The command's name                |
+| `command` | The command's line                |
+| `time`    | Time of output                    |
+| `pid`     | ID of the command's process (PID) |
+| `none`    | No prefix                         |
+
+Any of these can be used by setting the `--prefix`/`-p` flag. For example:
+
+```bash
+$ concurrently --prefix pid "echo Hello there" "echo 'General Kenobi!'"
+[2222] Hello there
+[2223] General Kenobi!
+[2222] echo Hello there exited with code 0
+[2223] echo 'General Kenobi!' exited with code 0
+```
+
+It's also possible to have a prefix based on a template. Any of the styles listed above can be used by wrapping it in `{}`.
+Doing so will also remove the square brackets:
+
+```bash
+$ concurrently --prefix "{index}-{pid}" "echo Hello there" "echo 'General Kenobi!'"
+0-2222 Hello there
+1-2223 General Kenobi!
+0-2222 echo Hello there exited with code 0
+1-2223 echo 'General Kenobi!' exited with code 0
+```
+
+## Prefix Colors
+
+By default, there are no colors applied to concurrently prefixes, and they just use whatever the terminal's defaults are.
+
+This can be changed by using the `--prefix-colors`/`-c` flag, which takes a comma-separated list of colors to use.<br/>
+The available values are color names (e.g. `green`, `magenta`, `gray`, etc), a hex value (such as `#23de43`), or `auto`, to automatically select a color.
+
+```bash
+$ concurrently -c red,blue "echo Hello there" "echo 'General Kenobi!'"
+```
+
+<details>
+<summary>List of available color names</summary>
+
+- `black`
+- `blue`
+- `cyan`
+- `green`
+- `gray`
+- `magenta`
+- `red`
+- `white`
+- `yellow`
+</details>
+
+Colors can take modifiers too. Several can be applied at once by prepending `.<modifier 1>.<modifier 2>` and so on.
+
+```bash
+$ concurrently -c red,bold.blue.dim "echo Hello there" "echo 'General Kenobi!'"
+```
+
+<details>
+<summary>List of available modifiers</summary>
+
+- `reset`
+- `bold`
+- `dim`
+- `hidden`
+- `inverse`
+- `italic`
+- `strikethrough`
+- `underline`
+</details>
+
+A background color can be set in a similary fashion.
+
+```bash
+$ concurrently -c bgGray,red.bgBlack "echo Hello there" "echo 'General Kenobi!'"
+```
+
+<details>
+<summary>List of available background color names</summary>
+
+- `bgBlack`
+- `bgBlue`
+- `bgCyan`
+- `bgGreen`
+- `bgGray`
+- `bgMagenta`
+- `bgRed`
+- `bgWhite`
+- `bgYellow`
+</details>
+
+## Prefix Length
+
+When using the `command` prefix style, it's possible that it'll be too long.<br/>
+It can be limited by setting the `--prefix-length`/`-l` flag:
+
+```bash
+$ concurrently -p command -l 10 "echo Hello there" "echo 'General Kenobi!'"
+[echo..here] Hello there
+[echo..bi!'] General Kenobi!
+[echo..here] echo Hello there exited with code 0
+[echo..bi!'] echo 'General Kenobi!' exited with code 0
+```
+
+It's also possible that some prefixes are too short, and you want all of them to have the same length.<br/>
+This can be done by setting the `--pad-prefix` flag:
+
+```bash
+$ concurrently -n foo,barbaz --pad-prefix "echo Hello there" "echo 'General Kenobi!'"
+[foo   ] Hello there
+[foo   ] echo Hello there exited with code 0
+[barbaz] General Kenobi!
+[barbaz] echo 'General Kenobi!' exited with code 0
+```
+
+> [!NOTE]
+> If using the `pid` prefix style in combination with [`--restart-tries`](./restarting.md), the length of the PID might grow, in which case all subsequent lines will match the new length.<br/>
+> This might happen, for example, if the PID was 99 and it's now 100.

package/docs/cli/restarting.md

@@ -0,0 +1,38 @@
+# Restarting Commands
+
+Sometimes it's useful to have commands that exited with a non-zero status to restart automatically.<br/>
+concurrently lets you configure how many times you wish for such a command to restart through the `--restart-tries` flag:
+
+```bash
+$ concurrently --restart-tries 2 "exit 1"
+[0] exit 1 exited with code 1
+[0] exit 1 restarted
+[0] exit 1 exited with code 1
+[0] exit 1 restarted
+[0] exit 1 exited with code 1
+```
+
+Sometimes, it might be interesting to have commands wait before restarting.<br/>
+To do this, simply set `--restart-after` to a the number of milliseconds you'd like to delay restarting.
+
+```bash
+$ concurrently -p time --restart-tries 1 --restart-after 3000 "exit 1"
+[2024-09-01 23:43:55.871] exit 1 exited with code 1
+[2024-09-01 23:43:58.874] exit 1 restarted
+[2024-09-01 23:43:58.891] exit 1 exited with code 1
+```
+
+If a command is not having success spawning, you might want to instead apply an exponential back-off.<br/>
+Set `--restart-after exponential` to have commands respawn with a `2^N` seconds delay.
+
+```bash
+$ concurrently -p time --restart-tries 3 --restart-after exponential "exit 1"
+
+[2024-09-01 23:49:01.124] exit 1 exited with code 1
+[2024-09-01 23:49:02.127] exit 1 restarted
+[2024-09-01 23:49:02.139] exit 1 exited with code 1
+[2024-09-01 23:49:04.141] exit 1 restarted
+[2024-09-01 23:49:04.157] exit 1 exited with code 1
+[2024-09-01 23:49:08.158] exit 1 restarted
+[2024-09-01 23:49:08.174] exit 1 exited with code 1
+```

package/docs/cli/shortcuts.md

@@ -0,0 +1,72 @@
+# Command Shortcuts
+
+Package managers that execute scripts from a `package.json` file can be shortened when in concurrently.<br/>
+The following are supported:
+
+| Syntax          | Expands to            |
+| --------------- | --------------------- |
+| `npm:<script>`  | `npm run <script>`    |
+| `pnpm:<script>` | `pnpm run <script>`   |
+| `yarn:<script>` | `yarn run <script>`   |
+| `bun:<script>`  | `bun run <script>`    |
+| `node:<script>` | `node --run <script>` |
+
+> [!NOTE]
+>
+> `node --run` is only available from [Node 22 onwards](https://nodejs.org/en/blog/announcements/v22-release-announce#running-packagejson-scripts).
+
+For example, given the following `package.json` contents:
+
+```jsonc
+{
+  // ...
+  "scripts": {
+    "lint:js": "...",
+    "lint:ts": "...",
+    "lint:fix:js": "...",
+    "lint:fix:ts": "..."
+    // ...
+  }
+  // ...
+}
+```
+
+It's possible to run some of these with the following command line:
+
+```bash
+$ concurrently "pnpm:lint:js"
+# Is equivalent to
+$ concurrently -n lint:js "pnpm run lint:js"
+```
+
+Note that the command automatically receives a name equal to the script name.
+
+If you have several scripts with similar name patterns, you can use the `*` wildcard to run all of them at once.<br/>
+The spawned commands will receive names set to whatever the `*` wildcard matched.
+
+```bash
+$ concurrently "npm:lint:fix:*"
+# is equivalent to
+$ concurrently -n js,ts "npm run lint:fix:js" "npm run lint:fix:ts"
+```
+
+If you specify a command name when using wildcards, it'll be a prefix of what the `*` wildcard matched:
+
+```bash
+$ concurrently -n fix: "npm:lint:fix:*"
+# is equivalent to
+$ concurrently -n fix:js,fix:ts "npm run lint:fix:js" "npm run lint:fix:ts"
+```
+
+Filtering out commands matched by wildcard is also possible. Do this with by including `(!<some pattern>)` in the command line:
+
+```bash
+$ concurrently 'yarn:lint:*(!fix)'
+# is equivalent to
+$ concurrently -n js,ts "yarn run lint:js" "yarn run lint:ts"
+```
+
+> [!NOTE]
+> If you use this syntax with double quotes (`"`), bash and other shells might fail
+> parsing it. You'll need to escape the `!`, or use single quote (`'`) instead.<br/>
+> See [here](https://serverfault.com/a/208266/160539) for more information.

package/index.d.mts

@@ -0,0 +1,7 @@
+/*
+ * While in local development, make sure you've run `pnpm run build` first.
+ */
+import { concurrently } from './dist/src/index.js';
+
+export * from './dist/src/index.js';
+export default concurrently;

package/index.d.ts

@@ -0,0 +1,11 @@
+/*
+ * While in local development, make sure you've run `pnpm run build` first.
+ */
+import { concurrently } from './dist/src/index.js';
+
+export * from './dist/src/index.js';
+// @ts-expect-error ignore the usage of `export =` along with `export default`.
+// This is seemingly fine, but the file needs to be included in the TS project, which can't be done
+// due to importing from `dist`. See https://stackoverflow.com/q/42609768/2083599
+export = concurrently;
+export default concurrently;

package/index.js

@@ -5,5 +5,10 @@
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const concurrently = require('./dist/src/index.js');
 
-module.exports = exports = concurrently.default;
+// For require()
+module.exports = exports = concurrently.concurrently;
+
+// For TS + import syntax; mimics `export default`
+exports.default = exports;
+
 Object.assign(exports, concurrently);

package/index.mjs

@@ -2,9 +2,9 @@
  * While in local development, make sure you've run `pnpm run build` first.
  */
 
-import concurrently from './dist/src/index.js';
+import { concurrently } from './dist/src/index.js';
 
 // NOTE: the star reexport doesn't work in Node <12.20, <14.13 and <15.
 export * from './dist/src/index.js';
 
-export default concurrently.default;
+export default concurrently;

package/package.json

@@ -1,23 +1,28 @@
 {
   "name": "concurrently",
-  "version": "8.2.2",
+  "version": "9.0.1",
   "description": "Run commands concurrently",
+  "packageManager": "pnpm@8.15.9+sha256.daa27a0b541bc635323ff96c2ded995467ff9fe6d69ff67021558aa9ad9dcc36",
   "main": "index.js",
-  "types": "dist/src/index.d.ts",
+  "types": "index.d.ts",
   "type": "commonjs",
   "bin": {
     "concurrently": "./dist/bin/concurrently.js",
     "conc": "./dist/bin/concurrently.js"
   },
   "engines": {
-    "node": "^14.13.0 || >=16.0.0"
+    "node": ">=18"
   },
   "exports": {
     ".": {
-      "types": "./dist/src/index.d.ts",
-      "import": "./index.mjs",
-      "require": "./index.js",
-      "default": "./index.js"
+      "import": {
+        "types": "./index.d.mts",
+        "default": "./index.mjs"
+      },
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      }
     },
     "./package.json": "./package.json"
   },
@@ -38,40 +43,39 @@
   "license": "MIT",
   "dependencies": {
     "chalk": "^4.1.2",
-    "date-fns": "^2.30.0",
     "lodash": "^4.17.21",
     "rxjs": "^7.8.1",
     "shell-quote": "^1.8.1",
-    "spawn-command": "0.0.2",
     "supports-color": "^8.1.1",
     "tree-kill": "^1.2.2",
     "yargs": "^17.7.2"
   },
   "devDependencies": {
     "@hirez_io/observer-spy": "^2.2.0",
-    "@swc/core": "^1.3.93",
-    "@swc/jest": "^0.2.29",
+    "@jest/types": "^29.6.3",
+    "@swc/core": "^1.7.23",
+    "@swc/jest": "^0.2.36",
     "@types/jest": "^29.5.6",
-    "@types/lodash": "^4.14.200",
-    "@types/node": "^14.18.62",
-    "@types/shell-quote": "^1.7.3",
-    "@types/supports-color": "^8.1.2",
-    "@types/yargs": "^17.0.29",
-    "@typescript-eslint/eslint-plugin": "^6.8.0",
-    "@typescript-eslint/parser": "^6.8.0",
-    "coveralls-next": "^4.2.0",
+    "@types/lodash": "^4.17.7",
+    "@types/node": "^18.19.50",
+    "@types/shell-quote": "^1.7.5",
+    "@types/supports-color": "^8.1.3",
+    "@types/yargs": "^17.0.33",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "coveralls-next": "^4.2.1",
     "ctrlc-wrapper": "^0.0.4",
-    "esbuild": "~0.19.5",
-    "eslint": "^8.51.0",
-    "eslint-config-prettier": "^9.0.0",
-    "eslint-plugin-import": "^2.28.1",
-    "eslint-plugin-jest": "^27.4.2",
-    "eslint-plugin-prettier": "^5.0.1",
+    "esbuild": "~0.23.1",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-import": "^2.30.0",
+    "eslint-plugin-jest": "^27.9.0",
+    "eslint-plugin-prettier": "^5.2.1",
     "eslint-plugin-simple-import-sort": "^10.0.0",
-    "husky": "^8.0.3",
+    "husky": "^9.1.5",
     "jest": "^29.7.0",
     "jest-create-mock-instance": "^2.0.0",
-    "lint-staged": "^13.3.0",
+    "lint-staged": "^15.2.10",
     "prettier": "^3.0.3",
     "safe-publish-latest": "^2.0.0",
     "string-argv": "^0.3.2",
@@ -80,10 +84,13 @@
   "files": [
     "dist",
     "index.js",
+    "index.d.ts",
     "index.mjs",
+    "index.d.mts",
     "!**/fixtures",
     "!**/*.spec.js",
-    "!**/*.spec.d.ts"
+    "!**/*.spec.d.ts",
+    "docs"
   ],
   "lint-staged": {
     "*.?(m){js,ts}": "eslint --fix",
@@ -98,6 +105,7 @@
     "lint": "eslint --ignore-path .gitignore --ext mjs,js,ts .",
     "lint:fix": "pnpm run lint --fix",
     "report-coverage": "cat coverage/lcov.info | coveralls",
-    "test": "jest"
+    "test": "jest --selectProjects unit",
+    "test:smoke": "jest --selectProjects smoke"
   }
 }

package/dist/bin/epilogue.d.ts

@@ -1 +0,0 @@
-export declare const epilogue: string;

package/dist/bin/epilogue.js

@@ -1,90 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.epilogue = void 0;
-// Add new examples here.
-// Always start with `$ $0` so that it a) symbolizes a command line; and b) $0 gets replaced by the binary name uniformly.
-const examples = [
-    {
-        description: 'Output nothing more than stdout+stderr of child processes',
-        example: '$ $0 --raw "npm run watch-less" "npm run watch-js"',
-    },
-    {
-        description: 'Normal output but without colors e.g. when logging to file',
-        example: '$ $0 --no-color "grunt watch" "http-server" > log',
-    },
-    {
-        description: 'Custom prefix',
-        example: '$ $0 --prefix "{time}-{pid}" "npm run watch" "http-server"',
-    },
-    {
-        description: 'Custom names and colored prefixes',
-        example: '$ $0 --names "HTTP,WATCH" -c "bgBlue.bold,bgMagenta.bold" "http-server" "npm run watch"',
-    },
-    {
-        description: 'Auto varying colored prefixes',
-        example: '$ $0 -c "auto" "npm run watch" "http-server"',
-    },
-    {
-        description: 'Mixing auto and manual colored prefixes',
-        example: '$ $0 -c "red,auto" "npm run watch" "http-server" "echo hello"',
-    },
-    {
-        description: 'Configuring via environment variables with CONCURRENTLY_ prefix',
-        example: '$ CONCURRENTLY_RAW=true CONCURRENTLY_KILL_OTHERS=true $0 "echo hello" "echo world"',
-    },
-    {
-        description: 'Send input to default',
-        example: [
-            '$ $0 --handle-input "nodemon" "npm run watch-js"',
-            'rs  # Sends rs command to nodemon process',
-        ].join('\n'),
-    },
-    {
-        description: 'Send input to specific child identified by index',
-        example: ['$ $0 --handle-input "npm run watch-js" nodemon', '1:rs'].join('\n'),
-    },
-    {
-        description: 'Send input to specific child identified by name',
-        example: ['$ $0 --handle-input -n js,srv "npm run watch-js" nodemon', 'srv:rs'].join('\n'),
-    },
-    {
-        description: 'Shortened NPM run commands',
-        example: '$ $0 npm:watch-node npm:watch-js npm:watch-css',
-    },
-    {
-        description: 'Shortened NPM run command with wildcard (make sure to wrap it in quotes!)',
-        example: '$ $0 "npm:watch-*"',
-    },
-    {
-        description: 'Exclude patterns so that between "lint:js" and "lint:fix:js", only "lint:js" is ran',
-        example: '$ $0 "npm:*(!fix)"',
-    },
-    {
-        description: "Passthrough some additional arguments via '{<number>}' placeholder",
-        example: '$ $0 -P "echo {1}" -- foo',
-    },
-    {
-        description: "Passthrough all additional arguments via '{@}' placeholder",
-        example: '$ $0 -P "npm:dev-* -- {@}" -- --watch --noEmit',
-    },
-    {
-        description: "Passthrough all additional arguments combined via '{*}' placeholder",
-        example: '$ $0 -P "npm:dev-* -- {*}" -- --watch --noEmit',
-    },
-];
-const examplesString = examples
-    .map(({ example, description }) => [
-    ` - ${description}`,
-    example
-        .split('\n')
-        .map((line) => `     ${line}`)
-        .join('\n'),
-].join('\n\n'))
-    .join('\n\n');
-exports.epilogue = `
-Examples:
-
-${examplesString}
-
-For more details, visit https://github.com/open-cli-tools/concurrently
-`;