feat: Add array length function, closes #3308

docs/4_secondary_admin_controls/expressions/functions.md

@@ -2,6 +2,16 @@ There are various supported functions, and we are willing to add more. Let us kn
 
 The currently supported functions are:
 
+##### General operations
+
+**length(val)**
+
+Find the length of the item passed in.
+* For a strings it will return the number of unicode graphemes
+* For arrays, the number of elements
+* For JSON or other objects, it will return the number of properties
+* For numbers it will return the length of the string representation
+
 ##### Numeric operations
 
 **round(val)**
@@ -110,7 +120,6 @@ Find the index of the first occurrence of a value within the provided string.
 
 Optionally provide an offset to start the search from.
 
-
 **lastIndexOf(val, find, offset)**
 
 Find the index of the last occurrence of a value within the provided string.
@@ -141,7 +150,6 @@ eg `encode("Companion","hex")` gives `"436f6d70616e696f6e"`
 
 Decode a string from the requested format ('hex','base64'). If `enc` is missing, `latin1` will be used.
 
-
 eg `decode("436f6d70616e696f6e","hex")` gives `"Companion"`
 
 **parseVariables(string)**
@@ -204,7 +212,6 @@ eg `00:10:15` gives 615
 
 You can do the reverse of this with `secondsToTimestamp(str)`
 
-
 **secondsToTimestamp(seconds, format)**
 
 Convert a number of seconds into a timestamp of format 'HH:mm:ss'.

shared-lib/lib/Expression/ExpressionFunctions.ts

@@ -1,8 +1,34 @@
 import { pad } from '../Util.js'
 import { JSONPath } from 'jsonpath-plus'
+import { countGraphemes } from 'unicode-segmenter/grapheme';
 
 // Note: when adding new functions, make sure to update the docs!
 export const ExpressionFunctions: Record<string, (...args: any[]) => any> = {
+	// General operations
+	length: (v) => {
+		let len = 0
+		if (v === undefined || v === null) {
+			len = 0
+		} else if (Array.isArray(v)) {
+			len = v.length
+		} else if (typeof v === 'number') {
+			len = (v + '').length
+		} else if (typeof v === 'bigint') {
+			len = v.toString().length
+		} else if (typeof v === 'string') {
+			// So we handle UTF graphemes correctly
+			len = countGraphemes(v)
+		} else if (v instanceof RegExp) {
+			len = v.toString().length
+		} else if (typeof v === 'object') {
+			len = Object.keys(v).length
+		} else {
+			// If it's got to here, we don't know how to handle it
+			len = NaN
+		}
+		return len
+	},
+
 	// Number operations
 	// TODO: round to fractionals, without fp issues
 	round: (v) => Math.round(v),
@@ -74,7 +100,7 @@ export const ExpressionFunctions: Record<string, (...args: any[]) => any> = {
 	// Bool operations
 	bool: (v) => !!v && v !== 'false' && v !== '0',
 
-	// Object operations
+	// Object/array operations
 	jsonpath: (obj, path) => {
 		const shouldParseInput = typeof obj === 'string'
 		if (shouldParseInput) {

shared-lib/package.json

@@ -20,7 +20,8 @@
     "jsep": "^1.4.0",
     "jsonpath-plus": "^10.3.0",
     "ps-tree": "^1.2.0",
-    "semver": "^7.7.1"
+    "semver": "^7.7.1",
+    "unicode-segmenter": "^0.11.3"
   },
   "scripts": {
     "build": "run build:ts",

shared-lib/test/expressions-functions.test.ts

@@ -2,6 +2,38 @@
 import { ExpressionFunctions } from '../lib/Expression/ExpressionFunctions.js'
 
 describe('functions', () => {
+	describe('general', () => {
+		it('length', () => {
+			expect(ExpressionFunctions.length()).toBe(0)
+			expect(ExpressionFunctions.length('')).toBe(0)
+			expect(ExpressionFunctions.length('a')).toBe(1)
+			expect(ExpressionFunctions.length('abc')).toBe(3)
+			expect(ExpressionFunctions.length('ä')).toBe(1) // codepoint U+00E4, one grapheme
+			expect(ExpressionFunctions.length('̈a')).toBe(1) // codepoints U+0308 U+0061, one grapheme
+			expect(ExpressionFunctions.length('́̈a')).toBe(1) // codepoints U+0301 U+0308 U+0061, one grapheme
+			expect(ExpressionFunctions.length(9)).toBe(1)
+			expect(ExpressionFunctions.length(99)).toBe(2)
+			expect(ExpressionFunctions.length(-123)).toBe(4)
+			expect(ExpressionFunctions.length(3.14)).toBe(4)
+			expect(ExpressionFunctions.length(BigInt(1024))).toBe(4)
+			expect(ExpressionFunctions.length(BigInt(9007199254740991))).toBe(16)
+			expect(ExpressionFunctions.length(new RegExp('ab+c', 'i'))).toBe(7)
+			expect(ExpressionFunctions.length([])).toBe(0)
+			expect(ExpressionFunctions.length([9])).toBe(1)
+			expect(ExpressionFunctions.length([99])).toBe(1)
+			expect(ExpressionFunctions.length(['abc'])).toBe(1)
+			expect(ExpressionFunctions.length([9, 'a'])).toBe(2)
+			expect(ExpressionFunctions.length(['a', 'c'])).toBe(2)
+			expect(ExpressionFunctions.length(['ab', ''])).toBe(2)
+			expect(ExpressionFunctions.length([1, , 3])).toBe(3)
+			expect(ExpressionFunctions.length(['a', 'b', 'c'])).toBe(3)
+			expect(ExpressionFunctions.length(['a', ['b', 'b'], 'c'])).toBe(3)
+			expect(ExpressionFunctions.length({ a: 1 })).toBe(1)
+			expect(ExpressionFunctions.length({ a: 1, b: { c: 5 } })).toBe(2)
+			expect(ExpressionFunctions.length({ a: ['a', 'c'], b: { c: 5 } })).toBe(2)
+		})
+	})
+
 	describe('number', () => {
 		it('round', () => {
 			expect(ExpressionFunctions.round(9.99)).toBe(10)

yarn.lock

@@ -1244,6 +1244,7 @@ __metadata:
     ps-tree: "npm:^1.2.0"
     semver: "npm:^7.7.1"
     typescript: "npm:~5.7.3"
+    unicode-segmenter: "npm:^0.11.3"
   languageName: unknown
   linkType: soft
 
@@ -16052,6 +16053,13 @@ asn1@evs-broadcast/node-asn1:
   languageName: node
   linkType: hard
 
+"unicode-segmenter@npm:^0.11.3":
+  version: 0.11.3
+  resolution: "unicode-segmenter@npm:0.11.3"
+  checksum: 10c0/e5f6c16ebd2112eb6e447436ebaa525deb69705a609e6e19161c779ae738f1c2325b96cd986d5099c0f9b8c92538940d41d77237dd5a169230bb8405ec5f4835
+  languageName: node
+  linkType: hard
+
 "unified@npm:^11.0.0":
   version: 11.0.5
   resolution: "unified@npm:11.0.5"