feat(core utils): Support NodeList in ensureArray and add option enforce_array if an array-like object should converted to a real array.

Author: thet

src/core/utils.js

@@ -554,9 +554,22 @@ const jqToNode = (el) => {
     return el;
 };
 
-const ensureArray = (it) => {
+/**
+ * Always return an iterable object.
+ *
+ * @param {any} it: The object which needs to be wrapped in an array or returned as is if it is iterable.
+ * @param {boolean} force_array: If the object is iterable but not an Array, convert it to an array (e.g. For jQuery items or NodeList objects).
+ *
+ * @returns {Array}: Returns the object wrapped in an Array, expanded to an Array or as-is if it is already iterable.
+ */
+const ensureArray = (it, force_array) => {
     // Ensure to return always an array
-    return Array.isArray(it) || it.jquery ? it : [it];
+    const array_like = !!(
+        NodeList.prototype.isPrototypeOf(it) || // eslint-disable-line no-prototype-builtins
+        Array.isArray(it) ||
+        it.jquery
+    );
+    return array_like ? (force_array ? [...it] : it) : [it];
 };
 
 const localized_isodate = (date) => {

src/core/utils.test.js

@@ -642,6 +642,34 @@ describe("core.utils tests", () => {
 
             done();
         });
+
+        it("returns a array-like NodeList object as is", () => {
+            const el = document.createElement("div");
+            el.innerHTML = `
+                <div></div>
+                <div></div>
+                <div></div>
+            `;
+            const node_list = el.querySelectorAll("div");
+            const result = utils.ensureArray(node_list);
+            expect(result.length).toBe(3);
+            expect(NodeList.prototype.isPrototypeOf(result)).toBe(true); // eslint-disable-line no-prototype-builtins
+            expect(Array.isArray(result)).toBe(false);
+        });
+
+        it("returns a array from a NodeList is force_array is set", () => {
+            const el = document.createElement("div");
+            el.innerHTML = `
+                <div></div>
+                <div></div>
+                <div></div>
+            `;
+            const node_list = el.querySelectorAll("div");
+            const result = utils.ensureArray(node_list, true);
+            expect(result.length).toBe(3);
+            expect(NodeList.prototype.isPrototypeOf(result)).toBe(false); // eslint-disable-line no-prototype-builtins
+            expect(Array.isArray(result)).toBe(true);
+        });
     });
 
     describe("localized_isodate tests", () => {