fix(zeebe): throw on client if array passed as variables to CompleteJob

fixes #247

src/__tests__/zeebe/stringifyVariables.unit.spec.ts

@@ -50,6 +50,12 @@ test('stringifyVariables stringifies the variables key of a job object', () => {
 	expect(stringified.variables).toBe(expectedStringifiedVariables)
 })
 
+test('stringifyVariables throws an error when passed an array', () => {
+	const arrayInput = { variables: ['something'] }
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	expect(() => stringifyVariables(arrayInput as any)).toThrow(Error)
+})
+
 test('parseVariables returns a new object', () => {
 	expect(parseVariables(jobDictionary)).not.toEqual(jobDictionary)
 })

src/zeebe/lib/stringifyVariables.ts

@@ -11,11 +11,14 @@ export function parseVariables<T extends { variables: string }, V = JSONDoc>(
 	})
 }
 
+/**
+ * Parse an incoming job and convert its variables and custom headers to JSON.
+ */
+
 export function parseVariablesAndCustomHeadersToJSON<Variables, CustomHeaders>(
 	response: ActivatedJob,
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	/* eslint-disable @typescript-eslint/no-explicit-any */
 	inputVariableDto: new (...args: any[]) => Readonly<Variables>,
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	customHeadersDto: new (...args: any[]) => Readonly<CustomHeaders>
 ): Promise<Job<Variables, CustomHeaders>> {
 	return new Promise((resolve, reject) => {
@@ -40,12 +43,25 @@ export function parseVariablesAndCustomHeadersToJSON<Variables, CustomHeaders>(
 	})
 }
 
+/**
+ * Turn the `variables` field of a request from a JS object to a JSON string
+ * This should be a key:value object where the keys will be variable names in Zeebe and the values are the corresponding values.
+ * This function is used when sending a job back to Zeebe.
+ */
 export function stringifyVariables<
 	K,
 	T extends { variables: K extends JSONDoc ? K : K },
 	V extends T & { variables: string },
 >(request: T): V {
 	const variables = request.variables || {}
+	/**
+	 * This is a run-time guard. The type system disallows passing an array, but type erasure and dynamic programming can override that.
+	 * If you pass an array as the variables to a CompleteJob RPC call, it will report success, but fail on the broker, stalling the process.
+	 * See: https://github.com/camunda/camunda-8-js-sdk/issues/247
+	 */
+	if (Array.isArray(variables)) {
+		throw new Error('Unable to parse Array into variables')
+	}
 	const variablesString = losslessStringify(variables)
 	return Object.assign({}, request, { variables: variablesString }) as V
 }