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

Author: z3dev

packages/array-utils/src/coalesce.d.ts

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

packages/array-utils/src/coalesce.js

@@ -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
+}

packages/array-utils/src/coalesce.test.js

@@ -0,0 +1,35 @@
+import test from 'ava'
+
+import { coalesce } from './index.js'
+
+test('array-utils: coalesce() should coalesce arrays into an array', (t) => {
+  let obs = coalesce([1, 2, 3, 4])
+  let exp = [1, 2, 3, 4]
+  t.deepEqual(obs, exp)
+
+  obs = coalesce([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+  exp = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+  t.deepEqual(obs, exp)
+})
+
+test('array-utils: coalesce() should coalesce arrays with arrays and values into an array', (t) => {
+  let obs = coalesce([[1], 2, 3, [4]])
+  let exp = [1, 2, 3, 4]
+  t.deepEqual(obs, exp)
+
+  obs = coalesce([1, [2, 3], 4])
+  exp = [1, 2, 3, 4]
+  t.deepEqual(obs, exp)
+})
+
+test('array-utils: coalesce() should coalesce heiarchy of arrays and values into an array', (t) => {
+  const obs = coalesce([[1], [2, 3, [4, 5]], 6])
+  const exp = [1, 2, 3, 4, 5, 6]
+  t.deepEqual(obs, exp)
+})
+
+test('array-utils: coalesce() should coalesce arrays with nullish values into an array', (t) => {
+  const obs = coalesce([[1], [2, null, [4, undefined]], undefined])
+  const exp = [1, 2, 4]
+  t.deepEqual(obs, exp)
+})

packages/array-utils/src/index.js

@@ -1,10 +1,13 @@
 /**
  * JSCAD Utility functions for arrays.
+ *
  * @module array-utils
+ *
  * @example
- * const { flatten, head } = require('@jscad/array-utils')
+ * import { flatten, head } from '@jscad/array-utils'
  */
 
+export { coalesce } from './coalesce.js'
 export { flatten } from './flatten.js'
 export { fnNumberSort } from './fnNumberSort.js'
 export { head } from './head.js'