Type annotations for params

Signed-off-by: Ben Sherman <bentshermann@gmail.com>

Author: bentsherman

docs/migrations/25-10.md

@@ -8,6 +8,31 @@ 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>Workflow params</h3>
+
+The `params` block is a new way to declare pipeline parameters in a Nextflow script:
+
+```nextflow
+params {
+  // Path to input data.
+  input: Path
+
+  // Whether to save intermediate files.
+  save_intermeds: Boolean = false
+}
+
+workflow {
+  println "params.input = ${params.input}"
+  println "params.save_intermeds = ${params.save_intermeds}"
+}
+```
+
+This syntax allows you to declare all parameters in one place and allows Nextflow to validate them at runtime.
+
+See {ref}`workflow-params-def` for details.
+
 ## 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/syntax.md

@@ -114,8 +114,8 @@ The params block consists of one or more *parameter declarations*. A parameter d
 
 ```nextflow
 params {
-    input
-    save_intermeds = false
+    input: Path
+    save_intermeds: Boolean = false
 }
 ```
 

docs/workflow.md

@@ -22,6 +22,8 @@ workflow {
 }
 ```
 
+(workflow-params-def)=
+
 ## Parameters
 
 Parameters can be declared in a Nextflow script with the `params` block or with *legacy* parameter declarations.
@@ -42,15 +44,23 @@ params {
     /**
      * Path to input data.
      */
-    input
+    input: Path
 
     /**
      * Whether to save intermediate files.
      */
-    save_intermeds = false
+    save_intermeds: Boolean = false
 }
 ```
 
