Type annotations

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

Author: bentsherman

docs/migrations/25-10.md

@@ -8,6 +8,55 @@ This page summarizes the upcoming changes in Nextflow 25.10, which will be relea
 This page is a work in progress and will be updated as features are finalized. It should not be considered complete until the 25.10 release.
 :::
 
+## New features
+
+<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.
+
+```nextflow
+workflow RNASEQ {
+  take:
+  reads: Channel<Path>
+  index: Channel<Path>
+
+  main:
+  samples_ch = QUANT( reads.combine(index) )
+
+  emit:
+  samples: Channel<Path> = samples_ch
+}
+
+def isSraId(id: String) -> Boolean {
+  return id.startsWith('SRA')
+}
+```
+
+The following declarations can be annotated with types:
+
+- Pipeline parameters (the `params` block)
+- Workflow takes and emits
+- Function parameters and returns
+- Local variables
+- Closure parameters
+- Workflow outputs (the `output` block)
+
+Type annotations can refer to any of the {ref}`standard types <stdlib-types>` as well as the following primitive types:
+
+- Boolean
+- Integer
+- Number
+
+Type annotations can be appended with `?` to denote that the value can be `null`:
+
+```nextflow
+def x_opt: String? = null
+```
+
+:::{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`.
+:::
+
 ## Breaking changes
 
 - The AWS Java SDK used by Nextflow was upgraded from v1 to v2, which introduced some breaking changes to the `aws.client` config options. See {ref}`the guide <aws-java-sdk-v2-page>` for details.

docs/reference/stdlib-types.md

@@ -36,20 +36,20 @@ See {ref}`channel-page` for an overview of channels. See {ref}`channel-factory`
 
 A Duration represents a duration of time with millisecond precision.
 
-A Duration can be created by adding a unit suffix to an integer (e.g. `1.h`), or more explicitly with `Duration.of()`:
+A Duration can be created by adding a unit suffix to an integer (e.g. `1.h`), or by explicitly casting to `Duration`:
 
 ```nextflow
 // integer with suffix
 oneDay = 24.h
 
 // integer value (milliseconds)
-oneSecond = Duration.of(1000)
+oneSecond = 1000 as Duration
 
 // simple string value
-oneHour = Duration.of('1h')
+oneHour = '1h' as Duration
 
 // complex string value
-complexDuration = Duration.of('1day 6hours 3minutes 30seconds')
+complexDuration = '1day 6hours 3minutes 30seconds' as Duration
 ```
 
 The following suffixes are available:
@@ -352,17 +352,17 @@ Maps in Nextflow are backed by the [Java](https://docs.oracle.com/en/java/javase
 
 A MemoryUnit represents a quantity of bytes.
 
-A MemoryUnit can be created by adding a unit suffix to an integer (e.g. `1.GB`), or more explicitly with `MemoryUnit.of()`:
+A MemoryUnit can be created by adding a unit suffix to an integer (e.g. `1.GB`), or by explicitly casting to `MemoryUnit`:
 
 ```nextflow
 // integer with suffix
 oneMegabyte = 1.MB
 
 // integer value (bytes)
-oneKilobyte = MemoryUnit.of(1024)
+oneKilobyte = 1024 as MemoryUnit
 
 // string value
-oneGigabyte = MemoryUnit.of('1 GB')
+oneGigabyte = '1 GB' as MemoryUnit
 ```
 
 The following suffixes are available:

docs/strict-syntax.md

@@ -299,10 +299,22 @@ def str = 'hello'
 def meta = [:]
 ```
 
-:::{note}
-Because type annotations are useful for providing type checking at runtime, the language server will not report errors for Groovy-style type annotations at this time. Type annotations will be addressed in a future version of the Nextflow language specification.
+:::{versionadded} 25.10.0
 :::
 
+Local variables can be declared with a type annotation:
+
+```nextflow
+def a: Integer = 1
+def b: Integer = 2
+def (c: Integer, d: Integer) = [3, 4]
+def (e: Integer, f: Integer) = [5, 6]
+def str: String = 'hello'
+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.
+
 ### Strings
 
 Groovy supports a wide variety of strings, including multi-line strings, dynamic strings, slashy strings, multi-line dynamic slashy strings, and more.
@@ -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.
+
+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:
 
 ```groovy
-def Map map = readJson(json)
+def x = '42' as Integer
+def x = '42'.toInteger()    // preferred
 ```
 
-Nextflow will raise an error at runtime if the `readJson()` function does not return a `Map`.
+:::{versionadded} 25.10.0
+:::
 
-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:
 
 ```groovy
-def x = '42' as Integer
-def x = '42'.toInteger()    // preferred
+def map: Map = readJson(json)
 ```
 
+Nextflow will raise an error at runtime if the `readJson()` function does not return a `Map`.
+
 ### Process env inputs and outputs
 
 In Nextflow DSL2, the name of a process `env` input/output can be specified with or without quotes:

modules/nextflow/src/main/groovy/nextflow/script/parser/v2/ScriptCompiler.java

@@ -68,7 +68,8 @@ public class ScriptCompiler {
         "java.nio.file.Path",
         "nextflow.Channel",
         "nextflow.util.Duration",
-        "nextflow.util.MemoryUnit"
+        "nextflow.util.MemoryUnit",
+        "nextflow.util.VersionNumber"
     );
     private static final String MAIN_CLASS_NAME = "Main";
     private static final String BASE_CLASS_NAME = "nextflow.script.BaseScript";

modules/nextflow/src/main/groovy/nextflow/util/ArrayBag.groovy

@@ -15,11 +15,13 @@
  */
 
 package nextflow.util
+
 import com.esotericsoftware.kryo.Kryo
 import com.esotericsoftware.kryo.KryoSerializable
 import com.esotericsoftware.kryo.io.Input
 import com.esotericsoftware.kryo.io.Output
 import groovy.transform.CompileStatic
+import nextflow.script.types.Bag
 import org.codehaus.groovy.runtime.InvokerHelper
 
 /**

modules/nf-commons/build.gradle

@@ -25,6 +25,7 @@ sourceSets {
 }
 
 dependencies {
+    api(project(':nf-lang'))
     api "ch.qos.logback:logback-classic:1.5.18"
     api "org.apache.groovy:groovy:4.0.27"
     api "org.apache.groovy:groovy-nio:4.0.27"

modules/nf-commons/src/main/nextflow/util/Duration.groovy

@@ -22,6 +22,7 @@ import java.util.concurrent.TimeUnit
 import groovy.transform.CompileStatic
 import groovy.transform.EqualsAndHashCode
 import groovy.util.logging.Slf4j
+import nextflow.script.types.Duration as IDuration
 import org.apache.commons.lang.time.DurationFormatUtils
 /**
  * A simple time duration representation
@@ -31,7 +32,7 @@ import org.apache.commons.lang.time.DurationFormatUtils
 @Slf4j
 @CompileStatic
 @EqualsAndHashCode(includes = 'durationInMillis')
-class Duration implements Comparable<Duration>, Serializable, Cloneable {
+class Duration implements IDuration, Comparable<Duration>, Serializable, Cloneable {
 
     static private final FORMAT = ~/^(\d+\.?\d*)\s*([a-zA-Z]+)/
 
@@ -215,6 +216,7 @@ class Duration implements Comparable<Duration>, Serializable, Cloneable {
         new Duration(java.time.Duration.between(start, end).toMillis())
     }
 
+    @Override
     long toMillis() {
         durationInMillis
     }
@@ -223,6 +225,7 @@ class Duration implements Comparable<Duration>, Serializable, Cloneable {
         durationInMillis
     }
 
+    @Override
     long toSeconds() {
         TimeUnit.MILLISECONDS.toSeconds(durationInMillis)
     }
@@ -231,6 +234,7 @@ class Duration implements Comparable<Duration>, Serializable, Cloneable {
         toSeconds()
     }
 
+    @Override
     long toMinutes() {
         TimeUnit.MILLISECONDS.toMinutes(durationInMillis)
     }
@@ -239,6 +243,7 @@ class Duration implements Comparable<Duration>, Serializable, Cloneable {
         toMinutes()
     }
 
+    @Override
     long toHours() {
         TimeUnit.MILLISECONDS.toHours(durationInMillis)
     }
@@ -247,6 +252,7 @@ class Duration implements Comparable<Duration>, Serializable, Cloneable {
         toHours()
     }
 
+    @Override
     long toDays() {
         TimeUnit.MILLISECONDS.toDays(durationInMillis)
     }

modules/nf-commons/src/main/nextflow/util/HashBuilder.java

@@ -46,6 +46,7 @@
 import nextflow.extension.FilesEx;
 import nextflow.file.FileHolder;
 import nextflow.io.SerializableMarker;
+import nextflow.script.types.Bag;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 

modules/nf-commons/src/main/nextflow/util/MemoryUnit.groovy

@@ -22,14 +22,15 @@ import java.util.regex.Pattern
 
 import groovy.transform.CompileStatic
 import groovy.transform.EqualsAndHashCode
+import nextflow.script.types.MemoryUnit as IMemoryUnit
 /**
  * Represent a memory unit
  *
  * @author Paolo Di Tommaso <[email protected]>
  */
 @CompileStatic
 @EqualsAndHashCode(includes = 'size', includeFields = true)
-class MemoryUnit implements Comparable<MemoryUnit>, Serializable, Cloneable {
+class MemoryUnit implements IMemoryUnit, Comparable<MemoryUnit>, Serializable, Cloneable {
 
     final static public MemoryUnit ZERO = new MemoryUnit(0)
 
@@ -95,20 +96,24 @@ class MemoryUnit implements Comparable<MemoryUnit>, Serializable, Cloneable {
 
     }
 
+    @Override
     long toBytes() {
         size
     }
 
     long getBytes() { size }
 
+    @Override
     long toKilo() { size >> 10 }
 
     long getKilo() { size >> 10 }
 
+    @Override
     long toMega() { size >> 20 }
 
     long getMega() { size >> 20 }
 
+    @Override
     long toGiga() { size >> 30 }
 
     long getGiga() { size >> 30 }
@@ -181,6 +186,7 @@ class MemoryUnit implements Comparable<MemoryUnit>, Serializable, Cloneable {
      *
      * @param unit String expressing memory unit in bytes, e.g. KB, MB, GB
      */
+    @Override
     long toUnit(String unit){
         int p = UNITS.indexOf(unit)
         if (p==-1)

modules/nf-commons/src/main/nextflow/util/VersionNumber.groovy

@@ -20,14 +20,15 @@ import java.util.regex.Pattern
 
 import groovy.transform.CompileStatic
 import nextflow.extension.Bolts
+import nextflow.script.types.VersionNumber as IVersionNumber
 
 /**
  * Model a semantic version number
  *
  * @author Paolo Di Tommaso <[email protected]>
  */
 @CompileStatic
-class VersionNumber implements Comparable {
+class VersionNumber implements IVersionNumber, Comparable {
 
     static private Pattern CHECK = ~/\s*([!<=>]+)?\s*([0-9A-Za-z\-_\.]+)(\+)?/
 
@@ -62,16 +63,19 @@ class VersionNumber implements Comparable {
     /**
      * @return The major version number ie. the first component
      */
+    @Override
     String getMajor() { version[0] }
 
     /**
      * @return The minor version number ie. the second component
      */
+    @Override
     String getMinor() { version[1] }
 
     /**
      * @return The minor version number ie. the third component
      */
+    @Override
     String getPatch() { version[2] }
 
     /**
@@ -177,6 +181,7 @@ class VersionNumber implements Comparable {
      * @param condition
      * @return
      */
+    @Override
     boolean matches(String condition) {
         for( String token : condition.tokenize(',')) {
             if( !matches0(token) )