Feature DQL first non-null value of a list (#2543)

To be used in conjunction with defining inline fields in sublists/-tasks, and/or just to extract the first non-null value of any given list.

Author: holroy

Diff for: docs/docs/reference/functions.md

@@ -432,6 +432,15 @@ nonnull([null, false]) = [false]
 nonnull([1, 2, 3]) = [1, 2, 3]
 ```
 
+### `firstvalue(array)`
+
+Return the first non-null value from the array, as a single element. This can be used to pick the first defined field in the children of a task/list item, like in `firstvalue(children.myField)`.
+
+```js
+firstvalue([null, 1, 2]) => 1
+firstvalue(children.myField) => If children.myField equals [null, null, "myValue", null], it would return "myValue"
+```
+
 ### `all(array)`
 
 Returns `true` only if ALL values in the array are truthy. You can also pass multiple arguments to this function, in

Diff for: src/expression/functions.ts

@@ -878,6 +878,16 @@ export namespace DefaultFunctions {
         })
         .add1("null", () => null)
         .build();
+
+    // Returns the first non-null value from the array as a single element
+    export const firstvalue = new FunctionBuilder("firstvalue")
+        .add1("array", a => {
+            let nonnull = a.filter(v => Values.typeOf(v) != "null");
+            let res = nonnull.length != 0 ? nonnull[0] : null;
+            return res;
+        })
+        .add1("null", () => null)
+        .build();
 }
 
 /** Default function implementations for the expression evaluator. */
@@ -919,6 +929,7 @@ export const DEFAULT_FUNCTIONS: Record<string, FunctionImpl> = {
     reverse: DefaultFunctions.reverse,
     length: DefaultFunctions.length,
     nonnull: DefaultFunctions.nonnull,
+    firstvalue: DefaultFunctions.firstvalue,
     all: DefaultFunctions.all,
     any: DefaultFunctions.any,
     none: DefaultFunctions.none,

Diff for: src/test/function/aggregation.test.ts

@@ -83,3 +83,10 @@ describe("nonnull()", () => {
     test("empty", () => expectEvals("nonnull([])", []));
     test("[null, false]", () => expectEvals("nonnull([null, false])", [false]));
 });
+
+describe("firstvalue()", () => {
+    test("empty", () => expectEvals("firstvalue([])", null));
+    test("null", () => expectEvals("firstvalue(null)", null));
+    test("[1, 2, 3]", () => expectEvals("firstvalue([1, 2, 3])", 1));
+    test("[null, 1, 2]", () => expectEvals("firstvalue([null, 1, 2])", 1));
+});