+The following types can be used for parameters:
+
+- Boolean
+- Integer
+- Number
+- {ref}`stdlib-types-path`
+- {ref}`stdlib-types-string`
+
 Parameters can be used in the entry workflow:
 
 ```nextflow

modules/nextflow/src/main/groovy/nextflow/script/ParamsDsl.groovy

@@ -16,10 +16,15 @@
 
 package nextflow.script
 
+import java.nio.file.Path
+
+import groovy.transform.Canonical
 import groovy.transform.CompileStatic
 import groovy.util.logging.Slf4j
 import nextflow.Session
+import nextflow.file.FileHelper
 import nextflow.exception.ScriptRuntimeException
+import nextflow.script.types.Types
 /**
  * Implements the DSL for defining workflow params
  *
@@ -29,14 +34,14 @@ import nextflow.exception.ScriptRuntimeException
 @CompileStatic
 class ParamsDsl {
 
-    private Map<String,Optional<?>> declarations = [:]
+    private Map<String,Param> declarations = [:]
 
-    void declare(String name) {
-        declarations[name] = Optional.empty()
+    void declare(String name, Class type) {
+        declarations[name] = new Param(name, type, Optional.empty())
     }
 
-    void declare(String name, Object defaultValue) {
-        declarations[name] = Optional.of(defaultValue)
+    void declare(String name, Class type, Object defaultValue) {
+        declarations[name] = new Param(name, type, Optional.of(defaultValue))
     }
 
     void apply(Session session) {
@@ -50,18 +55,70 @@ class ParamsDsl {
 
         final params = new HashMap<String,?>()
         for( final name : declarations.keySet() ) {
-            final defaultValue = declarations[name]
+            final decl = declarations[name]
             if( cliParams.containsKey(name) )
-                params[name] = cliParams[name]
+                params[name] = resolveFromCli(decl, cliParams[name])
             else if( configParams.containsKey(name) )
-                params[name] = configParams[name]
-            else if( defaultValue.isPresent() )
-                params[name] = defaultValue.get()
+                params[name] = resolveFromCode(decl, configParams[name])
+            else if( decl.defaultValue.isPresent() )
+                params[name] = resolveFromCode(decl, decl.defaultValue.get())
             else
                 throw new ScriptRuntimeException("Parameter `$name` is required but was not specified on the command line, params file, or config")
+
+            final actualType = params[name].getClass()
+            if( !Types.isAssignableFrom(decl.type, actualType) )
+                throw new ScriptRuntimeException("Parameter `$name` with type ${Types.getName(decl.type)} cannot be assigned to ${params[name]} [${Types.getName(actualType)}]")
         }
 
         session.binding.setParams(params)
     }
 
+    private Object resolveFromCli(Param decl, Object value) {
+        if( value == null )
+            return null
+
+        if( value !instanceof CharSequence )
+            return value
+
+        final str = value.toString()
+
+        if( decl.type == Boolean ) {
+            if( str.toLowerCase() == 'true' ) return Boolean.TRUE
+            if( str.toLowerCase() == 'false' ) return Boolean.FALSE
+        }
+
+        if( decl.type == Integer || decl.type == Number ) {
+            if( str.isInteger() ) return str.toInteger()
+            if( str.isLong() ) return str.toLong()
+        }
+
+        if( decl.type == Number ) {
+            if( str.isFloat() ) return str.toFloat()
+            if( str.isDouble() ) return str.toDouble()
+        }
+
+        if( decl.type == Path ) {
+            return FileHelper.asPath(str)
+        }
+
+        return value
+    }
+
+    private Object resolveFromCode(Param decl, Object value) {
+        if( value == null )
+            return null
+
+        if( decl.type == Path && value instanceof CharSequence )
+            return FileHelper.asPath(value.toString())
+
+        return value
+    }
+
+    @Canonical
+    private static class Param {
+        String name
+        Class type
+        Optional<?> defaultValue
+    }
+
 }

modules/nextflow/src/test/groovy/nextflow/script/ParamsDslTest.groovy

@@ -1,6 +1,9 @@
 package nextflow.script
 
+import java.nio.file.Path
+
 import nextflow.Session
+import nextflow.file.FileHelper
 import nextflow.exception.ScriptRuntimeException
 import spock.lang.Specification
 /**
@@ -18,11 +21,11 @@ class ParamsDslTest extends Specification {
 
         when:
         def dsl = new ParamsDsl()
-        dsl.declare('input')
-        dsl.declare('save_intermeds', false)
+        dsl.declare('input', Path)
+        dsl.declare('save_intermeds', Boolean, false)
         dsl.apply(session)
         then:
-        session.binding.getParams() == [input: './data', save_intermeds: false]
+        session.binding.getParams() == [input: FileHelper.asPath('./data'), save_intermeds: false]
     }
 
     def 'should report error for missing required param'() {
@@ -34,8 +37,8 @@ class ParamsDslTest extends Specification {
 
         when:
         def dsl = new ParamsDsl()
-        dsl.declare('input')
-        dsl.declare('save_intermeds', false)
+        dsl.declare('input', Path)
+        dsl.declare('save_intermeds', Boolean, false)
         dsl.apply(session)
         then:
         def e = thrown(ScriptRuntimeException)
@@ -51,12 +54,29 @@ class ParamsDslTest extends Specification {
 
         when:
         def dsl = new ParamsDsl()
-        dsl.declare('input')
-        dsl.declare('save_intermeds', false)
+        dsl.declare('input', Path)
+        dsl.declare('save_intermeds', Boolean, false)
         dsl.apply(session)
         then:
         def e = thrown(ScriptRuntimeException)
         e.message == 'Parameter `inputs` was specified on the command line or params file but is not declared in the script or config'
     }
 
+    def 'should report error for invalid type'() {
+        given:
+        def cliParams = [input: './data', save_intermeds: 42]
+        def configParams = [:]
+        def session = new Session()
+        session.init(null, null, cliParams, configParams)
+
+        when:
+        def dsl = new ParamsDsl()
+        dsl.declare('input', Path)
+        dsl.declare('save_intermeds', Boolean, false)
+        dsl.apply(session)
+        then:
+        def e = thrown(ScriptRuntimeException)
+        e.message == 'Parameter `save_intermeds` with type Boolean cannot be assigned to 42 [Integer]'
+    }
+
 }

modules/nf-lang/src/main/antlr/ScriptParser.g4

@@ -160,7 +160,7 @@ paramsBody
     ;
 
 paramDeclaration
-    :   identifier (ASSIGN expression)?
+    :   identifier (COLON type)? (ASSIGN expression)?
     |   statement
     ;
 

modules/nf-lang/src/main/java/nextflow/script/control/ScriptResolveVisitor.java

@@ -84,6 +84,7 @@ public void visit() {
     @Override
     public void visitParam(Parameter node) {
         node.setInitialExpression(resolver.transform(node.getInitialExpression()));
+        resolver.resolveOrFail(node.getType(), node);
     }
 
     @Override

modules/nf-lang/src/main/java/nextflow/script/control/ScriptToGroovyVisitor.java

@@ -124,9 +124,10 @@ public void visitParams(ParamBlockNode node) {
         var statements = Arrays.stream(node.declarations)
             .map((param) -> {
                 var name = constX(param.getName());
+                var type = classX(param.getType());
                 var arguments = param.hasInitialExpression()
-                    ? args(name, param.getInitialExpression())
-                    : args(name);
+                    ? args(name, type, param.getInitialExpression())
+                    : args(name, type);
                 return stmt(callThisX("declare", arguments));
             })
             .toList();

modules/nf-lang/src/main/java/nextflow/script/control/TypeCheckingVisitor.java

@@ -26,6 +26,7 @@
 import nextflow.script.types.Types;
 import org.codehaus.groovy.ast.ASTNode;
 import org.codehaus.groovy.ast.MethodNode;
+import org.codehaus.groovy.ast.Parameter;
 import org.codehaus.groovy.ast.Variable;
 import org.codehaus.groovy.ast.expr.BinaryExpression;
 import org.codehaus.groovy.ast.expr.DeclarationExpression;
@@ -83,6 +84,16 @@ public void visitFeatureFlag(FeatureFlagNode node) {
             addError("Type mismatch for feature flag '" + node.name + "' -- expected a " + Types.getName(expectedType) + " but received a " + Types.getName(actualType), node);
     }
 
+    @Override
+    public void visitParam(Parameter node) {
+        if( !node.hasInitialExpression() )
+            return;
+        var expectedType = node.getType();
+        var actualType = node.getInitialExpression().getType();
+        if( !Types.isAssignableFrom(expectedType, actualType) )
+            addError("Parameter '" + node.getName() + "' with type " + Types.getName(expectedType) + " cannot be assigned to default value with type " + Types.getName(actualType), node);
+    }
+
     // statements
 
     @Override

modules/nf-lang/src/main/java/nextflow/script/formatter/Formatter.java

@@ -24,6 +24,7 @@
 import org.codehaus.groovy.ast.ClassNode;
 import org.codehaus.groovy.ast.CodeVisitorSupport;
 import org.codehaus.groovy.ast.Parameter;
+import org.codehaus.groovy.ast.Variable;
 import org.codehaus.groovy.ast.expr.BinaryExpression;
 import org.codehaus.groovy.ast.expr.BitwiseNegationExpression;
 import org.codehaus.groovy.ast.expr.CastExpression;
@@ -713,6 +714,10 @@ private static boolean hasTrailingComma(Expression node) {
         return node.getNodeMetaData(ASTNodeMarker.TRAILING_COMMA) != null;
     }
 
+    public static boolean hasType(Variable variable) {
+        return !variable.isDynamicTyped() || isLegacyType(variable.getType());
+    }
+
     public static boolean isLegacyType(ClassNode cn) {
         return cn.getNodeMetaData(ASTNodeMarker.LEGACY_TYPE) != null;
     }