Add intersection() function

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

@@ -0,0 +1,236 @@
+---
+description: Reference for the 'intersection' DSC configuration document function
+ms.date:     09/26/2025
+ms.topic:    reference
+title:       intersection
+---
+
+## Synopsis
+
+Returns a single array or object with the common elements from the parameters.
+
+## Syntax
+
+```Syntax
+intersection(value1, value2, ...)
+```
+
+## Description
+
+The `intersection()` function takes two or more arrays or objects and returns
+only the elements that exist in all of them. For arrays, it returns elements
+that appear in every array. For objects, it returns key-value pairs where both
+the key and value match across all objects.
+
+All parameters must be the same type - either all arrays or all objects.
+Results are deduplicated, meaning each element appears only once in the output.
+
+Supported types:
+
+- Arrays (elements compared by value)
+- Objects (key-value pairs compared by deep equality)
+
+## Examples
+
+### Example 1 - Find common security groups across environments (arrays)
+
+Use `intersection()` to identify security groups that are consistently applied
+across development, staging, and production environments. This helps ensure
+security policies are uniformly enforced. This example uses
+[`createArray()`][01] to build the security group lists.
+
+```yaml
+# intersection.example.1.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+- name: Common Security Groups
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      commonGroups: "[intersection(createArray('admin-access', 'monitoring', 'backup'), createArray('monitoring', 'backup', 'web-access'), createArray('backup', 'monitoring', 'database'))]"
+      twoEnvCommon: "[intersection(createArray('admin-access', 'monitoring'), createArray('monitoring', 'audit-log'))]"
+```
+
+```bash
+dsc config get --file intersection.example.1.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Common Security Groups
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        commonGroups:
+        - monitoring
+        - backup
+        twoEnvCommon:
+        - monitoring
+messages: []
+hadErrors: false
+```
+
+### Example 2 - Identify shared configuration properties (objects)
+
+Find configuration settings that are identical across multiple service
+instances. This is useful for extracting common configuration into shared
+templates or validating consistency. This example uses [`createObject()`][02]
+to build configuration objects.
+
+```yaml
+# intersection.example.2.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+- name: Shared Config Properties
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      commonSettings: "[intersection(createObject('timeout', 30, 'retries', 3, 'region', 'us-east'), createObject('retries', 3, 'ssl', true, 'region', 'us-east'), createObject('region', 'us-east', 'retries', 3, 'logging', 'info'))]"
+```
+
+```bash
+dsc config get --file intersection.example.2.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Shared Config Properties
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        commonSettings:
+          region: us-east
+          retries: 3
+messages: []
+hadErrors: false
+```
+
+### Example 3 - Find overlapping server capabilities (arrays with no matches)
+
+Sometimes environments have no common elements, which is valuable information
+for infrastructure planning. This example shows how `intersection()` handles
+arrays with no shared elements.
+
+```yaml
+# intersection.example.3.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+- name: Server Capabilities
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      noOverlap: "[intersection(createArray('windows-iis', 'dotnet-core'), createArray('linux-apache', 'php', 'mysql'))]"
+      someOverlap: "[intersection(createArray('docker', 'kubernetes', 'monitoring'), createArray('monitoring', 'logging', 'docker'))]"
+```
+
+```bash
+dsc config get --file intersection.example.3.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Server Capabilities
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        noOverlap: []
+        someOverlap:
+        - docker
+        - monitoring
+messages: []
+hadErrors: false
+```
+
+### Example 4 - Validate compliance across teams (objects)
+
+Use `intersection()` to verify that critical compliance settings are identical
+across different team configurations. Only settings with matching values will
+appear in the result.
+
+```yaml
+# intersection.example.4.dsc.config.yaml
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+- name: Compliance Check
+  type: Microsoft.DSC.Debug/Echo
+  properties:
+    output:
+      sharedCompliance: "[intersection(createObject('encryption', true, 'backup', 'daily', 'audit', true), createObject('audit', true, 'encryption', true, 'access', 'restricted'), createObject('encryption', true, 'audit', true, 'monitoring', 'enabled'))]"
+```
+
+```bash
+dsc config get --file intersection.example.4.dsc.config.yaml
+```
+
+```yaml
+results:
+- name: Compliance Check
+  type: Microsoft.DSC.Debug/Echo
+  result:
+    actualState:
+      output:
+        sharedCompliance:
+          audit: true
+          encryption: true
+messages: []
+hadErrors: false
+```
+
+## Parameters
+
+### value1
+
+The first array or object to compare. Required.
+
+```yaml
+Type:     array | object
+Required: true
+Position: 1
+```
+
+### value2
+
+The second array or object to compare. Must be the same type as value1.
+Required.
+
+```yaml
+Type:     array | object
+Required: true
+Position: 2
+```
+
+### Additional values
+
+Additional arrays or objects to include in the intersection. All must be the
+same type. Optional.
+
+```yaml
+Type:     array | object
+Required: false
+Position: 3+
+```
+
+## Output
+
+Returns an array or object containing only the common elements. The return type
+matches the input type.
+
+```yaml
+Type: array | object
+```
+
+## Related functions
+
+- [`union()`][00] - Combines all elements from multiple arrays or objects
+- [`contains()`][03] - Checks for presence in arrays/objects/strings
+- [`createArray()`][01] - Creates an array from individual values
+- [`createObject()`][02] - Creates an object from key-value pairs
+
+<!-- Link reference definitions -->
+[00]: ./union.md
+[01]: ./createArray.md
+[02]: ./createObject.md
+[03]: ./contains.md

