Type annotations #6278

bentsherman · 2025-07-15T17:19:52Z

This PR adds Nextflow-style type annotations for workflows, functions, and local variables.

Waiting for #5929 to be merged

netlify · 2025-07-15T17:19:56Z

✅ Deploy Preview for nextflow-docs-staging ready!

Name	Link
🔨 Latest commit	`59f9378`
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs-staging/deploys/687ad0f9d49c5d000879016b
😎 Deploy Preview	https://deploy-preview-6278--nextflow-docs-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Signed-off-by: Ben Sherman <[email protected]>

christopher-hakkaart

I didn't spot any errors/typos. I've made some suggests to move the language to a active voice. Feel free to approve/reject as you see fit.

christopher-hakkaart · 2025-07-21T00:06:01Z

docs/migrations/25-10.md

+
+<h3>Type annotations</h3>
+
+Type annotations are a way to denote the *type* of a variable. They are useful both for documenting and validating your pipeline code.


Suggested change

Type annotations are a way to denote the *type* of a variable. They are useful both for documenting and validating your pipeline code.

You can use type annotations to denote the **type** of a variable. They help document and validate your pipeline code.

christopher-hakkaart · 2025-07-21T00:07:06Z

docs/migrations/25-10.md

+}
+```
+
+The following declarations can be annotated with types:


Suggested change

The following declarations can be annotated with types:

You can annotate the following declarations with types:

christopher-hakkaart · 2025-07-21T00:10:11Z

docs/migrations/25-10.md

+
+Type annotations can refer to any of the {ref}`standard types <stdlib-types>`.
+
+Type annotations can be appended with `?` to denote that the value can be `null`:


Suggested change

Type annotations can be appended with `?` to denote that the value can be `null`:

You can append an `?` to type annotations to denote that the value can be `null`:

christopher-hakkaart · 2025-07-21T00:16:06Z

docs/migrations/25-10.md

+```
+
+:::{note}
+While Nextflow inherited type annotations of the form `<type> <name>` from Groovy, this syntax was deprecated in the {ref}`strict syntax <strict-syntax-page>`. Groovy-style type annotations are still allowed for functions and local variables, but will be automatically converted to Nextflow-stype type annotations when formatting code with the language server or `nextflow lint`.


Suggested change

While Nextflow inherited type annotations of the form `<type> <name>` from Groovy, this syntax was deprecated in the {ref}`strict syntax <strict-syntax-page>`. Groovy-style type annotations are still allowed for functions and local variables, but will be automatically converted to Nextflow-stype type annotations when formatting code with the language server or `nextflow lint`.

Nextflow previously inherited type annotations in the form `<type> <name>` from Groovy, but this syntax is now deprecated under the <strict-syntax-page>`. Groovy-style type annotations are still allowed for functions and local variables. However, the language server and `nextflow lint` will automatically convert them to Nextflow-style type annotations when formatting code.

christopher-hakkaart · 2025-07-21T00:18:02Z

docs/process.md

@@ -655,7 +655,7 @@ hello

 ### Input tuples (`tuple`)

-The `tuple` qualifier allows you to group multiple values into a single input definition. It can be useful when a channel emits tuples of values that need to be handled separately. Each element in the tuple is associated with a corresponding element in the `tuple` definition. For example:
+The `tuple` qualifier allows you to group multiple values into a single input definition. It can be useful when a channel emits {ref}`tuples <script-tuples>` of values that need to be handled separately. Each element in the tuple is associated with a corresponding element in the `tuple` definition. For example:


Suggested change

The `tuple` qualifier allows you to group multiple values into a single input definition. It can be useful when a channel emits {ref}`tuples <script-tuples>` of values that need to be handled separately. Each element in the tuple is associated with a corresponding element in the `tuple` definition. For example:

The `tuple` qualifier groups multiple values into a single input definition. It can be useful when a channel emits {ref}`tuples <script-tuples>` of values that need to be handled separately. Each element in the tuple is associated with a corresponding element in the `tuple` definition. For example:

christopher-hakkaart · 2025-07-21T01:01:49Z

docs/script.md

+is_male = person[2]
+```
+
+Tuples can be destructured in assignments:


Suggested change

Tuples can be destructured in assignments:

You can destroy tuples in assignments:

christopher-hakkaart · 2025-07-21T02:02:41Z

docs/strict-syntax.md

+def meta: Map = [:]
+```
+
+While Groovy-style type annotations are still supported, the linter and language server will automatically convert them to Nextflow-style type annotations when formatting code. Groovy-style type annotations will not be supported in a future version.


Suggested change

While Groovy-style type annotations are still supported, the linter and language server will automatically convert them to Nextflow-style type annotations when formatting code. Groovy-style type annotations will not be supported in a future version.

Groovy-style type annotations are supported. However, the language server and `nextflow lint` will automatically convert them to Nextflow-style type annotations when formatting code. Groovy-style type annotations will not be supported in a future version.

christopher-hakkaart · 2025-07-21T02:03:49Z

docs/strict-syntax.md

@@ -368,21 +380,26 @@ def map = (Map) readJson(json)  // soft cast
 def map = readJson(json) as Map // hard cast
 ```

-In the strict syntax, only hard casts are supported. However, hard casts are discouraged because they can cause unexpected behavior if used improperly. Groovy-style type annotations should be used instead:
+In the strict syntax, only hard casts are supported.


Suggested change

In the strict syntax, only hard casts are supported.

Only hard casts are supported in the strict syntax.

christopher-hakkaart · 2025-07-21T02:05:10Z

