reorg(all): promote array utils package

* reorg(all): promoted array-utils package

* feat(array-utils): added coalesce as well as test suite

* docs(array-utils): tweaks to docs and annotations

Author: z3dev

jsdoc.json

@@ -1,7 +1,7 @@
 {
   "source" : {
     "include": [
-      "packages/utils/array-utils/src",
+      "packages/array-utils/src",
 
       "packages/modeling/src/colors",
       "packages/modeling/src/curves",

package.json

@@ -4,6 +4,7 @@
   "description": "",
   "homepage": "https://openjscad.xyz/",
   "repository": "https://github.com/jscad/OpenJSCAD.org",
+  "type": "module",
   "scripts": {
     "docs": "jsdoc --configure jsdoc.json",
     "coverage": "lerna run --concurrency 1 --stream coverage",

packages/utils/array-utils/CHANGELOG.md packages/array-utils/CHANGELOG.mdpackages/utils/array-utils/CHANGELOG.md renamed to packages/array-utils/CHANGELOG.md

@@ -0,0 +1,3 @@
+import type { RecursiveArray } from './recursiveArray.d.ts'
+
+export function coalesce<T>(arr: RecursiveArray<T>): Array<T>

packages/utils/array-utils/README.md packages/array-utils/README.mdpackages/utils/array-utils/README.md renamed to packages/array-utils/README.md

@@ -0,0 +1,24 @@
+/**
+ * Flattens and filters out nullish values from the given list of arguments.
+ *
+ * The arguments can be composed of multiple depths of objects and arrays.
+ * The output is a single flat array with no missing values.
+ *
+ * @param {Array} arr - list of arguments
+ * @returns {Array} a flat list of arguments
+ *
+ * @alias module:modeling/utils.coalesce
+ * @function
+ */
+export const coalesce = (arr) => flattenHelper(arr, [])
+
+// Helper to recursively append to a given list.
+// This is MUCH faster than other flatten methods.
+const flattenHelper = (arr, out) => {
+  if (Array.isArray(arr)) {
+    arr.forEach((child) => flattenHelper(child, out))
+  } else if (arr != null && arr !== undefined) {
+    out.push(arr)
+  }
+  return out
+}