dsc/tests/dsc_functions.tests.ps1

@@ -111,6 +111,125 @@ Describe 'tests for function expressions' {
     }
   }
 
+  It 'intersection function works for: <expression>' -TestCases @(
+    @{ expression = "[intersection(parameters('firstArray'), parameters('secondArray'))]"; expected = @('cd') }
+    @{ expression = "[intersection(parameters('firstObject'), parameters('secondObject'))]"; expected = [pscustomobject]@{ two = 'b' } }
+    @{ expression = "[intersection(parameters('thirdArray'), parameters('fourthArray'))]"; expected = @('ef', 'gh') }
+    @{ expression = "[intersection(parameters('thirdObject'), parameters('fourthObject'))]"; expected = [pscustomobject]@{ three = 'd' } }
+    @{ expression = "[intersection(parameters('firstArray'), parameters('thirdArray'))]"; expected = @() }
+    @{ expression = "[intersection(parameters('firstObject'), parameters('firstArray'))]"; isError = $true }
+    @{ expression = "[intersection(parameters('firstArray'), parameters('secondArray'), parameters('fifthArray'))]"; expected = @('cd') }
+    @{ expression = "[intersection(parameters('firstObject'), parameters('secondObject'), parameters('sixthObject'))]"; expected = [pscustomobject]@{ two = 'b' } }
+    @{ expression = "[intersection(parameters('nestedObject1'), parameters('nestedObject2'))]"; expected = [pscustomobject]@{ 
+      shared = [pscustomobject]@{ value = 42; flag = $true }
+      level = 1
+    } }
+    @{ expression = "[intersection(parameters('nestedObject1'), parameters('nestedObject3'))]"; expected = [pscustomobject]@{ level = 1 } }
+    @{ expression = "[intersection(parameters('nestedObject1'), parameters('nestedObject2'), parameters('nestedObject4'))]"; expected = [pscustomobject]@{ level = 1 } }
+  ) {
+    param($expression, $expected, $isError)
+
+    $config_yaml = @"
+            `$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+            parameters:
+              firstObject:
+                type: object
+                defaultValue:
+                  one: a
+                  two: b
+              secondObject:
+                type: object
+                defaultValue:
+                  two: b
+                  three: d
+              thirdObject:
+                type: object
+                defaultValue:
+                  two: c
+                  three: d
+              fourthObject:
+                type: object
+                defaultValue:
+                  three: d
+                  four: e
+              sixthObject:
+                type: object
+                defaultValue:
+                  two: b
+                  five: f
+              nestedObject1:
+                type: object
+                defaultValue:
+                  shared:
+                    value: 42
+                    flag: true
+                  level: 1
+                  unique1: test
+              nestedObject2:
+                type: object
+                defaultValue:
+                  shared:
+                    value: 42
+                    flag: true
+                  level: 1
+                  unique2: test
+              nestedObject3:
+                type: object
+                defaultValue:
+                  shared:
+                    value: 24
+                    flag: true
+                  level: 1
+                  unique3: test
+              nestedObject4:
+                type: object
+                defaultValue:
+                  level: 1
+                  different:
+                    value: 100
+                    flag: false
+              firstArray:
+                type: array
+                defaultValue:
+                - ab
+                - cd
+              secondArray:
+                type: array
+                defaultValue:
+                - cd
+                - ef
+              thirdArray:
+                type: array
+                defaultValue:
+                - ef
+                - gh
+              fourthArray:
+                type: array
+                defaultValue:
+                - gh
+                - ef
+                - ij
+              fifthArray:
+                type: array
+                defaultValue:
+                - cd
+                - kl
+            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
+    if ($isError) {
+      $LASTEXITCODE | Should -Be 2 -Because (Get-Content $TestDrive/error.log -Raw)
+      (Get-Content $TestDrive/error.log -Raw) | Should -Match 'All arguments must either be arrays or objects'
+    } else {
+      $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 'contain function works for: <expression>' -TestCases @(
     @{ expression = "[contains(parameters('array'), 'a')]" ; expected = $true }
     @{ expression = "[contains(parameters('array'), 2)]" ; expected = $false }

dsc_lib/locales/en-us.toml

@@ -353,6 +353,11 @@ parseStringError = "unable to parse string to int"
 castError = "unable to cast to int"
 parseNumError = "unable to parse number to int"
 
+[functions.intersection]
+description = "Returns a single array or object with the common elements from the parameters"
+invoked = "intersection function"
+invalidArgType = "All arguments must either be arrays or objects"
+
 [functions.indexOf]
 description = "Returns the index of the first occurrence of an item in an array"
 invoked = "indexOf function"