Typed processes

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

Author: bentsherman

docs/migrations/25-10.md

@@ -16,16 +16,16 @@ The `params` block is a new way to declare pipeline parameters in a Nextflow scr
 
 ```nextflow
 params {
-  // Path to input data.
-  input: Path
+    // Path to input data.
+    input: Path
 
-  // Whether to save intermediate files.
-  save_intermeds: Boolean = false
+    // Whether to save intermediate files.
+    save_intermeds: Boolean = false
 }
 
 workflow {
-  println "params.input = ${params.input}"
-  println "params.save_intermeds = ${params.save_intermeds}"
+    println "params.input = ${params.input}"
+    println "params.save_intermeds = ${params.save_intermeds}"
 }
 ```
 
@@ -39,19 +39,19 @@ Type annotations are a way to denote the *type* of a variable. They help documen
 
 ```nextflow
 workflow RNASEQ {
-  take:
-  reads: Channel<Path>
-  index: Value<Path>
+    take:
+    reads: Channel<Path>
+    index: Value<Path>
 
-  main:
-  samples_ch = QUANT( reads, index )
+    main:
+    samples_ch = QUANT( reads, index )
 
-  emit:
-  samples: Channel<Path> = samples_ch
+    emit:
+    samples: Channel<Path> = samples_ch
 }
 
 def isSraId(id: String) -> Boolean {
-  return id.startsWith('SRA')
+    return id.startsWith('SRA')
 }
 ```
 
@@ -78,6 +78,36 @@ In the type system, queue channels are represented as `Channel`, while value cha
 Nextflow supports Groovy-style type annotations using the `<type> <name>` syntax, but this approach is deprecated in {ref}`strict syntax <strict-syntax-page>`. While Groovy-style annotations remain valid for functions and local variables, the language server and `nextflow lint` automatically convert them to Nextflow-style annotations during code formatting.
 :::
 
+See {ref}`migrating-static-types` to get started.
+
+<h3>Typed processes</h3>
+
+Typed processes are a new way to define process inputs and outputs with type annotations:
+
+```nextflow
+process fastqc {
+    input:
+    id: String
+    fastq_1: Path
+    fastq_2: Path?
+
+    output:
+    logs = tuple(id, file('fastqc_logs'))
+
+    script:
+    """
+    mkdir fastqc_logs
+    fastqc -o fastqc_logs -f fastq -q ${fastq_1} ${fastq_2}
+    """
+}
+```
+
+The new `stage:` and `topic:` sections can be used to describe additional process-specific behaviors such as custom file names and topic emissions.
+
+Typed processes bring additional runtime improvements, such as support for nullable input and output files.
+
+See {ref}`migrating-static-types` for details.
+
 ## Enhancements
 
 <h3>Nextflow plugin registry</h3>
@@ -113,7 +143,7 @@ workflow {
 
 This syntax is simpler and easier to use with the {ref}`strict syntax <strict-syntax-page>`. See {ref}`workflow-handlers` for details.
 
-<h3>Improved handling of dynamic directives</h3>
+<h3>Simpler syntax for dynamic directives</h3>
 
 The {ref}`strict syntax <strict-syntax-page>` allows dynamic process directives to be specified without a closure:
 
@@ -131,6 +161,8 @@ process hello {
 }
 ```
 
+Dynamic process settings in configuration files must still be specified with closures.
+
 See {ref}`dynamic-directives` for details.
 
 <h3>Configurable date formatting</h3>

docs/reference/process.md

@@ -50,9 +50,55 @@ The following task properties are defined in the process body:
 
 Additionally, the [directive values](#directives) for the given task can be accessed via `task.<directive>`.
 
+(process-reference-typed)=
+
+## Typed inputs and outputs
+
+:::{versionadded} 25.10.0
+:::
+
+### Stage directives
+
+The following directives can be used in the `stage:` section of a typed process:
+
+`env( name: String, String value )`
+: Declare an environment variable in the task environment with the given name and value.
+
+`stageAs( filePattern: String, value: Path )`
+: Stage a file into the task directory under the given alias.
+
+`stageAs( filePattern: String, value: Set<Path> )`
+: Stage a collection of files into the task directory under the given alias.
+
+`stdin( value: String )`
+: Stage the given value as the standard input (i.e. `stdin`) to the task script.
+
+### Outputs
+
+The following functions are available in the `output:` and `topic:` sections of a typed process:
+
+`env( name: String ) -> String`
+: Get the value of an environment variable from the task environment.
+
+`eval( command: String ) -> String`
+: Get the standard output of the given command, which is executed in the task environment after the task script.
+
+`file( name: String, [options] ) -> Path`
+: Get a file from the task environment that matches the given pattern.
+
+`files( pattern: String, [options] ) -> Set<Path>`
+: Get the files from the task environment that match the given pattern.
+
+`stdout() -> String`
+: Get the standard output of the task script.
+
+(process-reference-legacy)=
+
+## Legacy inputs and outputs
+
 (process-reference-inputs)=
 
-## Inputs
+### Inputs
 
 `val( identifier )`
 
@@ -103,7 +149,7 @@ Additionally, the [directive values](#directives) for the given task can be acce
 
 (process-reference-outputs)=
 
-## Outputs
+### Outputs
 
 `val( value )`