Add join() function

Author: Gijsreyn

docs/reference/schemas/config/functions/join.md

@@ -0,0 +1,122 @@
+---
+description: Reference for the 'join' DSC configuration document function
+ms.date:     08/29/2025
+ms.topic:    reference
+title:       join
+---
+
+## Synopsis
+
+Joins a string array into a single string, separated using a delimiter.
+
+## Syntax
+
+```Syntax
+join(inputArray, delimiter)
+```
+
+## Description
+
+The `join()` function takes either an array or a string and a delimiter.
+
+- If `inputArray` is an array, each element is converted to a string and
+  concatenated with the delimiter between elements.
+- If `inputArray` is a string, its characters are joined with the delimiter
+  between each character.
+
+The `delimiter` can be any value; it is converted to a string.
+
+## Examples
+
+### Example 1 - Join array of strings
+
+```yaml
+# join.example.1.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+- name: Echo
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output: "[join(createArray('a','b','c'), '-')]"
+```
+
+```bash
+dsc config get --file join.example.1.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Echo
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output: a-b-c
+messages: []
+hadErrors: false
+```
+
+### Example 2 - Join characters of a string
+
+```yaml
+# join.example.2.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+- name: Echo
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output: "[join('abc', '-')]"
+```
+
+```bash
+dsc config get --file join.example.2.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Echo
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output: a-b-c
+messages: []
+hadErrors: false
+```
+
+## Parameters
+
+### inputArray
+
+An array or a string.
+
+```yaml
+Type:     array | string
+Required: true
+Position: 1
+```
+
+### delimiter
+
+Any value used between elements/characters. Converted to a string.
+
+```yaml
+Type:     any
+Required: true
+Position: 2
+```
+
+## Output
+
+Returns a string containing the joined result.
+
+```yaml
+Type: string
+```
+
+## Related functions
+
+- [`concat()`][00] - Concatenates strings together
+- [`string()`][01] - Converts values to strings
+
+<!-- Link reference definitions -->
+[00]: ./concat.md
+[01]: ./string.md

dsc/tests/dsc_functions.tests.ps1

@@ -408,4 +408,25 @@ Describe 'tests for function expressions' {
     $LASTEXITCODE | Should -Be 0 -Because (Get-Content $TestDrive/error.log -Raw)
     ($out.results[0].result.actualState.output | Out-String) | Should -BeExactly ($expected | Out-String)
   }
+
+  It 'join function works for: <expression>' -TestCases @(
+    @{ expression = "[join(createArray('a','b','c'), '-')]"; expected = 'a-b-c' }
+    @{ expression = "[join('abc', '-')]"; expected = 'a-b-c' }
+    @{ expression = "[join(createArray(), '-')]"; expected = '' }
+    @{ expression = "[join('', '-')]"; expected = '' }
+  ) {
+    param($expression, $expected)
+
+    $config_yaml = @"
+            `$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+            resources:
+            - name: Echo
+              type: Microsoft.DSC.Debug/Echo
+              properties:
+                output: "$expression"
+"@
+    $out = dsc -l trace config get -i $config_yaml 2>$TestDrive/error.log | ConvertFrom-Json
+    $LASTEXITCODE | Should -Be 0 -Because (Get-Content $TestDrive/error.log -Raw)
+    ($out.results[0].result.actualState.output | Out-String) | Should -BeExactly ($expected | Out-String)
+  }
 }

dsc_lib/locales/en-us.toml

@@ -323,6 +323,11 @@ description = "Returns the index of the first occurrence of an item in an array"
 invoked = "indexOf function"
 invalidArrayArg = "First argument must be an array"
 
+[functions.join]
+description = "Joins a string array into a single string, separated using a delimiter."
+invoked = "join function"
+invalidInputType = "The inputArray must be an array or a string."
+
 [functions.length]
 description = "Returns the length of a string, array, or object"
 invoked = "length function"

dsc_lib/src/functions/join.rs

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+use crate::DscError;
+use crate::configure::context::Context;
+use crate::functions::{FunctionArgKind, Function, FunctionCategory, FunctionMetadata};
+use rust_i18n::t;
+use serde_json::Value;
+use tracing::debug;
+
+#[derive(Debug, Default)]
+pub struct Join {}
+
+fn stringify_value(v: &Value) -> String {
+    if let Some(s) = v.as_str() { return s.to_string(); }
+    if let Some(n) = v.as_i64() { return n.to_string(); }
+    if let Some(b) = v.as_bool() { return b.to_string(); }
+    if v.is_null() { return "null".to_string(); }
+    // Fallback to JSON for arrays/objects or other numbers
+    serde_json::to_string(v).unwrap_or_default()
+}
+
+impl Function for Join {
+    fn get_metadata(&self) -> FunctionMetadata {
+        FunctionMetadata {
+            name: "join".to_string(),
+            description: t!("functions.join.description").to_string(),
+            category: FunctionCategory::String,
+            min_args: 2,
+            max_args: 2,
+            accepted_arg_ordered_types: vec![
+                vec![FunctionArgKind::Array, FunctionArgKind::String],
+                // delimiter: accept any type (no validation), convert to string
+                vec![
+                    FunctionArgKind::Array,
+                    FunctionArgKind::Boolean,
+                    FunctionArgKind::Null,
+                    FunctionArgKind::Number,
+                    FunctionArgKind::Object,
+                    FunctionArgKind::String,
+                ],
+            ],
+            remaining_arg_accepted_types: None,
+            return_types: vec![FunctionArgKind::String],
+        }
+    }
+
+    fn invoke(&self, args: &[Value], _context: &Context) -> Result<Value, DscError> {
+        debug!("{}", t!("functions.join.invoked"));
+
+        let delimiter = stringify_value(&args[1]);
+
+        if let Some(array) = args[0].as_array() {
+            let items: Vec<String> = array.iter().map(stringify_value).collect();
+            return Ok(Value::String(items.join(&delimiter)));
+        }
+
+        if let Some(s) = args[0].as_str() {
+            // Edge case: empty string => empty string
+            if s.is_empty() { return Ok(Value::String(String::new())); }
+            let items: Vec<String> = s.chars().map(|c| c.to_string()).collect();
+            return Ok(Value::String(items.join(&delimiter)));
+        }
+
+        Err(DscError::Parser(t!("functions.join.invalidInputType").to_string()))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::configure::context::Context;
+    use crate::parser::Statement;
+
+    #[test]
+    fn join_array_of_strings() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[join(createArray('a','b','c'), '-')]", &Context::new()).unwrap();
+        assert_eq!(result, "a-b-c");
+    }
+
+    #[test]
+    fn join_string_chars() {
+        let mut parser = Statement::new().unwrap();
+        let result = parser.parse_and_execute("[join('abc', '-')]", &Context::new()).unwrap();
+        assert_eq!(result, "a-b-c");
+    }
+}

dsc_lib/src/functions/mod.rs

@@ -37,6 +37,7 @@ pub mod less_or_equals;
 pub mod format;
 pub mod int;
 pub mod index_of;
+pub mod join;
 pub mod max;
 pub mod min;
 pub mod mod_function;
@@ -146,6 +147,7 @@ impl FunctionDispatcher {
             Box::new(format::Format{}),
             Box::new(int::Int{}),
             Box::new(index_of::IndexOf{}),
+            Box::new(join::Join{}),
             Box::new(max::Max{}),
             Box::new(min::Min{}),
             Box::new(mod_function::Mod{}),