docs/strict-syntax.md

-In the strict syntax, only hard casts are supported. However, hard casts are discouraged because they can cause unexpected behavior if used improperly. Groovy-style type annotations should be used instead:
+In the strict syntax, only hard casts are supported.
+
+When casting a value to a different type, it is always better to use an explicit method if one is available. For example, to parse a string as a number:


Suggested change

When casting a value to a different type, it is always better to use an explicit method if one is available. For example, to parse a string as a number:

Always use an explicit method to cast a value to a different type if one is available. For example, to parse a string as a number:

christopher-hakkaart · 2025-07-21T02:06:32Z

docs/strict-syntax.md


-When converting a value to a different type, it is better to use an explicit method rather than a cast. For example, to parse a string as a number:
+In cases where a function returns an unknown type, use a type annotation:


Suggested change

In cases where a function returns an unknown type, use a type annotation:

Use a type annotation when a function returns an unknown type:

bentsherman requested a review from pditommaso July 15, 2025 17:19

bentsherman added this to the 25.10 milestone Jul 15, 2025

bentsherman force-pushed the type-annotations branch 3 times, most recently from 91d5453 to d737101 Compare July 16, 2025 17:19

Type annotations

59f9378

Signed-off-by: Ben Sherman <[email protected]>

bentsherman force-pushed the type-annotations branch from d737101 to 59f9378 Compare July 18, 2025 22:55

christopher-hakkaart reviewed Jul 21, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Type annotations #6278

Type annotations #6278

Uh oh!

bentsherman commented Jul 15, 2025 •

edited

Loading

Uh oh!

netlify bot commented Jul 15, 2025 •

edited

Loading

Uh oh!

christopher-hakkaart left a comment

Uh oh!

christopher-hakkaart Jul 21, 2025

Uh oh!

christopher-hakkaart Jul 21, 2025

Uh oh!

christopher-hakkaart Jul 21, 2025

Uh oh!

christopher-hakkaart Jul 21, 2025

Uh oh!

christopher-hakkaart Jul 21, 2025

Uh oh!

christopher-hakkaart Jul 21, 2025

Uh oh!

christopher-hakkaart Jul 21, 2025

Uh oh!

christopher-hakkaart Jul 21, 2025

Uh oh!

christopher-hakkaart Jul 21, 2025

Uh oh!

christopher-hakkaart Jul 21, 2025

Uh oh!

Uh oh!


		<h3>Type annotations</h3>

		Type annotations are a way to denote the type of a variable. They are useful both for documenting and validating your pipeline code.

	Type annotations are a way to denote the type of a variable. They are useful both for documenting and validating your pipeline code.
	You can use type annotations to denote the type of a variable. They help document and validate your pipeline code.

	The following declarations can be annotated with types:
	You can annotate the following declarations with types:


		Type annotations can refer to any of the {ref}`standard types <stdlib-types>`.

		Type annotations can be appended with `?` to denote that the value can be `null`:

	Type annotations can be appended with `?` to denote that the value can be `null`:
	You can append an `?` to type annotations to denote that the value can be `null`:

	While Nextflow inherited type annotations of the form `<type> <name>` from Groovy, this syntax was deprecated in the {ref}`strict syntax <strict-syntax-page>`. Groovy-style type annotations are still allowed for functions and local variables, but will be automatically converted to Nextflow-stype type annotations when formatting code with the language server or `nextflow lint`.
	Nextflow previously inherited type annotations in the form `<type> <name>` from Groovy, but this syntax is now deprecated under the <strict-syntax-page>`. Groovy-style type annotations are still allowed for functions and local variables. However, the language server and `nextflow lint` will automatically convert them to Nextflow-style type annotations when formatting code.

	The `tuple` qualifier allows you to group multiple values into a single input definition. It can be useful when a channel emits {ref}`tuples <script-tuples>` of values that need to be handled separately. Each element in the tuple is associated with a corresponding element in the `tuple` definition. For example:
	The `tuple` qualifier groups multiple values into a single input definition. It can be useful when a channel emits {ref}`tuples <script-tuples>` of values that need to be handled separately. Each element in the tuple is associated with a corresponding element in the `tuple` definition. For example:

	Tuples can be destructured in assignments:
	You can destroy tuples in assignments:

	While Groovy-style type annotations are still supported, the linter and language server will automatically convert them to Nextflow-style type annotations when formatting code. Groovy-style type annotations will not be supported in a future version.
	Groovy-style type annotations are supported. However, the language server and `nextflow lint` will automatically convert them to Nextflow-style type annotations when formatting code. Groovy-style type annotations will not be supported in a future version.

	In the strict syntax, only hard casts are supported.
	Only hard casts are supported in the strict syntax.

	When casting a value to a different type, it is always better to use an explicit method if one is available. For example, to parse a string as a number:
	Always use an explicit method to cast a value to a different type if one is available. For example, to parse a string as a number:


		When converting a value to a different type, it is better to use an explicit method rather than a cast. For example, to parse a string as a number:
		In cases where a function returns an unknown type, use a type annotation:

	In cases where a function returns an unknown type, use a type annotation:
	Use a type annotation when a function returns an unknown type:

Type annotations #6278

Are you sure you want to change the base?

Type annotations #6278

Uh oh!

Conversation

bentsherman commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for nextflow-docs-staging ready!

Uh oh!

christopher-hakkaart left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bentsherman commented Jul 15, 2025 •

edited

Loading

netlify bot commented Jul 15, 2025 •

edited

Loading